深入理解 pi/第 02 章
「4 个工具」是半个真相
pi 常被概括为「只有 4 个工具」。这个说法不算错,但它说的是一个子集。实际工具面是三档,按角色划分:
| 构造函数 | 数量 | 成员 |
|---|---|---|
createCodingToolDefinitions |
4 | read · bash · edit · write |
createReadOnlyToolDefinitions |
4 | read · grep · find · ls |
createAllToolDefinitions |
8 | 上面两者并集 + powershell |
注意 read 同时出现在两个集合里——这不是冗余,而是刻意的:只读集合要能读文件但绝不能改文件,
所以它保留了 read,换掉了三个写入型工具,补上三个检索型工具。
export type ToolName = "read" | "bash" | "powershell" | "edit" | "write" | "grep" | "find" | "ls"; export const allToolNames: Set<ToolName> = new Set([ "read", "bash", "powershell", "edit", "write", "grep", "find", "ls", ]);
index.ts:96(工具名全集)· :164(三档构造)
read:三个参数,两个上限
read 的参数表短到只有三行,但每一行都有讲究:
path: Type.String({ description: "Path to the file to read (relative or absolute)" }),
offset: Type.Optional(Type.Number({ description: "Line number to start reading from (1-indexed)" })),
limit: Type.Optional(Type.Number({ description: "Maximum number of lines to read" })),
offset 明确写了 1-indexed——因为这是模型最容易搞错的地方(它见惯了 0-indexed 的代码)。
用描述把它钉死,比在实现里做兼容更省事。
真正的约束在截断层,而且是两个上限同时生效,谁先到算谁:
| 常量 | 值 | 为什么需要它 |
|---|---|---|
DEFAULT_MAX_LINES | 2,000 | 防止单个巨型日志文件撑爆上下文 |
DEFAULT_MAX_BYTES | 50 KB | 防止 2,000 行、每行 1 万字符的 minified 文件 |
只限行数不够(压缩后的 JS 一行能到几 MB),只限字节也不够(一行一字符的文件会读进上百万行)。 两个都限,才是真的安全。
另外它的描述里有一句常被忽略的话:图片以附件形式发送。也就是说 read 不只是「读文本」,
它还是 pi 多模态的入口——这也是为什么它的参数里没有任何 asImage 之类的开关:按扩展名自动判断。
truncate.ts:11-12(两个上限)· read.ts:94(工具定义)
bash:没有默认超时,这是设计还是漏洞
bash 只有一个必填参数和一个可选参数,而可选参数里写着四个字:no default timeout。
command: Type.String({ description: "Shell command to execute" }),
timeout: Type.Optional(Type.Number({ description: "Timeout in seconds (optional, no default timeout)" })),
上限也不是「合理值」,而是 2_147_483_647 毫秒——约 24.8 天,这个数字来自 32 位有符号整数上限,
也就是「别让 setTimeout 溢出」的技术边界,不是产品判断。
| 行为 | 实现 | 后果 |
|---|---|---|
| 不传 timeout | 返回 undefined | 命令可以一直跑 |
| 传非法值 | 抛 Invalid timeout | 错误变成模型输入,下一轮自己改 |
| 传超大值 | 超过 24.8 天则抛错 | 防定时器溢出,不是防久跑 |
输出侧反而很谨慎:截断保留最后 2,000 行 / 50 KB,并把完整输出写进临时文件,路径通过 full_output_path 返回给模型。
output: Type.String({ description: "Combined stdout and stderr, possibly truncated" }),
// ...
full_output_path: Type.Optional(Type.String({ description: "Full output, when truncated" })),
bash 的定位一致——这是个给人用的交互式 CLI,
用户能随时按 Ctrl+C。但对无人值守的长任务,这确实是个缺口:
没有超时就意味着一条挂住的命令能吃掉整晚。
对比站把它列进了 最小改造清单 的讨论范围。
bash.ts:22(MAX_TIMEOUT_MS)· :28-38(校验)
edit:三类真实故障驱动的参数修复
这是全篇最值得细看的一个细节,因为它把「模型会怎么搞错」写得明明白白。
edit 的契约是「精确文本替换」,要求每处 oldText 在原文件里唯一且互不重叠。
但真实模型经常不是按 schema 输出的,于是有了 prepareArguments——一个在校验之前运行的修复钩子:
function prepareEditArguments(input: unknown): EditToolInput { if (!input || typeof input !== "object") return input as EditToolInput; const args = input as Record<string, unknown>; // Some models (Opus 4.6, GLM-5.1) send edits as a JSON string instead of an array. // Others send a single edit object instead of a one-element edits array. if (typeof args.edits === "string") { try { const parsed = JSON.parse(args.edits); if (Array.isArray(parsed)) args.edits = parsed; else if (isSingleEditInput(parsed)) args.edits = [parsed]; } catch {} } else if (isSingleEditInput(args.edits)) { args.edits = [args.edits]; // 单对象 → 单元素数组 } // ...再往下还有:legacy oldText/newText → edits[] }
三类修复,每一类都有明确的来源:
| # | 畸形形态 | 修复 | 来源 |
|---|---|---|---|
| 1 | edits 是 JSON 字符串而不是数组 | JSON.parse 后按形状归一 | 注释点名 Opus 4.6、GLM-5.1 |
| 2 | edits 是单个对象而不是数组 | 包成单元素数组 | 注释点名「others」 |
| 3 | 用旧版顶层 oldText/newText | 搬进 edits[] | 向后兼容旧 prompt/旧模型记忆 |
修复之后才是校验,而校验只有一条规则(至少一处替换):
function validateEditInput(input: EditToolInput): { path: string; edits: Edit[] } { if (!Array.isArray(input.edits) || input.edits.length === 0) { throw new Error("Edit tool input is invalid. edits must contain at least one replacement."); } return { path: input.path, edits: input.edits }; }
prepareArguments 负责「猜得到就修」,validateEditInput 负责「猜不到就报」。
修复和处理错误分离,比混在一个函数里既好测也好读。
内核侧只提供一个通用钩子(types.ts:473),具体修什么由每个工具自己决定——所以 8 个工具里只有 edit 需要它。
edit.ts:103(修复)· :136(校验)· types.ts:473(内核钩子)
并发写的安全:按 realpath 排队
pi 的工具可以并行执行(executeToolCallsParallel)。但两个 edit 同时改一个文件会互相踩。
解法是一把按路径分片的串行队列。
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 而不是 resolve 是关键:软链接和 .. 会归到同一个键。
否则 ./a.ts 和 ./link-to-a.ts 会各拿一把锁,照样并发写坏。
而 ENOENT 的兜底也必要——write 可以创建新文件,那时 realpath 必然失败,
但不能因此拒绝入队,否则「两个 write 同时创建同一文件」就没人保护了。
约束解码:prefer 而不是 require
4 个 coding 工具的定义里都有一行容易跳过的字段:
constrainedSampling: { type: "json_schema", strict: "prefer" },
这是要求 provider 用 JSON Schema 约束解码(constrained decoding)——从采样层面保证输出一定符合 schema, 而不是「生成完再校验」。
但 strict 的取值是 "prefer" | "require",pi 用了前者。原因是各家的严格模式对 JSON Schema 关键字的支持不一样,
而 pi 维护了一张明确的不支持清单:
| 类别 | 关键字 |
|---|---|
| 引用类 | $ref · $defs · definitions |
| 组合类 | allOf · oneOf |
| 条件类 | if · then · else · not |
| 对象约束类 | patternProperties · dependentSchemas · dependencies · unevaluatedProperties · propertyNames |
| 数组约束类 | contains · prefixItems |
prefer 的语义因此很清楚:schema 里没用到这些关键字就用严格模式,用到了就退化成普通模式,
而不是整个请求失败。这是个很实用的取舍——严格模式能显著降低「参数畸形」,但不值得为它牺牲兼容性。
prepareArguments(错了尽量修)。
而 prefer 这个取值恰好说明作者知道第一道不可能总是生效——所以第二道才必须存在。
constrained-sampling.ts:15-31(不支持清单)· types.ts:762(prefer/require)
工具层的四条不变量
read 2,000 行 + 50 KB;bash 保留末 2,000 行 + 50 KB,全量转存临时文件。没有无界返回。isError 结果,不 rejectprepareArguments(猜得到就修)→ schema/validate(猜不到就报)。两者职责不重叠。realpath,软链接归一;文件不存在时退回 resolve,不放弃保护。