mirror of
https://github.com/claude-code-best/claude-code.git
synced 2026-06-17 13:55:50 +00:00
f5c4ab333d
移除 TypeScript 代码和源码路径， 聚焦两个审批节点的设计、基于属性而非名单的权限控制、 Prompt-based 权限的一揽子授权和计划文件可编辑的合约设计。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
83 lines
3.9 KiB
Plaintext
83 lines
3.9 KiB
Plaintext
---
|
||
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
|