---
title: "Plan mode"
description: "Gemini CLI plan mode 的用途：只读规划、复杂修改前方案设计、降低误改风险，以及和 approval mode 的关系。"
verifiedAt: "2026-05-09"
---

Plan mode 是复杂任务前最应该优先用的模式。官方 CLI cheatsheet 把 `--approval-mode=plan` 列为 approval mode 之一，官方 docs 也有 Plan mode 相关页面。

> [!IMPORTANT]
> **先 plan，再 edit**：跨文件重构、依赖升级、架构调整、数据迁移、生产相关任务，都应该先让 Gemini CLI 进入规划阶段。

## 怎么启动

```bash
gemini --approval-mode=plan
```

也可以在普通会话里明确要求：

```text
先不要修改文件。只读分析，给我计划、风险、影响文件和验证命令。
```

## 适合场景

- 你还不清楚影响范围。
- 任务需要跨多个文件。
- 修改可能破坏构建或数据。
- 涉及权限、安全、发布、账单。
- 你要先审核方案。

典型例子：

| 任务 | 是否先 Plan | 原因 |
| --- | --- | --- |
| 升级框架主版本 | 是 | 影响依赖、构建、路由和测试 |
| 调整认证流程 | 是 | 涉及安全、会话、权限边界 |
| 批量改文档格式 | 是 | 文件多，容易误改目录或 frontmatter |
| 查一个 CLI 参数 | 否 | 只读查询，不需要规划阶段 |
| 修一个错别字 | 否 | 直接小改更合适 |

## 不适合场景

- 只查一个命令。
- 只解释一个文件。
- 改一个明显拼写错误。
- 已经有明确 diff 的小修。

## 一个好计划应该包含什么

```text
目标
影响文件
不修改边界
执行顺序
验证命令
失败恢复
需要用户确认的动作
```

还应该明确“第一步只做什么”。Plan mode 的目的不是一次性把所有事情想完，而是把执行权拆小，让你能在每个风险节点做判断。

```mermaid
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 输出，应该让人能直接判断：这一步会改哪里、为什么现在改、失败后停在哪里。

## 接下来去哪

<Cards>
  <Card title="上下文与配置" description="CLI 工作流读完后，继续把规则、权限、模型和上下文沉淀到配置层。" href="/docs/gemini-cli/official/02-context-config" />
  <Card title="Todos / Planning 工具" description="继续看工具层面的 todos、plans 目录和 planning 行为。" href="/docs/gemini-cli/official/03-tools-mcp/34-todos-planning-tools" />
  <Card title="Sandbox" description="如果准备让 Gemini CLI 执行命令或写文件，继续看 sandbox 与权限边界。" href="/docs/gemini-cli/official/06-security-enterprise/60-sandbox" />
</Cards>

## 官方来源

- [Gemini CLI plan mode](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/plan-mode.md)
- [Plan mode steering tutorial](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/tutorials/plan-mode-steering.md)
- [Gemini CLI planning tools](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/planning.md)
