Skip to content

[Investigation] All 4 wire protocols rely on hand-crafted adapters: can we replace/align them with the official SDK? (Pr | [调查] 4 条 wire 协议全靠手搓 adapter:能否换成/对齐官方 SDK?(协议一致性调查单) #7461

Open

Description

@ranxianglei

背景:四条出站协议 responses / openai chat / anthropic / google(src/loop/index.ts 的 protocol: "responses" | "openai" | "anthropic" | "google",四个手搓 adapter src/loop/adapter-responses.ts / adapter-openai.ts / adapter-anthropic.ts / adapter-google.ts)近期连出三个"合成流不合官方 spec"的 bug——#7401(Responses 合成流缺 content_index,官方 OpenAI SDK 直接拒收整个响应)、#7405(fake-completion 缓冲超限吞掉成功大响应)、#7136(OpenAI 合成 completion 丢 provider usage 字段)。三个都是修了之后才知道的:没有任何自动化手段持续验证"我们合成的流官方客户端能不能吃",直到 #7402 把真 OpenAI SDK 当测试消费端才暴露出 #7401。

为什么现在没有直接用官方 SDK(先记已知事实,待核心维护者确认):openai(npm)、@anthropic-ai/sdk、google-genai 均为客户端——只解析流,不提供"服务端按 spec 发射 SSE 帧"的库;且 bili 的 adapter 在发射之外还要剥渲染标签、插 ACP marker/压缩信号、重试重构帧、remap item id、预算缓冲,需要 SSE 字节级控制权。

本单要做的事(调查,不是直接开工):

  1. 换可行性:逐协议查官方生态有没有"服务端发射这些 SSE 帧"的库;若无发射器则逐条记录"不可换"及原因。
  2. 验可行性(大概率可落地的方向):把四条协议各自的官方 SDK 都当 CI 消费端,钉住"合成流必须被官方客户端接受"。Responses 一条已有示范([PR] fix(responses): preserve content indices in synthesized streams #7402:真 SDK 消费 + wire-contract WC-026 校验器,测试文件 tests/responses-content-index.test.ts),查其余三条各自的消费端接法与覆盖字段(openai chat 用 openai 包的 chat streaming、anthropic 用 @anthropic-ai/sdk、google 用 google-genai)。
  3. spec fixture:是否值得给四条协议各建一组官方 wire capture 的 record-replay fixture,防字段级漂移。

验收标准:四条协议各自的结论(可换 / 不可换 / 部分可行 + 依据 + 工作量估计);若方向 2 可行,产出带 CI 车道的 PR 把四条官方消费端全部接上。

Activity

  1. changed the title [-][调查] 4 条 wire 协议全靠手搓 adapter:能否换成/对齐官方 SDK?(协议一致性调查单)[/-] [+][Investigation] All 4 wire protocols rely on hand-crafted adapters: can we replace/align them with the official SDK? (Pr | [调查] 4 条 wire 协议全靠手搓 adapter:能否换成/对齐官方 SDK?(协议一致性调查单)[/+] on Nov 21, 2026
  2. ranxianglei commented on Nov 21, 2026

    @ranxianglei
    OwnerAuthor

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 (ai: vllm-qwen/qwen3.8-27b)

    查重: 不重复(与已关闭的 #7406/#7407 相关——那是已修好的三个 bug 本身,本单是"为什么没被自动化抓住"的调查)。

    三个方向的结论

    方向 1 — 换可行性:四条全部不可换(无官方服务端发射器库)

    逐协议查了官方生态,结论一致:openai、@anthropic-ai/sdk、@google/genai 都是客户端(只解析流),官方没有"服务端按 spec 发射 SSE 帧"的库。bili 的 adapter 在发射之外还要剥渲染标签、插 ACP marker/压缩信号、重试重构帧、remap item id、预算缓冲——需要 SSE 字节级控制权,官方客户端 SDK 一个都不提供。所以四条手搓 adapter 是必要的,不可换。工作量估计:不适用(无库可换)。

    方向 2 — 验可行性:已落地,PR #7466 把四条官方消费端全部接上

    Responses 一条 #7402 已有示范。本 PR 补齐其余三条:

    • openai chat(openai 6.26.0):new OpenAI({ fetch }) 注入合成字节流,7 个测试。
    • anthropic(@anthropic-ai/sdk 0.91.1):new Anthropic({ fetch }),7 个测试。
    • google(@google/genai 1.52.0):该 SDK 的 generateContentStream 走全局 fetch(无 client 级 fetch 选项,已在 SDK 源码确认),所以消费端跑在 listen(0) 的本地 HTTP server 上,5 个测试。仍 hermetic(仅回环,无外网)。

    SDK 经 in-tree pi-coding-agent 解析(#7402 先例),不动 package.json/lockfile;pi-ai 若哪天丢掉某个传递依赖,套件会响亮失败(可见的有意 diff),不会静默。新 tests/*.test.ts 被 scripts/run-ci-tests.mjs 自动 glob(无需注册);三条套件都不 spawn 进程,无需 LIVE_FILES 登记。

    方向 3 — record-replay spec fixture:建议暂缓

    SDK 消费端(方向 2)钉的是"我们合成的流官方客户端能不能吃"——这正是 #7401/#7405/#7136 三个 bug 的逃逸面。record-replay 钉的是"我们解析上游的流是否忠实"——不同的风险面。鉴于 SDK 消费端已覆盖主要风险,record-replay 的边际收益有限而成本不低(要抓真实流量、维护 fixture),建议暂缓,等出现 SDK 消费端抓不到的字段级漂移再上。

    接线时发现的真实 bug(已修,含在 PR #7466)

    官方 OpenAI SDK 拒收"choice 0 从未带 role"的流(missing role for choice 0)——和 #7401(Responses 缺 content_index)同一类。当上游在发任何字节前就死掉时,代理合成的 error completion 是客户端的第一个帧,而两处发射点(relay 级 emitStreamError 和 loop 级 adapter.emitError)都漏了 role,SDK 直接拒收整个响应,客户端看到的是连接错误而不是失败文本。两处现在都先开 assistant role;重复 role(上游已发过)无害——SDK 只是重设已为 "assistant" 的 role。由两个 error-completion 测试钉住。

    PR: #7466 (已打标签 enhancement/bug/p3/scope-ci;CI 运行中)


    八问

    1. 是什么问题:四条出站 wire 协议全靠手搓 adapter,且没有任何自动化手段持续验证"我们合成的流官方客户端能不能吃"——[Bug] Synthesized Responses text events lose content_index and crash SDK consumers #7401/[Bug] Fake-completion buffering silently truncates successful responses #7405/[PR] fix(openai): keep provider usage fields in the synthesized completion #7136 三个 bug 都是修了之后才知道的。
    2. 什么原因导致的:官方 SDK 都是客户端(只解析、不发射),没有服务端 SSE 发射器库可换;adapter 需要字节级控制权(剥标签/插 marker/重试重构/remap id/预算缓冲),官方客户端 SDK 一个都不提供。缺"合成流必须被官方客户端接受"这条持续校验,字段级漂移就只能在用户撞上时才暴露。
    3. 影响范围与严重程度:四条协议此前都缺这条自动化校验(质量缺口,非单点故障)。接线时发现的 missing-role bug 影响面窄:仅 compat.streamErrorShape="completion" 用户 + 上游在发任何字节前死亡(边缘场景,p3);[Bug] Synthesized Responses text events lose content_index and crash SDK consumers #7401/[Bug] Fake-completion buffering silently truncates successful responses #7405/[PR] fix(openai): keep provider usage fields in the synthesized completion #7136 是已修好的真实用户面 bug。
    4. 怎么修复的:方向 2 落地——把四条官方 SDK 当 hermetic CI 消费端,喂代理合成的字节流、断言流被接受且 content/usage/finish 字段存活。missing-role bug 在两处发射点补上 assistant role 开头。
    5. 是否有回归问题:无。missing-role 修复只在 error completion(罕见路径)加一个 role 帧;重复 role 无害(SDK 重设已为 "assistant" 的 role)。既有测试(proxy-stream-error / google-stream-errors / upstream-truncation / loop-sse-framing-scan / verif-adapter-wire-stability 等 54 个)全绿。
    6. 是否破坏缓存:不涉及。改动只在 error completion 形状(罕见路径)+ 新增测试文件;缓存/重试/增量游标/去重键均未触碰。
    7. 是否改了设计方向:不涉及。adapter 仍手搓(方向 1 结论:不可换);本 PR 加的是校验(CI 消费端),不是新设计。
    8. 是否引入了新的配置:不涉及。无新 env/config/CLI flag;SDK 经 in-tree pi-coding-agent 解析,不动 package.json/lockfile。

    收工判定:调查三个方向全部给出结论(不可换 / 已落地 / 建议暂缓),方向 2 的 PR #7466 已开(四条官方消费端全接上 + 顺手修掉一个同类真实 bug),等 CI 绿 + 你验收。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions