第 8 章 · M8 Plan Mode 先计划后执行
第 8 章 · M8 Plan Mode 先计划后执行
- 8.1 M8 功能说明:先出计划,确认后再改
- 8.2 M8 总体架构:包结构与组件协作
- 8.3 PlanModeState + PlanModeHook + PlanModeStage
- 8.4 进入 Plan Mode:plan 命令与 EnterPlanMode 工具
- 8.5 退出 Plan Mode:ExitPlanMode 工具
8.1 M8 功能说明:先出计划,确认后再改
本篇涉及到的源码列表:
com.minicc.plan.PlanModeState.java
com.minicc.plan.PlanModeHook.java
com.minicc.context.PlanModeStage.java
com.minicc.tool.builtin.EnterPlanModeTool.java
com.minicc.tool.builtin.ExitPlanModeTool.java
com.minicc.cli.command.PlanCommand.java
到 M7 为止,我们这个 Agent 已经能读代码、能改代码、能做权限审批、能持久化会话、能跨会话记忆、能处理较长的上下文、还能按需加载技能。
但它有一个一直没解决的问题:它拿到需求就立刻开始修改代码。
对那种只修改一两行的小任务,这样处理是合适的。可一旦任务风险大、步骤多,用户往往希望先看一份思路,再决定要不要执行。
从这一章开始,我们进入第八个里程碑 M8,给 Agent 补上这项能力,也就是 Plan Mode(先计划后执行)。
我们先说清楚 Plan Mode 要解决什么
我们在用一个编程 Agent 做大改动的时候,如果大模型理解偏了,等我们发现方向不对,改动已经分散到多个文件,回退的成本就很高。
Plan Mode 采用另一种做法:开始修改之前,Agent 先把计划完整地呈现给我们。
进入这个模式之后,它只做调研,只产出一份计划,不修改任何文件。等我们确认计划没问题,它才切换到执行,真正开始修改。
这就是「架构模式」里常说的 Plan-and-Execute,也就是把「规划」和「执行」这两件事分开。
进入 Plan Mode 有两条路径
我们给进入 Plan Mode 设计了两条路径,覆盖两种不同的场景。
第一条是用户主动进入。你随时可以输入 /plan,把当前会话切换到计划态。
第二条是模型主动提议。模型遇到一个「非简单的实现任务」时,会自己判断「这个任务应该先规划」,主动调用 EnterPlanMode 工具提议进入。
模型提议的时候,harness 会弹出一张「是否进入 Plan Mode」的确认框,是否进入由你来决定。
两条路径最后都把会话切换到同一个计划态,区别只在于「谁发起、要不要弹框」。
退出只有一条路径
进入有两条路径,退出只有一条:模型调研完、计划写好了,调用 ExitPlanMode 请求你批准。
这时 harness 会弹出一张确认卡片,上面有两个选项:接受计划并开始执行,或者不执行、让它继续完善计划。
你选「接受」,它就退出计划态、开始执行;你选「继续完善」,它就留在计划态,根据你的反馈再调研、再给一版计划。
还有一个产品上的约定我们要先说清楚:计划只显示在终端、留在会话上下文里,不会写成磁盘上的 markdown 文件。
命令行里是什么样的
我们用三个场景,把 M8 的能力看一下。符号沿用前几章:行首的 ⏺ 是一步动作,⎿ 是这一步的结果,行首的 ⏸ 表示会话被切换到了计划态。
场景一:用户用 /plan 主动进入
你先输入 /plan 进入计划态,再把需求交给它。
> /plan
⏸ 已进入 Plan Mode:只调研与规划,不做任何修改。
> 把下单流程改成支持幂等
⏺ Read(OrderService.java)
⏺ Read(OrderController.java)
⏺ Grep(placeOrder)
⎿ 定位到 2 条调用路径
⏺ 调研完成,这是我的计划(尚未执行):
目标
同一笔下单请求被重放时,只产生一笔订单,并返回已有的那笔。
现状
OrderController.placeOrder 直接调用 OrderService.placeOrder(req),请求里没有幂等键。
placeOrder 还有第二条调用路径:CheckoutJob 会在定时重试时再调一次。
Order 表目前也没有可以用来去重的字段。
只在内存里记下「处理过的请求」挡不住多实例,进程重启之后也会失效,所以去重要落在数据库上。
方案
请求增加必填的 dedupKey,由调用方生成。orders 表增加 dedup_key,并建唯一约束。
下单时先按 dedupKey 查已有订单,命中就直接返回;并发插入撞上唯一约束时,再查一次,同样返回已有订单。
不采用「先插入一条 PENDING、再更新成已下单」:现有下单是一次写完的,多一个中间状态会牵动支付和库存,这次用不上。
改动
1. PlaceOrderRequest 增加 dedupKey,OrderController 在入口校验它非空。
2. orders 表增加 dedup_key 并建唯一索引,Order 实体补上这个字段。
3. OrderService.placeOrder 按「先查、再插、冲突再查」处理。
4. CheckoutJob 用 jobId 派生 dedupKey,重跑时复用同一个键。
5. 补测试:同一 key 连续两次返回同一订单;不同 key 产生两笔;并发双写只落一笔。
本次不做
支付回调和库存扣减的幂等。这次只保证「下单」这一步不重复建单。
⏺ ExitPlanMode
是否按此计划开始?
1. 接受计划并执行
2. 不执行,继续完善计划
请选择 [1-2]:1
⏺ 已退出 Plan Mode,开始执行第 1 步…我们来看一下这中间的几步。进入计划态之后,它只做了 Read 和 Grep 这类只读调研,一个文件都没有被修改。
它给出的也不是一份待办。TodoWrite 记的是「接下来做哪几步」;这里要先写清调研看到的现状、选定哪种做法、为什么不选另一种,再落到要改哪些文件、怎么验证、哪些先不做。用户确认的是这套方案,后面执行时才按里面的步骤去改。
计划是作为一段普通文字直接呈现在终端里的,没有生成任何计划文件。
你选了 1 之后,它才退出计划态、开始执行。而且执行阶段每一次编辑仍然会弹审批卡片,这和平时改代码的行为完全一样。
场景二:模型主动提议进入
这一次你没有输入 /plan,直接交给它一个改动较大的任务。
> 给应用加上用户登录
⏺ 这个任务涉及方案选型和多处改动,建议先规划
⏺ EnterPlanMode
要先进入 Plan Mode 吗?我想先调研代码库、设计实现方案,交你审阅后再动手。
1. 是,进入 Plan Mode(先出计划后改动)
2. 否,直接开始实现
请选择 [1-2]:1
⏸ 已进入 Plan Mode:先只调研与规划,不做任何修改。
⏺ Read(SecurityConfig.java)
⏺ Grep(UserRepository)
⎿ …(只读调研,之后产出计划、调用 ExitPlanMode 请求批准,和场景一一致)模型自己判断出这是个大任务,主动调用了 EnterPlanMode,弹出两选项确认框让你决定。
你选「是」就进入计划态,后面的流程和场景一完全一样;你选「否」它就不进入,按原有方式直接开始实现。
场景三:计划态里误碰了写操作
如果在计划态里,模型误调用写操作去改文件,会被 harness 拦下来。
⏺ Edit(OrderService.java)
⎿ 当前处于 Plan Mode:只能调研(只读工具),不能修改文件……请先产出计划再用 ExitPlanMode 请求批准。
⏺ 好的,我先继续调研,不修改文件。它的写操作被拦住了,拒绝的原因会回填给模型。模型看到原因之后,就会回到只调研。
整个过程里,文件一个都没有被改动。
M8 这一版交付什么
我们这一版只做一件事:给 Agent 加上 Plan Mode。
- 用户可以用
/plan随时进入计划态;模型也可以在遇到大任务时主动调用EnterPlanMode提议进入(弹框由用户批准)。 - 进入计划态之后,harness 拦住所有写操作(Edit / Write / Bash),Agent 只能用只读工具调研并产出计划。
- 模型调用
ExitPlanMode请求批准,用户确认后退出计划态、开始执行;用户如果不满意,就让它继续完善计划。 - 计划只显示在终端、留在会话上下文里,不写成磁盘文件。
这一版完成之后,mini Claude Code 第一次具备了「规划和执行分离」这种架构模式:风险大、步骤多的任务,可以先给出计划供用户审阅,再开始修改。
本章的学习路线
接下来的几节,我们把这套能力逐节细化成代码。
- 8.2 我们先讲一下总体架构:M8 复用了 M1 到 M7 的哪些结构、新增了哪个包、一次「先计划后执行」的会话是怎么流动的。
- 8.3 我们来讲一下这一章的三个核心类:计划态开关
PlanModeState、拦截钩子PlanModeHook、提示 StagePlanModeStage。 - 8.4 我们来讲一下进入 Plan Mode 的两条路径:
/plan命令和模型主动调用的EnterPlanMode工具。 - 8.5 我们来讲一下退出:
ExitPlanMode工具、两选项确认卡片。
读完这一章,你会看到 Plan Mode 几乎是「只新增、不修改既有代码」就实现出来的。这正是前面几章预先留好扩展点的结果。
8.2 M8 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.plan.PlanModeState.java
com.minicc.plan.PlanModeHook.java
com.minicc.plan.PlanApprover.java
com.minicc.context.PlanModeStage.java
com.minicc.tool.builtin.EnterPlanModeTool.java
com.minicc.tool.builtin.ExitPlanModeTool.java
com.minicc.MccApplication.java
上一节我们把 M8 要做什么、在命令行里是什么样,都讲清楚了。
这一节我们来看一下它的整体结构:它复用了 M1 到 M7 的哪些结构、新增了哪个包、一次「先计划后执行」的会话是怎么在各个组件之间流动的。
包结构的增量
M8 是建在 M7 之上的,所以我们重点看一下它相对 M7 新增和修改的部分。
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ plan/ // 新:整个包(Plan Mode 这一件事)
│ │ ├─ PlanModeState.java // 新:计划态会话级开关,独立于 PermissionState
│ │ ├─ PlanModeHook.java // 新:计划态拦截钩子(实现 PreExecuteHook,拦写操作)
│ │ └─ PlanApprover.java // 新:计划确认卡片的交互抽象(进入确认 + 退出确认)
│ ├─ context/
│ │ └─ PlanModeStage.java // 新:Stage,计划态开启时注入「只调研不修改」的提示
│ ├─ tool/
│ │ ├─ ToolContext.java // 改:加 PlanModeState 字段,把计划态下发给 PlanModeHook
│ │ └─ builtin/
│ │ ├─ EnterPlanModeTool.java // 新:模型提议进入计划态,弹框请用户批准
│ │ └─ ExitPlanModeTool.java // 新:模型计划好了调它请求批准退出
│ ├─ session/
│ │ └─ Session.java // 改:持有 PlanModeState、暴露 planMode(),/clear 时随新会话重建
│ ├─ cli/
│ │ ├─ CliPlanApprover.java // 新:PlanApprover 的 CLI 实现(进入两选项/退出两选项卡片)
│ │ ├─ Renderer.java // 改:渲染进入/退出 Plan Mode 的提示
│ │ └─ command/
│ │ └─ PlanCommand.java // 改:真正进入计划态(原为占位提示)
│ └─ MccApplication.java // 改:装配 Plan Mode(钩子/Stage/工具/卡片)plan 包里的几个角色
这个新包里只有三个类,各自负责一件事。
PlanModeState:计划态开关。它只回答一个问题,就是「现在是不是计划态」。它由Session持有,和PermissionState平级(见 8.3)。PlanModeHook:计划态拦截钩子。计划态下它拦住写操作、放行只读工具(见 8.3)。PlanApprover:计划确认的交互抽象。它负责「进入确认」和「退出确认」这两处弹框,由 CLI 实现(见 8.4、8.5)。
另外还有两个类放在别的包里。一个是 Stage:PlanModeStage,放在 context 包,和 M5 的 MemoryStage、M7 的 SkillStage 是同类。还有一对工具 EnterPlanModeTool 和 ExitPlanModeTool,放在 tool/builtin 包,和其它内置工具在一起。
既有代码改了哪几处
除了新增,M8 在既有代码上只有几处小改动,而且位置都是前几章早已预告的扩展点。
ToolContext:增加一个PlanModeState字段,把计划态下发给PlanModeHook。Session:持有一个PlanModeState实例、暴露planMode()访问器,并在clear()里随新会话重建。处理方式和PermissionState完全一样。PlanCommand:从占位提示升级为真正进入计划态。MccApplication:把这一切装配起来(下面我们再详细讲一下)。Renderer:新增「已进入 Plan Mode」这类提示的渲染。
钩子链里 PlanModeHook 排在哪里
这是 M8 最关键的一处接入,我们看一下钩子链的装配。
// 源码位置:com.minicc.MccApplication.java
// 钩子链顺序 = 判断顺序:PlanModeHook 排在 ApprovalHook 之前。
HookChain hookChain = new HookChain(List.of(
new PlanModeHook(), // M8:计划态拦写操作(只读放行)
new ApprovalHook(approver))); // M3:写操作先审批PlanModeHook 排在 ApprovalHook 之前,这个顺序很重要。
计划态下,一个写操作先被 PlanModeHook 拦掉,钩子链短路,不会继续执行到后面的审批。
非计划态下,PlanModeHook 一律放行,把判断交给后面的 ApprovalHook 按既有规则处理。
PlanModeStage 放在上下文组装器哪里
另一处接入是上下文组装器的管线。PlanModeStage 插在记忆、技能之后,压缩历史之前。
// 源码位置:com.minicc.MccApplication.java
ContextAssembler assembler = new ContextAssembler(List.of(
new SystemPromptStage(SystemPrompt.TEXT),
memoryStage, // M5:AGENT.md + 记忆说明 + MEMORY.md 索引
skillStage, // M7:技能清单
new PlanModeStage(), // M8:计划态开启时注入「只调研不修改」
new CompactionStage(compactionManager) // M6:接管会话历史这一段
));一次「先计划后执行」的会话全过程
我们按顺序说明一次完整的 Plan Mode 会话。这里以用户 /plan 进入为例,模型主动提议那条路径的差异我们放在第 2 步说明。
第一步,进入计划态。 用户输入 /plan。PlanCommand 调用 session.planMode().enterPlanMode(),Renderer 打印「已进入 Plan Mode」。程序仍然停在 > 等下一条输入。
第二步,每轮注入计划态提示。 用户输入需求,控制循环开始。每一轮组装上下文时,PlanModeStage 发现计划态已开启,就追加一段「你当前处于 Plan Mode:只能用只读工具调研……完成后用 ExitPlanMode 请求批准」的系统提示。如果这一次是模型主动提议进入的,那么在模型调用 EnterPlanMode、用户在弹框里选「是」之后,计划态同样被设置为开启,从下一轮起 PlanModeStage 就会生效,和 /plan 进入完全一致。
第三步,只读调研。 模型发起 Read、Grep、Glob。这些调用在执行前会经过钩子链,链上先是 PlanModeHook:只读工具直接放行。如果模型此刻想调用 Edit、Write 或 Bash,PlanModeHook 会返回拒绝,工具不执行,拒绝的原因回填给模型,模型根据这条原因回到「只调研」。
第四步,请求批准。 调研充分之后,模型把计划作为一段普通文字呈现,并调用 ExitPlanMode。这个工具是只读的,所以钩子链会放行。它通过 PlanApprover 弹出两选项确认卡片,暂停循环,等待用户选择。
第五步,按选择继续。 用户选「接受并执行」,计划态关闭,写操作重新放行,模型在下一轮开始执行计划第一步(执行时每次编辑仍经过审批钩子,逐个弹出卡片)。用户选「继续完善」,计划态保持开启,模型根据反馈继续调研、给出新版计划、再次调用 ExitPlanMode,如此往复,期间始终只读、不修改文件。
整个过程里,Plan Mode 集中在「一个独立开关 + 一个钩子 + 一个提示 Stage + 一对进入退出工具」。AgentLoop 主循环、ModelClient、PermissionState、既有工具都不需要知道它的存在。
下一节我们来讲一下这一章的三个核心类:计划态开关 PlanModeState、拦截钩子 PlanModeHook、提示 Stage PlanModeStage。
8.3 PlanModeState + PlanModeHook + PlanModeStage
本篇涉及到的源码列表:
com.minicc.plan.PlanModeState.java
com.minicc.plan.PlanModeHook.java
com.minicc.context.PlanModeStage.java
com.minicc.session.Session.java
com.minicc.tool.ToolContext.java
上一节我们看了 M8 的整体结构。这一节我们来讲一下这一章的三个核心类。
它们一起回答三个问题:计划态这个状态放在哪里?谁来拦住写操作?模型又怎么知道自己在计划态、该做什么?
三个问题分别对应三个类:PlanModeState、PlanModeHook、PlanModeStage。我们一个一个来讲一下。
PlanModeState:一个独立的会话级开关
我们先看第一个问题:计划态这个状态放在哪里?
我们把它做成一个独立的类 PlanModeState。它的内部只有一个布尔开关,外加三个方法。
// 源码位置:com.minicc.plan.PlanModeState.java
public class PlanModeState {
// 计划态:true 表示只调研、不写(volatile:工具可能在并行线程里查询它)。
private volatile boolean planMode = false;
/** 进入计划态(/plan 命令或 EnterPlanMode 被用户批准时置位)。 */
public void enterPlanMode() {
planMode = true;
}
/** 退出计划态(ExitPlanMode 被用户批准时复位)。只关计划态,不碰 acceptEdits。 */
public void exitPlanMode() {
planMode = false;
}
/** 当前是否处于计划态。 */
public boolean isPlanMode() {
return planMode;
}
}计划态怎么被持有和下发
PlanModeState 的归属和传递方式,和既有的会话级状态完全一致:一个会话一个实例,由 Session 持有,经 ToolContext 下发给钩子。
Session 像持有 PermissionState 那样持有它,并在 clear() 时随新会话重建。
// 源码位置:com.minicc.session.Session.java
// M3 新增:会话级放行状态。
private PermissionState permissions = new PermissionState();
// M8 新增:会话级计划态开关(和 permissions 平级、互不耦合)。
private PlanModeState planMode = new PlanModeState();
/** 本会话的计划态开关(经 ToolContext 下发给 PlanModeHook / PlanModeStage)。 */
public PlanModeState planMode() {
return planMode;
}
public void clear() {
history.clear();
todos.clear();
permissions = new PermissionState();
planMode = new PlanModeState(); // M8:计划态随新会话复位为关闭
}ToolContext 则按 M3、M5 用过的同一处扩展点,多带一个 PlanModeState 字段,把计划态下发给钩子。
// 源码位置:com.minicc.tool.ToolContext.java
public record ToolContext(
Path workingDir, WorkspaceState workspace, TodoList todos,
boolean sandbox, long bashTimeoutMs, CancelToken cancelToken,
PermissionState permissions,
PlanModeState planMode, // M8 新增:计划态开关
Path memoryDir, boolean memoryWritesOnly) {
}PlanModeHook:拦住所有写操作
我们再看第二个问题:谁来拦住写操作?答案是 PlanModeHook。
它实现 M1 的 PreExecuteHook 接口,注册在钩子链上。它的逻辑只有三段。
// 源码位置:com.minicc.plan.PlanModeHook.java
public class PlanModeHook implements PreExecuteHook {
@Override
public Decision beforeExecute(AssistantMessage.ToolCall call, Tool tool, ToolContext ctx) {
// 非计划态:这个钩子不管事,直接放行交给后面的审批钩子。
if (!ctx.planMode().isPlanMode()) {
return Decision.allow();
}
// 计划态:只读工具(Read/Grep/Glob/TodoWrite/EnterPlanMode/ExitPlanMode 等)放行。
if (tool.isReadOnly()) {
return Decision.allow();
}
// 计划态:写操作(Edit/Write/Bash)一律拦下,把原因回填给模型,让它回到「只调研」。
return Decision.deny("当前处于 Plan Mode:只能调研(只读工具),不能修改文件或执行命令。"
+ "请先完成调研并产出计划,再用 ExitPlanMode 请求批准后执行。");
}
}第一段,非计划态时,这个钩子直接放行。它只在计划态下才生效,非计划态下它不做任何拦截。
第二段,计划态下,只读工具会被放行。模型调研要用的 Read、Grep、Glob 都在这一类里。
第三段,计划态下,写操作一律会被拦下。拒绝的原因会作为观察回填给模型,模型看到之后就知道自己不该执行写操作,于是回到只调研。
这里有一个很容易出错的地方,我们要专门强调一下。
我们新增的 ExitPlanMode 工具,它的只读声明必须是 true。因为它声明只读,才能在计划态下被这段代码放行。
如果 ExitPlanMode 被当成写操作拦掉,模型在计划态里就无法请求退出计划态。
所以「ExitPlanMode 声明只读」不是随意声明的,它是让 Plan Mode 能正常退出的前提。
PlanModeStage:让模型知道自己在计划态
我们再看第三个问题:模型怎么知道自己在计划态、该做什么?
仅靠 PlanModeHook 拦住写操作还不够。如果模型不知道自己在计划态,它会一次次尝试写操作、一次次被拒绝,这些回合就浪费了。
所以我们还要把「你在计划态、该怎么做」这件事明确告诉模型。这就是 PlanModeStage 的职责。
它是一个 Stage,仅在计划态开启时贡献一段提示;非计划态时它不追加任何内容。
// 源码位置:com.minicc.context.PlanModeStage.java
public class PlanModeStage implements AssemblyStage {
static final String PLAN_MODE_PROMPT = """
# 你当前处于 Plan Mode(计划模式)
这是一个只读的调研与规划阶段。你现在要做的是:
1. 用 Read / Grep / Glob 彻底调研代码库,理解现有的实现模式与架构;
2. 考虑多种可行方案及其取舍;需要用户拍板时用 AskUserQuestion 澄清;
3. 设计一份具体、无歧义的实现计划,直接作为普通消息呈现给用户(不要写进文件);
4. 计划准备好后,调用 ExitPlanMode 请求用户批准,确认后再开始执行。
重要:现在不要修改或新建任何文件、也不要执行有副作用的命令——这些操作在计划态下都会被拒绝。
""";
/** 仅当本会话处于计划态时,追加一条计划态系统提示;否则不加任何内容。 */
@Override
public void contribute(List<Message> messages, Session session) {
if (session.planMode().isPlanMode()) {
messages.add(new SystemMessage(PLAN_MODE_PROMPT));
}
}
}这段提示把计划态下该做的事,按顺序告诉了模型:先彻底调研、再权衡方案、需要用户决定时用 AskUserQuestion 澄清、设计出一份具体的计划、最后用 ExitPlanMode 请求批准。
把这三个类放在一块来分析
我们把这三个类合在一起看,你就能看清计划态是怎么运转的。
PlanModeState 是那个开关,记录「现在是不是计划态」,由 Session 持有、经 ToolContext 下发。
PlanModeHook 读取这个开关,在执行前拦住写操作、放行只读工具,让「只调研」这件事被真正强制执行。
PlanModeStage 也读取这个开关,往上下文注入一段提示,让模型知道自己该调研、该规划、该用 ExitPlanMode 请求批准。
一个负责状态、一个负责强制、一个负责引导,三者配合,计划态的机制就完整了。
下一节我们来讲一下进入 Plan Mode 的两条路径:用户的 /plan 命令,和模型主动调用的 EnterPlanMode 工具。
8.4 进入 Plan Mode:plan 命令与 EnterPlanMode 工具
本篇涉及到的源码列表:
com.minicc.cli.command.PlanCommand.java
com.minicc.tool.builtin.EnterPlanModeTool.java
com.minicc.plan.PlanApprover.java
com.minicc.cli.CliPlanApprover.java
上一节我们把计划态的三个核心类讲完了。这一节我们来讲一下怎么进入计划态。
进入 Plan Mode 有两条路径:一条是用户主动的 /plan 命令,另一条是模型主动提议的 EnterPlanMode 工具。
两条路径最后都把会话切换到同一个计划态,区别只在于「谁发起、要不要弹框」。我们分别说明。
进入方式一:/plan 用户命令
/plan 只做一件事:把当前会话切换到计划态。
// 源码位置:com.minicc.cli.command.PlanCommand.java
public final class PlanCommand implements SlashCommand {
private final Session session;
private final Renderer renderer;
public PlanCommand(Session session, Renderer renderer) {
this.session = session;
this.renderer = renderer;
}
@Override public String name() { return "plan"; }
@Override public String description() {
return "进入 Plan Mode:只调研与规划,不做任何修改";
}
@Override
public boolean run(String args) {
session.planMode().enterPlanMode(); // 置位计划态;下一轮 PlanModeStage/PlanModeHook 即生效
renderer.planModeEntered(); // 打印「⏸ 已进入 Plan Mode……」
return false; // 不退出程序,仍停在 > 等下一条输入(需求)
}
}它拿到 Session,调用 session.planMode().enterPlanMode() 把计划态设置为开启,再让 Renderer 打印一行提示。
这里的 run 方法返回 false,表示不退出程序。输入完 /plan 之后,程序仍然停在 >,等你输入接下来的需求。
从你输入 /plan 的下一轮起,PlanModeStage 就会往上下文注入计划态提示,PlanModeHook 就会开始拦住写操作。
注意一个细节:/plan 由用户直接发起,不会弹出确认框。用户自己已经决定要先规划,harness 没有理由再问一次。
进入方式二:EnterPlanMode 工具(模型主动提议)
仅有 /plan 还不够。它要求用户记得在开始修改之前输入命令。可很多时候,用户并不知道这个任务有多大,等发现应该先规划时,Agent 可能已经改了多个文件。
更贴近实际的做法是:让模型自己判断「这个任务该不该先规划」,遇到大任务时主动提议进入 Plan Mode,但是否进入由用户决定。
这就是 EnterPlanMode 工具做的事。它和 ExitPlanMode 是对称的一对:一个负责提议进入,一个负责请求退出。
模型在非计划态下判断「这个任务需要先规划」时调用它;工具通过 PlanApprover 弹出一张两选项确认框请用户批准。
- 选「是」:把计划态设置为开启,返回一条观察,告诉模型接下来只用只读工具调研、设计计划、完成后用
ExitPlanMode请求批准。 - 选「否」:不进入计划态,返回观察告诉模型用户想直接开始实现,模型按原有方式开始修改。
工具的声明和描述
我们先看一下它的几个声明。它是只读的,也不能并行执行。
// 源码位置:com.minicc.tool.builtin.EnterPlanModeTool.java
@Override
public boolean isReadOnly() {
return true; // 不碰文件/环境,无需审批;计划态下也会被 PlanModeHook 放行
}
@Override
public boolean isConcurrencySafe() {
return false; // 要暂停循环、与用户交互,不能并行
}它声明为只读,是因为它不修改文件、不改变环境,只是弹出确认框询问用户。它不能并行,是因为它要暂停循环、等用户在确认框里选择,不能和别的工具一起执行。
更关键的是它的 description。这段描述直接决定了模型会在什么时候主动提议进入计划态,所以我们把「何时该用、何时不该用」写得很具体。
// 源码位置:com.minicc.tool.builtin.EnterPlanModeTool.java
@Override
public String description() {
return """
当你即将开始一个非简单的实现任务、且先让用户确认思路能避免返工时,主动调用本工具进入 Plan Mode。
适合用它的情况(满足任一即可):需求有多种合理实现方案、改动会影响既有行为或结构、
涉及架构取舍、预计要动多个文件、或需求尚不清晰需要先调研。
不要用它的情况:改一两行的小修复、按明确指示即可完成的任务、纯调研/检索类任务。
拿不准时,倾向于先规划——提前对齐比返工划算。
本工具不接收参数;是否进入由用户在弹框里确认。""";
}你可以看到,它把「适合用」和「不要用」两面都讲清楚了。有多种方案、要改结构、要改多个文件、需求不清晰,这些是该规划的;改一两行、指示明确、纯检索,这些不该规划。
最后一句「拿不准时,倾向于先规划」是一条兜底原则。提前对齐的成本低于返工,所以在模棱两可的时候,宁可先向用户确认。
工具的执行逻辑
我们再看一下它的 execute 方法。
// 源码位置:com.minicc.tool.builtin.EnterPlanModeTool.java
@Override
public ToolResult execute(AssistantMessage.ToolCall call, ToolContext ctx) {
// 已在计划态里再调它没有意义——返回错误观察让模型纠正(通常是它误判了状态)。
if (ctx.planMode().isPlanMode()) {
return ToolResult.error("当前已在 Plan Mode,无需再次进入。");
}
boolean enter = planApprover.confirmEnterPlan(); // 弹两选项框、等用户选
if (enter) {
ctx.planMode().enterPlanMode(); // 用户批准 → 置位计划态,下一轮 PlanModeStage 即生效
return ToolResult.ok("""
已进入 Plan Mode:接下来请只用只读工具(Read/Grep/Glob)彻底调研代码库、理解现有模式、
设计一份具体的实现计划,期间不要修改任何文件或执行有副作用的命令;
计划好了用 ExitPlanMode 请求用户批准后再执行。""");
}
// 用户选「直接实现」:不进入计划态,回填观察让模型照常动手。
return ToolResult.ok("用户选择直接开始实现,未进入 Plan Mode。");
}第一步是一个状态检查:如果当前已经在计划态了,再调用它没有意义,就返回一条错误观察让模型纠正。这通常是模型误判了自己的状态。
第二步调用 planApprover.confirmEnterPlan(),弹出确认框,等待用户选择。
用户选「是」,就把计划态设置为开启,并回填一条指引性的观察。用户选「否」,就不进入计划态,回填一条「用户想直接实现」的观察。
无论哪种选择,结果都是作为一条观察回流到历史里,循环带着这条观察继续执行。这就是为什么主循环不需要修改。
两条进入路径弹不弹框的区别
我们把两条进入路径对比一下,你就能看懂一个关键区别:为什么 /plan 不会弹出确认框,而 EnterPlanMode 必须弹出确认框。
/plan 是用户自己发起的。用户都已经主动输入命令了,说明他自己已经决定要先规划。这时候 harness 再弹出确认框问「你真的要进入计划态吗」,就多确认了一次。
EnterPlanMode 是模型发起的。进不进计划态这件事,最终要由用户决定,不能让模型自己决定。所以模型只能「提议」,弹框把决定权交还给用户。
可以概括为:用户自己发起的无需再问,模型发起的要由用户决定。
进入确认框长什么样
EnterPlanMode 弹出的那张确认框,底层复用了和审批、提问卡片同一套组件,也就是 CardPrompter。
它由 CliPlanApprover 的 confirmEnterPlan 组装。
// 源码位置:com.minicc.cli.CliPlanApprover.java
@Override
public boolean confirmEnterPlan() {
List<String> preview = List.of(
"要先进入 Plan Mode 吗?我想先调研代码库、设计实现方案,交你审阅后再动手。");
List<String> options = List.of(
"是,进入 Plan Mode(先出计划后改动)",
"否,直接开始实现");
int idx = prompter.select(preview, "EnterPlanMode", options);
if (idx < 0) { // Ctrl-C / Ctrl-D:取消整个任务(不进入、也不等于选「直接实现」)
cancelToken.cancel();
return false;
}
return idx == 0; // 0=进入;1=直接实现
}它组装一句说明、两个选项,交给 CardPrompter 打印并读一行编号,再把编号翻译回布尔值。
在终端里,它大致是这样。
⏺ EnterPlanMode
要先进入 Plan Mode 吗?我想先调研代码库、设计实现方案,交你审阅后再动手。
1. 是,进入 Plan Mode(先出计划后改动)
2. 否,直接开始实现
请选择 [1-2]:这里还有一个细节要注意:在等编号的时候按 Ctrl-C,会怎么样?
这时 CardPrompter 返回一个负数,confirmEnterPlan 根据这个返回值设置取消信号,取消整个任务。
我们要注意,取消不等于任何一个选项。被 Ctrl-C 取消,既不进入计划态,也不等于选了「直接实现」,而是取消整个任务,会话回到 > 等你的新指令。这个行为和审批、提问卡片完全一致。
这一节小结
进入 Plan Mode 有两条路径,它们最终都设置同一个 PlanModeState 开关。
/plan 由用户直接发起,不会弹出确认框,PlanCommand 直接把计划态设置为开启。
EnterPlanMode 由模型主动提议,必须弹出确认框,用户选「是」才把计划态设置为开启。
下一节我们来讲一下退出:模型调用的 ExitPlanMode 工具、两选项确认卡片,并把一次完整会话按顺序说明一遍。
8.5 退出 Plan Mode:ExitPlanMode 工具
本篇涉及到的源码列表:
com.minicc.tool.builtin.ExitPlanModeTool.java
com.minicc.plan.PlanApprover.java
com.minicc.cli.CliPlanApprover.java
上一节我们讲了怎么进入 Plan Mode。这一节我们来讲一下怎么退出,再把一次完整会话按顺序说明一遍。
退出计划态只有一条路径:模型调研完、计划写好了,调用 ExitPlanMode 请求用户批准。
退出为什么做成工具,而不是命令
进入计划态有一条路径是用户命令(/plan),退出却只做成工具。我们先说清楚这个选择。
我们把退出做成工具,有两个好处。
第一个好处是,由模型决定「计划好了」的时机。模型在调研的中途,可能会产出一些过程性的文字,那些都还不是最终计划。到底什么时候算「计划定稿、可以请求批准了」,交给模型自己判断是最合适的。
第二个好处是,退出的结果天然作为观察回流。工具返回的内容和任何工具结果一样,会回填进历史、驱动下一轮请求。这样循环不需要任何特殊的控制流就能继续执行。
这也正是 M8 的 AgentLoop 主循环一行都不需要修改的原因。
ExitPlanMode 工具
ExitPlanMode 和 EnterPlanMode 是对称的一对。它也是只读的、不能并行执行,也通过一张确认框加上回填观察来驱动循环。
我们先看一下它的描述。这段描述把何时该用、何时不该用讲清楚了。
// 源码位置:com.minicc.tool.builtin.ExitPlanModeTool.java
@Override
public String description() {
return """
当你正处于 Plan Mode、已经把实现计划写好、准备让用户审阅批准时调用本工具。
- 只在"需要规划一个要写代码的实现任务"时用;纯调研/检索/读代码理解的任务不要用它。
- 不要用 AskUserQuestion 去问"这个计划行不行/要不要开始"——那正是本工具要做的事。
- 调用前请确保计划完整、无歧义;若对需求或方案还有疑问,先用 AskUserQuestion 澄清。
本工具不接收计划内容作参数:计划应当已经作为普通消息呈现给用户。""";
}这里有一条约束我们要特别留意:不要用 AskUserQuestion 去问「这个计划行不行」。因为「请求用户批准计划」正是 ExitPlanMode 这个工具本身要做的事,用 AskUserQuestion 去问就重复了。
还有一句也值得我们注意:本工具不接收计划内容作参数。
为什么不接收计划?因为计划已经作为普通消息呈现在上下文里了。产品上我们约定计划留在终端和上下文、不写磁盘文件,所以 ExitPlanMode 不需要把计划再传一遍,它只负责「请求批准」这一件事。
我们再看一下它的执行逻辑。
// 源码位置:com.minicc.tool.builtin.ExitPlanModeTool.java
@Override
public ToolResult execute(AssistantMessage.ToolCall call, ToolContext ctx) {
// 不在计划态却调它没有意义——返回错误观察让模型纠正。
if (!ctx.planMode().isPlanMode()) {
return ToolResult.error("当前不在 Plan Mode,无需退出。");
}
PlanApprover.Result result = planApprover.confirmPlan(); // 弹卡片、等用户选
if (result.canExecute()) {
ctx.planMode().exitPlanMode(); // 只退出计划态,不碰 acceptEdits
return ToolResult.ok("计划已批准。已退出 Plan Mode,开始执行;每次编辑仍会弹审批卡片确认。");
}
// 继续完善计划:仍留在计划态,把用户反馈作为观察回填,驱动模型给出新版计划。
String feedback = result.feedback() == null ? "" : result.feedback().strip();
return ToolResult.ok("用户暂不执行,希望继续完善计划(仍处于 Plan Mode)。"
+ (feedback.isEmpty() ? "" : "用户反馈:" + feedback));
}开头同样是一个状态检查:如果当前不在计划态,调用它没有意义,返回错误观察让模型纠正。
接着调用 planApprover.confirmPlan() 弹出卡片、等待用户选择,结果分两种。
用户选「接受并执行」,就调用 exitPlanMode() 退出计划态,并回填一条观察。
用户选「继续完善」,就保持计划态,把用户填写的反馈拼进观察回填给模型,驱动模型给出新版计划。
PlanApprover:两处确认的交互抽象
ExitPlanMode 弹出确认框,靠的是 PlanApprover 这个交互抽象。
// 源码位置:com.minicc.plan.PlanApprover.java
public interface PlanApprover {
/** EnterPlanMode 弹「是否进入 Plan Mode?」两选项框。true=进入;false=直接实现。 */
boolean confirmEnterPlan();
/** ExitPlanMode 弹「是否按此计划开始?」两选项框。 */
Result confirmPlan();
/** canExecute=true 表示接受计划、退出计划态;false 表示继续完善计划(feedback 为用户反馈)。 */
record Result(boolean canExecute, String feedback) {
}
}这个接口里的两个方法,正好对应 Plan Mode「两条进入、一条退出」里需要弹框的两处。confirmEnterPlan 对应进入提议,confirmPlan 对应退出请求。
两处确认都是「两选项」,所以返回值都用布尔表示。进入确认直接返回 boolean,退出确认返回一个 Result,多带一句「继续完善」时的反馈文字。
退出确认卡片两选项
confirmPlan 的 CLI 实现,弹出的是一张两选项卡片,选「继续完善」时还会再读一行反馈意见。
// 源码位置:com.minicc.cli.CliPlanApprover.java
@Override
public Result confirmPlan() {
List<String> options = List.of(
"接受计划并执行",
"不执行,继续完善计划");
int idx = prompter.select(null, "ExitPlanMode:是否按此计划开始?", options);
if (idx < 0) { // Ctrl-C / Ctrl-D:取消整个任务(计划态保持原样)
cancelToken.cancel();
return new Result(false, "");
}
if (idx == 0) { // 接受计划并执行 → 退出计划态
return new Result(true, "");
}
// 继续完善计划:再读一行用户意见(可留空),随结果回填给模型。
String feedback = prompter.readLine(" 想让我怎么改进计划?(直接回车可跳过)> ");
if (feedback == null) { // 读反馈时 Ctrl-C:也按取消任务处理
cancelToken.cancel();
return new Result(false, "");
}
return new Result(false, feedback.strip());
}它先弹出两选项卡片。选 1 返回「接受并执行」,选 2 之后再读一行反馈意见(可以留空),把反馈随结果一起回填。
在终端里,模型呈现完计划、调用 ExitPlanMode 之后,大致是这样。
⏺ 调研完成,这是我的计划(尚未执行):
目标
同一笔下单请求被重放时,只产生一笔订单,并返回已有的那笔。
现状
OrderController.placeOrder 直接调用 OrderService.placeOrder(req),请求里没有幂等键。
placeOrder 还有第二条调用路径:CheckoutJob 会在定时重试时再调一次。
Order 表目前也没有可以用来去重的字段。
只在内存里记下「处理过的请求」挡不住多实例,进程重启之后也会失效,所以去重要落在数据库上。
方案
请求增加必填的 dedupKey,由调用方生成。orders 表增加 dedup_key,并建唯一约束。
下单时先按 dedupKey 查已有订单,命中就直接返回;并发插入撞上唯一约束时,再查一次,同样返回已有订单。
不采用「先插入一条 PENDING、再更新成已下单」:现有下单是一次写完的,多一个中间状态会牵动支付和库存,这次用不上。
改动
1. PlaceOrderRequest 增加 dedupKey,OrderController 在入口校验它非空。
2. orders 表增加 dedup_key 并建唯一索引,Order 实体补上这个字段。
3. OrderService.placeOrder 按「先查、再插、冲突再查」处理。
4. CheckoutJob 用 jobId 派生 dedupKey,重跑时复用同一个键。
5. 补测试:同一 key 连续两次返回同一订单;不同 key 产生两笔;并发双写只落一笔。
本次不做
支付回调和库存扣减的幂等。这次只保证「下单」这一步不重复建单。
⏺ ExitPlanMode
是否按此计划开始?
1. 接受计划并执行
2. 不执行,继续完善计划
请选择 [1-2]:为什么选 1 之后不用写特殊控制流
这是整个退出设计里最需要说明的一点。
你可能会认为,用户选「接受并执行」之后,需要在 AgentLoop 里写一段特殊的控制流,告诉循环「现在要开始执行计划了」。
控制循环不需要这样写。因为 ExitPlanMode 的返回值就是一条观察,它和任何工具结果一样回填进历史、驱动下一轮请求。
选 1 的时候,计划态已经关闭,写操作重新放行。模型在下一轮读到「计划已批准、已退出 Plan Mode」这条观察,就会开始执行计划第一步。执行阶段每次编辑仍然经过审批钩子,逐个弹出卡片,和非计划态下的既有行为完全一样。
选 2 的时候,计划态仍然开启,模型读到用户的反馈,继续调研、再给一版计划,再次调用 ExitPlanMode。整个过程全程只读,直到用户选了 1。
控制循环不需要做任何修改,后续步骤都由「观察回流」继续推进。
本章小结
到这里,整个第八章就讲完了。其实,还有很多其他功能,我们没有开发,比如subAgent、流式输出(打字效果)、调用超时/重试处理等等。等我有空了,会持续优化这个项目,并编写课程文档。
