Pi Agent 源码级教程
M03

Agent Loop —— 两层循环,三条出路

13,786 字 · 含 661 行代码 · 约 64 分钟

上一章我们把 12 个包摊在桌上,看清了分层:coding-agent 管业务,agent 是无状态内核,ai 统一各家模型。

但架构图是静态的。Agent 之所以是 Agent,靠的是 packages/agent/src/agent-loop.ts 里那个 while (true)。

这个文件 960 行,导出 5 个函数。它是全仓库里"投入产出比"最高的一段——不到一千行,定义了所有上层共享的执行语义:CLI 的交互模式、TUI 的流式渲染、durable 的可持久化运行时、chord 的插件宿主,全都建在这套语义之上。

这一章把它拆开。读完你应该能回答三个问题:

  1. 一次 pi "找出所有 TODO" 到底发生了什么?
  2. 循环什么时候继续、什么时候停?
  3. 用户跑到一半插一句话,是怎么被"插"进去的?

一、引子:同一个模型,三种用法

假设你手里有个不错的模型,想让它"帮我改代码"。有三种做法。

模式 1:直接调用。 一次请求,一次回答。你把代码贴进去,把结果贴出来。

ts
const reply = await model.chat([{ role: "user", content: "把 foo 改成 bar" }]);

模型不知道 foo 在哪,你也没给它工具。它能做的只有猜着写。

模式 2:Workflow。 你写死流程:先读文件,再让模型改,再写回去。

ts
const before = await readFile("a.ts");const patched = await model.chat(`把这段里的 foo 改成 bar:\n${before}`);await writeFile("a.ts", patched);

这能干活了。但流程是你定的。文件太大怎么办?改错了怎么办?要不要先 grep 一下?——这些分支都得你提前想到。分支一多,你就写了个编译器,而不是在写业务。

模式 3:Agent Loop。 你给模型工具和一句目标,让它自己决定下一步。

ts
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):

ts
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 的完整旅程

先看图,再逐个拆。

text
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 一条新的,换 = 原地替换同一格。既没 存 也没 换 的行只发事件,不动上下文。

text
── 开场,一次 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 发请求时的那个数组就长这样——这正是上一问的答案:上一轮的东西整串带走,一条不裁:

text
── 第 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:

ts
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):

ts
export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;

循环不知道流的存在,只知道"有个地方能接事件"。这个缝隙让上层可以换成日志、遥测、录制回放。

4.2 agent_end 一身二职

ts
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):

ts
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 convertToLlm is only called once per turn.

真正合不合法,取决于 convertToLlm 把 AgentMessage 转成了什么,而那一步每轮只跑一次。这里只能查"原始 role",查不了"转换后的 role"。

能查的查到底,查不了的写进契约——这个态度在整章会反复出现。

4.4 文件头那 13 个符号,划出了内核的势力范围

ts
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):

ts
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):

ts
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)是全部逻辑所在。抽掉细节,骨架长这样:

ts
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 });      // :329

5.2 内层在转什么

内层是"模型 ↔ 工具"的锯齿:

模型说"我要 grep" → 执行 grep → 把结果塞回去 → 模型再说 → ...

hasMoreToolCalls 就是齿距。它的赋值只有三处:

行号 赋成 含义
:189 true 进内层时先假定"还有"
:271 false 这轮没有工具调用?先按"停"算
:281 !batch.terminate 有调用,且没被全体要求终止 → 继续

注意 :271 在 if (toolCalls.length > 0) 之前。这个顺序很讲究:先默认停,再看有没有调用。没有就自然退出,逻辑上不需要 else 分支。

5.3 外层在补什么

内层停下有三种原因:没工具了、没插话了、被 terminate 了。

但"内层停了"不等于"这次 run 该结束"。外层依次问三个问题:

  1. 有 follow-up 吗?(:311)用户排着队等 agent 干完这轮再说的消息。有就塞进 pendingMessages,continue 回外层顶部,重开内层。
  2. 宿主要 continue 吗?(:320)finishTurn 上一轮返回了 {action:"continue"},但既没工具结果也没插话。那就"用当前上下文再发一次请求"。explicitContinuation 就是给这种情况留的记号。
  3. 都没有? break(:326)。

:305-307 那三行容易被跳过:

ts
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) 包着——只有跑完过一轮才会触发。

text
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):

ts
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):

ts
export type StopReason =	| "pending"	| "stop"	| "length"	| "toolUse"	| "error"	| "aborted"	| "deferred";

而在 runLoop 里,它只出现在两处::254 的 error / aborted,和 :277 的 length。

"stop" 和 "toolUse" 一次都没出现在循环判断里。 循环改看什么?

ts
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):

ts
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):

