深入理解 pi/第 05 章
32 个挂点,6 个能改
pi 的扩展面是一个 32 个事件的联合类型。但真正决定架构的不是「有多少个」,而是哪些能改返回值。
export type ExtensionEvent = // —— 生命周期(12)—— | ProjectTrustEvent | ResourcesDiscoverEvent | McpServersChangeEvent | SessionEvent | BeforeAgentStartEvent | AgentStartEvent | AgentEndEvent | AgentBeforeSettleEvent | AgentSettledEvent | TurnStartEvent | TurnEndEvent // —— 消息与上下文(7)—— | ContextEvent | ContextWithSystemEvent | MessageStartEvent | MessageUpdateEvent | MessageEndEvent | CacheWarmingDecisionEvent | InputEvent // —— 工具(3)—— | ToolCallEvent | ToolResultEvent | UserBashEvent // —— 模型与采样(4)—— | BeforeProviderRequestEvent | BeforeProviderHeadersEvent | AfterProviderResponseEvent | ProviderStreamEvent // —— UI 与模型选择(6)—— | UIPromptStartEvent | UIPromptEndEvent | ModelSelectEvent | ThinkingLevelSelectEvent | ToolExecutionStartEvent | ToolExecutionUpdateEvent;
分类不重要,能改才重要。32 个事件里只有 6 个定义了 Result 类型——也就是说只有这 6 个能影响流程,其余 26 个是纯观察。
| # | 可改事件 | 能改什么 | 性质 |
|---|---|---|---|
| 1 | ProjectTrustEvent | 信任决定 | 拦截 |
| 2 | BeforeAgentStartEvent | systemPrompt 整段替换、注入消息 | 拦截 |
| 3 | ContextEvent | messages 整个数组 | 改写 |
| 4 | ToolCallEvent | block 拒绝、原地改 input | 拦截 |
| 5 | ToolResultEvent | 结果内容、isError、用量 | 改写 |
| 6 | MessageEndEvent | 替换最终消息(角色不可变) | 改写 |
types.ts:1411-1443(32 事件)· :1460(ToolCallEventResult)
ToolCall 的三种用法,一个字段
ToolCallEventResult 只有三个字段,但它覆盖了「拦住」「改参数」「提前结束」三种完全不同的意图:
export interface ToolCallEventResult { /** Block tool execution. To modify arguments, mutate `event.input` in place instead. */ block?: boolean; reason?: string; /** * Hint that the agent should stop after the current tool batch when this call is blocked. * Early termination only happens when every finalized tool result in the batch sets this to true. */ terminate?: boolean; }
最值得注意的是注释里那句 To modify arguments, mutate event.input in place instead。
改参数不是通过返回值,而是靠原地改事件对象——这是个不寻常但合理的选择:
| 方案 | 优点 | 缺点 |
|---|---|---|
返回值带新 input | 纯函数,易测 | 多个 handler 时谁覆盖谁不清楚 |
原地改 event.input | 多个 handler 天然串行叠加 | 隐式副作用,调试时看不出谁改的 |
pi 选了后者。代价可接受,因为它保证了一件事:多个扩展可以先后加工同一个参数,而不是最后一个说了算。
terminate 的「全体一致」规则
terminate 的语义比看起来严格得多:只有当整批里每一个工具结果都设了 terminate: true,才会提前结束。
function shouldTerminateToolBatch(finalizedCalls: FinalizedToolCallOutcome[]): boolean { return finalizedCalls.length > 0 && finalizedCalls.every((finalized) => finalized.result.terminate === true); }
为什么要求全体一致而不是任意一个?因为半批执行是危险的:模型一次发起 3 个工具调用, 如果第 1 个说「够了」,剩下 2 个不执行,模型下一轮会看到「有 2 个调用没有结果」——轨迹结构就坏了。 要么整批做完,要么整批结束。
agent-loop.ts:700-702(every 而非 some)· types.ts:1464-1468(terminate 注释)
顺序:为什么 input 钩子必须在展开之前
input 事件的挂点在 prompt() 里,位置很讲究——它在 skill 展开与模板替换之前。
这个顺序不成立的话,扩展就无法工作:
| 顺序 | 扩展看到的输入 | 能做什么 |
|---|---|---|
| 展开之前拦截(pi 的做法) | 用户原话 | 改写、加前缀、整体吞掉 |
| 展开之后拦截 | 已拼装的完整 prompt | 只能做「整段替换」,改写原话已不可能 |
同一条链上还有一个顺序决定:skill 展开先于 template 展开。 因为 skill 是「可能带参数的指令块」,template 是「纯文本替换」——前者更结构化,先做才能让后者处理它的产物。
agent-session.ts:2117(input 钩子)
Context 事件:最危险的那个
ContextEvent 的返回值是 { messages?: AgentMessage[] }——整个消息数组都能换掉。
这是能力最大、也最容易搞坏东西的一个。
它挂在 transformContext 上,在 convertToLlm 之前执行:
let messages = context.messages; if (config.transformContext) { messages = await config.transformContext(messages, signal); // ← ContextEvent 在这 } const llmMessages = await config.convertToLlm(messages); // ← 之后才翻译
位置决定了它不会破坏持久化:transformContext 只影响「发给模型的这一份」,
agent-session.ts 里的 transcript 一个字都不改。
ContextEvent 能让你在第 1,000 条消息处插入一句话,
却不能让这句话出现在会话文件里。想持久化必须走 CustomMessageEntry(写进 appendMessage),
那是另一条路径、另一种责任。
「改视图」和「改事实」被刻意分开了。
types.ts:1449-1451(ContextEventResult)· agent-loop.ts:399
扩展面的三条边界
ContextEvent 只改「这一份请求」,会话文件不变。想持久化得写 CustomMessageEntry。terminate 要求 every() 而非 some()。这三条合起来说明一件事:pi 的扩展不是「插件随便改框架」,而是「在框架划定的语义边界上做加法」。 能力是受限的,但受限让它可预测。