第 2 章 · M2 能改代码的编程 Agent
第 2 章 · M2 能改代码的编程 Agent
- 2.1 M2 功能说明:改文件、跑命令、记待办
- 2.2 M2 总体架构:包结构与组件协作
- 2.3 写操作的公共约定:改前必须先读
- 2.4 实现 Edit 与 Write 工具
- 2.5 实现 Bash(命令执行)工具
- 2.6 实现 TodoWrite 与工作状态
- 2.7 只读并行、写操作串行的调度
- 2.8 沙箱设计:危险命令护栏 + OS 沙箱(可降级)
2.1 M2 功能说明:改文件、跑命令、记待办
本篇涉及到的源码列表:
com.minicc.tool.builtin.EditTool.java
com.minicc.tool.builtin.WriteTool.java
com.minicc.tool.builtin.BashTool.java
com.minicc.tool.builtin.TodoWriteTool.java
com.minicc.agent.ToolScheduler.java
com.minicc.session.WorkspaceState.java
com.minicc.tool.bash.CommandGuard.java
com.minicc.cli.Renderer.java
M1 我们做完了,它是一个能读代码、能回答问题的助手。但它只能读取和回答,还不能修改代码,也不能执行命令。
从这一章开始,我们进入第二个里程碑 M2,目标是让它从"只会读和答"变成"能真正修改代码、执行命令"。
这一版交付什么
M1 交付的是一个代码问答助手,只能读、只能答。M2 要把它变成一个能真正完成编码任务的 Agent。
我们的做法是在 M1 的只读工具之上,加入三个有副作用的工具和一个待办工具:
- Edit:对已有文件做精确的字符串替换式修改。
- Write:新建文件,或者整体覆盖写入。
- Bash:在沙箱里运行命令,比如编译、测试、git 操作。
- TodoWrite:维护本次任务的待办清单,跟踪多步任务的进度。
除了这四个工具,我们还要在调度上做一次升级。M1 对一轮里的多个工具调用是顺序逐个执行的,M2 把它升级成只读并行、写操作串行。
这一版完成后,它就能处理真实的小型编码任务了:读取代码、修改代码、运行测试、查看结果、继续修改。
这一点值得我们单独强调一下。配合 Bash 运行测试,模型会根据测试的输出自我修正,这就是我们在课程里讲过的 Reflection(反思)。
Reflection 不需要我们写任何额外的代码。它是模型在"改、测、看、再改"这个循环里自然表现出来的行为,我们要做的只是把 Bash 这个能拿到客观反馈的工具交给它。
一个重要的安全前提
M2 有一个必须先说清楚的前提:它的写操作工具(Edit、Write、Bash)会直接执行,没有人工审批。
审批卡片、中断取消、AskUserQuestion 这些人工介入的手段,都是 M3 的内容,M2 还没有。
因此在 M2 这个阶段,我们建议你只在用 git 跟踪、可以随时回退的项目上使用它。万一它改坏了什么,一条 git checkout 就能还原回来。
这个取舍是我们刻意做的。目的是让 M2 聚焦在"工具怎么实现、怎么调度",把"怎么做人工控制"这件事留给 M3 单独讲清楚。
命令行里分别是什么样
符号和上一章一样:行首的 ⏺ 是一步动作,⎿ 是这一步的结果。M2 的写操作直接执行,终端上紧接着就是调用和结果。
参数超过大约 120 个字符时,终端会截断。下面 Edit、Write、TodoWrite 的参数我们做了省略。工具结果仍然只显示前 6 行。
修改已有文件
它会先 Read,再 Edit。Edit 的结果写明替换了几处、增加和删除了多少行,并附上改动附近的几行。
> 给 OrderController 的 placeOrder 加一行日志
⏺ 先读一下 placeOrder 的现状
⏺ 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 行)
⏺ 在方法入口补一条日志
⏺ 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 log.info("place order");
51 orderService.placeOrder(req.toOrder());如果还没读过这个文件就直接改,Edit 会返回一条错误结果,文件保持原样。
⏺ Edit(file_path=/Users/wangzheng/codecrush/src/main/java/OrderController.java, old_string=...)
⎿ 修改前请先用 Read 读取该文件:/Users/wangzheng/codecrush/src/main/java/OrderController.java新建文件,以及运行命令
Write 用来新建文件。父目录不存在时,它会一并建好。覆盖已有文件时,这行结果会写成「已覆盖」,并且同样要求先 Read。
⏺ Write(file_path=/Users/wangzheng/codecrush/src/test/java/OrderIdempotencyTest.java, content=...)
⎿ 已新建 /Users/wangzheng/codecrush/src/test/java/OrderIdempotencyTest.java(28 行,860 字节)Bash 把命令的输出打出来,并在末尾补上退出码。测试输出往往很长,下面只保留能看出成败的两行。
⏺ Bash(command=mvn -q -Dtest=OrderControllerTest test, description=运行下单接口测试)
⎿ [ERROR] Tests run: 4, Failures: 1
[exit code: 1]退出码不是 0 时,这段输出会作为错误观察回到模型。模型可以再改一次代码,然后重新运行测试。终端上就是「改完、跑测试、看到失败、再改」这样来回出现,这就是前面说的 Reflection。
明显危险的命令会被护栏拦住,终端只留下拒绝原因。
⏺ Bash(command=sudo mvn test)
⎿ 该命令被安全护栏拦截,拒绝执行:sudo mvn test待办清单
多步任务里,模型会调用 TodoWrite 维护一份清单。回填给模型的是一行计数,终端上另外打出勾选列表。
☑ 是已完成,▶ 是正在做的那一项,用的是进行时的说法,☐ 是还没开始。任意时刻最多一项处于进行中。
⏺ 这个任务分几步,先记一份待办
⏺ TodoWrite(todos=[...])
⎿ 已更新 4 项待办:1 完成 / 1 进行中 / 2 待办;当前:为 placeOrder 增加参数校验
☑ 阅读 OrderController 的现状
▶ 为 placeOrder 增加参数校验
☐ 补一条非法数量的测试
☐ 运行测试确认通过只读一起做,写操作一个个做
一轮里如果要同时读两个文件,它们一起执行,全部结束后按原来的顺序成对打印。Edit、Write、Bash 则做完一个,再做下一个。
⏺ 对照一下 Controller 和 Service
⏺ 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 行)
⏺ Read(file_path=/Users/wangzheng/codecrush/src/main/java/OrderService.java)
⎿ 1 package com.example;
2
3 public class OrderService {
4
5 public void placeOrder(Order order) {
6 orderRepository.save(order);
…(共 80 行)本章的学习路线
接下来的七节,我们把上面这些能力一块块落实到代码里:
- 2.2 我们先来讲总体架构,看一下包是怎么组织的,以及一次"改代码"的任务是怎么在组件之间流动的。
- 2.3 我们讲写操作的一条公共约定:改前必须先读。
- 2.4 我们实现 Edit 与 Write 这两个文件写操作工具。
- 2.5 我们实现 Bash,让 Agent 能真正执行命令。
- 2.6 我们讲 TodoWrite 与工作状态,让多步任务不遗漏步骤、不偏离目标。
- 2.7 我们讲只读并行、写操作串行的调度。
- 2.8 我们讲沙箱设计:危险命令护栏加上可降级的 OS 沙箱,以及
sandbox、bashTimeoutMs这两个配置。
读完这一章,你就有一个能真正帮你修改代码、运行测试的 Agent 了。
2.2 M2 总体架构:包结构与组件协作
本篇涉及到的源码列表:
com.minicc.agent.AgentLoop.java
com.minicc.agent.ToolScheduler.java
com.minicc.tool.ToolContext.java
com.minicc.tool.bash.CommandRunner.java
com.minicc.tool.bash.Sandbox.java
com.minicc.tool.bash.CommandGuard.java
com.minicc.tool.builtin.ReadTool.java
com.minicc.tool.builtin.EditTool.java
com.minicc.tool.builtin.WriteTool.java
com.minicc.tool.builtin.BashTool.java
com.minicc.tool.builtin.TodoWriteTool.java
com.minicc.session.Session.java
com.minicc.session.WorkspaceState.java
com.minicc.session.TodoItem.java
com.minicc.session.TodoList.java
com.minicc.cli.Renderer.java
com.minicc.config.MccConfig.java
com.minicc.config.ConfigLoader.java
上一节我们把 M2 要做什么讲清楚了。这一节我们来看它的整体骨架:包怎么组织、一次"改代码"的任务怎么在各个组件之间流动。
你先掌握这张结构图,后面几节逐个讲每个组件时,你就知道它在整体里处在什么位置。
包结构的增量
M2 是建在 M1 之上的,所以我们重点看它相对 M1 新增和改动的部分。下面这张图里,带注释的就是 M2 修改过的地方:
mini-claude-code/
├─ src/main/java/com/minicc/
│ ├─ agent/
│ │ ├─ AgentLoop.java // 改:工具执行处改为调用 ToolScheduler
│ │ └─ ToolScheduler.java // 新:只读并行、写操作串行的调度
│ ├─ tool/
│ │ ├─ ToolContext.java // 改:扩展 WorkspaceState / 沙箱开关 / 超时
│ │ ├─ bash/
│ │ │ ├─ CommandRunner.java // 新:子进程执行命令、捕获输出与退出码、超时
│ │ │ ├─ Sandbox.java // 新:把命令包进 OS 沙箱,可降级
│ │ │ └─ CommandGuard.java // 新:危险命令护栏
│ │ └─ builtin/
│ │ ├─ ReadTool.java // 改:读成功后向 WorkspaceState 登记
│ │ ├─ EditTool.java // 新
│ │ ├─ WriteTool.java // 新
│ │ ├─ BashTool.java // 新
│ │ └─ TodoWriteTool.java // 新
│ ├─ session/
│ │ ├─ Session.java // 改:持有 WorkspaceState 与 TodoList
│ │ ├─ WorkspaceState.java // 新:记录本会话读过哪些文件
│ │ ├─ TodoItem.java // 新:一条待办
│ │ └─ TodoList.java // 新:待办集合
│ ├─ cli/
│ │ └─ Renderer.java // 改:新增待办清单、改动摘要的渲染
│ └─ config/
│ ├─ MccConfig.java // 改:新增 sandbox / bashTimeoutMs
│ └─ ConfigLoader.java // 改:读取新字段我们可以把这些改动归成几类。
一类是新的工具,都放在 tool/builtin 下,和 M1 的三个只读工具并列。
一类是Bash 的执行机制,单独建了一个 tool/bash 子包,把命令执行、沙箱、护栏这三部分集中放在一起。
一类是新的会话状态,放在 session 下:工作区状态和待办清单,它们都挂到 Session 上。
还有一类是调度器 ToolScheduler,放在 agent 下,和控制循环做邻居。
剩下的 ToolContext、AgentLoop、ReadTool、配置、渲染器,都只是小幅改动。
一次"改代码"的任务是怎么流动的
我们只看包结构还不够,关键是要理解一次任务如何在这些组件之间流转。我们用一个具体例子来看:让它"给某个接口加校验并运行测试"。
第一步,Repl 读到用户的需求,把它追加为一条用户消息,然后调用 AgentLoop.run()。这一步和 M1 完全一样。
第二步,AgentLoop 进入循环。 每一轮它先调模型,拿到这一轮的assistant消息。
如果这条消息不含工具调用,说明是最终答复,循环结束。
如果含工具调用,就不再像 M1 那样逐个顺序执行,而是整批交给 ToolScheduler。调度器把这一轮的多个调用按并发标记分组,只读的并行执行、写操作串行执行,结果再按原始顺序回填为观察。
第三步,每个工具执行时,都会拿到一个 ToolContext。 M2 的 ToolContext 比 M1 丰富了:它现在带上了 WorkspaceState,供 Edit 和 Write 做"改前先读"校验;也带上了沙箱配置,供 Bash 使用。
各个工具在这一轮里各自做什么
我们具体看一下这一轮里几个工具是怎么配合的。
Read 读取成功之后,往 WorkspaceState 里登记一笔"这个文件读过了"。
Edit 和 Write 在执行前,先检查 WorkspaceState。如果目标文件还没读过,它们直接返回一条错误观察,让模型先去 Read。
Bash 把命令交给 CommandRunner。后者先经过 CommandGuard 护栏检查,再按配置决定要不要把命令包进 Sandbox,然后执行、捕获输出和退出码,超时就中止。
TodoWrite 更新 Session 里的 TodoList,并把当前清单作为观察回填,Renderer 再把它渲染成一份勾选列表给人看。
整个过程里,HookChain(执行前钩子链)仍然是一条空链。审批要到 M3 才挂上去,所以 M2 的写操作是直接放行、直接执行的。
M2 要复用的 M1 扩展点
M2 其实是对一条设计原则的第一次检验,那就是"后续里程碑只新增、少改动既有代码"。
M1 当初预留的扩展点,这一章就要开始用上了。M2 主要做三件事:
第一件,向 ToolRegistry 新增工具。 Edit、Write、Bash、TodoWrite 都只是实现一下 Tool 接口再注册进去,分发逻辑一行都不需要修改。
第二件,在工具执行处补上并行与串行的调度。 这是 M1 文档里早就预告过的:把顺序执行的那段 for 循环,替换成按工具的并发标记分组执行,控制循环的其余结构不变。
第三件,按 M1 预留的方式扩展 ToolContext。 M1 的 ToolContext 注释里就写明了后续会在这里扩展取消信号、沙箱配置等。M2 给它加上"读过哪些文件"的记录和沙箱开关。
小结
M2 的架构可以概括为:在 M1 的控制循环里,把"顺序执行工具"这一段替换成 ToolScheduler 的"只读并行、写操作串行",并通过扩展后的 ToolContext 把工作区状态和沙箱配置下发给新工具。
接下来的几节,我们就逐个把这些组件落到代码里。下一节先讲一条贯穿所有写操作的公共约定:改前必须先读。
2.3 写操作的公共约定:改前必须先读
本篇涉及到的源码列表:
com.minicc.session.WorkspaceState.java
com.minicc.tool.builtin.ReadTool.java
com.minicc.tool.builtin.EditTool.java
com.minicc.tool.builtin.WriteTool.java
com.minicc.session.Session.java
com.minicc.tool.ToolContext.java
在开始实现 Edit 和 Write 之前,我们要先讲一条贯穿这两个工具的公共约定:修改一个已有文件之前,必须在本次会话里先 Read 过它。
这条约定不是可有可无的小细节,它直接决定了写操作是否可靠,所以我们单独用一节来讲清楚。
为什么要"改前先读"
你可以设想一下:如果不加这条约束,模型凭着自己的"记忆"就去改文件,会发生什么?
模型并不能真正记住一个文件此刻的确切内容。它可能记得某个方法大概长什么样,但缩进、空行、上一次别人改过的地方,它都未必清楚。
基于一个模糊的印象去修改代码,结果往往是改错位置,或者引入一批语法错误。
所以这条约定的第一个意义是:促使模型基于文件的真实内容来构造修改,而不是凭记忆随意修改。
第二个意义和我们的 Edit 实现方式有关。Edit 用的是精确的字符串替换,模型要给出一段 old_string,这段文本必须和文件里的内容一模一样,连缩进都不能差。
要拿到准确的缩进和上下文,模型就必须先读一遍文件原文。模型先读取文件,才能修改得准确。
用一个会话级的 WorkspaceState 来落地
这条约定怎么在代码里实现呢?我们的做法很简单:用一个会话级的对象,专门记录"本次会话读过哪些文件"。
这个对象就是 WorkspaceState。Read 成功读取一个文件后,往里面登记这个路径;Edit 和 Write 执行前,先检查这个路径有没有被登记过。
它的实现只有两个核心方法:
// 源码位置:com.minicc.session.WorkspaceState.java
public class WorkspaceState {
// 只读工具可以并行执行,所以这里用线程安全的集合
private final Set<Path> readFiles = ConcurrentHashMap.newKeySet();
/** 登记一个已读文件(Read 成功后调用)。 */
public void markRead(Path file) {
readFiles.add(normalize(file));
}
/** 这个文件本会话是否被 Read 过。 */
public boolean hasRead(Path file) {
return readFiles.contains(normalize(file));
}
// 统一规整为绝对路径,避免相对路径和绝对路径对不上
private static Path normalize(Path file) {
return file.toAbsolutePath().normalize();
}
}这里有两个小细节值得我们留意。
一是路径的规整。模型给的路径可能是各种写法,所以登记和查询时都统一转成规范化的绝对路径,否则同一个文件可能因为写法不同而被判成"没读过"。
二是用了线程安全的集合。因为只读工具(包括 Read)在 M2 里是可以并行执行的,多个 Read 可能同时往这里登记,所以要用 ConcurrentHashMap.newKeySet() 这种线程安全的集合。这一点我们在 2.7 讲调度时还会再讲到。
三处改动把这条约定串起来
要让这条约定生效,我们只需要在三个地方修改代码。
第一处,Read 成功后登记。 这是对 M1 的 ReadTool 唯一的改动,我们只补充一行调用:
// 源码位置:com.minicc.tool.builtin.ReadTool.java
// ReadTool 成功读取文件后:
ctx.workspace().markRead(path);第二处,Edit 执行前检查。 如果这个文件没有登记过,Edit 就直接返回一条错误观察,不执行修改:
// 源码位置:com.minicc.tool.builtin.EditTool.java
if (!ctx.workspace().hasRead(path)) {
return ToolResult.error("修改前请先用 Read 读取该文件:" + filePath);
}第三处,Write 执行前检查。 Write 稍有不同:只有当目标文件已经存在时才要求先读,因为新建一个文件本来就没什么可读的。
// 源码位置:com.minicc.tool.builtin.WriteTool.java
boolean existed = Files.exists(path);
// 覆盖已有文件前必须先读过它;新建文件则不需要
if (existed && !ctx.workspace().hasRead(path)) {
return ToolResult.error("覆盖已有文件前请先用 Read 读取它:" + filePath);
}这三处合起来,就形成了一个完整的闭环:读过的文件才能修改,没读过的会被拒绝并提示先读。
为什么把 WorkspaceState 挂在会话上
你可能会问,这个状态为什么是"会话级"的,而不是每次调用临时建一个?
因为"改前先读"是一个跨多轮的约束。模型可能在第二轮读了文件,第五轮才去改它,中间隔了好几轮对话。
所以这个"读过哪些文件"的记录,必须和整场会话同寿命。我们把 WorkspaceState 挂在 Session 上,再通过 ToolContext 下发给每个工具,它就能贯穿整场会话。
错误不是终点,而是一次提示
最后要强调的是,"改前没读"这件事,我们处理成一条普通的错误观察,而不是抛异常中断循环。
这延续了 M1 就已经确定下来的原则:工具的错误作为观察回传,让模型自己纠正。
模型收到"请先 Read"这条提示后,通常会补一次 Read,再重新发起修改。整个过程不需要我们额外干预,循环就能继续进行下去。
一个进阶的话题
更完整的实现,其实还会记录文件读取时的内容和修改时间。这样它甚至能检测出"你读完之后,这个文件又被外部改动过"的情况,从而避免覆盖掉别人的改动。
我们的 WorkspaceState 只记录"读过还是没读过",不记录内容和时间。这对我们当前要做的事情已经够用了,外部改动检测可以作为一个进阶练习留给你。
小结
"改前必须先读"是写操作的一条硬性公共约定,它促使模型基于真实内容来修改,也为精确替换提供准确的原文。
我们用一个会话级的 WorkspaceState 来实现它:Read 负责登记,Edit 和 Write 负责检查。下一节,我们就带着这条约定去实现 Edit 和 Write。
2.4 实现 Edit 与 Write 工具
本篇涉及到的源码列表:
com.minicc.tool.builtin.EditTool.java
com.minicc.tool.builtin.WriteTool.java
有了上一节的"改前先读"约定作为基础,这一节我们来实现两个文件写操作工具:Edit 和 Write。
Edit 负责对已有文件做精确修改,Write 负责新建文件或整体覆盖。它们是 Agent 修改代码时使用的两个主要工具。
Edit:精确的字符串替换
Edit 的核心思路是字符串替换:你告诉它一段原文 old_string,再给一段新内容 new_string,它把文件里的原文换成新内容。
为什么不用"按行号替换"这种更直接的方式?因为行号很容易错位,模型一旦数错一行,改动就会应用到别的位置。而精确匹配一段文本,要么匹配成功、要么失败,不会在不匹配的情况下改错位置。
它的参数有四个:
file_path:要修改文件的绝对路径。old_string:要被替换掉的原文,必须和文件内容精确匹配,包括缩进。new_string:替换后的新内容。replace_all:可选,是否替换所有匹配,默认是 false。
它的行为可以分成几步校验,再加一步替换。这些校验的顺序很重要,我们逐个来看。
Edit 先做基础校验:file_path 必须是绝对路径,文件必须存在(不存在就该用 Write 新建),而且不能是一个目录。
接着做改前先读校验,也就是上一节讲的那条约定。
然后做匹配校验,这是 Edit 最关键的一环:
// 源码位置:com.minicc.tool.builtin.EditTool.java
int occurrences = countOccurrences(content, oldString);
if (occurrences == 0) {
return ToolResult.error("未在文件中找到 old_string。请对照 Read 的输出,确认内容与缩进完全一致。");
}
if (occurrences > 1 && !replaceAll) {
return ToolResult.error("old_string 在文件中出现了 " + occurrences
+ " 次,不唯一。请补充更多上下文使其唯一,或将 replace_all 设为 true 以全部替换。");
}这里有三种情况,我们要分别处理:
old_string一次都没出现,这说明模型给出的文本不对,Edit 会返回错误,让模型对照 Read 的输出重新构造。old_string出现了多次,但没有开启replace_all,这时替换哪一处都有歧义,所以 Edit 会返回错误,提示模型补充上下文让匹配唯一,或者改用replace_all。- 还有一种情况是
old_string和new_string完全相同,那就等于没有修改,Edit 同样会返回错误。
这些校验都通过之后,Edit 才执行替换:
// 源码位置:com.minicc.tool.builtin.EditTool.java
String updated = replaceAll
? content.replace(oldString, newString) // 全部替换
: replaceLiteralFirst(content, oldString, newString); // 只替换第一处
Files.writeString(path, updated, StandardCharsets.UTF_8);这里我们要特别注意一点:old_string 要当作字面量来处理,而不是正则表达式。Java 的 String.replace 本身就是字面量替换,正好符合我们的需要。
Edit 要返回一份改动摘要
替换完成后,Edit 不是只返回一句"改好了"。它要返回一份改动摘要,告诉模型改了几处、增删了多少行,还附上改动附近几行带行号的代码片段。
// 源码位置:com.minicc.tool.builtin.EditTool.java
String summary = "已修改 " + filePath + "(替换 " + count + " 处,+" + added + " -" + removed + " 行)";
return ToolResult.ok(summary + "\n" + snippet(updated, newString));为什么要附上片段?因为这样模型能确认修改应用到了正确的位置。它看到改动出现在预期的位置,就可以继续下一步;如果发现不对,还能及时纠正。
这份带行号的片段,格式和 Read 的输出一致,模型可以直接对照。
replace_all 的典型场景
replace_all 最常见的场景是重命名变量。
比如你要把一个变量从 count 改成 total,它在文件里出现了十几次。这时逐次精确匹配并不现实,改用 replace_all,一次就能全部替换。
所以我们在给模型的工具说明里,会明确提示它:replace_all 适合变量重命名这类全量替换的场景。
Write:新建或整体覆盖
Write 比 Edit 简单。它不做精确匹配,而是直接把一整段内容写进文件。
它的参数只有两个:file_path(目标文件的绝对路径)和 content(要写入的完整内容)。
它的行为大致是这样:
// 源码位置:com.minicc.tool.builtin.WriteTool.java
boolean existed = Files.exists(path);
// 覆盖已有文件前必须先读过它;新建文件则不需要
if (existed && !ctx.workspace().hasRead(path)) {
return ToolResult.error("覆盖已有文件前请先用 Read 读取它:" + filePath);
}
// 父目录不存在则自动创建
if (path.getParent() != null) {
Files.createDirectories(path.getParent());
}
Files.writeString(path, content, StandardCharsets.UTF_8);
// 写入后视为"已读",便于随后继续用 Edit 修改它
ctx.workspace().markRead(path);这里有几个点值得我们说明一下。
第一,只有覆盖已有文件才要求先读。 新建一个文件没有旧内容,自然不需要先读取。这和 Edit 不一样,Edit 面对的永远是已有文件。
第二,父目录会自动创建。 如果要写的文件路径里有还不存在的目录,Write 会用 Files.createDirectories 把它们创建出来,这样模型就不必先单独创建一次目录。
第三,写完之后同时登记为"已读"。 这样如果模型紧接着想再用 Edit 调整这个文件,就不会因为"改前先读"校验而被拒绝。
工具说明里的使用策略
工具的 description 是写给模型看的使用说明,它直接影响模型会不会正确地用这个工具。Write 的说明里,我们特意强调了两条策略。
一条是:改已有文件优先用 Edit,不要用 Write。因为 Edit 只发送要改的那一小段 diff,更安全,也不容易影响到文件的其它部分;Write 则是整体覆盖,一旦模型生成的内容有遗漏,就会覆盖掉原文件里的其它内容。
另一条是:不要主动创建 *.md 或 README,除非用户明确要求。模型有时会自行生成一批文档文件,这条约定用来避免这种情况。
两个有意的简化
我们的 Edit 和 Write 相对成熟工具做了一些简化,这里我们说明其中两个,便于我们理解这些取舍。
一个是 Edit 一次只做一处替换。成熟工具支持一次传入多条编辑并批量处理,还会做一些等价性判断。我们只保留"一次一处替换"这个最核心的语义,多条编辑的批处理属于鲁棒性方面的优化,不是编辑语义的核心。
另一个是我们只做精确匹配,不做容错。成熟工具会对卷曲引号、被接口清洗过的字符做一些归一化处理,提高匹配成功率。这些容错对理解核心功能帮助不大,我们先不做。
小结
Edit 和 Write 是 Agent 修改代码的两个工具:Edit 做精确的字符串替换,Write 做新建或整体覆盖。
它们都严格遵守"改前先读",都把错误处理成可纠正的观察,Edit 还会返回改动摘要让模型确认改对了地方。
下一节,我们让 Agent 不只会修改文件,还能真正执行命令,那就是 Bash。
2.5 实现 Bash(命令执行)工具
本篇涉及到的源码列表:
com.minicc.tool.builtin.BashTool.java
com.minicc.tool.bash.CommandRunner.java
Edit 和 Write 让 Agent 能修改文件,但一个编程 Agent 只修改文件还不够,它还要能执行命令:编译项目、运行测试、查看 git 状态。
这一节我们来实现 Bash 工具。它是 M2 里能力最强的一个工具,也是风险最高的一个。
Bash 为什么如此关键
我们在 2.1 提过 Reflection(反思),这里我们把它讲清楚。
模型改完代码,它自己并不知道改对了没有。但如果它能运行一遍测试,拿到一份客观的测试输出,它就有了判断依据:测试通过,说明改对了;测试失败,它能从报错里看出哪里不对,然后继续修改。
这个"改、测、看、再改"的循环,就是 Reflection。而让这个循环得以运转的关键环节,正是 Bash。它是模型获取客观反馈的途径。
所以 Bash 的意义不只是"能执行命令",它是让 Agent 具备自我修正能力的关键环节。而且这个能力不需要我们写任何额外的循环代码,模型会自行用起来。
Bash 的参数与定位
Bash 的参数有三个:
command:要执行的命令,必填。timeout:超时时间,可选,单位毫秒,默认两分钟,上限十分钟。description:简要说明这条命令做什么,可选,用于终端展示。
在给模型的说明里,我们要把 Bash 的定位讲清楚,核心可以概括为:优先使用专用工具,而不是用 shell 命令去替代它们。
// 源码位置:com.minicc.tool.builtin.BashTool.java
- 读文件用 Read,不要用 cat/head/tail
- 改文件用 Edit,不要用 sed/awk
- 新建文件用 Write,不要用 echo >
- 找文件用 Glob,搜内容用 Grep,不要用 find/grep为什么要这样引导?因为专用工具的输出更规整、也更可控(比如 Read 带行号、Grep 有结果上限)。如果放任模型什么都用 cat、grep 去凑,上下文会被各种杂乱输出塞满。Bash 应该留给那些专用工具干不了的事,比如编译、测试、git。
另外我们还会提示:工作目录在命令之间是保持的,但 shell 变量这类状态不跨命令保持;多条相互依赖的命令请用 && 串联,不要用换行分隔。
把执行委托给 CommandRunner
Bash 工具本身职责很少,它主要负责解析参数,并把超时限制在上下限之内,真正执行命令的是 CommandRunner。
// 源码位置:com.minicc.tool.builtin.BashTool.java
// BashTool.execute 的核心:参数处理完后交给 runner
long timeout = Math.min(resolvedTimeout, MAX_TIMEOUT_MS); // 上限 10 分钟
return runner.run(command, ctx.workingDir(), timeout, ctx.sandbox(), ctx.cancelToken());CommandRunner 的职责是:用子进程执行一条命令,捕获输出和退出码,并支持超时中止。我们来看它的几个关键设计。
用子进程执行,并合并输出
CommandRunner 通过 /bin/sh -c 来执行命令,工作目录设成会话的项目目录,并且把标准错误合并进标准输出。
// 源码位置:com.minicc.tool.bash.CommandRunner.java
List<String> argv = sandbox ? Sandbox.wrap(command, workingDir) : Sandbox.plain(command);
ProcessBuilder pb = new ProcessBuilder(argv)
.directory(workingDir.toFile())
.redirectErrorStream(true); // stderr 合并进 stdout
Process p = pb.start();为什么要合并 stdout 和 stderr?因为很多命令(尤其是测试和编译)会把错误信息输出到 stderr,模型需要看到完整的输出才能判断。合并到一起之后,模型拿到的就是一份与终端显示一致的完整输出。
是否包进沙箱,由 ctx.sandbox() 这个配置决定。沙箱是怎么实现的,我们留到 2.8 专门来讲一下。这里我们只需要知道,它会返回一份要执行的 argv。
用单独的线程读输出,避免阻塞
这里有一个容易出错的地方:如果等子进程完全结束了才去读它的输出,当输出很多、把管道缓冲区写满时,子进程会阻塞在写入上无法继续,而主线程又在等它结束,双方就形成死锁。
所以我们用一个单独的线程,一边执行一边读取输出:
// 源码位置:com.minicc.tool.bash.CommandRunner.java
StringBuilder out = new StringBuilder();
Thread reader = new Thread(() -> readInto(p, out));
reader.setDaemon(true);
reader.start();这样子进程的输出会被及时读取,缓冲区不会被写满,也就不会阻塞。
超时与取消:短间隔轮询
等待子进程时,我们不是一次性阻塞等待,而是用一个短间隔的循环去轮询它的状态:
// 源码位置:com.minicc.tool.bash.CommandRunner.java
long deadline = System.currentTimeMillis() + timeoutMs;
while (!p.waitFor(POLL_MS, TimeUnit.MILLISECONDS)) { // 每 100ms 查一次
if (System.currentTimeMillis() >= deadline) {
p.destroyForcibly(); // 超时:强制中止进程树
return ToolResult.error("命令超时(" + timeoutMs + "ms)已中止:" + command + ...);
}
}为什么要用轮询,而不是 waitFor 直接等到超时?因为这个轮询点同时也是取消的检查点。
你注意到代码里还传了一个 cancelToken。这是为 M3 的 Ctrl-C 中途取消预留的:用户一旦按下取消,这个循环会在下一次轮询时发现,然后同样地中止子进程。超时和取消复用了同一条中止路径。
Bash 是 M2 里唯一可能长时间运行的工具,所以它也是取消时需要重点处理的对象。这里先把钩子预留好,到 M3 再接入。
退出码决定成功还是错误
命令执行完后,CommandRunner 读取退出码,并把它附在输出末尾一起返回:
// 源码位置:com.minicc.tool.bash.CommandRunner.java
int code = p.exitValue();
String tail = "\n[exit code: " + code + "]";
// 退出码非 0 的命令作为"错误观察"回传,让模型据此修正
return code == 0 ? ToolResult.ok(body + tail) : ToolResult.error(body + tail);这里的处理很关键:退出码非 0 的命令,我们当作一条错误观察回传给模型。
这正是 Reflection 能够生效的机制。测试失败时退出码非 0,模型拿到这条带有失败信息的观察,就知道需要修复;修复后再执行,直到退出码为 0。这一切都在控制循环里自然发生,不需要额外代码。
输出过长就截断
命令的输出有时会非常长,比如一次全量构建。如果全部放入上下文,很容易就把上下文窗口占满。
所以 CommandRunner 对输出设了一个字符上限,超了就截断并加一个标记:
// 源码位置:com.minicc.tool.bash.CommandRunner.java
return body.substring(0, MAX_OUTPUT_CHARS).stripTrailing()
+ "\n… [输出过长,已截断,共约 " + body.length() + " 字符]";这里我们只做最简单的截断。更精细的做法是"大结果落盘,只在上下文里留一段预览加路径",那是 M6 的工具结果预算要讲的内容,这里我们先不涉及。
小结
Bash 让 Agent 能执行命令,更重要的是,它给了模型一个获取客观反馈的途径,Reflection 由此自然成立。
CommandRunner 用子进程执行命令、单独线程读输出、短间隔轮询来处理超时和取消,并用退出码来区分成功与失败。
有了 Bash,Agent 已经能读取、能修改、能执行命令了。下一节我们再增加一个工具,让它面对多步任务时不遗漏步骤、不偏离目标,那就是 TodoWrite。
2.6 实现 TodoWrite 与工作状态
本篇涉及到的源码列表:
com.minicc.session.TodoItem.java
com.minicc.session.TodoList.java
com.minicc.tool.builtin.TodoWriteTool.java
com.minicc.cli.Renderer.java
读取、修改、执行,这三项能力我们都有了。这一节我们增加一个不直接修改文件、但对复杂任务很重要的工具:TodoWrite。
它维护的是一份待办清单,用来让多步任务不遗漏步骤、不偏离目标。
为什么需要一份待办清单
你让 Agent 做一个稍微复杂一些的任务,比如"给这个接口加上参数校验,补一个单元测试,再运行一遍确认通过"。这里面至少有三步。
多步任务有两个常见的问题:遗漏步骤,执行过程中忘了还有一步没做;偏离目标,执行到一半转向了无关的内容。
应对这种情况的常见做法,是列出清单并逐项完成。TodoWrite 提供给模型的,正是这样一份清单。
它让模型把任务分成几条待办先记下来,然后一项项推进、一项项标记完成。有了这份清单,模型就不容易遗漏步骤,我们也能直接看到它进行到哪一步。
它和长期记忆不是一回事
这里我们要先区分清楚,避免和后面的概念混淆。
TodoWrite 维护的是本次任务的工作状态。待办随任务存在,任务做完,这份清单也就没用了。
它和后续里程碑里的跨会话长期记忆并不相同。长期记忆要跨越多次会话长期留存,而待办只服务于当前这一次任务,任务结束就不再需要。
还有一点:TodoWrite 不修改文件、不改变环境,它只修改会话内部的一份状态。所以它不需要审批、也不需要沙箱。
数据结构:一条待办长什么样
每条待办有三个字段:
// 源码位置:com.minicc.session.TodoItem.java
public record TodoItem(String content, String activeForm, Status status) {
public enum Status { PENDING, IN_PROGRESS, COMPLETED }
}content:任务描述,说"该做什么",比如"运行测试"。activeForm:进行时的描述,正在做这一项时展示,比如"正在运行测试"。status:三种状态,待开始、进行中、已完成。
你可能觉得 content 和 activeForm 两个描述有点重复,为什么要分开?
因为它们用在不同的地方。清单静态展示时,我们用 content,读起来更清楚;某一项正在执行时,用进行时的 activeForm 展示,给人的感觉是"它正在做这件事"。
多条待办汇总成一个 TodoList,它仅支持整体替换:每次调用都用新清单把旧清单整个换掉,而不是增量地新增一条、修改一条。
行为与校验
TodoWrite 的 execute 做的事情,归纳起来就是"解析、校验、替换、回执"。
TodoWrite 先把传入的 todos 数组逐个解析成 TodoItem,解析时做一些容错处理,比如没有提供 activeForm 时就用 content 代替。
然后是最关键的一条校验:任意时刻恰好一个进行中。
// 源码位置:com.minicc.tool.builtin.TodoWriteTool.java
long inProgress = parsed.stream()
.filter(i -> i.status() == TodoItem.Status.IN_PROGRESS).count();
if (inProgress > 1) {
return ToolResult.error("同时有 " + inProgress + " 项处于 in_progress;任意时刻应恰好一项进行中,请修正。");
}为什么要加这条限制?因为它促使模型集中处理当前一项。同一时间只做一件事,做完一件再开始下一件,这样它才不会同时处理多项、最后哪一项都没有完成。
如果出现了多个进行中,我们就返回一条错误观察,让模型自己修正。注意这里允许"全部完成"或者"清单为空"的情况,只是不允许"多个同时进行中"。
校验通过之后,TodoWrite 就用新清单整体替换旧清单:
// 源码位置:com.minicc.tool.builtin.TodoWriteTool.java
ctx.todos().replace(parsed);
return ToolResult.ok(summary(parsed));返回给模型的和展示给用户的,是两份不同的内容
这里有一个值得我们详细说明的设计。TodoWrite 执行后,有两个输出:一个返回给模型,一个展示给用户。它们是有意做成不同的。
返回给模型的,只是一句简短的回执,告诉它"更新了几项、各状态几项、当前在做哪一项":
// 源码位置:com.minicc.tool.builtin.TodoWriteTool.java
// 类似:"已更新 3 项待办:1 完成 / 1 进行中 / 1 待办;当前:正在运行测试"为什么不把完整清单再返回给模型?因为模型上一轮刚把完整的 todos 参数发出来,那份数据已经在上下文里了。再原样返回一遍,只会重复占用 token。保留计数,是为了让模型能发现自己是否把状态写错了。
展示给用户的,才是完整的勾选清单,由 Renderer 单独渲染:
// 源码位置:com.minicc.cli.Renderer.java
public void todoList(List<TodoItem> items) {
for (TodoItem item : items) {
switch (item.status()) {
case COMPLETED -> ...("☑ " + item.content()); // 已完成,暗色划过
case IN_PROGRESS -> ...("▶ " + bold(item.activeForm())); // 进行中,高亮
default -> ...("☐ " + item.content()); // 待办
}
}
}已完成的用暗色降低视觉权重,进行中的用高亮加粗,待办的正常显示。这样我们就能直接看出整个任务进行到哪一步。
我们用开头那个任务举一个例子。参数校验已经做完,模型正在补单元测试,测试还没有开始运行。
这时候用户在终端上看到的是完整清单。已完成的用 content,进行中的用 activeForm:
☑ 给接口加上参数校验
▶ 正在补单元测试
☐ 运行测试确认通过同一时刻返回给模型的,只有一句计数:
已更新 3 项待办:1 完成 / 1 进行中 / 1 待办;当前:正在补单元测试用户能看到每一项要做什么,模型只需要知道更新了几项、当前在做哪一项。
这种"给模型的信息精简、给人的展示丰富"的分开处理,是一个很实用的设计思路,后面的里程碑里还会反复用到。
什么时候该用、什么时候不该用
工具好不好用,很大程度上取决于模型是否知道什么时候该使用它。所以我们在给模型的说明里写清楚了判断标准。
该用的时候:任务有三步及以上、用户一次给了多项任务、或者刚接到一个新需求时立即记录下来。
不该用的时候:单步的简单任务、纯粹的问答。像"这个函数是做什么的"这种问题也列出待办,就没有必要了。
把这些判断写进工具说明,模型才会在合适的时候使用它,而不是对每个任务都列出清单。
这段说明就是 TodoWrite 的 description,会随工具定义一起发给模型:
// 源码位置:com.minicc.tool.builtin.TodoWriteTool.java
为当前编码会话维护一份结构化的待办清单,用来跟踪进度、组织复杂任务。
何时使用:任务有 3 步及以上、用户一次给了多项任务、刚接到新需求时立即记录。
何时不用:单步琐碎任务、纯问答。
规则:实时更新状态;完成一项立即标 completed;任意时刻恰好一个 in_progress;
每项都要同时给 content(祈使形,如"运行测试")和 activeForm(进行时,如"正在运行测试")。
每次调用都用新清单整体替换旧清单。小结
TodoWrite 给多步任务提供了一份待办清单,依靠"整体替换"和"恰好一个进行中"这两条规则,让 Agent 不遗漏步骤、不偏离目标。
它有一个值得我们注意的地方,就是把"返回给模型的简短回执"和"展示给用户的完整清单"分开处理,分别优化。
到这里,M2 的四个工具就都实现完了。下一节我们来看这些工具在一轮里是怎么被调度执行的:只读并行、写操作串行。
2.7 只读并行、写操作串行的调度
本篇涉及到的源码列表:
com.minicc.agent.ToolScheduler.java
com.minicc.tool.Tool.java
com.minicc.agent.AgentLoop.java
四个工具我们都实现完了。这一节我们来看一轮里的多个工具调用是怎么被安排执行的。
M1 的做法是顺序逐个执行。M2 把它升级成只读并行、写操作串行,这部分逻辑集中在一个新类 ToolScheduler 里。
为什么要区分并行和串行
模型在一轮里可能一下子要求调用好几个工具。比如它想同时读三个文件:Read(A)、Read(B)、Grep(...)。
这几个都是只读操作,彼此互不影响,逐个顺序读取就会比较慢。如果能同时并行执行,这一轮的等待时间就能明显缩短。
但写操作不同。Edit、Write、Bash 会修改文件或环境,如果并行执行,很可能相互冲突。比如两个 Edit 同时修改同一个文件,结果就会出错。
所以我们的策略是:只读工具可以并行执行以提速,有副作用的工具必须串行执行以免互相干扰。
工具自己声明能不能并行
怎么知道一个工具能不能并行?这个信息在 M1 就已经预留了。Tool 接口上有一个方法 isConcurrencySafe(),由每个工具自己声明能否安全地并行执行。
我们把 M2 几个工具的标记列一下:
| 工具 | isReadOnly | isConcurrencySafe |
|---|---|---|
| Read / Grep / Glob | true | true |
| Edit / Write / Bash | false | false |
| TodoWrite | true | false |
这里有一个点,我们要特别留意:TodoWrite 虽然是只读性质的(不碰文件和环境),但它的 isConcurrencySafe 是 false。
因为它要修改会话里那份共享的待办状态。多个 TodoWrite 并行去修改同一份清单也会出错,所以它不参与并行。这说明"只读"和"能并行"是两个不同的判断,不能等同。
调度策略:把连续的只读调用归并成一批
ToolScheduler 的策略可以概括为:保持模型给出的调用顺序,把连续的可并行调用归并成一批一起执行,遇到不可并行的就单独串行执行。
它的核心是一个 while 循环,我们看简化后的样子:
// 源码位置:com.minicc.agent.ToolScheduler.java
int i = 0;
while (i < calls.size()) {
if (isConcurrencySafe(calls.get(i))) {
// 收集一批连续的可并行调用,一起提交线程池
List<Future<?>> futures = new ArrayList<>();
int j = i;
while (j < calls.size() && isConcurrencySafe(calls.get(j))) {
final int idx = j;
futures.add(pool.submit(() -> results[idx] = runOne(calls.get(idx), ctx)));
j++;
}
awaitAll(futures); // 等这一批全部执行完
i = j;
} else {
// 串行执行一个有副作用的调用
results[i] = runOne(calls.get(i), ctx);
i++;
}
}我们举一个例子来说明。假设模型这一轮要求的调用顺序是:Read、Read、Edit、Read。
调度器会这样处理:前两个 Read 是连续的只读,归并成一批并行执行;遇到 Edit,不可并行,等前面那批执行完,再单独串行执行它;最后一个 Read 再单独执行。
结果永远按原始顺序回填
这里有一个关键约定:不管实际执行时谁先谁后,结果始终按模型给出的原始顺序回填为观察。
你看代码里用的是一个 results 数组,每个任务把结果写到自己原来的下标位置:
// 源码位置:com.minicc.agent.ToolScheduler.java
results[idx] = runOne(calls.get(idx), ctx);并行执行的时候,哪个先执行完是不确定的,但它们各自写回自己对应的下标位置,所以最终 results 数组的顺序和 calls 完全一致。
为什么这点很重要?因为模型看到的上下文顺序必须稳定。它发出的调用是有顺序的,返回的观察也要按这个顺序对应,否则模型就无法把调用和结果对应起来。
渲染也要一一对应
和"结果按原始顺序回填"相关的,还有一个渲染上的问题。
如果并行执行时边执行边打印,⏺(表示调用)和 ⎿(表示结果)就会在屏幕上交错,无法一一对应,读起来很混乱。
我们的做法是:等调度器把这一批结果按原始顺序收齐之后,再回到控制循环里逐个成对打印。每个 ⏺ 调用 紧跟着它自己的 ⎿ 结果。
// 源码位置:com.minicc.agent.AgentLoop.java
List<ToolResult> results = scheduler.execute(calls, toolContext);
for (int k = 0; k < calls.size(); k++) {
renderer.toolUse(calls.get(k)); // ⏺ 工具名(参数)
renderer.toolResult(results.get(k)); // ⎿ 结果
session.appendToolResult(...); // 回填为观察
}代价是显示上不是"谁先执行完谁先显示",而是整批执行完后统一按顺序呈现。对我们这个项目来说,可读性比实时交错显示更重要,所以我们选择了前者。
用一个守护线程池来并行
并行靠的是一个线程池。ToolScheduler 在构造时创建一个线程池,专门供只读工具并行使用:
// 源码位置:com.minicc.agent.ToolScheduler.java
this.pool = Executors.newCachedThreadPool(r -> {
Thread t = new Thread(r, "mcc-tool");
t.setDaemon(true); // 守护线程:JVM 退出时不会被它阻塞
return t;
});用守护线程是一个细节:这样即使有并行任务还挂着,JVM 要退出时也不会被卡住。
单个工具崩了,不能连累整批
并行执行多个工具时,如果其中一个抛出异常,不能让它影响同批的其它工具,甚至导致整个循环中断。
所以每个工具的执行都包在一个 safeExecute 里,把异常捕获下来、转成一条普通的错误观察:
// 源码位置:com.minicc.agent.ToolScheduler.java
private ToolResult safeExecute(Tool tool, ToolCall call, ToolContext ctx) {
try {
return tool.execute(call, ctx);
} catch (Exception e) {
return ToolResult.error("工具执行失败:" + e.getMessage());
}
}这又一次延续了那条贯穿全项目的原则:我们把错误当作观察,不中断循环。
钩子仍在执行工具之前
最后我们再指出一点,方便你和后面的里程碑对应起来。
工具的执行前钩子(HookChain)并没有因为引入调度器而改变调用位置。它仍然在执行每个工具之前被调用,只不过这个调用点现在位于 ToolScheduler 内部的 runOne 里。
M1、M2 这条钩子链还是空的,所有工具直接放行。等到 M3 的审批、M8 的 Plan Mode 拦截,都挂在这里,而调度逻辑本身不需要修改。
小结
ToolScheduler 把 M1 的顺序执行升级成"连续只读批并行、其余串行、结果按原始顺序回填"。
它区分的是"能不能并行",而不是简单地看"是不是只读",并用守护线程池实现并行、用 safeExecute 捕获单个工具的异常。
下一节我们讲 M2 风险最高的部分:Bash 的沙箱设计,看一下怎么为能执行命令的 Agent 加上防护。
2.8 沙箱设计:危险命令护栏 + OS 沙箱(可降级)
本篇涉及到的源码列表:
com.minicc.tool.bash.CommandGuard.java
com.minicc.tool.bash.Sandbox.java
com.minicc.tool.bash.CommandRunner.java
mcc.yml
Bash 能真正执行命令,这是 M2 能力最强的地方,也是风险最高的地方。
模型生成的命令可能带有危险操作,也可能写入项目目录之外的位置。这一节我们来讲怎么为它加上防护,这就是沙箱设计。
三层防护,由内到外
我们的防护分三层,由内到外逐层加强:
- 危险命令护栏:执行前粗筛明显危险的命令。
- OS 沙箱:把命令限制在操作系统级别的一个受限环境里执行。
- 人工审批:由人来最终决定这条命令是否允许执行。
第三层人工审批是 M3 的内容,M2 还没有。所以 M2 这一版,真正起作用的是前两层。我们一层一层来看。
第一层:危险命令护栏
第一层叫 CommandGuard。它在执行任何命令之前,先用一组规则粗筛一遍,命中明显危险的就直接拒绝。
CommandGuard 的实现就是一组正则,命令命中任意一条,我们就把它判定为危险:
// 源码位置:com.minicc.tool.bash.CommandGuard.java
private static final List<Pattern> DENY = List.of(
Pattern.compile("\\brm\\s+-[a-z]*r[a-z]*f?\\s+/(?!\\S*/)", ...), // rm -rf /
Pattern.compile("\\bsudo\\b", ...), // 提权
Pattern.compile(":\\s*\\(\\s*\\)\\s*\\{.*\\}\\s*;\\s*:"), // fork 炸弹
Pattern.compile("\\bmkfs(\\.|\\b)", ...), // 格式化磁盘
Pattern.compile("\\b(shutdown|reboot|halt|poweroff)\\b", ...), // 关机重启
Pattern.compile("\\bcurl\\b[^|]*\\|\\s*(sh|bash)\\b", ...) // 下载管道执行
);
public static boolean isDangerous(String command) {
for (Pattern p : DENY) {
if (p.matcher(command).find()) {
return true;
}
}
return false;
}这里拦截的都是一些典型的危险操作:删除根目录、提权、fork 炸弹、格式化磁盘、关机重启、把网上的脚本下载下来直接管道执行。
关于这一层,必须说明一点:它不是安全边界,只是一层方便的防误操作措施。
为什么这么说?因为依靠正则黑名单无法拦截一条刻意绕过的命令,变换一下写法就能避开。它的价值在于拦截那些模型无意中生成的明显危险命令,不是可以依赖的安全边界。
真正的安全边界,是下面的 OS 沙箱,以及 M3 的人工审批。
第二层:OS 沙箱
第二层是真正在操作系统层面限制命令的 Sandbox。它借助操作系统提供的沙箱机制,限制命令能写入的目录。
不同系统用的机制不一样:macOS 用 seatbelt(也就是 sandbox-exec),Linux 用 bubblewrap(也就是 bwrap)。
Sandbox 的核心方法是 wrap,它根据操作系统把原始命令包装成实际要执行的 argv:
// 源码位置:com.minicc.tool.bash.Sandbox.java
public static List<String> wrap(String command, Path projectDir) {
String os = System.getProperty("os.name", "").toLowerCase();
if (os.contains("mac") && hasExecutable("sandbox-exec")) {
return List.of("sandbox-exec", "-p", seatbeltProfile(projectDir), "/bin/sh", "-c", command);
}
if (os.contains("linux") && hasExecutable("bwrap")) {
return bubblewrapArgv(command, projectDir);
}
warnOnce(); // 没有可用沙箱,打印一次提示
return List.of("/bin/sh", "-c", command); // 降级为直接执行
}在 macOS 上,我们给 sandbox-exec 传一段 profile,核心规则是"默认允许、禁止一切写、再单独放开项目目录和临时目录的写":
// 源码位置:com.minicc.tool.bash.Sandbox.java
(version 1)
(allow default)
(deny file-write*)
(allow file-write* (subpath "<项目目录>") (subpath "/tmp") (subpath "/private/tmp") (subpath "/dev"))这样一来,命令可以读取系统里的内容,但写入只能发生在项目目录和临时目录。如果它试图写入项目目录之外的位置,会被操作系统拒绝。
Linux 上用 bubblewrap 是类似的思路:把根目录以只读方式绑定,单独把项目目录以可写方式绑定,再保留 /dev、/proc、/tmp。
没有沙箱怎么办:降级
这里有一个很现实的问题:不是每台机器都装了 sandbox-exec 或 bwrap。
如果因为检测不到沙箱就拒绝运行,那就做不到"下载即可运行"了。所以我们选择降级。
你注意看 wrap 的最后:检测不到可用沙箱时,它打印一次提示,然后退化成不加沙箱的直接执行。
// 源码位置:com.minicc.tool.bash.Sandbox.java
private static void warnOnce() {
if (WARNED.compareAndSet(false, true)) {
System.err.println("⚠ 未检测到可用沙箱(sandbox-exec / bwrap),Bash 命令将不受沙箱限制地执行。");
}
}这里用了一个 AtomicBoolean 保证提示只输出一次,避免每执行一条命令就重复输出一行。
这个降级是一个明确的取舍:我们优先保证项目在任何环境下都能运行,同时通过运行时的提示明确告知用户"此时没有沙箱保护"。能运行,同时把安全上的不足说明清楚。
在一次执行里的顺序
我们回到 CommandRunner,看这几层是按什么顺序起作用的:
// 源码位置:com.minicc.tool.bash.CommandRunner.java
// 第一层:危险命令护栏(非安全边界,仅用于防误操作)
if (CommandGuard.isDangerous(command)) {
return ToolResult.error("该命令被安全护栏拦截,拒绝执行:" + command);
}
// 第二层:按配置决定是否包进 OS 沙箱
List<String> argv = sandbox ? Sandbox.wrap(command, workingDir) : Sandbox.plain(command);
// 然后才真正启动子进程执行顺序很清楚:命令先经过护栏粗筛,命中就直接拒绝执行;没有命中,再根据配置决定要不要包进沙箱,然后执行。
第三层留给 M3
第三层人工审批,M2 没有实现,写操作是直接执行的。
到了 M3,审批卡片会接入执行前的钩子链,成为最外层、也是最可靠的一个环节:由人来决定这条 Edit、Write 或 Bash 是否允许执行。
这正是 M1 当初把 HookChain 留成扩展点的用意。这三层防护合在一起,才构成一个相对完整的安全体系,而 M2 先把里面两层做好。
和沙箱相关的两个配置
M2 在 M1 的配置之上,只新增了两个字段,都和 Bash 有关:
# 源码位置:mcc.yml
model: deepseek-flash
maxSteps: 40
contextLimit: 200000
sandbox: true # M2 新增:是否把 Bash 命令包进 OS 沙箱(无沙箱环境会自动降级)
bashTimeoutMs: 120000 # M2 新增:Bash 默认超时(毫秒),上限 600000sandbox 是个布尔值,默认 true,控制要不要把 Bash 命令包进沙箱。前面我们已经讲过,即使开启它,在没有沙箱的环境里也会自动降级,不会因此无法运行。
bashTimeoutMs 是 Bash 的默认超时,默认两分钟。模型在单次调用里也可以通过 timeout 参数覆盖它,但不管怎么设,都有一个十分钟的上限。
这两个字段的读取沿用 M1 的配置加载链:内置默认值、全局配置、项目级配置,后者层层覆盖前者。
小结
M2 的沙箱分三层:危险命令护栏粗筛、OS 沙箱限制写入目录、人工审批(留给 M3)。
我们要明确,护栏只是防误操作的措施,并不是安全边界。OS 沙箱才是真正的安全边界。而在没有沙箱的环境下我们选择降级并给出提示,优先保证可以运行。
沙箱开不开、命令默认等多久,由 sandbox 和 bashTimeoutMs 这两个配置决定。
