深入理解 pi 全本 目录 学习手册全本
Full text

深入理解 pi
单页全本

六章合订。适合 Ctrl+F 搜索与打印。

1.1

先看全景:三层循环,不是一个

大多数人对 agent 主循环的印象是一个 while。pi 有三个,而且是嵌套的、各管一件事。 这是读懂 pi 的第一个关键——因为「为什么会重复请求」「为什么重试不生效」「为什么消息在奇怪的时候出现」这些问题的答案,分散在这三层里。

层代码位置循环条件它管什么
L1 会话层 agent-session.ts:1900 while (!abort) 压缩、重试、settle 之后要不要再来一轮
L2 轮次层 agent-loop.ts:188 while (true) + break 一次 agent.prompt() 内部的完整多轮工具调用
L3 步进层 agent-loop.ts:192 while (hasMoreToolCalls || pendingMessages.length > 0) 单个 assistant 回复 + 它带出的工具调用

这是个很反直觉的分工:真正「跑一个 turn」的是 L2,但「什么时候停」的决定权在 L1。 因为压缩、重试、失败恢复全都在 L1,L2 只负责把这一轮跑完。

这个分层解释了为什么 pi 主循环里搜不到 maxSteps—— 「多少轮算太多」是会话层的业务判断,而 L1 现在只判 abort,没有别的终止条件。 想看这一条的分析,去对比站的 故障与恢复 · 控制流真空。
1.2

入口只有 6 行

整个 CLI 的启动代码短到可以直接贴完:

packages/coding-agent/src/cli.ts:1-6
#!/usr/bin/env node
import { setupCli } from "./cli/setup.ts";
import { main } from "./main.ts";

setupCli();
main(process.argv.slice(2));

setupCli() 做进程级准备(信号处理、终端状态),main() 是 1,001 行的编排器: 解析参数、加载配置、迁移旧设置、装配 model runtime,最后按 appMode 分派到三种模式之一。

交互模式在这里创建:

