Agent Loop —— 两层循环,三条出路
上一章我们把 12 个包摊在桌上,看清了分层:coding-agent 管业务,agent 是无状态内核,ai 统一各家模型。
但架构图是静态的。Agent 之所以是 Agent,靠的是 packages/agent/src/agent-loop.ts 里那个 while (true)。
这个文件 960 行,导出 5 个函数。它是全仓库里"投入产出比"最高的一段——不到一千行,定义了所有上层共享的执行语义:CLI 的交互模式、TUI 的流式渲染、durable 的可持久化运行时、chord 的插件宿主,全都建在这套语义之上。
这一章把它拆开。读完你应该能回答三个问题:
- 一次
pi "找出所有 TODO"到底发生了什么? - 循环什么时候继续、什么时候停?
- 用户跑到一半插一句话,是怎么被"插"进去的?
一、引子:同一个模型,三种用法
假设你手里有个不错的模型,想让它"帮我改代码"。有三种做法。
模式 1:直接调用。 一次请求,一次回答。你把代码贴进去,把结果贴出来。
const reply = await model.chat([{ role: "user", content: "把 foo 改成 bar" }]);模型不知道 foo 在哪,你也没给它工具。它能做的只有猜着写。
模式 2:Workflow。 你写死流程:先读文件,再让模型改,再写回去。
const before = await readFile("a.ts");const patched = await model.chat(`把这段里的 foo 改成 bar:\n${before}`);await writeFile("a.ts", patched);这能干活了。但流程是你定的。文件太大怎么办?改错了怎么办?要不要先 grep 一下?——这些分支都得你提前想到。分支一多,你就写了个编译器,而不是在写业务。
模式 3:Agent Loop。 你给模型工具和一句目标,让它自己决定下一步。
await agent.prompt("找出所有 TODO 并修复");// 它自己决定:先 grep,看到 3 处结果,再 read,再 edit,最后说"改完了"区别不在模型,在谁掌握控制流:
| 控制流在谁手里 | 模型调用次数 | 能跑多久 | |
|---|---|---|---|
| 直接调用 | 你的代码 | 1 | 一次 |
| Workflow | 你的代码 | N(你写死) | 固定步数 |
| Agent Loop | 模型 | N(运行时决定) | 直到模型说停 |
把控制流交给概率模型,代价是它可能停不下来、可能绕圈、可能在 rm -rf 之前不问一声。
所以一个能用的 Agent Loop,真正的工作量不在"循环"本身,在围住循环的那圈硬约束:步数、token、abort 信号、工具权限、输出截断、失败重试。
下面看 Pi 怎么围。
二、先把词对齐
后面会反复用到三个词,先钉死定义。
Run(一次运行):从用户按下回车,到 agent 彻底空闲。事件流里对应 agent_start 和 agent_end。旧教程管它叫 Trace。
Turn(一轮):一次 assistant 回应 + 它发起的全部工具调用 + 全部工具结果。一个 run 包含 N 个 turn(N ≥ 1),对应 turn_start / turn_end(packages/agent/src/types.ts:533-534)。
Event(事件):循环向外界发出的通知。AgentEvent 一共定义了 10 种(packages/agent/src/types.ts:528-551):
export type AgentEvent = // Agent 生命周期 | { type: "agent_start" } | { type: "agent_end"; messages: AgentMessage[] } // Turn 生命周期:一次 assistant 回应 + 它的工具调用与结果 | { type: "turn_start" } | { type: "turn_end"; message: AgentMessage; toolResults: ToolResultMessage[] } // Message 生命周期 | { type: "message_start"; message: AgentMessage } | { type: "message_update"; message: AgentMessage; assistantMessageEvent: AssistantMessageEvent; } | { type: "message_end"; message: AgentMessage } // Tool 执行生命周期 | { type: "tool_execution_start"; toolCallId: string; toolName: string; args: any; } | { type: "tool_execution_update"; toolCallId: string; toolName: string; args: any; partialResult: any; } | { type: "tool_execution_end"; toolCallId: string; toolName: string; result: any; isError: boolean; durationMs?: number; };三句话概括这三层的关系:
- 一个 run 拆成若干 turn;
- 一个 turn 拆成若干 message(assistant 一条,外加 N 条 toolResult);
- 一条 message 在流式过程中拆成若干
message_update。
循环只 emit 事件,不碰 UI。 这是它能被四种宿主复用的根本原因。
宿主可以追加自己的事件。 内核的 10 种到这里就完了;coding-agent 在会话层又加了一个 agent_settled(packages/coding-agent/src/core/agent-session.ts:216 定义、:1100 发出),意思是"这一轮彻底停了,连同排队里的活"。后面某章的输出里看到它时,别去 AgentEvent 里找——它不在那儿。
三、全景:一次 prompt 的完整旅程
先看图,再逐个拆。
pi.prompt("找出所有 TODO") │ ├─ Agent.prompt() agent.ts:380 │ └─ runWithLifecycle() agent.ts:517 │ └─ runAgentLoop() agent-loop.ts:111 │ ├─ declareToolChanges() agent-loop.ts:119 │ ├─ emit agent_start agent-loop.ts:126 │ ├─ emit turn_start agent-loop.ts:127 │ ├─ emit user message pair agent-loop.ts:128-131 │ └─ runLoop() agent-loop.ts:172 │ │ │ ├─ prepareNextTurn() :195 │ ├─ prepareRequest() :228 │ ├─ streamAssistantResponse :251 │ ├─ executeToolCalls() :279 │ ├─ finishTurn() :295 │ ├─ getSteeringMessages() :304 │ └─ getFollowUpMessages() :311 │ └─ emit agent_end agent-loop.ts:329 └─ stream.end(messages) agent-loop.ts:66一个跑了两轮的 run,完整事件序列如下。第 1 轮调了一次 read,第 2 轮模型只回文本;带 · 的行不发事件,只是同一段时间里在跑的钩子。
行号只有一份来源:packages/agent/src/agent-loop.ts(960 行)——本节和后面几张表里凡是光写 :NNN 的,都指它;来自别的文件一定带全名。末尾的「存」标的是这条消息被写进 currentContext.messages(也就是下一轮的输入)的那一行:存 = append 一条新的,换 = 原地替换同一格。既没 存 也没 换 的行只发事件,不动上下文。
── 开场,一次 run 只走一遍 ────────────agent_start :126 全 run 只这一次turn_start :127 第 1 轮的 turn_start 在这 message_start :129 每条 initialMessage 一对: message_end :130 (system) 工具声明,工具集变了才有 (user) 你敲的那句 prompt 两条都在 :123 拼进 messages── 第 1 轮 ────────────────────────── · getSteeringMessages :185 开场 emit 完,进 runLoop 先捞一次 · prepareNextTurn :194 第 1 轮不跑:lastCompletedTurn 还不存在 message_start :221 (插话) 上一步真捞到了才有这两行 message_end :222 存 :223 · prepareRequest :228 message_start :430 (assistant) partial 占位 存 :428 message_update :446 × N,流式增量 换 :444 message_end :464 text/thinking/toolCall 全在这条 换 :457 tool_execution_start :608 每个调用一行,并行先连发完 :606 tool_execution_update :792 × N,多个调用穿插 tool_execution_end :931 message_start :957 (toolResult) 存 :284 message_end :958 · finishTurn :295 返回值决定要不要给 agent 续命turn_end :296── 第 2 轮起,每一轮都长这样 ──────────── · prepareNextTurn :195 两轮之间:可换 model、换整个 context · getSteeringMessages :214 压缩能跑几十秒,期间插的话在这儿捞turn_start :216 换到 runLoop 里发 message_start :221 (插话/追问/prepareNextTurn 交来的消息) message_end :222 没有注入就跳过这两行 存 :223 · prepareRequest :228 message_start :430 (assistant) message_update :446 × N message_end :464 ……这轮还要调工具,就重复上面那六行…… · finishTurn :295turn_end :296── 收尾,三条路都终于 agent_end ──────────:263 error / aborted:turn_end(:262) 紧跟 agent_end, 不发 tool_*,不拉两个队列,toolResults 是空数组:299 finishTurn 返回 end:turn_end(:296) 后立刻 agent_end,同样不拉队列:329 正常停下:steering(:304) 空 → follow-up(:311) 空 → 续命记号(:320) 没立 → break(:326) → agent_end把上面那些 存 / 换 按顺序排好,第 2 轮 :251 发请求时的那个数组就长这样——这正是上一问的答案:上一轮的东西整串带走,一条不裁:
── 第 2 轮的请求载荷:currentContext.messages 原样摊开 ──[0] (system) 工具声明差量,工具集没变就没这条 造 :119 存 :123[1] (user) "找出所有 TODO" 存 :123[2] (assistant) 第 1 轮的 text + thinking + 1 个 read 存 :428 换 :457[3] (toolResult) read 的返回 存 :284[4] (user) 插话,:214 捞到才有 存 :223 ── 第 1 轮的全部输出 = [2] + [3],全在这,不删不改 ──[5] (assistant) 第 2 轮的回答:请求发出去之后才 append 进来:251 把 currentContext 整个交给 streamAssistantResponse,后者从 :398 起一路把这串数组重拼、重发(7.1 的三级流水线)。内核自己一行剪枝代码都没有:数组只增不减,想让它变小只有两条路,都在宿主手里——transformContext(:400)在语义层剪,或者 prepareNextTurn(:197)交一份全新的 context 顶掉旧的。逐条总账在 7.5。
[0] 那行容易看错:transcript 里的 system 消息不是完整提示词,是差量补丁。发请求前由 getCurrentSystemMessage()(packages/ai/src/utils/transcript.ts:73-96)把历条 system 重放成头部一条:content 逐段追加、sections 按名覆盖、值为 null 就删节、工具按 toolsAdded / toolsRemoved 增删。碰上不支持会话中途 system 的模型,还要过一道 collapseSystemMessages(:108-120):后面的 system 全删,只留重放的那条;调用点在各 provider 开头(anthropic-messages.ts:583、openai-completions.ts:316、bedrock-converse-stream.ts:145)。存的是差量,模型看到的是重放后的全量;agent.ts:369 的 reset() 敢清空历史只留一条 baseline,靠的就是这个性质。
三个折扣得记住:进了 transcript 不等于进了请求——自定义 role 会被 convertToLlm(:404)滤掉,tools 字段压根不进请求,thinking 重不重发由 provider 定。这三条 7.5 逐个展开。
四处不对称得点清。agent_start 全 run 只发一次(:126,它在 runLoop 外面);prompt 那条 user 只在开场 emit(:128-131),后面每轮的 :221-222 管的是插话、追问和 prepareNextTurn 交来的消息;turn_start 有两个发出点(:127、:216),为什么不会重发,5.5 专门讲;prepareNextTurn 只在第 2 轮之后跑(:194 要求 lastCompletedTurn 存在),所以第 1 轮的请求只被 prepareRequest 动过。
还有一处顺序容易记反:第 2 轮是 prepareNextTurn 和两次 steering Poll 先跑,然后才 turn_start(:216)。也就是说钩子比"新一轮开始"这个信号更早——UI 看到 turn_start 时,模型和上下文已经换过了。
一轮里有多个工具调用时,并行模式下 tool_execution_start 会连着发完才进 Promise.all(:606-656),tool_execution_end 和后面那对 toolResult 按源序逐个发(:931、:957),中间的 update 穿插;串行模式(:540 起)一个调用走完整四行才轮到下个。撞上限被截断那一轮更省事:failToolCallsFromTruncatedMessage 对每个调用只发 start→end→toolResult 三下(:494-509),没有 update,isError: true,而且 terminate: false(:512)——循环照转,等于给模型一次重发的机会(9.5 节)。
有个不变量值得记牢:只要进入一个 turn,就必然产出一条 assistant 消息。因为内层循环每次迭代,除了开头注入待处理消息,第一件正事就是请求模型(agent-loop.ts:251)。没有别的分支。
四、五个函数,撑起一个循环
agent-loop.ts 对外只暴露 4 个类型 / 常量 + 5 个函数:
| 导出 | 签名 | 行号 |
|---|---|---|
agentLoop |
(...) => EventStream |
:47 |
agentLoopContinue |
(...) => EventStream |
:80 |
runAgentLoop |
(...) => Promise<AgentMessage[]> |
:111 |
runAgentLoopContinue |
(...) => Promise<AgentMessage[]> |
:137 |
runToolCall |
(toolCall, options) => Promise<AgentToolCallOutcome> |
:821 |
前四个构成一个 2×2 矩阵:
| 带新消息 | 不带新消息 | |
|---|---|---|
| 返回流 | agentLoop |
agentLoopContinue |
| 返回 Promise | runAgentLoop |
runAgentLoopContinue |
带不带新消息很好理解:prompt 要往上下文里塞一条 user,continue 是"接着上次"(重试,或者工具结果已经在上下文里了)。
返回流还是 Promise,是留给不同宿主的选择。
4.1 为什么 agentLoop 不是 async
看 agent-loop.ts:47-70:
export function agentLoop( prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal: AbortSignal | undefined, streamFn: StreamFn,): EventStream<AgentEvent, AgentMessage[]> { const stream = createAgentStream(); void runAgentLoop( prompts, context, config, async (event) => { stream.push(event); }, signal, streamFn, ).then((messages) => { stream.end(messages); }); return stream;}三个细节。
一,函数不带 async。 一旦加上,返回值就变成 Promise<EventStream>,调用方得先 await 才能拿到流——那么在第一个事件到来之前,调用方是"瞎"的,UI 没法边跑边渲染。
二,void 前缀 + .then,而不是 await。 这是"同步返回句柄、异步推进"的标准写法:void 告诉类型系统"我不关心这个 promise 的去向",.then 只负责在结束时把结果交给流。
三,事件泵是一个箭头函数。 它满足 AgentEventSink 的定义(:35):
export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;循环不知道流的存在,只知道"有个地方能接事件"。这个缝隙让上层可以换成日志、遥测、录制回放。
4.2 agent_end 一身二职
function createAgentStream(): EventStream<AgentEvent, AgentMessage[]> { // :162 return new EventStream<AgentEvent, AgentMessage[]>( (event: AgentEvent) => event.type === "agent_end", (event: AgentEvent) => (event.type === "agent_end" ? event.messages : []), );}EventStream 的构造函数收两个谓词:isComplete 和 extractResult(packages/ai/src/utils/event-stream.ts:35-41)。
于是 agent_end 同时承担两件事:
- 它是最后一个事件(推给 UI 的"跑完了"通知);
- 它同时是结果载体(
stream.result()的值)。
一个事件干两份活,省掉了"事件流 + 另一个 Promise"的配对。代价是:想知道结果,就必须等它跑完。
4.3 continue 的两道前置校验
agentLoopContinue 开头两道检查(:86-92),runAgentLoopContinue 里又重复了一遍(:144-150):
if (context.messages.length === 0) { throw new Error("Cannot continue: no messages in context");}if (context.messages[context.messages.length - 1].role === "assistant") { throw new Error("Cannot continue from message role: assistant");}为什么最后一条不能是 assistant?因为 provider 要求最后一条是 user 或 toolResult——你让模型接着自己上一句话往下说,大多数 API 直接 400。
注释里(:76-78)还坦白了一件更有意思的事:
This cannot be validated here since
convertToLlmis only called once per turn.
真正合不合法,取决于 convertToLlm 把 AgentMessage 转成了什么,而那一步每轮只跑一次。这里只能查"原始 role",查不了"转换后的 role"。
能查的查到底,查不了的写进契约——这个态度在整章会反复出现。
4.4 文件头那 13 个符号,划出了内核的势力范围
import { type AssistantMessage, type ClientIdentity, EventStream, getCurrentTools, getToolStateChanges, mergeClientIdentity, normalizeContext, PI_ATTRIBUTION, type SystemMessage, type ToolResultMessage, type ToolStateChanges, toToolDeclaration, validateToolArguments,} from "@earendil-works/pi-ai";import { getDefaultStreamFn } from "./stream-fn.ts";13 个符号全来自 pi-ai,没有一个是 coding-agent 的。这不是巧合,是分层的结果——packages/agent/package.json 的 dependencies 只有两个:pi-ai 和 pi-schema。M02 §8.1 把这件事叫"依赖定编译边界":箭头指谁,谁就得先 build;至于运行时真正干活的是谁,那是注入的事。而 pi-schema 在整个包里只露过一次面(types.ts:17):
import type { Static } from "@earendil-works/pi-schema";用来把工具参数的 schema 推导成 TS 类型(types.ts:466)。纯类型,零运行时。真正跑起来的时候,agent 包只认 pi-ai。
按职责分一下这 13 个:
| 符号 | 干什么 | 本章位置 |
|---|---|---|
EventStream |
流句柄,两个谓词定终局 | :163 |
normalizeContext |
补齐 transcript 结构 | :406 |
mergeClientIdentity |
请求身份,字段级合并 | :415 |
PI_ATTRIBUTION |
pi 的默认署名 | :41 |
getCurrentTools |
从 transcript 反推模型手上有哪些工具 | :356 |
getToolStateChanges |
比对出增删差异 | :356 |
toToolDeclaration |
可执行工具 → 可声明工具 | :358 |
validateToolArguments |
参数校验 | :737 |
AssistantMessage / SystemMessage / ToolResultMessage |
消息类型 | 到处 |
ClientIdentity / ToolStateChanges |
类型 | :41 / :374 |
有两个符号值得单独说,因为它们悄悄重新定义了"状态"这个词。
getCurrentTools 收的不是工具列表,是消息数组。 调用长这样(:356-359):
const changes = getToolStateChanges( getCurrentTools([...context.messages, ...baseline]), (context.tools ?? []).map(toToolDeclaration),);它从 transcript 里那几条 system 消息的 toolsAdded / toolsRemoved 一路加加减减,算出现在模型"以为"手上有哪些工具。换句话说,工具集是从历史里读出来的,不是某个变量存着的。
mergeClientIdentity 是字段级合并,不是整体替换。 实现在 ai/src/utils/identity.ts:49-59,逐字段判 !== undefined 才覆盖。所以默认身份只声明了 { attribution },宿主要加 userAgent、version,只给差量就行。
顺带一个细节:attribution 的注释写着"null 也会关掉合并身份带来的署名"。undefined 表示"我没意见",null 表示"明确不要"——两个空值在这里语义相反。这个三态写法在第七章还会撞见一次(thinkingLevel)。
这两个函数合起来给内核立了规矩:能从 transcript 推出来的不存变量;能用增量表达的不做整体覆盖。第七章会以"变更即追加"的名字正式登场。
五、两层循环
5.1 骨架
runLoop(:172-330)是全部逻辑所在。抽掉细节,骨架长这样:
let pendingMessages: AgentMessage[] = (await config.getSteeringMessages?.()) || []; // :185while (true) { // :188 外层 let hasMoreToolCalls = true; while (hasMoreToolCalls || pendingMessages.length > 0) { // :192 内层 // ... prepareNextTurn / 注入消息 / prepareRequest const message = await streamAssistantResponse(...); // :251 if (message.stopReason === "error" || message.stopReason === "aborted") { // :254-264 硬退出 return; } const toolCalls = message.content.filter((c) => c.type === "toolCall"); // :268 hasMoreToolCalls = false; if (toolCalls.length > 0) { const executedToolBatch = message.stopReason === "length" ? await failToolCallsFromTruncatedMessage(toolCalls, emit) // :278 : await executeToolCalls(currentContext, ...); // :279 hasMoreToolCalls = !executedToolBatch.terminate; // :281 } const decision = await config.finishTurn?.(lastCompletedTurn, signal); // :295 await emit({ type: "turn_end", message, toolResults }); // :296 if (decision?.action === "end") { // :298 await emit({ type: "agent_end", messages: newMessages }); return; } explicitContinuation = decision?.action === "continue"; // :303 pendingMessages = (await config.getSteeringMessages?.()) || []; // :304 if (hasMoreToolCalls || pendingMessages.length > 0) { explicitContinuation = false; // :306 } } const followUpMessages = (await config.getFollowUpMessages?.()) || []; // :311 if (followUpMessages.length > 0) { explicitContinuation = false; pendingMessages = followUpMessages; continue; } if (explicitContinuation) { // :320 explicitContinuation = false; continue; } break; // :326}await emit({ type: "agent_end", messages: newMessages }); // :3295.2 内层在转什么
内层是"模型 ↔ 工具"的锯齿:
模型说"我要 grep" → 执行 grep → 把结果塞回去 → 模型再说 → ...
hasMoreToolCalls 就是齿距。它的赋值只有三处:
| 行号 | 赋成 | 含义 |
|---|---|---|
:189 |
true |
进内层时先假定"还有" |
:271 |
false |
这轮没有工具调用?先按"停"算 |
:281 |
!batch.terminate |
有调用,且没被全体要求终止 → 继续 |
注意 :271 在 if (toolCalls.length > 0) 之前。这个顺序很讲究:先默认停,再看有没有调用。没有就自然退出,逻辑上不需要 else 分支。
5.3 外层在补什么
内层停下有三种原因:没工具了、没插话了、被 terminate 了。
但"内层停了"不等于"这次 run 该结束"。外层依次问三个问题:
- 有 follow-up 吗?(
:311)用户排着队等 agent 干完这轮再说的消息。有就塞进pendingMessages,continue回外层顶部,重开内层。 - 宿主要 continue 吗?(
:320)finishTurn上一轮返回了{action:"continue"},但既没工具结果也没插话。那就"用当前上下文再发一次请求"。explicitContinuation就是给这种情况留的记号。 - 都没有?
break(:326)。
:305-307 那三行容易被跳过:
if (hasMoreToolCalls || pendingMessages.length > 0) { explicitContinuation = false;}宿主要 continue,但内层本来就会再转一圈(有工具或插话)——这次请求已经被"自然满足"了,不需要外层再补。清掉记号,避免多跑一轮。
5.4 三条退出路径
| 退出点 | 条件 | 已 emit 的事件 |
|---|---|---|
:264 |
stopReason 为 error / aborted |
turn_end(工具结果为空)→ agent_end |
:300 |
finishTurn 返回 {action:"end"} |
turn_end → agent_end |
:326 |
无 follow-up、无 continuation | turn_end → agent_end |
三条都以 agent_end 收尾。区别在第一类不执行工具、不调 finishTurn——模型请求本身就失败了,没有"这一轮干了什么"可汇报。
5.5 turn_start 为什么有两个发出点
翻代码会发现 turn_start 在 :127 和 :216 各发一次。会不会重复?
不会。:127 属于 runAgentLoop,只管第一个 turn;:216 在 runLoop 里,被 if (lastCompletedTurn) 包着——只有跑完过一轮才会触发。
runAgentLoop :126 agent_start :127 turn_start ← 第 1 轮runLoop :195 prepareNextTurn :216 turn_start ← 第 2..N 轮为什么不在一个地方统一发?因为第一次进来时 lastCompletedTurn 还是 undefined,prepareNextTurn 没有可用的上下文。把第一轮交给入口函数发,runLoop 就不必区分"首次"和"后续",少一个状态位。
runAgentLoopContinue(:155-156)做了同样的事。于是两个入口的事件序列完全一致——下游不用关心这一轮是 prompt 起的还是 continue 起的。
5.6 runLoop 里的五个可变状态
runLoop 只有 160 行,但塞了五个跨轮存活的可变量。列清楚它们,循环就再没有"魔法"了。
| 变量 | 声明 | 谁改它 | 频率 |
|---|---|---|---|
currentContext |
:180 |
:197 :237 整体换;:223 :284 就地 push |
每轮多次 |
config |
:181 |
:199 :238 合并 model / reasoning |
每轮 |
lastCompletedTurn |
:182 |
:255 :289 |
每轮 |
explicitContinuation |
:183 |
:303 :306 :314 :321 |
每轮 |
pendingMessages |
:185 |
:213 :226 :304 :315 |
每轮多次 |
lastCompletedTurn 里装的是引用,不是快照。 构造它的时候(:289-294):
lastCompletedTurn = { message, toolResults, context: currentContext, // 引用 newMessages, // 引用};newMessages 是 runLoop 外面那个数组,后面每个 turn 都往里 push。所以宿主在 finishTurn 里拿到的 turn.newMessages 是一个还在长的数组——这一轮看到长度 5,下一轮同一个对象可能已经 9 了。
这不是 bug,是有意的:钩子想知道"到现在为止累计发生了什么",读长度就行,不用自己拼。但如果你把 turn.newMessages 存起来当快照,之后回读会看到别的内容。要快照,自己去 [...turn.newMessages]。
pendingMessages 有五个赋值点,每个对应一种时序。 按执行顺序排:
| 行号 | 时机 | 为什么必须在这里 |
|---|---|---|
:185 |
进 runLoop 之前 |
上次 run 结束到这次开始之间用户可能打了字 |
:213 |
prepareNextTurn 之后 |
压缩可能跑几十秒,期间插话得捞一次 |
:226 |
消费完队列后 | 清空,防止同一批消息被重复注入 |
:304 |
finishTurn 之后 |
本轮工具跑完,看有没有新插话 |
:315 |
内层退出之后 | follow-up 借同一个变量走同一条注入路径 |
:315 是个省钱技巧。follow-up 和 steering 语义完全不同(一个"等你说完",一个"打断你"),但注入机制一模一样:塞进 pendingMessages → continue 回外层 → 内层再转一圈。所以复用同一个变量、同一段注入代码(:220-225),只在最外层多一个判断。
explicitContinuation 被清掉的机会比设上的多。 设它一处(:303),清它三处::306 被自然满足、:314 有 follow-up 顶替、:321 兑现完。这个比例是对的——"待办记号"本就该被别的路径消化掉,只在都没兜住时才真正执行。那一次执行就是"用当前上下文再发一次请求",不注入任何消息。
六、旧版的那盏信号灯,新版拆成了三盏
如果你读过旧教程,可能记得一句话:stopReason 是循环唯一的信号灯。
这在 v0.80 时代是对的:stopReason === "toolUse" 继续,"stop" 就停。
在 v1.4.0 里,这句话不成立了。
6.1 stopReason 退居二线
StopReason 现在有 7 个取值(packages/ai/src/types.ts:489):
export type StopReason = | "pending" | "stop" | "length" | "toolUse" | "error" | "aborted" | "deferred";而在 runLoop 里,它只出现在两处::254 的 error / aborted,和 :277 的 length。
"stop" 和 "toolUse" 一次都没出现在循环判断里。 循环改看什么?
const toolCalls = message.content.filter((c) => c.type === "toolCall"); // :268看内容里有没有 toolCall 块。
为什么?因为 stopReason 是 provider 给的,各家口径不一。Pi 在 ai 层做过归一——比如 Google Vertex 这段(packages/ai/src/api/google-vertex.ts:242-244):
if ( output.content.some((b) => b.type === "toolCall") && output.stopReason === "stop") { output.stopReason = "toolUse";}但内核选择不依赖这层归一:"模型还要不要干活",用消息内容自证,比用 provider 的标签可靠。
这是版本演进里一个典型的判断:标签是外部给的,内容是自己在攒的。控制流押在后者上。
七个取值各自去哪,一次列清:
| 取值 | 谁产生 | 循环怎么看 | 真正的消费者 |
|---|---|---|---|
pending |
每个 provider 流开头的占位 | 走不到(done 才定稿) |
无 |
stop |
provider 正常结束 | 不看,改看有无 toolCall |
UI 展示 |
toolUse |
provider 识别出工具调用 | 不看,同上 | 旧逻辑遗留 |
length |
输出撞上限 | :277 整批工具判失败 |
9.5 节 |
error |
provider 报错 | :254 退出 |
外壳 |
aborted |
用户中断 | :254 退出 |
UI 关 spinner |
deferred |
延迟响应 | 不看,落普通分支 | 宿主自己轮询 |
停只是循环的一半。另一半是"谁能让它再转一圈"——6.2 到 6.4 是三盏灯,6.6 把它们放到同一条时间线上跑一次,6.7 再回收上表里三个没人读的取值。
6.2 出路一:steering —— 跑到一半插话
场景:agent 正在读第 12 个文件,你发现方向错了,想让它别读了。
Agent.steer(message)(agent.ts:308)把消息塞进 steeringQueue。队列在 createLoopConfig 里被包成 getSteeringMessages(agent.ts:506-512):
getSteeringMessages: async () => { if (skipInitialSteeringPoll) { skipInitialSteeringPoll = false; return []; } return this.steeringQueue.drain();},循环在两个位置拉它:
:185,开跑之前(用户可能在你按回车前就插了话);:304,每轮工具执行完、turn_end之后。
拉到之后,:220-225 把它们和 preparedMessages 一起注入:
for (const message of declareToolChanges(currentContext, [ ...preparedMessages, ...pendingMessages,])) { await emit({ type: "message_start", message }); await emit({ type: "message_end", message }); currentContext.messages.push(message); newMessages.push(message);}注入时又走了一次 declareToolChanges——插话可能带着新工具,工具集差异还得再声明。
这里藏着一个非常具体的细节(:210-215):
// Preparation can be long-running (for example, compaction). Pick up steering// queued while it ran. Only poll again if the earlier poll returned nothing;// otherwise one-at-a-time mode would deliver two messages in this turn.if (pendingMessages.length === 0) { pendingMessages = (await config.getSteeringMessages?.()) || [];}为什么要有这个 if?
因为 prepareNextTurn 可能很慢——真实宿主就在里面做上下文压缩(packages/coding-agent/src/core/agent-session.ts:920-921)。压缩跑几十秒,这期间用户又插了一句,得补拉一次。
但如果第一次已经拉到一条了,再拉就会在同一个 turn 里塞两条——破坏 one-at-a-time 语义。所以:只在"上一轮一无所获"时才补拉。
one-at-a-time 是默认值(agent.ts:255),由 PendingMessageQueue.peek() 控制(agent.ts:165-169):
peek(): AgentMessage[] { if (this.mode === "all") return this.messages.slice(); const first = this.messages[0]; return first ? [first] : [];}"一次只说一句"——插话是打断,连着塞三条等于让模型同时听三个人指挥。
6.3 出路二:follow-up —— 等你说完我再说
Agent.followUp(message)(agent.ts:313)塞的是另一个队列。它只在外层被拉(:311):
const followUpMessages = (await config.getFollowUpMessages?.()) || [];if (followUpMessages.length > 0) { explicitContinuation = false; pendingMessages = followUpMessages; continue;}触发条件是"内层已经停了"——没工具调用了、没插话了。也就是说,它不打断当前工作,只负责"既然你完事了,这儿还有一件"。
三条出路的区别:
| steering | follow-up | finishTurn 返回 continue |
|
|---|---|---|---|
| 队列 | steeringQueue |
followUpQueue |
无,直接返回值 |
| 拉取位置 | :185、:213、:304(内层) |
:311(外层) |
:295 判、:320 兑现(外层) |
| 触发时机 | 工具执行完,立刻 | 整个内层停下后 | 内层停了,也没有 follow-up |
| 效果 | 打断当前方向 | 排队承接 | 不注入任何消息,空转一轮 |
| 比喻 | "别读了,回头" | "干完了顺便把这个也做了" | "你到底还是再想一遍" |
6.4 出路三:finishTurn —— 宿主说了算
:295:
const decision = await config.finishTurn?.(lastCompletedTurn, signal);返回值三种(types.ts:147):
export type AgentTurnDecision = { action: "continue" } | { action: "end" };{action:"end"}→ 立刻停(:298);{action:"continue"}→ 请求"再来一轮";undefined→ 正常调度。
continue 的兑现方式有点绕,在 :320-323:
if (explicitContinuation) { explicitContinuation = false; continue;}此时内层已经退出、也没有 follow-up,但宿主说要继续。怎么办?用当前上下文再发一次请求——注释(:319)管这叫 "one context-only turn"。
上下文里没有新东西,模型看到的还是上一轮的样子。为什么允许这种"空转"?因为宿主需要它:扩展想在 turn_end 时让 agent 再想想,agent-session.ts:895-899 就是这么用的——扩展返回 continue,agent 就多跑一轮。
6.5 真实宿主怎么用这三个钩子
coding-agent 把四个钩子全挂上了,而且都是"包裹"式安装——先存旧值,再套一层(agent-session.ts:902-912):
private _installAgentBoundaryHooks(): void { const previousFinishTurn = this.agent.finishTurn; this.agent.finishTurn = async (turn, signal) => { this._boundaryDispatchedMessages.add(turn.message); const extensionContinue = await this._dispatchTurnEndBoundary( turn.message, turn.toolResults, ); const previousDecision = await previousFinishTurn?.(turn, signal); if (previousDecision?.action === "end") return previousDecision; if (extensionContinue || previousDecision?.action === "continue") { return { action: "continue" }; } return undefined; };}这段是"钩子该怎么写"的范本:
- 先干自己的事(分发扩展的
turn_end边界事件); - 再调上游(
previousFinishTurn); - 合并决策,而且
end优先——上游说停就停,不让扩展覆盖。
prepareRequest 的用法更重(agent-session.ts:803-860),每次请求前重建整个上下文投影:
const projection = this.sessionManager.buildSessionProjection();const canonicalContext = { ...request.context, messages: projection.messages, // Messages declare the provider-visible loadout; // context.tools keeps executable implementations. tools: this.agent.state.tools.slice(),};那行注释是"变更即追加"的前提,7.3 会正式拆开讲。(本节讲的是三盏灯;prepareRequest、getApiKey 属于另一组"请求前钩子",见 7.2。)
6.6 一次 run 把三条出路都走一遍
上面三节是分开讲的:三个开关,三张脸。合到一条时间线上,才看得清它们怎么互相让路。
场景:pi.prompt("找出所有 TODO")。中途用户插一句"别读 tests",过一会儿又说"顺便统计行数",扩展在某一轮结束时要求再想一遍。
| 轮 | 模型这轮给了什么 | 内层这两个数 | 谁让它继续 |
|---|---|---|---|
| 1 | 文本 + 2 个 read |
hasMoreToolCalls=true;:304 拉到 1 条 steering |
内层 :192 |
| 2 | 插话已注入(:220-225),纯文本无工具 |
false;:304 空 |
内层退出 → :311 拉到 follow-up → continue(:316) |
| 3 | 注入了 follow-up,1 个 bash |
true;:304 空 |
内层 :192 |
| 4 | 纯文本无工具 | false;:304 空 |
内层退出 → :295 给 {continue}(:303 立记号)→ :311 空 → :320 兑现 |
| 5 | 纯文本,上下文一个字没变 | false;:304 空 |
:326 break → :329 agent_end |
第 1 轮那条插话是搭顺风车的:它没让内层多转一圈,只是赶上了工具调用本来就要求的下一轮,到 :220-225 才真正注入。所以 steering 的效果取决于它在哪个 turn 边界被拉到,不取决于你什么时候按的回车——实验 2 会撞上这件事。
第 5 轮是整次 run 里唯一"什么新东西都没有还发请求"的一轮,注释(:319)管它叫 one context-only turn——6.4 已经见过它。它能发生只靠两行::321 清掉记号后 continue,以及 :189 把 hasMoreToolCalls 重置成 true——否则 :192 的条件为假,循环直接掉到 :326。内层循环唯一的"重置点"在 :189,而它躺在 while (true) 里面。
三盏灯不是并列选项,是三个先后判断:自然推进 / steering(:305 清记号)> follow-up(:314 清记号)> 宿主续命(:320 兑现)。前一个成立,后面的根本没机会执行——表里第 1、2、4 轮各演了一条。
这张表只到 agent 包为止。想看同一次请求继续穿过 ai、coding-agent、tui 的 25 个落点,附录 D 是这张表的放大版。至于第 2 轮到底收到了一串什么,7.5 有逐条总账。
6.7 三个还在产、已经没人读的取值
6.1 那张表里,三行值得单独说。
pending 是纯内部值:provider 开流时先造一条 content: [] 的 partial,done 一到就换成终态(anthropic-messages.ts:601 等 11 处),循环碰不到它。
toolUse 更有意思:类型里留着,4 个 provider 也还在发(anthropic-messages.ts:1670、openai-completions.ts:1569 等 4 处),循环已经不看它了。这是兼容性残留——UI 和 durable 的日志格式还在读这个字段,删掉会破契约。读源码时看到这种"还在产出、核心却不用"的东西,往往就是历史的断面。
deferred 最能说明分层:ai/src/types.ts:382 有这个请求选项,provider 先接单、稍后给结果,消息的 stopReason 记为 deferred 并附一个句柄。循环完全不认识它,只看到"这条消息没有 toolCall",于是内层退出、外层问 follow-up(6.3)、没有就 agent_end——"稍后取"整个交给宿主在 finishTurn(6.4)里处理,内核一行代码都没加。不认识就按"这一轮结束了"处理,扩展点留在外面;为它加个特殊分支才是病根:往后每来一个新特性都得改核心,旧版就是这么把 stopReason 当信号灯的。ai 那边为什么只用一个枚举值就换来这个能力,M04 §3.1 讲另一半。
七、一次请求之前
7.1 三级流水线
streamAssistantResponse(:390-479)是唯一调用 LLM 的地方。开头三行就是三级转换:
let messages = context.messages;if (config.transformContext) { messages = await config.transformContext(messages, signal); // :400}const llmMessages = await config.convertToLlm(messages); // :404const llmContext = normalizeContext({ messages: llmMessages }); // :406| 阶段 | 做什么 | 谁实现 |
|---|---|---|
transformContext |
剪枝、注入外部上下文(仍在 AgentMessage 层) | 宿主,可选 |
convertToLlm |
转成 provider 认识的 4 种 role,过滤自定义消息 | 宿主,必填 |
normalizeContext |
折叠 systemPrompt / tools;也是 TranscriptContext 的唯一出口 |
ai 包 |
顺序不能换。transformContext 在语义层动手("这条通知消息没用,剪掉"),convertToLlm 在协议层动手("custom → user")。先语义后协议。
文件头那句注释(:1-3)说的就是这件事:
Agent loop that works with AgentMessage throughout. Transforms to Message[] only at the LLM call boundary.
循环内部全程用 AgentMessage(可以带任意自定义 role),只在调用 provider 那一瞬间转成 Message[]。上层想在消息流里塞"通知""状态"这类非 LLM 消息,才不用动内核。
Agent 的默认实现最省事(agent.ts:39-47):
function defaultConvertToLlm(messages: AgentMessage[]): Message[] { return messages.filter( (message) => message.role === "system" || message.role === "user" || message.role === "assistant" || message.role === "toolResult", );}只留四种,其余全丢。
7.2 三个"请求前"钩子,别搞混
| 钩子 | 位置 | 能否注入消息 | 典型用途 |
|---|---|---|---|
prepareNextTurn |
:195,上一轮完成后 |
能(messages) |
压缩上下文、更新系统提示词 |
prepareRequest |
:228,每次请求前 |
不能 | 重建上下文投影、虚拟模型路由 |
getApiKey |
:410,紧贴请求 |
— | 续期 OAuth token |
为什么 prepareRequest 不能注入消息?看类型定义(types.ts:180):
export type AgentRequestUpdate = Omit<AgentLoopTurnUpdate, "messages">;用 Omit 硬性剥掉了 messages。因为它的执行时机在 :220-225 的注入之后——这时再塞消息,就绕过了 message_start / message_end 事件,UI 和 transcript 会对不上。
而 prepareNextTurn 卡在 turn_end 之后、turn_start 之前(:194-217),正好在两轮之间,注入的消息能走完整的事件流程。
真实用法印证了这条分工(agent-session.ts:920-947),它在 prepareNextTurn 里一次干三件事——压缩、刷新系统提示词、把提示词差异作为消息返回:
const updateMessage = this._preparePromptAndToolLoadout( options, nextContext.messages,);return { ...previousSnapshot, context: { ...nextContext, tools: this.agent.state.tools.slice() }, messages: updateMessage ? [...(previousSnapshot?.messages ?? []), updateMessage] : previousSnapshot?.messages, model: this.agent.state.model, thinkingLevel: this.agent.state.thinkingLevel,};7.3 贯穿全章的一条哲学:变更即追加
上面那个 updateMessage 是什么?看 agent-session.ts:1786-1790:
const sections = diffSystemPromptSections( getCurrentSystemMessage(messages)?.sections ?? {}, buildSystemPromptSections(options),);return sections ? { role: "system", content: "", sections, timestamp: Date.now() } : undefined;系统提示词变了,不是去改 context.systemPrompt,而是追加一条只含差异的 system 消息。
同样套路出现在三处:
| 变更 | 表达方式 | 文件 | 行号 |
|---|---|---|---|
| 系统提示词变了 | 追加 system 消息(只带 sections 差异) |
agent-session.ts |
:1786-1790 |
| 工具集变了 | 追加 system 消息(只带增删差异) | agent-loop.ts |
:342-372 |
| 模型 / 思考等级变了 | 改 config,下一轮生效 |
agent-loop.ts |
:199-208 |
前两个同源:transcript 是唯一事实源,任何状态变更都必须能在 transcript 里回放出来。
为什么这么较真?因为 durable 包要把会话持久化、能恢复、能分叉。如果系统提示词藏在某个变量里,恢复时只能"再算一遍",而重算结果未必和当初一致(工具集可能变了)。写进 transcript,才能做到"读出来就是当时的样子"。
declareToolChanges 的注释(:332-341)把这层意思说透了:
context.toolsis what the runtime can execute; the transcript's system messages declare what the model may call.
7.4 两个钩子的返回值,形状故意不一样
prepareNextTurn 和 prepareRequest 长得很像,返回类型却不是同一个(types.ts:161-189):
export interface AgentLoopTurnUpdate { context?: AgentContext; messages?: AgentMessage[]; model?: Model<any>; thinkingLevel?: ThinkingLevel;}export type AgentRequestUpdate = Omit<AgentLoopTurnUpdate, "messages">;Omit<..., "messages"> 这一行,就是"能不能注入消息"的全部实现。没有运行时检查,没有文档警告,类型层面直接让你写不出来。
为什么 prepareRequest 不能注入?types.ts:183-184 的注释说得很直白:
Called immediately before every conversational provider request, including the first. Pending messages have already been appended and emitted when this callback runs.
pending 消息已经 emit 过 message_start / message_end 了。这时再塞,UI 看到的和 transcript 里存的就对不上。
再看 context 字段的语义:整体替换,不是合并。:197 和 :237 都是:
currentContext = nextTurnSnapshot.context ?? currentContext;宿主要改一个字段,得先把整个 AgentContext 造出来。这和 mergeClientIdentity 的字段级合并正好相反——那边是"给差量",这边是"给全量"。
区别在规模。ClientIdentity 就三个字段,合并便宜;AgentContext 里塞着几千条消息,字段级合并得深拷贝,代价比整体替换高得多。而且整体替换有个隐含好处:宿主必须显式交出完整的下一轮上下文,不可能"漏改一处"。
最后是 thinkingLevel 那三行(:202-207):
reasoning: nextTurnSnapshot.thinkingLevel === undefined ? config.reasoning : nextTurnSnapshot.thinkingLevel === "off" ? undefined : nextTurnSnapshot.thinkingLevel,三层嵌套,看着啰嗦,其实在做三态映射:
| 钩子返回 | config.reasoning |
含义 |
|---|---|---|
undefined(没给) |
保持原值 | "我不关心" |
"off" |
undefined |
"关掉思考" |
"low" / "medium" / "high" |
原样 | "用这个等级" |
第三行只举了三档。
ThinkingLevel实际有七个取值(packages/agent/src/types.ts:349):off加minimal/low/medium/high/xhigh/max。除off以外的任何档位都走第三行,原样透传——这张表说的是三种语义,不是档位清单。
为什么"关掉"要映成 undefined 而不是保留 "off"?因为 reasoning 最终是传给 pi-ai 的可选配置,undefined 意味着"不传这个字段,用 provider 默认"。"off" 是 agent 层自己的概念,往下传没意义。
同一个值在两层的名字不一样,中间必须翻译一次。 这段三元表达式就是那个翻译层。而它上面一行 thinkingLevel: config.reasoning ?? "off"(:232)是反方向翻译:进请求时把 undefined 还原成 "off" 给钩子看。一个概念、两种表示、三个翻译点,这是分层系统必然的摩擦成本。
7.5 第二轮的输入,到底是哪些东西
前面讲的都是"怎么转",现在把"转的是什么"列成总账。一句话:第 2 轮发出去的,就是第 1 轮的全部输出,加上第 1 轮开始前就已经在的东西。
AgentContext 只有两个字段(types.ts:514-519):
export interface AgentContext { messages: AgentMessage[]; // 给模型看的 transcript tools?: AgentTool<any>[]; // 本地能执行的实现}注意它没有 systemPrompt。v1.4 里提示词不是请求上一个独立字段,它就是 transcript 开头那条 system 消息——所以"每轮都重发提示词"不需要代码支持,它跟着 messages 一起走。
往 messages 里追加的动作一共五处:
| 追加者 | 追加什么 | 行号 |
|---|---|---|
runAgentLoop 开场 |
prompt 那条 user,连同旧历史一起组成 currentContext |
:123 |
declareToolChanges |
工具集变化的 system 消息(toolsAdded / toolsRemoved) |
造 :119、:220 → 存 :123、:223 |
| 内层每轮开头 | 插话、追问、prepareNextTurn 交来的消息 |
:223 |
streamAssistantResponse |
本轮 assistant 消息,text / thinking / toolCall 块全在里面 |
:428 占位、:457 换终态 |
| 工具跑完 | N 条 toolResult,按源序 |
:284 |
只有 push,没有 delete。 内核从不把旧消息从 messages 里摘掉。想让它变小只有一条路:transformContext 在语义层剪(M09 的压缩就挂在这);或者 prepareNextTurn / prepareRequest 整体换个 context(:197、:237)——那不是剪枝,是宿主交一份新的。
但"进 transcript"不等于"进请求",中间有三个岔口:
**一、自定义 role 会被过滤。**就是 7.1 那段 defaultConvertToLlm:通知、状态这类消息本地全程都在,模型永远看不到。
二、tools 字段根本不进请求。 它只用来本地分派::527 靠它查 executionMode,:724 靠它取实现。模型看到的工具声明由 transcript 的 system 消息带,文件头注释写得直白(:335-336):
context.toolsis what the runtime can execute; the transcript's system messages declare what the model may call.
每轮请求前 declareToolChanges 把"transcript 已声明的工具集"和"本地可执行集"做差,差值写成 toolsAdded / toolsRemoved(:356-359)。两份数据、靠一个 diff 保持同步,这正是 7.3 "变更即追加"的落点。
三、thinking 重不重发,provider 说了算。 Anthropic 这条路上,上一轮的 thinking 块会连同 signature 一起带回去(anthropic-messages.ts:1467-1471),因为多轮连续性要校验签名;签名丢了(比如流被中断过)就降级成普通 text(:1461-1464);空 thinking 又没签名,直接跳过不发(:1449)。
最后一处容易看漏:streamAssistantResponse 调 normalizeContext 时只传了 messages(:406),看起来像空转。它确实是空转——折叠 systemPrompt 和 tools 那部分(ai/src/utils/transcript.ts:30-34)在这条链上没活干,因为 Agent 层早把两样都写成 system 消息了。那为什么还要调?因为 TranscriptContext 是个带 brand 的类型,只有 normalizeContext() 能造出来:
Only
normalizeContext()produces this type, so a rawContextcannot reach provider code by accident.
(ai/src/types.ts:796-805)它是一道类型闸门:不经这一步,原始 Context 到不了 provider 代码。用编译期强制换"没人会忘记折叠",跟 7.4 那个 Omit<..., "messages"> 是同一种手法。
transcript 只增不减,请求每次重拼。 这就是 6.6 那张表里第 5 轮能叫 one context-only turn 的原因:它一个新东西都没加,发出去的仍是这一整串。
八、流式响应如何落进 transcript
这是 streamAssistantResponse 最精妙的一段。核心矛盾:流式输出是增量的,但 transcript 是消息列表。
Pi 的做法是"先占位,再原地替换"(:424-468):
let partialMessage: AssistantMessage | null = null;let addedPartial = false;for await (const event of response) { switch (event.type) { case "start": partialMessage = event.partial; context.messages.push(partialMessage); // :428 先占位 addedPartial = true; await emit({ type: "message_start", message: { ...partialMessage } }); break; // text_delta / thinking_* / toolcall_* 走同一条分支 default: if (partialMessage) { partialMessage = event.partial; context.messages[context.messages.length - 1] = partialMessage; // :444 原地替换 await emit({ type: "message_update", assistantMessageEvent: event, message: { ...partialMessage }, }); } break; case "done": case "error": { const finalMessage = await result(); if (addedPartial) { context.messages[context.messages.length - 1] = finalMessage; // :457 换成终态 } else { context.messages.push(finalMessage); } await emit({ type: "message_end", message: finalMessage }); return finalMessage; } }}三个动作:
start:push 一个 partial 进数组,UI 立刻看到"assistant 开始说话了";- 增量:把数组末位整个替换成新快照(不是拼接,是换对象);
done/error:替换成终态。
为什么替换而不是原地改字段?因为 event.partial 本身就是 provider 流里累积出的完整快照(AssistantMessage 带 content 数组)。每次拿到新快照直接换引用最简单,也不会出现"数组改了一半"的中间态。
两个防御性分支值得注意:
addedPartial(:422):有的 provider 不发start,直接给done。这时数组里没有占位,得push而不是替换(:458-460),还得补发一次message_start(:462)。- 循环体外还有一份收尾(
:470-478):流正常结束却没发done/error的情况。同一段逻辑写两遍,是"不信 provider"的又一个例子。
还有一行很隐蔽(:419):
const result = async () => Object.assign(await response.result(), { thinkingLevel: config.reasoning ?? "off", });终态消息上额外盖了一个 thinkingLevel 字段。"这条消息是在什么思考等级下产生的"只有循环知道——provider 的响应里没有。在边界上打标,别指望下游能推出来。
8.1 provider 吐 12 种事件,这里只写了 4 个分支
switch 里看着只有 start / 一堆 case 并列 / done / error,但 default 那支挡住了 9 种事件。为什么能合并?
provider 的流事件大致长这样:
starttext_start text_delta text_endthinking_start thinking_delta thinking_endtoolcall_start toolcall_delta toolcall_enddoneerror12 种。其中 9 种是"某个块正在长",处理方式完全一样:把 partialMessage 换成新快照,发一个 message_update。
关键在 event.partial 是累积快照,不是增量。如果它只带这一小段文本,这里就得自己维护"第几个 content block、拼到第几个字符、thinking 和 text 怎么交错"。provider 直接给全量快照,循环里就只剩一句赋值。
代价是每次 emit 都要 { ...partialMessage } 浅拷一份。为什么不直接传 partialMessage?因为下游可能把它存起来(TUI 要缓存上一次渲染结果做 diff),传引用的话,下一次事件一到,缓存里那份"快照"就悄悄地变了。浅拷贝是给订阅者的隔离带。
再看 for await 结束后那段(:470-478):流正常结束却没发 done/error,代码还会再走一遍定稿。同一段逻辑写两遍,是"不信 provider"的又一个例子——这里的 provider 可能是浏览器里的 fetch polyfill,也可能是某个实现漏了收尾事件。
还有一个极易忽略的细节:case "done" 里面是 return finalMessage 而不是 break。因为这个 switch 在 for await 里面,break 只会跳出 switch,然后继续等下一个事件。如果 provider 之后不再发、直接关流,for await 正常结束,于是落到循环体后面那段收尾——message_end 会被 emit 两次。return 是为了就地截断。
九、工具执行
9.1 分派:一个坏苹果拖垮整批
executeToolCalls(:518-533):
const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");const hasSequentialToolCall = toolCalls.some( (tc) => currentContext.tools?.find( (t) => t.name === tc.name, )?.executionMode === "sequential",);if (config.toolExecution === "sequential" || hasSequentialToolCall) { return executeToolCallsSequential( currentContext, assistantMessage, toolCalls, config, signal, emit, );}return executeToolCallsParallel( currentContext, assistantMessage, toolCalls, config, signal, emit,);全局设置 sequential,或者这批里只要有任何一个工具声明了 executionMode: "sequential",整批就走串行。
为什么?因为并行意味着"同时在跑"。如果 edit 必须独占,而 read 与它并行,read 可能读到改了一半的文件。既然没法保证"部分并行"的语义安全,就整批降级。
toolExecution 默认值是 "parallel"(agent.ts:261)——安全靠单个工具自己声明兜底。
9.2 并行执行,顺序记账
这是本章第二个值得抄走的设计。executeToolCallsParallel(:596-670)分两段。
第一段:串行预检,把执行体包成 thunk。
for (const toolCall of toolCalls) { await emit({ type: "tool_execution_start", toolCallId: toolCall.id, toolName: toolCall.name, args: toolCall.arguments, }); const preparation = await prepareToolCall( // :614 串行预检 currentContext, assistantMessage, toolCall, config, signal, ); if (preparation.kind === "immediate") { // 校验失败 / 被 block:立刻有结果,不必并发 continue; } finalizedCalls.push(async () => { // :629 只是收集,不执行 const executed = await executePreparedToolCall( preparation, signal, emitToolExecutionUpdate(toolCall, emit), ); const finalized = await finalizeExecutedToolCall( currentContext, assistantMessage, preparation, executed, config, signal, ); await emitToolExecutionEnd(finalized, emit); return finalized; });}第二段:一次性并发。
const orderedFinalizedCalls = await Promise.all( finalizedCalls.map((entry) => typeof entry === "function" ? entry() : Promise.resolve(entry), ),); // :656-658const messages: ToolResultMessage[] = [];for (const finalized of orderedFinalizedCalls) { // :660 const toolResultMessage = createToolResultMessage(finalized); await emitToolResultMessage(toolResultMessage, emit); messages.push(toolResultMessage);}两个关键点:
- 预检串行。参数校验、权限钩子可能读文件、问用户,不能并发跑——否则弹窗会一起涌出来。
- 执行并发,记账按原序。
Promise.all保证结果数组顺序与输入一致,所以 transcript 里 toolResult 的顺序 = 模型发起调用的顺序,而不是完成顺序。
这解决了一个真实问题:并行工具的完成顺序是随机的。如果按完成顺序写进 transcript,同一段对话每次重放都不一样,缓存全失效,调试也没法复现。
但事件是另一回事:tool_execution_end 在 thunk 内部发(:648),所以它按完成顺序到达 UI。UI 要的就是"这个工具好了"的即时反馈。
这正是 types.ts:311-313 那句注释的意思:
emit
tool_execution_endin tool completion order after each tool is finalized, then emit tool-result message artifacts later in assistant source order
执行按实际速度,记账按逻辑顺序。 两套顺序,各服务各的消费者。
9.3 terminate:全体一致才能停
shouldTerminateToolBatch(:700-702):
function shouldTerminateToolBatch( finalizedCalls: FinalizedToolCallOutcome[],): boolean { return ( finalizedCalls.length > 0 && finalizedCalls.every((finalized) => finalized.result.terminate === true) );}全仓扫一遍会发现一个意外:八个内置工具没有一个设置 terminate。唯二的生产用法是两个示例扩展(structured-output、reload-runtime)加一个 eval——它是留给扩展作者的出口,不是内建行为。详见 §十三 坑 6。
用 every,不是 some。三个工具里两个说"停",第三个没表态,就不停。
原因很实在:模型一批发 5 个调用,是把它当成一个整体计划的。只执行 2 个就停,剩 3 个的 toolResult 缺失,对话历史会变成"有 call 没 result"——大多数 provider 直接报错。
要么整批执行完,要么整批都要求停。
9.4 一次工具调用的四道关
prepareToolCall(:718-787):
const tool = tools.find((t) => t.name === toolCall.name);if (!tool) { return { kind: "immediate", result: createErrorToolResult(`Tool ${toolCall.name} not found`), isError: true, };}try { const preparedToolCall = prepareToolCallArguments(tool, toolCall); // ① 垫片 const validatedArgs = validateToolArguments(tool, preparedToolCall); // ② 校验 if (config.beforeToolCall) { const beforeResult = await config.beforeToolCall({ ... }, signal); // ③ 权限 if (beforeResult?.block) { /* ④ 可拦截,也可要求终止 */ } } return { kind: "prepared", toolCall, tool, args: validatedArgs };} catch (error) { return { kind: "immediate", result: createErrorToolResult(...), isError: true, };}四道关,每一道失败都转成 immediate 结果——不抛异常,直接变成一条错误 toolResult 交给模型。
prepareArguments(:704-716)是"兼容垫片":模型可能按旧 schema 传参(比如少了一层 wrapper),工具可以用它做一次修正,再进校验。
然后执行(executePreparedToolCall,:831-867),再定稿(finalizeExecutedToolCall,:869-920)。定稿阶段 afterToolCall 可以改写结果:
const structuredContent = afterResult.structuredContent ?? (afterResult.content ? undefined : result.structuredContent);这行的逻辑:钩子如果改了 content 却没给 structuredContent,就把结构化内容删掉。因为两者可能已经对不上了——留着旧的比没有更危险。
9.5 截断保护
:276-279:
const executedToolBatch = message.stopReason === "length" ? await failToolCallsFromTruncatedMessage(toolCalls, emit) : await executeToolCalls(currentContext, message, config, signal, emit);当 stopReason === "length"(输出被上限截断),所有工具调用一律不执行,全转成错误。
理由在 :481-487 的注释里:
Streamed tool-call arguments are finalized with a best-effort JSON salvage parser, so a truncated message can yield tool calls whose arguments parse and validate but are silently incomplete.
关键在 "parse and validate"——salvage parser(尽力修复 JSON)可能把截断的 {"path": "src/foo.ts", "content": "..."} 补成一个合法 JSON。schema 校验也会过,因为必填字段都在。但内容是半截的。
这种调用最危险:它看起来完全合法。写文件写出半截内容,比直接报错糟得多。
failToolCallsFromTruncatedMessage 返回 terminate: false(:512),所以模型会收到 N 条"你的调用被截断了,请重发",循环继续——给它自己修复的机会。
9.6 并行版的类型把戏:一个数组装两种东西
executeToolCallsParallel 里有个不太常见的类型(:698):
type FinalizedToolCallEntry = | FinalizedToolCallOutcome | (() => Promise<FinalizedToolCallOutcome>);数组里既能放"已经定稿的结果",也能放"一个还没跑的 thunk"。为什么要混?
因为预检(prepareToolCall)是串行的,而且可能立刻失败:工具不存在、参数校验不过、beforeToolCall 拦下——这些不需要执行,结果当场就有。如果也包成 thunk,Promise.all 里就要多绕一层没必要的异步。
于是 :615-627 遇到 immediate 直接定稿、立刻 emit tool_execution_end、塞进数组;只有真正要执行的才包成闭包(:629)。
最后 Promise.all 那一句(:656-658):
const orderedFinalizedCalls = await Promise.all( finalizedCalls.map((entry) => typeof entry === "function" ? entry() : Promise.resolve(entry), ),);typeof entry === "function" 是唯一的判别式。用函数做"惰性值"的标记,省掉了一层包装类型;代价是只要有人往数组里塞一个函数值,就会被误当成 thunk。这里安全,因为数组只有两个生产者,且工具结果里不会有裸函数。
真正值钱的是 Promise.all 的保序性:它按输入顺序返回,不按完成顺序。所以 orderedFinalizedCalls 天生就是源序,后面 for 循环 emit message_start / message_end 时不用排序。
这和事件流形成了一个有趣的错位:tool_execution_end 在 thunk 里发(:648),按完成顺序到达 UI;toolResult 消息在 Promise.all 之后发(:660-664),按源顺序进 transcript。同一个批次,两条时间线。
9.7 执行期的三个守卫
executePreparedToolCall(:831-867)只有 36 行,塞了三个不起眼但都很关键的守卫。
一,updateEvents 先收集,再统一等。
const updateEvents: Promise<void>[] = [];// ...(partialResult) => { if (!acceptingUpdates) return; updateEvents.push(Promise.resolve(onUpdate(partialResult)));},工具可以边跑边吐增量(读大文件时先给前 100 行)。这些 emit 是异步的,如果在回调里直接 await,会把工具自己的执行卡住。所以先 push 进数组,执行完再 Promise.all 一次性等。
二,acceptingUpdates 在 finally 里也要关。
} catch (error) { // ... acceptingUpdates = false; await Promise.all(updateEvents); // ...} finally { acceptingUpdates = false;}finally 里那句看着冗余——成功和失败分支都关了。但它防的是第三种情况:工具在返回之后还异步调了一次 onUpdate。那时结果已经定稿,再 emit 就会拿旧数据覆盖终态。finally 保证"出了这个函数,这扇门一定关着"。
三,durationMs 用 performance.now(),不是 Date.now()。
const startedAt = performance.now();const elapsed = () => Math.round(performance.now() - startedAt);Date.now() 受系统时钟调校影响(NTP 同步、用户改时间),测出来可能是负的。performance.now() 是单调时钟。
这个数字最后会进 tool_execution_end 事件(:936)和 toolResult 消息(:951)。它不参与模型决策,但 TUI 要靠它显示"这个工具跑了 1.2s"。
十、失败也是消息
如果只能记住一条设计原则,就记这条:内核不 reject,失败也是一条消息。
三个层次。
层一:工具失败。 工具不存在、参数不合法、钩子抛异常、工具自己 throw,全部转成 createErrorToolResult(:922-927):
function createErrorToolResult(message: string): AgentToolResult<any> { return { content: [{ type: "text", text: message }], details: {} };}模型看到的是"你的调用错了,原因是 X",它可以换个参数重试。这条路径不中断循环。
runToolCall 的文档注释(:818-819)把契约写死了:
Never rejects for tool failures: unknown tools, validation errors, blocked calls, and thrown errors come back as
isError: true.
层二:模型失败。 stopReason 为 error 或 aborted 时,:254-265 收尾退出,但仍然 emit 完整的 turn_end + agent_end。
为什么 abort 也走这条路?因为 UI 需要一个"结束了"的信号把 spinner 关掉。abort 不是异常,是一种正常结局。
层三:外壳异常。 Agent.runWithLifecycle 的 catch(agent.ts:535-537)调 handleRunFailure(:542-558),合成一条假的 assistant 消息:
const failureMessage = { role: "assistant", content: [{ type: "text", text: "" }], api: this._state.model.api, provider: this._state.model.provider, model: this._state.model.id, usage: EMPTY_USAGE, stopReason: aborted ? "aborted" : "error", errorMessage: error instanceof Error ? error.message : String(error), timestamp: Date.now(),} satisfies AgentMessage;末尾那个 satisfies 是本章第一次用到:意思是"按 AgentMessage 的形状检查这个
字面量,但别把我的类型放宽成 AgentMessage"。
区别看后果:写成 : AgentMessage,变量就成了整个联合类型,后面只能访问
所有分支共有的字段;写 satisfies,类型还是那个窄字面量,字段随便取,
只多一道"形状对不对"的检查。附录 B §2.6 有三行对照。
然后照常发 message_start / message_end / turn_end / agent_end。
这样外部消费者只有一条路径要处理:订阅事件,等 agent_end。不需要 try/catch,不需要区分"正常结束"和"崩了"。
代价是:真实异常被降级成了数据,调试时得看 errorMessage 字段。这是个权衡——把复杂度从"N 个调用方"收敛到"内核的一处"。
三层的可恢复性完全不同,这是设计时就得想清楚的:
| 层 | 谁看到 | 能否自愈 | 循环继续吗 |
|---|---|---|---|
| 工具失败 | 模型(toolResult) | 能,换参数重试 | 继续 |
| 模型失败 | UI / 宿主 | 不能,run 结束 | 结束 |
| 外壳异常 | 所有人 | 不能,run 结束 | 结束 |
只有第一层是"把错误交还给模型",后两层都是"把错误交还给调用方"。
界线画在哪里?不在"错在哪一层",而在谁能修。参数写错了模型能改;provider 挂了它改不了。
这条界线也解释了为什么 stopReason === "length" 被归到第一层而不是第二层(9.5 节):截断虽然发生在 provider 那边,但修复动作(重发一个参数更完整的调用)在模型这一侧。
判断错误归属前,先问"谁能修"。这个问题比"谁弄错的"有用得多——前者决定代码怎么写,后者只能决定日志怎么写。
十一、Agent:有状态的那层
agent-loop.ts 是无状态的:给它 context,它跑,返回新消息。agent.ts 的 Agent 类负责"记住跑过什么"。
11.1 systemPrompt 是算出来的
createMutableAgentState(agent.ts:83-112):
let messages = initialState?.messages?.slice() ?? [];const initialMessage = createInitialSystemMessage( initialState?.systemPrompt, tools.map(toToolDeclaration),);if (messages[0]?.role !== "system" && initialMessage) { messages.unshift(initialMessage);}return { get systemPrompt() { return getCurrentSystemPrompt(messages); }, // ...};systemPrompt 不是一个字段,是一个 getter。每次读,都从 messages 里把 system 消息"重放"出来。
AgentState 的注释(types.ts:384-388)也写明它是只读的:
Read-only: to change the prompt, append a system message with
contentorsections.
回到 §7.3 那条哲学:单一事实源。想改提示词?追加消息,别改字段。字段和列表一旦并存,就一定会不一致。
这也解释了 reset()(agent.ts:364-377)为什么是"只留下 baseline system 消息":
const baseline = getCurrentSystemMessage(this._state.messages);this._state.messages = baseline ? [baseline] : [];清空对话,但保留"你是谁"。
11.2 单飞
runWithLifecycle(agent.ts:517-540)开头:
if (this.activeRun) { throw new Error("Agent is already processing.");}一个 Agent 实例同时只能跑一个 run。想插话?steer();想排队?followUp()(agent.ts:383-387 的错误信息直接把这两条路指出来了)。
这个约束换来了什么?this.state 无锁可读,abort() 只需一个 AbortController,waitForIdle() 只需 await 一个 promise。
如果改成允许并发 run,state 就得加锁,事件顺序也得定义"交错规则"。不值得。
11.3 reducer
processEvents(agent.ts:575-622)把事件流折叠成状态:
| 事件 | 状态变化 |
|---|---|
message_start |
streamingMessage = message |
message_update |
streamingMessage = message |
message_end |
streamingMessage = undefined,messages.push(message) |
tool_execution_start |
pendingToolCalls.add(id) |
tool_execution_end |
pendingToolCalls.delete(id) |
turn_end |
若 assistant 带 errorMessage → 记到 state.errorMessage |
agent_end |
streamingMessage = undefined |
注意这里 messages.push 的是事件里的消息,不是循环内部的数组。Agent 自己维护一份 transcript,靠事件同步。
所以 Agent.state.messages 和 runLoop 里的 currentContext.messages 是两份数据。内容一致(因为事件就是那边 push 时发的),但对象不同。
11.4 agent_end 不等于 idle
这是最容易踩的理解偏差。types.ts:524-527 的注释:
agent_endis the last event emitted for a run, but awaitedAgent.subscribe()listeners for that event are still part of run settlement. The agent becomes idle only after those listeners finish.
也就是说:
emit agent_end ─────► 监听器 await 完 ─────► finishRun() ─────► idle ↑ ↑ 事件层跑完了 waitForIdle() 才 resolve为什么这么设计?因为监听器可能要写磁盘、发网络请求、更新数据库。如果 agent_end 一发就算空闲,用户马上发下一条,两个 run 就会竞争同一份持久化资源。
processEvents 会把每个 listener 依次 await(agent.ts:619-621):
for (const listener of this.listeners) { await listener(event, signal);}串行 await,按订阅顺序。慢监听器会拖慢 run 的收尾——这是"顺序可预测"换来的代价。
十二、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出;需要真 key 的两条已标出。
六个实验,从易到难。
先备好一件事:没有 API key 也能跑完这六个实验。 实验 1、2、5 都要真的发请求,不想花额度(或者手上没 key),就把 streamFn 换成固定假回复——二十行以内:
const streamFn = () => { const s = createAssistantMessageEventStream(); queueMicrotask(() => s.push({ type: "done", reason: "stop", message })); return s;};message 是那条 stopReason: "stop" 的 AssistantMessage,形状照 agent-loop.test.ts:48-62 抄;跑法用 M01 §8.2 那条 --import 命令。后面每个实验都能用它跑——需要什么 stopReason,就在 message 上写什么。
实验 1:数清事件。
const agent = new Agent({ streamFn: models.streamSimple, initialState: { model },});agent.subscribe((event) => console.log(event.type));await agent.prompt("用 ls 看一下当前目录");你应该看到:agent_start → turn_start → message_start/message_end(user)→ message_start → N×message_update → message_end → tool_execution_start → tool_execution_end → message_start/message_end(toolResult)→ turn_end → turn_start → … → agent_end。
对照 §3 的序列图,看能不能对上每一个。对不上的地方,就是你没理解的地方。
实验 2:插话。
让 agent 读一个大目录,中途插话:
const run = agent.prompt("读遍 src 下所有文件,总结架构");setTimeout(() => { agent.steer({ role: "user", content: "别读了,直接说结论", timestamp: Date.now(), });}, 1500);await run;看插话出现在第几个 turn 之后。如果它出现在"所有文件读完"之后,说明插晚了——steering 只在 :304(每轮工具执行完)生效,读文件是一个 turn 里的多个 call,插不进去。
实验 3:验证并行。
让模型一次发起两个 read,打开事件日志,对比 tool_execution_end 的顺序和 toolResult 消息的顺序。多跑几次,看前者是否变化、后者是否恒定。
实验 4:亲手造一次截断。
在 streamFn 外面包一层,把 maxTokens 压到 30,然后让它写一个 200 行的文件:
const agent = new Agent({ streamFn: (model, context, options) => models.streamSimple(model, context, { ...options, maxTokens: 30 }), initialState: { model },});看事件日志:你应该看到 tool_execution_start 后面紧跟着 tool_execution_end,isError: true,中间没有实际执行时间——这就是 failToolCallsFromTruncatedMessage。
没 key 也一样造:在假 streamFn 里让 message 带一个 toolCall 块、stopReason 写 "length"(done.reason 同步写 "length"),:277 就整批判失败——截不截断只看那个字段,不看是谁吐的。
然后对比另一种失败:把 apiKey 故意填错,重跑一次。这次 stopReason 是 error,走 :254 直接 agent_end,一个工具都不会尝试。
同样是"模型这轮不正常",一个继续、一个终止,区别就在"模型还有没有机会补救"。
实验 5:让钩子炸掉。
const agent = new Agent({ streamFn: models.streamSimple, initialState: { model }, afterToolCall: async () => { throw new Error("钩子炸了"); },});预期:工具照常执行(tool_execution_start 和 tool_execution_end 都有,durationMs 也正常),但结果被换成了错误,模型收到的是"钩子炸了"。
原因在 :908-911——finalizeExecutedToolCall 把整个钩子调用包在 try/catch 里,捕到就换结果。工具白跑了,但 transcript 是完整的。 这就是"失败也是消息"的具体形状:宁可丢一次执行,不能丢一致性。
顺带验证一下 §十三 第 9 条的坑:把同样的代码写在 finishTurn 里,整个 run 会直接崩掉。
实验 6:改一处试试——让一条消息永远收不了尾。
- 改哪里
packages/agent/src/agent-loop.ts:131,把这一行注释掉:
// await emit({ type: "message_end", message });- 预期 事件序列从(本机实测,为排版折行,不含工具调用):
agent_start -> turn_start -> message_start -> message_end -> message_start -> message_end -> turn_end -> agent_end变成:
agent_start -> turn_start -> message_start -> message_start -> message_end -> turn_end -> agent_end用户那条消息从此只有 message_start,没有 message_end。
- 连带
agent.ts:585-588的 reducer 只在这个事件里把消息推进_state.messages。少一次,这条用户消息就不在Agent的状态里, 下一轮convertToLlm拼出的上下文缺它。注意runAgentLoop的返回值newMessages仍然含它(agent-loop.ts:120)——所以是「transcript 对、 状态不对」,这种错最难查。 - 回滚 把那行的
//去掉。
十三、工程暗坑
1. runAgentLoopContinue 会污染你传进去的数组。
runAgentLoop 建了新数组(:121-124):
const currentContext: AgentContext = { ...context, messages: [...context.messages, ...initialMessages], // 新数组};但 runAgentLoopContinue 只做了浅拷贝(:153):
const currentContext: AgentContext = { ...context }; // messages 引用未变后续 context.messages.push(...)(:223、:284、:428)会直接写进你传进来的那个数组。
Agent 不会踩到,因为它传的是快照(agent.ts:469-474):
private createContextSnapshot(): AgentContext { return { messages: this._state.messages.slice(), tools: this._state.tools.slice(), };}直接调低级 API 的人会踩到。绕过办法:调用前自己 .slice()。
2. partialMessage 是原地替换,浅拷贝会看到"对象没变但内容变了"。
:444 是 context.messages[i] = partialMessage——数组元素被换成新对象。但 emit 时传的是 { ...partialMessage }(:448),所以 UI 拿到的是快照。
如果你在监听器里存了 event.message 的引用并指望它"持续更新"——不会,每次都是新对象。反过来,如果你存了 context.messages 的引用,会看到它"悄悄变了"。
3. agentLoop 的 streamFn 类型必填,运行时却有兜底。
签名要求传(:52),内部却是 streamFn ?? getDefaultStreamFn()(:133)。传 undefined 也能跑,前提是 setDefaultStreamFn 被调过(stream-fn.ts:11-13),否则抛 No default stream function configured(stream-fn.ts:17)。
这个兜底存在的理由是:Agent 允许不传 streamFn(agent.ts:244),而它内部要调 runAgentLoop。M02 §8.1 的另一半——"调用由注入决定"——在这里就是这行 ??:类型要求必填,运行期允许宿主从外面塞。
4. one-at-a-time 意味着插话会排队,可能等好几轮。
默认 steeringMode 是 "one-at-a-time"(agent.ts:255)。连插三句,第一句在下一个 drain 点生效,第二、三句要再等。想一次性全塞,设 steeringMode = "all"。
5. 串行降级是整批的,不是单个的。
只要这批里有一个工具是 executionMode: "sequential",其他本来能并行的也一起变串行(:529)。如果 edit 是串行的,而模型一次发了 1 个 edit + 5 个 read,6 个全串行。想快就把只读工具安排到别的批次,或者接受这个保守选择。
6. terminate 用 every,而且全仓几乎没人用。
判定条件写在 shouldTerminateToolBatch(:700-702):
function shouldTerminateToolBatch( finalizedCalls: FinalizedToolCallOutcome[],): boolean { return finalizedCalls.length > 0 && finalizedCalls.every((f) => f.result.terminate === true);}every 的意思是本批全部为 true 才停。所以单条工具想中断整个循环,得让同批其他工具也返回 true——一次 read + 一次 write,只给 write 设 terminate 是无效的。
比 every 更值得知道的是:八个内置工具一个都不设置 terminate。 整仓扫一遍 terminate: true,只落在三处:
| 位置 | 口径 | 用途 |
|---|---|---|
coding-agent/examples/extensions/structured-output.ts:42 |
示例 | 让 agent 在工具调用处结束,直接产出结构化结果 |
coding-agent/examples/extensions/reload-runtime.ts:37 |
示例 | 重载运行时后不让循环继续 |
evals/evals/documentation-audit.eval.ts:27 |
评测 | 审计结束时收尾 |
没有一处是 src/ 里的内建行为。types.ts:323 的注释把定位说得很清楚:"A blocked result can also set terminate: true to participate in the batch early-termination rule"——它是留给扩展作者的出口,不是主干路径。
所以你读 CLI 跑出来的事件流时,永远不会看到它生效。要复现,得自己写一个返回 terminate: true 的扩展工具。
7. 中止时批次不再执行,但已执行的那几条结果照常落账。
这条原来的写法是"中止会破坏『每个 toolCall 必须有 toolResult』的不变量"。对着源码重读一遍,结论是反的。
串行路径(:582-587):
finalizedCalls.push(finalized); messages.push(toolResultMessage); if (signal?.aborted) { break; }}break 在 push 之后。已经跑完的调用先发齐 toolExecutionEnd 和 toolResultMessage,再跳出循环。剩下的调用根本没进循环,自然不会产生结果。
再看 runLoop 那一侧(:268-286):toolResults 来自 executedToolBatch.messages,整批原样 push 进 currentContext.messages 和 newMessages。
并行路径里,中止有两个处理点,而且都不"丢弃"结果:
if (preparation.kind === "immediate") { const finalized = { toolCall, result: preparation.result, isError: preparation.isError, } satisfies FinalizedToolCallOutcome; await emitToolExecutionEnd(finalized, emit); finalizedCalls.push(finalized); // :622 照样入队 if (signal?.aborted) { break; } continue;}finalizedCalls.push(async () => { if (signal?.aborted) { const finalized = { toolCall, result: createErrorToolResult("Operation aborted"), isError: true, } satisfies FinalizedToolCallOutcome; await emitToolExecutionEnd(finalized, emit); return finalized; }:651 的 break 也在 finalizedCalls.push 之后,已经进数组的 thunk 仍会被 :656 的 Promise.all 执行,在里面走上面这条 aborted 分支。
而 prepareToolCall 的两个中止检查点(:748、:767)返回的是 Operation aborted 的 immediate 结果——它会被 :622 push 进 finalizedCalls,不是"不 push"。
所以真正的情况是:
| 说法 | 成立吗 |
|---|---|
| 每个 toolCall 都有对应 toolResult | 成立(已预检或已执行的都有;根本未进批次的根本不会出现在 assistant 消息里) |
| 同一批工具要么全做、要么全不做 | 不成立 |
按中止时序分三种:
- 批次开始前已中止:串行下每个调用都在
prepareToolCall里被 immediate 拦截,第一个就break,进入runLoop的那条路径里toolResults为空;并行下则是每条都被拦截、各自 push 一条Operation aborted,再break。两条路径在这一点上行为不一致——也是一个真实的裂缝:同一次中止,串行得到 0 条结果,并行得到 N 条错误结果。 - 串行跑到第 2 个时中止:第 1 个带真实结果,第 2 个起不再执行,
messages里有 1 条。 - 并行执行中途中止:3 个全部有结果——中止前完成的带真实结果,中止后进 thunk 的带
Operation aborted。
前两种的 transcript 里结果数少于 toolCall 数,但那是"批次没跑完",不是"结果丢了"。被牺牲的是原子性,不是完整性。
实践上这是有代价的:第 1 个 write 已写进磁盘,第 2 个 edit 没执行,而模型看到的历史像是一个正常的半批次。所以工具本身要幂等,别指望循环帮你回滚。
循环自己不检查 signal——它把 signal 一路传进 streamAssistantResponse(:393),靠 provider 在发请求时抛 AbortError,把下一轮变成 stopReason: "aborted",从 :254 退出。如果你自己实现 streamFn 并忽略 signal,就会带着结果数不足的批次去请求:多数 API 会因为 toolCall 数量和 toolResult 数量对不上而 400——但那是 provider 的校验在拒绝,不是 Pi 的 transcript 结构不合法。
8. agent_end 里的 messages 是同一个数组引用。
:263、:299、:329 三处都是 emit({ type: "agent_end", messages: newMessages }),而 runAgentLoop 最后 return newMessages——同一个对象。
订阅者在 agent_end 里 messages.push(...) 会直接改掉 run 的返回值,也会改到 stream.result() 的结果。要改就 [...messages]。
(这条和 §5.6 的 turn.newMessages 是同一个坑,只是发生得更晚。)
9. finishTurn 抛异常会从 runLoop 直接冒出去。
:261 和 :295 都是裸 await config.finishTurn?.(...),没有 try/catch。钩子里一个未捕获的 rejection,会让整个 runLoop reject——然后被 Agent.runWithLifecycle 的 catch 接住(agent.ts:535-536),调 handleRunFailure 合成一条假消息。
后果比想象的重::295 抛出时,下一行的 turn_end(:296)根本不会发,agent_end 里也不包含这一轮已经跑完的工具结果。工具白跑了。
对比 afterToolCall:它被 try/catch 包着(:881-911),炸了最多丢一个结果。同样是宿主钩子,两道保险差这么多,写的时候得心里有数。
10. declareToolChanges 有时返回新数组、有时返回原数组。
:364 和 :367 两处 return pendingMessages 是原引用,:365 和 :371 是新数组。所以拿返回值做 === 判断"有没有变",会在没变时得到 true、变了得到 false。
它还会被调两次::119 注入 prompt 时、:220 注入 pending 时。第二次的入参是 [...preparedMessages, ...pendingMessages],一个新数组。所以"传进去再传回来"不保证同一性,别在它上面挂状态。
十四、三个可以带走的方法
方法一:双层循环——内层管锯齿,外层管续命。
内层 while (hasMoreToolCalls || pendingMessages.length > 0) 处理"模型↔工具"的往复;外层 while (true) 处理"这轮完了还要不要继续"。
把两个关注点混进一个循环,退出条件会变成一团与或非。分开之后,内层的退出只看"还能不能转",外层的退出只看"还有没有理由继续"。
方法二:并行执行,顺序记账。
预检串行(可能问用户、查权限)、执行并发(Promise.all)、结果按原序组装(orderedFinalizedCalls)。
这保证了 transcript 的可重放性:同样的输入,重放出来的消息序列完全一致。缓存、断点恢复、审计日志全依赖这一点。
方法三:失败也是消息。
工具不存在、参数非法、被拦截、抛异常、模型报错、外壳崩溃——全部降级成一条带 isError 的消息,或一条 stopReason: "error" 的 assistant 消息。
调用方只需处理一条路径:订阅事件,等 agent_end。内核把"N 种失败"收敛成"1 种数据"。
本章小结
- 一次 prompt 走九站:拼 context → 请求 → 落 transcript → 工具 → 回写。
- 内层循环管"模型↔工具"的锯齿,外层管"还要不要继续"。
- 退出不看
stopReason,看还有没有没执行的toolCall。 - 预检串行、执行并发、结果按原序组装,transcript 才可重放。
- 十种失败全降级成一条消息,调用方只有一条路径。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| transcript | 只追加的消息序列,run 的输入输出都在它上面 | §三 |
| 锯齿 | 一轮 assistant + 一批 toolResult 的往复 | §五 |
| steering | 跑到一半插话用的队列,下个 drain 点生效 | §6.2 |
| 显式状态 | 进度存在对象里,不靠函数调用栈 | §六 |
| 降级 | 任何失败都变成带 isError 的消息 |
§十 |
练习
练习 1(读):§十三 坑 7 说中止会留下"半批"结果。
假设 assistant 发了 3 个 toolCall 只回了 1 个 toolResult,
下一次请求会发生什么?→ 回 §八 / §十 找到那条被破坏的不变量。
练习 2(改):把 agent.ts:255 的 steeringMode 从默认
"one-at-a-time" 改成 "all",连插三句。预期:三句在同一次 drain 全部注入;
回滚:改回默认值或删掉这一行。
常见误区
- 你会以为 循环停不停看
stopReason;实际是 看还有没有未执行的toolCall;证据 §6.1。 - 你会以为 并行执行会让结果顺序乱;实际是 执行并发、按原序组装;
证据 §九 的
orderedFinalizedCalls。 - 你会以为 只要一条工具
terminate就能停;实际是 整批都为 true 才生效, 而且内置工具全都不设置它;证据 §十三 坑 6。 - 你会以为 中止会让 transcript 里「toolCall 比 toolResult 多」从而不合法; 实际是 已执行、已预检的调用都各有一条结果,被牺牲的是批次原子性; 证据 §十三 坑 7。
读完自检
对照开头那三问,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
一次 pi "找出所有 TODO" 到底发生了什么? |
拼 context → 内层转"模型→工具"的锯齿 → 结果回写 transcript | §三 |
| 循环什么时候继续、什么时候停? | 不看 stopReason,看还有没有没执行的 toolCall |
§6.1 |
| 跑到一半插一句话,是怎么进去的? | steering 队列,在下一次请求前注入 |
§6.2 |
下一步
现在我们知道了循环怎么转、什么时候停、消息怎么流动。但有一块被当成黑盒跳过了:streamAssistantResponse 里那句 await streamFunction(...)。
StreamFn 的契约到底是什么?一个 provider 实现要处理多少种流事件?工具调用的参数是怎么一个字一个字吐出来的?为什么 pi-ai 要在 7 家 provider 之上再盖一层归一?
下一章拆 packages/ai——那 28,581 行里的统一层。
想亲手把这个循环造一遍?Part E 的 E01 用 112 行复刻了同构的两层骨架,零依赖直接跑。
源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/agent/src/agent-loop.ts |
960 | 主循环 :172-330、请求 :390-479、工具 :518-670、钩子 :718-920 |
packages/agent/src/agent.ts |
624 | 状态 :83-112、生命周期 :517-566、reducer :575-622 |
packages/agent/src/types.ts |
552 | 事件 :528-551、钩子 :264-341、工具定义 :478-511 |
packages/agent/src/stream-fn.ts |
21 | 默认流函数注册 :11-20 |
packages/ai/src/utils/event-stream.ts |
— | EventStream 实现 :26- |
packages/ai/src/types.ts |
— | StopReason :489 |
packages/coding-agent/src/core/agent-session.ts |
4480 | 钩子真实用法 :803-947、工具钩子 :668-671 |