第11章-扩展系统-设计文档.md
章节设计文档:第11章 扩展系统 —— 不改源码给 Agent 加能力
目标读者:看过前 10 章的开发者,理解 Agent Loop / 工具 / 消息 / 事件驱动,但没有插件系统设计经验——"工厂函数"、"throwing stubs"、"事件总线"这些插件系统常见模式对他们来说是新的 目标:读完之后,读者能:① 写一个最简扩展;② 理解 Pi 为什么用"事件总线 + 两阶段绑定"这套设计;③ 能在自己的项目里借鉴这套插件架构思路
1. 本章一句话
读者看完后脑子里的认知变化:
扩展系统不是"魔法注入",而是 Pi 在工作流的 8 个关键点 emit 事件——把"改变行为"的能力通过事件总线交给扩展。这是一种用"约定(事件名 + 返回值协议)"换"灵活(不改源码)"的设计。
对比旧版的坏例子:"这章讲了 28 个事件、注册机制、两阶段绑定"——那是主题列表。
2. 叙事线索
叙事起点类型:设计问题("为什么要搞这个?")
线索:跟着"团队要禁止 rm -rf——给 Pi 改源码吗?"这个真实需求,追踪它从提出到解决的完整旅程。
- 你不想让 Agent 执行
rm -rf(需求产生) - 改 Pi 源码?(成本太高,每次升级要重 merge)
- 用扩展!(解法登场)
- 扩展怎么写?(写一个 .ts 文件)
- Pi 怎么找到它?(目录约定 + Jiti 加载)
- Pi 怎么执行它?(工厂函数 + 两阶段绑定)
- 扩展怎么拦住
rm -rf?(事件总线 + tool_call 事件 + 返回 block) - Agent Loop 怎么响应?(跳过工具执行,返回错误消息)
- 完整闭环(用户看到"禁止递归删除")
这条线索把"扩展能干什么"和"机制怎么运作"自然串起来。
2.5 概念空白清单
| 概念 | 读者是否已知 | 引入策略 | 引入位置 | 使用的类比/解释 |
|---|---|---|---|---|
| 事件总线 | 模糊(前 7 章见过 emit,但没讲扩展怎么挂) | 用对比引入 | §二 讲机制时 | "像广播电台——Pi 在 8 个频道发节目,扩展订阅感兴趣的频道,听到时调自己的处理器" |
| 工厂函数 | 未知 | 用日常类比 | §三 讲生命周期时 | "像新员工入职填表——扩展是新人,工厂函数是入职流程,pi 对象是它领到的工牌(工牌上有些功能现在还不能用)" |
| throwing stubs | 未知 | 用日常类比 | §三 讲两阶段绑定时 | "像工牌上的门禁卡——有些门现在打不开(调用就报警),等入职流程走完(bindCore)才能用" |
| bindCore | 未知 | 一句话定义 | §三 | "把所有 throwing stubs 替换为真实实现的开关函数" |
| 链式中间件 | 模糊(Web 开发者用过 express 中间件) | 用流水线类比 | §二 讲修改型事件时 | "像流水线——第一个工人打磨、第二个上色、第三个包装,前一个人的输出是后一个人的输入" |
| API 门面(Facade) | 模糊 | 一句话定义 | §四 | "暴露给扩展的'窗口'——只展示扩展需要看到的方法,隐藏内部对象" |
| Jiti | 未知 | 备菜策略 | §三 讲加载时 | "运行时 TS 转译器,记忆点:改了重启就生效,不用 build" |
| 声明合并 | 已知(第 6 章讲过) | 直接使用 | §四 简短回顾 | "第 6 章讲过的机制,让扩展拿到全栈类型安全" |
3. 知识点分层
主线(必须讲透的,3 个):
- 事件总线是扩展系统的核心机制——不讲这个,后面所有事件都是黑魔法
- 两阶段绑定解决"工厂函数时机矛盾"——这是扩展系统最精妙的设计,也是读者最容易困惑的点
- 四种事件模式(通知/取消/修改/短路)——决定了扩展能用什么方式介入
支线(需要提及但不展开):
- 目录约定三条规则 → 用例子带过,不深挖边界
- Jiti 双模式(alias vs virtualModules)→ 一段话带过,不展开 Bun 编译原理
- wrapper.ts 工具包装 → 一段话带过,链接回第 5 章
补充(可选的,放附录或不讲):
- 28 个事件的完整清单 → 放文末表格,正文只讲 8 个介入点的代表事件
- API 门面的所有方法列表 → 放文末表格,正文只讲三层划分的动机
3.5 方法论提炼
| 方法名 | 来源 | 复用指引 |
|---|---|---|
| 事件总线暴露关键点 | Pi 在 Agent 工作流的 8 个关键点 emit 事件 | 设计插件系统时,识别工作流的关键节点,emit 统一事件。比给每个点写专门 hook 函数扩展性强 |
| throwing stubs + bindCore 分阶段 | 注册阶段抛错、运行阶段切换为真实实现 | 插件加载时核心还没就绪?用这个模式分离"声明意图"和"执行操作" |
| API 门面 + 最小权限 | 三层 API(ExtensionAPI / Context / CommandContext) | 给插件不同的门面对象——事件处理时只读,命令处理时可写。永远不暴露内部对象 |
| 错误隔离 | 所有事件处理器都被 try/catch 包裹 | 一个插件崩了不能拖垮核心——错误编码为事件,不打断流程 |
4. 认知旅程
第一个循环(建→破→立):扩展能干什么 + 怎么做到
阶段 1(建):开篇展示 6 个真实需求场景——禁止 rm -rf、用本地 Ollama、SQL 工具、自动翻译、注入时间、/deploy 命令。让读者感到"扩展很强大,能改变 Agent 的方方面面" → 读者感受:"哇,扩展能干这么多事,那它到底怎么工作的?"
阶段 2(破):但 Pi 是开源项目,Pi 不可能预先知道你团队要禁 rm -rf。如果 Pi 没有为这个需求写代码,扩展怎么"凭空"加上这个能力?这是一个看似矛盾的问题 → 读者感受:"对啊,Pi 不知道我的需求,怎么扩展?"
阶段 3(立):答案是事件总线——Pi 不需要预先知道你的需求,它只负责在 8 个工作流关键点 emit 事件("嘿,我要执行工具了,要不要拦?")。你写扩展回答"要拦"就行。这是一种用"约定"(事件名 + 返回值协议)换"灵活"(不改源码)的设计 → 读者感受:"原来如此——Pi 不是为每个需求写代码,而是把'决定权'通过事件交给扩展"
第二个循环(建→破→立):扩展怎么写 + 时机矛盾
阶段 1(建):扩展就是一个 .ts 文件,导出一个工厂函数。在工厂函数里
pi.on(...)注册处理器,看起来很简单 → 读者感受:"就这?挺简单的"阶段 2(破):但工厂函数是在 Pi 启动加载阶段执行的——那时 Agent 还不存在、SessionManager 还没创建、Agent Loop 还没启动。如果你在工厂函数里调
pi.sendMessage("init"),会发生什么?消息发给谁?这是一个时机矛盾 → 读者感受:"对啊,工厂函数这么早执行,运行时的操作怎么办?"阶段 3(立):Pi 的解法是两阶段绑定——工厂函数执行时(注册阶段),
pi对象上的操作型方法是 throwing stubs(调用就抛错);Agent 启动后调用bindCore(),把所有 stubs 替换为真实实现。扩展代码无感知这个差异——你在工厂函数里调会抛错(合理,因为这时调用没意义),在事件处理器里调就是真实操作 → 读者感受:"妙啊——一个 pi 对象两种状态,自动适配阶段"
第三个循环(建→破→立):扩展崩了怎么办
阶段 1(建):扩展是第三方代码,写完了就能拦 Agent 行为,能力很大 → 读者感受:"扩展这么强,那万一写错了呢?"
阶段 2(破):如果扩展的事件处理器抛了异常,会不会拖垮整个 Agent?如果任何扩展都能 forkSession、switchSession、reload,一个恶意扩展会不会劫持 Agent? → 读者感受:"对啊,第三方代码不能完全信任"
阶段 3(立):两个机制保护:① 错误隔离——所有处理器被 try/catch 包裹,扩展崩了只丢弃自己的修改,不影响核心;② API 门面三层——ExtensionAPI 给注册能力、Context 给只读查询、CommandContext 给特权操作。普通事件处理器拿不到 forkSession 这种危险方法 → 读者感受:"考虑得真周到——错误隔离 + 最小权限"
收尾
总结三大设计(事件总线 / 两阶段绑定 / 错误隔离 + 门面),提炼可迁移的方法论,留悬念给下一章(测试模式)
4.5 链路闭环清单
这是 v2 文档最大的漏洞——旧版链路全是断的。新版每个事件必须从触发追踪到最终结果。
| 链路 | 触发端 | 中转 | 消费端 | 最终结果 | 链路闭环? |
|---|---|---|---|---|---|
| rm -rf 拦截 | 用户输入包含 rm -rf 的工具调用请求 |
Agent Loop 准备调 bash 工具前 → runner.emit("tool_call") |
扩展处理器收到 event,识别危险命令,返回 {block: true, reason} |
Agent Loop 跳过工具执行,返回错误消息给 LLM,LLM 知道命令被拦 | ✅ 必须完整讲 |
| 注入当前时间 | Agent Loop 准备调用 LLM 前 | 构建好 messages → runner.emitContext(messages) |
扩展处理器 push 一条 user message,返回新 messages | 新 messages 发给 LLM,LLM 看到时间信息 | ✅ 必须完整讲 |
| 工具结果截断 | 工具执行完产生长结果 | runner.emitToolResult(event) |
扩展 A 截断 → 扩展 B 加元数据 → 返回最终 result | Agent Loop 把最终 result 包成 ToolResultMessage 加入 messages | ✅ 用链式传递讲 |
| 会话切换否决 | 用户触发切换会话 | runner.emit("session_before_switch") |
扩展弹确认对话框,用户选取消,返回 {cancel: true} |
Agent 取消切换,留在当前会话 | ✅ 用一票否决讲 |
| /deploy 命令 | 用户输入 /deploy |
斜杠命令路由 → 扩展的 command handler | 处理器拿到 CommandContext,调用 exec 执行部署脚本 | 部署完成,结果通过 sendMessage 回报给 Agent | ✅ 用注册型能力讲 |
5. 数据展示清单
| 序号 | 展示什么 | Before | After | 代码来源 |
|---|---|---|---|---|
| 1 | Extension 对象状态变化 | factory 执行前:7 个空 Map | factory 执行后:tools Map 多一项 | loader.ts:380-390 |
| 2 | runtime.sendMessage 变化 | 注册阶段:() => { throw Error(...) } |
bindCore 后:actions.sendMessage 真实实现 |
loader.ts:160 + runner.ts:307-378 |
| 3 | tool_call 事件的 event 对象 | 原始 event:{toolName: "bash", input: {command: "rm -rf /"}} |
扩展返回:{block: true, reason: "禁止"} |
runner.ts:862-883 |
| 4 | messages 数组被注入 | 注入前:3 条消息 | 注入后:4 条(多一条时间信息) | runner.ts:914-944 |
| 5 | tool_result 链式修改 | 原始:8000 字符 | 扩展 A 截断:500 字符 | 扩展 B 加 details:500 字符 + details |
6. 转折点设计
转折点 1:读者的第一个困惑——"Pi 不知道我的需求怎么扩展?"
- 触发时机:讲完 6 个真实场景之后
- 回答方式:用第一个建→破→立循环解决——事件总线是答案
转折点 2:读者的第二个困惑——"工厂函数这么早执行,运行时操作怎么办?"
- 触发时机:讲完扩展怎么写之后
- 回答方式:用第二个建→破→立循环——两阶段绑定
转折点 3:读者的潜在质疑——"为什么搞这么复杂?直接 if-else 不行吗?"
- 触发时机:讲完四种事件模式后
- 回答方式:用反例——如果用 if-else,每个新需求都要改 Pi 核心;事件总线让 Pi 核心稳定,扩展层自由演化
转折点 4:读者的担忧——"扩展崩了会拖垮 Agent 吗?"
- 触发时机:讲完 API 门面后
- 回答方式:用第三个建→破→立循环——错误隔离
7. 与前文的衔接
上一章留下的悬念:第 10 章会话管理提到"扩展可以拦截会话操作"(session_before_switch 等),但没展开机制。第 7 章事件驱动讲了 emit/on 的基础,但没讲扩展系统怎么挂上去。
本章开头怎么接(2-3 句话):
前 9 章 Pi 的核心机制都讲完了。你可能注意到一个现象——这些核心都很简洁(不到 2000 行),但 Pi 的实际能力远超核心代码的覆盖范围。比如禁止 rm -rf、用本地 Ollama、自定义 SQL 工具——这些 Pi 核心代码里没有。它们从哪儿来?答案是扩展系统。
本章结尾留什么悬念:
扩展系统让 Pi 有了"不改源码加能力"的机制。但怎么测试这些能力?扩展注册了 tool_call 处理器返回
{block: true},怎么验证它真的拦住了?传统测试方法不适用——下一章测试模式回答这个问题。
8. 关键代码路径
| 文件 | 关键行号 | 代码角色 | 证明什么观点 | 在认知旅程中的位置 |
|---|---|---|---|---|
extensions/types.ts |
L993-1023 | 28 个事件类型联合类型 | "8 个介入点"的源码依据 | 第一个循环-立 |
extensions/runner.ts |
L736-768 | emit 方法(带 try/catch) |
事件总线 + 错误隔离的源码依据 | 第一个循环-立 + 第三个循环-立 |
extensions/runner.ts |
L862-883 | tool_call 事件处理 |
"返回 block 阻止执行"的源码依据 | 链路闭环:rm -rf 拦截 |
extensions/runner.ts |
L812-860 | tool_result 链式处理 |
"修改型事件链式传递"的源码依据 | 链路闭环:结果截断 |
extensions/loader.ts |
L160-195 | createExtensionRuntime 的 throwing stubs |
"注册阶段操作型方法抛错"的源码依据 | 第二个循环-破 |
extensions/runner.ts |
L307-378 | bindCore |
"stub 替换为真实实现"的源码依据 | 第二个循环-立 |
extensions/runner.ts |
L573-633 | createContext 只读门面 |
"API 门面 + 最小权限"的源码依据 | 第三个循环-立 |
extensions/types.ts |
L298-327 | ExtensionContext 类型 |
"三层 API"的源码依据 | 第三个循环-立 |
examples/extensions/confirm-destructive.ts |
- | 真实取消型扩展示例 | 一票否决的真实用法 | 链路闭环:会话切换否决 |
9. 篇幅规划
| 部分 | 占比 | 内容 |
|---|---|---|
| §一 背景:6 个真实需求场景 | 10% | 制造"我需要扩展系统"的需求 |
| §二 第一个循环:事件总线是核心机制 | 25% | 8 个介入点 + 4 种事件模式 + rm -rf 完整闭环 |
| §三 第二个循环:两阶段绑定 | 25% | 工厂函数时机矛盾 + throwing stubs + bindCore |
| §四 第三个循环:错误隔离 + API 门面 | 20% | try/catch + 三层 API + 最小权限 |
| §五 扩展从写到生效的旅程(简化版) | 12% | 目录约定 + Jiti + 工具包装 |
| §六 总结 + 方法论提炼 | 5% | 三大设计 + 可迁移思路 |
| §七 下一站衔接 | 3% | 留悬念给测试章 |
预计总篇幅:800-1000 行(旧版 192 行太薄,v2 的 460 行还是压缩过度)。
设计文档自检
- 概念空白清单完整吗? ✅ 列出 8 个空白(事件总线、工厂函数、throwing stubs、bindCore、链式中间件、API 门面、Jiti、声明合并),每个都有引入策略
- 链路闭环了吗? ✅ 5 条关键链路(rm -rf 拦截、注入时间、结果截断、会话否决、/deploy)全部从触发追踪到最终结果
- 叙事起点制造了需求吗? ✅ 用"团队禁 rm -rf"这个真实需求做起点,先让读者感到"我需要这个"
- 至少有一个"破"点吗? ✅ 三个建→破→立循环:① Pi 不知道需求怎么扩展 ② 工厂函数时机矛盾 ③ 扩展崩了怎么办
- 数据展示够具体吗? ✅ 5 个 Before/After 对照,含字段级变化
- 读者画像与叙事策略一致吗? ✅ 读者是有前 9 章基础的开发者,没有插件系统经验——叙事用具体场景而不是抽象模式
跟旧版 / v2 的关键差异
| 维度 | 旧版 / v2 | 设计文档 v3 |
|---|---|---|
| 篇幅 | 192 / 460 行 | 800-1000 行(不再压缩) |
| 概念空白 | 没识别 | 8 个空白全部有引入策略 |
| 链路闭环 | 全是断的(只列事件名) | 5 条完整闭环 |
| 叙事起点 | "27 行代码" | "团队要禁 rm -rf" |
| 认知节奏 | 平铺直叙 | 3 个建→破→立循环 |
| 主线 | 实现顺序(生命周期 5 阶段) | 读者关心(事件总线怎么工作) |