Plan mode
Gemini CLI plan mode 的用途：只讀規劃、複雜修改前方案設計、降低誤改風險，以及和 approval mode 的關係。
Plan mode 是複雜任務前最應該優先用的模式。官方 CLI cheatsheet 把 --approval-mode=plan 列為 approval mode 之一，官方 docs 也有 Plan mode 相關頁面。
先 plan，再 edit：跨檔案重構、依賴升級、架構調整、資料遷移、生產相關任務，都應該先讓 Gemini CLI 進入規劃階段。
怎麼啟動
gemini --approval-mode=plan也可以在普通會話裡明確要求：
先不要修改文件。只读分析，给我计划、风险、影响文件和验证命令。適合場景
- 你還不清楚影響範圍。
- 任務需要跨多個檔案。
- 修改可能破壞構建或資料。
- 涉及許可權、安全、釋出、賬單。
- 你要先稽核方案。
典型例子：
| 任務 | 是否先 Plan | 原因 |
|---|---|---|
| 升級框架主版本 | 是 | 影響依賴、構建、路由和測試 |
| 調整認證流程 | 是 | 涉及安全、會話、許可權邊界 |
| 批次改文件格式 | 是 | 檔案多，容易誤改目錄或 frontmatter |
| 查一個 CLI 引數 | 否 | 只讀查詢，不需要規劃階段 |
| 修一個錯別字 | 否 | 直接小改更合適 |
不適合場景
- 只查一個命令。
- 只解釋一個檔案。
- 改一個明顯拼寫錯誤。
- 已經有明確 diff 的小修。
一個好計劃應該包含什麼
目标
影响文件
不修改边界
执行顺序
验证命令
失败恢复
需要用户确认的动作還應該明確“第一步只做什麼”。Plan mode 的目的不是一次性把所有事情想完，而是把執行權拆小，讓你能在每個風險節點做判斷。
flowchart TD
Read["只讀掃描"] --> Scope["確認影響範圍"]
Scope --> Plan["輸出計劃"]
Plan --> Review{"使用者批准?"}
Review -->|否| Revise["修改計劃"]
Review -->|是| FirstStep["只執行第一小步"]
FirstStep --> Verify["跑最小驗證"]
Verify --> Next["繼續或停止"]
Revise --> Plan
style Read fill:#dbeafe,stroke:#3b82f6
style Review fill:#fef3c7,stroke:#f59e0b
style Verify fill:#dcfce7,stroke:#22c55e退出 Plan mode 的判斷
只有當方案足夠具體、使用者已經理解風險、驗證命令明確時，才進入執行。計劃還停留在“最佳化專案、修復問題、整理程式碼”這種層級，就不該退出 Plan mode。
如果計劃需要寫入檔案，官方 planning tools 會要求 plan 檔案在允許的 plans 目錄中，並在退出時呈現給使用者稽核。被拒絕時應留在 Plan mode，根據反饋改計劃，而不是繞過審批開始改檔案。
和 approval mode 的關係
Plan mode 不等於“永遠不執行”。它更像執行前的只讀階段：先探索、列方案、暴露風險，等使用者批准後再進入寫入。其他 approval mode 關注工具呼叫是否需要確認，Plan mode 關注在確認之前是否已經把事情想清楚。
| 模式關注點 | 主要問題 | 審查重點 |
|---|---|---|
| Plan mode | 現在能不能開始改 | 方案、影響檔案、風險、驗證 |
| Approval mode | 工具呼叫要不要批准 | 寫檔案、跑命令、訪問網路、許可權 |
| Sandbox | 命令和檔案系統能碰哪裡 | 目錄邊界、外部副作用 |
| Checkpoint | 改壞後能不能回退 | 恢復點、diff、測試結果 |
複雜任務裡，這幾層最好一起用：Plan mode 先收斂方案，approval mode 控制每次工具呼叫，sandbox 限制可觸達範圍，checkpoint 降低單次誤改成本。
驗收方式
用一個跨檔案任務測試 Plan mode：確認它只讀探索、不會直接編輯；方案裡列出影響檔案、執行順序、驗證命令和回復策略；批准前不會動檔案。這個行為穩定後，再把 Plan mode 寫進團隊工作流。
常見錯誤
- 計劃寫得很大，但沒有第一步。
- 計劃只列目標，不列檔案。
- 計劃沒有驗證命令。
- 使用者還沒確認，就開始編輯。
- 計劃被拒絕後，繞開 Plan mode 直接執行。
一個可用的 Plan mode 輸出，應該讓人能直接判斷：這一步會改哪裡、為什麼現在改、失敗後停在哪裡。
接下來去哪
上下文與配置
CLI 工作流讀完後，繼續把規則、許可權、模型和上下文沉澱到配置層。
Todos / Planning 工具
繼續看工具層面的 todos、plans 目錄和 planning 行為。
Sandbox
如果準備讓 Gemini CLI 執行命令或寫檔案，繼續看 sandbox 與許可權邊界。