phi 为什么要自造 PXB 二进制扩展协议?16字节帧头+标签字段实现比 JSON Lines 快 10 倍的完整指南

原创2026-10-31 09:12:531,351 阅读

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 自造这套协议的设计动机、帧结构细节与演进规则,帮助扩展开发者理解其背后的取舍。

phi 终端 coding agent 主界面

一个真实的痛点:扩展为什么不能用 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)自行复测。

phi 与其他 coding agent 首帧耗时对比

PXB 的快速只是"锦上添花":官方也诚实指出,真实扩展延迟主要由进程启动和管道 RTT 主导。但它让 phi 整体"快"的名声更完整——首帧 0.031s、常驻内存约 21 MB,都显著领先同类:

phi 与其他 coding agent 内存占用对比

协议演进规则:让宿主与扩展各自独立升级

自造协议最大的风险是"版本地狱"。PXB 在 ext/go/pxb/doc.go 中写死了 5 条演进规则:

  1. 新增字段:分配新 tag(≥1),永不复用旧 tag;
  2. 新增生命周期事件:分配新 Ev* 事件码;旧扩展没订阅就永远看不到它;
  3. 新增帧类型:Ext→Host 取 1–99 区间、Host→Ext 取 100–199 区间的新号;不认识的帧对端按长度跳过;
  4. 不兼容的重命名/语义破坏:提升 ProtocolVersion,宿主直接拒绝不支持的版本(Hello/HelloAck 握手时协商);
  5. 实验性 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。

phi agent 会话中扩展与工具协作的终端画面

协议约束: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 定义里。

登录后查看全文
phi