---
title: "Plan Mode"
description: "先看后做的安全机制。Plan Mode 让 AI 在探索阶段只能读不能写，形成方案后再提交用户审批。理解权限收窄、Prompt-based 权限和计划持久化的设计。"
keywords: ["Plan Mode", "计划模式", "先规划再执行", "安全工作流"]
---

## 核心问题

你说"重构这个模块"，AI 立刻开始改代码——但你还没搞清楚它打算怎么改。等改了一半发现方向不对，已经来不及了。

## 解决方案：先看后做

Plan Mode 给对话加了一个"只读阶段"：

<Steps>
  <Step title="进入计划模式">
    AI 判断任务需要规划，请求进入 Plan Mode。需要**用户审批**。
  </Step>
  <Step title="探索阶段">
    AI 只能使用只读工具（Read、Grep、Glob）。写操作被自动拒绝。
  </Step>
  <Step title="提交方案审批">
    AI 完成探索后，将计划文件提交给用户审阅。这是第二个**需要审批**的节点。
  </Step>
  <Step title="恢复执行">
    用户批准后，权限恢复，AI 按计划执行。
  </Step>
</Steps>

**两个审批节点的设计**：进入时审批（"我可以探索吗？"）和退出时审批（"这个方案可以吗？"）。两次审批确保用户对过程和结果都有控制权。

## 权限的自动收窄与恢复

### 进入：只读锁定

权限模式切换为 `plan`，所有工具的 `isReadOnly()` 检查成为唯一准入条件。不是"某些工具被禁用"，而是"只有标记为只读的工具才能执行"。

**设计考量**：基于属性而非名单的权限控制更安全。如果新增了一个工具但忘记把它加入"plan 模式禁用名单"，基于名单的系统会漏过它；但基于 `isReadOnly()` 的系统不会——新工具必须显式声明自己只读才能在 Plan Mode 中使用。

### 退出：Prompt-based 权限

AI 可以在计划中声明它需要执行的命令类别。用户批准计划后，这些命令自动放行。

**设计洞察**：这是 Plan Mode 最精妙的设计。传统做法是：计划完成后，AI 每执行一步都要用户确认。Prompt-based 权限让用户在审批计划时"一揽子"授权了后续操作——既减少了打断，又保持了控制。

当然，AI 只能获得计划中声明的权限。如果计划说"运行测试"，AI 不能突然执行 `rm -rf /`。

## 计划文件：可编辑的方案

计划内容被写入磁盘文件，用户可以在审批前修改 AI 的方案。

**为什么不直接在对话中展示计划**？
1. 对话中的计划是"只读"的，用户无法直接修改
2. 磁盘文件可以被用户用任何编辑器修改
3. 修改后的计划成为 AI 执行的"合约"——AI 必须执行用户修改后的版本

## 什么时候该用 Plan Mode

| 场景 | 应该用吗 | 原因 |
|------|:--------:|------|
| 修复 typo | 跳过 | 改动明确，无需规划 |
| 添加删除按钮 | 通常跳过 | 路径明确 |
| 重构认证系统 | **使用** | 高影响，需要理解全局 |
| 架构决策（Redis vs 内存缓存） | **使用** | 需要权衡多种方案 |
| 用户说"开始做 X" | 通常跳过 | 用户已明确意图 |

**设计哲学**：Plan Mode 是工具而非默认行为。AI 应该在"不确定性高"时使用它，而不是在每次修改时都进入。过度使用 Plan Mode 会降低效率，如同人类在每次改代码前都写设计文档一样低效。

## 与任务系统的配合

Plan Mode 通常与任务系统配合：
1. AI 在探索阶段创建任务列表
2. 用户审批计划（包含任务列表）
3. 退出 Plan Mode 后，AI 按任务列表逐项执行

这把"理解"和"执行"在时间上分开了——先花时间理解问题，再高效执行方案。

## 接下来

- **权限模型** — 理解支撑 Plan Mode 的完整权限体系
- **任务管理** — 理解 Plan Mode 中创建的任务追踪
- **子 Agent** — 理解 Plan Mode 中使用的 Explore Agent