oh-my-pi 协作会话线缆协议:深入解析 `@oh-my-pi/pi-wire` 共享 TypeScript 契约

原创2026-09-11 20:08:461,948 阅读
文章标签:代码智能体AI Agent人工智能大模型CLI开发工具工具调用

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 架构的最小模型:

  1. 调用方构造 GuestFrame 或 HostFrame——例如访客发送 prompt、abort,宿主发送 welcome、entry;
  2. 传输代码将帧序列化为 JSON,放入加密载荷——即 AES-256-GCM 密封;
  3. 中继代码仅依据明文 peer-id 前缀路由不透明信封——中继永远看不到会话内容;
  4. 接收方按 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 向后兼容的改造流程

新增字段或事件类型时,遵循仓库既有的四步纪律:

  1. 在 pi-wire 中扩展对应联合类型,并保持字段全部可选或带默认值,让旧客户端能安全跳过;
  2. 消费端(host / guest / collab-web)在 switch (frame.t) / switch (entry.type) 中保留宽容的 default:;
  3. 仅在“旧 host 与旧 guest 必须互相拒绝”时才递增 COLLAB_PROTO(如 v3 引入 ui-request 时所做的);
  4. 新增常量时同步更新 packages/wire/test/constants.test.ts,把数值契约钉死在测试里。

11.3 关键源码路径速查

十二、总结

@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 就是那本必须读懂、且必须保持向后兼容的协议手册。

登录后查看全文
oh-my-pi