oh-my-pi 协作会话线缆协议:深入解析 `@oh-my-pi/pi-wire` 共享 TypeScript 契约
oh-my-pi 协作会话线缆协议:深入解析 @oh-my-pi/pi-wire 共享 TypeScript 契约
导读
@oh-my-pi/pi-wire 是 oh-my-pi 项目中主持端 CLI(@oh-my-pi/pi-coding-agent)与浏览器访客端(@oh-my-pi/collab-web)之间协作实时会话(collab live session)所共享的 TypeScript 线缆契约包。该包只包含 JSON 安全(JSON-safe)的协议形状与常量,没有任何运行时依赖,是协作模式中消息、转录条目、Agent 事件、加密封帧与中继常量的事实标准。读完本文,你将掌握 pi-wire 的全部导出面、协议边界职责划分、帧与信封的二进制布局、协议版本演进规则,以及它在 host / guest / relay 三端代码中如何被实际消费。
一、包定位:只定义契约,不实现逻辑
pi-wire 的设计哲学在 packages/wire/README.md 中一句话点透:它不负责编码、解码、校验、加密或路由帧,只定义这些边界处所使用的共享契约。这一点从 packages/wire/src/index.ts 的头部注释也能看到——包内全部是 interface、type 联合与 const 常量,没有任何传输实现。
其消费方明确而克制:
- Host(主持端):
@oh-my-pi/pi-coding-agent,在 packages/coding-agent/src/collab/protocol.ts 中围绕pi-wire的类型定义宿主角色的帧语法(CollabFrame)、信封打包/解包(packEnvelope/unpackEnvelope)与协作链接的格式化/解析; - Guest(访客端):浏览器端
@oh-my-pi/collab-web,直接导入本包类型而非依赖 coding-agent 运行时;类型一致性由 packages/coding-agent/test/collab/web-wire.types.ts 以纯类型方式断言。
pi-wire 作为中间契约层,让浏览器端与测试端不必引入庞大的 Agent 运行时,即可获得与宿主完全一致的协议视图。这是本包在架构上的首要价值。
二、导出概览:一个 import 拿全协议面
README 给出的标准导入方式如下:
import type { GuestFrame, HostFrame, SessionEntry } from "@oh-my-pi/pi-wire";
import { COLLAB_PROTO, DEFAULT_RELAY_URL, ENVELOPE_HEADER_LENGTH } from "@oh-my-pi/pi-wire";
全部导出按功能可分为五个关键组(见 packages/wire/src/index.ts 的分区注释):
| 分组 | 内容 | 典型用途 |
|---|---|---|
| 消息与转录条目形状 | WireMessage、SessionEntry 及其各变体 |
collab 访客端渲染消息流与转录 |
| 实时 Agent 事件与任务子 Agent 总线负载 | AgentEvent、AgentProgress、SubagentProgressPayload、SubagentLifecyclePayload |
访客端驱动事件回放、子 Agent 观察面板 |
| 加密封帧联合 | GuestFrame、HostFrame、WireFrame |
AES-GCM 密封载荷内的 JSON 结构 |
| 中继控制 TEXT 消息 | RelayControlToHost、RelayControlToGuest、RelayControlMessage |
房间加入/离开通知、房间关闭通知 |
| 链接/信封常量 | ENVELOPE_HEADER_LENGTH、ROOM_ID_BYTES、ROOM_KEY_BYTES、WRITE_TOKEN_BYTES、DEFAULT_RELAY_URL、DEFAULT_SHARE_URL、ParsedCollabLink |
host、guest 与本地 relay 三端共享 |
常量正确性由 packages/wire/test/constants.test.ts 直接守护:COLLAB_PROTO 恒为 3、COLLAB_PROMPT_MESSAGE_TYPE 恒为 "collab-prompt"、ENVELOPE_HEADER_LENGTH 恒为 4、ROOM_ID_BYTES 恒为 16、DEFAULT_RELAY_URL 恒为 wss://my.omp.sh。
三、协议边界:四步职责划分
README 用四步勾勒了 pi-wire 在完整协作流程中的位置,这也是理解整个 collab 架构的最小模型:
- 调用方构造
GuestFrame或HostFrame——例如访客发送prompt、abort,宿主发送welcome、entry; - 传输代码将帧序列化为 JSON,放入加密载荷——即 AES-256-GCM 密封;
- 中继代码仅依据明文 peer-id 前缀路由不透明信封——中继永远看不到会话内容;
- 接收方按
frame.t分发,并对未知的未来字段保持容忍——switch中保留宽容的default:分支。
第 4 步在 packages/wire/src/index.ts 的头部注释中被反复强调:未知的条目/事件变体会以纯 JSON 形式到达线缆,联合类型只覆盖当前客户端需要渲染的变体,消费方在 JSON 边界做类型转换(cast),且每个 switch 都保留 default: 分支以跳过未知类型。这是协议可演进的客户端侧保障。
宿主端的实际分发逻辑在 packages/coding-agent/src/collab/host.ts 的 #handleFrame 中逐项 switch (frame.t),未识别的帧只落一条 logger.debug 忽略;而 packages/coding-agent/src/collab/guest.ts 则定义了访客本地可执行的命令白名单(dump、export、open、leave 等),其余一律视为宿主专属。
四、消息与转录条目:访客端渲染的数据基础
4.1 内容块(Content blocks)
会话消息的内容由五类可组合的内容块构成,同时服务于用户、开发者与助手消息:
TextContent:{ type: "text", text };ImageContent:{ type: "image", data, mimeType },data为 Base64 编码图像,mimeType如"image/png";ThinkingContent:{ type: "thinking", thinking };RedactedThinkingContent:{ type: "redactedThinking", data };ToolCallContent:{ type: "toolCall", id, name, arguments, intent? }。
AssistantContent 是上述四类(不含文本外的纯文本之外的组合)的联合,即 TextContent | ThinkingContent | RedactedThinkingContent | ToolCallContent。此外还定义了 StopReason("stop" | "length" | "toolUse" | "error" | "aborted")与 WireUsage(输入/输出/缓存读写 token 数、总 token 数与 cost.total),用于助手消息的成本与用量上报。
4.2 四类 WireMessage
WireMessage 是 UserMessage | DeveloperMessage | AssistantMessage | ToolResultMessage 的联合,全部以 role 字段区分:
UserMessage:content可为字符串或(TextContent | ImageContent)[];synthetic?: boolean标记是否为系统注入(如 auto-continue);timestamp为 Unix 毫秒时间戳;DeveloperMessage:与用户消息同构,面向开发者角色;AssistantMessage:携带model、usage: WireUsage、stopReason以及可选的errorMessage;ToolResultMessage:携带toolCallId、toolName、内容块数组、可选details与isError标志,使工具调用与结果可一一对应。
4.3 SessionEntry 六种变体
SessionEntry 是会话转录条目的联合,所有条目继承 EntryBase(id、parentId: string | null、timestamp),并有:
SessionHeader(type: "session"):会话元信息,含id、可选title、timestamp与cwd;MessageEntry(type: "message"):包装一条WireMessage;CustomMessageEntry(type: "custom_message"):自定义类型消息,customType标识类型、content可为文本或内容块、display: boolean控制是否展示,可带details;CompactionEntry(type: "compaction"):上下文压缩记录,含summary、可选shortSummary、firstKeptEntryId与tokensBefore;BranchSummaryEntry(type: "branch_summary"):分支摘要,fromId指向来源条目;ModelChangeEntry(type: "model_change"):模型切换记录,model采用"provider/modelId"格式,可带role;ThinkingLevelChangeEntry(type: "thinking_level_change"):思考级别变更,thinkingLevel?: string | null。
其中 custom_message 与 collab 有特殊耦合:常量 COLLAB_PROMPT_MESSAGE_TYPE = "collab-prompt" 是访客端注入到宿主上的提示词条目 customType;对应的 CollabPromptDetails 只含一个可选 from 字段,用于标注提示词来自哪位访客。宿主侧在 #handlePrompt 中正是以 promptCustomMessage({ customType: COLLAB_PROMPT_MESSAGE_TYPE, ..., attribution: "user" }) 的方式把访客输入以“可流动式注入(steer)”接入会话(见 packages/coding-agent/src/collab/host.ts)。
五、AgentEvent:实时事件流
AgentEvent 覆盖了 Agent 会话的完整生命周期,访客端借此实时回放宿主的工作过程:
- 生命周期:
agent_start/agent_end/turn_start/turn_end; - 消息三阶段:
message_start、message_update(携带完整累积中的消息,无需增量追踪,这是协议特意简化的设计)、message_end; - 工具执行三阶段:
tool_execution_start(含intent?)、tool_execution_update(含partialResult)、tool_execution_end(含result与isError?); - 提示与通知:
notice(level为"info" | "warning" | "error",可带source); - 自动压缩:
auto_compaction_start(reason/action)、auto_compaction_end(aborted/willRetry/errorMessage?/skipped?); - 自动重试:
auto_retry_start(attempt/maxAttempts/delayMs/errorMessage)、auto_retry_end(success/attempt/finalError?); - 思考级别:
thinking_level_changed(thinkingLevel?: string)。
宿主端在 packages/coding-agent/src/collab/host.ts 通过 WIRE_AGENT_EVENT_TYPES 白名单过滤宿主会话事件流,命中者以 { t: "event", event } 广播,并依据 STATE_TRIGGER_EVENTS 决定哪些事件需要触发底部状态栏刷新。
六、状态与 Agent 快照
访客端底部状态栏渲染所需的状态由以下形状承载:
WireModel:id、name、provider与可为null的contextWindow;ContextUsage:tokens、contextWindow、percent三项均可为null;Participant:name加role: "host" | "guest",readOnly?: boolean标记是否经只读(view)链接加入;SessionState:宿主周期性广播的“防抖页脚快照”,含isStreaming、queuedMessageCount、可选sessionName、cwd(仅展示,访客永不 chdir)、可选model与thinkingLevel、contextUsage、participants数组以及isAborting?;AgentSnapshot:Agent 注册表快照,kind: "main" | "sub"区分主/子 Agent,status为"running" | "idle" | "parked" | "aborted",hasSessionFile决定访客能否发起远程转录读取,另含createdAt/lastActivity。
值得注意的实现细节:宿主在 packages/coding-agent/src/collab/host.ts 的 #buildState 中直接复用状态栏的 getCachedContextBreakdown() 缓存数据,保证访客端看到的上下文数字与宿主自己状态栏锚定一致的“provider 真实计数”;#snapshotAgents 则显式过滤掉 advisor 类型的 Agent——advisor 转录是纯本地可观测性资源,绝不允许访客对其发起 chat/kill/revive。
七、总线负载:任务子 Agent 的生命周期与进度
collab 会话把任务(task)子 Agent 生态完整镜像给访客:
BusChannel仅开放两个通道:"task:subagent:progress"与"task:subagent:lifecycle";AgentProgress是子 Agent 进度的完整快照:index、id、agent、状态(pending | running | completed | failed | aborted)、task、可选description与lastIntent、当前工具及参数与开始时间、recentTools环形数组、recentOutput、工具计数、请求数、token 数、上下文窗口、cost、durationMs与resolvedModel?;SubagentProgressPayload在AgentProgress之外附加parentToolCallId?、assignment?与sessionFile?;SubagentLifecyclePayload是生命周期事件:status为"started" | "completed" | "failed" | "aborted",附带id、agent、description?、sessionFile?、parentToolCallId?与index。
宿主端在 start() 中订阅的是“会话树可观测性总线”(observabilityBus = ctx.subagentEventBus ?? ctx.eventBus),原因在注释中写得很清楚:子 Agent 帧会在任意派生深度发布,只有从可观测性总线镜像,嵌套 Agent 的事件才能真正到达访客(见 packages/coding-agent/src/collab/host.ts)。
八、帧联合:GuestFrame / HostFrame / WireFrame
8.1 GuestFrame(访客 → 宿主)
hello:携带proto版本号、name,以及writeToken?——base64url 写令牌,证明持有完整链接;只读(view)链接不携带,宿主会把无有效令牌的对端标记为只读并拒绝其可变帧;prompt:text加可选images?: ImageContent[];ui-response:reqId与可选value,响应宿主的 UI 询问;abort:中断当前流;agent-cmd:cmd: "chat" | "kill" | "revive",针对agentId,chat可带text;fetch-transcript:reqId、agentId与fromByte偏移,增量拉取子 Agent 转录。
8.2 HostFrame(宿主 → 访客)
welcome:协议握手帧,携带proto、header、state、agents、entryCount(宿主随后将投递的SessionEntry总数)与readOnly?;snapshot-chunk:快照分片,entries: SessionEntry[]加final: boolean——最后一个分片携带final: true,访客据此终结副本;entry:单条实时SessionEntry;event:单条AgentEvent;state:最新SessionState;bus:镜像的 EventBus 流量(仅任务子 Agent 通道),data: unknown;agents:全量 Agent 注册表快照;ui-request/ui-request-end:向访客发起选择/编辑器询问,reqId配对;transcript:对fetch-transcript的定向回复,text是从fromByte起解码的 JSONL,newSize是下一次读取的偏移基准,error?标记终态读取失败;bye(携带reason)与error(携带message)。
WireFrame = GuestFrame | HostFrame 统一了加密封内的 JSON 语法。
8.3 UI 询问(CollabUiRequest)
CollabUiRequestDraft 支持两种形态:select(标题、选项数组 CollabUiSelectItem、initialIndex、selectionMarker: "radio" | "checkbox"、checkedIndices、markableCount 与 helpText)和 editor(标题与 prefill?)。CollabUiRequest = CollabUiRequestDraft & { reqId: number }。宿主侧通过 requestGuestUi() 发起、#pendingUi 表跟踪,MAX_PENDING_UI_REQUESTS = 64 作为上限;返回的 CollabGuestUiResult 区分“已应答”(undefined 是访客的真实取消)与“不可用”(通道消失,调用方不得视为取消)两种语义。
8.4 协议版本 COLLAB_PROTO
COLLAB_PROTO 当前为 3,其演进历史本身就说明了协议设计的取舍:
- v1(legacy):
welcome内联携带完整entries数组; - v2:
welcome只携带元数据(header/state/agents/entryCount),转录条目改由snapshot-chunk分片跟随,避免多 MB 会话被单个 welcome 帧卡在访客的首帧超时内; - v3:宿主通过
ui-request/ui-request-end向访客询问、访客以ui-response应答。早于该语法的访客会静默丢弃ui-request,导致询问在宿主端永远挂起,因此必须在hello阶段直接拒绝旧版本。
README 给出的版本管理铁律是:只有旧 host 与新 guest(或反之)必须互相拒绝时,才应升级 COLLAB_PROTO——协议变更要保持向后感知(backward-aware)。宿主在 #handleHello 中收到不匹配的 proto 时,会向对端回发 error 帧并拒绝入房。
九、信封与链接常量:加密边界的字节级约定
9.1 信封布局
ENVELOPE_HEADER_LENGTH = 4,信封格式为 [4B uint32 BE peerId][sealed payload]。对应实现(packages/coding-agent/src/collab/protocol.ts):
packEnvelope(peerId, sealed):以大端序写入 4 字节 peerId 再拼接密封载荷;unpackEnvelope(data):不足 4 字节返回null,否则拆分;rewriteEnvelopePeer(data, peerId):原地改写 peerId 而不复制载荷。
路由语义:宿主 → 中继时 peerId 0 表示广播给所有访客、N 表示定向给访客 N;访客 → 中继恒为 0,由中继改写为发送者 id。中继只能看到这个明文前缀与不含会话数据的 TEXT JSON 控制消息,永远接触不到加密内容。
9.2 密钥与令牌常量
| 常量 | 值 | 含义 |
|---|---|---|
ROOM_ID_BYTES |
16 | 房间 id 随机字节数 |
ROOM_KEY_BYTES |
32 | AES-256-GCM 房间密钥字节数,即每个 collab 帧的密封密钥 |
WRITE_TOKEN_BYTES |
16 | 随机写令牌字节数,完整链接中追加在房间密钥之后(base64url(key ∥ token));view 链接只携带裸密钥 |
拥有写令牌即向宿主证明具备 prompt/abort/agent-cmd 能力(宿主用 timingSafeEqual 做恒时比较,见 packages/coding-agent/src/collab/host.ts 的 #verifyWriteToken)。密封布局为 <a href="https://link.gitcode.com/i/070d4618b05da65e9ff92e21261dec54" target="_blank">12B IV][ciphertext+tag],见 [packages/coding-agent/src/collab/crypto.ts。
9.3 链接格式
ParsedCollabLink 定义了解析产物:wsUrl(wss://host[:port]/r/<roomId>,无 query 无 fragment)、roomId、key(32 字节)与可选的 writeToken。链接渲染与解析的细节值得单独说明(见 packages/coding-agent/src/collab/protocol.ts):
- 默认中继压缩为
wss://my.omp.sh,其它 wss 中继去掉 scheme(host[:port]/r/…),仅 localhost 的ws://链接保留完整 URL 以防解析误判为 wss; - 房间密钥采用 点连接(
<roomId>.<key>)而非#连接:RFC 3986 禁止在 fragment 内出现裸#,严格 URL 栈(如 macOS Foundation 的终端点击打开)会把第二个#百分号编码成%23从而破坏链接;解析端仍然兼容 legacy 的#形式与被破坏的%23形式; - 浏览器深链
formatCollabWebLink把 collab 链接放入 fragment,确保房间密钥不出现在 HTTP 路径与 query 字节中; - 完整链接密钥长度为 48 字节(key∥token),view 链接为 32 字节,解析端据此区分读写与只读。
DEFAULT_RELAY_URL = "wss://my.omp.sh" 是默认公共中继,裸 <roomId>.<key> 链接都解析到它;DEFAULT_SHARE_URL = "https://my.omp.sh/s" 是默认分享查看/上传基址,/share 链接解析为 <base>/<id>#<key>。
十、中继控制消息:唯一不被加密的流量
控制消息是明文 TEXT JSON,且明确不含任何会话数据:
RelayControlToHost:{ t: "peer-joined" | "peer-left", peer: number },告知宿主有访客加入/离开;RelayControlToGuest:{ t: "room-closed" },通知访客房间关闭;RelayControlMessage为二者联合。
在 packages/coding-agent/src/collab/relay-client.ts 的 #handleMessage 中,字符串消息走 onControl 回调(解析失败仅记一条 debug 日志),二进制消息才走信封解包与 AES-GCM 解密。同样的文件中还体现了传输层的健壮性设计:断线后以指数退避重连(BACKOFF_BASE_MS = 1_000 起、BACKOFF_MAX_MS = 30_000 封顶、抖动系数 0.75–1.25),致命关闭码(4001 房间关闭、4004 房间不存在、4009 房间已有宿主、4029 房间已满)与解密失败绝不重连;发送侧以 #sendChain 串行化密封保证帧按发送顺序落线,并以 #pendingSends(上限 256 帧)与背压阈值(64 KB 触发、32 KB 恢复)缓冲断线期间与慢速链路上的帧。
十一、实践指南:如何消费与扩展本包
11.1 零依赖引入
packages/wire/package.json 声明了极简的包面:main 与 types 均指向 ./src/index.ts,exports 支持 "." 与 "./*" 通配导入;devDependencies 仅有 @types/bun,运行时零依赖。引擎要求 bun >= 1.3.14。质量门禁为 bun run check(oxlint + oxfmt + tsgo 类型检查)与 bun test --parallel。
11.2 向后兼容的改造流程
新增字段或事件类型时,遵循仓库既有的四步纪律:
- 在
pi-wire中扩展对应联合类型,并保持字段全部可选或带默认值,让旧客户端能安全跳过; - 消费端(host / guest / collab-web)在
switch (frame.t)/switch (entry.type)中保留宽容的default:; - 仅在“旧 host 与旧 guest 必须互相拒绝”时才递增
COLLAB_PROTO(如 v3 引入ui-request时所做的); - 新增常量时同步更新 packages/wire/test/constants.test.ts,把数值契约钉死在测试里。
11.3 关键源码路径速查
- 契约定义:packages/wire/src/index.ts
- 常量测试:packages/wire/test/constants.test.ts
- 宿主侧协议延伸与链接/信封实现:packages/coding-agent/src/collab/protocol.ts
- 宿主会话实现:packages/coding-agent/src/collab/host.ts
- 访客会话实现:packages/coding-agent/src/collab/guest.ts
- AES-256-GCM 密封:packages/coding-agent/src/collab/crypto.ts
- WebSocket 传输与重连:packages/coding-agent/src/collab/relay-client.ts
- 浏览器访客端:packages/collab-web
十二、总结
@oh-my-pi/pi-wire 用一份零依赖的 TypeScript 契约,把 collab 实时会话中所有跨进程、跨语言边界(CLI host、浏览器 guest、中继 relay)的通信形状统一起来:消息与转录条目让访客端完整复刻会话历史,AgentEvent 与总线负载让子 Agent 生态实时可见,GuestFrame/HostFrame 联合定义了 AES-GCM 密封内的帧语法,信封与链接常量则把“密钥只活在链接 fragment 里、中继只见明文 peer-id”的安全边界固化进字节级约定。对任何想要为 oh-my-pi 扩展协作能力(新帧类型、新条目变体、新控制消息)的开发者而言,pi-wire 就是那本必须读懂、且必须保持向后兼容的协议手册。