[ranxianglei]

Closes #5193

Adds a README FAQ entry (en + zh, kept in sync) documenting how to combine bili with the qoder-trae-workbuddy-switch quota gateway — same /bili/<abs-url> prefix pattern as the existing magpie entry, plus the four load-bearing caveats from the #5193 code-level analysis of that gateway:

1. Account stickiness keys off the body field metadata.conversation_id ONLY (no header fallback) — clients that don't write it (Claude Code, Codex) get a per-request account draw from the pool and each vendor account keeps its own prefix cache, so cross-turn prefix-cache hits ≈ 0; workarounds listed (client that writes the field, Sequential pick mode, single-account allowlist).
2. Unified gateway requires namespaced model names <ns>:<model> (bare → 400) — declare their context windows under the providers key via models.<name>.context (Provider route miss silently drops per-model context override; 502 error then advises setting the already-set compress.modelContextLimit #2317).
3. Qoder lane reports zero token usage upstream → bili usage stats degrade there (compression unaffected — local tokenization).
4. Mid-conversation account switches invalidate the provider prefix cache and stay invisible to bili's KEY SWITCHES attribution (outbound key is always the stable sk-* gateway key).

Docs only — no code changes.

[github-actions]

📦 Built Package Artifact

Branch: 2026-11-01_faq-buddy-switch-gateway (0c5190c)

Latest build — install this exact version

npm install -g billion-context@0.0.9042-pr.5381.a5a0d14

This exact version is immutable and reproducible. The rolling pr tag tracks the newest test build across all PRs.

Recent builds (commit → version)

commit	version	build
0c5190c	billion-context@0.0.9042-pr.5381.a5a0d14	build
59b67ec	billion-context@0.0.7601-pr.5381.786104b	build

Download artifact

1. Download the artifact from the Actions run
2. Extract the tarball and install:

tar xzf billion-context-pr5381.tgz
npm install -g package

---

Install instructions are refreshed on each push.

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

审核结论：可合并。 这是 #5193 兼容性分析收尾时明确列出、并经「ework 接单」确认执行的 FAQ 文档后续动作（不是重复立项）。我独立核对了 diff、en/zh 同步、事实准确性与 CI，没照抄 #5193 的结论。

核对要点：

• diff 干净：仅 2 个文件、+20/−0，每一行都服务于目的——README.md 与 README.zh-CN.md 各加一条 qoder-trae-workbuddy-switch 配额网关 FAQ，紧挨 magpie 条目插入。无跑题文件、无空白重排、无 lockfile/生成物变更。
• en/zh 真同步（初看 +18 vs +2 像不同步，实为两文件既有排版约定差异）：英文 FAQ 答案多行折行，中文单行长段——各自与相邻的 magpie 条目写法一致。四条注意事项 + 端口表(57891 WorkBuddy / 57892 统一 / 57894 Trae / 57895 Qoder) + /bili/<abs-url> 接法在中英两侧逐条对应，无遗漏、无新增主张。CI 的 docs-sync / docs-coverage 门禁均绿，独立佐证同步成立。
• 事实准确：接法与四条坑（①粘性只认 body metadata.conversation_id 不读任何头 → Claude Code/Codex 跨轮缓存≈0 及三种绕行；②<ns>:<model> 命名空间裸名 400 → 用 models.<name>.context 声明窗口 Provider route miss silently drops per-model context override; 502 error then advises setting the already-set compress.modelContextLimit #2317；③Qoder 车道上游恒报 0 token → 用量统计退化但压缩走本地 tokenize 不受影响；④会话中途换号使 provider 前缀缓存失效且对 KEY SWITCHES 归因不可见）与 [PR] storage gc: batch orphan-content collection + refuse full VACUUM while another process holds the db (#4612, #4796) #5193 的代码级分析逐点吻合，没有引入未经核实的说法。
• 无索引回归：两份 README 的 FAQ 只有 ## FAQ / ## 常见问题 节标题，没有逐项索引导航，新增问题无需另处更新。
• CI：已完成的门禁全绿（static-gates、kernel-guard、config-surface-guard、lane-guard、lock-sync、docs-sync、docs-coverage、version-guard、build-artifact 等）；真实客户端 e2e 车道按默认门控 skip（docs PR 的预期行为）；仅 ubuntu/windows 全量 test 分片仍在跑——纯文档改动会平凡通过。当前 merge 状态 blocked 只因 test 分片未完 + 待 owner 批准，不是失败。

结构化八问

1. 是什么问题：给 bili × qoder-trae-workbuddy-switch 配额网关这个组合补一条 README FAQ（en+zh），把接法和 [PR] storage gc: batch orphan-content collection + refuse full VACUUM while another process holds the db (#4612, #4796) #5193 分析出的四条坑讲清楚。
2. 什么原因导致的：[PR] storage gc: batch orphan-content collection + refuse full VACUUM while another process holds the db (#4612, #4796) #5193 分析收尾提出「可选 docs PR」，owner 接单确认执行——本 PR 就是该动作，不是新需求。
3. 影响范围与严重程度：纯文档新增，零代码零行为变更，无任何用户面/触发面影响。
4. 怎么修复的：仿现有 magpie FAQ 条目的写法，在两份 README 各追加一条同构条目，细节回指 [PR] storage gc: batch orphan-content collection + refuse full VACUUM while another process holds the db (#4612, #4796) #5193。
5. 是否有回归问题：无——只增不改（0 删除），未触碰任何既有行为/配置/wire/格式；docs-sync、docs-coverage、kernel-guard、config-surface-guard 均绿。
6. 是否破坏缓存：不涉及（文档未改任何缓存/重试/失效策略）。
7. 是否改了设计方向：不涉及。
8. 是否引入了新的配置：不涉及——条目只引用既有条目（网关选号模式、bili providers.<key>.models 声明），未新增任何 config/env/CLI 面。

判定：可合并。 文档质量达标、en/zh 同步、事实准确、diff 干净、相关 CI 门禁全绿。等 test 分片跑完即全绿；合并按仓库规则由 owner 执行（我不代合并）。合入后本 PR 关闭 #5193。

[ranxianglei]

(ai: vllm-qwen/qwen3.8-27b)

审查结论：可合并（APPROVE 等效） —— 纯文档新增。独立复核了 diff、en/zh 同步、事实核对（对照 #5193 源码级分析）与 CI，未照抄线程内既有结论。（GitHub 规则禁止 PR 作者账号经 API 正式自批，故以 review COMMENT 提交本结论。）

APPROVE — 纯文档新增。独立复核了 diff、en/zh 同步、事实核对（对照 #5193 源码级分析）与 CI，未照抄线程内既有结论。

独立核对要点：

• diff：仅 README.md(+18) / README.zh-CN.md(+2)，纯新增(0 删除)。条目各紧挨既有 magpie FAQ 条目之后插入(README.md:437 / README.zh-CN.md:303)、下一节标题之前；无跑题文件、无空白重排、无 lockfile/生成物变更。
• en/zh 真同步：接法(/bili/ 前缀、/v1=OpenAI 线 / 去 /v1=Anthropic 线 + sk-* key)、端口表(57891 WorkBuddy / 57892 统一 / 57894 Trae / 57895 Qoder)、四条注意事项、回指 #5193——两侧逐条对应，无遗漏、无超出分析的新主张。EN 多行折行 / ZH 单行长段+全角标点，各自与所在文件的相邻 magpie 条目写法一致。
• 事实核对：四条坑与 #5193 代码级分析逐点吻合(①粘性键只从 body metadata.conversation_id 取、不读任何头 → Claude Code/Codex 无粘性、跨轮 prefix cache ≈ 0，列出三种绕行；②统一网关裸模型名 → 400，用 models.<name>.context 声明窗口 #2317；③Qoder 车道上游恒报 0 token → 用量统计退化但压缩走本地 tokenize 不受影响；④会话中途换号使 provider 前缀缓存失效且对 KEY SWITCHES 归因不可见)。端口表与分析一致。
• 无索引回归：两份 README 的 FAQ 均只有节标题、无逐项索引(顶部锚点只指向节不指向项)→ 无需别处更新。
• 惯例：分支名 2026-11-01_faq-buddy-switch-gateway 符合 YYYY-MM-DD_short-title；commit docs: 前缀；分支基于当前 master tip；version 未动；未触碰 kernel/、零代码变更、无新配置面(只引用既有 providers.<key>.models 声明)→ 不触发任何授权门禁。
• CI(镜像缓存 @ 59b67ec)：30 项检查 0 失败 0 待跑——ubuntu/windows × node 22/24 全部 test 分片绿，static-gates / mysql-contract / test-import-graph / version-guard / docs-sync / docs-coverage 绿；真实客户端 e2e 车道按默认门控 skip(docs PR 预期行为)。merge state blocked 是待 owner 批准所致，非检查失败。

结构化八问：

1. 是什么问题：给 bili × qoder-trae-workbuddy-switch 配额网关组合补一条 README FAQ(en+zh)，讲清接法与四个坑。
2. 什么原因导致的：#5193 兼容性分析收尾时明确提出可选 docs PR，owner 接单确认执行——本 PR 即该动作，不是新需求。
3. 影响范围与严重程度：纯文档新增，零代码零行为变更，无用户面/触发面影响。
4. 怎么修复的：仿现有 magpie FAQ 条目结构，在两份 README 各追加一条同构条目，细节回指 #5193。
5. 是否有回归问题：审过触碰路径承担的既有行为——FAQ 节渲染与导航(无逐项索引，不受影响)、en/zh 文档同步门禁(docs-sync/docs-coverage 绿)、接法描述与既有 magpie 条目的一致性(相符)。只增不改(0 删除)，未破坏任何既有行为/配置/wire/格式。
6. 是否破坏缓存：不涉及(文档未改任何缓存/重试/失效策略)。
7. 是否改了设计方向：不涉及。
8. 是否引入了新的配置：不涉及——条目只引用既有条目(网关选号模式、bili models.<name>.context 声明)，无新 config/env/CLI 面。

判定：可合并。 合并按仓库规则由 owner 执行；合入后本 PR 关闭 #5193。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b) 专职 review 完成：结论可合并（APPROVE 等效，已提交正式 review）——独立复核 diff（仅两 README +20/0 纯新增）、en/zh 逐条同步、四条坑对照 #5193 源码级分析、CI 30 项检查 0 失败（镜像缓存 @59b67ec），纯文档无 kernel 触碰；上游 GitHub PR 实际编号为 #5381（本镜像编号 #5382，review 已落在正确 PR 上）。等 owner 合并。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

(ai: vllm-qwen/qwen3.8-27b)

查重: 不重复 — 本单是既有已审 PR #5381 的冲突处置(同签名无其他 open/closed 条目)。
标签: pr / scope/docs / p3 / qoder / trae / workbuddy — docs-only FAQ,覆盖 Qoder/Trae/WorkBuddy 网关组合,非缺陷;已打齐并实读核验。

Conflict resolution. Rebased the single-commit docs branch onto master@58a8796224. One content conflict in README.zh-CN.md (FAQ section): while this PR sat stale, master (a) extended the magpie entry with clause ⑤ (BILI_CLAUDE_UPSTREAM, #5369), (b) added a new opencodex/ocx entry, and (c) re-pointed the "日志和会话数据存在哪?" line to docs/configuration.zh-CN.md — while the PR side had inserted its own qoder-trae-workbuddy-switch entry beside the old log line. Resolved by union of intent: all master-side content kept, and the reviewed qoder entry re-inserted byte-identical immediately after the opencodex entry — exactly matching the order git auto-generated for README.md. Net diff vs master remains precisely the originally-reviewed footprint: README.md +18, README.zh-CN.md +2, 0 deletions. Force-pushed with a lease pinned to the old head (the sanctioned conflict-rebase push; remote head verified unchanged immediately before). New head: 0c5190ca9e.

Live state (verified this run, single reads). PR open, mergeable=true, mergeable_state=behind: master has since moved to 33104b1f95 (#6150 remove-compress-at-fold-point merged). "behind" is not a blocker; no further action needed on it.

CI on the new head. 48 checks completed: 35 success / 12 skipped / 1 failure = test (ubuntu-latest, 24, 3) (run 42944675280 / job 130274656230). The failure is two TAP cases in tests/plugin-fork.test.ts: case 2119 (uncaughtException, SyntaxError: Unexpected end of JSON input at tests/plugin-fork.test.ts:91 — an empty/truncated HTTP response body) and case 2120 (AssertionError: 2 !== 1 at tests/plugin-fork.test.ts:344). Diagnosis: single-runner load-starvation flake, not a regression — (1) this PR's diff is pure markdown, zero code touched; (2) every sibling shard/check in the same run is green; (3) local targeted run at the exact head 0c5190ca9e (npm ci + build clean): 57/57 pass — the failures do not reproduce at code level, which rules out an inherited deterministic red; (4) the error shape (truncated response under load) matches the flake family already tracked in #4599. It is distinct from the sentinel-tracked deterministic pi-lane red (#2791 cross-protocol fold reuse): different lane, different signature. Action taken: targeted rerun-failed-jobs triggered (HTTP 201); if the same signature goes red again it flips to true regression and gets escalated. Note: this PR's mirror upstream-checks cache has been stuck at pre-push shas since 2026-10-31 (same phenomenon as #4599 floor 1221), so states above come from direct single reads of the GitHub API, per policy.

八问(中文)

1. 是什么问题:PR 分支与 master 合并冲突(merge state dirty);rebase 后 CI 出现一个红测试分片。
2. 什么原因导致的:冲突源于 PR 滞留期间 master 改动了 zh-README FAQ 同一区段(新增 opencodex 条目、magpie ⑤ 条款、日志路径链接变更),与本 PR 新增的 qoder 条目重叠;红分片为 runner 负载饥饿时序抖动(HTTP 空响应解析失败 + 计数断言),与本 docs-only diff 无关。
3. 影响范围与严重程度:仅影响本 PR 自身的可合并性与 CI 判决;纯文档改动,对用户行为零影响。严重度:流程性阻塞,已解除。
4. 怎么修复的:冲突按 union-of-intent 解决(master 侧内容全保留 + 本 PR 已审条目逐字节重插、顺序与 EN 文件对齐),净 diff 不变;红分片按四重证据链判 flake,触发失败 job 定向重跑,零代码改动。
5. 是否有回归问题:无。净 diff 与原审核版完全一致(README.md +18 / README.zh-CN.md +2,无删除);未触碰任何代码/协议/配置/持久化路径。
6. 是否破坏缓存:不涉及(纯 markdown,未触碰缓存/重试/游标/去重逻辑)。
7. 是否改了设计方向:无。
8. 是否引入了新的配置:无。

判定:冲突已解、净 diff 未变、重跑判决在途——重跑转绿后 owner 可直接合并(§7.4 人工合并档)。

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[ework] auto-fix stalled: test (windows-latest, 22, 4), test (ubuntu-latest, 24, 2), test (ubuntu-latest, 22, 2) — stopping for human review

[ranxianglei]

🤖 Powered by ework · qwen3.8-27b

[ework] auto-fix stalled: test (windows-latest, 22, 4), test (ubuntu-latest, 24, 2), test (ubuntu-latest, 22, 2) — stopping for human review