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

下一篇