深入 bb Provider Bridge 协议:thread/delta 语义语法与 Delta Assembler 的设计思想【免费下载链接】bbThe agent IDE that builds itself项目地址: https://gitcode.com/gh_mirrors/bb14/bbbb 是自我构建的智能体 IDE,而它的多 AI 提供商接入能力,核心来自Provider Bridge 协议——一套运行在 bb 与各家 AI 提供商桥(bridge)进程之间的 JSON-RPC 契约。本文将深入解析该协议中最精妙的部分:thread/delta语义增量语法,以及运行时侧的Delta Assembler(增量装配器)设计思想:为什么桥懂方言、运行时懂时间线的分工,能让 Codex、Claude Code、Pi 等完全不同的提供商,汇聚成同一条干净、有序、可回放的事件时间线。一、为什么需要 Provider Bridge 协议 不同 AI 提供商的方言差异极大:Codex 的 app-server 原生输出 turn/item 事件,Claude Code 走流式 SDK,ACP 有自己的内部信封层,Pi 则直接以 delta 形式发送文本。如果让每个桥进程各自负责把方言翻译成 bb 的完整时间线事件,就意味着每个桥都要重复实现同一批复杂逻辑:ID 铸造、输入排队、物品配对、用量累计……这正是旧架构里约 1000 行 SDK 代码的负担来源。bb 的修订方案(设计过程记录在 plans/narrow-grammar-protocol.md)只做了一件事:切分工界线角色职责类比Bridge(桥进程)解析自家提供商流量,输出解析后的语义增量听译员:听懂方言,产出标准语料Delta Assembler(运行时)消费增量,独占所有时间线不变量,构造规范的ThreadEvent字幕组:决定最终成片的时间轴一句话总结:桥懂方言,运行时懂时间线。二、thread/delta:一条通知,26 种语义增量所有时间线相关内容都搭载在同一条 JSON-RPC 通知上:{ method: thread/delta, params: { threadId: thr_xxx, deltas: [ ... ] } }一个 delta 是一个解析后的语义单元——永远不是原始提供商事件,也永远不是最终成品事件。完整语法定义在 thread-delta.ts,共 26 种kind,按职责可以分为六族:增量族代表 kind作用回合生命周期turn.open、turn.boundary、input.accepted标记回合的开始、结算与用户输入确认物品生命周期item.open/item.close/item.progress命令、文件变更、工具调用等物品的开合与进度流式文本item.textDelta/item.textClose/item.outputDelta逐字流式文本与命令输出用量与上下文usage、contextWindow、context.compactedtoken 用量、上下文窗口刻度诊断与错误provider.error、provider.warning、unhandled用户可见错误行、警告、未识别事件会话生命周期session.reset、session.ended会话重置与终结时的收尾几个设计细节值得品味:item.close永远携带完整终态形状——关合物品时把最终数据带上,装配器可以统一处理配对关合、中途改类型关合、无开合关合三种情形,桥无需维护配对账本。turn.boundary支持claimIfIdle——提供商侧的兜底结算信号只有在有待处理输入时才真正占有一个回合,避免在空闲线程上凭空制造回合。input.accepted强制携带clientRequestId——关联是显式的,运行时从不猜哪条用户消息开启了回合。三、Delta Assembler:中央 ID 铸造与不变量装配器实现在 delta-assembler.ts(约 2100 行),每个桥适配器一个实例。它独占以下时间线不变量:1️⃣ ID 铸造权在运行时,桥只做背书标识符铸造者threadIdbb 服务端providerThreadId提供商turn / item IDDelta Assemblerdelta 只携带提供商原生的连接键(工具调用 ID、流键、父引用、可选提供商回合 ID)。装配器维护双向的 provider↔bb ID 映射:既用来归属入站增量,也在命令平面(转向、中断)做反向翻译。这意味着桥完全不做 ID 翻译——这正是 #1320 事故的结构性教训:提供商可以在自己的线上注入任意标识符,但进入 bb 持久层的 ID 一律由 bb 铸造(entropy serial,每次session.reset重置)。2️⃣ 回合只能由三种路径开启只有turn.open、认领型turn.boundary和已接受输入的生命周期结算能开启回合;物品/流式增量永远不能。没有回合时到达的增量,按桥预先附带的noTurnFallback降级为线程级provider/unhandled,绝不静默丢弃。3️⃣ 流式文本是延迟记账的delta 优先的文本流(如 Claude 匿名流用channel: assistantparentRef定位)首次出现item.textDelta时,装配器自动合成item/started——桥只管吐文本,零簿记。首个 delta 立即发出(首 token 时延不变),之后的连续文本在100ms 合并窗口(textDeltaFlushMs)内拼接成单个事件,让话痨提供商不再每个 token 产生一条时间线事件;任何不可合并事件都是排序屏障,合并永远不会重排。4️⃣ 用量只有一种方言usage { total, last, modelContextWindow }原样转发为thread/tokenUsage/updated。报精确累计值的提供商(Codex)两个都发;按回合报的提供商(Claude、Pi)在桥侧用 kit 里的addTokenUsage自行累加。缓存读/写字段在提供商边界翻译后一路保留到 SDK/CLI 读取,缺失≠零,语义精确到历史事件保持未上报。5️⃣ 结算永远有兜底session.ended和结算型错误会按正确状态关闭所有未结的回合与物品;运行时还为已接受却迟迟不开始的回合配了看门狗——超时会变成可见的system/provider-turn-watchdog事件,而不是静默挂起。四、版本协商:grammar v3 如何无感升级协议版本目前固定在2(窄语法切换,thread/delta取代了旧的thread/event),而语法词汇表的变化走独立通道:握手时双方交换grammarVersions区间,取交集的最高版本。当前装配器只说v3(ASSEMBLER_GRAMMAR_VERSIONS),因此仓库内所有桥都报告[3, 3]。v3 相对 v2 是纯增量式扩展:新增fileRead、search、imageGeneration、delegation、planSteps等核心物品形状;presentation(标签/图标/标题)让插件即使被卸载,历史物品行依然能正确渲染;extension形状 extension.state则允许插件定义私有物品类型——线上只校验命名空间,服务端在摄入时用插件声明的 schema 校验载荷,不合格者降级为provider/unhandled,永不丢弃、永不未验证入库。五、一致性套件:用真实录制证明桥是对的 ✅因为桥以插件产物形式发布、可能是第三方的,协议测试分两层:一致性套件(conformance/):一组可测试规则(回合必须结算、中断必须在响应前完成结算、skills/configure声明与行为一致等),在 CI 里对每个桥运行。录制回放 parity(testing/parity.ts):设置BB_PROVIDER_BRIDGE_RECORD_DIR后,桥进程两侧的所有行被 tee 成 NDJSON 录制;回放时把提供商线路喂给假子进程、运行时线路喂给桥,在装配事件与投影行上做字节级 diff,每个录制单元的事件数/行数被row-counts.json钉死。脱敏后的录制提交在 recordings/。最佳学习材料是 examples/plugins/echo-provider/——官方第三方金丝雀插件:它只允许导入公开 SDK 和 zod,却完整演示了语法 v3 的每一种 delta、presentation 盖章、零工作回合结算、扩展类型校验与录制回放,是理解整条协议的最小完备实现。六、如何上手探索这份协议 读协议文档:总入口是 docs/provider-bridge-protocol.md,涵盖传输卫生、握手能力、回合状态机、恢复提示等全部语法之外的约定。看语法 schema:thread-delta.ts 是 26 种 delta 的唯一事实来源,用 zod 写成,读起来比散文快。看装配器:assembler/delta-assembler.ts 配合单元测试 delta-assembler.test.ts,能逐条看到不变量如何被断言。跑通 echo-provider:bb plugin install ./examples/plugins/echo-provider后在提供商选择器里选 Echo,配合它的 conformance / stream / parity 三个测试,就能看到桥→增量→装配→事件的完整闭环。总结:Provider Bridge 协议的本质是一次关注点切割——把易变的提供商方言留在桥里,把稳定的时间线不变量(中央 ID 铸造、生命周期配对、流式批处理、用量累计)全部收进运行时的 Delta Assembler。配合 grammar 区间协商与录制回放的一致性体系,bb 得以在协议层用极小的词汇表,容纳无限多样的 AI 提供商。【免费下载链接】bbThe agent IDE that builds itself项目地址: https://gitcode.com/gh_mirrors/bb14/bb创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考