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

深入理解 pi/第 01 章

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 在两者之间持续记录真实发生的事。 后面五章都是这条链上的局部放大。

本章学习记录

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