阶段二 · 状态与边界
事件驱动与扩展 —— 让界面看得见,让扩展插得上手
Pi 最核心的设计思路是"事件即契约":Agent 每走一步就发一个事件,终端界面、脚本输出、协议模式、你自己写的前端,全都消费同一串事件,谁都不去翻 Agent 的内部状态。扩展则通过同一套事件,在合适的时机插手。这一章讲清两套监听方式的区别、事件怎么分组,以及 1.x 新增的"边界时刻"。
具体回答三个问题:界面凭什么看得见?扩展凭什么插手?为什么你的钩子写了却不生效?
学习目标
- 理解"事件即契约"为什么能让界面和核心解耦。
- 分清两种监听方式:只观察的,和能改结果的。
- 知道扩展可以注册什么、在哪些时刻被调用。
- 理解"一轮结束"和"运行结算"这两个边界时刻为什么重要。
- 避开几个最常见的事件名与返回值误区。
一、问题:界面怎么知道 Agent 在干什么
Agent 正在跑循环:请求模型、执行工具、填回结果。终端界面要实时显示进度,脚本要拿到结构化输出,协议模式要把事件转发给别的进程。这些"观察者"凭什么知道内部发生了什么?
最笨的办法:每个观察者都去读 Agent 的内部状态。那样界面就和核心绑死了,改一处界面得动核心。
Pi 的答案是事件流:核心每走一步发一个事件,观察者订阅。核心不知道也不关心谁在听,它只负责把"发生了什么"说出去。
事件按生命周期分四组:
| 分组 | 什么时候发 | 典型用途 |
|---|---|---|
| 运行 | 一次完整运行开始 / 结束 | 计总账、清理、判定最终失败 |
| 轮次 | 一轮开始 / 结束 | 刷新进度、记录每轮摘要 |
| 消息 | 一条消息开始 / 流式更新 / 结束 | 打字机效果、逐条渲染 |
| 工具 | 一次工具执行开始 / 进度 / 结束 | 显示命令在跑、输出在涨 |
这四个形态的界面——交互终端、一次性输出、结构化输出、进程间协议——都是这些事件的消费者。这就是"核心可移植"的机制保证:界面怎么变,核心不用改。
二、两种监听:只看,还是能改
Pi 有两套并行的监听机制,共享同一批事件源,但分水岭很明确:你的返回值算不算数。
| 维度 | 只观察的订阅 | 扩展的钩子 |
|---|---|---|
| 用途 | 日志、界面、统计 | 拦截、改写、决策 |
| 返回值 | 被忽略,没有回传通道 | 参与决策(拦下、替换、追加记录…) |
| 谁在用 | 宿主程序、SDK 使用者 | TypeScript 扩展 |
只学一套,一定会遇到"代码写了却静默不生效":在只观察的订阅里想拦一次工具调用,是做不到的——它拿不到决策权。要拦必须用扩展钩子。
有一个细节容易说错:观察型订阅的回调是同步调用、返回值被忽略,但底层 Agent 会按订阅顺序等回调跑完,一次运行的"结算"也要等结束事件的监听者跑完。所以"不等"指的是"不采用你的返回值",不是"不关心你跑完没有"。
三、扩展能做什么
一个扩展就是一个函数,接收一套注册接口,可以在里面登记:工具、斜杠命令、快捷键、界面组件、模型服务商、事件处理函数。
要纠正一句老话:"高级能力都不内置"已经不准确了。MCP(接外部工具服务器)和 code mode(让模型写脚本调工具)从 1.0 前后就作为内置扩展随包发布——它们仍然是用扩展写法注入的,但不再是"要自己装"的东西。真正没有内置实现的,是通用子代理与计划模式。
扩展在四种形态下都会加载,但终端界面专属的能力(弹自定义面板、接管终端输入)在协议模式下会降级。
扩展跑在你的进程里
这一点必须说清:扩展是加载进 Pi 进程的代码,拥有和 Pi 一样的系统权限。装一个扩展,接近执行一段本地代码。评审第三方扩展时,请按"它能不能读我的密钥、能不能发网络请求"来审,而不是按"它是不是一个插件"来审。
四、新版本新增:两个"边界时刻"
早期的扩展只能在"消息"和"工具"这个粒度上插手。之后的版本增加了两个可行动的边界,让扩展能在"这一轮结束、下一次开始"之间做决定:
- 一轮结束:助手回复和全部工具结果都落地之后、宣布这一轮结束之前。扩展可以在这里追加结构化的记录(自定义记录、上下文编辑、压缩草案),并决定要不要再跑一轮。
- 运行结算前:一次运行即将彻底收尾之前的最后一道钩子。它的作用类似,但时机更靠后——所有自动重试、压缩、排队续跑都处理完之后。
还有一个状态事件值得知道:结算完成事件带一个"是不是被取消"的标记。集成方判断"真的结束了"要看它,而不是"运行结束"事件——后者之后还可能发生自动重试、压缩、排队续跑。
此外还有一条更彻底的改写通道:带系统消息的上下文钩子。它在普通上下文钩子之后运行,拿到包含系统消息在内的完整对话,返回值原样发给模型服务商——比"改写本轮系统提示词"更靠底层。
五、几个最容易记错的地方
- 关闭事件的名字:是"会话关闭",不是"会话结束"。它的原因有几种:退出、重载、新建、恢复、分叉。
- 没有"设置变更"事件:改设置不会广播,不要指望能订阅它。
- 工具输入改写:是在事件对象上原地改,不是返回一个"修改后的输入"。返回一个不存在的字段不会有任何效果。
- 拦截工具调用:返回"拦下"加一个原因;被拦的调用不执行,但会回填一条错误结果。
- 压缩前定制:用压缩前钩子,可以取消,也可以自己给摘要。
- 运行开始前钩子有两种触发来源:用户提示词,和扩展自己发起的消息。只关心用户输入的处理器,必须判断一下来源,否则自定义消息触发的运行也会走进来。
当前 Pi 行为
- 核心发出的界面事件有九种,按运行 / 轮次 / 消息 / 工具四组分布。
- 扩展可监听的事件有三十余种,并且与界面事件同名重叠:两边都有"运行开始""轮次结束",但携带的信息不同(扩展侧的轮次结束多带轮次序号与记录编号)。写扩展时看的是扩展那份清单。
- 两套清单都不做运行时校验:事件名写错、返回值形状不对,通常不会立刻报错,只是安静地不生效。类型系统是唯一的防线。
- 扩展在交互、一次性、结构化、协议四种形态下都加载,终端专属能力在协议下降级。
- 只有观察型订阅没有决策权;要改变行为必须用扩展钩子。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 运行 / 轮次 / 消息 / 工具事件 | agent_* / turn_* / message_* / tool_execution_* |
| 只观察的订阅 | subscribe |
| 扩展钩子注册 | pi.on(...) |
| 会话关闭 | session_shutdown |
| 运行结算 / 结算完成 | agent_before_settle / agent_settled |
| 带系统消息的上下文钩子 | context_with_system |
| 压缩前钩子 | session_before_compact |
源码位置
packages/agent/src/types.ts:核心发出的界面事件。packages/coding-agent/src/core/extensions/types.ts:扩展事件与返回值约定。packages/coding-agent/docs/extensions.md:一手文档,事件表与选型表都在里面。
失败与边界实验
事件系统的三个经典故障,理论上都成立,但课程测试目前只覆盖第一个——另外两个靠类型与文档约束:
- 订阅者抛异常。 一个界面崩溃不能拖垮 Agent:事件总线对每个处理函数做异常隔离,失败只属于那一个订阅者。教学模型有对应用例。
- 返回值被忽略。 钩子返回什么是有约定的:返回一个"系统提示词"就替换本轮提示词,返回别的形状等于没改。运行时不会报错——这是"事件即契约"的代价:契约靠类型和文档维持。
- 不认识的事件类型。 新版本加了事件,旧消费者必须能忽略而不是崩溃。判别联合加默认分支是 TypeScript 侧的纪律;结构化输出侧则要求消费者按类型分发、对未知值宽容。
python3 -m learn_pi_lab lab events
python3 -m unittest tests.test_07_extension_events -v
在 Pi 里怎么操作
- 安装扩展:从 npm 或 git 装,查看已装列表,移除,或者临时加载一个文件。
- 装完可以查看它注册了哪些工具与命令。
- MCP 服务器有独立的一套命令,也可以用会话内的斜杠命令查看连接状态。
社区扩展参考
Pi 生态有数千个包,生态地图见 awesome-pi。社区里比较有代表性的方向:
- 子代理:把"再开一个 Agent"包装成工具调用。
- 记忆:跨会话的持久记忆、会话搜索、密钥扫描。
- 远程接入:把 Pi 接到手机、聊天工具。
- 网页访问:给模型一个能降级重试的取网页工具。
- 上下文剪枝:按工具调用树删掉无关历史。
社区项目的 star 数会变,本课程不复述具体数字。安装前先读源码,确认它要什么权限、会访问什么网络。
Python 实验
extension_events.py 是课程自己的事件总线,一百多行,把事件系统的三条纪律写得明明白白:
snapshot = _freeze_value(payload) # ① 先冻结再广播
handlers = tuple(self._handlers.get(event, ()))
for handler_index, (_rid, callback) in enumerate(handlers):
try:
outcomes.append(EventOutcome(status="ok", value=callback(snapshot)))
except Exception as error: # ② 异常隔离成数据
outcomes.append(EventOutcome(status="error", error=f"{type(error).__name__}: {error}"))
三条纪律:
- 先冻结再广播:处理函数拿到的是不可变快照,谁也没法通过改负载影响后面的处理函数。
- 捕获普通异常,不捕获系统退出:
KeyboardInterrupt与SystemExit有意放行——用户按 Ctrl+C 必须能立刻停,事件系统无权吞掉它。 - 异常是结果,不是中断:一个处理函数崩了,后面的照常跑,调用方拿到一份完整的结果列表自行决定怎么呈现。
它还实现了幂等退订:拿到的订阅凭证调用一次就失效,重复调用也不会误删别人的订阅。这看着琐碎,但在"界面反复挂载卸载"的场景里是刚需。
它不是 Pi 扩展接口的 Python 绑定——Pi 扩展是 TypeScript 代码。但它和 Pi 的观察型订阅是同一个语义模型。
python3 -m learn_pi_lab lab events
这一模块的核心代码在核心代码导览 · 事件总线有逐段解读。
验证方式
python3 -m unittest tests.test_07_extension_events -v
边界与安全
- 事件名、携带的信息、返回值约定,都以基线版本的文档为准,不要从旧示例复制。
- 扩展应校验所有外部输入、限制自己能做的操作,把异常变成明确的用户反馈或日志。
- 扩展在 Pi 进程内运行,权限与 Pi 相同——这是最大的风险面,也是它强大的原因。
- 社区项目会随版本演进,本课程的 Python 实验不依赖、也不绑定任何 Pi 扩展。
自测三问
- 在只观察的订阅里拦截工具调用,为什么不会生效?
- 为什么"运行结束"不等于"真的结束了"?
- 扩展的默认导出函数可以是异步的吗?这对注册时机有什么影响?
回顾
- 事件是契约:核心发事件、界面消费,核心不知道谁在听。
- 两种监听:只观察的拿不到决策权;能改行为的必须走扩展钩子。
- 两套清单同名重叠:界面事件九种,扩展事件三十余种。
- 两个边界时刻:一轮结束、运行结算前,可以在那里落盘记录、决定续跑。
- 事件名容易记错:会话关闭不是会话结束;运行开始前钩子要看来源。
窗口会满、对话会太长——下一章上下文压缩讲如何在有限窗口里装下无限对话。