深入理解 pi 02 / 06 目录 单页全本 学习手册 对比站

深入理解 pi/第 02 章

2.1

「4 个工具」是半个真相

pi 常被概括为「只有 4 个工具」。这个说法不算错,但它说的是一个子集。实际工具面是三档,按角色划分:

构造函数数量成员
createCodingToolDefinitions 4 read · bash · edit · write
createReadOnlyToolDefinitions 4 read · grep · find · ls
createAllToolDefinitions 8 上面两者并集 + powershell

注意 read 同时出现在两个集合里——这不是冗余,而是刻意的:只读集合要能读文件但绝不能改文件, 所以它保留了 read,换掉了三个写入型工具,补上三个检索型工具。

packages/coding-agent/src/core/tools/index.ts:96-105
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(三档构造)

2.2

read:三个参数,两个上限

read 的参数表短到只有三行,但每一行都有讲究:

packages/coding-agent/src/core/tools/read.ts:14-18
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_LINES2,000防止单个巨型日志文件撑爆上下文
DEFAULT_MAX_BYTES50 KB防止 2,000 行、每行 1 万字符的 minified 文件

只限行数不够(压缩后的 JS 一行能到几 MB),只限字节也不够(一行一字符的文件会读进上百万行)。 两个都限,才是真的安全。

另外它的描述里有一句常被忽略的话:图片以附件形式发送。也就是说 read 不只是「读文本」, 它还是 pi 多模态的入口——这也是为什么它的参数里没有任何 asImage 之类的开关:按扩展名自动判断。

truncate.ts:11-12(两个上限)· read.ts:94(工具定义)

2.3

bash:没有默认超时,这是设计还是漏洞

bash 只有一个必填参数和一个可选参数,而可选参数里写着四个字:no default timeout。

packages/coding-agent/src/core/tools/bash.ts:40-43
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 返回给模型。

packages/coding-agent/src/core/tools/bash.ts:57-59
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(校验)

2.4

edit:三类真实故障驱动的参数修复

这是全篇最值得细看的一个细节,因为它把「模型会怎么搞错」写得明明白白。

edit 的契约是「精确文本替换」,要求每处 oldText 在原文件里唯一且互不重叠。 但真实模型经常不是按 schema 输出的,于是有了 prepareArguments——一个在校验之前运行的修复钩子:

packages/coding-agent/src/core/tools/edit.ts:103-123
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[]
}

三类修复,每一类都有明确的来源:

#畸形形态修复来源
1edits 是 JSON 字符串而不是数组JSON.parse 后按形状归一注释点名 Opus 4.6、GLM-5.1
2edits 是单个对象而不是数组包成单元素数组注释点名「others」
3用旧版顶层 oldText/newText搬进 edits[]向后兼容旧 prompt/旧模型记忆

修复之后才是校验,而校验只有一条规则(至少一处替换):

packages/coding-agent/src/core/tools/edit.ts:136-141
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(内核钩子)

2.5

并发写的安全:按 realpath 排队

pi 的工具可以并行执行(executeToolCallsParallel)。但两个 edit 同时改一个文件会互相踩。 解法是一把按路径分片的串行队列。

packages/coding-agent/src/core/tools/file-mutation-queue.ts:15-25
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 同时创建同一文件」就没人保护了。

file-mutation-queue.ts:15

2.6

约束解码:prefer 而不是 require

4 个 coding 工具的定义里都有一行容易跳过的字段:

packages/coding-agent/src/core/tools/{bash,edit,read,write}.ts
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 里没用到这些关键字就用严格模式,用到了就退化成普通模式, 而不是整个请求失败。这是个很实用的取舍——严格模式能显著降低「参数畸形」,但不值得为它牺牲兼容性。

把 2.4 和 2.6 连起来看:pi 在参数正确性上有两道防线。 第一道是事前的约束解码(尽量不让它错),第二道是事后的 prepareArguments(错了尽量修)。 而 prefer 这个取值恰好说明作者知道第一道不可能总是生效——所以第二道才必须存在。

constrained-sampling.ts:15-31(不支持清单)· types.ts:762(prefer/require)

2.7

工具层的四条不变量

① 每个工具都有硬上限(行数 / 字节 / 输出)
read 2,000 行 + 50 KB;bash 保留末 2,000 行 + 50 KB,全量转存临时文件。没有无界返回。
② 失败一律变成 isError 结果,不 reject
工具层的错误是给模型看的,不是给调用栈看的。
③ 参数先修再校验
prepareArguments(猜得到就修)→ schema/validate(猜不到就报)。两者职责不重叠。
④ 同一文件的写操作串行
键取 realpath,软链接归一;文件不存在时退回 resolve,不放弃保护。

本章学习记录

记录仅保存在当前浏览器。