phi 为什么要自造 PXB 二进制扩展协议?16字节帧头+标签字段实现比 JSON Lines 快 10 倍的完整指南
phi 为什么要自造 PXB 二进制扩展协议?16字节帧头+标签字段实现比 JSON Lines 快 10 倍的完整指南
phi 是一个主打极速体验的终端 coding agent,其扩展系统(Extensions)基于自研的 PXB(Phi eXtension Binary)二进制协议在子进程间通信。相比常见的 JSON Lines 方案,PXB 用 16 字节固定帧头加标签字段(tagged fields)编码,Hello 消息编解码仅需约 0.11 µs,比同类 JSON Lines 实现的约 1.2 µs 快了约 10 倍。本文将拆解 phi 自造这套协议的设计动机、帧结构细节与演进规则,帮助扩展开发者理解其背后的取舍。
一个真实的痛点:扩展为什么不能用 JSON Lines?
phi 的扩展是原生二进制子进程,通过 stdin/stdout 与宿主进程交换消息:订阅工具/会话事件、注册 LLM 工具和斜杠命令。每个 agent 轮次中,工具调用拦截(tool_call)、事件通知、RPC 应答等消息会高频穿过这条管道。
早期方案(以及业界多数 CLI 插件系统)用"一行一个 JSON 对象"(JSON Lines)来分隔消息,直观但代价明显:
- 要扫描分隔符:接收端必须逐字节找换行符、判断对象边界;
- 字符串键名反复编码:
"tool_name": "bash"这类键名在每条消息里占字节、占 CPU; - 解析开销大:官方基准中,Go 的 JSON Lines 实现每次编解码约 1.2 µs、产生 15 次内存分配。
而 agent 的热路径上,每次工具调用都要经过"扩展前置拦截 → 权限门 → 执行 → 后置事件"的完整链路(见 doc/extensions.md 的事件链),序列化成本会被成倍放大。
PXB 帧结构:16 字节帧头 + 标签字段
PXB 的完整设计文档在 ext/go/pxb/doc.go,核心就两层结构:
帧头:16 字节定长,小端编码
┌──────── header(16 字节,little-endian)────────┐
│ magic[4]="PXB\x01" │ typ u16 │ flags u16 │ id u32 │
│ payload_len u32 │
└──────────────────────────────────────────────────┘
│ payload: 标签字段序列 │
| 字段 | 类型 | 作用 |
|---|---|---|
magic[4] |
PXB\x01 |
魔数 + 版本字节,防止串流 |
typ |
u16 | 帧类型:Ext→Host 用 1–99,Host→Ext 用 100–199 |
flags |
u16 | 标志位(如 FlagHasID 表示 id 有效) |
id |
u32 | RPC 关联 ID,请求/响应按 id 配对 |
payload_len |
u32 | 载荷长度,接收方"按长度读完即一帧" |
定长帧头带来两个关键性质:读取器永远不需要扫描分隔符;遇到不认识的帧类型,直接按 payload_len 跳过整个帧即可——这正是协议前向兼容的基石。编解码实现见 ext/go/pxb/codec.go 中的 WriteFrame / ReadFrame,帧类型常量定义在 ext/go/pxb/types.go。
载荷:protobuf 风格的标签字段
载荷不是 JSON 对象,而是一段定宽标签字段序列:
tag u16 | kind u8 | value
kind 1(WireU64)→ 8 字节小端整数(u16/u32/bool/事件码都统一用 8 字节承载);kind 2(WireBytes)→ u32 长度 + 字节串。
只有这两种 kind,所以任何未知字段都能靠 kind 安全跳过,不需要共享 schema。空字符串/空字节串编码时直接省略,省略即零值。字段编解码核心在 ext/go/pxb/fields.go。
以握手消息 Hello 为例,schema 即"线格式唯一事实来源"(ext/go/pxb/schema.go):
type Hello struct {
Name string `pxb:"1"`
Version string `pxb:"2"`
Caps uint32 `pxb:"3"`
Protocol uint16 `pxb:"4"`
}
每个字段用 pxb:"<tag>" 标注标签号,make generate 由代码生成器(ext/go/internal/pxbgen/)产出精确计算长度的编码器 ext/go/pxb/msg_gen.go——编码器预分配精确空间,单次分配写完整包,无扩容、无垃圾回收压力。
性能实测:10 倍差距来自协议本身
官方在 Apple Silicon(release、单线程)上给出的编解码基准(完整表格见 README.md 的 Extensions 章节):
| 实现 | Hello 编+解码 | 帧写+读(内存内) | 分配次数 |
|---|---|---|---|
Rust PXB(phi-ext) |
~0.12 µs | ~0.06 µs | — |
| Go PXB(ext/go/pxb) | ~0.11 µs | ~0.05 µs | 3 / 次 |
| Go JSON Lines | ~1.2 µs | — | 15 / 次 |
~10 倍的差距来自协议设计(固定帧头 + 标签字段)而非语言——Rust 和 Go 在同一套编解码工作上差距在噪声范围内。Go 侧基准见 ext/go/pxb/bench_test.go,Rust 侧可用 cargo run --release --example bench(ext/rust/examples/bench.rs)自行复测。
PXB 的快速只是"锦上添花":官方也诚实指出,真实扩展延迟主要由进程启动和管道 RTT 主导。但它让 phi 整体"快"的名声更完整——首帧 0.031s、常驻内存约 21 MB,都显著领先同类:
协议演进规则:让宿主与扩展各自独立升级
自造协议最大的风险是"版本地狱"。PXB 在 ext/go/pxb/doc.go 中写死了 5 条演进规则:
- 新增字段:分配新 tag(≥1),永不复用旧 tag;
- 新增生命周期事件:分配新
Ev*事件码;旧扩展没订阅就永远看不到它; - 新增帧类型:Ext→Host 取 1–99 区间、Host→Ext 取 100–199 区间的新号;不认识的帧对端按长度跳过;
- 不兼容的重命名/语义破坏:提升
ProtocolVersion,宿主直接拒绝不支持的版本(Hello/HelloAck握手时协商); - 实验性 tag 用 128+,且必须保持可跳过。
tag 命名空间同样是规约:1–63 为消息自定义字段,64–127 保留(跨切面),128+ 实验/私有(见 ext/go/pxb/schema.go 头部注释)。这套规则让宿主与扩展二进制可以独立升级,不需要共享 JSON schema、也不需要同步发版。
多语言字节级兼容:同一协议,三套 SDK
PXB 的价值不止快,还在于跨语言一致性。仓库内置三套作者 SDK:
| 路径 | 语言 | 形态 |
|---|---|---|
| ext/go/ | Go | 模块 github.com/pulseaiclub/phi/ext/go |
| ext/rust | Rust | crate phi-ext(serde + tokio) |
| ext/ts | TypeScript | npm @pulseaiclub/phi-ext(零依赖) |
三者共享同一套线协议,通过 golden fixture 保证字节级一致:Go 侧用 UPDATE_GOLDEN=1 go test 生成 testdata/*.bin(ext/go/pxb/golden_test.go),Rust/TS 的测试套件直接解码这些二进制夹具做往返校验(ext/rust/tests/pxb_test.rs、ext/ts/test/golden.test.ts)。这意味着用 Rust 写的扩展和 Go 宿主之间的每一个字节都是可预测、可回归测试的。
宿主侧的进程管理(发现、启动、热重载、Fiber 状态机)则分层在 internal/extension/ 下,架构说明见 doc/extension-architecture.md;用户侧管理入口是 TUI 的 Ctrl+K → extensions,详见 doc/extension-management-guide.md。
协议约束:payload 上限与安全边界
- 单帧 payload 默认上限 16 MiB(
MaxPayload),双方通过CapLargeFrames能力位协商后可放宽至 256 MiB(MaxStreamPayload,见 ext/go/pxb/types.go); - 超大的工具结果会返回显式错误,官方建议"大输出落盘,只回摘要 + 文件路径";
- 扩展进程继承你的权限,只建议安装可信来源的扩展。
总结:自造协议买到了什么?
回顾 phi 自造 PXB 的决策,收益清单非常具体:
- ✅ 快:定长帧头免扫描分隔符,标签字段免字符串键名,编解码 ~0.11 µs / 3 次分配;
- ✅ 稳:按长度跳帧 + 按 kind 跳字段,新消息对旧对端天然透明;
- ✅ 省:单次分配预分配精确空间,热路径无 GC 抖动;
- ✅ 跨语言:Go/Rust/TS 三套 SDK 由 golden fixture 保证字节级一致;
- ✅ 可演进:tag/事件码只增不复用,不兼容变更靠版本号一刀切。
如果你正准备给 phi 写第一个扩展,建议按 doc/extensions.md 的 Authoring 章节走一遍 Go SDK 流程,再回头读 ext/go/pxb/doc.go 的帧注释——你会发现所谓"10 倍速"的全部秘密,其实就写在那 16 个字节和两行 kind 定义里。



