第 3 章 · M3 人工介入(HITHL)
第 3 章 · M3 人工介入(HITHL)
- 3.1 M3 功能说明:审批、提问与中途取消
- 3.2 M3 总体架构:包结构与组件协作
- 3.3 权限模型:把审批做成 PreExecuteHook
- 3.4 会话级放行状态 PermissionState
- 3.5 权限审批卡片:三个选项与渲染
- 3.6 AskUserQuestion 工具的实现
- 3.7 Ctrl-C 中途取消:协作式取消与 CancelToken
- 3.8 取消信号从哪来、各处怎么响应、取消后的停止
3.1 M3 功能说明:审批、提问与中途取消
本篇涉及到的源码列表:
com.minicc.permission.ApprovalHook.java
com.minicc.cli.CliApprover.java
com.minicc.cli.CardPrompter.java
com.minicc.permission.PermissionState.java
com.minicc.tool.builtin.AskUserQuestionTool.java
com.minicc.cli.CliQuestionAsker.java
com.minicc.agent.CancelToken.java
com.minicc.cli.Repl.java
com.minicc.cli.Renderer.java
M2 我们做完了,它已经是一个能真正改代码、能执行命令的 Agent。
但 M2 有一个我们当时就说明过的前提:它的写操作(Edit、Write、Bash)会直接执行,中间没有任何人工把关。
我们只能靠"在 git 项目上用、改坏了随时回退"来兜底。这显然不够。
从这一章开始,我们进入第三个里程碑 M3,目标就是把这道最关键的部分补上:把执行控制权交回给使用者。
这一节我们先不写代码,而是把 M3 要交付的功能讲清楚,并看用户在命令行里会看到什么。包怎么组织、一次任务怎么流动,我们放到下一节。
M3 这一版交付什么
M3 要给 Agent 加上三把"控制阀",它们正好对应人机协作的三种场景。
- 审批选择卡片:执行 Edit、Write、Bash 这类有副作用的操作之前,运行时强制弹出一张卡片,由你来决定是否允许执行。
- Ctrl-C 中途取消:Agent 执行过程中,你随时可以按 Ctrl-C 打断它。运行时会在安全位置停下,保留已有的工作状态,等你的新指令。
- AskUserQuestion 主动提问:当需求不明确、或者有好几种都合理的做法时,模型主动调用这个工具弹出一张选择卡片,让你在候选项里选择,而不是凭空假设。
审批:改文件、执行命令之前先问你
Read、Grep、Glob 直接执行。轮到 Edit、Write、Bash,运行时先把卡片打出来,等你选完,工具才执行。
所以卡片出现在 ⏺ Edit(...) 那一行之前。审批发生在工具执行之前,调用和结果要等这一批做完,才按原来的顺序成对打印。
> 给 OrderController 的下单接口加上参数校验
⏺ 先看一下 OrderController 的现状
⏺ Read(file_path=/Users/wangzheng/codecrush/src/main/java/OrderController.java)
⎿ 1 package com.example;
2
3 import org.springframework.web.bind.annotation.RestController;
4
5 @RestController
6 public class OrderController {
…(共 120 行)
⏺ 复用已有的 OrderValidator,在 placeOrder 入口做校验
变更预览:/Users/wangzheng/codecrush/src/main/java/OrderController.java
- public void placeOrder(@RequestBody OrderRequest req) {
+ public void placeOrder(@RequestBody OrderRequest req) {
+ orderValidator.validate(req);
对 OrderController.java 应用此修改?
1. 允许
2. 允许,本会话内的所有文件修改不再询问
3. 拒绝,并说明原因
请选择 [1-3]:1
⏺ Edit(file_path=/Users/wangzheng/codecrush/src/main/java/OrderController.java, old_string=...)
⎿ 已修改 /Users/wangzheng/codecrush/src/main/java/OrderController.java(替换 1 处,+2 -1 行)
49 public void placeOrder(@RequestBody OrderRequest req) {
50 orderValidator.validate(req);
51 orderService.placeOrder(req.toOrder());输入 1,只放行这一次。下一次改文件,卡片还会再出现。
输入 2,这次放行,并且本会话里后续的 Edit 和 Write 直接执行。Write 的标题是「写入 OrderController.java?」,预览是即将写入的前几行,三个选项和 Edit 相同。
Bash 的第二项按命令的第一个词来写。mvn -q test 对应的是所有 mvn 命令。
$ mvn -q test
# 运行测试验证改动
执行命令?
1. 允许
2. 允许,本会话内的所有 mvn 命令不再询问
3. 拒绝,并说明原因
请选择 [1-3]:输入 3,这次操作不执行。终端再读一行原因,原因会作为这次工具的结果回到模型,模型可以换一种做法继续。
请选择 [1-3]:3
拒绝原因(告诉 Agent 换个做法,直接回车可跳过)> 校验放到 OrderService,不要改 Controller
⏺ Edit(file_path=/Users/wangzheng/codecrush/src/main/java/OrderController.java, old_string=...)
⎿ 用户拒绝执行工具 Edit,理由:校验放到 OrderService,不要改 Controller卡片等待编号时按 Ctrl-C,取消的是整个任务。若只拒绝这一次操作,请输入 3 并填写原因。
提问:模型还不能确定时来问你
模型自己调用 AskUserQuestion 时,终端先打出它的说明,再打出一张提问卡片。系统总会在候选项最后补上「其他(我来补充)」。你选了这一项,它会再读一行补充说明。
> 给用户密码加上加密存储
⏺ 这个改动有几种常见做法,想先跟你确认一下
用哪种加密方案?
选择:加密方案
1. BCrypt — Spring Security 自带,开箱即用
2. Argon2 — 更强,但需要额外依赖
3. PBKDF2 — 标准库支持
4. 其他(我来补充)
请选择 [1-4]:1
⏺ AskUserQuestion(questions=[{question=用哪种加密方案?, header=加密方案, ...}])
⎿ 用户已作答:
- [加密方案] 用哪种加密方案?
选择:BCrypt你输入 1 之后,答案回到模型,循环按你的选择继续。AskUserQuestion 是只读工具,审批钩子直接放行,提问卡片打完就等你输入编号。
问题允许多选时,提示会变成「请选择(多选用逗号分隔,如 1,3)」,你输入 1,3 即可。
取消:执行过程中按 Ctrl-C
任务还在执行时,你按 Ctrl-C,终端只多一行提示,然后回到 >。程序保持运行,已经确认过的修改留在工作区里,会话和待办也还在。你可以接着输入下一条指令。
⏺ 正在给 PaymentService 补超时处理
⏺ Read(file_path=/Users/wangzheng/codecrush/src/main/java/PaymentService.java)
⎿ 1 package com.example;
2
3 public class PaymentService {
4
5 public void pay() {
6 // ...
…(共 300 行)
[按下 Ctrl-C]
⎿ Interrupted by user(已中断)
>任务已经结束、光标停在 > 上时,再按 Ctrl-C 是结束会话、退出程序。
本章的学习路线
接下来的七节,我们把上面这些能力一块块细化成代码。
- 3.2 我们先来讲总体架构,看要复用哪些扩展点、包怎么组织,以及一次带审批的任务怎么在组件之间流动。
- 3.3 我们讲权限模型:为什么权限由运行时强制,以及怎么把审批做成一个
PreExecuteHook。 - 3.4 我们讲会话级放行状态
PermissionState。 - 3.5 我们讲审批卡片:三个选项的语义与渲染方式。
- 3.6 我们讲 AskUserQuestion 工具,重点是它和审批卡片的根本区别。
- 3.7 我们讲 Ctrl-C 中途取消的协作式取消与
CancelToken。 - 3.8 我们讲取消信号从哪来、各处怎么响应、取消后的停止语义。
读完这一章,你就有一个会遵守使用者决定的 Agent 了:危险操作会先问你,你随时可以中断执行,它还不能确定时也会主动来问你。
3.2 M3 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.agent.AgentLoop.java
com.minicc.agent.ToolScheduler.java
com.minicc.agent.CancelToken.java
com.minicc.permission.ApprovalHook.java
com.minicc.permission.PermissionState.java
com.minicc.permission.Approval.java
com.minicc.permission.Approver.java
com.minicc.ask.QuestionAsker.java
com.minicc.ask.Question.java
com.minicc.ask.Answer.java
com.minicc.tool.ToolContext.java
com.minicc.tool.hook.PreExecuteHook.java
com.minicc.tool.bash.CommandRunner.java
com.minicc.tool.builtin.AskUserQuestionTool.java
com.minicc.cli.Repl.java
com.minicc.cli.Renderer.java
com.minicc.cli.CardPrompter.java
com.minicc.cli.CliApprover.java
com.minicc.cli.CliQuestionAsker.java
com.minicc.session.Session.java
上一节我们把 M3 要做什么、在命令行里长什么样讲清楚了。这一节我们来看它的整体骨架:要复用 M1 和 M2 的哪些扩展点、包怎么组织、一次带审批的任务怎么在各个组件之间流动。
你先掌握这张结构图,后面几节逐个讲每个组件时,你就知道它在整体里处在什么位置。
M3 要复用的 M1 / M2 扩展点
M3 是对"后续里程碑只新增、少修改既有代码"这条设计原则的又一次检验,而且是最能体现扩展点价值的一次。它主要做三件事。
第一件,把审批钩子挂进 HookChain。 M1 在控制循环里预留了"执行前钩子"这条链,M2 让它一直是一条空链(写操作直接放行)。M3 只是往这条链里注册一个 ApprovalHook 实现。M2 的四个工具本身一行都不用改,它们执行之前自动多过一道审批关。
第二件,给 ToolContext 接上取消信号。 M1 的 ToolContext 注释里早就写明,后续会在这里扩展取消信号。M3 把 CancelToken 加进去,工具在执行中按需查询它。
第三件,向 ToolRegistry 新增一个工具。 AskUserQuestion 和 M2 新增 Edit、Write 一样,实现 Tool 接口,我们再把它注册进去就可以了。
包结构的增量
M3 是建在 M2 之上的,所以我们重点看它相对 M2 新增和修改的部分。
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ agent/
│ │ ├─ AgentLoop.java // 改:循环检查点检查取消信号;回填拒绝原因
│ │ ├─ ToolScheduler.java // 改:响应取消、不再派发新工具
│ │ └─ CancelToken.java // 新:协作式取消信号
│ ├─ permission/ // 新:整个包(审批 / 权限这一件事)
│ │ ├─ ApprovalHook.java // 新:审批钩子,实现 PreExecuteHook
│ │ ├─ PermissionState.java // 新:会话级放行状态
│ │ ├─ Approval.java // 新:用户对审批卡片的选择
│ │ └─ Approver.java // 新:审批交互抽象(只有 requestApproval)
│ ├─ ask/ // 新:整个包(模型主动提问这一件事)
│ │ ├─ QuestionAsker.java // 新:提问交互抽象(只有 askQuestions)
│ │ ├─ Question.java // 新:一个问题
│ │ └─ Answer.java // 新:用户对一个问题的回答
│ ├─ tool/
│ │ ├─ ToolContext.java // 改:加入 CancelToken 与 PermissionState
│ │ ├─ hook/
│ │ │ └─ PreExecuteHook.java // 改:Decision 升级为可携带拒绝原因
│ │ ├─ bash/
│ │ │ └─ CommandRunner.java // 改:取消时中止子进程
│ │ └─ builtin/
│ │ └─ AskUserQuestionTool.java // 新:依赖 QuestionAsker
│ ├─ cli/
│ │ ├─ Repl.java // 改:任务期间安装 Ctrl-C 处理函数,置位取消信号
│ │ ├─ Renderer.java // 改:渲染"已中断"
│ │ ├─ CardPrompter.java // 新:审批 / 提问卡片的统一渲染与交互
│ │ ├─ CliApprover.java // 新:Approver 的 CLI 实现(审批卡片)
│ │ └─ CliQuestionAsker.java // 新:QuestionAsker 的 CLI 实现(提问卡片)
│ └─ session/
│ └─ Session.java // 改:持有 PermissionState我们可以把这些改动归成几类。
一类是两个新包,对应两件独立的事。permission 包装的是审批与权限,ask 包装的是模型主动提问。它们刻意分开,互不依赖。
一类是取消信号,就是 agent 包下新增的一个 CancelToken。
一类是CLI 的交互部件,都放在 cli 下:统一的卡片渲染 CardPrompter,以及审批、提问各自的 CLI 实现。
剩下的 ToolContext、PreExecuteHook、AgentLoop、ToolScheduler、CommandRunner、Repl、Renderer、Session,都只是小幅修改。图里标了"新"的是纯新增,标了"改"的是少量修改,而且多数是 M1 和 M2 早就预告过的扩展点。
你会发现,控制循环的骨架、模型边界、上下文组装器、工具接口的主体、M2 的四个工具实现,几乎都没有改动。
一次"带审批的改代码"任务怎么流动
上一节的终端画面,是下面这条链路打出来的。我们还是用「给下单接口加参数校验」这个例子,看一次任务怎么在这些组件之间流转。
第一步,Repl 读到用户的需求,把它追加为一条用户消息,然后安装一个 Ctrl-C 处理函数(按下就会把取消信号置位),再调用 AgentLoop.run()。
第二步,AgentLoop 进入循环。 每一轮它都先在循环顶部检查一次取消信号,再调模型拿到这一轮的assistant消息,模型返回后、派发工具前再检查一次取消。
如果这条消息不含工具调用,说明是最终答复,循环结束。
如果含工具调用,就整批交给 ToolScheduler。
第三步,ToolScheduler 在真正执行每个工具之前,先经过一遍 HookChain。 和 M2 不同的是,现在链上挂着 ApprovalHook。
- 工具是只读的(Read、Grep、Glob、TodoWrite、AskUserQuestion):审批钩子直接放行。
- 工具有副作用(Edit、Write、Bash):审批钩子先查询
PermissionState,本会话已经放行同类就放行;否则通过Approver弹出上一节那种编号卡片、暂停等你选择。你选「允许」就放行,选「会话级放行」就先更新PermissionState再放行,选「拒绝」就把这次调用拦截下来,并把原因回填给模型。
第四步,任务结束,Repl 还原 Ctrl-C 处理函数,回到 > 等待你的下一条输入。此时再按 Ctrl-C,含义变成结束会话、退出程序,不再是取消任务。
提问是怎么插进来的
上面我们讲的是审批这条线。那模型主动提问这条线呢?
它更简单:模型若主动调用 AskUserQuestion,这就是一个普通的工具调用。
ToolScheduler 执行它时,工具内部通过 QuestionAsker 和 CardPrompter 弹出提问卡片、等你作答,把答案作为观察回填,循环继续。
因为它是只读工具,所以根本不会触发审批,不需要再经过 ApprovalHook 那一关。
三条线,各走各的
这一节的架构可以概括为:审批发生在 HookChain、取消贯穿 CancelToken、提问是一个工具。
这三条线分得很清楚,彼此独立。审批挂在钩子链上,是工具执行前的一道外部关卡;取消是一个被各处主动查询的信号;提问则完全是一个普通工具,走和其它工具一样的调用路径。
正因为职责分得清楚,M3 才能在几乎不修改 M2 既有代码的前提下,把这三把控制阀一次加进来。
3.3 权限模型:把审批做成 PreExecuteHook
本篇涉及到的源码列表:
com.minicc.tool.hook.PreExecuteHook.java
com.minicc.permission.ApprovalHook.java
我们先来讲一个很重要的原则:是否需要审批、是否允许执行,统统由 harness 来判断,不依赖模型自觉。
模型只管提出"我要调用 Edit 改这个文件",至于是否允许,由运行时在执行前拦截下来决定。
为什么要强调"不依赖模型自觉"?因为模型是不可控的,你没法保证它每次都乖乖地先征求同意,再开始执行。
把关的职责必须放在一个模型无法跳过的位置。这正是 M1 当初把"执行前钩子"设计成扩展点的用意:权限判断是工具之外、执行之前的一道独立关卡。
先给 Decision 升级一下
M1 定义的钩子接口很简单,返回值是一个裸枚举:
// 源码位置:com.minicc.tool.hook.PreExecuteHook.java(M1 的原始形态)
public interface PreExecuteHook {
Decision beforeExecute(ToolCall call, Tool tool, ToolContext ctx);
enum Decision { ALLOW, DENY } // M1 原始定义
}这个枚举在 M1、M2 都够用,因为那时拒绝就是拒绝,不需要多说什么。
但 M3 的审批卡片有一个选项是"拒绝,并说明原因"。这个原因必须作为观察回填给模型("用户拒绝了这次修改,理由是……"),模型才能据此换个做法。
裸枚举没法携带这段文字,所以我们把 Decision 从枚举升级为一个小对象。
// 源码位置:com.minicc.tool.hook.PreExecuteHook.java
record Decision(boolean allowed, String reason) {
/** 放行。 */
public static Decision allow() {
return new Decision(true, null);
}
/** 拒绝,并带回原因(回填给模型)。 */
public static Decision deny(String reason) {
return new Decision(false, reason);
}
}这是 M3 对 M1 钩子接口唯一的一处改动,而且向后兼容:放行和拒绝的语义都还在,只是多了一个 reason 字段。
HookChain 里原来判断是否拒绝的 == DENY,相应改成 !decision.allowed() 就可以了。
把审批做成一个 PreExecuteHook 实现
有了升级后的 Decision,我们就可以把整个审批逻辑封装成一个 ApprovalHook,让它实现 PreExecuteHook 接口,挂到钩子链上。
我们先看它的字段。它只依赖一个 Approver,也就是"弹卡片、等用户选"这个能力的抽象。
// 源码位置:com.minicc.permission.ApprovalHook.java
public class ApprovalHook implements PreExecuteHook {
// 只依赖 Approver(弹卡片、等用户选,由 CLI 实现)。
// 会话级放行状态 PermissionState 不作为字段注入,而是随会话走、由 ToolContext 带进来,
// 和 M2 的 WorkspaceState 一个套路。这样钩子保持无状态,/clear 换会话也不会读到脏状态。
private final Approver approver;
public ApprovalHook(Approver approver) {
this.approver = approver;
}
// ...
}这里有个细节值得我们单独说一下:为什么 PermissionState 不作为字段注入,而是从 ToolContext 里取?
因为放行状态是跟着会话走的,/clear 换了新会话,它就该重建。如果把它做成钩子的字段,换会话后钩子还握着旧会话的放行状态,就会读到脏数据。
所以我们让钩子保持无状态,放行状态由 Session 持有、经 ToolContext 下发。这和 M2 的 WorkspaceState 是同一个套路。
判断逻辑:三步走
接下来我们看 beforeExecute 的判断逻辑。它分三步,一步步往下走。
// 源码位置:com.minicc.permission.ApprovalHook.java(省略了 M5 记忆相关的分支)
@Override
public Decision beforeExecute(AssistantMessage.ToolCall call, Tool tool, ToolContext ctx) {
PermissionState permissions = ctx.permissions(); // 从上下文取本会话的放行状态
// 1) 只读工具(Read/Grep/Glob/TodoWrite/AskUserQuestion)无副作用,直接放行。
if (tool.isReadOnly()) {
return Decision.allow();
}
// 2) 本会话已放行同类操作 → 直接放行。
// - Edit/Write:会话已进入"自动接受编辑"
// - Bash:该命令前缀已在本会话放行过
if (permissions.isGranted(call, tool)) {
return Decision.allow();
}
// 3) 以上都不命中 → 弹审批卡片,暂停等用户选。
Approval choice = approver.requestApproval(call, tool, ctx);
switch (choice.kind()) {
case ALLOW_ONCE:
return Decision.allow();
case ALLOW_SESSION:
permissions.grantSession(call, tool); // 记入本会话的放行状态
return Decision.allow();
case REJECT:
default:
return Decision.deny(choice.reason()); // 带回用户填写的原因
}
}第一步,只读工具直接放行。Read、Grep、Glob、TodoWrite、AskUserQuestion 都不修改文件,也不改变运行环境,没有必要询问你。
第二步,审批钩子查询会话级放行状态。如果本会话里你已经放行过同类操作,也直接放行,不必每次都询问。这一步的细节我们下一节专门来讲一下。
第三步,前两步都不命中,才弹审批卡片,暂停循环等你选。你的三种选择,分别对应"放行本次""放行会话级同类并记入状态""拒绝并带回原因"。
这里补充说明:实际代码里在第一步和第二步之间,还有两个和 M5 长期记忆相关的分支(写入记忆目录自动放行、提取回合只准写记忆目录)。它们属于 M5 的内容,和 M3 的审批主干无关,我们这里先略过。
小结
这一节我们建立了 M3 的权限模型。
权限由运行时强制,不依赖模型自觉,这决定了审批必须放在一个模型无法跳过的位置,也就是执行前钩子。
我们把 Decision 升级为能携带拒绝原因的小对象,这是对 M1 接口唯一的改动。
然后把整个审批逻辑封装成一个 ApprovalHook,挂到钩子链上。它对只读工具直接放行,对会话里已经放行的操作也直接放行,其余情况弹出审批卡片。
下一节我们分别说明第二步那个"会话级放行状态" PermissionState,看它到底记录了什么。
3.4 会话级放行状态 PermissionState
本篇涉及到的源码列表:
com.minicc.permission.PermissionState.java
com.minicc.session.Session.java
上一节我们讲审批逻辑时,有一步是"查询会话级放行状态,命中就不再询问"。这一节我们详细说明这个 PermissionState。
为什么需要"会话级放行"
我们先看一个场景:你让 Agent 运行测试,它要执行 mvn test。你放行了。它改了点代码,又要再执行一次 mvn test。
如果每一次同类操作都弹一张卡片,审批会过于频繁。你可能不再查看具体内容就直接选择允许,审批就起不到作用了。
所以我们需要一种机制,让你能一次性决定:"本会话里这类操作都放行,以后不用再询问。"这就是会话级放行。
它对应审批卡片的第二个选项,我们下一节会讲到。这一节我们先看承载这个状态的 PermissionState。
它记录两类信息
PermissionState 记录的是本会话内你主动放行过的范围。它只在本会话有效,退出就失效。
具体记录两类信息:文件修改的总开关,和已放行的 Bash 命令前缀。
// 源码位置:com.minicc.permission.PermissionState.java
public class PermissionState {
/** Edit/Write:会话是否进入"自动接受编辑"。 */
private volatile boolean acceptEdits = false;
/** Bash:本会话已放行的命令前缀(如 "mvn"、"git")。 */
private final Set<String> allowedBashPrefixes = ConcurrentHashMap.newKeySet();
// ...
}为什么文件修改用一个布尔开关,Bash 却要用一个集合?
因为文件修改的粒度比较粗:一旦放行,整个会话里的 Edit 和 Write 都放行,不区分是哪个文件。所以一个布尔 acceptEdits 就足够了。
Bash 则不一样。你放行 mvn 命令,不代表你愿意放行 rm 命令。所以我们按"命令前缀"分别记录,放行了 mvn 就只放行 mvn。
怎么查、怎么记
查询和记录是两个成对的方法。查询用 isGranted,判断这次调用本会话是否已经放行过。
// 源码位置:com.minicc.permission.PermissionState.java
/** 该工具调用本会话是否已被放行。 */
public boolean isGranted(AssistantMessage.ToolCall call, Tool tool) {
if (isFileEdit(tool)) { // Edit / Write
return acceptEdits;
}
if (isBash(tool)) { // Bash:按命令前缀判断
return allowedBashPrefixes.contains(bashPrefix(call));
}
return false;
}
/** 用户选了"本会话内不再询问同类"时记入放行。 */
public void grantSession(AssistantMessage.ToolCall call, Tool tool) {
if (isFileEdit(tool)) {
acceptEdits = true; // 整个会话的文件修改都放行
} else if (isBash(tool)) {
allowedBashPrefixes.add(bashPrefix(call)); // 该前缀的命令都放行
}
}逻辑很直白。Edit 和 Write 看 acceptEdits 这个开关;Bash 看命令前缀在不在已放行集合里。
记录时也一样,文件修改就把开关打开,Bash 就把这条命令的前缀加进集合。
命令前缀怎么取
上面反复提到"命令前缀",它是怎么算出来的?
我们做了一个很大的简化:命令前缀就取命令的第一个词。
// 源码位置:com.minicc.permission.PermissionState.java
/** 取命令前缀:简化为命令的第一个词(如 "mvn -q test" → "mvn")。 */
public String bashPrefix(AssistantMessage.ToolCall call) {
String cmd = ToolCallHelper.getString(call, "command", "").trim();
if (cmd.isEmpty()) {
return "";
}
int sp = cmd.indexOf(' ');
return sp < 0 ? cmd : cmd.substring(0, sp);
}于是 mvn -q test 和 mvn clean package 的前缀都是 mvn,放行了其中一个,另一个也不再询问。
这个简化是有代价的,这里需要说明一下。Claude Code 的命令前缀提取要做得严谨得多:它会走 AST 解析,把复合命令(a && b)分成多段逐段检查,剥离 env 变量,做一系列安全校验。
mini Claude Code 不做这些。我们只取第一个词,足够演示"放行一类、而不是每次都问"这个思想,不引入前缀提取的全部复杂度。
它和 WorkspaceState 是同一个套路
讲到这里,我们需要把一个设计要点说明白:PermissionState 的归属和传递方式,和 M2 的 WorkspaceState 完全一致。
一个会话一个实例,由 Session 持有。它的生命周期就等于会话的生命周期,/clear 的时候随新会话一起重建。
// 源码位置:com.minicc.session.Session.java
private PermissionState permissions = new PermissionState();
public PermissionState permissions() {
return permissions;
}然后在每一轮组装 ToolContext 的时候,从 Session 取出来下发给审批钩子。
这样做有两个好处。
第一,审批钩子保持无状态,不会在 /clear 之后读到上一个会话遗留的放行状态。
第二,它和"会话状态由 Session 持有、经 ToolContext 下发"这个既有模式对齐。我们没有为 M3 发明新的套路,而是复用了 M2 已经验证过的那一套。
一个重要提醒:放行不是安全边界
我们最后强调一点:会话级放行只是一种便利,它不是安全边界。
你放行了 mvn,不代表 mvn 命令就一定安全。真正危险的命令,仍然由 M2 的危险命令护栏在执行时兜底拦截,沙箱也会限制写入范围。
换句话说,审批、护栏、沙箱构成的是纵深防御。审批是最外层、由人来把关的那一道,护栏和沙箱是即使放行了也仍然生效的底线。
会话级放行减少的是每次都询问的次数,它不等于放行之后任何操作都可以执行。
下一节我们讲审批卡片本身:三个选项长什么样,又是怎么渲染出来的。
3.5 权限审批卡片:三个选项与渲染
本篇涉及到的源码列表:
com.minicc.permission.Approval.java
com.minicc.permission.Approver.java
com.minicc.cli.CliApprover.java
com.minicc.cli.CardPrompter.java
前面两节我们讲了审批逻辑和会话级放行状态。这一节我们看审批卡片本身:它给你哪三个选项,又是怎么在终端里渲染出来的。
三个选项的语义
审批卡片由 Approver 弹出,一共三个选项。我们先把每个选项的语义说清楚。
第一个,允许。 只放行当前这一次,下次同类操作仍然会再问你。对应 ALLOW_ONCE。
第二个,允许本会话内的同类操作。 本次放行,并且在当前会话里自动放行同类,记入上一节讲的 PermissionState。对应 ALLOW_SESSION。
这个选项的措辞会随工具类型变化,把放行范围写清楚:
- Edit、Write 的卡片写"允许,本会话内的所有文件修改不再询问"。
- Bash 的卡片写"允许,本会话内的所有某类命令不再询问",比如所有
mvn命令。
第三个,拒绝,并说明原因。 不执行这次操作,让你告诉 Agent 换一种做法。对应 REJECT,你填的原因会回填给模型。
这三个选项用一个 Approval 记录来表示。
// 源码位置:com.minicc.permission.Approval.java
public record Approval(Kind kind, String reason) {
/** 三个选项。 */
public enum Kind { ALLOW_ONCE, ALLOW_SESSION, REJECT }
// 三个静态工厂方法:allowOnce() / allowSession() / reject(reason)
}kind 是你选了哪一项,reason 只在拒绝时才有值,记录的是你填写的原因。
审批交互的抽象
弹卡片这件事,我们抽象成一个接口 Approver,只有一个方法。
// 源码位置:com.minicc.permission.Approver.java
public interface Approver {
/** 为一次有副作用的工具调用弹出审批卡片,返回用户的选择。 */
Approval requestApproval(AssistantMessage.ToolCall call, Tool tool, ToolContext ctx);
}为什么要抽象成接口?两个原因。
一是便于 ApprovalHook 在单元测试里注入一个假实现,不用真的弹卡片等人输入。
二是将来如果要换交互形态,比如从命令行换成图形界面,只需要修改实现,不需要修改钩子。
它的 CLI 实现叫 CliApprover,负责把一次工具调用组装成卡片的标题、预览和选项。
卡片长什么样
我们先看最终效果,再看怎么拼出来的。改一个文件时,卡片大致是这样:
变更预览:OrderController.java
- public void placeOrder(@RequestBody OrderRequest req) {
+ public void placeOrder(@RequestBody OrderRequest req) {
+ orderValidator.validate(req);
对 OrderController.java 应用此修改?
1. 允许
2. 允许,本会话内的所有文件修改不再询问
3. 拒绝,并说明原因
请选择 [1-3]:改文件前会给出一段 diff 预览,让你看清楚它到底要改什么。Bash 则展示将要执行的命令。
这段标题和预览由 CliApprover 根据工具类型拼出来。
// 源码位置:com.minicc.cli.CliApprover.java
@Override
public Approval requestApproval(AssistantMessage.ToolCall call, Tool tool, ToolContext ctx) {
List<String> options = List.of("允许", sessionOptionLabel(tool, call, ctx), "拒绝,并说明原因");
int idx = prompter.select(buildPreview(call, tool), buildTitle(call, tool), options);
if (idx < 0) { // Ctrl-C / Ctrl-D:取消整个任务
cancelToken.cancel();
return Approval.reject("用户取消了本次任务。");
}
if (idx == 0) {
return Approval.allowOnce();
}
if (idx == 1) {
return Approval.allowSession();
}
// idx == 2:拒绝并说明原因,再读一行作为原因。
String reason = prompter.readLine(" 拒绝原因(告诉 Agent 换个做法,直接回车可跳过)> ");
if (reason == null) { // Ctrl-C/Ctrl-D:也按取消处理
cancelToken.cancel();
return Approval.reject("用户取消了本次任务。");
}
reason = reason.strip();
return Approval.reject(reason.isEmpty() ? "用户拒绝了这次操作,未说明具体原因。" : reason);
}这段逻辑很直接:CliApprover 先拼好三个选项,再交给 CardPrompter 打印并等待用户输入选项,然后把编号翻译回 Approval。
你选了第三项,它会再读一行,把你填的原因装进 Approval.reject(reason)。
这里还有一个细节:如果 select 返回了 -1,说明你在卡片等待时按了 Ctrl-C。这时它置位取消信号,取消整个任务。这个和取消相关的行为,我们放到 3.7 再说明。
第二个选项的措辞怎么来的
第二个选项的文案是动态生成的,因为它要把放行范围写清楚。
// 源码位置:com.minicc.cli.CliApprover.java
/** "本会话内放行同类"选项的文案,按工具类型把放行范围写清楚。 */
private static String sessionOptionLabel(Tool tool, AssistantMessage.ToolCall call, ToolContext ctx) {
String name = tool.name();
if ("Bash".equals(name)) {
String prefix = ctx.permissions().bashPrefix(call);
return "允许,本会话内的所有 " + prefix + " 命令不再询问";
}
// Edit / Write 及其它写操作。
return "允许,本会话内的所有文件修改不再询问";
}Bash 会从 PermissionState 取出命令前缀,拼成"所有 mvn 命令不再询问"这样的文案。文件修改则统一写"所有文件修改不再询问"。
这样你在选第二项之前,就清楚自己到底放行了多大的范围。
为什么是输入编号,而不是方向键
卡片的交互是"输入编号后回车",不是用方向键上下选。这是一个有意的简化,我们解释一下原因。
方向键在终端里不是一个普通字符,而是 ESC [ A 这样的转义序列。要支持方向键,卡片就得自己解码这些序列,用 ANSI 转义码把光标移回去重绘,还要把终端切进 raw 模式。
这些机制和"审批"本身没有关系,实现量和阅读成本都很高。
输入编号就直接得多:CardPrompter 把选项打印出来,再读一行,解析成数字。代码读起来比较直接。
渲染和读入都集中在 CardPrompter 里,审批卡片和下一节要讲的提问卡片共用同一套组件,都是"标题 + 若干编号选项 + 读一行",只是选项内容不同。
// 源码位置:com.minicc.cli.CardPrompter.java
/** 单选。返回选中项的下标(从 0 起);用户取消时返回 -1。 */
public int select(List<String> preview, String title, List<String> options) {
printCard(preview, title, options);
String prompt = " 请选择 [1-" + options.size() + "]:";
while (true) {
String line = readLine(prompt);
if (line == null) {
return -1; // Ctrl-C / Ctrl-D
}
Integer index = parseSingle(line, options.size());
if (index != null) {
return index;
}
say(" 请输入 1 到 " + options.size() + " 之间的编号。");
}
}你输入的编号不合法,它会再问一次,直到拿到一个有效编号或者你按 Ctrl-C。
审批天然是串行的
还有一个性质:审批不会出现"同时弹两张卡片"的情况。
因为写操作在 M2 的 ToolScheduler 里本来就是串行执行的,而审批发生在工具执行之前。既然写操作一个接一个地执行,审批也就一张接一张地弹出。
只读工具可以并行,但它们不需要审批,所以不受影响。
渲染上也延续 M2 的约定:等调度器把一批结果按原始顺序收集齐之后,再成对打印"调用 + 结果";审批卡片则在各自工具执行前就地弹出。
下一节我们讲另一种卡片:AskUserQuestion。它和审批卡片长得像,但本质完全不同。
3.6 AskUserQuestion 工具的实现
本篇涉及到的源码列表:
com.minicc.ask.QuestionAsker.java
com.minicc.ask.Question.java
com.minicc.ask.Answer.java
com.minicc.tool.builtin.AskUserQuestionTool.java
com.minicc.cli.CliQuestionAsker.java
上一节的审批卡片,是 harness 在危险操作前强制弹出的。这一节的 AskUserQuestion,长得很像审批卡片,但它的用途完全不同。
我们先把这个区别讲清楚,这是 M3 要反复强调的一点。
它和审批卡片的根本区别
两张卡片看起来都是"给你几个选项、等你选",但发起方和解决的问题截然不同。
审批卡片由 harness 强制发起,在执行危险操作前弹出,解决的是"准不准这么做"。
AskUserQuestion 由模型主动调用,在需求不明确时弹出,解决的是"要不要这么做、或者怎么做"。
前者是运行时的一道权限关卡,模型无法跳过。后者是模型可以主动调用的一个普通工具,是否调用由模型自己判断。
举个例子你就明白了。你说"给用户密码加上加密存储",模型发现加密方案有好几种,它不确定你想用哪个,于是主动调用 AskUserQuestion 问你。这是提问。
而当模型决定用 BCrypt、要 Edit 改代码时,运行时强制弹出的那张"准不准改这个文件"的卡片,才是审批。
为什么用两个接口
正因为审批和提问是两件事,我们在代码里用了两个接口,而不是合成一个。
审批走 permission.Approver,方法是 requestApproval。提问走 ask.QuestionAsker,方法是 askQuestions。
// 源码位置:com.minicc.ask.QuestionAsker.java
public interface QuestionAsker {
/** 为模型发起的一组问题弹出选择卡片(自动补"其他"项),返回用户的回答。 */
List<Answer> askQuestions(List<Question> questions);
}两个接口各只有一个方法,各有各的 CLI 实现,只共用底层的 CardPrompter 来渲染卡片、读编号。
这样 AskUserQuestionTool 只依赖"提问",ApprovalHook 只依赖"审批"。
问题和回答的数据结构
模型发起提问时,要给出一个或多个问题。每个问题用 Question 表示。
// 源码位置:com.minicc.ask.Question.java
public record Question(String header, String question, List<Option> options, boolean multiSelect) {
public record Option(String label, String description) {
}
}几个字段的含义:
header:很短的标签,比如"加密方案""分页方式",不超过 12 个字。question:完整的问题文本,要清晰具体、以问号结尾。options:候选项,2 到 4 个。每项有一个简短的label和一段说明取舍的description。注意,模型不要自带"其他"选项,系统会自动补充。multiSelect:是否允许多选,默认不允许。
你的回答用 Answer 表示。一个问题对应一个 Answer,里面记下是哪一个问题,以及你选中的内容。
// 源码位置:com.minicc.ask.Answer.java
public record Answer(String header, String question, List<String> choices) {
}三个字段的含义:
header和question:原样记下对应问题的短标签和问题文本,回答回填给模型时能对上是哪一问。choices:你选定的内容,一项一条。单选时列表里只有一条,多选时有多条。选的是候选项,这里放的是它的label。选的是「其他」,这里放的是你自己补充的文字。
工具的关键声明
AskUserQuestion 就是注册进 ToolRegistry 的一个普通 Tool,走和其它工具完全一样的调用路径。它有两个声明特别关键。
// 源码位置:com.minicc.tool.builtin.AskUserQuestionTool.java
@Override
public boolean isReadOnly() {
return true; // 不碰文件/环境,无需审批
}
@Override
public boolean isConcurrencySafe() {
return false; // 要暂停循环、与用户交互,不能并行
}isReadOnly() 返回 true。它不修改文件,也不改变运行环境,所以在 ApprovalHook 那里会被直接放行,根本不需要审批。
isConcurrencySafe() 返回 false。它要暂停循环、和你交互,不能和别的工具并行执行。所以调度器会把它当作不可并行的工具,单独串行执行。
执行时做了什么
它的 execute 方法很短:解析出问题,交给 QuestionAsker 弹卡片等你作答,再把答案整理成一段文字回填给模型。
// 源码位置:com.minicc.tool.builtin.AskUserQuestionTool.java
@Override
public ToolResult execute(AssistantMessage.ToolCall call, ToolContext ctx) {
List<Question> questions;
try {
questions = parseQuestions(call);
} catch (IllegalArgumentException e) {
return ToolResult.error("AskUserQuestion 参数不合法:" + e.getMessage());
}
List<Answer> answers = asker.askQuestions(questions); // 弹卡片、等用户选(自动加"其他")
if (answers.isEmpty()) {
return ToolResult.ok("用户未作答(可能已取消)。请你先自行判断,或稍后再确认。");
}
return ToolResult.ok(formatAnswers(answers));
}这里有个稳健性细节:如果你在提问卡片上按了 Ctrl-C 取消,askQuestions 会返回空列表。工具不会崩,而是回填一句"用户未作答",让模型自行判断或稍后再确认。
给模型的说明
模型要在恰当的时候用这个工具,就得在工具描述里把用法讲清楚。这段描述很重要,我们摘录几条要点。
// 源码位置:com.minicc.tool.builtin.AskUserQuestionTool.java(description 摘录)
"""
在需求不明确、或存在多个都合理的实现方案时,主动向用户提问以收集偏好、澄清歧义、让其在方案间做选择,
而不是自行假设。用法:
- questions 为 1–4 个问题;每个问题含 question(完整问题,以问号结尾)、header(≤12 字的短标签)、
options(2–4 个候选项,每项含 label 简短选项与 description 取舍说明)。
- 不要自带"其他"选项,系统会自动补充一个让用户自由输入。
- 若你推荐某个选项,把它放在第一个,并在其 label 末尾标注 "(Recommended)"。
- multiSelect 为 true 时允许用户多选。
- 仅在确有必要时提问;能自行合理决定的小事不要打断用户。
"""最后一条尤其重要:能自行合理决定的小事,不要频繁打断你。提问是用来澄清真正的分歧的,不是让模型事事都来请示。
"其他"选项是系统自动补的
你注意到上面反复说"系统会自动补充一个'其他'项"。这件事在 CLI 实现里完成。
// 源码位置:com.minicc.cli.CliQuestionAsker.java(节选)
List<String> labels = new ArrayList<>();
for (Question.Option o : q.options()) {
String desc = (o.description() == null || o.description().isBlank())
? "" : " — " + o.description();
labels.add(o.label() + desc);
}
int otherIndex = labels.size();
labels.add("其他(我来补充)");它把模型给的候选项逐个排上,再在最后追加一个"其他(我来补充)"。
如果你选了"其他",它会再读一行,把你补充的自由文本写入回答。这样即使模型给的几个选项你都不满意,也总有一条退路。
一次提问的样子
把上面这些步骤连起来,一次提问在终端里大致是这样:
> 给用户密码加上加密存储
这个改动有几种常见做法,想先跟你确认一下
选择:加密方案
1. BCrypt (Recommended) — Spring Security 自带,开箱即用
2. Argon2 — 更强,但需要额外依赖
3. PBKDF2 — 标准库支持
4. 其他(我来补充)
请选择 [1-4]:1
好的,使用 BCrypt。继续…模型给了三个方案并把推荐项放在第一个,系统再补充上第四项"其他"。你选了 1,答案回填给模型,循环继续。
下一节我们讲 M3 的第三把控制阀:Ctrl-C 中途取消。
3.7 Ctrl-C 中途取消:协作式取消与 CancelToken
本篇涉及到的源码列表:
com.minicc.agent.CancelToken.java
com.minicc.cli.Repl.java
com.minicc.cli.CardPrompter.java
com.minicc.cli.CliApprover.java
com.minicc.cli.CliQuestionAsker.java
前面几节我们讲的是审批和提问。这一节我们讲 M3 的第三把控制阀:你随时能按 Ctrl-C 打断 Agent。
取消是"协作式"的,不是强制终止
我们先说清楚一个关键的取舍:收到取消请求时,我们不是立刻强制中断。
如果 Agent 正在写一个文件,写到一半被强制终止,就可能留下一个不完整的文件。这不是我们想要的结果。
所以取消是"协作式"的:我们在一些安全位置停下。只读操作可以立即中断,正在进行的写操作会先完成当前这一步原子动作,保证不留下损坏的中间状态。
取消之后,工作状态全部保留:会话历史在、待办在、已经写入的改动也在。你可以调整需求,让它继续执行。
要做到这点,取消就不能是一个强制中断,而必须是一个信号,由各处主动去检查。
取消信号 CancelToken
这个信号我们用一个很简单的对象实现:一个 volatile 的布尔标志位。
// 源码位置:com.minicc.agent.CancelToken.java
public class CancelToken {
private volatile boolean cancelled = false;
/** Repl 装的 Ctrl-C 处理函数在用户按下时调用,置位取消信号。 */
public void cancel() {
cancelled = true;
}
/** 各安全检查点查询是否已被取消。 */
public boolean isCancelled() {
return cancelled;
}
/** 每次新任务开始前复位:上一条输入的取消不应影响下一条。 */
public void reset() {
cancelled = false;
}
}它的作用相当于别的框架里的"取消令牌"或"中断信号",但我们用最简单的方式实现。
为什么字段要用 volatile?因为置位发生在一个线程(JLine 的信号处理线程),查询发生在另一些线程(循环线程、工具线程)。volatile 保证一个线程的修改对其它线程立即可见。
reset() 也值得我们说明一下:每次新任务开始前要复位,否则上一条输入的取消会影响到下一条。
它作为字段加进 ToolContext,也就是 M1 早就预告过的那个扩展位。这样工具在执行过程中就能查询到它。
关键选择:为什么用 Ctrl-C,而不是 Esc
这里有一个很重要的设计选择:取消信号用 Ctrl-C,而不是像 Claude Code 那样用 Esc。
为什么不用 Esc?因为 Esc 是输入流里的一个字节。要在 Agent 执行期间认出它,就得开一个后台线程,把终端切到 raw 模式去逐字节读。
而且这个后台线程还要和卡片的读入抢同一个输入流:卡片弹出时得先暂停监听、恢复行模式,卡片结束之后再切换回去。
这些机制和"取消"本身没有关系,却是读代码时最不容易读懂的地方。
Ctrl-C 则完全不同。它在终端里不是一个字符,而是操作系统内核直接发给进程的 SIGINT 信号。
JLine 已经提供了接收这个信号的办法,我们只要在任务执行期间安装一个处理函数,按下就置位 CancelToken。
Repl 怎么安装、怎么还原
负责安装这个处理函数的是 Repl。它在执行一轮任务之前先安装上,任务结束后还原。
// 源码位置:com.minicc.cli.Repl.java
private void runTask() {
cancelToken.reset();
// 装 SIGINT 处理函数:按 Ctrl-C 就置位取消信号,循环在安全检查点停下。
Terminal.SignalHandler previous = terminal.handle(Terminal.Signal.INT, s -> cancelToken.cancel());
try {
agentLoop.run(session);
} finally {
// 还原:回到 > 后,Ctrl-C 交给外层 readLine,结束会话。
terminal.handle(Terminal.Signal.INT, previous);
}
}逻辑就三步:先复位信号,再装处理函数,任务结束后在 finally 里还原。
这个 finally 里的还原是不能省略的,它关系到 Ctrl-C 在不同时刻的含义,我们马上来讲一下。
这样做之后,后台监听线程、raw 模式、逐字节读取、方向键解析都不再需要。
卡片等输入时按 Ctrl-C 呢
还有一种情况:审批卡片或提问卡片正弹着、等你输入编号时,你按了 Ctrl-C,会怎么样?
这时 JLine 的 readLine 会临时接管 Ctrl-C,抛出一个中断异常。CardPrompter 据此返回"取消",上层的 CliApprover 或 CliQuestionAsker 再置位 CancelToken。
我们回看上一节审批的代码就能印证这一点:
// 源码位置:com.minicc.cli.CliApprover.java(节选)
int idx = prompter.select(buildPreview(call, tool), buildTitle(call, tool), options);
if (idx < 0) { // Ctrl-C / Ctrl-D:取消整个任务
cancelToken.cancel();
return Approval.reject("用户取消了本次任务。");
}readLine 读完会自动还原到 Repl 安装的那个信号处理函数。所以不管是执行期间还是卡片等待期间,按 Ctrl-C 的结果都是"取消当前任务"。
Ctrl-C 在三个时刻含义不同
把上面这些情况合在一起看,Ctrl-C 在三个不同的时刻,含义是不一样的。
| 时刻 | 效果 |
|---|---|
在 > 等待下一条用户消息 | 结束会话、退出程序,和 /exit 相同 |
| 任务执行中(等模型、执行工具) | 取消当前任务:置位信号,循环在安全检查点停下,回到 >,程序不退出 |
| 审批 / 提问卡片正在等编号 | 取消当前任务(不是退出程序,也不等于卡片上的某一项) |
现在你就明白为什么 finally 里的还原不能省略了。
任务期间,Ctrl-C 被我们安装的处理函数接走,用来取消任务。任务一结束就还原,于是回到 > 时,Ctrl-C 重新交给外层的 readLine,含义变回"结束会话"。
如果不还原,回到提示符后按 Ctrl-C 还会走任务期的取消逻辑,那就不对了。
一个重要澄清:取消不等于拒绝
最后澄清一个容易混淆的点:卡片正弹着时按 Ctrl-C,取消的是整个任务,而不是卡片上的"拒绝"那一项。
这两者是不同的。
取消任务:这次待执行的操作不会执行,循环直接停下,回到 >。
拒绝这次操作:你要输入编号 3、填写原因。这时任务不会停止,模型会收到你的拒绝原因,换一种做法继续执行。
这一节我们建立了取消的机制:一个简单的信号 CancelToken,由 Ctrl-C 置位,各处主动查询。
但"各处"到底是哪些地方?它们各自怎么响应?取消之后停止的语义又是什么?这些我们留到下一节来详细讲一下。
3.8 取消信号从哪来、各处怎么响应、取消后的停止
本篇涉及到的源码列表:
com.minicc.agent.CancelToken.java
com.minicc.cli.Repl.java
com.minicc.cli.CliApprover.java
com.minicc.cli.CliQuestionAsker.java
com.minicc.agent.AgentLoop.java
com.minicc.agent.ToolScheduler.java
com.minicc.tool.bash.CommandRunner.java
com.minicc.cli.Renderer.java
com.minicc.tool.ToolResult.java
上一节我们建立了取消的机制:一个简单的 CancelToken,由 Ctrl-C 置位。这一节我们把这条链路说明完:信号从哪里来,各处怎么响应,取消之后停在什么位置、呈现什么结果。
信号从哪来:一处置位
我们先回顾一下置位这一侧,上一节我们已经讲过了,这里可以概括为:
信号只有一个来源:你按 Ctrl-C。Repl 在任务期间装的 SIGINT 处理函数会调用 cancelToken.cancel(),把标志位置为 true。
卡片等待输入时按 Ctrl-C 也是同一种处理:CliApprover 或 CliQuestionAsker 收到取消后,同样调用 cancelToken.cancel()。
置位是一处,查询却分散在多处。接下来我们逐个看这些"安全检查点"。
检查点一:AgentLoop
控制循环是最主要的检查点。它在两个地方检查取消:循环顶部,以及模型返回后、派发工具前。
// 源码位置:com.minicc.agent.AgentLoop.java(节选)
while (true) {
// 检查点①:循环顶部查取消信号。命中则安全停下、保留会话状态。
if (isCancelled()) {
renderer.interrupted();
return;
}
// ... 边界检查、调模型、拿到本轮assistant消息 ...
// 检查点②:模型返回后、派发工具前再查一次取消。
if (isCancelled() && calls.isEmpty()) {
renderer.interrupted();
return;
}
// ... 有工具调用则交给调度器执行 ...
}检查点一在循环顶部。上一轮工具执行期间如果发生了取消,这一轮一开头就会被它捕获,直接停下。
检查点二在模型返回之后。这里的判断需要单独说明。
检查点二为什么要判断 calls 是否为空
你注意到检查点二的条件是 isCancelled() && calls.isEmpty(),多了一个"本轮没有工具调用"的判断。为什么?
因为会话历史有一个合法性要求:assistant消息里的每一个工具调用,都必须有一条对应的工具响应。
如果模型这一轮返回了工具调用,我们却在这里直接 return,那这些工具调用就没有对应的响应,会话历史就残缺了。取消之后你想继续对话时,请求体会不完整。
所以这里的处理很讲究:
- 如果本轮不含工具调用,历史本来就完整,直接停下即可。
- 如果本轮含工具调用,就不在这里停,而是交给调度器。调度器发现已取消后,会把这批调用全部标记成"未执行"并回填,保证每个调用都有响应。随后由下一轮顶部的检查点一停下。
这个细节体现了协作式取消的严谨:我们宁可多走一步,也要保证会话历史始终合法。
检查点三:ToolScheduler
调度器在派发工具时响应取消。它的策略是:已取消就不再派发后续工具。
// 源码位置:com.minicc.agent.ToolScheduler.java(节选)
public List<ToolResult> execute(List<AssistantMessage.ToolCall> calls, ToolContext ctx) {
ToolResult[] results = new ToolResult[calls.size()];
int i = 0;
while (i < calls.size()) {
// 取消检查点:已取消则不再派发,剩余调用留空。
if (isCancelled(ctx)) {
break;
}
// ... 并行执行一批只读工具,或串行执行一个写操作 ...
}
// 把因取消而未派发的尾部调用填成"已取消",保证结果与 calls 一一对应。
for (int k = 0; k < results.length; k++) {
if (results[k] == null) {
results[k] = ToolResult.cancelled();
}
}
return List.of(results);
}它在执行每个工具(或每一批并行工具)之前检查一次取消。一旦取消,就 break,不再派发后面的调用。
然后它把没来得及执行的调用,统统填成"已取消"的结果。这正是上面说的"保证每个调用都有响应"。
对已经在并行执行的只读工具,取消后不强制终止。它们很快就结束了,我们不打断它们,只是不再启动新的。
检查点四:CommandRunner
Bash 是唯一可能长时间运行的工具,所以它要单独响应取消,否则一个 sleep 30 就能让取消等上半天。
// 源码位置:com.minicc.tool.bash.CommandRunner.java(节选)
while (!p.waitFor(POLL_MS, TimeUnit.MILLISECONDS)) {
if (cancelToken != null && cancelToken.isCancelled()) {
p.destroyForcibly(); // 取消:中止子进程树
reader.join(1000);
return ToolResult.error("命令已被用户中断(Ctrl-C):" + command
+ "\n" + truncate(snapshot(out)));
}
if (System.currentTimeMillis() >= deadline) {
p.destroyForcibly(); // 超时:同一条中止路径
// ...
}
}它在等待子进程的时候,用短间隔轮询,同时盯着两件事:超时和取消。
一旦发现取消,就调用 destroyForcibly() 中止整个子进程树。这里复用的正是 M2 超时中止的那条路径,没有另外实现一套逻辑。
至于 Read、Grep、Glob 这类只读工具,执行很快,我们不单独为它们增加检查点,由循环层面的检查点处理即可。
取消后的停止语义
把这些检查点放在一起,取消之后的停止语义就清楚了。我们逐条说明。
只读操作立即停下。 循环不再派发新的只读调用,已经开始执行的那些调用很快就会结束。
写操作停在原子边界。 Edit、Write 的"读文本、替换、写回"本身很快,取消要么发生在它开始前(那就直接不执行),要么它已经完成这一步写入(那就不会把文件写成不完整的状态)。Bash 正在执行的话,子进程会被中止。
已应用的改动保留。 此前每一次修改你都在审批卡片上确认过,已经写入的改动留在工作区里,可以用 git 查看或回退。
工作状态保留。 会话历史和待办都在,你可以调整需求后让它继续执行。
终端只提示一行。 和 Claude Code 一致,取消后只简短地打印一行。
// 源码位置:com.minicc.cli.Renderer.java
public void interrupted() {
System.out.println(dim(BRANCH + "Interrupted by user(已中断)"));
System.out.println();
}取消不是错误
有一个语义上的区分,我们要特别说明一下:取消不是错误。
你看调度器填的那个"已取消"结果,它的 error 标志是 false,不是错误观察。
// 源码位置:com.minicc.tool.ToolResult.java
public static ToolResult cancelled() {
return new ToolResult("已被用户中断(Ctrl-C),未执行。", false);
}为什么要强调这点?因为我们在 M2 建立过一个原则:工具的错误会作为观察回填,让模型自行纠正。
但取消不该触发模型"纠正"。你取消任务,是想停下来、调整方向,不是报告一个让模型去修正的错误。所以取消只是让循环安全停下,等你的新指令,并不把它当错误回填给模型。
这和"被拒绝"也不一样。被拒绝会带着原因回填给模型(让它换一种做法),而被取消只是停下。
关于取消在途的模型请求
最后说一个我们做了简化的地方:如果 Ctrl-C 恰好发生在等待模型响应的网络请求期间,会怎么样?
M3 的做法是:等这个请求返回后,在检查点二停下。我们不去强行打断在途的 HTTP 请求。
为什么这么简化?因为打断在途请求的实现成本不低,收益却有限。等一个请求返回通常也就一两秒,用户感知不强。这是一个合理的取舍。
小结
这一节我们把取消这条线走完了。
信号从一处来(Ctrl-C 置位),在多处被查询(循环的两个检查点、调度器、Bash)。
停止是协作式的:只读操作立即停止,写操作停在原子边界,已应用的改动和工作状态都保留。
取消不是错误,也不是拒绝,它只是让循环安全地停下来,等你的下一步。
到这里,这三把控制阀我们就全部讲完了:写操作先审批、Ctrl-C 能安全打断、模型能主动提问。mini Claude Code 第一次有了完整的人机协作闭环。
下一章我们进入 M4,让会话能持久化、能从中断处恢复。
