Pi Agent 源码级教程
M07

事件驱动 —— 十颗钉子,四十一个挂钩

6,955 字 · 含 284 行代码 · 约 34 分钟

M03 讲循环时反复出现一个动作:await emit({ type: "tool_execution_start", ... })。 M05 讲工具批处理时,也是先 emit 再执行。

问题一直挂着:emit 是谁?它把事件发给谁?为什么有的地方 await,有的地方不 await?

这一章回答。核心结论先说:内核只发十种事件,扩展能挂四十一个钩子,中间隔着一层 翻译。理解这层翻译,你就理解了 Pi 的可扩展性边界在哪—— 那边界不在设计文档里,就在 agent-session.ts:1319 那个函数里。


零、读这章之前,你需要先知道一件事

事件驱动:内核每做一步就广播一次(emit),谁感兴趣谁就订阅(on); 订阅者默认只观察,不改变主流程。一条完整消息不是"一下子"出现的, 而是 message_start → 若干 update → message_end。

没有它会怎样:以为 await agent.prompt() 返回时事情才开始——实际返回时已经广播了几十个事件, TUI 的每一行都是靠它们画出来的。

本书哪里用到:§二 那张事件表;SSE 转发的完整应用在附录 C。


一、一次工具调用,十颗钉子

先把 AgentEvent 摆全(packages/agent/src/types.ts:521-551)。这个联合类型只有 十个成员,分四层:

层 事件 附加数据
Agent agent_start —
Agent agent_end messages
Turn turn_start —
Turn turn_end message toolResults
Message message_start message
Message message_update message assistantMessageEvent
Message message_end message
Tool tool_execution_start toolCallId toolName args
Tool tool_execution_update partialResult
Tool tool_execution_end result isError durationMs

十种,四层,每层都是「开始 →(更新 ×N)→ 结束」的节奏。跟 M04 的 AssistantMessageEvent 十二种不同:那十二种是"内容块"的粒度, 这十种是"生命周期"的粒度。

模型写一个 3 行的 read 调用,实际发出的序列是:

text
agent_start├── turn_start│   ├── message_start          (user 消息)│   ├── message_end│   ├── message_start          (assistant 消息)│   ├── message_update ×N      (每个 token 一次)│   ├── message_end│   ├── tool_execution_start│   ├── tool_execution_update ×N│   └── tool_execution_end└── turn_end

agent_end 不在这棵树里——它是整棵树结束后才发的最后一颗。

1.1 为什么没有 thinking 事件

十二种 AssistantMessageEvent 里有 thinking_start / thinking_delta / thinking_end,但十种 AgentEvent 里没有任何一个专门表示思考。

答案在 message_update 身上:它把整个 AssistantMessageEvent 原样塞进了 assistantMessageEvent 字段(types.ts:538)。于是思考过程的每一个增量, 都是通过 message_update 递出去的——十二种套一种。

这是个刻意的取舍:如果内核也把十二种摊平成顶层事件,AgentEvent 就变成二十一种, 而其中十一种只有渲染层关心。让一个"你不需要认识的事件"当信封, 比让所有人背二十一个类型名划算。

这条取舍还能推得更远:事件的数量应该由"生命周期长度"决定, 而不是由"东西的种类"决定。 消息里能装的内容有十二种, 但消息的生命周期只有三段:开始、更新、结束。 所以事件按三段切,不按十二种切。

1.2 emit 的签名

AgentEventSink 只有一行(packages/agent/src/agent-loop.ts:35):

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

返回 void | Promise<void>——返回值永远是空的。这一行决定了内核事件的性质: 它是通知,不是调用。发出去就完事,对方返回什么都不要。

对比一下 M05 的 beforeToolCall:那个是 Promise<BeforeToolCallResult | undefined>, 有返回值,能改参数、能拦。有没有返回值,是"通知"和"钩子"的分界线。


二、三条通道,不是一条

如果只记住一句话,记这句:Pi 有三条并行的通道,能力完全不同。

2.1 通道一:内核事件流

agentLoop() 返回一个 EventStream<AgentEvent, AgentMessage[]> (agent-loop.ts:47-70):

ts
const stream = createAgentStream();void runAgentLoop(prompts, context, config,	async (event) => { stream.push(event); },	signal, streamFn,).then((messages) => { stream.end(messages); });return stream;

createAgentStream() 定义了什么算"完"(:162-167):

ts
new EventStream<AgentEvent, AgentMessage[]>(	(event) => event.type === "agent_end",	(event) => (event.type === "agent_end" ? event.messages : []),)

agent_end 既标记流结束,又把整轮的 messages 作为最终结果。所以 for await (const event of stream) 读到 agent_end 就停,.result() 拿到全部消息。

这条通道是给谁用的?给"直接调 agentLoop() 的代码"。M03 的 runAgentLoop 就是一例。它是拉取式的:你不读,事件就堆在队列里。

2.2 通道二:Agent.subscribe

Agent 类(packages/agent/src/agent.ts)在内部消费那条流,再广播一遍。 订阅接口只有三行(:275-278):

ts
subscribe(listener): () => void {	this.listeners.add(listener);	return () => this.listeners.delete(listener);}

关键是它等(:619-621):

ts
for (const listener of this.listeners) {	await listener(event, signal);}

串行、await、按注册顺序。所以一个慢 listener 会阻塞后一个,也会阻塞整个循环。

