Plan mode、Checkpoint、Headless

Plan mode（计划模式 🔬，Gemini CLI 当前为实验功能）、checkpoint（检查点）、headless mode（无头 / 脚本模式）分别解决三个问题：先想清楚、改坏能回退、自动化能调用。

Plan mode

Plan mode 适合复杂任务。它让 agent 先产出计划，再进入执行。

适合：

• 多文件改动。
• 需要理解架构。
• 要接外部系统。
• 有并发修改。
• 涉及发布、部署、迁移。

一个好计划应该包含：

• 目标。
• 文件范围。
• 分阶段动作。
• 验证命令。
• 风险和停止条件。

Checkpoint

Checkpoint 解决“改了一半发现方向错了”的问题。它让你在关键节点保留回退点。

建议在这些节点建 checkpoint：

• 大改前。
• 自动化生成文件前。
• 跑迁移脚本前。
• 进入不熟悉代码路径前。
• 批量替换前。

Headless mode

Headless mode 适合脚本和 CI：

git diff | gemini -p "Summarize this change"
gemini --output-format json -p "Classify this issue"

它适合“一次输入、一次输出”的任务，不适合需要复杂交互确认的高风险任务。

三者怎么组合

人工复杂任务    Plan mode -> 分批执行 -> checkpoint -> 验证
批量低风险任务  headless -> JSON 输出 -> 脚本校验 -> 人工抽查
高风险任务      Plan mode -> 人工确认 -> checkpoint -> 最小写入 -> 验证

实用原则

如果任务可能产生不可逆影响，就不要 headless 自动跑。先让 Gemini CLI 输出计划和风险，再由人决定是否执行。

典型错误

• 把 Plan mode 当成“慢一点的聊天”，但没有要求影响文件、验证命令和停止条件。
• 把 checkpoint 当成 git 分支，结果长期修改没有 commit 记录。
• 把 headless 用在需要多轮确认的任务，例如批量删除、发布、部署。
• 让 headless 直接写正式文件，没有临时文件、JSON 校验和失败分支。

一个可靠流程

复杂改动先进入 Plan mode，只读扫描代码和配置。用户确认后，只执行第一小步，并在关键改动前建立 checkpoint。每一步跑最小验证，失败就停下来回到计划，而不是继续扩大修改。

自动化场景则相反：prompt 固定、输入可控、输出结构化。headless 更适合分类、摘要、生成草稿，不适合让模型在 CI 里自主修复生产问题。

验收标准

人工任务看四项：是否有计划，是否有回退点，是否有验证命令，是否有人确认高风险动作。脚本任务看四项：退出码、JSON 解析、空输出处理、配额失败处理。

最小落地模板

可以把复杂任务拆成三句话：

先只读分析并给计划，不要改文件。
我确认计划后，只执行第一批文件，并在改前说明验证方式。
每批结束后输出 diff 范围、检查结果和下一批是否继续。

这不是模板化提示词，而是控制权设计：先让 Gemini CLI 暴露计划，再让它小步执行，最后用验证结果决定是否继续。

何时不用

简单单文件解释不需要 Plan mode；已经有清晰 Git 分支和小 diff 时，checkpoint 不是必须；需要人工多轮确认的任务不要 headless。控制手段要匹配风险，过度上工具会增加排障成本。

商业教程里要写出“什么时候不用”，否则读者会把所有功能都叠上，反而不知道问题出在哪里。

组合示例

真实任务可以这样组合：先 Plan mode 只读产出方案；用户批准后做第一批小改；改前建 checkpoint；改后跑最小验证；需要批量重复时，再把稳定部分改成 headless 脚本。顺序反过来就容易失控。

最重要的是每一步都能停。不能停的自动化，不适合处理真实项目。

不可逆动作不要交给 headless 自主执行，包括删除远端资源、发布正式版本、改生产配置和写入账号后台。即使输出是 JSON，也不代表这个动作已经可自动批准。

Checkpoint、Plan 和 headless 都是控制权工具。它们的价值不是显得专业，而是让人知道什么时候批准、什么时候回退、什么时候停止。

官方资料

• Plan mode 🔬：docs/cli/plan-mode.md
• Checkpointing：docs/cli/checkpointing.md
• Headless mode：docs/cli/headless.md
• Rewind（回放）：docs/cli/rewind.md

下一篇