Pi Agent 源码级教程
M05

工具系统 —— 八个工具,一道文件锁

7,210 字 · 含 225 行代码 · 约 35 分钟

M04 结尾留下的问题是:模型返回一个 toolCall——一个名字、一段 JSON,谁去执行?

答案在 coding-agent/src/core/tools/。这个目录 16 个文件、3,662 行,看起来平平无奇,但它要回答三个很难的问题:

  • 模型给的参数可能不合 schema、可能是坏 JSON、可能根本不存在的工具名,怎么办
  • 模型一次调八个工具,并行还是串行
  • 两个工具同时改同一个文件,怎么不打架

第三个问题的答案是本章的核心。先说结论:按文件路径分片的串行锁,粒度是文件,不是全局。


零、读这章之前,你需要先知道一件事

工具调用(tool call):模型只能输出文字。工具是它唯一能"动手"的地方—— 它写一段结构化的请求(调哪个、什么参数),由宿主去执行,结果再塞回上下文。

没有它会怎样:你会把它当函数调用(以为模型在自己执行代码),于是看不懂 "它为什么又调了一遍同一个工具":因为结果不是你给的,是宿主回填的。

本书哪里用到:§一 八工具表;循环里那次 tool_execution_start 在 M03 §六。


一、八个工具,一张台账

ToolName 正好八个取值(index.ts:95):

ts
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 三种体格

看行数分布就会发现三个档位:

text
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 对象:

ts
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,最终成为提示词的一部分:

text
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 四张脸各管什么

text
ToolDefinition   产品层:带 promptSnippet / renderers / 状态机     ↕ wrapToolDefinition / createToolDefinitionFromAgentToolAgentTool        内核层:@earendil-works/pi-agent-core 认识的形状     ↕ TypeBoxAgentTool静态类型          Static<typeof schema>:TypeBox 推导出的参数类型

而 Tool 是 AgentTool<any> 的别名(index.ts:93):

ts
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:

ts
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):

ts
export function createWriteTool(	cwd: string,	options?: WriteToolOptions,): TypeBoxAgentTool<typeof writeSchema> {

为什么不直接写 AgentTool?tool-definition-wrapper.ts:5-9 的注释解释了原因:

pi-agent-core types params through pi-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,中间有五步。这张图可以当目录用:

text
模型吐 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):

ts
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 的注释是这一层的存在理由:

ts
// 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 全文就九行:

ts
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)会发现是三段:

text
第①段  串行登记      依次 emit start、依次 prepare第②段  并行执行      全部闭包一起开跑第③段  串行收口      按原顺序 emit 结果消息

第①段是 for 循环里 await prepareToolCall——准备是串行的。代价是准备慢的调用会推迟后面的登记,收益是 tool_execution_start 事件的顺序永远等于模型给的顺序(这对 TUI 渲染很重要)。

第②段的写法值得看:

ts
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():

ts
const orderedFinalizedCalls = await Promise.all(	finalizedCalls.map((entry) =>		typeof entry === "function" ? entry() : Promise.resolve(entry)),);

这个"先登记、后开跑"的顺序保证了启动时刻接近。如果边登记边启动,第一个工具可能已经跑完,第八个才开始,那就不是并行了。

第③段最简单也最重要:

ts
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):

ts
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 链的读法是这样的:

text
文件 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。

ts
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?因为下面四条路径指向同一个文件,但字符串完全不同:

text
./src/../src/a.tssrc/a.ts/abs/path/src/a.ts/abs/path/src/lnk.ts     ← 软链接指向 a.ts

realpath 把它们归一到同一个 key,锁才真正互斥。而 ENOENT / ENOTDIR 时退回 resolvedPath——因为新建文件还没有 realpath 可解析,这一步不 fallback 就没法给"写新文件"上锁。

细节二:注册本身也要串行。

registrationQueue(:5)是一个全局串行队列,只包住"读 Map-算链-写 Map"这三步。为什么需要它?

因为两个调用同时进来时,可能都读到旧的 fileMutationQueues.get(key),于是各自建了一条新链,互相不知道对方存在——锁就漏了。这和"自举一个锁需要另一把锁"是同一个问题。

注意它的写法:

ts
registrationQueue = registration.then(	() => undefined,	() => undefined,);

两个 () => undefined 把成功和失败都吞掉。注册队列不能因为一次注册失败就永久卡死。

细节三:最后一个走的负责清理。

ts
	} 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.aborted after each await observes the same aborts while keeping the queue locked until the current operation has settled.

翻译成大白话:不要在 abort 事件里直接 reject,因为 reject 会让 finally 立刻放锁——但此时磁盘写入可能还没完。放锁之后下一个 write 冲进来,就和上一笔未完成的写交错,文件就坏了。

所以写法是"每个 await 之后查一次":

ts
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 的产物完全一样:

ts
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:

ts
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 行)定了两条独立上限,谁先到谁赢:

ts
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):