agent_end 的语义还有个坑(types.ts:521-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.

agent_end 不是"结束了",是"不会再有事件了"。 Agent 真正 idle 要等这批 listener 全部 resolve。

2.3 通道三:agent hook

Agent 上还有几个可写的属性(agent-session.ts:668-671):

ts
this.agent.beforeToolCall = (context) => this._beforeToolCall(context);this.agent.afterToolCall  = (context) => this._afterToolCall(context);

这些不是事件,是回调——有返回值,能改行为。M05 讲的五步管道里, beforeToolCall 就是那道"一票否决"的关卡。

2.4 三条通道的分工

触发时机 能否改变行为 内核等不等 典型使用者
事件流 循环内 emit 否 是(同步推) 直接调 agentLoop
subscribe 事件转发后 否 是(串行 await) TUI 渲染
hook 执行前/后 能 是 扩展的拦截

"能不能改"由签名决定,"等不等"由实现决定。 记住这两条就不会混。

2.5 一个场景,走一遍三条通道

假设你想"每次工具执行完打印一行日志"。三条通道各写一遍:

ts
// 通道一:直接读流(只有自己调 agentLoop 时可用)for await (const event of agentLoop(...)) {	if (event.type === "tool_execution_end") log(event);}// 通道二:订阅session.subscribe((event) => {	if (event.type === "tool_execution_end") log(event);});// 通道三:hook —— 做不到。// afterToolCall 存在,但它拿的是 hook context,不是 event;// 而且工具被拦时它根本不会走。

第三条确实做不到。要观察就选前两条。

那前两条怎么选?看你要不要"活得比一次循环更长"。

  • 通道一绑死在一次 agentLoop 调用上,流结束就没了
  • 通道二绑在 Agent 实例上,可反复订阅、可单独取消

TUI 选通道二,因为它要在一个长驻进程里反复渲染。测试代码常选通道一, 因为 for await 写起来最直、生命周期最短。


三、翻译层:十变成四十一

内核发十种,扩展能挂四十一个钩子。中间少了什么、多了什么?

ExtensionAPI.on() 有四十一个重载(core/extensions/types.ts:1621-1688)。 ExtensionEvent 联合类型只有三十二个成员(:1425-1457)——比四十一少 九个,因为 SessionEvent 把十个 session_* 事件收成了一个类型(:882-892)。 工具亚型(BashToolCallEvent、EditToolCallEvent……九个)藏在 ToolCallEvent 内部(:1276-1285),在这个联合里只占一个位置。

3.1 翻译发生在一个函数里

agent-session.ts:1319 的 _emitExtensionEvent 是这张翻译表的全部实现。 它有十个分支,正好对应十种 AgentEvent:

ts
private async _emitExtensionEvent(event: AgentEvent): Promise<void> {	if (event.type === "agent_start") {		this._turnIndex = 0;		await this._extensionRunner.emit({ type: "agent_start" });	} else if (event.type === "agent_end") {		await this._extensionRunner.emit({			type: "agent_end", messages: event.messages,		});	} else if (event.type === "turn_start") {		await this._extensionRunner.emit({			type: "turn_start",			turnIndex: this._turnIndex,       // ← 新加的字段			timestamp: Date.now(),            // ← 新加的字段		});	} else if (event.type === "turn_end") {		/* 不转发,转去 boundary,见 3.3 */	}	// ... message_* / tool_execution_* 各一支}

十个分支里,九个直接转发,一个(turn_end)转去别处。

注意 turn_start 那两个新字段:turnIndex 和 timestamp 内核根本没有。 扩展看到的不是内核事件,是加工过的事件。

3.2 tool_call 和 tool_result 不走这里

四十一个钩子里,只有这两个完全不来自事件流——它们来自 hook:

ts
// agent-session.ts:674-697private async _beforeToolCall({ toolCall, args }) {	const runner = this._extensionRunner;	if (!runner.hasHandlers("tool_call")) return undefined;	return await runner.emitToolCall({		type: "tool_call",		toolName: toolCall.name,		toolCallId: toolCall.id,		input: args as Record<string, unknown>,	});}

这是全章最容易误解的一点:tool_execution_start 和 tool_call 是两个钩子, 触发时机不同。

text
tool_call              ← hook,执行前,能拦、能改 inputtool_execution_start   ← 事件,已经决定要执行了,只是通知

一个只读通知,一个能改。名字很像,能力差一个数量级。

3.3 turn_end 的岔路

turn_end 没被直接转发,而是进了 _dispatchTurnEndBoundary (agent-session.ts:862)。它做三件事:

  1. 从 stopReason 算出 outcome(completed / aborted / error)
  2. 找出这一轮的 assistant 消息已落盘的 entryId
  3. 交给 emitBoundary,拿回 { entries, continue, context }

第 2 步有个硬约束:messageEntryId 找不到就报错并放弃(:870-877)。 也就是说 turn_end 必须在 message_end 落盘之后才可能触发—— 顺序变了,这个钩子就废了。

而返回的 continue 会被 finishTurn 用上(:906-910):

ts
const extensionContinue = await this._dispatchTurnEndBoundary(...);if (extensionContinue) return { action: "continue" };

扩展在 turn_end 返回 { continue: true },能让 agent 自己再转一圈。 这是四十一个钩子里权限最大的几个之一——它直接改循环的退出条件。

3.4 为什么翻译层不在 agent 包里

一个自然的疑问:既然要翻译,为什么不直接在 agent 包里把十种改成四十一种, 省得两层?

因为 agent 包不知道那四十一个概念。看几个钩子名: session_before_fork、before_provider_headers、model_select、 ui_prompt_start。全是"一个具体 CLI 产品"才有的东西。

agent 包的职责边界在 M02 讲过:它只懂"循环、消息、工具、模型"。 它不知道什么叫"会话分叉",不知道 provider 有 headers,也不知道有 UI。

所以翻译层的落点只能是 AgentSession——它是"一次会话"的所有者, 同时听得懂两边的话。它既是调度器,也是翻译器。

这条边界还解释了为什么 wrapper.ts 只剩 30 行(:3-5 注释):

These wrappers only adapt tool execution so extension tools receive the runner context. Tool call and tool result interception is handled by AgentSession via agent-core hooks.

拦截已经从 wrapper 挪到了 AgentSession。 wrapper 现在只干一件事: 给扩展注册的工具塞一个 ctx。

分层不是按文件数分的,是按"谁知道什么"分的。


四、四十一个钩子的地图

不用背,按"你什么时候想动手"查:

时机 钩子 有无返回值
启动/会话 session_start session_shutdown 无
session_before_switch session_before_fork cancel
session_before_compact session_before_tree cancel
输入 input 可改写
user_bash 整套结果
上下文 context context_with_system 新 messages
before_agent_start systemPrompt
请求 before_provider_request 改写 payload
before_provider_headers 就地改 headers
Agent agent_start agent_end 无
agent_before_settle agent_settled continue
Turn turn_start 无
turn_end continue + entries
Message message_start message_update 无
message_end 替换消息
Tool tool_call block reason
tool_result 改 content
tool_execution_start/_update/_end 无
UI ui_prompt_start ui_prompt_end 无
model_select thinking_level_select 无

规律很清楚,四个层:

  • *_start / *_end:纯通知,没有返回值
  • before_*:有返回值,能取消
  • tool_call / tool_result / message_end:能改内容
  • turn_end / agent_before_settle:能改控制流

越往后,权限越大,能出的事也越大。

4.1 四十一个里,常用的只有六个

按 examples/extensions/ 那 70 个例子统计,出场率最高的六个:

钩子 干什么 代表例子
tool_call 拦危险操作、改参数 permission-gate
tool_result 裁剪输出、加标注 truncated-tool
session_start 初始化、读配置 几乎所有
session_shutdown 收尾、提交、清理 auto-commit-on-exit
agent_end 统计、汇报 notify
input 改写用户输入 input-transform

剩下三十五个大多和 UI 渲染有关(custom-header、status-line、 那一批 widget 相关的),或者和 provider 定制有关(debug-provider、 provider-payload)。这两类是"做产品",不是"改行为"。

先掌握这六个,能覆盖八成的扩展需求。 剩下那些不是不重要, 是你一时半会不会去碰。

4.2 ctx 是谁

每个 handler 都拿两个参数:event 和 ctx。 event 是数据,ctx 是能力。

ctx 由 createContext()(runner.ts:884)现造,字段分三组:

组 成员 用途
读 sessionManager getSystemPrompt() 看历史、看提示词
做 ui sendMessage() 弹窗、注入消息
判 hasUI mode 探测环境能力

注意它每次都新建,不是共享单例。你可以在 handler 里随便用, 但不能靠 ctx 的对象身份做判断。

而 ctx 上的"动作"方法都先过一道 assertActive()(runner.ts:1022-1031):

ts
context.reload = () => {	this.assertActive();	return this.reloadHandler();};

这就是那条长得离谱的错误消息的来历(loader.ts:201):

This extension ctx is stale after session replacement or reload. Do not use a captured pi or command ctx after ctx.newSession(), ctx.fork(), ctx.switchSession(), or ctx.reload(). ... move post-replacement work into withSession and use the ctx passed to withSession.

ctx 有寿命。 会话一换,旧 ctx 作废。 这是"用一个对象代表一次会话"必然的代价:对象不会自己知道已经过期, 只能靠调用时检查。


五、三种错误策略

扩展是第三方代码,它会抛错。Pi 对不同的钩子选了三种不同的态度, 这是全章最值得抄的设计。

5.1 观察类:吞掉,记一笔

ExtensionRunner.emit()(runner.ts:1096-1125):

ts
for (const { ext, handlers } of snapshotEventHandlers(...)) {	for (const handler of handlers) {		try {			await handler(event, ctx);		} catch (err) {			this.emitError({				extensionPath: ext.path,				event: event.type,				error: String(err),			});		}	}}

吞掉,上报,继续跑下一个 handler。因为这类钩子本来就不能改变行为—— 它抛错不该影响 agent。一个只想打日志的扩展崩了,不该让整轮对话失败。

5.2 变换类:吞掉,丢掉这次修改

emitMessageEnd / emitToolResult / emitContext / emitBoundary 都是这个策略:catch 之后 emitError,然后把这次的返回值当没发生。

emitMessageEnd 还多一道护栏(runner.ts:1163-1170):

ts
if (handlerResult.message.role !== currentMessage.role) {	this.emitError({ ..., error: "message_end handlers must return a " +		"message with the same role" });	continue;}

能改内容,不能改身份。 把 assistant 换成 user 会让 M06 那套 "最后一条必须是 user/toolResult"的假设全部失效,所以直接拒。

5.3 拦截类:不吞,让它阻断

emitToolCall(:1249-1267)没有 try/catch。handler 抛错就一路往上抛:

ts
try {	return await runner.emitToolCall({ ... });} catch (err) {	if (err instanceof Error) throw err;	throw new Error(		`Extension failed, blocking execution: ${String(err)}`,	);}

结果:这次工具调用不执行,变成一条 isError: true 的结果消息 (M05 那七种失败之一)。这是刻意的——一个负责拦截的守门员自己崩了, 默认应该拦,不是默认放行。

emitUserBash(:1269-1298)稍有不同:catch → emitError → 重新抛。 上报一次是为了让用户看见,重抛是为了让调用方停手。

5.4 一张表

类别 代表 抛错后
观察 emit 吞,继续下一个
变换 emitMessageEnd emitContext 吞,丢弃本次修改
拦截 emitToolCall emitUserBash 抛,阻断执行

越有权限的钩子,越不该宽容。 这是一条可以搬到任何插件系统的规则。

5.5 四种返回值,四种权力

四十一个钩子的返回值,语义只有四种:

返回 含义 谁在用
undefined 没意见,继续 全部
{ block: true } 停这一条 tool_call
{ cancel: true } 停整件事 session_before_*
{ continue: true } 反过来,让它继续 turn_end

前三个是"踩刹车",第四个是"踩油门"。

第四个最反直觉:一个叫"结束"的事件里的钩子,能让循环不结束。 turn_end 的 continue 被 finishTurn 直接翻译成 { action: "continue" } (agent-session.ts:909),而 M03 讲的外层循环看到这个就再跑一轮。

它为什么合理?因为 agent 的生命周期本来就不该由"模型说完了"单方面决定。 扩展可以在模型停下的那一刻说"还没完"。

代价是:这是唯一能让 agent 无限循环的钩子。用之前先想清楚退出条件。


六、顺序、快照与并发

6.1 三路广播的先后

_handleAgentEvent 里顺序是写死的(agent-session.ts:1158-1160):

ts
// Emit to extensions first, then notify public listeners.await this._emitExtensionEvent(event);this._emit(event.type === "agent_end"	? { ...event, willRetry: this._willRetryAfterAgentEnd(event) }	: event);

扩展先看到,UI 后看到。 为什么?

因为 message_end 的扩展可以把消息改掉(emitMessageEnd 返回替换), 而 UI 应该渲染改过的那一版。顺序反了,UI 会先闪一下原文再变。

改完之后还要把 agent 内部状态里的那个对象就地改掉 (_replaceMessageInPlace,:1302-1316):

ts
const targetRecord = target as unknown as Record<string, unknown>;for (const key of Object.keys(targetRecord)) delete targetRecord[key];Object.assign(targetRecord, replacement);

为什么不能直接赋值成新对象?注释给了答案(:1303-1306):

Agent-core stores the finalized message object in its state before emitting message_end. ... Mutating this object in place keeps agent state, later turn/agent events, listeners, and the eventual persistence in sync.

agent 核心在发事件之前就把对象存进 state 了,你换一个新对象,state 里还是旧的。 所以只能掏空再填——这是"共享可变对象"的典型代价。

6.2 快照:slice()

snapshotEventHandlers(runner.ts:276-278)只有两行:

ts
function snapshotEventHandlers(extensions, event) {	return extensions.map((ext) => ({		ext, handlers: ext.handlers.get(event)?.slice() ?? [],	}));}

.slice() 是关键。handler 里调用 pi.on() 返回的取消函数,不会影响当前这一轮 ——数组已经是副本。同理,handler 里新注册的也不会在本轮生效。

这让"边遍历边改集合"这个经典 bug 不可能发生。

6.3 没有并行

所有 handler 都是串行 await。四十一个钩子,没有一个是 Promise.all。

代价是慢——十个扩展各花 10ms,一次事件就 100ms。收益是确定性: 后一个扩展能看到前一个的修改,emitMessageEnd 的"链式替换"才成立。

对一个需要可复现的调试工具来说,这个交换是对的。

6.4 顺序本身就是契约

"扩展 → UI → 落盘"这个顺序,看着像实现细节,其实是契约。

一,message_end 改消息。 扩展先改,UI 渲染改后的版本,落盘也是改后的。 如果反过来——先落盘再给扩展——那改完的内容存不进文件, 下次打开会话就还原了。

二,turn_end 要 entryId。 它必须等落盘完成才能拿到 ID, 所以它排在落盘后面。这也意味着 turn_end 里读 ctx.sessionManager 能看到本轮消息,而在 message_end 里读不到。

三,agent_end 的 willRetry 只有 UI 版有。 _handleAgentEvent 给公开 listener 补了个 willRetry 字段(:1160), 扩展收到的那份没有。想让扩展知道会不会重试,得自己判断。

一个事件,两个版本,三种时序。 读代码时先问"这个 handler 在第几站", 比问"它什么时候触发"更有用。

6.5 没有超时

四十一个钩子,没有一个有超时。handler 里 await 一个永不 resolve 的 promise,agent 就永久卡住。

Pi 没加超时,理由是想清楚了:加了也没用。 真超时了你只有两个选择—— 吞掉(丢掉用户的拦截意图)或者抛错(连观察类都变致命)。两个都比"卡住"更难排。

所以责任在写扩展的人身上:handler 里的每个 await 都得有界。 pi.exec 有进程级超时;ctx.ui.confirm() 等用户,天然可能无限期—— 这也是为什么它只该出现在有人、有 UI 的环境里(§8.3 那道 ctx.hasUI)。


七、写一个扩展

ExtensionAPI 的入口是一个工厂函数(types.ts:2069):

ts
export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;

下面这个扩展干三件事:拦危险命令、给结果打标记、退出时汇报。 它覆盖了三种错误策略对应的三个钩子。

ts
import {	isToolCallEventType, type ExtensionAPI,} from "@earendil-works/pi-coding-agent";const DANGEROUS = /rm\s+-rf\s+\/(?!tmp)|:\(\)\{.*\}:|mkfs\./;let blocked = 0;let calls = 0;export default function (pi: ExtensionAPI) {	// ① 拦截类:能改 input、能拦	pi.on("tool_call", async (event, ctx) => {		calls++;		if (!isToolCallEventType("bash", event)) return;		const cmd = String(event.input.command ?? "");		// 改参数:就地改 event.input		if (cmd.includes("npm")) {			event.input.command = cmd.replace(/\bnpm\b/g, "pnpm");		}		if (DANGEROUS.test(cmd)) {			blocked++;			await ctx.ui.notify(`已拦截危险命令:${cmd}`, "warning");			return { block: true, reason: "危险命令,生产环境禁止" };		}	});	// ② 变换类:改内容,不改身份	pi.on("tool_result", async (event) => {		if (!isToolCallEventType("bash", event)) return;		const text = event.content			.filter((c) => c.type === "text")			.map((c) => c.text)			.join("\n");		return {			content: [{ type: "text", text: `${text}\n\n[audited]` }],		};	});	// ③ 观察类:只读,返回值被忽略	pi.on("agent_end", async (_event, ctx) => {		await ctx.ui.notify(			`本轮 ${calls} 次调用,拦截 ${blocked} 次`, "info",		);	});}

几个必须知道的细节:

「改参数」和「拦」是两种操作。 想改参数就就地改 event.input (注释见 types.ts:1475),返回 { block } 只负责拦。返回一个 input 字段是没用的——ToolCallEventResult 里没有这个字段。

tool_result 的 event.content 已经是数组,不是 Message。 ToolResultEventResult 里还有 details / structuredContent / isError / usage 四个可选字段(types.ts:1503-1509)。

换掉 content 会连带丢掉 structuredContent(同上注释)。因为它可能 和新内容对不上了。想留就一起返回。

判断工具类型必须用 isToolCallEventType。 类型注释解释了为什么 (types.ts:1405-1406):

Direct narrowing via event.toolName === "bash" doesn't work because CustomToolCallEvent.toolName is string which overlaps with all literals.

自定义工具的 toolName 是宽 string,所以直接比较永远不能收窄类型。 得走显式的类型守卫函数。

7.1 用 turn_end 让 agent 继续

验收要求"在指定事件点插入行为",最能把这条讲透的是 turn_end—— 因为它能改控制流。

场景:模型觉得"干完了"但其实没验证。你想在它停下的那一刻推它一把。

ts
let nudges = 0;export default function (pi: ExtensionAPI) {	pi.on("turn_end", async (event) => {		// ① 只为正常结束的一轮兜底		if (event.outcome !== "completed") return;		// ② 最多催两次,避免无限循环		if (nudges >= 2) return;		// ③ 这轮调过工具 = 它在干活,不用催		if (event.toolResults.length > 0) return;		nudges++;		return {			continue: true,			entries: [{				type: "custom_message",				customType: "self-check",				content: "收尾前再查一遍:测试跑了吗?",				display: false,			}],		};	});}

三个细节:

event.outcome 只有三种值(types.ts:990):completed / aborted / error。后两种不该催——用户按了 Esc,或模型报错了,你再说"继续"就是添乱。

entries 的类型是 SessionBoundaryDraft(:1021-1025),四选一: custom / custom_message / context_edit / compaction。 注意给人看的自定义消息用的是 custom_message,不是 custom—— 后者是纯数据块,不进对话。

必须有递减的计数器。 continue: true 没有上限,这就是 §5.5 说的"踩油门"。 没有退出条件的 turn_end 扩展,会让 agent 永远转下去。


八、扩展从哪来

discoverAndLoadExtensions(loader.ts:832-880)按三处找:

  1. 项目级:<cwd>/.pi/extensions/(目录名来自 CONFIG_DIR_NAME, config.ts:606 读 pkg.piConfig?.configDir,默认 ".pi")
  2. 全局:<agentDir>/extensions/
  3. 显式配置的路径:可以是目录(找 package.json 的 pi 清单或 index.ts), 也可以直接是文件

去重靠 seen 集合(:841-851),所以同名文件在两个位置只会加载一次。

.ts 文件靠 jiti 在运行时转译(:580-585),不需要预先编译:

ts
const module = await jiti.import(extensionPath, { default: true });

这也是为什么你可以直接把 .ts 丢进 .pi/extensions/ 就用。

8.1 加载期的"半成品"状态

createExtensionAPI(:248-272)里有个状态机:

ts
let state: "loading" | "active" | "failed" = "loading";const applyRuntimeChange = (change: () => void) => {	if (state === "loading") pendingRuntimeChanges.push(change);	else change();};

扩展加载过程中调用的"动作类" API(发消息、改设置)不会立刻生效,而是排队, 等加载完 commit() 时一起放。加载失败就 discard() 全部丢弃。

一个半死不活的扩展,不该留下半个副作用。

8.2 70 个现成例子

packages/coding-agent/examples/extensions/ 下有 70 个 .ts 扩展: hello.ts(26 行,最小可运行)、confirm-destructive.ts(59 行,用 cancel: true 拦会话切换)、auto-commit-on-exit.ts(49 行,session_shutdown 时自动 commit)、event-bus.ts(43 行,扩展之间互相发消息)。

读扩展比读框架快。 每个文件都是"一个钩子 + 一段业务"。

8.3 拆三个例子

hello.ts(26 行):最小可运行。

ts
const helloTool = defineTool({	name: "hello",	label: "Hello",	description: "A simple greeting tool",	parameters: Type.Object({ name: Type.String() }),	async execute(_id, params) {		return {			content: [{ type: "text", text: `Hello, ${params.name}!` }],			details: { greeted: params.name },		};	},});export default function (pi: ExtensionAPI) {	pi.registerTool(helloTool);}

defineTool 只做类型推导,运行时什么都不干。返回值里 details 就是 M06 讲的 那个"不发给模型、只给 UI 和落盘"的槽位。

注意 execute 有六个参数,最后一个是 _ctx。这正是扩展工具比内置工具多的 那一个:AgentTool.execute 只有五个(M05)。 wrapRegisteredTool 干的就是把 ctx 塞进去这一件事(wrapper.ts:17-21)。

confirm-destructive.ts(59 行):用 cancel 拦。

ts
pi.on("session_before_switch", async (event, ctx) => {	if (!ctx.hasUI) return;              // ← 关键	// ... 问一句,用户说不就 cancel	return { cancel: true };});

ctx.hasUI 那道检查很重要:没有 UI 的环境(--print / rpc)里 ctx.ui.confirm() 会直接抛。能问就问,问不了就放行。

auto-commit-on-exit.ts(49 行):session_shutdown 里做收尾。

它在关闭时跑 git status,有改动就 git add -A 再 commit, 提交信息取最后一条 assistant 消息的第一行(截断到 50 字)。

这个例子演示两件事:一是 pi.exec 可以在扩展里跑外部命令; 二是 ctx.sessionManager.getEntries() 能读全部历史——包括 M06 那八种消息。

8.4 扩展之间也能说话

createEventBus()(core/event-bus.ts,33 行)是扩展之间的独立通道, 和那四十一个钩子完全无关:

ts
pi.events.emit("my:notification", { message, from: "/emit" });pi.events.on("my:notification", (data) => { /* ... */ });

实现是 Node 的 EventEmitter 加一层保护(:19-25):

ts
const safeHandler = async (data: unknown) => {	try { await handler(data); }	catch (err) {		console.error(`Event handler error (${channel}):`, err);	}};

又是一个"吞掉"策略。但注意它是 async 却没人 await—— 所以总线事件不保证顺序,也不保证完成。

它是广播,不是 RPC。 想让另一个扩展"回你一句",得自己再发一条。


九、完整数据流

从内核一颗钉子,到扩展拿到它:

text
agent-loop.ts  emit({ type: "tool_execution_end", ... })     ↓  AgentEventSink(通道一:EventStream)Agent.subscribe 的 listeners       (通道二:UI 渲染)     ↓AgentSession._handleAgentEvent           ← agent-session.ts:1119     ├── 1. 内部记账(nestedCalls、队列清理)     ├── 2. _emitExtensionEvent     │      ↓  十分支翻译,加 turnIndex/timestamp     │   ExtensionRunner.emit()        ← runner.ts:1096     │      ↓  snapshotEventHandlers(.slice())     │   handler(event, ctx)  ×N       串行 await     │      ↓  异常 → emitError(吞 or 抛)     ├── 3. this._emit()               公开 subscriber     └── 4. SessionManager.appendMessage   落盘

注意第 2 步和第 4 步的顺序:扩展先于落盘。所以 message_end 的 handler 能看到还没写盘的消息,而 turn_end 就必须等落盘完成(要 entryId)。

同一个 message_end 事件,在第 2 步里"消息还没进文件",在第 3 步里 "扩展可能已经改过它了"。时序是这套系统的隐性契约。

反过来看也成立:这套设计能撑住 70 个示例扩展,靠的就是这三条通道的分工—— 想观察的去 subscribe,想拦的去 tool_call,想改上下文的去 context。 每一类需求都有且只有一个正确入口,别的地方虽然能实现,但会让时序乱掉。


十、自己动手验证

环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。

实验 1:数一数内核事件。

bash
# 在仓库根目录执行cd packages/agent/srcsed -n '528,551p' types.ts

十个 type:,四个注释分组。

实验 2:确认钩子数量。

bash
cd ../../coding-agent/src/core/extensionsgrep -c 'on(event: "' types.ts

四十一个 on 重载。

实验 3:找翻译层。

bash
cd ../../..grep -n "_emitExtensionEvent" core/agent-session.ts

定义在 :1319,调用在 :1159——调用点里那句注释就是"扩展先于 UI"。

实验 4:对比两个易混钩子。

bash
cd core/extensionssed -n '1474,1483p' types.ts

ToolCallEventResult 只有 block / reason / terminate 三个字段, 没有 input。这就证明了"改参数靠就地改,不靠返回值"。

实验 5:确认错误策略的差异。

bash
grep -n "async emitToolCall" -A 6 runner.tsgrep -n "async emit(" -A 8 runner.ts

前者没有 try,后者有。

实验 6:跑一个扩展。

bash
mkdir -p .pi/extensionscp examples/extensions/hello.ts .pi/extensions/

重启后让模型调 hello,它会回 Hello, <name>!。

实验 7:改一处试试——把「扩展先于 UI」这条顺序反过来。

  • 改哪里 packages/coding-agent/src/core/agent-session.ts:1159-1160, 两行对调:
ts
// 原样await this._emitExtensionEvent(event);this._emit(event.type === "agent_end"	? { ...event, willRetry: this._willRetryAfterAgentEnd(event) }	: event);
ts
// 对调后this._emit(event.type === "agent_end"	? { ...event, willRetry: this._willRetryAfterAgentEnd(event) }	: event);await this._emitExtensionEvent(event);
  • 准备一个能改消息的扩展 在 message_end 里给 assistant 末尾加 [改]:
ts
pi.on("message_end", async (event) => {	const m = event.message;	if (m.role !== "assistant") return;	if (!Array.isArray(m.content)) return;	const content = m.content.map((c) =>		c.type === "text" ? { ...c, text: c.text + "[改]" } : c);	return { message: { ...m, content } };});

用 DefaultResourceLoader 的 extensionFactories 挂上就行,不用往 ~/.pi/agent/extensions/ 里塞文件。

  • 预期 原顺序下 UI 拿到改过的版本;对调后 UI 拿到原文。

  • 实测 原顺序:

text
subscribe 看到尾部: "收到[改]"state 里最后一条: assistant "收到[改]"

对调后:

text
subscribe 看到尾部: "收到"state 里最后一条: assistant "收到[改]"

这就是 §6.1 那句注释的字面证据。注意第二行没变—— _replaceMessageInPlace(:1302)事后改的是 agent state 里那个对象, 和顺序无关。

  • 连带 不报错、不崩、没有任何警告。前端只会在那一瞬间渲染出原文, 随后被就地改写覆盖。这就是注释里说的「UI 会先闪一下原文再变」—— 如果你的 UI 已经按旧文本算好了布局,它会闪一下,或者干脆停在旧版本。 顺序看着像实现细节,错位了就是渲染 bug。
  • 回滚 两行换回去。改回来再跑一次,subscribe 又变回 "收到[改]"。

十一、工程暗坑

1. 以为 tool_execution_start 能拦。

不能。它是通知,返回值被丢弃。要拦用 tool_call。

2. 以为 subscribe 的 listener 抛错会中断。

会。Agent.processEvents 里是裸 await listener(...)(agent.ts:619-621), 没有 try/catch。一个渲染 bug 能让整轮对话挂掉。自己包一层 try。

3. message_end 返回新对象,结果没生效。

因为 agent 核心已经存了旧引用。Pi 用 _replaceMessageInPlace 解决, 你自己的 listener 遇到的同类问题要自己处理——共享可变对象的世界里, "返回新值"和"改掉旧值"不是一回事。

4. context handler 里看不到 system 消息。

emitContext 传给 handler 的是过滤后的列表(runner.ts:1312):

ts
const visibleMessages = currentMessages.filter(	(message) => message.role !== "system",);

想连 system 一起看,用 context_with_system——那个拿的是全量, 但删掉首条 system 会触发一条告警(:1345-1351),因为 provider 从首条 system 里读提示词和工具声明(M04 讲过)。

5. 在 handler 里 pi.on() 不会立刻生效。

slice() 快照。想在下一轮生效,就得等下一个事件。

6. 扩展加载期调 pi.sendMessage() 会抛。

runtime 还是 notInitialized(loader.ts:162-164)。要在加载期排队的操作用 applyRuntimeChange——不过那是内部 API,扩展侧的做法是在 session_start 里做,别在工厂函数体里做。

7. turn_end 拿不到 entryId 就整轮跳过。

_dispatchTurnEndBoundary 找不到落盘记录会 emitError 然后 return false (agent-session.ts:870-877)。如果你的扩展依赖 turn_end,先确认 message_end 的落盘没被别人吞掉。

8. subscribe 的 listener 拿到的是"同一个对象",不是副本。

processEvents 直接把 event 传给每个 listener(agent.ts:619-620)。 你在 A 里改了 event.message.content,B 会看到改后的。 想隔离就自己 structuredClone——但那样你也看不到扩展的修改了, 属于另一头的取舍。

9. 自定义消息能在 message_end 里换掉内置消息。

emitMessageEnd 只校验 role 相同,没有限制"必须是四种内置类型"。 所以扩展可以把一条 assistant 消息换成 custom 消息(M06 的八种之一), _replaceMessageInPlace 接受,SessionManager 会按 custom 分支落盘 (agent-session.ts:1166-1173)。

这条路径很隐蔽:一条 assistant 消息可以变成 custom,而 UI 大概率会渲染崩。

10. message_update 每个 token 都走完整分发链路。

流式响应时,每产出一个增量就是一颗 message_update。而 emit() 一进去就 this.createContext()(runner.ts:1097),再造一遍 handler 快照数组—— 即使一个 handler 都没注册。

只有 tool_call(agent-session.ts:679)和 turn_end(:869)做了 hasHandlers 快路径。高频的 message_update 没有。

所以装了十个扩展时,流式会明显变顿——不是 handler 慢,是每 token 建两次大对象。 高频事件要优先加空检查。

11. 把 ctx 存到模块级变量里。

examples/extensions/event-bus.ts:14 就这么干了:

ts
let currentCtx: ExtensionContext | undefined;pi.on("session_start", async (_event, ctx) => {	currentCtx = ctx;});

单会话场景下能用,但 ctx.newSession() 之后它就是 stale 的了, 再调 currentCtx.ui.notify() 会抛 assertActive 的错误。

没有更好的办法吗?有——把"用完这个 ctx"的代码搬进 withSession, 用回调里传进来的新 ctx。错误消息里就是这么建议的。

存一个有能力对象的时候,就要准备好它会被吊销。

12. handler 的执行顺序 = 扩展的加载顺序,而加载顺序是拼出来的。

discoverAndLoadExtensions 按"项目 → 全局 → 显式配置"三段拼(loader.ts:853-877), snapshotEventHandlers 再按这个数组顺序遍历。

所以两个扩展都挂 tool_call 时,谁先跑取决于它们在哪—— 项目级的先于全局的。别把拦截逻辑写成"我一定在别人之前"。 要保证顺序,就在同一个扩展里注册两个 handler(pi.on 可多次调用, 顺序按注册先后)。


十二、三个可以带走的方法

方法一:通知用一个空返回值的签名,钩子用带返回值的签名。

AgentEventSink = (event) => Promise<void> | void 和 beforeToolCall = (ctx) => Promise<Result | undefined> 的差别只有一处: 有没有返回值。但调用方的代码形态完全不同——前者可以 void emit(...), 后者必须 const r = await hook(...)。

类型签名是能力的声明书。 别用 any 糊过去,那等于放弃了这个区分。

方法二:按"权限"给异常定策略,不按"重要性"。

观察类吞、变换类丢、拦截类抛。三层对应三种权限, 而不是"这个钩子重不重要"。

一个只打日志的扩展崩了,用户不该看到报错;一个负责拦截的扩展崩了, 用户必须看到报错。判断依据是"它本来能做什么",不是"它多重要"。

方法三:越权的地方,加一道形状校验。

message_end 只能换内容不能换 role(:1163-1170), context_with_system 删了首条 system 会告警(:1345-1351)。

这两处的共同点:允许修改,但校验"改完还满足下游假设吗"。 扩展系统不可能不开放,但可以在开放的口子上装一道形状检查—— 比事后 debug 便宜得多。

写自己的插件系统时,先列一遍"下游依赖什么":

  • 消息的 role 变了 → M06 那套 convertToLlm 的假设失效
  • 首条 system 没了 → provider 收不到提示词和工具声明(M04)
  • 工具参数在 hook 里被改了 → 校验已经跑过,没人再验一遍

第三类 Pi 没拦,因为 tool_call 排在 validateToolArguments 之后(M05)。 能拦的别放过,拦不到的写进文档。


本章小结

  1. 内核只发 10 种事件,扩展能挂 41 个钩子,中间隔一层翻译。
  2. 三条通道:事件广播 / 钩子 / 工具包装,不是一条。
  3. 异常策略按权限定:观察类吞、变换类丢、拦截类抛。
  4. 越权处加形状校验:允许换内容,不允许换 role。
  5. handler 在边界处快照,运行中注册本轮不生效。

概念回顾

术语 一句话 在哪
三条通道 事件 / 钩子 / 工具包装,各有各的返回值约定 §二
翻译层 10 个内核事件翻成 41 个钩子 §三
三种策略 吞 / 丢 / 抛,按"本来能做什么"分 §五
快照 snapshotEventHandlers,本轮不变 §六
形状校验 改完还要满足下游假设 §十二 方法三

练习

练习 1(读):§五 说拦截类钩子抛了必须让用户看到。 如果把它当"观察类"一并吞掉,用户会经历什么?→ 对比 §五 的三种策略表。

练习 2(改):照 §七 的模板写一个扩展,在 beforeToolCall 里 对 edit 一律 block(不带 terminate)。预期:edit 不执行, 模型收到一条被拦截的结果,循环继续;回滚:删掉这个扩展文件。

常见误区

  1. 你会以为 四十一钩子都得会用;实际是 常用只有六个;证据 §4.1。
  2. 你会以为 扩展抛异常会中断流程;实际是 观察类直接吞;证据 §五。
  3. 你会以为 运行中注册的 handler 立刻生效;实际是 要等下一个边界; 证据 §六 的快照。

读完自检

三条,能不能不看稿说出来?

自检 一句话答案 不会就去
内核发几种事件?扩展能挂几个钩子? 10 / 41,中间隔一层翻译 §一、§三
扩展抛异常了,谁该看到报错? 按权限定:观察类吞、变换类丢、拦截类抛 §五
四十一个钩子,常用的有几个? 六个 §4.1

下一步

事件系统讲完,内核部分就齐了:循环在前面转,模型在后面调, 工具在手里,消息在账上,事件在血管里流。

下一章开始往上走。模型每次请求都要带上"系统提示词"——那段几千字的、 告诉模型它是谁的文本,是怎么拼出来的?谁往里加东西?顺序能不能改?

打开上下文装配。

想亲手给工具表挂一层钩子?Part E 的 E07 用 46 行造了同构的 before/after 包装器,内核零改动。


本章源码索引

文件 行数 本章用到的位置
packages/agent/src/types.ts 552 AgentEvent :521-551、agent_end 语义 :521-527
packages/agent/src/agent-loop.ts 960 AgentEventSink :35、createAgentStream :162-167
packages/agent/src/agent.ts 624 listeners :196、subscribe :275-278、processEvents :575-622
packages/coding-agent/src/core/agent-session.ts 4,480 _handleAgentEvent :1119、三路广播 :1158-1160、_replaceMessageInPlace :1302、_emitExtensionEvent :1319-1397、工具 hook :668-740、_dispatchTurnEndBoundary :862-892
packages/coding-agent/src/core/extensions/types.ts 2,329 ExtensionAPI.on 四十一重载 :1621-1688、ExtensionEvent :1425-1457、ToolCallEventResult :1474-1483、ToolResultEventResult :1503-1509、isToolCallEventType :1408-1422
packages/coding-agent/src/core/extensions/runner.ts 1,566 snapshotEventHandlers :276-278、hasHandlers :772-780、emit :1096、emitMessageEnd :1151、emitToolResult :1190、emitToolCall :1249、emitUserBash :1269、emitContext :1305-1360、emitBoundary :1036
packages/coding-agent/src/core/extensions/loader.ts 881 createExtensionAPI 状态机 :248-272、createExtension :599-615、jiti :580-585、discoverAndLoadExtensions :832-880
packages/coding-agent/src/core/extensions/wrapper.ts 30 wrapRegisteredTool :17-21(只做 execute 适配)
packages/coding-agent/src/core/event-bus.ts 34 createEventBus、handler 异常隔离 :19-25
packages/coding-agent/src/config.ts 682 CONFIG_DIR_NAME :606
packages/coding-agent/examples/extensions/ 70 个文件 hello.ts confirm-destructive.ts auto-commit-on-exit.ts event-bus.ts