ts
getSteeringMessages: async () => {	if (skipInitialSteeringPoll) {		skipInitialSteeringPoll = false;		return [];	}	return this.steeringQueue.drain();},

循环在两个位置拉它:

  • :185,开跑之前(用户可能在你按回车前就插了话);
  • :304,每轮工具执行完、turn_end 之后。

拉到之后,:220-225 把它们和 preparedMessages 一起注入:

ts
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):

ts
// 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):

ts
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):

ts
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:

ts
const decision = await config.finishTurn?.(lastCompletedTurn, signal);

返回值三种(types.ts:147):

ts
export type AgentTurnDecision = { action: "continue" } | { action: "end" };
  • {action:"end"} → 立刻停(:298);
  • {action:"continue"} → 请求"再来一轮";
  • undefined → 正常调度。

continue 的兑现方式有点绕,在 :320-323:

ts
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):

ts
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;	};}

这段是"钩子该怎么写"的范本:

  1. 先干自己的事(分发扩展的 turn_end 边界事件);
  2. 再调上游(previousFinishTurn);
  3. 合并决策,而且 end 优先——上游说停就停,不让扩展覆盖。

prepareRequest 的用法更重(agent-session.ts:803-860),每次请求前重建整个上下文投影:

ts
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 的地方。开头三行就是三级转换:

ts
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):

ts
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):

ts
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 里一次干三件事——压缩、刷新系统提示词、把提示词差异作为消息返回:

ts
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:

ts
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.tools is what the runtime can execute; the transcript's system messages declare what the model may call.

7.4 两个钩子的返回值,形状故意不一样

prepareNextTurn 和 prepareRequest 长得很像,返回类型却不是同一个(types.ts:161-189):

ts
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 都是:

ts
currentContext = nextTurnSnapshot.context ?? currentContext;

宿主要改一个字段,得先把整个 AgentContext 造出来。这和 mergeClientIdentity 的字段级合并正好相反——那边是"给差量",这边是"给全量"。

区别在规模。ClientIdentity 就三个字段,合并便宜;AgentContext 里塞着几千条消息,字段级合并得深拷贝,代价比整体替换高得多。而且整体替换有个隐含好处:宿主必须显式交出完整的下一轮上下文,不可能"漏改一处"。

最后是 thinkingLevel 那三行(:202-207):

ts
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):

ts
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.tools is 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 raw Context cannot 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):

ts
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;		}	}}

三个动作:

  1. start:push 一个 partial 进数组,UI 立刻看到"assistant 开始说话了";
  2. 增量:把数组末位整个替换成新快照(不是拼接,是换对象);
  3. done / error:替换成终态。

为什么替换而不是原地改字段?因为 event.partial 本身就是 provider 流里累积出的完整快照(AssistantMessage 带 content 数组)。每次拿到新快照直接换引用最简单,也不会出现"数组改了一半"的中间态。

两个防御性分支值得注意:

  • addedPartial(:422):有的 provider 不发 start,直接给 done。这时数组里没有占位,得 push 而不是替换(:458-460),还得补发一次 message_start(:462)。
  • 循环体外还有一份收尾(:470-478):流正常结束却没发 done / error 的情况。同一段逻辑写两遍,是"不信 provider"的又一个例子。

还有一行很隐蔽(:419):

ts
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 的流事件大致长这样:

text
starttext_start      text_delta      text_endthinking_start  thinking_delta  thinking_endtoolcall_start  toolcall_delta  toolcall_enddoneerror

12 种。其中 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):

ts
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。

ts
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;	});}

第二段:一次性并发。

ts
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_end in 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):

ts
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):

ts
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 可以改写结果:

ts
const structuredContent =	afterResult.structuredContent ??	(afterResult.content ? undefined : result.structuredContent);

这行的逻辑:钩子如果改了 content 却没给 structuredContent,就把结构化内容删掉。因为两者可能已经对不上了——留着旧的比没有更危险。

9.5 截断保护

:276-279:

ts
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):

ts
type FinalizedToolCallEntry =	| FinalizedToolCallOutcome	| (() => Promise<FinalizedToolCallOutcome>);

数组里既能放"已经定稿的结果",也能放"一个还没跑的 thunk"。为什么要混?

因为预检(prepareToolCall)是串行的,而且可能立刻失败:工具不存在、参数校验不过、beforeToolCall 拦下——这些不需要执行,结果当场就有。如果也包成 thunk,Promise.all 里就要多绕一层没必要的异步。

于是 :615-627 遇到 immediate 直接定稿、立刻 emit tool_execution_end、塞进数组;只有真正要执行的才包成闭包(:629)。

最后 Promise.all 那一句(:656-658):

ts
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 先收集,再统一等。

