事件驱动 —— 十颗钉子,四十一个挂钩
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 调用,实际发出的序列是:
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_endagent_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):
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):
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):
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):
subscribe(listener): () => void { this.listeners.add(listener); return () => this.listeners.delete(listener);}关键是它等(:619-621):
for (const listener of this.listeners) { await listener(event, signal);}串行、await、按注册顺序。所以一个慢 listener 会阻塞后一个,也会阻塞整个循环。
agent_end 的语义还有个坑(types.ts:521-527 的注释明说):
agent_endis the last event emitted for a run, but awaitedAgent.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):
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 一个场景,走一遍三条通道
假设你想"每次工具执行完打印一行日志"。三条通道各写一遍:
// 通道一:直接读流(只有自己调 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:
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:
// 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 是两个钩子,
触发时机不同。
tool_call ← hook,执行前,能拦、能改 inputtool_execution_start ← 事件,已经决定要执行了,只是通知一个只读通知,一个能改。名字很像,能力差一个数量级。
3.3 turn_end 的岔路
turn_end 没被直接转发,而是进了 _dispatchTurnEndBoundary
(agent-session.ts:862)。它做三件事:
- 从
stopReason算出outcome(completed/aborted/error) - 找出这一轮的 assistant 消息已落盘的 entryId
- 交给
emitBoundary,拿回{ entries, continue, context }
第 2 步有个硬约束:messageEntryId 找不到就报错并放弃(:870-877)。
也就是说 turn_end 必须在 message_end 落盘之后才可能触发——
顺序变了,这个钩子就废了。
而返回的 continue 会被 finishTurn 用上(:906-910):
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):
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
pior command ctx afterctx.newSession(),ctx.fork(),ctx.switchSession(), orctx.reload(). ... move post-replacement work intowithSessionand use the ctx passed towithSession.
ctx 有寿命。 会话一换,旧 ctx 作废。
这是"用一个对象代表一次会话"必然的代价:对象不会自己知道已经过期,
只能靠调用时检查。
五、三种错误策略
扩展是第三方代码,它会抛错。Pi 对不同的钩子选了三种不同的态度, 这是全章最值得抄的设计。
5.1 观察类:吞掉,记一笔
ExtensionRunner.emit()(runner.ts:1096-1125):
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):
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 抛错就一路往上抛:
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):
// 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):
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)只有两行:
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):
export type ExtensionFactory = (pi: ExtensionAPI) => void | Promise<void>;下面这个扩展干三件事:拦危险命令、给结果打标记、退出时汇报。 它覆盖了三种错误策略对应的三个钩子。
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 becauseCustomToolCallEvent.toolNameisstringwhich overlaps with all literals.
自定义工具的 toolName 是宽 string,所以直接比较永远不能收窄类型。
得走显式的类型守卫函数。
7.1 用 turn_end 让 agent 继续
验收要求"在指定事件点插入行为",最能把这条讲透的是 turn_end——
因为它能改控制流。
场景:模型觉得"干完了"但其实没验证。你想在它停下的那一刻推它一把。
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)按三处找:
- 项目级:
<cwd>/.pi/extensions/(目录名来自CONFIG_DIR_NAME,config.ts:606读pkg.piConfig?.configDir,默认".pi") - 全局:
<agentDir>/extensions/ - 显式配置的路径:可以是目录(找
package.json的 pi 清单或index.ts), 也可以直接是文件
去重靠 seen 集合(:841-851),所以同名文件在两个位置只会加载一次。
.ts 文件靠 jiti 在运行时转译(:580-585),不需要预先编译:
const module = await jiti.import(extensionPath, { default: true });这也是为什么你可以直接把 .ts 丢进 .pi/extensions/ 就用。
8.1 加载期的"半成品"状态
createExtensionAPI(:248-272)里有个状态机:
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 行):最小可运行。
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 拦。
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 行)是扩展之间的独立通道,
和那四十一个钩子完全无关:
pi.events.emit("my:notification", { message, from: "/emit" });pi.events.on("my:notification", (data) => { /* ... */ });实现是 Node 的 EventEmitter 加一层保护(:19-25):
const safeHandler = async (data: unknown) => { try { await handler(data); } catch (err) { console.error(`Event handler error (${channel}):`, err); }};又是一个"吞掉"策略。但注意它是 async 却没人 await——
所以总线事件不保证顺序,也不保证完成。
它是广播,不是 RPC。 想让另一个扩展"回你一句",得自己再发一条。
九、完整数据流
从内核一颗钉子,到扩展拿到它:
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:数一数内核事件。
# 在仓库根目录执行cd packages/agent/srcsed -n '528,551p' types.ts十个 type:,四个注释分组。
实验 2:确认钩子数量。
cd ../../coding-agent/src/core/extensionsgrep -c 'on(event: "' types.ts四十一个 on 重载。
实验 3:找翻译层。
cd ../../..grep -n "_emitExtensionEvent" core/agent-session.ts定义在 :1319,调用在 :1159——调用点里那句注释就是"扩展先于 UI"。
实验 4:对比两个易混钩子。
cd core/extensionssed -n '1474,1483p' types.tsToolCallEventResult 只有 block / reason / terminate 三个字段,
没有 input。这就证明了"改参数靠就地改,不靠返回值"。
实验 5:确认错误策略的差异。
grep -n "async emitToolCall" -A 6 runner.tsgrep -n "async emit(" -A 8 runner.ts前者没有 try,后者有。
实验 6:跑一个扩展。
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, 两行对调:
// 原样await this._emitExtensionEvent(event);this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);// 对调后this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);await this._emitExtensionEvent(event);- 准备一个能改消息的扩展 在
message_end里给 assistant 末尾加[改]:
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 拿到原文。
-
实测 原顺序:
subscribe 看到尾部: "收到[改]"state 里最后一条: assistant "收到[改]"对调后:
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):
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 就这么干了:
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)。
能拦的别放过,拦不到的写进文档。
本章小结
- 内核只发 10 种事件,扩展能挂 41 个钩子,中间隔一层翻译。
- 三条通道:事件广播 / 钩子 / 工具包装,不是一条。
- 异常策略按权限定:观察类吞、变换类丢、拦截类抛。
- 越权处加形状校验:允许换内容,不允许换 role。
- handler 在边界处快照,运行中注册本轮不生效。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 三条通道 | 事件 / 钩子 / 工具包装,各有各的返回值约定 | §二 |
| 翻译层 | 10 个内核事件翻成 41 个钩子 | §三 |
| 三种策略 | 吞 / 丢 / 抛,按"本来能做什么"分 | §五 |
| 快照 | snapshotEventHandlers,本轮不变 |
§六 |
| 形状校验 | 改完还要满足下游假设 | §十二 方法三 |
练习
练习 1(读):§五 说拦截类钩子抛了必须让用户看到。 如果把它当"观察类"一并吞掉,用户会经历什么?→ 对比 §五 的三种策略表。
练习 2(改):照 §七 的模板写一个扩展,在 beforeToolCall 里
对 edit 一律 block(不带 terminate)。预期:edit 不执行,
模型收到一条被拦截的结果,循环继续;回滚:删掉这个扩展文件。
常见误区
- 你会以为 四十一钩子都得会用;实际是 常用只有六个;证据 §4.1。
- 你会以为 扩展抛异常会中断流程;实际是 观察类直接吞;证据 §五。
- 你会以为 运行中注册的 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 |