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 与权限边界。