第 1 章 · M1 能问答的编程 Agent
第 1 章 · M1 能问答的编程 Agent
- 1.1 M1 功能说明:用自然语言问代码
- 1.2 M1 总体架构:分层、包结构与组件协作
- 1.3 核心抽象(一):会话状态 Session
- 1.4 核心抽象(二):工具接口 Tool 与注册表 ToolRegistry
- 1.5 核心抽象(三):控制循环 AgentLoop 与 PreExecuteHook
- 1.6 核心抽象(四):上下文组装 ContextAssembler 与 AssemblyStage
- 1.7 实现只读工具:Read、Grep、Glob
- 1.8 系统提示词与上下文组装顺序
- 1.9 CLI 交互、配置与程序入口 MccApplication
1.1 M1 功能说明:用自然语言问代码
本篇涉及到的源码列表:
com.minicc.tool.builtin.ReadTool.java
com.minicc.tool.builtin.GrepTool.java
com.minicc.tool.builtin.GlobTool.java
com.minicc.agent.AgentLoop.java
com.minicc.cli.Repl.java
com.minicc.cli.Renderer.java
com.minicc.cli.command.HelpCommand.java
com.minicc.cli.command.ToolsCommand.java
com.minicc.cli.command.ClearCommand.java
com.minicc.cli.command.ExitCommand.java
从这一章开始,我们真正动手写代码了。
第 0 章讲清楚了编程 Agent 是什么、它内部怎么运转、跑起来什么样。现在我们进入第一个里程碑 M1,目标是把这些概念落到一个能跑的程序上。
这一节我们先不写代码,而是把 M1 的全貌讲清楚:它交付什么、用户在命令行里会看到什么、要搭建好哪四个核心抽象、哪些事情先不做。
这一版交付什么
M1 交付一个可运行的交互式会话程序。
你在任意项目目录下输入 mcc 把它启动起来,就会进入一个持续的命令行会话。
你用自然语言提问,它通过只读工具(Read、Grep、Glob)按需读代码、检索信息,跑通"决策—行动—观察"的控制循环,最后给出回答。
换句话说,M1 完成后它已经是一个能用的代码问答助手。
你可以问它"这个类是做什么的""某个配置在哪里定义""这段逻辑的调用链是什么",它会自己去翻代码,再回答你。
它还不能改代码、不能跑命令,这些是 M2 要做的事情。M1 只做一件事:能读代码,能回答关于代码的问题。
命令行里是什么样
你在项目目录里输入 mcc,它打印一行欢迎信息,然后停在 > 上等待输入。
$ mcc
mini Claude Code v0.1 · 模型:deepseek-flash · 项目:/Users/wangzheng/codecrush
输入你的需求,/help 查看命令,/exit 退出。
>你用自然语言提问之后,它自己调用 Read、Grep、Glob 去读取和检索代码。行首的 ⏺ 是一步动作,⎿ 是这一步的结果,参数拼在工具名后面的括号里。
这些都是只读操作,直接执行。工具结果超过 6 行时,终端只保留前 6 行,其余改写成一行「…(共 N 行)」。
一次问答大致是这样。下面每一小段,都是模型看完上一步的结果之后,再决定的下一步。
> OrderController 的下单接口都做了哪些校验?
⏺ 先定位下单接口在哪个文件
⏺ Glob(pattern=**/*Controller.java, path=/Users/wangzheng/codecrush)
⎿ /Users/wangzheng/codecrush/src/main/java/OrderController.java
/Users/wangzheng/codecrush/src/main/java/PayController.java
⏺ 再看 placeOrder 附近有没有校验
⏺ Grep(pattern=placeOrder, glob=*.java, output_mode=content)
⎿ /Users/wangzheng/codecrush/src/main/java/OrderController.java:49: public void placeOrder(@RequestBody OrderRequest req) {
/Users/wangzheng/codecrush/src/main/java/OrderService.java:22: public void placeOrder(Order order) {
⏺ 读一下这个方法的上下文
⏺ 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 行)
⏺ 下单接口 placeOrder 目前没有校验入参。它把请求交给 orderService.placeOrder,quantity 和 amount 都没有检查。
>最后那段前后各空一行,那是给用户的最终答复。然后提示符回到 >,你可以继续问下一个问题。
会话本身用斜杠命令控制。这一版真正可用的是下面四个。
> /help
可用命令:
/help — 查看可用命令
/tools — 列出当前可用的工具
/clear — 清空当前会话,重新开始
/exit — 退出
> /tools
已注册工具:
Read(只读)
Grep(只读)
Glob(只读)
> /clear
会话已清空。
> /exit
再见。/plan、/compact、/memory、/resume 在这一版里只提示「该功能在后续版本提供」。
> /plan
该功能在后续版本提供。本章的学习路线
这一章接下来的八节,我们就把上面这张图一块块落到代码里:
- 1.2 我们来讲总体架构,看代码分几层、包怎么组织,以及这些组件怎么协作。
- 1.3 我们来讲第一个核心抽象:会话状态
Session。 - 1.4 我们来讲第二个核心抽象:工具接口
Tool与注册表ToolRegistry。 - 1.5 我们来讲第三个核心抽象:控制循环
AgentLoop与PreExecuteHook。 - 1.6 我们来讲第四个核心抽象:上下文组装
ContextAssembler与AssemblyStage。 - 1.7 我们来实现 Read、Grep、Glob 这三个只读工具。
- 1.8 我们来讲系统提示词,以及上下文是按什么顺序组装起来的。
- 1.9 我们来讲 CLI 交互、配置与程序入口。
读完这一章,你手上就会有一个能问答的最小编程 Agent。更重要的是,你会亲手把那四个核心抽象搭起来,为后面所有里程碑打下基础。
1.2 M1 总体架构:分层、包结构与组件协作
本篇涉及到的源码列表:
com.minicc.MccApplication.java
com.minicc.cli.Repl.java
com.minicc.cli.command.SlashCommand.java
com.minicc.cli.Renderer.java
com.minicc.agent.AgentLoop.java
com.minicc.tool.Tool.java
com.minicc.tool.ToolRegistry.java
com.minicc.tool.ToolCallHelper.java
com.minicc.tool.ToolResult.java
com.minicc.tool.ToolContext.java
com.minicc.tool.Schemas.java
com.minicc.tool.hook.PreExecuteHook.java
com.minicc.tool.hook.HookChain.java
com.minicc.tool.builtin.ReadTool.java
com.minicc.tool.builtin.GrepTool.java
com.minicc.tool.builtin.GlobTool.java
com.minicc.context.ContextAssembler.java
com.minicc.context.AssemblyStage.java
com.minicc.context.SystemPrompt.java
com.minicc.context.SystemPromptStage.java
com.minicc.context.HistoryStage.java
com.minicc.model.ModelClient.java
com.minicc.model.ToolsConverter.java
com.minicc.session.Session.java
com.minicc.config.MccConfig.java
com.minicc.config.ConfigLoader.java
上一节把 M1 要做什么讲清楚了,这一节我们来看 M1 的整体骨架:代码分几层、包怎么组织、一次提问在各个组件之间怎么流动。
你先掌握这张结构图,后面几节逐个讲每个组件时,你就知道它在整体里处在什么位置。
分层与包结构
M1 的代码按职责分层,根包是 com.minicc。下面是 M1 的包结构,每个文件后面标了它的职责,你可以把它当作本章后续内容的一张地图:
mini-claude-code/
├─ build.gradle
├─ src/main/java/com/minicc/
│ ├─ MccApplication.java // 程序入口,装配各组件并启动 REPL 会话
│ ├─ cli/
│ │ ├─ Repl.java // 交互式会话主循环(REPL):读输入、分发斜杠命令、渲染输出
│ │ ├─ SlashCommand.java // 斜杠命令抽象
│ │ └─ Renderer.java // 把 Agent 的每一步渲染成终端文本(⏺ / ⎿)
│ ├─ agent/
│ │ └─ AgentLoop.java // 控制循环(harness 核心):决策—行动—观察
│ ├─ tool/
│ │ ├─ Tool.java // 工具接口
│ │ ├─ ToolRegistry.java // 工具注册表
│ │ ├─ ToolCallHelper.java // 解析 / 构造工具调用的参数
│ │ ├─ ToolResult.java // 工具执行结果(回填时再转成框架消息)
│ │ ├─ ToolContext.java // 工具执行所需的上下文(工作目录等)
│ │ ├─ Schemas.java // 构造工具参数 JSON Schema 的小工具
│ │ ├─ hook/
│ │ │ ├─ PreExecuteHook.java // 执行前钩子接口(M1 空实现,M3/M8 挂载)
│ │ │ └─ HookChain.java // 钩子链:按顺序放行或拒绝
│ │ └─ builtin/
│ │ ├─ ReadTool.java
│ │ ├─ GrepTool.java
│ │ └─ GlobTool.java
│ ├─ context/
│ │ ├─ ContextAssembler.java // 上下文组装器
│ │ ├─ AssemblyStage.java // AssemblyStage 接口(有序、可插入)
│ │ ├─ SystemPrompt.java // 系统提示词模板
│ │ ├─ SystemPromptStage.java // Stage:系统提示词
│ │ └─ HistoryStage.java // Stage:会话历史
│ ├─ model/
│ │ ├─ ModelClient.java // 模型边界:调用模型,原样返回 AssistantMessage
│ │ └─ ToolsConverter.java // 把项目的 Tool 转成只含定义的 ToolCallback
│ ├─ session/
│ │ └─ Session.java // 会话状态:消息历史、工作目录
│ └─ config/
│ ├─ MccConfig.java // 对应 mcc.yml 的配置对象
│ └─ ConfigLoader.java // 配置加载(默认值 → 全局 → 项目级)
└─ src/test/java/com/minicc/... // 单元测试每个包只管一件事:cli 负责和用户交互,agent 是驱动循环的核心,tool 放工具体系(接口、注册表、钩子,以及 builtin 子包里的三个只读工具),context 负责组装上下文,model 收口模型调用,session 保存会话状态,config 管配置。包与包之间通过清晰的接口打交道。
这样分层,目的是让你按职责就能快速定位代码。你要找"循环逻辑"就去 agent,要找"怎么读文件"就去 tool/builtin,要找"怎么拼上下文"就去 context。最外层的 MccApplication 是程序入口,负责把这些组件 new 出来、串起来、启动会话。
一次提问是怎么流动的
光看包结构还不够,关键是理解一次用户提问如何在这些组件间流转。
整个过程大致是这样:
第一步,Repl 读到用户输入。
如果输入以 / 开头,就当作斜杠命令交给对应的命令处理。否则把它作为一条用户消息追加进 Session,然后调用 AgentLoop.run(),开始跑一轮 Agent 循环。
第二步,AgentLoop 进入循环。 每一轮做这么几件事:
先用 ContextAssembler 按固定顺序把本次要发给模型的消息拼好,再交给 ModelClient.call() 请求模型。ModelClient 只负责调用模型,把返回的 AssistantMessage 原样交回,循环再把它写回 Session 的历史。
然后看这条assistant消息里有没有工具调用:
- 如果不含工具调用,说明这是最终答复,渲染出来,循环结束。
- 如果含工具调用,就逐个处理。每个工具调用先经
ToolRegistry找到对应的Tool,过一遍执行前钩子链(M1 为空,直接放行),再执行。执行结果作为"观察"回填到Session,然后进入下一轮。
每一轮还会检查是否超过最大步数,防止无限打转。
第三步,循环结束,Repl 等待用户的下一条输入。
这就是第 0 章讲的"决策—行动—观察"在代码里的样子。模型决策(要不要调工具、调哪个),工具行动(读文件、检索),结果作为观察回到模型面前,如此往复,直到模型觉得信息够了、直接作答。
M1 要搭建好的四个核心抽象
M1 最重要的任务,其实不是"能问答"这个功能本身。
它的首要任务是把后续每个里程碑都要反复复用的四个核心抽象一次性搭建好,并且预留出扩展点。这四个抽象是整个项目的基础,基础稳固了,后面扩展能力才能"只新增、少改动"。
第一个:会话状态容器。
我们用一个 Session 保存一场会话的全部状态。M1 里它只存两样:按时间排好的消息历史,和会话的工作目录。它是整场会话的唯一事实来源,控制循环往里写、上下文组装器从里读。后续里程碑的持久化、工作状态、权限、计划态,都作为新字段挂到它身上。
第二个:工具接口与注册表。
我们定义一个统一的 Tool 接口和一个 ToolRegistry 注册表。M1 往里注册 Read、Grep、Glob 三个工具。后续里程碑要加 Edit、Write、Bash、TodoWrite、askUserQuestion 这些工具时,只是注册一个新实现,控制循环的分发逻辑一行都不用改。
第三个:带"执行前钩子"的工具分发循环。
控制循环在真正执行一个工具之前,会先过一遍"执行前钩子"链。M1 的钩子链是空的,只读工具直接放行。但我们先把接口留好,M3 的写操作审批、M8 的 Plan Mode 拦截,都挂在这个钩子上,不需要修改其他代码。
第四个:上下文组装器,内部是一条有序、可插入 Stage 的管线。
我们在每轮请求模型之前,都要把发给模型的那段输入"拼"出来。M1 只有"系统提示词 + 会话历史"两段,但我们把拼装过程拆成一串有顺序、可增减的 Stage。M5 的长期记忆、M6 的压缩、M7 的 Skills,都作为新增 Stage 挂进这条管线。
这四个抽象对应第 0 章讲过的"扩展点原则"。你把它们理解清楚,后面的里程碑就会越学越轻松。
小结
M1 的架构可以概括为:Repl 在外层接收用户输入,AgentLoop 在内层驱动"组装上下文 → 调模型 → 执行工具 → 回填观察"的循环,Tool、Context、Model、Session 各司其职。
接下来的四节(1.3 到 1.6)是本章的核心,我们逐个把四个核心抽象讲清楚:会话状态、工具接口与注册表、控制循环与执行前钩子、上下文组装器与模型客户端。
1.3 核心抽象(一):会话状态 Session
本篇涉及到的源码列表:
com.minicc.session.Session.java
上一节我们看了 M1 的总体架构,知道了一次提问是怎么在各个组件之间流动的。从这一节起,我们逐个把 M1 的四个核心抽象来讲清楚。
我们第一个要讲的,是贯穿整场会话的状态容器:Session。
为什么我们把它放在第一个来讲?因为后面三个抽象,也就是工具、控制循环、上下文组装,都是围绕它来工作的。
控制循环把每一轮的结果写进它,上下文组装器又从它里面读出历史,发给模型。你先把这个容器理解清楚,再看那三个操作这个容器的部件,就会顺畅很多。
Session 到底存了什么
M1 的 Session 保存的东西很少。它只保存一次会话所必需的两样:消息历史和工作目录。
// 源码位置:com.minicc.session.Session.java
public class Session {
private final Path workingDir; // 本次会话针对的项目目录
private final List<Message> history = new ArrayList<>(); // 按时间排好的消息历史
public Session(Path workingDir) {
this.workingDir = workingDir;
}
// ...
}消息历史是这里面最重要的部分。它按时间顺序记录着这场会话里发生的一切:你问的话、模型的每一句回复、每一次工具调用,以及每一条工具执行之后的观察。
工作目录表示这场会话是在哪个项目里工作。Read、Grep、Glob 解析相对路径时,都以它为基准。
M1 的 Session 就只有这两样,没有别的字段。
为什么历史直接用框架的消息类型
这里有一个关键设计,值得我们单独来讲一下:历史列表里存放的,是 Spring AI 原生的 Message。
具体有三种:用户消息 UserMessage、assistant消息 AssistantMessage、工具结果消息 ToolResponseMessage。
你可能会问,为什么我们不自己定义一套消息类?因为那样会多出一层来回转换。
模型返回的本来就是一条 AssistantMessage,我们原样放进历史。下一轮组装上下文时,我们再把历史原样发回给模型。中间我们不需要先把框架消息转成自己的类,发送之前再转回去。
更重要的是,这同一份消息后面还会继续使用。控制循环派发工具时,用的是这条消息上的 ToolCall。M4 写到磁盘上的,也是这几种消息。
/resume 在回放的时候,会把这几种消息原样读回内存。我们用同一套类型,从追加历史一直用到恢复会话。追加的时候和恢复的时候,我们都不需要在两套类型之间来回转换。
这就是我们直接使用 Spring AI 这三个消息类型的原因。
三个写入口:所有历史改动都封装在这里
Session 对外只提供三个写入方法,分别对应会话里的三种角色:
// 源码位置:com.minicc.session.Session.java
/** 追加一条用户消息。 */
public void appendUserMessage(String text) {
history.add(new UserMessage(text));
}
/** 追加模型这一轮返回的assistant消息(原样写入)。 */
public void appendAssistant(AssistantMessage message) {
history.add(message);
}
/** 把一次工具执行结果作为观察追加进去。 */
public void appendToolResult(AssistantMessage.ToolCall call, ToolResult result) {
history.add(toToolResponse(call, result));
}Repl 收到你的输入时,会调用 appendUserMessage。appendAssistant 和 appendToolResult 都在控制循环里调用:模型一返回,控制循环就把assistant消息写回去;一个工具执行完,控制循环就把结果作为观察写回去。
所有对历史的追加,都只能通过这三个方法完成。这一点现在看起来很普通,但它是 M4 的一个重要伏笔,后面我们会讲到。
ToolResult 在这里转成框架消息
请你注意,appendToolResult 多做了一步转换。
工具执行返回的,是我们项目自己的 ToolResult。下一节我们会详细来讲它,这里你只要知道,它是对工具执行结果的一个简单封装。
历史里要存放的,是 Spring AI 的 ToolResponseMessage。所以这一步转换,就封装在 Session 里:
// 源码位置:com.minicc.session.Session.java
public static ToolResponseMessage toToolResponse(AssistantMessage.ToolCall call, ToolResult result) {
return ToolResponseMessage.builder()
.responses(List.of(
new ToolResponseMessage.ToolResponse(call.id(), call.name(), result.content())))
.build();
}这里有一个细节:ToolResult 的 error 标记并不会进入消息。
因为错误说明已经写在 content 文本里了,模型照样能读到。error 只是给控制循环看的一个信号,这个标记不需要写进历史。
为什么我们把这步转换放在 Session?因为历史里的消息长什么样,由 Session 来决定。
工具只负责产出结果。结果要怎样封装成一条框架消息,再放进历史,这是 Session 的职责。
读历史:只读地交给上下文组装器
写入有三个入口,读取则只有一个入口:
// 源码位置:com.minicc.session.Session.java
/** 只读地返回消息历史(供 Stage 使用)。 */
public List<Message> history() {
return List.copyOf(history);
}它返回的是一份只读副本。上下文组装器里的 HistoryStage 会调用它,把整段历史追加进发给模型的消息列表。
我们返回副本,而不是把内部列表本身交出去,是为了不让外部代码误改 Session 的内部状态。外部代码如果要读历史,就拿这一份快照去用。
还有两个小方法
clear() 会清空历史,让你重新开始一场会话。在 M1 里,它对应 /clear 命令,会把之前的对话全部清掉。
size() 返回当前历史有多少条,给 /context 这类命令用来粗略展示会话有多长。
这两个方法都很简单。我们把它们列在这里,是为了让你对 M1 的 Session 有一个完整的印象:它一共就这么几个方法。
为什么它值得成为一个核心抽象
我们讲到这里,你可能会问:它不就是一个里面存了 List 的类吗,凭什么算核心抽象?
因为它是整场会话的唯一事实来源。
控制循环要知道之前都发生了什么,就去读 Session。组装要知道这一轮发什么给模型,也去读 Session。整场会话只有这一处存着对话的真实状态,不会出现两份历史对不上的情况。
更关键的是,它把会话状态的读写封装成了一个清楚的边界。写入只有三个 append 方法,读取只有一个 history()。谁要修改历史,都要通过这些方法。
这个封装好的边界,就是后面几个里程碑的扩展点。
这个抽象怎么被后面复用
我们之前反复讲过扩展点原则。Session 在这里表现得特别典型。后面好几个里程碑,都是在这个容器上新增内容,不需要修改它已经有的逻辑。
第一个例子是 M4 的持久化。它就加在那三个 append 方法里面。
因为所有写入都封装在这三个方法里,M4 只要在这三处把同一条消息也写进磁盘日志,就实现了自动落盘,一条消息都不会漏掉。这就是前面说的那个伏笔。
第二个例子是 M2 往 Session 里增加工作状态。比如记录哪些文件已经读过,用来做"改前先读"的校验,以及保存一份待办清单。它们都作为 Session 的新字段加进来。
第三个例子是 M3 加上会话级的放行状态,M8 加上计划态的开关。这些同样是 Session 上的新字段,跟这场会话一起存在。执行 /clear 的时候,这些字段会重新建立。
你可以看到,从 M1 到 M8,Session 一开始只有历史和工作目录。到了后面,整场会话的状态都会放在这里。
但它的核心骨架,也就是这一节讲的消息历史和三个写入口,从 M1 起就确定下来了。后面只新增字段,不需要修改这一节讲的这部分。
小结
Session 是四个核心抽象里最基础的一个。它是贯穿整场会话的状态容器,也是唯一的事实来源。
它存两样东西:按时间排好的消息历史,和会话的工作目录。历史直接使用框架的消息类型,这样就不需要再做一层转换。
写入都封装在三个 append 方法里,读取只通过 history() 这一个方法。
下一节我们来讲第二个核心抽象:工具接口 Tool 与注册表 ToolRegistry。我们来看,怎么让模型真正能够操作环境。
1.4 核心抽象(二):工具接口 Tool 与注册表 ToolRegistry
本篇涉及到的源码列表:
com.minicc.tool.Tool.java
com.minicc.tool.ToolResult.java
com.minicc.tool.ToolRegistry.java
com.minicc.MccApplication.java
上一节我们讲了第一个核心抽象 Session,一场会话的状态都存在它里面。这一节我们讲第二个核心抽象:工具体系。
它是一个统一的 Tool 接口,加一个 ToolRegistry 注册表。这是让模型能操作环境的基础扩展点,后面所有工具(Read、Edit、Bash、TodoWrite 等)都建立在它之上。
工具是什么
先回到第 0 章的一个基本认识:模型本身只会输出文本,它不能直接读文件、也不能改代码。
要让模型真的能操作环境,就得给它一组工具。模型通过"我要调用 Read,参数是这个路径"这样的方式表达意图,由我们的程序真正去执行,再把结果告诉它。工具就是模型观察和操作真实环境的手段。
所以工具这个抽象要回答三个问题:模型怎么知道有哪些工具可用、每个工具怎么用、以及调用时我们怎么执行它。Tool 接口就是围绕这三点设计的。
Tool 接口的几个方法
M1 的 Tool 接口保留最关键的几项,去掉了和 UI 渲染、权限规则、埋点相关的方法。核心是这几个:
// 源码位置:com.minicc.tool.Tool.java
public interface Tool {
/** 工具名,模型通过这个名字来调用(如 "Read")。 */
String name();
/** 给模型看的工具说明,讲清楚这个工具做什么、怎么用。 */
String description();
/** 工具参数的 JSON Schema(用 Map 表示),供模型按规范生成参数。 */
Map<String, Object> paramsSchema();
/** 是否只读。只读工具不产生副作用、无需审批(M1 三个工具都返回 true)。 */
boolean isReadOnly();
/** 是否可并行执行。只读工具通常可并行。 */
boolean isConcurrencySafe();
/** 执行工具调用,返回结果。结果会作为"观察"回填给模型。 */
ToolResult execute(AssistantMessage.ToolCall call, ToolContext ctx);
}我们一个个看它们为什么存在。
name()、description()、paramsSchema() 是给模型看的三件套。
名字是模型调用时用的标识。描述讲清楚这个工具干什么、什么时候用。参数 Schema 用 JSON Schema 描述每个参数的类型和含义,模型据此生成合规的参数。这三样会随请求一起发给模型,模型才知道"手上有哪些工具、怎么用"。
isReadOnly() 和 isConcurrencySafe() 是两个行为标记。
isReadOnly() 标记工具是否只读。M1 的三个工具都是只读,返回 true。这个标记现在看着没用,但它决定了后续里程碑要不要走审批:M3 里,只读工具直接放行,写操作才需要你确认。
isConcurrencySafe() 标记工具能否并行执行。只读工具通常可以并行,因为它们之间没有相互影响。M1 不做并行调度,但我们先把标记声明好,M2 会用它实现"只读并行、写操作串行"。
execute() 是真正干活的方法。
它拿到模型发起的工具调用和一个执行上下文,执行后返回 ToolResult。注意参数 call 里的 arguments 是一段 JSON 字符串,不是解析好的 Map,取值时走 ToolCallHelper。
一个预埋的小细节:结果预算
接口里还有一个带默认实现的方法,M1 先埋下、M6 才真正用到:
// 源码位置:com.minicc.tool.Tool.java
default int maxResultChars() {
return 50_000; // 默认阈值;返回 -1 表示无限大、永不落盘
}它声明了"这个工具单条结果超过多少字符就该落盘"。M1 没有压缩,这个方法现在只是个约定。
但有一个工具必须现在就把它确定好,就是 Read。Read 会把它覆盖成 -1,表示结果永不落盘。原因第 0 章提过:如果把 Read 结果落盘、历史里只留文件路径,模型拿到路径又会再 Read 一次,形成"读路径 → 落盘 → 再读路径"的死循环。
这是一个很典型的"扩展点预埋":当下用不到,但我们在接口里先留好位置,到了对应的里程碑直接接上,不用回头改接口。
返回值 ToolResult
工具执行的结果用一个简单的 record 表示:
// 源码位置:com.minicc.tool.ToolResult.java
public record ToolResult(String content, boolean error) {
public static ToolResult ok(String content) { return new ToolResult(content, false); }
public static ToolResult error(String message){ return new ToolResult(message, true); }
}content 是结果文本,error 标记这是不是一条错误结果。
这里有个重要设计:工具出错不会中断循环。 比如读了个不存在的文件,工具返回一条 error 结果,这条结果照样作为观察回填给模型。模型看到"文件不存在,可用 Glob 查找正确路径",就有机会自己纠正,换个路径再试。把错误当作普通观察回传,是编程 Agent 容错的关键一招。
注册表 ToolRegistry
有了工具,还需要一个地方按名字登记和查找它们,这就是 ToolRegistry:
// 源码位置:com.minicc.tool.ToolRegistry.java
public class ToolRegistry {
// 用 LinkedHashMap 保留注册顺序,便于 /tools 按固定顺序展示。
private final Map<String, Tool> tools = new LinkedHashMap<>();
public void register(Tool tool) { tools.put(tool.name(), tool); }
public Optional<Tool> find(String name){ return Optional.ofNullable(tools.get(name)); }
public Collection<Tool> all() { return tools.values(); }
}就这么简单。register 登记一个工具,find 按名字查找,all 返回全部。
M1 启动时注册三个工具:
// 源码位置:com.minicc.MccApplication.java
ToolRegistry registry = new ToolRegistry();
registry.register(new ReadTool());
registry.register(new GrepTool());
registry.register(new GlobTool());all() 返回的全部工具,会由 ToolsConverter 转成随请求发给模型的工具定义(只含名称、描述、参数 Schema,不承载执行)。控制循环分发工具时,用 find(name) 按模型给的名字找到实现。
为什么这是一个扩展点
注册表的价值,在于它把"有哪些工具"和"怎么分发工具"彻底解耦了。
控制循环永远只跟注册表打交道:模型说要调用 Edit,循环就 find("Edit"),找到就执行。至于 Edit 是什么时候加进来的、怎么实现的,循环一概不关心。
所以后续里程碑新增工具,就是一句 registry.register(new EditTool()),分发逻辑一个字都不用动。这正是第 0 章说的"新增一个工具"这类最省事的扩展动作。
四个核心抽象的第二个,我们就讲完了。下一节我们看第三个,也是 harness 真正的核心:控制循环 AgentLoop,以及挂在它上面的执行前钩子。
1.5 核心抽象(三):控制循环 AgentLoop 与 PreExecuteHook
本篇涉及到的源码列表:
com.minicc.agent.AgentLoop.java
com.minicc.tool.hook.PreExecuteHook.java
com.minicc.tool.hook.HookChain.java
这一节我们来讲 harness 的核心:控制循环 AgentLoop。
第 0 章我们反复说"决策—行动—观察",这一节我们就把这句话变成几十行能跑的 Java 代码,顺带把挂在循环上的第二个扩展点,执行前钩子 PreExecuteHook,也一起讲一下。
循环到底在循环什么
我们先把循环的本质说清楚。
模型一次调用,只能做两件事之一:要么直接给出文字答复,要么说"我要调用某个工具"。它没法在一次调用里既读完文件又给出最终答案。
所以要完成一个需要读好几个文件才能回答的问题,就得一轮轮来:模型说要读 A 文件,我们读给它看;它看完说再读 B,我们再读;直到它信息够了,才给出最终答复。
这个"反复请求模型、按它的要求执行工具、把结果回填给它"的过程,就是控制循环。 它什么时候停?当模型返回的消息里不再包含任何工具调用时,说明它准备好作答了,循环结束。
M1 循环的骨架
把上面这段话翻译成代码,核心就是一个 while 循环。下面是去掉后续里程碑叠加内容后的 M1 骨架:
// 源码位置:com.minicc.agent.AgentLoop.java
public void run(Session session) {
int step = 0;
while (true) {
// 边界控制:超过最大步数就停,防止模型在工具间无限打转。
if (step++ >= config.maxSteps()) {
renderer.warn("已达到最大步数上限,停止本轮任务。");
return;
}
// 1) 拼好本次上下文,请求模型,再把这一轮原样写回会话。
List<Message> messages = assembler.assemble(session);
AssistantMessage assistantMessage = modelClient.call(messages, registry.all());
session.appendAssistant(assistantMessage);
List<AssistantMessage.ToolCall> calls = assistantMessage.getToolCalls();
if (calls == null) calls = List.of();
// 2) 没有工具调用 → 这是最终答复,渲染后结束。
if (calls.isEmpty()) {
renderReasoning(assistantMessage);
renderer.finalAnswer(assistantMessage.getText());
return;
}
// 思维链在正文和工具调用之前,调暗显示,避免和最终答复混在一起。
renderReasoning(assistantMessage);
// 若本轮既有文本又有工具调用,先把文本展示出来(模型常用来说明接下来要做什么)。
if (assistantMessage.getText() != null && !assistantMessage.getText().isBlank()) {
renderer.thought(assistantMessage.getText());
}
// 3) 有工具调用 → 逐个执行并把结果作为观察回填。
for (AssistantMessage.ToolCall call : calls) {
renderer.toolUse(call);
Tool tool = registry.find(call.name()).orElse(null);
if (tool == null) {
ToolResult unknown = ToolResult.error("未知工具:" + call.name());
session.appendToolResult(call, unknown);
continue;
}
// 执行前钩子(M1 空链,全部放行)。
if (!hookChain.beforeExecute(call, tool, toolContext).allowed()) {
session.appendToolResult(call, ToolResult.denied(call));
continue;
}
ToolResult result = safeExecute(tool, call); // 捕获异常并转成错误结果
renderer.toolResult(result);
session.appendToolResult(call, result); // 回填为观察
}
// 回到循环顶部,带着新观察再次请求模型。
}
}
// 把思考模式的思维链打到终端。没有则跳过。
private void renderReasoning(AssistantMessage message) {
Object reasoning = message.getMetadata().get(SessionStore.REASONING_CONTENT);
if (reasoning instanceof String text) {
renderer.reasoning(text);
}
}这段代码就是整个项目最该读懂的一段。我们逐块说明。
逐块说明
第 1 块:组装、调用、写回。
每一轮开头,先让 ContextAssembler 把本次要发给模型的消息拼好。注意这里是每轮都重新组装,因为上一轮执行工具产生的观察已经加进了历史,这一轮要带着它们一起发给模型。
然后 ModelClient.call() 请求模型,拿到一条 AssistantMessage,立刻用 session.appendAssistant() 原样写回历史。
这里有个要点:从这条assistant消息上取出的 getToolCalls(),和写进历史的,是同一份数据。循环派发工具用它,历史保存用它,M4 落盘也用它。不另造一套类型,就不用在不同表示之间来回翻译。
第 2 块:判断该不该停。
取出工具调用列表。如果为空,说明模型不想再调工具了,这就是最终答复。我们先渲染思维链,再渲染最终答复,然后 return 结束循环。
思维链放在 assistant消息的 metadata 里,键是 reasoningContent。模型没有返回思维链时,renderReasoning 直接返回,终端上不会多出一行。
这是循环正常结束的唯一出口:只要模型这一轮不再要工具,就说明它判断信息已经够了,循环在这里收尾。
第 3 块:有工具就执行。
有工具调用时,我们同样先渲染思维链,再展示模型附带的说明文字。这段文字通常是在说接下来要做什么,和最终答复分开显示。
如果有工具调用,就逐个处理。对每个调用:先渲染一行"正在调用某工具",用注册表按名字找到工具实现,过一遍执行前钩子,然后执行,最后把结果回填进历史作为观察。
回填完所有工具结果,循环回到顶部,带着这些新观察再请求一次模型。
几个容错细节
循环里藏着几处容错,你别小看它们,正是它们让 Agent 足够健壮。
未知工具不崩溃。 模型偶尔会调一个不存在的工具名。这时不抛异常中断循环,而是回填一条"未知工具"的错误观察,让模型下一轮改用正确的工具。
工具异常不崩溃。 safeExecute 把工具执行时的所有异常都捕获,转成错误结果回填。文件读不了、路径非法,都变成一条普通观察,循环继续。
步数有上限。 maxSteps(默认 40)是边界保护。万一模型陷入"读了又读、永不作答"的循环,到了上限就强制停下并提示,避免无限循环造成不必要的开销。
模型调用失败就干净地停下。 前面三条都是"把异常转成观察、让模型自己纠正",但有一种情况没法这么处理:调用模型本身抛了异常(比如网络断开、鉴权失败、服务端报错)。这时候我们没有新的观察可以回填,循环也进行不下去,于是直接结束本轮并提示用户。M1 不做自动重试,把重试这件事留到后续里程碑。
所以 M1 的循环有两个停止条件:模型给出不含工具调用的答复(正常结束),或达到最大步数(边界保护);此外模型调用失败会让本轮异常终止。
这几处容错的共同思路其实是一致的:能转成"观察"让模型自己纠正的,我们就不中断循环;真的进行不下去的,就干净地停下来并告知用户,绝不让程序崩在半路。 编程 Agent 要跟模型和文件系统这两个充满意外的外部世界打交道,正是这些兜底让它在各种异常面前都不至于直接崩溃。
执行前钩子 PreExecuteHook
现在我们来说一下挂在循环上的第二个扩展点。它有点类似Spring中的Filter或者Interceptor。
注意第 3 块里,执行工具之前有一行"过一遍执行前钩子"。这就是预留给 M3 审批、M8 Plan Mode 的位置。钩子接口很简单:
// 源码位置:com.minicc.tool.hook.PreExecuteHook.java
public interface PreExecuteHook {
/** 在执行工具前判断是否放行。 */
Decision beforeExecute(AssistantMessage.ToolCall call, Tool tool, ToolContext ctx);
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); }
}
}钩子要做的事情就是:在工具真正执行前被问一句"这个能执行吗",回答放行或拒绝。拒绝时还能带一句原因。
多个钩子串成一条 HookChain,按顺序询问,只要有一个拒绝,整体就拒绝:
// 源码位置:com.minicc.tool.hook.HookChain.java
public Decision beforeExecute(AssistantMessage.ToolCall call, Tool tool, ToolContext ctx) {
for (PreExecuteHook hook : hooks) {
Decision d = hook.beforeExecute(call, tool, ctx);
if (!d.allowed()) return d; // 带回原因,供回填给模型
}
return Decision.allow();
}M1 的链是空的。 传进去一个空列表,等价于全部放行,只读工具直接执行。
那为什么现在就要把它建好?因为这样一来,M3 加审批就只是"往链上注册一个 ApprovalHook",M8 加 Plan Mode 拦截就是"再注册一个 PlanModeHook",循环里"执行工具"这段代码一个字都不用改。
这又是一次"扩展点预埋":我们先在基础结构里留好位置,后续里程碑直接接上即可。
小结
控制循环是整个 harness 的核心,可以概括为:组装上下文 → 调模型 → 看有没有工具调用,没有就作答结束、有就执行并回填观察 → 回到开头。
下一节讲第四个核心抽象:上下文组装器 ContextAssembler。它把"组装上下文"做成一条有序、可插入 Stage 的管线。
1.6 核心抽象(四):上下文组装 ContextAssembler 与 AssemblyStage
本篇涉及到的源码列表:
com.minicc.context.AssemblyStage.java
com.minicc.context.ContextAssembler.java
com.minicc.context.SystemPromptStage.java
com.minicc.context.HistoryStage.java
com.minicc.MccApplication.java
com.minicc.model.ModelClient.java
com.minicc.model.ToolsConverter.java
第四个核心抽象,讲的是"每轮到底发什么给模型"。
上一节的循环里有两行:assembler.assemble(session) 把上下文拼好,modelClient.call(...) 把它发出去。这一节我们就来讲这两个组件:上下文组装器 ContextAssembler,和调模型的唯一入口 ModelClient。
为什么组装要做成"管线"
我们先想一个朴素的问题:每轮请求模型,到底要发哪些东西?
M1 很简单,就两样:系统提示词(告诉模型它是谁、该怎么干活),加上会话历史(之前的所有对话和工具观察)。
你可能会想,那直接写个方法,new 一个列表,先 add 系统提示词,再 addAll 历史,不就完了吗?
M1 确实就这么点内容。但往后看:M5 要加长期记忆,M6 要在历史前做压缩,M7 要加 Skills 清单。如果都写进一个方法,这个方法会越来越臃肿,而且每加一项内容都要改它、都有可能影响已经写好的逻辑。
所以我们换个思路:把"拼装"拆成一串有先后顺序的小步骤,每个步骤只负责往消息列表里追加自己那一段。 每个这样的步骤就叫一个 Stage。
这和 Servlet 的 Filter 链、Spring 的拦截器链是同一种思路:一串按顺序执行、各管一段、可随时增减的处理环节,只不过这里处理的对象是"要发给模型的消息列表"。
AssemblyStage 接口
AssemblyStage 只有一个方法:
// 源码位置:com.minicc.context.AssemblyStage.java
public interface AssemblyStage {
/** 把本 Stage 负责的内容追加到 messages 中。 */
void contribute(List<Message> messages, Session session);
}它拿到正在拼装的消息列表和当前会话,往列表里追加自己那一段,就这么简单。
上下文组装器 ContextAssembler
上下文组装器内部是一条管线。它持有一个有序的 Stage 列表,按顺序依次调用:
// 源码位置:com.minicc.context.ContextAssembler.java
public class ContextAssembler {
private final List<AssemblyStage> stages; // 有序;后续里程碑往这里插新 Stage
public ContextAssembler(List<AssemblyStage> stages) {
this.stages = stages;
}
public List<Message> assemble(Session session) {
List<Message> messages = new ArrayList<>();
for (AssemblyStage stage : stages) {
stage.contribute(messages, session); // 每个 Stage 追加自己那一段
}
return messages;
}
}逻辑一目了然:建一个空列表,让每个 Stage 依次往里加东西,最后返回拼好的完整列表。
M1 的两个 Stage
M1 注册两个 Stage,顺序固定为"先系统提示词、再会话历史"。
Stage 一:系统提示词。
// 源码位置:com.minicc.context.SystemPromptStage.java
public class SystemPromptStage implements AssemblyStage {
private final String systemPrompt; // 固定模板,见 1.8
public void contribute(List<Message> messages, Session session) {
messages.add(new SystemMessage(systemPrompt));
}
}它往列表最前面放一条系统消息。系统提示词是固定模板,所以始终排第一个。
Stage 二:会话历史。
// 源码位置:com.minicc.context.HistoryStage.java
public class HistoryStage implements AssemblyStage {
public void contribute(List<Message> messages, Session session) {
messages.addAll(session.history()); // 已按时间顺序维护
}
}它把会话历史里按时间顺序排好的消息(用户消息、assistant消息、工具观察)整个追加进去。
两个 Stage 注册进管线,注册顺序就是执行顺序:
// 源码位置:com.minicc.MccApplication.java
ContextAssembler assembler = new ContextAssembler(List.of(
new SystemPromptStage(SystemPrompt.TEXT),
new HistoryStage()
));执行完,messages 就是 [system, user, assistant, tool, …, user(最新)] 这样的顺序,正好是一次标准请求该有的样子。
这就是第三个扩展点
管线的价值,和前面的注册表、钩子链一样,在于它让"加东西"变成"插一个 Stage"。
后续里程碑要往上下文里加新内容时,只需新增一个 AssemblyStage 实现、把它插进 stages 列表的合适位置,完全不用改 SystemPromptStage、HistoryStage,也不用改 assemble() 方法本身:
- M5 的长期记忆,新增一个记忆加载 Stage,插在系统提示词之后。
- M6 的压缩,用一个压缩 Stage 接管会话历史这一段。
- M7 的 Skills,新增一个技能清单 Stage,插在记忆 Stage 之后。
这就是"扩展点原则"在上下文组装这里的落地:后续只新增,少改动。
模型客户端 ModelClient
上下文拼好了,接下来是把它发出去。这件事封装在一个类里:ModelClient。
它是整个 harness 调用模型的唯一入口,只做一件事:拿到已经拼好的消息和本次可用的工具,调用模型,把返回的 AssistantMessage 原样交回。
// 源码位置:com.minicc.model.ModelClient.java
public AssistantMessage call(List<Message> messages, Collection<Tool> tools) {
OpenAiChatOptions options = OpenAiChatOptions.builder()
.model(config.model())
.toolCallbacks(ToolsConverter.toToolCallbacks(tools))
.build();
ChatResponse resp = chatModel.call(new Prompt(messages, options));
return resp.getResult().getOutput();
}Spring AI 2.0 的 ChatModel.call 不再在框架里执行工具。模型要求的工具调用留在返回的 AssistantMessage 上,由我们自己的控制循环来分发和回填。
思考模式的思维链放在这条消息的 metadata 里,键是 reasoningContent。下一轮请求时,Spring AI 会把它作为 reasoning_content 回传,所以这条 assistant消息要原样保存,metadata 不能丢。
它不负责组装上下文(那是 ContextAssembler 要做的事情),也不负责把结果写回历史(那是 Session 要做的事情)。这两步都由 AgentLoop 编排。ModelClient 职责单一:只管跟模型说话。
工具定义怎么发给模型
还有一个配角 ToolsConverter,负责把我们自己的 Tool 转成 Spring AI 能识别的工具定义:
// 源码位置:com.minicc.model.ToolsConverter.java
ToolDefinition def = ToolDefinition.builder()
.name(tool.name())
.description(tool.description())
.inputSchema(toJsonString(tool.paramsSchema())) // 参数 Schema 序列化成 JSON
.build();它只搬运工具的定义(名称、描述、参数 Schema),不搬运执行。Spring AI 2.0 不会在这次调用里替我们执行工具。这些定义只是让模型知道有哪些工具可用、怎么填参数,真正执行永远由我们自己的循环来做。
为什么要封装在一个类
把"调模型"这件事封装在 ModelClient 一个类里,好处是边界清晰。
将来你要换模型、改接口参数、调整 Spring AI 的用法,只需要动 ModelClient 和 ToolsConverter 这两个类,系统其余部分一概不受影响。控制循环只知道"我调一下 modelClient.call,拿回一条assistant消息",它不关心底层用的是哪家模型、哪个框架。
小结
四个核心抽象,我们到这里就讲完了:
- 1.3 的会话状态
Session,是贯穿全程的唯一事实来源。 - 1.4 的工具体系,让模型能操作环境。
- 1.5 的控制循环,驱动"决策—行动—观察"。
- 1.6 的上下文组装器和模型客户端,决定每轮发什么、怎么发。
这四块基础我们已经稳稳地搭建好,M1 的骨架就立起来了。接下来两节(1.7、1.8)我们为它补充具体内容:实现三个只读工具,写好系统提示词。
1.7 实现只读工具:Read、Grep、Glob
本篇涉及到的源码列表:
com.minicc.tool.builtin.ReadTool.java
com.minicc.tool.builtin.GrepTool.java
com.minicc.tool.builtin.GlobTool.java
基础我们已经搭建好了,这一节我们为 M1 补上真正干活的部分:三个只读工具。
Read 读文件,Grep 按正则检索,Glob 按文件名找文件。有了这三个,模型就能像一个工程师那样翻遍整个代码库,回答关于项目的问题。
Read:读文件
Read 是最常用的工具,模型靠它看文件内容。
参数有三个:file_path(必填,文件的绝对路径)、offset(可选,起始行号)、limit(可选,读取行数)。后两个只在文件很大、需要分段读时才用。
行为上有几个关键点,都是对标成熟工具确定下来的:
- 默认从头读,最多 2000 行。文件再大也不会一次性灌爆上下文。
- 输出采用
cat -n格式,带从 1 开始的行号。行号很重要,M2 的 Edit 要靠它定位要改的位置。 - 文件存在但为空时,返回一条系统提醒"文件存在但内容为空",而不是一个空字符串。否则模型会以为工具坏了。
- 文件不存在时,返回友好的错误,并提示可以用 Glob 查找正确路径。
- 二进制文件按扩展名拒绝,并且再兜一层:读进来发现内容含 NUL 字节也判定为二进制。
核心的读取逻辑,去掉边界判断后大致是这样:
// 源码位置:com.minicc.tool.builtin.ReadTool.java
byte[] bytes = Files.readAllBytes(path);
String text = new String(bytes, StandardCharsets.UTF_8);
List<String> lines = splitLines(text);
int from = offset - 1; // offset 从 1 开始,转成 0 基下标
int to = Math.min(lines.size(), from + limit);
StringBuilder sb = new StringBuilder();
for (int i = from; i < to; i++) {
// cat -n 风格:行号右对齐 6 位,制表符分隔
sb.append(String.format("%6d\t%s%n", i + 1, lines.get(i)));
}如果还有更多行没读完,末尾会追加一条提醒,告诉模型"文件共 N 行,本次读了 X-Y 行,要继续就用 offset=Z"。模型据此决定要不要再读一段。
Read 还有一个必须现在就确定好的约定:结果永不落盘。 它把接口里的 maxResultChars() 覆盖成 -1。原因我们在 1.4 讲过,若 Read 结果落盘、历史只留路径,模型会拿着路径反复重读,死循环。这个约定从 M1 固定下来,M6 的压缩会读取它。
M1 的 Read 做了简化:只读文本文件,不处理图片、PDF、Notebook,也不做去重缓存。这些和"代码问答"主线无关。
Grep:按正则检索
Grep 让模型能在整个代码库里按正则搜索,这是它定位代码的主力工具。
参数:pattern(必填,正则)、path(可选,检索范围)、glob(可选,按文件名过滤,如 *.java)、output_mode(输出模式)、-i(忽略大小写)。
其中 output_mode 有三种,对应不同的提问场景:
content:显示匹配的行。想看具体代码时用。files_with_matches:只显示匹配的文件路径,这是默认。想知道"哪些文件提到了它"时用。count:显示每个文件的匹配次数。
实现上有个工程取舍,值得我们单独讲一下。 成熟工具的 Grep 基于 ripgrep(rg),性能和行为都好。我们也优先调用系统的 rg:
// 源码位置:com.minicc.tool.builtin.GrepTool.java
if (hasRipgrep()) {
return runRipgrep(pattern, searchPath, glob, outputMode, ignoreCase);
}
return runJavaFallback(pattern, searchPath, glob, outputMode, ignoreCase);但不是每台机器都装了 rg。为了保证"下载即可运行",我们提供一个降级实现:检测不到 rg 时,用 Java 正则加目录遍历完成基本的 content / files_with_matches / count。
降级实现的核心就是走一遍目录,逐文件逐行匹配:
// 源码位置:com.minicc.tool.builtin.GrepTool.java
Pattern regex = Pattern.compile(pattern, ignoreCase ? Pattern.CASE_INSENSITIVE : 0);
for (Path file : files) {
List<String> fileLines = Files.readAllLines(file, StandardCharsets.UTF_8);
for (int i = 0; i < fileLines.size(); i++) {
if (regex.matcher(fileLines.get(i)).find()) {
// 按 output_mode 记录匹配行 / 文件 / 计数
}
}
}遍历时会跳过 .git、node_modules、build、target 这类不需要检索的目录。结果也有行数上限,太多就截断并提示模型用更精确的 pattern 缩小范围。
M1 的 Grep 先实现最常用的几个参数,其余(按语言类型过滤、上下文行、多行匹配等)留作后续扩展。
Glob:按文件名找文件
Glob 解决"我知道文件大概叫什么,但不知道在哪"的问题。
参数:pattern(必填,glob 模式,如 **/*.java、src/**/*.yml)、path(可选,搜索根目录)。
行为上有一个对标来的关键点:结果按文件修改时间倒序排列,最近改过的排在前面。因为你最近在动的文件,往往就是当前最相关的。
实现用 Java 自带的 glob 匹配器配合目录遍历:
// 源码位置:com.minicc.tool.builtin.GlobTool.java
PathMatcher matcher = FileSystems.getDefault().getPathMatcher("glob:" + pattern);
List<Path> matched = new ArrayList<>();
Files.walk(root)
.filter(Files::isRegularFile)
.forEach(file -> {
Path relative = root.relativize(file); // 相对根目录匹配,** 行为更符合直觉
if (matcher.matches(relative)) matched.add(file);
});
// 按修改时间倒序排列(最近修改的在前)
matched.sort(Comparator.comparingLong(GlobTool::lastModified).reversed());和 Grep 一样,Glob 也跳过那些无需查找的目录,结果也有数量上限。
三个工具的共性
把三个工具放一起看,你会发现它们有一套共同的设计特征,这不是偶然:
- 参数都用 JSON Schema 声明,通过一个小工具
Schemas构造,减少拼 Map 的样板。 - 错误都转成结构化的
ToolResult.error,而不是抛异常。路径非法、文件不存在、正则写错,都变成一条能让模型自我纠正的观察。 - 结果都有上限,避免一次检索返回上万行占满上下文。
- 描述都写得像给人看的使用说明,因为它确实是给模型"看"的,模型靠它判断什么时候该用这个工具。
这几条合起来,才让它们在真实项目里真正好用。给模型的说明和参数写得够清楚,模型才判断得出什么时候该用哪个工具、参数该怎么填。结果设了上限、出错也不抛异常,所以一次返回上万行、或者模型给了个坏参数,都不会拖垮整个循环。至于行号、按修改时间排序、按文件名过滤这些细节,决定了它在一个几千文件的代码库里翻起来顺不顺手。
小结
三个只读工具一上线,M1 就从"空骨架"变成了"能真的去翻代码"的助手。
模型现在可以:用 Glob 按名字找到文件,用 Grep 定位关键代码,用 Read 细看具体内容,然后综合起来回答你的问题。
工具有了,循环有了,我们还差最后一块:告诉模型"你是谁、该怎么用这些工具"。这就是下一节的系统提示词。
1.8 系统提示词与上下文组装顺序
本篇涉及到的源码列表:
com.minicc.context.SystemPrompt.java
com.minicc.context.ContextAssembler.java
com.minicc.context.SystemPromptStage.java
com.minicc.context.HistoryStage.java
com.minicc.agent.AgentLoop.java
com.minicc.model.ModelClient.java
工具已经有了,循环也已经有了,但模型还不知道"自己是谁、手上这些工具该怎么用"。
这一节我们补上最后一块:系统提示词。顺便我们把"每轮请求到底按什么顺序把消息拼起来"这件事也彻底说清楚。
系统提示词是干什么的
系统提示词是每次请求都放在最前面的一段文字,它给模型确定一个角色和一套行为准则。
对一个编程 Agent 来说,它要讲清楚三件事:你是谁、你该怎么干活、你手上的工具怎么配合使用。模型读完这段,才知道该用工具去读真代码,而不是凭记忆编一段看似合理的答案。
M1 的系统提示词
M1 的系统提示词维护在一个常量模板里,方便你直接读全文。它包含三块内容:
// 源码位置:com.minicc.context.SystemPrompt.java
你是 mini Claude Code,一个运行在命令行里的编程助手,帮助用户理解和检索当前项目的代码。
工作方式:
- 优先使用工具去读取和检索真实代码,而不是凭记忆或猜测回答。
- 需要查看文件内容时用 Read;按正则检索代码用 Grep;按文件名模式查找文件用 Glob。
- Read 的 file_path 必须使用绝对路径。
- 一个问题往往需要多步:先用 Grep/Glob 定位,再用 Read 细看,然后作答。
- 当你已经掌握足够信息时,直接给出简洁、准确的最终回答,不要再调用工具。
回答风格:
- 简洁、直接、切中要点,避免冗余的客套和复述。
- 涉及具体代码时,指明文件路径和关键行,便于用户核对。
- 用中文回答。我们逐块看它为什么这么写。
第一块是身份。 简要说明它是谁、做什么。角色明确了,模型的回答才会聚焦在"理解和检索代码"上。
第二块是工作方式,这是最关键的一段。 它反复强调一件事:优先用工具去读真代码,别凭猜测。 这是编程 Agent 和普通对话助手最大的区别。它还点明了什么场景用哪个工具、绝对路径的要求,以及"信息够了就直接作答,别再空调工具"。
这最后一点呼应了 1.5 的循环停止条件:引导模型在合适的时候返回不含工具调用的答复,循环才能正常收敛。
第三块是回答风格。 简洁、直接、指明文件路径和关键行。编程场景下,一句"在 OrderController 第 42 行"比一大段客套有用得多。
一个容易忽略的点:工具说明不在系统提示词里
你可能会问:工具怎么用,不是该写在系统提示词里吗?
不是。工具的名称、描述、参数 Schema,不放在系统提示词的文本里,而是通过请求的 tools 字段单独发送(1.6 里我们讲过的 ToolsConverter 做的就是这件事)。
这是主流模型工具调用协议的标准做法。系统提示词讲的是"大的工作方式和风格",具体每个工具的参数规范走专门的 tools 通道。两者分工不同,你别把两者混在一起。
上下文组装顺序
说完系统提示词,我们把"每轮请求的完整消息长什么样"拼起来看。
我们在 1.6 讲过,ContextAssembler 按注册顺序执行各 Stage。M1 两个 Stage 的顺序是"先系统提示词、再会话历史",所以每轮组装出来的消息是这样:
[system] 系统提示词
[user] 历史里的用户消息
[assistant] 历史assistant消息(含之前的工具调用)
[tool] 历史工具结果(作为观察)
……按时间顺序……
[user] 本轮最新输入系统提示词永远第一个,然后是按时间顺序排列的整段会话历史,一直到最新的那条用户输入。
为什么顺序要固定
组装顺序固定,不是随便确定的,背后有个实际收益:前缀缓存。
很多模型服务对"请求开头那段不变的内容"有缓存优化。如果每轮请求的开头(系统提示词、靠前的历史)都稳定不变,模型侧就能复用缓存,省时间也省钱。
反过来,如果你每轮都频繁改动系统提示词的内容、让顺序不稳定,缓存就失效了。所以我们刻意把稳定的东西放前面、固定住。这个"稳定在前"的原则,到 M6 讲压缩时会变得更重要。
一次完整请求的样子
把这一章前面讲的串起来,一次请求模型的完整链路是:
AgentLoop调assembler.assemble(session)。SystemPromptStage往列表放入系统提示词。HistoryStage追加整段会话历史。- 得到完整消息列表,连同注册表里的全部工具,交给
ModelClient.call()。 ModelClient把消息和工具定义组装成请求发给模型,拿回一条AssistantMessage。
模型看到的,就是"一段角色设定 + 到目前为止的全部对话和观察 + 一份可用工具清单"。它据此决定:是再调个工具,还是直接作答。
小结
系统提示词给模型确定了身份和行为准则,组装顺序决定了每轮发给模型的消息长什么样。
到这里,M1 的核心能力已经齐全:四个核心抽象、三个只读工具、系统提示词和组装顺序。下一节我们补上外层交互:命令行交互怎么做、配置怎么加载、以上所有的组件如何组装起来运行。
1.9 CLI 交互、配置与程序入口 MccApplication
本篇涉及到的源码列表:
com.minicc.cli.Repl.java
com.minicc.agent.AgentLoop.java
com.minicc.cli.Renderer.java
com.minicc.cli.command.SlashCommand.java
com.minicc.cli.command.HelpCommand.java
com.minicc.cli.command.ToolsCommand.java
com.minicc.cli.command.ClearCommand.java
com.minicc.cli.command.ExitCommand.java
com.minicc.config.ConfigLoader.java
com.minicc.config.MccConfig.java
mcc.yml
com.minicc.MccApplication.java
核心能力已经齐全,这一节我们为 M1 补上外层:用户怎么跟它交互、配置怎么加载、程序启动时又是怎么把各个组件装配起来、拉起整个会话的。
这些不是最"核心"的部分,但少了它们,程序就不是一个能交到用户手上的工具。
REPL:两层循环
mini Claude Code 启动后进入一个 REPL。
REPL 是 Read-Eval-Print Loop 的缩写,也就是"读取—求值—打印 循环",就是你平时在终端里敲 python、node 进去那种一问一答的交互环境。它由四个环节不断循环:读取一行输入(Read)、对输入求值(Eval)、把结果打印出来(Print)、回到开头等下一次输入(Loop)。
这里有一个特别重要、也特别容易混淆的点:整个系统其实有两层循环,我们要把它分清楚。
- 外层是
Repl:一轮处理一条用户输入,这是人和程序之间的交互循环。 - 内层是
AgentLoop:在一次用户输入内部,驱动"决策—行动—观察"的模型与工具循环,可能连着调好几个工具,直到模型给出最终答复,才把控制权交回外层。
你输入一句话,外层 Repl 接住,交给内层 AgentLoop 跑一整轮(期间可能读了五个文件、检索了三次),跑完了,外层再回到 > 等你下一句。
Repl 的主循环
Repl 的主循环逻辑很直白:读一行,判断是斜杠命令还是自然语言,分别处理。
// 源码位置:com.minicc.cli.Repl.java
while (true) {
String line = reader.readLine("> "); // 读取一行输入
if (line == null) break;
line = line.strip();
if (line.isEmpty()) continue;
if (line.startsWith("/")) {
boolean exit = dispatchSlash(line); // 斜杠命令,直接执行
if (exit) break;
} else {
session.appendUserMessage(line); // 自然语言,作为用户消息
agentLoop.run(session); // 驱动一轮 Agent 循环
}
}以 / 开头的交给斜杠命令处理,不经过模型。否则当作一条用户消息追加进会话,再调 agentLoop.run() 跑一轮。
一个实现细节:读行用了 JLine 这个库来接管输入,由它负责退格、方向键、历史记录,以及中文等多字节字符的编辑。这比直接用裸的标准输入体验好得多,尤其是中文退格。
启动起来是什么样子
启动后先打一行横幅,报告版本、模型、项目路径,然后进入会话:
$ mcc
mini Claude Code v0.1 · 模型:deepseek-flash · 项目:/Users/wangzheng/codecrush
输入你的需求,/help 查看命令,/exit 退出。
> OrderController 的下单接口都做了哪些校验?
⏺ Read(OrderController.java)
⎿ 读取 120 行
⏺ Grep("validate")
⎿ 找到 3 处
⏺ 下单接口 placeOrder 目前只校验了……行首的 ⏺ 表示一步动作,⎿ 表示这步的结果,工具调用写成"工具名(参数)"。这个渲染由 Renderer 负责,它还会把中间过程调暗、把最终答复高亮,让你一眼区分"它正在忙什么"和"给我的结论"。
M1 的斜杠命令
斜杠命令用来控制会话本身,不交给模型。M1 只实现最小子集:
/help:列出可用命令。/tools:列出已注册的工具(Read / Grep / Glob)。/clear:清空当前会话历史,重新开始。/exit:退出程序。/context:简化版,展示当前上下文的大致占用(精确的 Token 统计是 M6 要做的事情)。
像 /plan、/compact、/memory、/resume 这些依赖后续里程碑的命令,M1 没有实现,或只提示"该功能在后续版本提供"。
每个命令都实现同一个 SlashCommand 接口,Repl 启动时按顺序注册进一张命令表。加一个新命令,就是写一个实现、注册一下,和工具、钩子、Stage 是同一种"只新增"的扩展套路。
配置:两层覆盖
为了不让每个项目都手建一份配置,ConfigLoader 按"内置默认值 → 全局配置 → 项目级配置"的顺序层层覆盖,后者覆盖前者:
- 内置默认值:写在
MccConfig的常量里,什么都不配也能跑。 - 全局配置
~/.mcc/mcc.yml:配一次,所有项目通用。 - 项目级
<项目>/.mcc/mcc.yml:可选,某个项目要特殊设置时才建。
首次启动时还有个便捷的引导:如果全局配置不存在,就自动拷一份带注释的默认模板过去,并打印路径。这样你第一次运行完,就有一份可以直接改的配置文件。
M1 实际用到的字段不多:
# 源码位置:mcc.yml
model: deepseek-flash
maxSteps: 40 # 单次任务的最大循环步数
contextLimit: 200000 # 上下文窗口上限(Token);M1 仅作记录,压缩在 M6 启用配置文件里可能还有 sandbox、compact 等字段,那是后续里程碑用的,M1 即使读到也先忽略。
凭证不写进配置文件。 API Key 通过环境变量 OPENAI_API_KEY 提供,服务地址可用 OPENAI_BASE_URL 覆盖。这样配置文件可以放心提交,不怕泄露密钥。
程序入口 MccApplication:手动装配与启动
前面我们把 Repl、AgentLoop、工具、上下文、配置都讲过了,但它们各自是独立的组件,总得有一个地方把它们 new 出来、按依赖关系串起来,再拉起整个会话。这个地方就是程序入口 MccApplication。
它的 main 方法做的事情可以分成三步,顺序是固定的:
第一步,加载配置,确定运行参数。 先用前面讲过的 ConfigLoader 把"内置默认值 → 全局配置 → 项目级配置"三层合并出一个 MccConfig,再从环境变量里读出 API Key 和服务地址。到这一步,model、maxSteps 这些运行参数就都定下来了,后面构造组件时直接拿来用。
第二步,自底向上地把组件一个个装出来。 这一步是入口的主体,大致是这样一条装配链:
// 源码位置:com.minicc.MccApplication.java
public static void main(String[] args) {
MccConfig config = new ConfigLoader().load(); // 1) 三层配置合并
ModelClient modelClient = new ModelClient(config); // 2) 收口模型调用
ToolRegistry registry = new ToolRegistry(); // 3) 工具注册表
registry.register(new ReadTool()); // 注册三个只读工具
registry.register(new GrepTool());
registry.register(new GlobTool());
HookChain hookChain = new HookChain(List.of()); // 4) 空钩子链(M1 全放行)
ContextAssembler assembler = new ContextAssembler( // 5) 上下文组装器(Stage 有序)
List.of(new SystemPromptStage(), new HistoryStage()));
Session session = new Session(); // 6) 会话状态
Renderer renderer = new Renderer(); // 7) 终端渲染
AgentLoop agentLoop = new AgentLoop( // 8) 把核心组件注入控制循环
config, modelClient, registry, hookChain, assembler, renderer);
Repl repl = new Repl(config, session, agentLoop, renderer); // 9) 外层交互循环
repl.start(); // 10) 打横幅、进入 REPL
}顺序之所以是"从里到外",是因为后装的组件依赖先装的:AgentLoop 要用到模型、注册表、钩子链和上下文组装器,所以这些得先 new 好;Repl 又要用到 AgentLoop,所以放在最后。你顺着这段代码从上往下读,整个系统谁依赖谁、怎么拼起来的,一眼就看清楚了。
第三步,启动会话。 最后一行 repl.start() 打出横幅、进入本节开头讲的那个 REPL 主循环,程序就正式开始接收用户输入了。
这里要专门提一句:MccApplication 是一行行手动 new 出来、手动串起来的,并没有用 Spring Boot 的自动装配。这是刻意的选择。手动装配虽然啰嗦,但它把每个组件怎么组合、谁依赖谁、Spring AI 到底只承担了模型调用那一小块,全都摆在明面上,不会有"框架在背后偷偷帮我做了什么"的黑箱感。
还有一点值得留意:你会发现这里埋着好几个"扩展位"。第 4 步的钩子链在 M1 是空的,M3 的审批、M8 的 Plan Mode 都会往里注册;第 5 步的上下文组装器在 M1 只有两个 Stage,M5 记忆、M6 压缩、M7 技能都会往它的管线里插新 Stage。后续里程碑的大量改动,其实都集中在 MccApplication 这一处"多注册一个工具、多挂一个钩子、多插一个 Stage",而循环、工具、上下文这些主体代码几乎不用动。这正是我们在 1.2 里说的"只加不改"在入口处的体现。
小结
这一节我们给 M1 补齐了外壳:REPL 的两层循环、终端渲染、斜杠命令、两层配置,以及把这一切装配起来并启动的程序入口 MccApplication。
到此,M1 的所有组件我们就都讲完了。
