深入理解 pi/第 01 章
先看全景:三层循环,不是一个
大多数人对 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 在两者之间持续记录真实发生的事。 后面五章都是这条链上的局部放大。