工具系统 —— 八个工具,一道文件锁
M04 结尾留下的问题是:模型返回一个 toolCall——一个名字、一段 JSON,谁去执行?
答案在 coding-agent/src/core/tools/。这个目录 16 个文件、3,662 行,看起来平平无奇,但它要回答三个很难的问题:
- 模型给的参数可能不合 schema、可能是坏 JSON、可能根本不存在的工具名,怎么办
- 模型一次调八个工具,并行还是串行
- 两个工具同时改同一个文件,怎么不打架
第三个问题的答案是本章的核心。先说结论:按文件路径分片的串行锁,粒度是文件,不是全局。
零、读这章之前,你需要先知道一件事
工具调用(tool call):模型只能输出文字。工具是它唯一能"动手"的地方—— 它写一段结构化的请求(调哪个、什么参数),由宿主去执行,结果再塞回上下文。
没有它会怎样:你会把它当函数调用(以为模型在自己执行代码),于是看不懂 "它为什么又调了一遍同一个工具":因为结果不是你给的,是宿主回填的。
本书哪里用到:§一 八工具表;循环里那次 tool_execution_start 在 M03 §六。
一、八个工具,一张台账
ToolName 正好八个取值(index.ts:95):
export type ToolName = | "read" | "bash" | "powershell" | "edit" | "write" | "grep" | "find" | "ls";| 工具 | 文件 | 行数 | 干什么 | 截断方式 |
|---|---|---|---|---|
bash |
bash.ts |
442 | 跑 shell 命令 | truncateTail(保尾部) |
grep |
grep.ts |
325 | 搜内容 | truncateLine + 条数上限 |
find |
find.ts |
318 | 按 glob 找文件 | 条数上限 + 字节兜底 |
read |
read.ts |
224 | 读文件/图片 | truncateHead(保头部) |
edit |
edit.ts |
218 | 精确文本替换 | — |
ls |
ls.ts |
175 | 列目录 | 条数上限 + 字节兜底 |
write |
write.ts |
97 | 新建/覆盖 | — |
powershell |
powershell.ts |
68 | 跑 PowerShell | truncateTail |
八个工具本体合计 1,867 行。而支撑它们的基础设施——truncate / output-accumulator / file-mutation-queue / path-utils / edit-diff / render-utils / tool-definition-wrapper / index——合计 1,795 行。
一半的代码在管另一半。 这是本章想说清的事:工具本身都是"薄"的(write 只有 97 行),真正的工作量在于"怎么让这八个东西不互相踩"。
1.1 三套预设,不是一套
index.ts 提供三个工厂,权限依次放大:
| 工厂 | 含哪几个 | 用途 |
|---|---|---|
createReadOnlyTools |
read grep find ls |
只读模式、审查场景 |
createCodingTools |
read bash edit write |
日常编码 |
createAllTools |
全部 8 个 | 全权限 |
注意 createCodingTools 里没有 grep / find / ls。这不是漏了——有 bash 就够了,grep 那三个工具的价值是"不经过 shell 也能搜",属于减依赖而非加能力。
而 createReadOnlyTools 把 bash 排除在外,才是真正的安全边界:只读模式不能有 shell,因为 shell 什么都能干。
1.2 三种体格
看行数分布就会发现三个档位:
441/442 bash 跑进程,要管超时/中止/进程树/流式输出317-325 grep / find 包一层 ripgrep / glob,管条数和字节68-224 其余六个 读、写、改、列目录最悬殊的一组是 bash(442 行)和 powershell(68 行)——差 6.5 倍。原因很简单:powershell.ts 一行执行逻辑都没有,全部复用 bash.ts 导出的 createLocalShellOperations 和 createShellToolDefinition,只改三样东西:shell 名、提示符、临时文件前缀。
1.3 模型怎么知道有这八个工具
八个工具都在 createAllTools 里,但模型并不会"看到"这个函数。它看到的是每个工具自报的一段文字。
每个工具文件开头都有这么一个 as const 对象:
export const readToolSystemPromptContribution = { snippet: "Read file contents", guidelines: ["Use read to examine files instead of cat or sed."],} as const;末尾那个 as const 是全书第一次正面用到它:不加时 snippet 会被推断成
string、guidelines 会被推断成 string[];加了之后才是字面量类型。
为什么要较真:string 宽到可以装任何字符串,下游用 snippet 拼提示词时
拼错也没人报错;窄成字面量后,写错一个字符就是编译错误。代价是不能改,
要改就改源码。附录 B §2.7 有对比。
八个工具八段,全部挂到 ToolDefinition.promptSnippet / promptGuidelines 上。然后 M04 讲过的折叠把它们带进首条 system 消息的 toolsAdded,最终成为提示词的一部分:
ToolDefinition.promptSnippet ↓ createToolDefinitionContext.tools[] ↓ normalizeContext(M04 2.1)messages[0].toolsAdded ↓ provider 渲染系统提示词里的工具说明这条链有个实用推论:改 guidelines 就是改 Agent 行为,不用动一行逻辑代码。
看 write 和 edit 的分工是怎么定的——完全靠提示词,不靠代码:
| 工具 | guidelines 原话 | 效果 |
|---|---|---|
write |
Use write only for new files or complete rewrites | 拦住"小改用 write" |
edit |
Each edits[].oldText must exactly and uniquely match... |
逼模型给短匹配 |
edit |
Batch changes to one file in a single call | 减少重复打开 |
第三行尤其关键:一次 edit 调用的每个 await 都在持有文件锁。引导模型批量改,等于减少持锁次数。
二、四层类型:一个工具为什么有四张脸
同一个 read 工具,代码里会出现四种类型名:Tool、AgentTool、ToolDefinition、TypeBoxAgentTool。
2.1 四张脸各管什么
ToolDefinition 产品层:带 promptSnippet / renderers / 状态机 ↕ wrapToolDefinition / createToolDefinitionFromAgentToolAgentTool 内核层:@earendil-works/pi-agent-core 认识的形状 ↕ TypeBoxAgentTool静态类型 Static<typeof schema>:TypeBox 推导出的参数类型而 Tool 是 AgentTool<any> 的别名(index.ts:93):
export type Tool = AgentTool<any>;export type ToolDef = ToolDefinition<any, any>;2.2 多出来的两个字段
ToolDefinition 比 AgentTool 多出的是什么?看 tool-definition-wrapper.ts:27-49 的转换——它只透传 9 个字段,其中两个是 AgentTool 根本没有的:
promptSnippet/promptGuidelines:这个工具的一句话说明和用法约束,会被折进系统提示词(M04 的toolsAdded里带的就是这个)renderers:TUI 里怎么画这次调用(M14 会讲)
举个例子,write.ts:15-18:
export const writeToolSystemPromptContribution = { snippet: "Create or overwrite files", guidelines: ["Use write only for new files or complete rewrites."],} as const;这一小段就是"模型怎么知道该用 write 而不是 edit"的全部来源。它不是文档,是提示词的一部分。
2.3 第四张脸:TypeBoxAgentTool
在 write.ts 的末尾会看到一个奇怪的返回类型(:94):
export function createWriteTool( cwd: string, options?: WriteToolOptions,): TypeBoxAgentTool<typeof writeSchema> {为什么不直接写 AgentTool?tool-definition-wrapper.ts:5-9 的注释解释了原因:
pi-agent-coretypesparamsthroughpi-schema, which maps only the common TypeBox kinds.
两个包各自用不同的 schema 基础设施。agent 包通过 pi-schema 推导参数类型,只映射常见 kind;而内置工具用 TypeBox 写 schema,Static<typeof writeSchema> 是精确的类型。
TypeBoxAgentTool 就是两者的交:把 execute 和 prepareArguments 两个方法的签名重新声明成 TypeBox 版本(:10-21)。这样在两个世界里都对:传给 agent 包能用,在 coding-agent 内部调用参数有完整类型。
代价是每加一个工具都得过这层交叉类型。收益是工具实现里能直接拿到 { path, content } 的类型推导,不用手写 interface。
所以"一个工具几张脸"的完整答案是四张:Tool(别名)、AgentTool(内核形状)、ToolDefinition(产品形状)、TypeBoxAgentTool(类型精确版内核形状)。
2.4 反向转换
createToolDefinitionFromAgentTool(:65-77)做反方向:把外部传入的裸 AgentTool 包一层成 ToolDefinition。注释说得很直白:
This keeps AgentSession's internal registry definition-first even when a caller provides plain AgentTool overrides.
"definition-first"——内部注册表只认 ToolDefinition,外部给什么都先转换。这样上层永远不用判断"这个工具是内置的还是扩展塞进来的"。
2.5 为什么不干脆用一个类型
因为这两层由不同的包拥有。AgentTool 在 agent 包,它只需要知道"有个东西能执行、有 schema、有名字"。ToolDefinition 在 coding-agent 包,它要给 TUI 画图、要往系统提示词里塞说明。
如果把 renderers 塞进 AgentTool,那 agent 包就得认识渲染层——抽象立刻污染。两层类型不是过度设计,是两个包的边界。
三、五步管道
模型给出了 toolCall,到它变成一条 ToolResultMessage,中间有五步。这张图可以当目录用:
模型吐 toolCall │ ├─ 找不到这个工具 ──────────────→ error 消息 ↓① prepareArguments 垫片:修模型发坏的格式 ↓② validateToolArguments 校验:schema 说了算 ↓③ beforeToolCall 钩子:可以拦,可以终止 ↓④ tool.execute 干活(文件锁在这里) ↓⑤ afterToolCall 钩子:可以改结果 ↓ToolResultMessage代码在 agent/src/agent-loop.ts,prepareToolCall(:718-787)+ executePreparedToolCall(:831-867)+ finalizeExecutedToolCall(:869-920)。
3.1 第 0 步:工具集从哪来
管道开始之前,得先知道调用谁。prepareToolCall 的第一行就是查表(agent-loop.ts:726):
const tool = tools.find((t) => t.name === toolCall.name);if (!tool) { return { kind: "immediate", result: createErrorToolResult(`Tool ${toolCall.name} not found`), isError: true, };}tools 默认取 currentContext.tools ?? []。回到 M03 就知道,这个 tools 是从 transcript 算出来的当前工具集(M04 的 toolsAdded / toolsRemoved 累加)。
于是出现一个真实场景:模型在第 3 轮调了一个第 5 轮才加进来的工具。它会被 not found 拦住——因为此刻的 transcript 里确实没有这个工具。
这不是 bug,是"工具集随对话演进"的必然结果。M07 讲扩展动态加载时会更清楚。
3.2 第 1 步 prepareArguments:给模型擦屁股
edit.ts:107 的注释是这一层的存在理由:
// Some models (Opus 4.6, GLM-5.1) send edits as a JSON string// instead of an array. Others send a single edit object.于是 prepareEditArguments(:100-131)要认三种坏格式:edits 是 JSON 字符串、edits 是单个对象、老的顶层 oldText+newText。
垫片只修形状,不修语义。修完照样要过 schema 校验——这个分工很重要:如果垫片顺手把"参数不对"也修了,那 schema 就形同虚设。
3.3 第 2 步 validateToolArguments:schema 说了算
一次调用,校验失败就返回 isError: true 的消息。注意这一步不抛异常,而是变成消息回到模型手里——模型看到"参数不合法,字段 X 缺少"之后,下一轮通常会自己改对。
这就是工具设计里的第一条实用原则:错误信息不是给人看的,是给模型看的下一轮输入。
3.4 第 3、5 步钩子:可拦、可改
beforeToolCall 能返回 { block: true, reason },还能带 terminate: true。afterToolCall 能替换 content、details、isError。
两个钩子都有可能抛异常,而两处都被 try/catch 吃掉了(:780-786、:908-911)——连钩子崩溃都不能让循环挂掉。
agent-loop.ts:812-819 的注释说明了另一件事:
Run one tool call through the same steps as a model-issued call... Tools that call other tools use this so the hooks (for example permission checks) apply to those calls too.
嵌套工具调用(M13 的 codemode 场景)也走同一条管道,否则"权限检查"就能被"套一层工具调用"绕过去。
四、并行还是串行:一票否决,但没人投这一票
4.1 调度层怎么写
agent-loop.ts:525-533 全文就九行:
const toolCalls = assistantMessage.content .filter((c) => c.type === "toolCall");const hasSequentialToolCall = toolCalls.some( (tc) => currentContext.tools?.find((t) => t.name === tc.name) ?.executionMode === "sequential",);if (config.toolExecution === "sequential" || hasSequentialToolCall) { return executeToolCallsSequential(...);}return executeToolCallsParallel(...);ToolExecutionMode 只有两个值(agent/src/types.ts:47):"sequential" | "parallel"。默认是 "parallel"(agent.ts:261)。
有个细节值得注意:一个批次里只要有一个工具声明了 sequential,整批都串行。不是"这个串行、那个并行"。理由是顺序保证——如果 A 要等 B 的效果,那把 A 挪到并行队列里就破坏了语义。
4.2 内置工具一个都没标
这是本章最重要的一个发现。八个内置工具的 ToolDefinition 里,没有任何一个设置 executionMode。搜遍 core/tools/*.ts,executionMode 只出现在 tool-definition-wrapper.ts 的两行透传里。
也就是说:两个 write 同时打同一个文件,是并行开始的。
想亲眼看它变成串行,把该工具的 executionMode 改成 "sequential"(取值只有 "sequential" | "parallel" 两个,见 agent/src/types.ts:47),再跑同一批调用——第①段的 tool_execution_start 会从"几乎同时"变成"依次"。不改,就永远是并行的。
那为什么不打架?
4.3 并行批次其实分三段,只有中间一段是并行的
上一节容易让人以为"并行 = 全部 Promise.all"。看 executeToolCallsParallel(:596-670)会发现是三段:
第①段 串行登记 依次 emit start、依次 prepare第②段 并行执行 全部闭包一起开跑第③段 串行收口 按原顺序 emit 结果消息第①段是 for 循环里 await prepareToolCall——准备是串行的。代价是准备慢的调用会推迟后面的登记,收益是 tool_execution_start 事件的顺序永远等于模型给的顺序(这对 TUI 渲染很重要)。
第②段的写法值得看:
finalizedCalls.push(async () => { const executed = await executePreparedToolCall( preparation, signal, emitToolExecutionUpdate(toolCall, emit)); const finalized = await finalizeExecutedToolCall( currentContext, assistantMessage, preparation, executed, config, signal); return finalized;});推入的是闭包,不是 promise。循环期间一个都没启动,直到 Promise.all 才一起 entry():
const orderedFinalizedCalls = await Promise.all( finalizedCalls.map((entry) => typeof entry === "function" ? entry() : Promise.resolve(entry)),);这个"先登记、后开跑"的顺序保证了启动时刻接近。如果边登记边启动,第一个工具可能已经跑完,第八个才开始,那就不是并行了。
第③段最简单也最重要:
for (const finalized of orderedFinalizedCalls) { const toolResultMessage = createToolResultMessage(finalized); await emitToolResultMessage(toolResultMessage, emit); messages.push(toolResultMessage);}Promise.all 保留数组顺序,所以结果消息的顺序 = 模型给的顺序,与谁先跑完无关。
为什么强调这点?因为 transcript 是有序的。如果结果按完成顺序推入,同一个 transcript 重放两次会得到不同的消息序列——M10 的会话恢复、M09 的压缩都会跟着出现非确定性。并发可以乱,落盘不能乱。
五、两个工具同时改一个文件,怎么不打架
答案在 file-mutation-queue.ts,全文 61 行。这是整个工具目录里最值得读的文件。
5.1 按路径分片的串行锁
核心函数(:32-61):
export async function withFileMutationQueue<T>( filePath: string, fn: () => Promise<T>,): Promise<T> { const registration = registrationQueue.then(async () => { const key = await getMutationQueueKey(filePath); const currentQueue = fileMutationQueues.get(key) ?? Promise.resolve(); let releaseNext!: () => void; const nextQueue = new Promise<void>((r) => { releaseNext = r; }); const chainedQueue = currentQueue.then(() => nextQueue); fileMutationQueues.set(key, chainedQueue); return { key, currentQueue, chainedQueue, releaseNext }; }); // ...}不熟悉 promise 链的读法是这样的:
文件 A: [调用 1 执行中]──→[调用 2 执行中]──→[调用 3]文件 B: [调用 4 执行中] ← 与 A 完全无关chainedQueue = currentQueue.then(() => nextQueue) 是排队:新来的调用把自己的 nextQueue 接在上一个的尾巴后面。而 await currentQueue(:52)就是"等我前面那个走完"。
关键在于 fileMutationQueues 是一个 Map<路径, Promise>。每个路径一条链,不同路径互不阻塞。 这就是"按 key 分片的互斥锁"(sharded mutex)。
如果换成全局一把锁,那"读 A 文件"和"写 B 文件"也得排队——并发度直接掉到 1。
5.2 三个不显眼的细节
细节一:key 不是入参,是 realpath。
async function getMutationQueueKey(filePath: string): Promise<string> { const resolvedPath = resolve(filePath); try { return await realpath(resolvedPath); } catch (error) { if (isMissingPathError(error)) return resolvedPath; throw error; }}为什么要 realpath?因为下面四条路径指向同一个文件,但字符串完全不同:
./src/../src/a.tssrc/a.ts/abs/path/src/a.ts/abs/path/src/lnk.ts ← 软链接指向 a.tsrealpath 把它们归一到同一个 key,锁才真正互斥。而 ENOENT / ENOTDIR 时退回 resolvedPath——因为新建文件还没有 realpath 可解析,这一步不 fallback 就没法给"写新文件"上锁。
细节二:注册本身也要串行。
registrationQueue(:5)是一个全局串行队列,只包住"读 Map-算链-写 Map"这三步。为什么需要它?
因为两个调用同时进来时,可能都读到旧的 fileMutationQueues.get(key),于是各自建了一条新链,互相不知道对方存在——锁就漏了。这和"自举一个锁需要另一把锁"是同一个问题。
注意它的写法:
registrationQueue = registration.then( () => undefined, () => undefined,);两个 () => undefined 把成功和失败都吞掉。注册队列不能因为一次注册失败就永久卡死。
细节三:最后一个走的负责清理。
} finally { releaseNext(); if (fileMutationQueues.get(key) === chainedQueue) { fileMutationQueues.delete(key); } }releaseNext() 放行后面的;然后检查"我是不是这条链的尾巴"——是的话从 Map 里删掉。不删的话,长会话里每个改过的文件都会在 Map 里留一个已完成的 promise,内存只增不减。
=== chainedQueue 这个判断不能省:如果在我之后又来了一个调用,Map 里存的就变成新的 chainedQueue 了,这时删掉会把别人的锁弄丢。
5.3 中止与锁的冲突
write.ts:66-73 和 edit.ts:160-167 有段一模一样的注释,是这段代码里最老练的一笔:
Do not reject from an abort event listener here: that would release the mutation queue while an in-flight filesystem operation may still finish. Checking
signal.abortedafter eachawaitobserves the same aborts while keeping the queue locked until the current operation has settled.
翻译成大白话:不要在 abort 事件里直接 reject,因为 reject 会让 finally 立刻放锁——但此时磁盘写入可能还没完。放锁之后下一个 write 冲进来,就和上一笔未完成的写交错,文件就坏了。
所以写法是"每个 await 之后查一次":
const throwIfAborted = (): void => { if (signal?.aborted) throw new Error("Operation aborted");};throwIfAborted();await ops.mkdir(dir);throwIfAborted();await ops.writeFile(absolutePath, content);throwIfAborted();中止的响应变慢了一个 await,换来的是锁只在操作真正落定后才释放。这是一个明确的取舍:宁可晚 5 毫秒停下,也不要留下半个文件。
六、永不抛出:错误也是一条消息
6.1 三层 try/catch,一个出口
prepareToolCall 的 try 包住了"找工具 → 垫片 → 校验 → 钩子"(:735-786),executePreparedToolCall 包住了 tool.execute(:841-866),finalizeExecutedToolCall 又包住了 afterToolCall(:881-911)。
三处 catch 的产物完全一样:
return { result: createErrorToolResult(message), isError: true, durationMs,};runToolCall(:821-829)的注释把契约写死了:
Never rejects for tool failures: unknown tools, validation errors, blocked calls, and thrown errors come back as
isError: true.
工具失败不 reject。 七种失败,一种产物。
七种精确列出来,都在 agent-loop.ts:
| # | 失败点 | 位置 | 错误消息 |
|---|---|---|---|
| 1 | 工具不存在 | :727 |
Tool X not found |
| 2 | 垫片抛错 | :780 |
原异常 message |
| 3 | schema 校验失败 | :780 |
同上(同一个 catch) |
| 4 | 钩子前中止 | :748 |
Operation aborted |
| 5 | 被钩子拦下 | :755 |
Tool execution was blocked |
| 6 | 执行抛错 | :855 |
原异常 message |
| 7 | afterToolCall 抛错 |
:908 |
原异常 message |
第 2、3 条共用一个 catch,因为它们都在同一个 try 里——垫片和校验的失败在调用方看来是同一回事。 模型不需要区分"JSON 形状不对"和"少传了 path",它只需要知道"参数不行,重来"。
6.2 错误标志是"平行字段"
注意 createErrorToolResult(:922-927)返回的对象里没有 isError:
function createErrorToolResult(message: string): AgentToolResult<any> { return { content: [{ type: "text", text: message }], details: {}, };}isError 是调用方在外面单独设的。这个设计有代价:任何收窄的地方都可能把 isError 丢掉。所以 finalizeExecutedToolCall 里要写 let isError = executed.isError;,钩子改结果时还要 isError = afterResult.isError ?? isError;。
为什么不用一个带 isError 的函数?因为 afterToolCall 钩子可能把错误结果改成成功(比如重试后成功),也可能反过来。把"是不是错误"和"结果内容"分开,钩子才能独立改其中一个。
6.3 为什么"伪造成消息"是最优解
三个候选方案,对比一下:
| 方案 | 模型能看到错误吗 | 循环会中断吗 | 重放能还原吗 |
|---|---|---|---|
| 抛异常到顶层 | 不能 | 会 | 不能 |
返回 null |
不能 | 不会 | 不能 |
isError: true 的消息 |
能 | 不会 | 能 |
模型看到错误消息,下一轮会自己调整参数——这是 Agent 自愈能力的来源。而"消息"意味着进 transcript,M03 的"变更即追加"和 M09 的压缩都能把它当正常数据对待。
七、截断三姊妹:2000 行 / 50KB
工具输出不能无限往上下文里塞。truncate.ts(314 行)定了两条独立上限,谁先到谁赢:
export const DEFAULT_MAX_LINES = 2000;export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KBexport const GREP_MAX_LINE_LENGTH = 500;三个函数,对应三种"该保哪一头":
| 函数 | 保哪里 | 谁用 | 理由 |
|---|---|---|---|
truncateHead |
开头 | read |
读文件通常从头看 |
truncateTail |
结尾 | bash |
命令的结论在最后(报错也在最后) |
truncateMiddle |
首尾各半 | codemode 脚本 | 只关心开头和结局 |
7.1 永远不返回半行
这是三条规则中最容易忽略、也最容易被破坏的一条。文件头注释(:8)写的是 "Never returns partial lines (except bash tail truncation edge case)"。
为什么较真?因为半行会破坏行号。如果第 2000 行被切成 function foo(a, b,那模型后续用 offset=2001 接着读,从中间断的地方开始,行号全错一位。read.ts 的续读提示依赖 truncation.outputLines,这个数必须是完整行数。
唯一的例外是 truncateTail 的"最后一行本身就超 50KB"——此时连一行都放不下,只能取尾部字节。这时会置 lastLinePartial: true,让上层输出一条特殊提示(bash.ts:345-347):
[Showing last 12.3KB of line 5000 (line is 3.4MB). Full output: /tmp/pi-bash-xxxx.log]降级可以,但必须让读者知道降级了。 这是"标志位 + 提示语"的双重保险。
7.2 第一行就超限怎么办
truncateHead 有个专门分支(:105-119):如果第一行就超过 50KB,返回空 content,并把 firstLineExceedsLimit 置为 true。
read.ts:178-182 接住这个标志,输出一条能直接执行的替代方案:
[Line 123 is 3.2MB, exceeds 50KB limit. Use bash: sed -n '123p' big.log | head -c 51200]这是整章我最喜欢的一处设计。它不是告诉模型"失败了",而是告诉模型"换个方法,这条命令能行"。
7.3 字节边界要按字符切
truncate.ts:257 这几行是处理中文的关键:
let start = buf.length - maxBytes;while (start < buf.length && (buf[start] & 0xc0) === 0x80) { start++;}UTF-8 里 10xxxxxx 是续字节(不是字符开头)。从中间切会把一个汉字劈开,解码后得到一串替换字符 U+FFFD(Unicode 用它标记"这段字节解不出来")。这段循环往前挪到真正的字符边界。
& 0xc0 === 0x80 这个判断在本章会出现三次(truncate.ts、output-accumulator.ts 两处),是 UTF-8 处理的通用手法——按字节限流,但按字符切。
7.4 搜索类工具:条数上限兜底,字节只兜底
grep / find / ls 不用行数限制,因为它们的输出行数本来就由条数决定了:
| 工具 | 默认条数 | 超限提示 |
|---|---|---|
grep |
100 条匹配(DEFAULT_LIMIT) |
Use limit=200 for more, or refine pattern |
find |
1000 个结果 | Use limit=2000 for more, or refine pattern |
ls |
500 个条目 | Use limit=1000 for more |
所以它们调 truncateHead 时传的是 maxLines: Number.MAX_SAFE_INTEGER(grep.ts:283、find.ts:146、ls.ts:140)——行数上限等于关掉,只留 50KB 字节兜底。
为什么还要留字节兜底?因为单行可能极长。一个 min.js 匹配到的一行可能有几百 KB,100 条这样的行远超 50KB。这时 truncateHead 会按字节截,truncatedBy 是 "bytes" 而不是 "lines"。
grep 还有第二道:单行先过 truncateLine,超过 500 字符切成 ... [truncated],并置 linesTruncated,最后统一提示:
Some lines truncated to 500 chars. Use read tool to see full lines注意最后半句——它指向了另一个工具。 工具之间互相指路,比"失败"有用得多。
ls 的注释(:139)把逻辑说得很直白:
Apply byte truncation. There is no separate line limit because entry count is already capped.
两层上限,能合并的时候就合并,不能就必须两格都在。 合并的前提是"一个是另一个的严格更紧的约束"——条目数已封顶,行数就不会超,所以关掉行数是对的。
八、流式输出怎么不撑爆内存
bash 的问题和 read 不同:read 是一次拿到整个文件,bash 是边跑边出。一条 npm install 可能吐 200MB。
output-accumulator.ts(257 行)的答案:只留尾巴,超了就落盘。
8.1 三件事同时做
append(data: Buffer): void { if (this.finished) throw new Error("Cannot append to a finished"); this.totalRawBytes += data.length; this.appendDecodedText(this.decoder.decode(data, { stream: true })); if (this.tempFileStream || this.shouldUseTempFile()) { this.ensureTempFile(); this.tempFileStream?.write(data); } else if (data.length > 0) { this.rawChunks.push(data); }}三件事:统计总量、解码成文本(只留尾巴)、决定要不要落盘。
{ stream: true } 是必须的。 chunk 边界可能正好落在汉字的三个字节中间,一次性解码会出乱码。TextDecoder 的 streaming 模式会把不完整的尾巴留着,等下一个 chunk 补上。
maxRollingBytes = maxBytes * 2(:60):尾巴留两倍余量,因为 truncateTail 之后还要按行切,切完可能不够了。
8.2 落盘之后的读法
一旦超限就切到临时文件,rawChunks 全部写进去并清空(:252-255)。之后内存占用就恒定了——只保留尾巴那一小段文本。
readFullOutput(maxBytes)(:149-176)读文件时也是"首尾各一半 + 中间省略标记":
const omitted = size - headBytes - tailBytes;return { content: `${headText}\n\n[... ${omitted} bytes omitted ...]\n\n${tailText}`, truncated: true,};bash 给模型的输出是 50KB(截断尾部),给 codemode 脚本的 structuredContent 是 1MB(首尾各半)。同一个命令,两个消费者,两种预算。
8.3 闸门模式:关了就一律不收
bash.ts 里有个 acceptingOutput 变量(:276),finishOutput() 第一件事就是把它置 false(:328)。agent-loop.ts:837 的 executePreparedToolCall 里有同名的 acceptingUpdates。
这是同一个模式,本章出现两次:
开始 → 闸门开 → 数据随便进结束 → 闸门关 → 之后来的全部丢弃为什么需要?因为进程退出和 stdout 关闭不是同时发生的。子进程已经 exit,但管道里还有缓冲数据在路上,晚到的 data 事件如果还被接受,就会污染已经定稿的结果。
agent-loop.ts:846-849 那几行更细:
(partialResult) => { if (!acceptingUpdates) return; updateEvents.push(Promise.resolve(onUpdate(partialResult)));},它不只丢弃,还把进行中的 update 收集成 Promise,在 await Promise.all(updateEvents) 之后才返回。保证"最后一个 update"一定在结果之前到达消费者,不会出现"结果已经渲染完了,界面又被一个迟到的进度覆盖"。
九、编辑的三个编码暗坑
edit.ts 只有 217 行,但有三处防的是真实事故。
9.1 BOM
// Strip BOM before matching. The model will not include an// invisible BOM in oldText.const { bom, text: content } = splitBom(rawContent);Windows 上很多文件带 UTF-8 BOM(\uFEFF)。模型看不到它,也绝不会在 oldText 里写它。所以匹配前必须剥掉,写回时再拼上(:194:const finalContent = bom + restoreLineEndings(...))。
不剥 → oldText 永远匹配不到,模型会反复重试同一处。
剥了不拼回 → 文件 BOM 被静默删掉,Git diff 里出现一行"整文件重写"。
9.2 行尾符
const originalEnding = detectLineEnding(content);const normalizedContent = normalizeToLF(content);const { baseContent, newContent } = applyEditsToNormalizedContent(normalizedContent, edits, path);CRLF 文件里,模型给的多行 oldText 通常是 LF。直接匹配必然失败。所以:记原行尾 → 转成 LF → 改 → 转回去。
这也是"改一个字却整文件 diff"的常见成因:如果你不记录原行尾,写回时统一成 LF,整个文件每一行都会变。
9.3 路径变体
path-utils.ts(118 行)里有五连试探,全是 macOS 的坑:
function tryMacOSScreenshotPath(filePath: string): string { return filePath.replace(/ (AM|PM)\./gi, `${NARROW_NO_BREAK_SPACE}$1.`);}macOS 截图文件名用的是窄不换行空格(U+202F)而不是普通空格;文件名存的是 NFD 分解形式;法语系统截图里的撇号是 U+2019 而不是 '。
用户手打出来的路径必然对不上。于是 resolveReadPath 依次试:原路径 → AM/PM 变体 → NFD 变体 → 弯引号变体 → NFD+弯引号组合。
这些不是洁癖,是"用户报了文件名,你找不到,他就以为工具坏了"。
十、Operations 抽象:工具不直接碰系统
每个工具都定义了一个 XxxOperations 接口,把系统能力抽出来:
export interface WriteOperations { writeFile: (absolutePath: string, content: string) => Promise<void>; mkdir: (dir: string) => Promise<void>;}注释都一样:Override these to delegate file writing to remote systems (for example SSH).
这个抽象带来三件事:
- 可测:
write的行为测试不需要真写磁盘 - 可远程:SSH 场景下换掉
operations,工具的 schema、截断、锁全都照旧 - 可嵌壳:
bash.ts的spawnHook(:183)能在命令执行前改写 command / cwd / env,这是扩展拦截user_bash的入口
但要注意抽象的粒度:每个工具声明自己需要的最小集合。write 只要 writeFile + mkdir,edit 要 readFile + writeFile + access。没有一个"万能 FileSystem 接口"——那样每个实现方都得把用不到的方法也实现一遍。
十一、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。
实验 1:确认八个工具。
# 在仓库根目录执行cd packages/coding-agent/src/core/toolssed -n '93,105p' index.tsToolName 八个 + allToolNames 八个,两者必须同步——漏一个就会在 createToolDefinition 的 default 分支抛 Unknown tool name。
实验 2:确认没有工具声明 sequential。
grep -rn "executionMode" *.ts只有 tool-definition-wrapper.ts 的两行透传。零命中就是答案:内置工具全部走并行调度。
实验 3:看锁的粒度。
grep -n "fileMutationQueues" file-mutation-queue.ts四处:声明、读、写、删。一个 Map<string, Promise<void>> 就是全部状态。
实验 4:验证"永远不还半行"。
node -e "const {truncateHead} = require('./dist/core/tools/truncate.js');const big = Array.from({length:5000}, (_,i)=>'line '+(i+1)).join('\n');const r = truncateHead(big, {maxLines:10});console.log(r.outputLines, r.truncatedBy, JSON.stringify(r.content.split('\n').pop()));"outputLines 应该是 10,最后一行是完整的 line 10。(需要先 build。)
实验 5:数一数截断的出现次数。
grep -c "0xc0) === 0x80" truncate.ts output-accumulator.ts两次和一次。这个模式只出现在"按字节往回退到字符边界"的地方。
实验 6:读出工具的提示词贡献。
grep -rn "SystemPromptContribution" *.ts | headSelect-String -Path *.ts -Pattern 'SystemPromptContribution' | Select-Object -First 10八个工具各有一段。这些就是模型"知道该用哪个工具"的全部依据。
实验 7:改一处试试——改掉模型看到的那一行。
- 改哪里
bash.ts:45,把snippet换成"Run shell commands"。 - 预期 打印
bashToolSystemPromptContribution.snippet, 从Execute bash commands (ls, grep, find, etc.)变成Run shell commands(本机实测)。 - 连带
bash.ts:421把它接进promptSnippet,最终进系统提示词 的工具清单(M08 §三)。它不影响工具能不能跑,只影响模型「会不会想起来 用它」——最容易改、最难量化的一行。有快照测试就会报 diff。 - 回滚 改回原字符串。
两行脚本就能看结果(跑法用 M01 §8.2 那条 --import 命令):
import { bashToolSystemPromptContribution as c } from "./packages/coding-agent/src/core/tools/bash.ts";console.log(c.snippet);实验 8(破坏性):把文件锁拆成一把全局锁,看它先坏在哪。(改法实测于 v1.4.0,性能数字未实跑:需要一次真模型会话才能测出耗时差)
- 改哪里
core/tools/file-mutation-queue.ts的getMutationQueueKey,把"按realpath分片"降级成常量——所有文件共用一条链:
async function getMutationQueueKey(filePath: string): Promise<string> { void filePath; // 不再区分文件 return "__global__";}- 预期 正确性不会坏(依然互斥),坏的是并发度:同时
writeA 和 B, 第二个要等第一个整个execute跑完。串行化对模型完全透明——它只感觉 "工具变慢了",你看日志也看不出异常。 - 连带
read不走这把锁(只写工具走),"读 A 同时写 B"不受影响; 被拉平的是 8 个工具里的两个写工具。若改成直接await fn()(彻底去锁), 同一文件两笔写会交错:先截断后写的那笔被后一笔的截断打断,磁盘上留下 半个文件;edit的读-改-写则丢掉其中一次修改。 - 回滚 把
getMutationQueueKey改回realpath版本(§5.2 那段代码)。
十二、工程暗坑
1. 用 promise 链做锁,别忘了 finally。
withFileMutationQueue 里如果 fn() 抛了而你没在 finally 里 releaseNext(),这条文件链永久阻塞——后续所有对该文件的写都会挂住,而且看日志完全看不出原因(进程还活着,只是不干活)。任何基于 promise 链的锁,放锁必须在 finally。
2. realpath 会因文件不存在而抛。
getMutationQueueKey 必须捕获 ENOENT / ENOTDIR 并退回 resolve() 结果,否则"写新文件"这个最常见的场景直接失败。
3. 不要在 abort 监听里 reject。
见 5.3。放锁早于操作结束 = 下一笔写和上一笔未完成的写交错。
4. truncateHead 对超长首行返回空字符串。
不要以为"有 content 就是成功"。content === "" 且 firstLineExceedsLimit === true 是合法状态,必须单独处理。
5. 非零退出码不是异常。
bash.ts:399-406 里 exitCode !== 0 返回的是 isError: true 的正常结果,不是 reject。而对 codemode 脚本,structuredContent.exit_code 照旧给出——同一个事实,对模型是"失败",对脚本是"数据"。
6. 进程退出了,stdio 可能还连着。
bash.ts:145-147 用 waitForChildProcess 而不是裸 once("exit"),注释写着 "without hanging on inherited stdio handles held by detached descendants"。子 shell 拉起的后台进程继承了 stdout,父进程 exit 之后管道不关,只等 exit 会卡死。
7. PowerShell 输出默认不是 UTF-8。
powershell.ts:16 那一行前缀就是补丁:
const UTF8_OUTPUT_PREFIX = "try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n";没有它,中文输出在 Windows 上会变问号。这不是 Pi 的 bug,是 PowerShell 5.1 的默认编码。
8. grep 不能读用户的 ripgrep 配置。
grep.ts:161 用了 --no-config,注释说工具契约不能依赖用户配置。如果用户的 ~/.ripgreprc 加了 --max-columns 或者改了输出格式,工具解析就崩了。包装外部命令时,先把它变成"可预测的机器"。
十三、四个可以带走的方法
方法一:锁的粒度选"业务主键",不选"全局"。
fileMutationQueues 用文件路径当 key。如果换成全局锁,正确性一分不差,吞吐量掉到 1/8(八个工具只能一个个来)。
写并发控制时先问:这次冲突到底发生在哪个对象上? 那个对象的标识,就是锁的 key。
方法二:给"降级"配一个标志位,别让它沉默。
truncated / truncatedBy / lastLinePartial / firstLineExceedsLimit / matchLimitReached / entryLimitReached——六个标志位,每个都对应一句给模型的提示。
降级本身不是问题,静默降级才是。模型不知道数据被截断了,就会基于不完整的信息下结论。
方法三:错误信息要写成"下一步能做什么"。
对比两种写法:
✗ File too large to read.✓ [Line 123 is 3.2MB, exceeds 50KB limit. Use bash: sed -n '123p' big.log | head -c 51200]第二种模型能直接照做。工具报错的读者是模型,不是人。
方法四:让"关闸"成为结束流程的第一件事。
acceptingOutput = false 在 finishOutput() 第一行;acceptingUpdates = false 在拿到结果后的第一件事。晚到的数据不会污染已定稿的结果。
任何"流式 + 有一个终点"的系统都需要这一行。
本章小结
- 八个工具,每个都有四张脸:定义 / schema / 执行 / 呈现。
- 五步管道把参数校验、执行、截断、结果、记账串成一条线。
- 默认整批并行;一个
sequential就把整批降级成串行。 - 写锁按文件路径分片,粒度是文件,不是全局。
- 截断必须留标志位;静默降级才是真的坏降级。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 四层类型 | 定义 / 参数 schema / 执行 / 呈现 | §二 |
| 五步管道 | 预检 → 执行 → 截断 → 结果 → 记账 | §三 |
| 一票否决 | 一个 sequential 拖住整批 |
§四 |
| 文件锁 | 按 realpath 分片的 promise 链 |
§五 |
| 六个标志位 | truncated 等,防静默降级 |
§七 |
练习
练习 1(读):§十二 坑 5 说 exitCode !== 0 是正常结果而不是异常。
如果某个工具真的把异常抛出了循环,下一次请求会看到什么?
→ 回 §六 与 M03 §十 找"失败也是消息"的归口。
练习 2(改):照 §十一 实验 8 把 getMutationQueueKey 改成常量
"__global__"。预期:正确性不坏,并发度掉到 1;回滚:改回 realpath 版。
常见误区
- 你会以为 截断只是少给点数据;实际是 必须同时回一句"被截断了"; 证据 §七 的六个标志位。
- 你会以为 工具描述写得越长模型越听话;实际是 四层类型各管一摊, 描述只占一层;证据 §二 的四张脸。
- 你会以为 非零退出码就是异常;实际是 它是
isError: true的正常结果; 证据 §十二 坑 5。
读完自检
三条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| 两个工具同时改一个文件,怎么不打架? | 按文件路径分片的串行锁,粒度是文件不是全局 | §五 |
| 模型一次调八个工具,并行还是串行? | 整批并行:八个内置工具一个都没标 executionMode,而默认值就是 "parallel";要串行必须显式标 "sequential" |
§四 |
| 工具报错的读者是谁? | 模型,不是人;所以要写成"下一步能做什么" | §六、§十三 |
下一步
工具能跑了,但它们说的话要进 transcript——一条 ToolResultMessage,带 toolCallId、isError、可能还有图片。
M03 讲过工具结果是"挂在 user 消息里"还是"独立 role: "tool""是 provider 差异。那 Pi 内部到底用哪种?消息类型分几层?
下一章打开消息系统。
本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/coding-agent/src/core/tools/index.ts |
225 | ToolName :95、三套预设 :164-224 |
packages/coding-agent/src/core/tools/file-mutation-queue.ts |
62 | 全文,尤其 :32-61 |
packages/coding-agent/src/core/tools/truncate.ts |
315 | 常量 :11-13、truncateHead :78-160、字节边界 :247-262 |
packages/coding-agent/src/core/tools/output-accumulator.ts |
258 | append :64-78、readFullOutput :149-176 |
packages/coding-agent/src/core/tools/bash.ts |
442 | 进程树 :96-165、闸门 :321-335、退出码 :385-407 |
packages/coding-agent/src/core/tools/write.ts |
97 | 锁 + abort :66-88 |
packages/coding-agent/src/core/tools/edit.ts |
218 | 垫片 :100-131、BOM/行尾 :187-195 |
packages/coding-agent/src/core/tools/read.ts |
224 | 续读提示 :175-202、中止 :110-119 |
packages/coding-agent/src/core/tools/path-utils.ts |
119 | macOS 五连 :52-84 |
packages/coding-agent/src/core/tools/tool-definition-wrapper.ts |
78 | 双向转换 :27-77 |
packages/agent/src/agent-loop.ts |
960 | 五步管道 :704-920、一票否决 :518-533 |
packages/agent/src/types.ts |
— | ToolExecutionMode :47 |