ts
const updateEvents: Promise<void>[] = [];// ...(partialResult) => {	if (!acceptingUpdates) return;	updateEvents.push(Promise.resolve(onUpdate(partialResult)));},

工具可以边跑边吐增量(读大文件时先给前 100 行)。这些 emit 是异步的,如果在回调里直接 await,会把工具自己的执行卡住。所以先 push 进数组,执行完再 Promise.all 一次性等。

二,acceptingUpdates 在 finally 里也要关。

ts
} catch (error) {	// ...	acceptingUpdates = false;	await Promise.all(updateEvents);	// ...} finally {	acceptingUpdates = false;}

finally 里那句看着冗余——成功和失败分支都关了。但它防的是第三种情况:工具在返回之后还异步调了一次 onUpdate。那时结果已经定稿,再 emit 就会拿旧数据覆盖终态。finally 保证"出了这个函数,这扇门一定关着"。

三,durationMs 用 performance.now(),不是 Date.now()。

ts
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):

ts
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 消息:

ts
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):

ts
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 content or sections.

回到 §7.3 那条哲学:单一事实源。想改提示词?追加消息,别改字段。字段和列表一旦并存,就一定会不一致。

这也解释了 reset()(agent.ts:364-377)为什么是"只留下 baseline system 消息":

ts
const baseline = getCurrentSystemMessage(this._state.messages);this._state.messages = baseline ? [baseline] : [];

清空对话,但保留"你是谁"。

11.2 单飞

runWithLifecycle(agent.ts:517-540)开头:

ts
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_end is the last event emitted for a run, but awaited Agent.subscribe() listeners for that event are still part of run settlement. The agent becomes idle only after those listeners finish.

也就是说:

text
emit agent_end ─────► 监听器 await 完 ─────► finishRun() ─────► idle       ↑                                                            ↑  事件层跑完了                                        waitForIdle() 才 resolve

为什么这么设计?因为监听器可能要写磁盘、发网络请求、更新数据库。如果 agent_end 一发就算空闲,用户马上发下一条,两个 run 就会竞争同一份持久化资源。

processEvents 会把每个 listener 依次 await(agent.ts:619-621):

ts
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 换成固定假回复——二十行以内:

ts
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:数清事件。

ts
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 读一个大目录,中途插话:

ts
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 行的文件:

ts
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:让钩子炸掉。

ts
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,把这一行注释掉:
ts
// await emit({ type: "message_end", message });
  • 预期 事件序列从(本机实测,为排版折行,不含工具调用):
text
agent_start -> turn_start -> message_start -> message_end  -> message_start -> message_end -> turn_end -> agent_end

变成:

text
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):

ts
const currentContext: AgentContext = {	...context,	messages: [...context.messages, ...initialMessages],   // 新数组};

但 runAgentLoopContinue 只做了浅拷贝(:153):

ts
const currentContext: AgentContext = { ...context };   // messages 引用未变

后续 context.messages.push(...)(:223、:284、:428)会直接写进你传进来的那个数组。

Agent 不会踩到,因为它传的是快照(agent.ts:469-474):

ts
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):

ts
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):

ts
finalizedCalls.push(finalized);	messages.push(toolResultMessage);	if (signal?.aborted) {		break;	}}

break 在 push 之后。已经跑完的调用先发齐 toolExecutionEnd 和 toolResultMessage,再跳出循环。剩下的调用根本没进循环,自然不会产生结果。

再看 runLoop 那一侧(:268-286):toolResults 来自 executedToolBatch.messages,整批原样 push 进 currentContext.messages 和 newMessages。

并行路径里,中止有两个处理点,而且都不"丢弃"结果:

ts
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 种数据"。


本章小结

  1. 一次 prompt 走九站:拼 context → 请求 → 落 transcript → 工具 → 回写。
  2. 内层循环管"模型↔工具"的锯齿,外层管"还要不要继续"。
  3. 退出不看 stopReason,看还有没有没执行的 toolCall。
  4. 预检串行、执行并发、结果按原序组装,transcript 才可重放。
  5. 十种失败全降级成一条消息,调用方只有一条路径。

概念回顾

术语 一句话 在哪
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 全部注入; 回滚:改回默认值或删掉这一行。

常见误区

  1. 你会以为 循环停不停看 stopReason;实际是 看还有没有未执行的 toolCall;证据 §6.1。
  2. 你会以为 并行执行会让结果顺序乱;实际是 执行并发、按原序组装; 证据 §九 的 orderedFinalizedCalls。
  3. 你会以为 只要一条工具 terminate 就能停;实际是 整批都为 true 才生效, 而且内置工具全都不设置它;证据 §十三 坑 6。
  4. 你会以为 中止会让 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