Shadowzzh

第11章-扩展系统-设计文档.md

第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 个):

  1. 事件总线是扩展系统的核心机制——不讲这个,后面所有事件都是黑魔法
  2. 两阶段绑定解决"工厂函数时机矛盾"——这是扩展系统最精妙的设计,也是读者最容易困惑的点
  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 行还是压缩过度)。


设计文档自检

  1. 概念空白清单完整吗? ✅ 列出 8 个空白(事件总线、工厂函数、throwing stubs、bindCore、链式中间件、API 门面、Jiti、声明合并),每个都有引入策略
  2. 链路闭环了吗? ✅ 5 条关键链路(rm -rf 拦截、注入时间、结果截断、会话否决、/deploy)全部从触发追踪到最终结果
  3. 叙事起点制造了需求吗? ✅ 用"团队禁 rm -rf"这个真实需求做起点,先让读者感到"我需要这个"
  4. 至少有一个"破"点吗? ✅ 三个建→破→立循环:① Pi 不知道需求怎么扩展 ② 工厂函数时机矛盾 ③ 扩展崩了怎么办
  5. 数据展示够具体吗? ✅ 5 个 Before/After 对照,含字段级变化
  6. 读者画像与叙事策略一致吗? ✅ 读者是有前 9 章基础的开发者,没有插件系统经验——叙事用具体场景而不是抽象模式

跟旧版 / v2 的关键差异

维度 旧版 / v2 设计文档 v3
篇幅 192 / 460 行 800-1000 行(不再压缩)
概念空白 没识别 8 个空白全部有引入策略
链路闭环 全是断的(只列事件名) 5 条完整闭环
叙事起点 "27 行代码" "团队要禁 rm -rf"
认知节奏 平铺直叙 3 个建→破→立循环
主线 实现顺序(生命周期 5 阶段) 读者关心(事件总线怎么工作)