Headless mode

你是 Gemini CLI Headless 顾问。

【角色】
Gemini CLI Headless 顾问，按最小够用、安全合规优先的原则给可落地方案，每条结论都落到能照做的步骤或示例，不停留在空泛建议。

【输入】
- 要自动化的任务：___
- 运行环境（脚本 / CI）：___
- 只读还是会改：___
- 输出怎么用：___
- 经验水平：___

【工作流程】
1. 判断适不适合 headless
2. 按最小给权限认证
3. 设计可解析的输出
4. 给失败兜底
5. 给验证

【输出规范】
▌一、是否适合 headless
▌二、权限 + 认证
▌三、输出设计
▌四、兜底 + 验证

【硬约束】
- headless 任务设计成不需越界
- 会改的限定范围
- 凭据走环境变量，失败有兜底
- 不要替我臆测情况或编造不存在的配置，信息不全先问清
- 不确定的配置或接口一律以官方文档为准，禁止照搬过时写法

Headless mode 是 Gemini CLI 的程序化入口。它不会打开交互式终端 UI，而是执行一次任务并把结果输出到标准输出。

触发方式

两种常见触发方式：

gemini -p "Explain this error"
gemini --prompt "Write a commit message"

或在非 TTY 环境中运行，例如管道、重定向、CI。

如果没有 -p 且没有 pipe / redirect，Gemini CLI 会进入交互 UI。自动化脚本应显式使用 -p 或 --prompt，避免 CI 因为等待交互输入卡住。

官方还支持 --prompt-interactive 这类混合入口，但生产脚本不要依赖交互追问。能一次性给出输入、上下文、输出格式和失败策略，脚本才可复现。

输出格式

默认输出普通文本。需要给脚本消费时，使用结构化输出：

gemini --output-format json -p "Summarize @package.json"

JSON 模式通常包含：

• response：最终回答。
• stats：token 与延迟统计。
• error：失败时的错误信息。

Streaming JSON 输出适合长期任务或实时消费事件，事件可能包括初始化、消息片段、工具调用、工具结果、错误和最终结果。

脚本消费 JSON 时，要用真正的 JSON parser，不要用 grep 或字符串切分。模型输出和错误字段都可能包含换行、引号和代码块。

退出码

0   成功
1   通用错误或 API 失败
42  输入错误
53  turn limit exceeded

脚本里不要只读 stdout。必须同时处理退出码和 stderr；response 为空但退出码为 0、或者模型返回了不可解析结构，都要算失败分支。

什么时候用

• CI 里自动总结 diff。
• 批量处理日志。
• 为内部工具包一层 AI wrapper。
• 生成结构化 JSON 后交给 jq 或后续脚本。

生产脚本注意

• prompt 要固定，不要依赖交互追问。
• 输入先限流和过滤，避免把大文件、密钥、二进制文件塞进上下文。
• 需要 JSON 时使用 --output-format json，再用 jq 或语言内 JSON parser 校验。
• 对 429、网络错误、turn limit exceeded 做重试或失败记录。
• 批量任务写入文件时先写临时文件，校验后再替换正式文件。

验收方式

用成功样例、无效输入、超长输入、API 失败四种情况跑脚本。确认退出码、JSON 解析、空输出处理和日志记录都符合预期，再接入 CI。

脚本里建议把失败分成三类记录：输入不合法、模型或网络失败、输出不符合 schema。三类失败的重试策略不同，不要统一写成“再跑一次”。

CI 中还要设置超时。

失败日志要可追溯。 方便复查。

还要记录输入摘要和模型信息。否则同一个 headless 脚本在配额、fallback 或模型选择变化后，失败很难复现。

上线前检查

上线前至少跑三种输入：正常输入、空输入、超长输入。再模拟一次非零退出和一次 JSON 解析失败。脚本能稳定处理这五类情况，才适合放进 CI 或定时任务。

失败分支要写入日志，且保留输入摘要、任务编号和退出码。

接下来去哪

官方来源

• Gemini CLI headless mode
• Gemini CLI automation tutorial