深入理解 pi
单页全本
六章合订。适合 Ctrl+F 搜索与打印。
先看全景:三层循环,不是一个
大多数人对 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 只负责把这一轮跑完。
maxSteps——
「多少轮算太多」是会话层的业务判断,而 L1 现在只判 abort,没有别的终止条件。
想看这一条的分析,去对比站的 故障与恢复 · 控制流真空。
入口只有 6 行
整个 CLI 的启动代码短到可以直接贴完:
#!/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 分派到三种模式之一。
交互模式在这里创建:
} else if (appMode === "interactive") { const interactiveMode = new InteractiveMode(runtime, {
注意 runtime 是构造参数——说明 model runtime 在进 TUI 之前就已经装配好了。
这个顺序很重要:TUI 只负责收集输入和渲染,不负责模型选择。
六道闸门:模型被调用之前
用户按下回车,第一个接到消息的不是模型,而是 session.prompt()。
这个方法值得逐行读,因为它在真正花钱之前设了六道闸门——而每一道都对应一类真实的失败。
| # | 闸门 | 判据 | 拒绝后的结果 |
|---|---|---|---|
| 1 | settle 中? | _isEmittingAgentSettled | 不拒绝——推迟执行(_deferredSettledActions) |
| 2 | 斜杠命令? | text.startsWith("/") | 交给扩展执行,不发模型 |
| 3 | 正在压缩? | _compactionAbortController !== undefined | 抛错,要求等压缩结束 |
| 4 | 扩展要拦截? | _runInputHandlers 返回空 | 静默丢弃 |
| 5 | 正在流式? | this.isStreaming | 必须显式指定 steer 或 followUp,否则抛错 |
| 6 | 模型与凭据? | 有 model、有 auth | 抛错并给出修复命令 |
第 5 道闸门的设计最值得注意:流式期间提交新消息必须显式声明意图。
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 钩子位置)
_startRun:L1 那个循环长什么样
过了六道闸门,进入 _startRun。这里的结构是本篇最需要看懂的一段:
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() 返回 true | settle 之前的钩子要求再跑一轮 | 扩展在 settle 边界注入了新消息 |
所以「一次用户提问」到底跑几轮模型调用,不是由模型决定的,是由 L1 的三个判断决定的: L2 自然停止、post-run 要不要续、settle 边界要不要续。
_prepareRun 在 L2 开始之前就调用了 _checkCompaction。
也就是说压缩发生在「这一轮请求发出前」,而不是等溢出报错才做。
这解释了为什么 pi 的压缩看起来「提前」——它是预防式的。
agent-session.ts:1873(_startRun)· :1899(L1 循环)
重入闸门:activeRun
会话层有六道闸门,内核层只有一道,但它更硬:activeRun。
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 队列,都空才报错:
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)
L2/L3:runLoop 全文骨架
现在到内核。runLoop 从 172 行开始,是 pi 唯一真正的「agent 主循环」。骨架是这样:
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 时立刻返回,不重试_handlePostAgentRun),不在内核。内核只负责「把这次失败如实记进 transcript 并上报」。
这是很干净的分工:内核不理解策略,只理解状态。
hasMoreToolCalls 由工具的 terminate 反向决定hasMoreToolCalls = !executedToolBatch.terminate。所以一个工具可以主动结束整轮。
而 terminate 只在整批都为 true 时才生效(shouldTerminateToolBatch)。
explicitContinuation 允许「只跑一轮上下文」finishTurn 返回 action: "continue" 但没有工具调用也没有排队消息,
外层会再跑一圈——用于「需要一次纯上下文请求」的场景。它会被任何真实消息重置,所以不会白白多跑。
agent-loop.ts:172(runLoop)· :188 L2 · :192 L3
格式边界:AgentMessage[] → Message[]
这是全篇最容易混淆的一处。pi 里有两种消息类型,不是一种:
| 类型 | 定义 | 谁用它 | 特点 |
|---|---|---|---|
AgentMessage |
Message | CustomAgentMessages[keyof] |
transcript(会话记忆) | 开放——扩展可注册自己的消息类型 |
Message |
System | User | Assistant | ToolResult |
发给模型的线上格式 | 封闭四元组——就这四种 |
转换发生在每次请求之前,而且可插拔:
// 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 });
三段各管一件事,顺序不能换:
| 阶段 | 输入→输出 | 做什么 |
|---|---|---|
transformContext | AgentMessage[] → AgentMessage[] | 改写会话内容(压缩、注入、裁剪) |
convertToLlm | AgentMessage[] → Message[] | 把扩展的自定义消息翻译成四元组之一 |
normalizeContext | Message[] → TranscriptContext | 补齐协议要求的结构 |
coding-agent 注入的实现叫 convertToLlmWithBlockImages——名字就说明了它额外做的一件事:处理被拦下的图片。
convertToLlm,而不是去翻 transcript。
agent-loop.ts:399 · :404 · sdk.ts:411(注入的实现)
落盘:一次提问的最后一步
消息进了 transcript 不代表存下来了。真正写文件的是 _appendEntry → _persist,而 _persist 有个容易被忽略的首次写逻辑。
_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 只有四行,但它定义了整棵树的生长方式:
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.prompt()_startRun → _prepareRunbefore_agent_start,再装配起始消息。agent.prompt() → 过 activeRun 闸门 → runLoopstreamAssistantResponse 做三次转换:transform → convert → normalize。isError 结果——这是「错误即输入」的落点。_appendEntry 推进 leafId → _persist 追加一行 JSONLwx 排他创建并补写缓冲,之后纯 append。continue()一句话总结:L2 负责「跑完这一轮」,L1 负责「决定还要不要下一轮」,而 JSONL 在两者之间持续记录真实发生的事。 后面五章都是这条链上的局部放大。
「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,不放弃保护。为什么不是「一个消息数组」
最简单的会话存储是一个数组:往后面 push,读的时候整个读出来。pi 不用这个方案,因为有三件事它做不到:
| 需求 | 数组方案的困境 | 树方案的解 |
|---|---|---|
| 回到某一步重来 | 要么复制整个前缀,要么丢掉后面 | 把 leafId 指回旧条目,下一条自然长在那里 |
| 压缩后仍能查原始消息 | 摘要一旦写入,原文就没了 | 摘要是新条目,原条目仍在文件里 |
| 崩溃后不丢数据 | 整文件重写有窗口期 | 一次追加一行,写多少算多少 |
代价也很明确:读的时候要重建。数组是 O(1) 读,树是 O(深度) 回溯。 pi 接受了这个代价,换来的是「历史不可变、状态可分支」。
条目:11 种类型,全都是事件
会话文件里的每一行是一个 SessionEntry,而它是 11 种类型的联合:
export type SessionEntry = | SessionMessageEntry // 一条对话消息 | ThinkingLevelChangeEntry // 思考档位变更 | ModelChangeEntry // 换模型 | UsageEntry // 用量记账 | CompactionEntry // 压缩摘要 | BranchSummaryEntry // 分支摘要 | CustomEntry // 扩展自定义状态 | CustomMessageEntry // 扩展自定义消息 | ContextEditEntry // 上下文编辑 | LabelEntry // 打标签 | SessionInfoEntry; // 会话元信息
注意里面没有一个是「当前状态」字段。当前用什么模型、思考档位多高,都不是存在某个可变字段里, 而是由历史事件推导出来的:
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(推导当前设置)
生长:四行代码定义的树
树的全部生长逻辑就在 _appendEntry 里,而它的核心只有一行 this.leafId = entry.id:
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,形成一条直线。文件里看不出树,因为退化成了链。leafId 设回第 3 条。下一条消息的 parentId 就是第 3 条——不需要复制任何历史,分支自然出现。parentId 链条走向哪里。文件是纯追加的,旧分支一个字都没改。读:回溯 + 反转
读一条路径的逻辑简单到有点朴素——从叶子开始沿 parentId 往回走,然后反转:
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 失效(旧文件、被删条目)时退回最后一条,不报错——容错优先 |
一个迁移里的关键决定:索引 → ID
这是本篇最想让你注意的一处。会话格式从 v1 升到 v2 时加了 id/parentId,
同时把压缩条目里的 firstKeptEntryIndex 换成了 firstKeptEntryId。
/** 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 串起来——不需要推断任何分支结构。
落盘:排他创建 + 惰性补写
append-only 只是逻辑模型,物理写入还有个首次写的特殊情况:
_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 | 可流式读、可断点续、坏一行不影响前面 |
一句话记住它
这套结构的本质是:文件是日志,树是日志的读法,状态是历史的函数。
| 你以为它是 | 实际上是 | 推论 |
|---|---|---|
| 一个可变的消息数组 | 只追加的 JSONL 日志 | 永远不需要「保存」——每一步都已经是保存 |
| 一个有分支的树对象 | 一批带 parentId 的条目 | 分支是「把叶子指针挪一下」,零拷贝 |
| 一份当前设置 | 一串变更事件 | 回放旧分支拿到旧设置,不会串味 |
下一章要讲的压缩,正是这套结构最重要的使用者——因为压缩必须在不破坏历史的前提下,改变「模型看到什么」。 如果历史是可变的,压缩就变成了「删掉旧消息」;而在这里,压缩只是追加一条新的摘要条目。
什么时候压:一个不等式
压缩的触发条件只有一行,但它包含两个可调参数:
contextTokens > contextWindow - settings.reserveTokens
| 参数 | 默认 | 含义 |
|---|---|---|
reserveTokens | 16,384 | 给「下一轮回复」预留的空间。不留就会压完立刻再溢出 |
keepRecentTokens | 20,000 | 压缩后保留的近期原文量。太少会丢细节,太多压了等于没压 |
两个数解决的是不同问题:reserveTokens 是为了能继续说话,keepRecentTokens 是为了还记得刚才在干什么。
注意它们是同一个方向上的拉扯——保留越多,能留的对话轮次越少。
compaction.ts:269(触发)· :128-129(默认值)
切点算法:从末尾倒着走
决定「从哪条开始保留」的算法是压缩的核心。它的方向很关键——从最新往回数,而不是从最旧往前数。
/** * 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] | 找不到时退化成「什么都不压」的失控 |
split turn:切在一轮中间怎么办
倒着数到 keepRecentTokens 时,很可能正好落在**一个 turn 的中间**——用户说了话、模型回了、工具跑了,但这一轮还没结束。
这时切下去会留下一段「没有开头的对话」。
pi 的解法是记录两个额外信息,而不是硬切:
| 返回字段 | 作用 |
|---|---|
firstKeptEntryIndex | 保留区从哪条开始 |
turnStartIndex | 若是 split,这一轮起头的那条用户消息在哪 |
isSplitTurn | 是否切在轮次中间 |
于是 turnPrefixMessages 出现了——被切掉的那半轮单独摘要,而不是混进主摘要:
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 | 未完成的那半轮开头 | 要明确标出「这一轮还没结束」,否则摘要会说成已完成 |
投影:为什么不能「摘要的摘要」
如果一份会话被压过三次,第四次压缩时该拿什么当输入?直觉答案是「上次的摘要 + 之后的新消息」。 但那样会有一个隐蔽的问题:上次摘要自己也是被压过的,再算 token 预算就会算错。
pi 的处理叫 projection——先把所有压缩条目「投影」成消息形态,再做切点计算:
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)。
previousSummary 直接传给下一次压缩,让它「在新摘要里带上旧摘要」。
这样信息不会随压缩次数指数衰减——这是长篇会话能一直跑下去的关键。
previousSummary 的 carry-forward 正是因为意识到这件事。
摘要本身就是一次模型调用
压缩不是本地算法,它要花一次完整的模型调用。这就带来一个必须防的问题:摘要模型可能在摘要时调用工具。
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"); }
为什么这算错误而不是「忽略工具调用取文本」?因为摘要调用不该有工具—— 如果模型调了工具,说明它误解了任务(以为自己在继续干活),此时它输出的文本很可能不是摘要。 宁可失败重来,也不要拿一段莫名其妙的文本当摘要写进历史。
而系统提示词的第二句正是在防这件事:
「不要回答对话里的问题」这句看起来多余,其实是最容易犯的错:历史里往往有用户提问, 摘要模型很容易顺手就答了——答完就不是摘要了。
compaction.ts:747(工具调用护栏)· utils.ts:161-163(系统提示)
压缩的四个决定
| # | 决定 | 取值 / 做法 | 为什么 |
|---|---|---|---|
| 1 | 何时压 | tokens > window − 16,384 |
预留回复空间;提前压而不是等溢出报错 |
| 2 | 保留多少 | 倒着数到 20,000 token | 保证「最近发生了什么」还在原文里 |
| 3 | 切在哪 | 只在合法切点(永不切工具结果) | 保住调用/结果配对,轨迹结构不坏 |
| 4 | 旧摘要怎么办 | carry forward,不重新摘要 | 避免信息随压缩次数指数衰减 |
可以看到,压缩真正的难点不在「怎么总结」——那是模型的事。
难点全在「切在哪」「旧信息怎么带上」「切坏了怎么办」这三个结构问题上。
这也是为什么 compaction.ts 有近千行,而摘要提示词只有三句。
32 个挂点,6 个能改
pi 的扩展面是一个 32 个事件的联合类型。但真正决定架构的不是「有多少个」,而是哪些能改返回值。
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 个是纯观察。
| # | 可改事件 | 能改什么 | 性质 |
|---|---|---|---|
| 1 | ProjectTrustEvent | 信任决定 | 拦截 |
| 2 | BeforeAgentStartEvent | systemPrompt 整段替换、注入消息 | 拦截 |
| 3 | ContextEvent | messages 整个数组 | 改写 |
| 4 | ToolCallEvent | block 拒绝、原地改 input | 拦截 |
| 5 | ToolResultEvent | 结果内容、isError、用量 | 改写 |
| 6 | MessageEndEvent | 替换最终消息(角色不可变) | 改写 |
types.ts:1411-1443(32 事件)· :1460(ToolCallEventResult)
ToolCall 的三种用法,一个字段
ToolCallEventResult 只有三个字段,但它覆盖了「拦住」「改参数」「提前结束」三种完全不同的意图:
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,才会提前结束。
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 注释)
顺序:为什么 input 钩子必须在展开之前
input 事件的挂点在 prompt() 里,位置很讲究——它在 skill 展开与模板替换之前。
这个顺序不成立的话,扩展就无法工作:
| 顺序 | 扩展看到的输入 | 能做什么 |
|---|---|---|
| 展开之前拦截(pi 的做法) | 用户原话 | 改写、加前缀、整体吞掉 |
| 展开之后拦截 | 已拼装的完整 prompt | 只能做「整段替换」,改写原话已不可能 |
同一条链上还有一个顺序决定:skill 展开先于 template 展开。 因为 skill 是「可能带参数的指令块」,template 是「纯文本替换」——前者更结构化,先做才能让后者处理它的产物。
agent-session.ts:2117(input 钩子)
Context 事件:最危险的那个
ContextEvent 的返回值是 { messages?: AgentMessage[] }——整个消息数组都能换掉。
这是能力最大、也最容易搞坏东西的一个。
它挂在 transformContext 上,在 convertToLlm 之前执行:
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
扩展面的三条边界
ContextEvent 只改「这一份请求」,会话文件不变。想持久化得写 CustomMessageEntry。terminate 要求 every() 而非 some()。这三条合起来说明一件事:pi 的扩展不是「插件随便改框架」,而是「在框架划定的语义边界上做加法」。 能力是受限的,但受限让它可预测。
两个 Message,一个边界
第 1 章提过这两种类型,这一章讲它们为什么必须分开。
export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
export type Message = SystemMessage | UserMessage | AssistantMessage | ToolResultMessage;
| 类型 | 形状 | 语义 | 为什么这样做 |
|---|---|---|---|
Message |
封闭四元组 | 所有模型 API 都认的四种角色 | 线上协议就是这四种,多一种都没有意义 |
AgentMessage |
开放(申明合并) | 会话记忆里的任意东西 | 扩展可以注册自己的消息类型,内核不必知道 |
CustomAgentMessages 是一个由扩展「声明合并」(declaration merging)扩充的接口。
于是出现了这个局面:内核代码里出现的类型是开放的,但真正发出去的形状是封闭的——两者之间必须有一次显式转换。
这次转换就是 convertToLlm。它的函数签名本身就说明了责任:
convertToLlm: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
Message 是封闭的,
任何自定义消息类型都必须提供一个「怎么变成四元组之一」的答案,否则代码根本编译不过。
编译器替你把「不许发明新的线上角色」这条规则守住了。
agent/types.ts:374(开放)· ai/types.ts:659(封闭)
StreamFn:不许抛错
这是 pi 类型系统里最强的一条契约,而且它写在注释里:
/** * 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 里有两个专门为此存在的取值。
export type StopReason = "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";
| 取值 | 含义 | 谁会处理它 |
|---|---|---|
stop | 正常说完 | L2 检查有没有工具调用 |
length | 撞到输出上限 | 需要「续写」逻辑 |
toolUse | 要调工具 | 进 L3 执行 |
error | 请求失败 | 带 errorMessage 返回给 L2,L2 直接结束,L1 决定要不要重试 |
aborted | 被取消 | 同上,但走取消路径 |
pending | 占位(流式未完成) | 内部状态 |
deferred | 延后 | 特殊分支 |
为什么「错误变成数据」比抛异常好?因为这个错误需要被写进 transcript:
stopReason: "error"error 正常收尾,L1 从历史里读到这条失败并决定重试。失败也是一条真实发生过的事件。agent/types.ts:27-38(不抛错契约)· ai/types.ts:489(StopReason)
配对完整性:为什么它不需要运行时检查
「每个 toolCall 必须有对应的 toolResult」——这是所有 agent 框架最头疼的不变量。 pi 基本不用运行时校验,因为它在结构上就不可能出现。
推理链条是这样:
ToolResultMessage 只能由内核产生AssistantMessage,其中的 toolCall 是内容块,不是消息。模型无法自己「插入工具结果」。executedToolBatch 产出结果后立刻 append,不会隔圈。所以「调用」和「结果」在 transcript 里永远相邻且成对。isError: true 的结果——结果一定存在。stopReason: "length")时可能出现「调用被截半」——pi 在这里合成一条配对错误结果,而不是留下空洞。
第 ③ 和第 ④ 合起来,就是「配对完整」的全部保证。它不靠一个 validateTranscript(),
而是靠让每个可能出错的环节都返回一个合法结果。
agent-loop.ts:488(截断时合成配对)· :818(永不 reject 契约)
ToolDefinition:一个工具要回答的 8 个问题
工具的类型定义本身就是一份规范。一个工具必须声明的事情,恰好是模型和框架各自需要的:
| 字段 | 给谁 | 回答什么问题 |
|---|---|---|
name / label | 模型 / UI | 它叫什么 |
description | 模型 | 什么时候该用它 |
parameters(TypeBox schema) | 模型 + 校验 | 参数长什么样 |
constrainedSampling | provider | 能不能约束解码 |
prepareArguments | 框架 | 畸形参数怎么修 |
execute | 框架 | 真正做什么 |
promptSnippet / promptGuidelines | 模型 | 在系统提示里怎么介绍它 |
renderShell | UI | 输出怎么渲染 |
注意 parameters 用的是 TypeBox(Type.Object),它同时提供两样东西:
TypeScript 类型(编译期)和 JSON Schema(运行时、发给 provider)。一份声明,三处使用。
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)」这种防止误用的话,而不是「读取文件」这种废话。
类型做了四件运行时不用做的事
| # | 不变量 | 靠什么保证 | 省掉了什么 |
|---|---|---|---|
| 1 | 线上只有 4 种角色 | Message 封闭联合 |
不用在发送前校验角色合法性 |
| 2 | 失败不会中断循环 | StreamFn 契约 + stopReason |
不用在每层 try/catch |
| 3 | 调用与结果成对 | 工具永不 reject + 截断时合成 | 不用全量扫描轨迹找孤儿调用 |
| 4 | 工具声明完整 | ToolDefinition 必填字段 |
不用在注册时做字段检查 |
六章讲完。回头看,pi 的「极简」不在于代码少——而在于它把复杂度放在了边界上: 两个 Message 类型之间、一次模型请求的前后、一个工具的入参和出参之间。 每一处边界都有明确的类型或契约,所以内部可以很小。
这也解释了为什么内核 6 个文件 2,541 行就能跑一个完整 agent:不是省略了功能,是把功能压进了契约里。
531340f