packages/coding-agent/src/main.ts:954-955
} else if (appMode === "interactive") {
  const interactiveMode = new InteractiveMode(runtime, {

注意 runtime 是构造参数——说明 model runtime 在进 TUI 之前就已经装配好了。 这个顺序很重要:TUI 只负责收集输入和渲染,不负责模型选择。

cli.ts:1-6 · main.ts:954

1.3

六道闸门:模型被调用之前

用户按下回车,第一个接到消息的不是模型,而是 session.prompt()。 这个方法值得逐行读,因为它在真正花钱之前设了六道闸门——而每一道都对应一类真实的失败。

#闸门判据拒绝后的结果
1settle 中?_isEmittingAgentSettled不拒绝——推迟执行(_deferredSettledActions)
2斜杠命令?text.startsWith("/")交给扩展执行,不发模型
3正在压缩?_compactionAbortController !== undefined抛错,要求等压缩结束
4扩展要拦截?_runInputHandlers 返回空静默丢弃
5正在流式?this.isStreaming必须显式指定 steer 或 followUp,否则抛错
6模型与凭据?有 model、有 auth抛错并给出修复命令

第 5 道闸门的设计最值得注意:流式期间提交新消息必须显式声明意图。

packages/coding-agent/src/core/agent-session.ts:2137-2147
if (this.isStreaming) {
  if (!options?.streamingBehavior) {
    throw new Error(
      "Agent is already processing. Specify streamingBehavior ('steer' or 'followUp') to queue the message.",
    );
  }
  if (options.streamingBehavior === "followUp") {
    await this._queueFollowUp(expandedText, currentImages);
  } else {
    await this._queueSteer(expandedText, currentImages);
  }
  return;
}

为什么必须显式?因为 steer 和 followUp 的语义完全不同: steer 插在当前轮次里(模型下一轮立刻看到),followUp 排在停止之后(L2 外层循环才会取)。 让调用方默认猜一个,不如强制它表态。

第 4 道闸门:扩展能改输入

_runInputHandlers 是个容易被低估的钩子——它在 skill 展开和模板替换之前运行, 返回 undefined 就等于「这条输入我吃了」。于是扩展可以做到:改写用户输入、加上下文、或者完全吞掉。

顺序也值得记住:拦截 → 展开技能 → 展开模板 → 排队或发送。 反过来(先展开再拦截)会让扩展看到一个已经被拼装过的字符串,想改原文就来不及了。

agent-session.ts:2092(prompt 全貌)· :2117(input 钩子位置)

1.4

_startRun:L1 那个循环长什么样

过了六道闸门,进入 _startRun。这里的结构是本篇最需要看懂的一段:

packages/coding-agent/src/core/agent-session.ts:1899-1911(简化)
await this.agent.prompt(messages);
while (!this._agentRunAbortRequested) {
  if (await this._handlePostAgentRun()) {
    if (this._agentRunAbortRequested) break;
    await this.agent.continue();      // ← 再来一轮
    continue;
  }
  if (this._agentRunAbortRequested || !(await this._runBeforeSettleBoundary())) break;
  if (this._agentRunAbortRequested) break;
  await this.agent.continue();        // ← 再来一轮
}

两个 continue() 就是两层含义:

触发点含义典型场景
_handlePostAgentRun() 返回 true上一轮「没收尾好」,需要接着跑压缩成功、溢出恢复成功、失败响应要重试
_runBeforeSettleBoundary() 返回 truesettle 之前的钩子要求再跑一轮扩展在 settle 边界注入了新消息

所以「一次用户提问」到底跑几轮模型调用,不是由模型决定的,是由 L1 的三个判断决定的: L2 自然停止、post-run 要不要续、settle 边界要不要续。

一个容易踩的坑:_prepareRun 在 L2 开始之前就调用了 _checkCompaction。 也就是说压缩发生在「这一轮请求发出前」,而不是等溢出报错才做。 这解释了为什么 pi 的压缩看起来「提前」——它是预防式的。

agent-session.ts:1873(_startRun)· :1899(L1 循环)

1.5

重入闸门:activeRun

会话层有六道闸门,内核层只有一道,但它更硬:activeRun。

packages/agent/src/agent.ts:382-390
async prompt(input, images?): Promise<void> {
  if (this.activeRun) {
    throw new Error(
      "Agent is already processing a prompt. Use steer() or followUp() to queue messages, or wait for completion.",
    );
  }
  const messages = this.normalizePromptInput(input, images);
  await this.runPromptMessages(messages);
}

这道闸门的作用是保护 AgentState.messages 不被两个并发写者交错修改。 没有它,两个 prompt() 同时跑会出现「工具结果插到别的调用后面」——正是轨迹结构损坏的来源。

而 continue() 比 prompt() 多一层检查:它要求最后一条消息不是 assistant。 逻辑上说得通(从 assistant 继续没有意义),但它留了后门——如果最后是 assistant,先看 steering 队列、再看 followUp 队列,都空才报错:

packages/agent/src/agent.ts:403-417(简化)
if (lastMessage.role === "assistant") {
  const queuedSteering = this.steeringQueue.drain();
  if (queuedSteering.length > 0) { await this.runPromptMessages(queuedSteering, { skipInitialSteeringPoll: true }); return; }

  const queuedFollowUps = this.followUpQueue.drain();
  if (queuedFollowUps.length > 0) { await this.runPromptMessages(queuedFollowUps); return; }

  throw new Error("Cannot continue from message role: assistant");
}

agent.ts:382(activeRun 闸门)· :393(continue)

1.6

L2/L3:runLoop 全文骨架

现在到内核。runLoop 从 172 行开始,是 pi 唯一真正的「agent 主循环」。骨架是这样:

packages/agent/src/agent-loop.ts:188-320(骨架,略去细节)
while (true) {                                    // L2 外层:followUp 会让它再来一圈
  let hasMoreToolCalls = true;

  while (hasMoreToolCalls || pendingMessages.length > 0) {   // L3 内层
    // ① 有上一轮就调 prepareNextTurn(可能触发压缩),并发 turn_start
    // ② 把 prepared + pending 消息推进 transcript
    // ③ prepareRequest 允许改 context / model / thinkingLevel
    const message = await streamAssistantResponse(...);        // ④ 真正请求模型

    if (message.stopReason === "error" || message.stopReason === "aborted") {
      await config.finishTurn?.(...); await emit({ type: "turn_end", ... });
      await emit({ type: "agent_end", ... }); return;   // ← 直接返回,不重试
    }

    const toolCalls = message.content.filter(c => c.type === "toolCall");
    if (toolCalls.length > 0) { ...执行工具...; hasMoreToolCalls = !executedToolBatch.terminate; }

    const decision = await config.finishTurn?.(...);
    if (decision?.action === "end") { await emit({ type: "agent_end", ... }); return; }

    pendingMessages = (await config.getSteeringMessages?.()) || [];
  }

  const followUpMessages = (await config.getFollowUpMessages?.()) || [];
  if (followUpMessages.length > 0) { pendingMessages = followUpMessages; continue; }
  if (explicitContinuation) { explicitContinuation = false; continue; }
  break;                                             // 唯一自然出口
}

三个细节值得单独说:

① streamAssistantResponse 返回 error 时立刻返回,不重试
重试在 L1(_handlePostAgentRun),不在内核。内核只负责「把这次失败如实记进 transcript 并上报」。 这是很干净的分工:内核不理解策略,只理解状态。
② hasMoreToolCalls 由工具的 terminate 反向决定
不是「有工具调用就继续」,而是「工具没要求终止就继续」—— hasMoreToolCalls = !executedToolBatch.terminate。所以一个工具可以主动结束整轮。 而 terminate 只在整批都为 true 时才生效(shouldTerminateToolBatch)。
③ explicitContinuation 允许「只跑一轮上下文」
如果 finishTurn 返回 action: "continue" 但没有工具调用也没有排队消息, 外层会再跑一圈——用于「需要一次纯上下文请求」的场景。它会被任何真实消息重置,所以不会白白多跑。

agent-loop.ts:172(runLoop)· :188 L2 · :192 L3

1.7

格式边界:AgentMessage[] → Message[]

这是全篇最容易混淆的一处。pi 里有两种消息类型,不是一种:

类型定义谁用它特点
AgentMessage Message | CustomAgentMessages[keyof] transcript(会话记忆) 开放——扩展可注册自己的消息类型
Message System | User | Assistant | ToolResult 发给模型的线上格式 封闭四元组——就这四种

转换发生在每次请求之前,而且可插拔:

packages/agent/src/agent-loop.ts:398-406
// Apply context transform if configured (AgentMessage[] → AgentMessage[])
let messages = context.messages;
if (config.transformContext) {
  messages = await config.transformContext(messages, signal);
}

// Convert to LLM-compatible messages (AgentMessage[] → Message[])
const llmMessages = await config.convertToLlm(messages);

const llmContext = normalizeContext({ messages: llmMessages });

三段各管一件事,顺序不能换:

阶段输入→输出做什么
transformContextAgentMessage[] → AgentMessage[]改写会话内容(压缩、注入、裁剪)
convertToLlmAgentMessage[] → Message[]把扩展的自定义消息翻译成四元组之一
normalizeContextMessage[] → TranscriptContext补齐协议要求的结构

coding-agent 注入的实现叫 convertToLlmWithBlockImages——名字就说明了它额外做的一件事:处理被拦下的图片。

为什么这个边界重要:所有「模型看到的」和「会话记住的」之间的差异,都发生在这三行里。 调试「模型为什么没看到某条消息」时,先确认它过没过 convertToLlm,而不是去翻 transcript。

agent-loop.ts:399 · :404 · sdk.ts:411(注入的实现)

1.8

落盘:一次提问的最后一步

消息进了 transcript 不代表存下来了。真正写文件的是 _appendEntry → _persist,而 _persist 有个容易被忽略的首次写逻辑。

packages/coding-agent/src/core/session-manager.ts:1172-1198
_persist(entry: SessionEntry): void {
  if (!this.persist || !this.sessionFile) return;

  if (!this.flushed) {
    if (!this._hasConversation()) return;          // ← 空会话不落盘
    const fd = openSync(this.sessionFile, "wx");      // ← 排他创建
    try {
      for (const e of this.fileEntries) {
        writeFileSync(fd, `${JSON.stringify(e)}\n`);   // ← 补写所有缓冲条目
      }
    } finally { closeSync(fd); }
    this.flushed = true;
  } else {
    appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
  }
}

四件事各有理由:

代码为什么这样写
_hasConversation() 检查避免「打开就退出」留下一个空文件,污染会话列表
openSync(…, "wx")排他标志:文件已存在就失败,绝不覆盖已有会话
首次遍历 fileEntries打开一个历史会话时,前面已解析的条目要原样写下(换路径另存也走这条)
之后 appendFileSync真正的 append-only:一次一条 JSON + \n,可流式读、可断点续

而 _appendEntry 只有四行,但它定义了整棵树的生长方式:

packages/coding-agent/src/core/session-manager.ts:1191-1197
private _appendEntry(entry: SessionEntry): void {
  this.fileEntries.push(entry);
  this.byId.set(entry.id, entry);
  this.leafId = entry.id;      // ← 叶子推进:下一次 append 的 parentId 就是它
  this._persist(entry);
}

「叶子推进」这一行是 append-only 树的全部秘密:新条目总是挂在当前叶子上,然后自己成为新叶子。 分支(fork)不需要复制历史,只需要把 leafId 指回某个旧条目,下一条自然就长在那个位置。

session-manager.ts:1191 · :1172

1.9

把一次提问压成一张图

① 按键 → session.prompt()
六道闸门依次过:settle / 斜杠 / 压缩中 / input 钩子 / 流式中 / 模型凭据。
② _startRun → _prepareRun
先看要不要压缩(预防式),再 before_agent_start,再装配起始消息。
③ agent.prompt() → 过 activeRun 闸门 → runLoop
进入 L2。每一圈 streamAssistantResponse 做三次转换:transform → convert → normalize。
④ 模型返回 → 有 toolCall 就进 L3 执行 → 结果回填 transcript
工具永不 reject,失败变成 isError 结果——这是「错误即输入」的落点。
⑤ 每步落盘:_appendEntry 推进 leafId → _persist 追加一行 JSONL
首次写用 wx 排他创建并补写缓冲,之后纯 append。
⑥ L2 停止 → 回到 L1:post-run / settle 边界决定要不要 continue()
这一层才是压缩、溢出恢复、失败重试的舞台。

一句话总结:L2 负责「跑完这一轮」,L1 负责「决定还要不要下一轮」,而 JSONL 在两者之间持续记录真实发生的事。 后面五章都是这条链上的局部放大。

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,不放弃保护。
3.1

为什么不是「一个消息数组」

最简单的会话存储是一个数组:往后面 push,读的时候整个读出来。pi 不用这个方案,因为有三件事它做不到:

需求数组方案的困境树方案的解
回到某一步重来要么复制整个前缀,要么丢掉后面把 leafId 指回旧条目,下一条自然长在那里
压缩后仍能查原始消息摘要一旦写入,原文就没了摘要是新条目,原条目仍在文件里
崩溃后不丢数据整文件重写有窗口期一次追加一行,写多少算多少

代价也很明确:读的时候要重建。数组是 O(1) 读,树是 O(深度) 回溯。 pi 接受了这个代价,换来的是「历史不可变、状态可分支」。

3.2

条目:11 种类型,全都是事件

会话文件里的每一行是一个 SessionEntry,而它是 11 种类型的联合:

packages/coding-agent/src/core/session-manager.ts:183-194
export type SessionEntry =
  | SessionMessageEntry          // 一条对话消息
  | ThinkingLevelChangeEntry     // 思考档位变更
  | ModelChangeEntry             // 换模型
  | UsageEntry                   // 用量记账
  | CompactionEntry              // 压缩摘要
  | BranchSummaryEntry           // 分支摘要
  | CustomEntry                  // 扩展自定义状态
  | CustomMessageEntry           // 扩展自定义消息
  | ContextEditEntry             // 上下文编辑
  | LabelEntry                   // 打标签
  | SessionInfoEntry;            // 会话元信息

注意里面没有一个是「当前状态」字段。当前用什么模型、思考档位多高,都不是存在某个可变字段里, 而是由历史事件推导出来的:

packages/coding-agent/src/core/session-manager.ts:418-430
function getSessionContextSettings(path: SessionEntry[]): Pick<SessionContext, "thinkingLevel" | "model"> {
  let thinkingLevel = "off";
  let model: { provider: string; modelId: string } | null = null;

  for (const entry of path) {
    if (entry.type === "thinking_level_change") {
      thinkingLevel = entry.thinkingLevel;
    } else if (entry.type === "model_change") {
      // ...
    }
  }
}

这是「事件溯源」(event sourcing)的标准形态,好处很实际:回放到任意一步,得到的就是当时真实的模型与档位。 如果用可变字段,切到旧分支时你会带着新分支的模型设定,那是错的。

session-manager.ts:183(11 种条目)· :418(推导当前设置)

3.3

生长:四行代码定义的树

树的全部生长逻辑就在 _appendEntry 里,而它的核心只有一行 this.leafId = entry.id:

packages/coding-agent/src/core/session-manager.ts:1191-1196
private _appendEntry(entry: SessionEntry): void {
  this.fileEntries.push(entry);
  this.byId.set(entry.id, entry);
  this.leafId = entry.id;      // ← 下一次 append 的 parentId 就是它
  this._persist(entry);
}

配合 appendMessage 里那行 parentId: this.leafId,就有了完整的生长规则:

正常对话
每条新消息的 parentId = 上一条的 id,形成一条直线。文件里看不出树,因为退化成了链。
想回到第 3 条重来
把 leafId 设回第 3 条。下一条消息的 parentId 就是第 3 条——不需要复制任何历史,分支自然出现。
两条分支的区别
只在于从第 3 条之后的 parentId 链条走向哪里。文件是纯追加的,旧分支一个字都没改。
这就是为什么必须 append-only:如果允许改旧条目,「回到第 3 条」就得原地修改,旧分支会消失。 而追加型结构让「分支」变成零成本操作——它只是一个指针的赋值。
3.4

读:回溯 + 反转

读一条路径的逻辑简单到有点朴素——从叶子开始沿 parentId 往回走,然后反转:

packages/coding-agent/src/core/session-manager.ts:408-417
const path: SessionEntry[] = [];
let current: SessionEntry | undefined = leaf;
while (current) {
  path.push(current);
  current = current.parentId ? index.get(current.parentId) : undefined;
}
path.reverse();
return path;

有两个细节值得注意:

细节意图
index.get(parentId) 先建一次 Map 索引,否则每次回溯都要线性搜,深度一深就退化
leaf ??= entries[entries.length - 1] 叶子 ID 失效(旧文件、被删条目)时退回最后一条,不报错——容错优先

session-manager.ts:407

3.5

一个迁移里的关键决定:索引 → ID

这是本篇最想让你注意的一处。会话格式从 v1 升到 v2 时加了 id/parentId, 同时把压缩条目里的 firstKeptEntryIndex 换成了 firstKeptEntryId。

packages/coding-agent/src/core/session-manager.ts:286-302
/** Migrate v1 → v2: add id/parentId tree structure. Mutates in place. */
function migrateV1ToV2(entries: FileEntry[]): void {
  const ids = new Set<string>();
  let prevId: string | null = null;

  for (const entry of entries) {
    if (entry.type === "session") { entry.version = 2; continue; }

    entry.id = generateId(ids);
    entry.parentId = prevId;      // ← 线性链:旧文件没有分支
    prevId = entry.id;

    // Convert firstKeptEntryIndex to firstKeptEntryId for compaction
    if (entry.type === "compaction") { /* ... */ }

为什么必须换?因为索引在分支结构下会失效。

表示含义出错场景
firstKeptEntryIndex: 42 文件里第 42 行开始保留 分支后「第 42 行」可能属于另一条分支,压缩边界指向错误位置
firstKeptEntryId: "a3f9" 从 id 为 a3f9 的条目开始保留 不成立——id 全局唯一,永远指向同一条

同一个迁移里还有一句注释揭示了 v1 的真实形状:entry.parentId = prevId。 旧文件是纯线性的,所以迁移时可以直接把 prevId 串起来——不需要推断任何分支结构。

这条经验可以推广:任何「在可变序列里记录位置」的设计,一旦引入分支或重排,位置表示就会失效。 用稳定 ID 替换下标,是让日志结构能长期演进的前提。

session-manager.ts:286-302

3.6

落盘:排他创建 + 惰性补写

append-only 只是逻辑模型,物理写入还有个首次写的特殊情况:

packages/coding-agent/src/core/session-manager.ts:1172-1189
_persist(entry: SessionEntry): void {
  if (!this.persist || !this.sessionFile) return;

  if (!this.flushed) {
    if (!this._hasConversation()) return;        // ← 空会话不建文件
    const fd = openSync(this.sessionFile, "wx");    // ← 排他创建
    try {
      for (const e of this.fileEntries) {
        writeFileSync(fd, `${JSON.stringify(e)}\n`); // ← 补写所有已解析条目
      }
    } finally { closeSync(fd); }
    this.flushed = true;
  } else {
    appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`);
  }
}
行为为什么
没有对话就不建文件避免「打开-退出」留下一堆空会话,污染列表
"wx" 而不是 "w"文件已存在则失败,永不覆盖别人的会话
首次遍历 fileEntries恢复/另存时要补写已解析的历史;之后才转为纯追加
一行一个 JSON+\n可流式读、可断点续、坏一行不影响前面

session-manager.ts:1172-1189

3.7

一句话记住它

这套结构的本质是:文件是日志,树是日志的读法,状态是历史的函数。

你以为它是实际上是推论
一个可变的消息数组只追加的 JSONL 日志永远不需要「保存」——每一步都已经是保存
一个有分支的树对象一批带 parentId 的条目分支是「把叶子指针挪一下」,零拷贝
一份当前设置一串变更事件回放旧分支拿到旧设置,不会串味

下一章要讲的压缩,正是这套结构最重要的使用者——因为压缩必须在不破坏历史的前提下,改变「模型看到什么」。 如果历史是可变的,压缩就变成了「删掉旧消息」;而在这里,压缩只是追加一条新的摘要条目。

4.1

什么时候压:一个不等式

压缩的触发条件只有一行,但它包含两个可调参数:

packages/coding-agent/src/core/compaction/compaction.ts:269
contextTokens > contextWindow - settings.reserveTokens
参数默认含义
reserveTokens16,384给「下一轮回复」预留的空间。不留就会压完立刻再溢出
keepRecentTokens20,000压缩后保留的近期原文量。太少会丢细节,太多压了等于没压

两个数解决的是不同问题:reserveTokens 是为了能继续说话,keepRecentTokens 是为了还记得刚才在干什么。 注意它们是同一个方向上的拉扯——保留越多,能留的对话轮次越少。

compaction.ts:269(触发)· :128-129(默认值)

4.2

切点算法:从末尾倒着走

决定「从哪条开始保留」的算法是压缩的核心。它的方向很关键——从最新往回数,而不是从最旧往前数。

packages/coding-agent/src/core/compaction/compaction.ts:431-478(简化)
/**
 * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
 * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
 *
 * Can cut at user OR assistant messages (never tool results). When cutting at an
 * assistant message with tool calls, its tool results come after and will be kept.
 */
const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
let accumulatedTokens = 0;
let cutIndex = cutPoints[0];

for (let i = endIndex - 1; i >= startIndex; i--) {
  const messageTokens = sessionEntryToContextMessages(entries[i])
    .reduce((sum, message) => sum + estimateTokens(message), 0);
  if (messageTokens === 0) continue;
  accumulatedTokens += messageTokens;

  if (accumulatedTokens >= keepRecentTokens) {
    cutIndex = cutPoints.find((candidate) => candidate >= i) ?? cutPoints[cutPoints.length - 1];
    break;
  }
}

为什么必须倒着走?因为要保证的是「最近 N token 一定在」,而不是「最旧 N token 一定被压」。 正着走会让你不知道该在哪里停——你不知道后面还剩多少。

三个约束同时生效:

约束实现防的是
不能切在工具结果上findValidCutPoints 只给合法位置调用与结果被拆开,轨迹结构损坏
切点取「最近的合法位置」cutPoints.find(c => c >= i)为了凑整而切到很远的地方,多压了一大段
兜底不越过首个合法点?? cutPoints[last]找不到时退化成「什么都不压」的失控
一句注释的信息量:When cutting at an assistant message with tool calls, its tool results come after and will be kept. 这说明作者考虑过「切在 assistant 上会不会把它的工具结果丢掉」——答案是「结果在后面,所以会被保留」。 这种把边界情形写进注释的习惯,比多写十个测试更有用。

compaction.ts:431-478

4.3

split turn:切在一轮中间怎么办

倒着数到 keepRecentTokens 时,很可能正好落在**一个 turn 的中间**——用户说了话、模型回了、工具跑了,但这一轮还没结束。 这时切下去会留下一段「没有开头的对话」。

pi 的解法是记录两个额外信息,而不是硬切:

返回字段作用
firstKeptEntryIndex保留区从哪条开始
turnStartIndex若是 split,这一轮起头的那条用户消息在哪
isSplitTurn是否切在轮次中间

于是 turnPrefixMessages 出现了——被切掉的那半轮单独摘要,而不是混进主摘要:

packages/coding-agent/src/core/compaction/compaction.ts:890-900
const historyEnd = cutPoint.isSplitTurn
  ? cutPoint.turnStartIndex
  : cutPoint.firstKeptEntryIndex;

const messagesToSummarize = projectedEntries
  .slice(boundaryStart, historyEnd)
  .flatMap(getMessagesFromProjectedEntryForCompaction);

const turnPrefixMessages = cutPoint.isSplitTurn
  ? projectedEntries.slice(cutPoint.turnStartIndex, cutPoint.firstKeptEntryIndex)
      .flatMap(getMessagesFromProjectedEntryForCompaction)
  : [];

为什么要分开?因为两者的语义不同:

段落性质摘要方式
主历史已完成的多轮对话正常摘要,讲清「做过什么」
turnPrefix未完成的那半轮开头要明确标出「这一轮还没结束」,否则摘要会说成已完成

compaction.ts:890-900

4.4

投影:为什么不能「摘要的摘要」

如果一份会话被压过三次,第四次压缩时该拿什么当输入?直觉答案是「上次的摘要 + 之后的新消息」。 但那样会有一个隐蔽的问题:上次摘要自己也是被压过的,再算 token 预算就会算错。

pi 的处理叫 projection——先把所有压缩条目「投影」成消息形态,再做切点计算:

packages/coding-agent/src/core/compaction/compaction.ts:867-882
const projection = buildSessionProjection(pathEntries);
const projectedEntries = projection.entries;
const sourceEntries = projectedEntries.map((entry) => entry.sourceEntry);

// The newest compaction is projected first. Older compaction entries can still
// occur in its retained raw range, but their projected contribution is empty.
const prevCompactionIndex = projectedEntries.findIndex(
  (entry) => entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
);

let previousSummary: string | undefined;
let boundaryStart = 0;
if (prevCompactionIndex >= 0) {
  previousSummary = (projectedEntries[prevCompactionIndex].sourceEntry as CompactionEntry).summary;
  // The canonical projection has already selected the previous compaction's retained tail.
  boundaryStart = prevCompactionIndex + 1;
}

两个机制配合起来才成立:

① 投影让「嵌套压缩」退化成一个平面序列
无论历史上压过几次,投影后的 projectedEntries 都只有一个压缩边界有效—— 最新的那个。更早的压缩条目即使还留在保留区里,投影贡献也为空(注释直说了:their projected contribution is empty)。
② 旧摘要被 carry forward,不是被重新摘要
previousSummary 直接传给下一次压缩,让它「在新摘要里带上旧摘要」。 这样信息不会随压缩次数指数衰减——这是长篇会话能一直跑下去的关键。
这是一个很容易做错的点。如果每次压缩都只把「上次摘要 + 新消息」重新摘要一遍, 那么第 N 次压缩后,第 1 次的内容会被压 N 遍——细节以指数速度流失。 previousSummary 的 carry-forward 正是因为意识到这件事。

compaction.ts:867-882

4.5

摘要本身就是一次模型调用

压缩不是本地算法,它要花一次完整的模型调用。这就带来一个必须防的问题:摘要模型可能在摘要时调用工具。

packages/coding-agent/src/core/compaction/compaction.ts:742-748
const failure = getSummarizationFailure(response, "Summarization");
if (failure) { throw new Error(failure); }
if (response.content.some((block) => block.type === "toolCall")) {
  throw new Error("Summarization attempted to call a tool");
}

为什么这算错误而不是「忽略工具调用取文本」?因为摘要调用不该有工具—— 如果模型调了工具,说明它误解了任务(以为自己在继续干活),此时它输出的文本很可能不是摘要。 宁可失败重来,也不要拿一段莫名其妙的文本当摘要写进历史。

而系统提示词的第二句正是在防这件事:

Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.
不要继续对话。不要回答对话里的任何问题。只输出结构化摘要。
— compaction/utils.ts:163 · SUMMARIZATION_SYSTEM_PROMPT

「不要回答对话里的问题」这句看起来多余,其实是最容易犯的错:历史里往往有用户提问, 摘要模型很容易顺手就答了——答完就不是摘要了。

compaction.ts:747(工具调用护栏)· utils.ts:161-163(系统提示)

4.6

压缩的四个决定

#决定取值 / 做法为什么
1 何时压 tokens > window − 16,384 预留回复空间;提前压而不是等溢出报错
2 保留多少 倒着数到 20,000 token 保证「最近发生了什么」还在原文里
3 切在哪 只在合法切点(永不切工具结果) 保住调用/结果配对,轨迹结构不坏
4 旧摘要怎么办 carry forward,不重新摘要 避免信息随压缩次数指数衰减

可以看到,压缩真正的难点不在「怎么总结」——那是模型的事。 难点全在「切在哪」「旧信息怎么带上」「切坏了怎么办」这三个结构问题上。 这也是为什么 compaction.ts 有近千行,而摘要提示词只有三句。

5.1

32 个挂点,6 个能改

pi 的扩展面是一个 32 个事件的联合类型。但真正决定架构的不是「有多少个」,而是哪些能改返回值。

packages/coding-agent/src/core/extensions/types.ts:1411-1443
export type ExtensionEvent =
  // —— 生命周期(12)——
  | ProjectTrustEvent | ResourcesDiscoverEvent | McpServersChangeEvent | SessionEvent
  | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent
  | AgentBeforeSettleEvent | AgentSettledEvent | TurnStartEvent | TurnEndEvent
  // —— 消息与上下文(7)——
  | ContextEvent | ContextWithSystemEvent | MessageStartEvent | MessageUpdateEvent
  | MessageEndEvent | CacheWarmingDecisionEvent | InputEvent
  // —— 工具(3)——
  | ToolCallEvent | ToolResultEvent | UserBashEvent
  // —— 模型与采样(4)——
  | BeforeProviderRequestEvent | BeforeProviderHeadersEvent
  | AfterProviderResponseEvent | ProviderStreamEvent
  // —— UI 与模型选择(6)——
  | UIPromptStartEvent | UIPromptEndEvent | ModelSelectEvent
  | ThinkingLevelSelectEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent;

分类不重要,能改才重要。32 个事件里只有 6 个定义了 Result 类型——也就是说只有这 6 个能影响流程,其余 26 个是纯观察。

#可改事件能改什么性质
1ProjectTrustEvent信任决定拦截
2BeforeAgentStartEventsystemPrompt 整段替换、注入消息拦截
3ContextEventmessages 整个数组改写
4ToolCallEventblock 拒绝、原地改 input拦截
5ToolResultEvent结果内容、isError、用量改写
6MessageEndEvent替换最终消息(角色不可变)改写

types.ts:1411-1443(32 事件)· :1460(ToolCallEventResult)

5.2

ToolCall 的三种用法,一个字段

ToolCallEventResult 只有三个字段,但它覆盖了「拦住」「改参数」「提前结束」三种完全不同的意图:

packages/coding-agent/src/core/extensions/types.ts:1460-1469
export interface ToolCallEventResult {
  /** Block tool execution. To modify arguments, mutate `event.input` in place instead. */
  block?: boolean;
  reason?: string;
  /**
   * Hint that the agent should stop after the current tool batch when this call is blocked.
   * Early termination only happens when every finalized tool result in the batch sets this to true.
   */
  terminate?: boolean;
}

最值得注意的是注释里那句 To modify arguments, mutate event.input in place instead。 改参数不是通过返回值,而是靠原地改事件对象——这是个不寻常但合理的选择:

方案优点缺点
返回值带新 input纯函数,易测多个 handler 时谁覆盖谁不清楚
原地改 event.input多个 handler 天然串行叠加隐式副作用,调试时看不出谁改的

pi 选了后者。代价可接受,因为它保证了一件事:多个扩展可以先后加工同一个参数,而不是最后一个说了算。

terminate 的「全体一致」规则

terminate 的语义比看起来严格得多:只有当整批里每一个工具结果都设了 terminate: true,才会提前结束。

packages/agent/src/agent-loop.ts:700-702
function shouldTerminateToolBatch(finalizedCalls: FinalizedToolCallOutcome[]): boolean {
	return finalizedCalls.length > 0 && finalizedCalls.every((finalized) => finalized.result.terminate === true);
}

为什么要求全体一致而不是任意一个?因为半批执行是危险的:模型一次发起 3 个工具调用, 如果第 1 个说「够了」,剩下 2 个不执行,模型下一轮会看到「有 2 个调用没有结果」——轨迹结构就坏了。 要么整批做完,要么整批结束。

agent-loop.ts:700-702(every 而非 some)· types.ts:1464-1468(terminate 注释)

5.3

顺序:为什么 input 钩子必须在展开之前

input 事件的挂点在 prompt() 里,位置很讲究——它在 skill 展开与模板替换之前。 这个顺序不成立的话,扩展就无法工作:

顺序扩展看到的输入能做什么
展开之前拦截(pi 的做法)用户原话改写、加前缀、整体吞掉
展开之后拦截已拼装的完整 prompt只能做「整段替换」,改写原话已不可能

同一条链上还有一个顺序决定:skill 展开先于 template 展开。 因为 skill 是「可能带参数的指令块」,template 是「纯文本替换」——前者更结构化,先做才能让后者处理它的产物。

agent-session.ts:2117(input 钩子)

5.4

Context 事件:最危险的那个

ContextEvent 的返回值是 { messages?: AgentMessage[] }——整个消息数组都能换掉。 这是能力最大、也最容易搞坏东西的一个。

它挂在 transformContext 上,在 convertToLlm 之前执行:

packages/agent/src/agent-loop.ts:398-404
let messages = context.messages;
if (config.transformContext) {
  messages = await config.transformContext(messages, signal);   // ← ContextEvent 在这
}
const llmMessages = await config.convertToLlm(messages);      // ← 之后才翻译

位置决定了它不会破坏持久化:transformContext 只影响「发给模型的这一份」, agent-session.ts 里的 transcript 一个字都不改。

这是整个扩展设计的核心取舍:ContextEvent 能让你在第 1,000 条消息处插入一句话, 却不能让这句话出现在会话文件里。想持久化必须走 CustomMessageEntry(写进 appendMessage), 那是另一条路径、另一种责任。 「改视图」和「改事实」被刻意分开了。

types.ts:1449-1451(ContextEventResult)· agent-loop.ts:399

5.5

扩展面的三条边界

① 观察与拦截分开:26 观察 / 6 可改
想看什么都能看,想改必须走指定的 6 个口子。这让「扩展会不会悄悄改变行为」这个问题有了确定答案。
② 改视图与改事实分开
ContextEvent 只改「这一份请求」,会话文件不变。想持久化得写 CustomMessageEntry。
③ 提前结束必须整批一致
半批执行会留下「有调用没结果」的坏轨迹,所以 terminate 要求 every() 而非 some()。

这三条合起来说明一件事:pi 的扩展不是「插件随便改框架」,而是「在框架划定的语义边界上做加法」。 能力是受限的,但受限让它可预测。

6.1

两个 Message,一个边界

第 1 章提过这两种类型,这一章讲它们为什么必须分开。

packages/agent/src/types.ts:374
export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
packages/ai/src/types.ts:659
export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
类型形状语义为什么这样做
Message 封闭四元组 所有模型 API 都认的四种角色 线上协议就是这四种,多一种都没有意义
AgentMessage 开放(申明合并) 会话记忆里的任意东西 扩展可以注册自己的消息类型,内核不必知道

CustomAgentMessages 是一个由扩展「声明合并」(declaration merging)扩充的接口。 于是出现了这个局面:内核代码里出现的类型是开放的,但真正发出去的形状是封闭的——两者之间必须有一次显式转换。

这次转换就是 convertToLlm。它的函数签名本身就说明了责任:

packages/agent/src/types.ts:222
convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
这是整篇最「类型驱动」的一处设计:因为 Message 是封闭的, 任何自定义消息类型都必须提供一个「怎么变成四元组之一」的答案,否则代码根本编译不过。 编译器替你把「不许发明新的线上角色」这条规则守住了。

agent/types.ts:374(开放)· ai/types.ts:659(封闭)

6.2

StreamFn:不许抛错

这是 pi 类型系统里最强的一条契约,而且它写在注释里:

packages/agent/src/types.ts:27-38
/**
 * Contract:
 * - Must not throw or return a rejected promise for request/model/runtime failures.
 * - Must return an AssistantMessageEventStream.
 * - Failures must be encoded in the returned stream via protocol events and a
 *   final AssistantMessage with stopReason "error" or "aborted" and errorMessage.
 */
export type StreamFn = (
  model: Model<Api>,
  context: TranscriptContext,
  options?: SimpleStreamOptions,
) => AssistantMessageEventStream | Promise<AssistantMessageEventStream>;

「不许抛错」听起来是个软约束,但它的实现支撑在另一处:StopReason 里有两个专门为此存在的取值。

packages/ai/src/types.ts:489
export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
取值含义谁会处理它
stop正常说完L2 检查有没有工具调用
length撞到输出上限需要「续写」逻辑
toolUse要调工具进 L3 执行
error请求失败带 errorMessage 返回给 L2,L2 直接结束,L1 决定要不要重试
aborted被取消同上,但走取消路径
pending占位(流式未完成)内部状态
deferred延后特殊分支

为什么「错误变成数据」比抛异常好?因为这个错误需要被写进 transcript:

如果抛异常
调用栈直接弹出循环,这条 assistant 消息不存在——历史里少了一轮,下一轮模型会困惑「我明明调了工具,怎么没记录」。
如果编码成 stopReason: "error"
消息照常追加进 transcript(带错误信息),L2 看到 error 正常收尾,L1 从历史里读到这条失败并决定重试。失败也是一条真实发生过的事件。

agent/types.ts:27-38(不抛错契约)· ai/types.ts:489(StopReason)

6.3

配对完整性:为什么它不需要运行时检查

「每个 toolCall 必须有对应的 toolResult」——这是所有 agent 框架最头疼的不变量。 pi 基本不用运行时校验,因为它在结构上就不可能出现。

推理链条是这样:

① ToolResultMessage 只能由内核产生
模型输出的是 AssistantMessage,其中的 toolCall 是内容块,不是消息。模型无法自己「插入工具结果」。
② 内核在同一个循环体内成对写入
L3 里 executedToolBatch 产出结果后立刻 append,不会隔圈。所以「调用」和「结果」在 transcript 里永远相邻且成对。
③ 工具永不 reject,所以每条调用都必然产出结果
这是关键的一环:如果工具能抛错,那就会出现「调用了但没结果」。而它被规定为返回 isError: true 的结果——结果一定存在。
④ 唯一的破坏路径被显式修补
输出截断(stopReason: "length")时可能出现「调用被截半」——pi 在这里合成一条配对错误结果,而不是留下空洞。

第 ③ 和第 ④ 合起来,就是「配对完整」的全部保证。它不靠一个 validateTranscript(), 而是靠让每个可能出错的环节都返回一个合法结果。

对比一下另一种取向:如果框架选择「校验失败就拒绝/报错」,那它必须在每个边界上判断轨迹是否完整, 并且要有「轨迹坏了怎么办」的策略。pi 选择「不产生坏轨迹」,代价是错误处理必须写在每个工具里。 两种都能对,但后者更容易在长时运行中保持稳定。

agent-loop.ts:488(截断时合成配对)· :818(永不 reject 契约)

6.4

ToolDefinition:一个工具要回答的 8 个问题

工具的类型定义本身就是一份规范。一个工具必须声明的事情,恰好是模型和框架各自需要的:

字段给谁回答什么问题
name / label模型 / UI它叫什么
description模型什么时候该用它
parameters(TypeBox schema)模型 + 校验参数长什么样
constrainedSamplingprovider能不能约束解码
prepareArguments框架畸形参数怎么修
execute框架真正做什么
promptSnippet / promptGuidelines模型在系统提示里怎么介绍它
renderShellUI输出怎么渲染

注意 parameters 用的是 TypeBox(Type.Object),它同时提供两样东西: TypeScript 类型(编译期)和 JSON Schema(运行时、发给 provider)。一份声明,三处使用。

packages/coding-agent/src/core/tools/read.ts:14-18
const readSchema = Type.Object({
  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" })),
});

这里还有个容易忽略的细节:description 是给模型看的提示词,不是给人看的文档。 所以它写的是「(1-indexed)」「(optional, no default timeout)」这种防止误用的话,而不是「读取文件」这种废话。

read.ts:14-18

6.5

类型做了四件运行时不用做的事

#不变量靠什么保证省掉了什么
1 线上只有 4 种角色 Message 封闭联合 不用在发送前校验角色合法性
2 失败不会中断循环 StreamFn 契约 + stopReason 不用在每层 try/catch
3 调用与结果成对 工具永不 reject + 截断时合成 不用全量扫描轨迹找孤儿调用
4 工具声明完整 ToolDefinition 必填字段 不用在注册时做字段检查

六章讲完。回头看,pi 的「极简」不在于代码少——而在于它把复杂度放在了边界上: 两个 Message 类型之间、一次模型请求的前后、一个工具的入参和出参之间。 每一处边界都有明确的类型或契约,所以内部可以很小。

这也解释了为什么内核 6 个文件 2,541 行就能跑一个完整 agent:不是省略了功能,是把功能压进了契约里。

《深入理解 pi》六章合订 · 证据锚点固定 commit 531340f