深入理解 pi 05 / 06 目录 单页全本 学习手册 对比站

深入理解 pi/第 05 章

5.1

32 个挂点,6 个能改

pi 的扩展面是一个 32 个事件的联合类型。但真正决定架构的不是「有多少个」,而是哪些能改返回值。

packages/coding-agent/src/core/extensions/types.ts:1411-1443
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 个是纯观察。

#可改事件能改什么性质
1ProjectTrustEvent信任决定拦截
2BeforeAgentStartEventsystemPrompt 整段替换、注入消息拦截
3ContextEventmessages 整个数组改写
4ToolCallEventblock 拒绝、原地改 input拦截
5ToolResultEvent结果内容、isError、用量改写
6MessageEndEvent替换最终消息(角色不可变)改写

types.ts:1411-1443(32 事件)· :1460(ToolCallEventResult)

5.2

ToolCall 的三种用法,一个字段

ToolCallEventResult 只有三个字段,但它覆盖了「拦住」「改参数」「提前结束」三种完全不同的意图:

packages/coding-agent/src/core/extensions/types.ts:1460-1469
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,才会提前结束。

packages/agent/src/agent-loop.ts:700-702
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 注释)

5.3

顺序:为什么 input 钩子必须在展开之前

input 事件的挂点在 prompt() 里,位置很讲究——它在 skill 展开与模板替换之前。 这个顺序不成立的话,扩展就无法工作:

顺序扩展看到的输入能做什么
展开之前拦截(pi 的做法)用户原话改写、加前缀、整体吞掉
展开之后拦截已拼装的完整 prompt只能做「整段替换」,改写原话已不可能

同一条链上还有一个顺序决定:skill 展开先于 template 展开。 因为 skill 是「可能带参数的指令块」,template 是「纯文本替换」——前者更结构化,先做才能让后者处理它的产物。

agent-session.ts:2117(input 钩子)

5.4

Context 事件:最危险的那个

ContextEvent 的返回值是 { messages?: AgentMessage[] }——整个消息数组都能换掉。 这是能力最大、也最容易搞坏东西的一个。

它挂在 transformContext 上,在 convertToLlm 之前执行:

packages/agent/src/agent-loop.ts:398-404
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

5.5

扩展面的三条边界

① 观察与拦截分开:26 观察 / 6 可改
想看什么都能看,想改必须走指定的 6 个口子。这让「扩展会不会悄悄改变行为」这个问题有了确定答案。
② 改视图与改事实分开
ContextEvent 只改「这一份请求」,会话文件不变。想持久化得写 CustomMessageEntry。
③ 提前结束必须整批一致
半批执行会留下「有调用没结果」的坏轨迹,所以 terminate 要求 every() 而非 some()。

这三条合起来说明一件事:pi 的扩展不是「插件随便改框架」,而是「在框架划定的语义边界上做加法」。 能力是受限的,但受限让它可预测。

本章学习记录

记录仅保存在当前浏览器。