text
[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 接住这个标志,输出一条能直接执行的替代方案:

text
[Line 123 is 3.2MB, exceeds 50KB limit. Use bash: sed -n '123p' big.log | head -c 51200]

这是整章我最喜欢的一处设计。它不是告诉模型"失败了",而是告诉模型"换个方法,这条命令能行"。

7.3 字节边界要按字符切

truncate.ts:257 这几行是处理中文的关键:

ts
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,最后统一提示:

text
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 三件事同时做

ts
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)读文件时也是"首尾各一半 + 中间省略标记":

ts
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。

这是同一个模式,本章出现两次:

text
开始 → 闸门开 → 数据随便进结束 → 闸门关 → 之后来的全部丢弃

为什么需要?因为进程退出和 stdout 关闭不是同时发生的。子进程已经 exit,但管道里还有缓冲数据在路上,晚到的 data 事件如果还被接受,就会污染已经定稿的结果。

agent-loop.ts:846-849 那几行更细:

ts
(partialResult) => {	if (!acceptingUpdates) return;	updateEvents.push(Promise.resolve(onUpdate(partialResult)));},

它不只丢弃,还把进行中的 update 收集成 Promise,在 await Promise.all(updateEvents) 之后才返回。保证"最后一个 update"一定在结果之前到达消费者,不会出现"结果已经渲染完了,界面又被一个迟到的进度覆盖"。


九、编辑的三个编码暗坑

edit.ts 只有 217 行,但有三处防的是真实事故。

9.1 BOM

ts
// 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 行尾符

ts
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 的坑:

ts
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 接口,把系统能力抽出来:

ts
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).

这个抽象带来三件事:

  1. 可测:write 的行为测试不需要真写磁盘
  2. 可远程:SSH 场景下换掉 operations,工具的 schema、截断、锁全都照旧
  3. 可嵌壳: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:确认八个工具。

bash
# 在仓库根目录执行cd packages/coding-agent/src/core/toolssed -n '93,105p' index.ts

ToolName 八个 + allToolNames 八个,两者必须同步——漏一个就会在 createToolDefinition 的 default 分支抛 Unknown tool name。

实验 2:确认没有工具声明 sequential。

bash
grep -rn "executionMode" *.ts

只有 tool-definition-wrapper.ts 的两行透传。零命中就是答案:内置工具全部走并行调度。

实验 3:看锁的粒度。

bash
grep -n "fileMutationQueues" file-mutation-queue.ts

四处:声明、读、写、删。一个 Map<string, Promise<void>> 就是全部状态。

实验 4:验证"永远不还半行"。

bash
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:数一数截断的出现次数。

bash
grep -c "0xc0) === 0x80" truncate.ts output-accumulator.ts

两次和一次。这个模式只出现在"按字节往回退到字符边界"的地方。

实验 6:读出工具的提示词贡献。

bash
grep -rn "SystemPromptContribution" *.ts | head
powershell
Select-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 命令):

ts
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 分片"降级成常量——所有文件共用一条链:
ts
async function getMutationQueueKey(filePath: string): Promise<string> {	void filePath;          // 不再区分文件	return "__global__";}
  • 预期 正确性不会坏(依然互斥),坏的是并发度:同时 write A 和 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 那一行前缀就是补丁:

ts
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——六个标志位,每个都对应一句给模型的提示。

降级本身不是问题,静默降级才是。模型不知道数据被截断了,就会基于不完整的信息下结论。

方法三:错误信息要写成"下一步能做什么"。

对比两种写法:

text
✗  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 在拿到结果后的第一件事。晚到的数据不会污染已定稿的结果。

任何"流式 + 有一个终点"的系统都需要这一行。


本章小结

  1. 八个工具,每个都有四张脸:定义 / schema / 执行 / 呈现。
  2. 五步管道把参数校验、执行、截断、结果、记账串成一条线。
  3. 默认整批并行;一个 sequential 就把整批降级成串行。
  4. 写锁按文件路径分片,粒度是文件,不是全局。
  5. 截断必须留标志位;静默降级才是真的坏降级。

概念回顾

术语 一句话 在哪
四层类型 定义 / 参数 schema / 执行 / 呈现 §二
五步管道 预检 → 执行 → 截断 → 结果 → 记账 §三
一票否决 一个 sequential 拖住整批 §四
文件锁 按 realpath 分片的 promise 链 §五
六个标志位 truncated 等,防静默降级 §七

练习

练习 1(读):§十二 坑 5 说 exitCode !== 0 是正常结果而不是异常。 如果某个工具真的把异常抛出了循环,下一次请求会看到什么? → 回 §六 与 M03 §十 找"失败也是消息"的归口。

练习 2(改):照 §十一 实验 8 把 getMutationQueueKey 改成常量 "__global__"。预期:正确性不坏,并发度掉到 1;回滚:改回 realpath 版。

常见误区

  1. 你会以为 截断只是少给点数据;实际是 必须同时回一句"被截断了"; 证据 §七 的六个标志位。
  2. 你会以为 工具描述写得越长模型越听话;实际是 四层类型各管一摊, 描述只占一层;证据 §二 的四张脸。
  3. 你会以为 非零退出码就是异常;实际是 它是 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