✷ Harness
写一个 pi 扩展,告诉你 agent 什么时候完成
pi 工作的时候,我总会切到别的窗口。可能是一次漫长的编辑,也可能是一整套测试;反正没什么好盯着的,我就去看点别的。等我回来,才发现任务四分钟前就结束了。反过来的情况更糟:我刚切走,它就因为触发速率限制而停下,过了很久我才发现。
pi 确实会向终端报告自己的状态——工作中、阻塞、完成、失败——但那同样是一种转义序列,目前几乎没有终端实现。我们大多数人用的 Warp、Ghostty 或 iTerm2 都不支持。所以我写了一个小扩展,在一次运行结束时显示真正的桌面通知。
这个扩展叫 pi-bell,用 pi install npm:pi-bell 安装。下面是我会告诉同样想做这件事的人的经验,主要是那些我一开始弄错的地方。

最小的版本
pi 扩展是一个默认导出函数的文件。这个函数接收一个 API 对象,剩下的就是订阅上面的事件。
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
export default function (pi: ExtensionAPI) {
pi.on("agent_start", () => {
// a run began
});
pi.on("agent_settled", (event, ctx) => {
// it's over, and it isn't coming back
});
}
基本结构就是这样。用 pi -e ./my-extension.ts 在单次会话中加载;放进 ~/.pi/agent/extensions/ 就能长期使用;也可以发布到 npm,让别人安装。
我最初选错了事件
agent_end 看起来像是运行结束。其实不是。
pi 中一次会话级运行可以包含多次底层运行。模型报错时,pi 会重试;上下文溢出时,它会压缩上下文然后重试;工作过程中排队的后续消息也会启动另一次运行。agent_end 会在每一次底层运行结束时触发,而不是在你真正等待的那件事结束时触发。
我是吃了亏才发现的。一个 prompt,三条通知,而第三条到来时 agent 还在继续工作。这正是这个扩展最终采用现在这种形式的原因。
你需要的事件是 agent_settled。当 pi 对这次运行不再有自动工作要做时,它才会触发——重试、压缩后的重试和排队消息都处理完之后。它还带有 aborted,告诉你这次运行是不是因为你按了 Escape 而结束。
还有一个细节:agent_before_settle 会在它之前触发,是扩展还能添加上下文、请求再进行一轮的最后机会。如果你只想观察,就用 agent_settled;如果想影响接下来的行为,就用另一个。
一条通知,三种情况
「结束」并不能说明全部情况。一次运行可能是模型完成了工作,也可能是你取消了,或者发生了错误。这些情况应该一眼就能区分,所以通知通过一个简单的状态机选择标题和颜色。
信息藏在最后一条 assistant 消息里。message_end 会在每条消息结束时触发;筛选 role === "assistant",然后读取 stopReason 和 errorMessage。stopReason 的值包括 stop、length、toolUse、error、aborted。保留最后一次看到的值即可——每次重试都会覆盖它,这正是我们需要的。
然后按这个顺序判断:
aborted (event.aborted) → cancelled
stopReason === "error" → failed, with the first line of the message
stopReason === "aborted" → cancelled
stopReason === "length" → done, with a note that it was cut off
everything else → done
顺序很重要。如果一个即将失败的请求还在处理中,你按了 Escape,两个信号可能同时存在。这时如实说是你取消了它,才是正确的。
有一个缺口我没能补上。如果模型还没来得及回复,运行就失败了——比如 API key 错误或 DNS 故障——就没有 assistant 消息,也没有 stopReason 可读,运行便会被报告为完成。我可以根据 ctx.getContextUsage() 或 provider 错误去猜,但在这里,错误地报「失败」比含糊地报「完成」更糟。所以我只在 README 中说明了这个限制,没有继续处理。
终端不是一根透明的管道
这一部分花的时间比 pi 本身还多。
从终端发出桌面通知不是一次系统调用,而是向 stdout 写入几个字节,再由终端决定怎么处理:
ESC ] 777 ; notify ; <title> ; <body> BEL
ESC ] 表示一个 Operating System Command 的开始。777 是 rxvt-unicode 多年前为通知选定的编号,Ghostty、WezTerm、Warp 等后来沿用了它。Kitty 则用自己的 99。这背后并没有什么标准组织。不认识该编号的终端会默默丢弃这段序列,什么也不会显示。
所以该用哪种通道,取决于两件事,而不是一件:pi 是否运行在你面前的机器上,以及中间是否有终端复用器。
| 场景 | 通道 | 原因 |
|---|---|---|
| 本地,无复用器 | OSC 转义序列 | 终端显示通知 |
| 本地,未知终端 | 系统通知 | Apple Terminal 等终端会忽略 OSC |
| 本地 tmux | 系统通知 | 不做配置时 tmux 会吞掉 OSC |
| SSH,无复用器 | OSC | 系统通知会出现在远程机器上 |
| SSH + tmux | 用 DCS 包裹的 OSC | 两层都需要透传 |
SSH 那一行是人们常常弄错的地方。osascript 和 notify-send 在进程运行的机器上执行。通过 SSH 时,那台机器并不是你坐在面前的机器。而转义序列会随着输出流传输,最终到达你面前的终端。
tmux 那一行则是相反的陷阱。tmux 自己负责重绘屏幕,只转发它认识的序列,所以 777 到这里就没了。本地最简单的办法是跳过 OSC,直接调用操作系统 API,不需要配置 tmux。远程则不能这么做,所以必须把序列包起来:
ESC P tmux ; ESC ] 777 ; notify ; ... ESC \ ESC \
这需要在 tmux 配置中设置 set -g allow-passthrough on。这是扩展唯一要求你修改配置的地方。
不同终端使用什么通道
我亲自在 macOS 上端到端测试过 Warp 和 Ghostty。表里的其他终端只是根据各自支持的机制列出的,并不代表我都实际运行过。
| 终端 | 通道 |
|---|---|
| Warp | OSC 777 |
| Ghostty | OSC 777 |
| iTerm2 | OSC 777 |
| WezTerm | OSC 777 |
| rxvt-unicode | OSC 777 |
| kitty | OSC 99 |
| Apple Terminal | 系统通知 |
| Alacritty | 系统通知 |
| VS Code 集成终端 | OSC 777,未经验证 |
| Windows Terminal | PowerShell toast |
| tmux / screen(本地) | 系统通知 |
| SSH 上的 tmux | OSC + DCS 透传 |
README 里也把 VS Code 标为未经验证。我宁愿让表格留个空缺,也不愿让人安装之后纳闷为什么什么都没发生。
然后 macOS 做了一件奇怪的事
即使用对了通道,通知也可能看不见——因为你正看着它。
处于焦点的应用不会显示横幅通知,终端窗口重新回到前台时也会清除自己已经投递的通知。第一次在 Ghostty 中测试时,我什么都没看到,就以为代码坏了。但系统日志说的不是这么回事:
Requested authorization [ didGrant: 1 ]
Adding notification request D528-212C
Added notification request: [ hasError: 0 ]
Removing 1 delivered notifications
通知已经投递,然后三秒后被移除了。只有当你不在终端里时,通知才会保留下来——而这当然正是整个扩展要解决的场景。第一次使用时还必须先回应一次授权提示;在此之前,macOS 会拒绝投递所有通知,而且不会明确告诉你。
测试一个不会说「不」的通道
OSC 没有确认机制。你写出字节,然后只能寄希望于它生效。这让集成无法按通常的方式测试,于是我把它拆开:凡是能做成纯函数的,都通过参数接收输入;只有两个函数会接触外部世界。
decideChannel(env, platform) 接收一个环境对象,而不是读取 process.env,并返回一个描述下一步操作的普通对象。文本格式化和运行状态机也一样。这就是整个设计约束,也是测试套件不需要 mock 库的原因。
测试用 node --test 直接运行 TypeScript 源码。Node 24 会剥离类型,所以不需要构建步骤,也不需要测试框架:
node --test "test/**/*.test.ts"
45 个测试,零依赖。有件事浪费了我十分钟:node --test test/ 会把目录当成模块,导致运行失败。带引号的 glob 才是各个平台都能用的写法。
剩下的两个函数分别写入 stdout 和启动进程。这些我在两个终端里手动测试,用录屏作为证据。
唯一一件与终端无关的事
pi 有四种运行模式:tui、rpc、json、print。在 RPC 模式下,stdout 是一个 JSON 流——而转义序列也会写到同一个 stdout。如果在那里写入通知,就会破坏读取它的客户端所依赖的协议。
所以扩展在写入任何内容之前都会检查 ctx.mode === "tui",在其他模式下保持静默。print 和 JSON 模式的调用方本来就会读取结果;RPC 的调用方通常是编辑器,也会自行显示结果。
我在计划中把这点弄错了,直到对照笔记检查设计时才发现。它只是一个单行判断,却正是那种会变成「你的扩展破坏了我的集成」这种 bug 报告的代码。
发布
pi 包画廊没有提交表单。package.json 里的 pi-package 关键词就是提交方式:
{
"name": "pi-bell",
"keywords": ["pi-package"],
"pi": {
"extensions": ["./src/index.ts"],
"video": "https://raw.githubusercontent.com/beasaltfish/pi-bell/master/demo.mp4"
}
}
pi 字段就是清单:它告诉 pi 入口文件在哪里,可选的 image / video 字段则为画廊提供展示素材。不需要别的东西。
画廊列表本身是定期生成的快照,所以今天发布的包会晚一些才出现在搜索结果中,有时要等一天。但 pi.dev/packages/<name> 的详情页会立即生效,这让延迟看起来比实际更奇怪。
代码分布在五个文件中,大约 300 行,其中约三分之一是终端检测。如果你正在基于 pi 构建东西,只想从这篇文章里记住一件事,那就是:检查你订阅的是哪个事件。agent_end 并不意味着结束。
pi-bell 在 GitHub 和 npm 上都能找到。如果你在表格之外的终端里试用了它,欢迎告诉我结果——这也是让表格变得更准确的方法。
我是 X 上的 @0xasten,我会在那里分享自己构建东西的经历。