EN

Plan Mode

Plan Mode(规划模式)是 Deep Code 内置的一种协作模式。在 Plan Mode 下,AI 助手会与你共同制定详细的实施方案,但不会执行任何会修改代码的操作。先规划、再实现,让复杂任务的每一步都有据可查。

为什么需要 Plan Mode

直接让 AI 改代码适合简单任务,但面对复杂的跨文件重构、新功能开发或架构调整时,常见的问题是:

  • AI 在缺乏全貌的情况下就开始改代码,导致方向偏离
  • 缺少共识就动手,后续来回修正成本高
  • 修改与规划混在一起,难以追溯决策依据

Plan Mode 把"想清楚"和"动手做"拆成两个阶段,先在规划阶段充分探索、提问、达成共识,形成一份决策完备的方案再进入实现。

启用 Plan Mode

有两种方式可以进入 Plan Mode:

方式操作
快捷键在输入框中按 Shift+Tab,可随时在 Plan Mode 和 Default Mode 之间切换
斜杠命令输入 /plan,或输入 / 打开命令菜单后选择 /plan

进入 Plan Mode 后,输入框右上角会显示黄色 💡 Plan mode 提示,表明当前处于规划模式。

退出 Plan Mode 同样使用 Shift+Tab 切换,或在输出方案后选择 "switch to Default mode"。

Plan Mode 下的行为

AI 的三个规划阶段

进入 Plan Mode 后,AI 助手会遵循一个三阶段的协作流程:

  1. 环境摸底(Phase 1):先通过阅读文件、搜索代码、检查配置等方式理解项目现状,尽可能通过探索消除不确定性,而不是直接提问。
  2. 意图对齐(Phase 2):围绕你的目标和偏好提问,明确成功标准、范围边界、约束条件和关键取舍。
  3. 方案推敲(Phase 3):在意图稳定后,讨论具体实现路径,包括接口设计、数据流、边界情况、测试策略等,直到方案"决策完备"。

在每个阶段,AI 都会通过 AskUserQuestion 工具与你交互,提供具体的选项供你选择。

严格限制:禁止修改操作

Plan Mode 的核心规则是只规划,不动手。例如以下操作是被允许的:

  • 读取和搜索文件、配置、类型定义、文档
  • 静态分析和代码探索
  • 运行不影响仓库追踪文件的干运行命令(如 --dry-run)
  • 运行测试、构建等可能写入缓存或构建产物(如 target/、.cache/)但不修改仓库追踪文件的命令

以下操作则不被允许:

  • 编辑或写入文件
  • 运行会修改文件的格式化或 lint 工具
  • 应用补丁、迁移或代码生成
  • 其他目的为实现方案而非完善方案的副作用操作

权限强制限制

即使在 settings.json 中配置了对写入、删除等操作自动放行,Plan Mode 也会强制将这些权限升级为"询问"(ask)。具体来说,以下权限范围在 Plan Mode 下首次使用时需要确认:

权限范围说明
write-in-cwd在工作区内创建或覆写文件
write-out-cwd在工作区外创建或覆写文件
delete-in-cwd删除工作区内的文件
delete-out-cwd删除工作区外的文件
mutate-git-log修改 Git 历史

这一设计确保即使权限配置较为宽松,Plan Mode 也不会在你确认前修改你的代码。

输出方案

当 AI 认为方案已经决策完备,它就会在回复一个 <proposed_plan> 块:

<proposed_plan>
方案内容(使用 Markdown 格式)
</proposed_plan>

方案通常包含以下部分:

  • 标题:方案名称
  • Summary:简要概述
  • Key Changes / Implementation Changes:关键变更,以行为描述为主(而非文件清单)
  • Test Plan:测试用例和场景
  • Assumptions:做出的假设和选择的默认方案

方案输出后,你不需要输入任何额外内容,Deep Code 会自动弹出选择界面:

选项作用
1. implement this plan退出 Plan Mode,自动发送实现指令,让 AI 开始按方案写代码
2. clear context and implement保留当前会话,创建一个仅携带已确认方案的新会话,并在 Default mode 下开始实现
3. stay in Plan mode保持在 Plan Mode,继续修改或完善方案
4. switch to Default mode退出 Plan Mode,回到默认模式(不自动开始实现)

你可以用数字键 1-4 直接选择,也可以用 ↑/↓ 移动光标后按 Enter 确认。按 Esc 等同于选择 "stay in Plan mode"。选择清除上下文后,原 Plan 会话仍可通过 /resume 恢复。新会话不会继承旧对话消息。

Plan Mode 与 UpdatePlan 工具的区别

Plan Mode 是一种对话协作模式,最终产物是 <proposed_plan> 块中的完整方案。

UpdatePlan 是 Deep Code 的任务进度清单工具(对应 UpdatePlan 工具),用于在执行过程中展示步骤进度。它不会进入或退出 Plan Mode,也不是最终规划产物。

两者可以配合使用:在实现阶段,AI 可能会使用 UpdatePlan 来跟踪复杂任务的执行进度,但方案本身已在 Plan Mode 中确定。

典型使用场景

1. 新功能开发

给用户列表加上分页和搜索功能。

在 Plan Mode 下,AI 会先了解现有代码结构、路由、数据模型,然后与你讨论分页方式(游标还是偏移)、搜索范围、API 变更等问题,最后输出一份完整方案。

2. 代码重构

把 UserService 中混杂的业务逻辑拆分到独立的 service 中。

AI 会先分析 UserService 的依赖关系和调用方,给出拆分方案、迁移步骤和兼容性考虑。

3. 架构评审

分析当前项目的认证流程,给出安全改进建议。

AI 会遍历认证相关代码,识别潜在风险,并以方案形式给出具体的改进步骤。