Skip to content

[PR] docs: document the pi-claude-bridge compression-state limitation (#3429) - #3553

Closed
ranxianglei wants to merge 5 commits into
masterfrom
2026-10-17_issue3429-pi-claude-bridge-docs
Closed

ranxianglei wants to merge 5 commits into
masterfrom
2026-10-17_issue3429-pi-claude-bridge-docs

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 17, 2026 •

Copy link
Copy Markdown
Owner

For #3429 — option B of the triage conclusion (the limitation is a bridge-side identity gap, not a bili defect; documenting it until the bridge ships a fix).

What

One paragraph in the Pi section of CLIENTS.md (+ zh-CN mirror), placed right after "How routing works" because the limitation is a direct consequence of verbatim session keying:

  • pi-claude-bridge spawns a fresh Claude Code subprocess per pi session start; its own x-claude-code-session-id rides every model request while pi's stable conversation id never does;
  • bili keys sessions verbatim on the id it sees → after reopen/resume/fork the new CC id maps onto an EMPTY conversation: folded history and compression accounting do not carry over, and launcher/native compress addressed to the pi id returns 404 (unknown plugin conversation) — one root mechanism, not two bugs;
  • explicit non-defect framing: content is never lost or corrupted, only the state of compression resets;
  • fix direction named: belongs in pi-claude-bridge (derive the CC session id stably from the pi conversation id); meanwhile treat pi+claude-bridge as plain-proxy mode for context management.

Why this PR exists on its own

#3429's triage concluded bili needs no code change (a content-affinity fallback on the proxy side was explicitly rejected — mis-attributing sessions across re-minted ids is the most expensive failure class in this project, see MESSAGE-IDENTITY.md). The actionable bili-side remainder was exactly this documentation gap: users of the combination currently discover the behavior as "compression is entirely decorative" with no explanation anywhere in the docs.

No code changes; no tests required. Option A (the actual bridge-side fix) is cross-repo work and awaits owner sign-off per the cross-repo submission policy.


Fixes #3429

(孤儿认领:标题本已指向 #3429,补上关闭关键字 —— 第三批清理)

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-17_issue3429-pi-claude-bridge-docs (ea828c7)

Latest build — install this exact version

npm install -g billion-context@0.0.6199-pr.3553.8450982

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
ea828c7 billion-context@0.0.6199-pr.3553.8450982 build
319f149 billion-context@0.0.6111-pr.3553.7d5591d build
253f6df billion-context@0.0.6019-pr.3553.c6fe169 build
6b1e2ce billion-context@0.0.5542-pr.3553.9f250f1 build

Download artifact

  1. Download the artifact from the Actions run
  2. Extract the tarball and install:
tar xzf billion-context-pr3553.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复。本条是 #3429 triage 选项 B 的文档 PR;扫描了所有提及 pi-claude-bridge 的在途 PR(#3001 async 压缩功能、#3221 /compact summarizer 路由)——目标不同,与本文档缺口无重叠,无并行同类工作。

审核方式(独立复核,未照抄 issue 结论): 拉取分支 2026-10-17_issue3429-pi-claude-bridge-docs(head 181ca17 = 当前 master tip + 1 commit,base 不陈旧),通读全量 diff,逐条事实断言回到代码核对。

Diff 与落位 ✅

  • 仅 2 文件 +4 行:CLIENTS.md:605、CLIENTS.zh-CN.md:151,各一段;
  • 位置恰在 Pi 段「How routing works」(zh:「路由机制」)段之后、「WebSocket coverage」之前——与 PR 描述逐字一致,限制确实是 verbatim 键控的直接推论,放这里读者刚看完键控机制就接住后果;
  • 无代码变更、无测试变更、无空白噪音,diff 干净。

事实断言逐条核对(代码级)✅

  1. 「bili keys sessions verbatim on the id it sees」→ src/session-id.ts:82-87:header 优先级表,原样返回客户端值(仅 trim);session-id.ts:109 明确「Everyone else keys VERBATIM」。成立。
  2. 「launcher/native compress addressed to the pi id returns 404」→ src/plugin.ts:742-743 / 1730-1731:模型流量落在 CC id、compress 带 pi id 时正是 unknown plugin conversation id … (no model request has arrived with this conversation id yet) 路径。成立。
  3. 「one root mechanism, not two bugs」+「内容从不丢失或损坏,只是压缩状态重置」→ 与 Pi + claude-bridge: native sends no model requests to proxy; launcher compress returns 404 #3429 分层判断一致(reopen 丢/resume 丢/404 是身份解耦的三种表现);报告人自己的证据(旧状态仍在盘上、挂在旧 CC id 名下)支持非缺陷定性。成立。
  4. 根治方向点名(bridge 侧从 pi 会话 id 稳定派生 CC session id)→ 与 triage 给出的根因方向一致;段落没有承诺任何 bili 侧行为变化,也没有引入代理侧内容回退。成立。

CI 状态

八问:

  1. 是什么问题:文档缺口——pi+claude-bridge 组合用户会自己发现「压缩态不跨 reopen/resume/fork + compress 404」,而文档里没有任何解释。
  2. 什么原因导致的:桥侧身份缺口(Pi + claude-bridge: native sends no model requests to proxy; launcher compress returns 404 #3429 triage 结论):每次 pi 会话启动 spawn 全新 CC 子进程并盖全新 x-claude-code-session-id,pi 稳定 id 从不上这条 HTTP;bili 的 verbatim 键控契约是正确行为,不是缺陷。
  3. 影响范围与严重程度:仅限走 pi+claude-bridge 手动路线的用户;轮内压缩正常,跨 reopen/resume/fork 状态重置,launcher/native compress 404——特定条件触发,非全面不可用。本 PR 本身零运行时影响(纯文档)。
  4. 怎么修复的:CLIENTS.md Pi 段(紧跟路由机制段)+ zh 镜像各补一段说明:现象、同一根机制定性、非缺陷边界、bridge 侧根治方向、过渡期按纯代理模式看待上下文管理。
  5. 是否有回归问题:无——零代码/配置/wire 改动;docs-sync/docs-coverage 门禁通过,未触碰任何既有行为路径。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:不涉及——段落明确维持 verbatim 会话键控契约(bili 侧不做内容亲和回退),与 MESSAGE-IDENTITY 原则一致。
  8. 是否引入新配置:无。

小注:PR 正文用「For #3429」而非 Closes——有意为之,#3429 应留开到桥侧修复(option A)落地;标题已带链接,不影响可追溯性。

判定:可合。 windows 重跑转绿即可直接合;若再红一次,上述证据链仍支持环境噪声,届时你定强合还是再等。option A(桥侧根治)继续等你按跨仓政策明确同意后我再列投递计划。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

重跑结果更新(run 39025590078,attempt 2):

判定不变:可合。 当前红是 #3530 flake 窗口的误红,不是本 PR 的问题。可按上述证据链直接合并;若想要全绿截图,再等一轮重跑也行,但不必因此阻塞。

@ranxianglei ranxianglei changed the title docs: document the pi-claude-bridge compression-state limitation (#3429) [PR] docs: document the pi-claude-bridge compression-state limitation (#3429) Oct 24, 2026
pi-claude-bridge spawns a fresh Claude Code subprocess per pi session start whose own x-claude-code-session-id never carries pi's stable conversation id — so after reopen/resume/fork bili's verbatim session keying maps the new CC id onto an empty conversation (folded history + compression accounting lost, launcher/native compress 404s on the pi id). One root mechanism, not a bili defect: content is never lost or corrupted, only the compression state resets. Documented in the Pi section of CLIENTS.md / CLIENTS.zh-CN.md with the bridge-side fix direction (stable CC id derivation); option B of the #3429 triage.
@ranxianglei
ranxianglei force-pushed the 2026-10-17_issue3429-pi-claude-bridge-docs branch from 181ca17 to 6b1e2ce Compare October 24, 2026 15:39
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重:同 #3530 家族(Windows runner flake,victim 轮转、master 自身也红过),该 issue 已被 owner 于 10-18 关闭(completed);不另立项——期间 #3665 已把对应恢复机制合入 master(见下)。

处置:已把分支 rebase 到当前 master 并 push——新 head 6b1e2ceac(原 181ca17c8 作废,那条红 job 属于被取代的旧 head)。docs diff 逐字未变,仍为 CLIENTS.md / CLIENTS.zh-CN.md 各 +1 段;rebase 无冲突。

为什么这样修(独立取证,非复述前评论):

结构化八问:

  1. 是什么问题:Windows 一个 test 分片因 runner 基础设施 flake(事件循环 drain)判红,与 PR 内容无关(纯文档 4 行)。
  2. 什么原因导致的:runner 事件循环中途停滞导致 5 个在飞子测试被父进程 cancel(fail=0/cancelled=5,全 cancelledByParent);叠加分支基线陈旧 1253 个提交,其 CI 脚本缺少 Flaky Windows CI: issue1993-preflight-400 suite cancelled by early event-loop drain | Windows CI 偶发假红:preflight-400 测试进程提前退出致 5 例取消 #3665 的自动恢复机制,瞬态失败未被吸收而直接判红。
  3. 影响范围与严重程度:仅本 PR 的一个 windows-latest/node22 分片检查;不影响任何代码行为与用户;属 CI 误报(同一 lane 在并发 master 运行中绿过,Windows CI flake: local-HTTP test promises strand mid-run ('Promise resolution is still pending'), victim test rotates — master itself red at 467e09ef6 #3530 证据在案)。
  4. 怎么修复的:rebase 到当前 master,让 PR 的 CI 使用含 Flaky Windows CI: issue1993-preflight-400 suite cancelled by early event-loop drain | Windows CI 偶发假红:preflight-400 测试进程提前退出致 5 例取消 #3665 有界重试的新 runner 脚本——该失败签名自动整片重试一次,重试绿即通过;文档改动本身零变化。
  5. 是否有回归问题:无。无代码/行为变更;唯一变化是分支基线前进到 master 最新(§7.2 本就要求合并前对齐最新 master),diff 相对新基线仍是原样 2 文件 +2/+2。
  6. 是否破坏缓存:不涉及。
  7. 是否改了设计方向:无。
  8. 是否引入了新的配置:无。

收工判定:分支已与 master 对齐、mergeable,等新 head 的 CI 跑完即可合并;若该 flake 再次触发,#3665 会自动重试吸收,若仍红则是确定性挂起、需要人工介入(届时我会再报)。

ci-check added 4 commits October 26, 2026 10:20
master window commits 293ae65/de5e03659 bumped kernel/package.json to
0.0.165 without regenerating the lockfiles; lock-sync re-resolution then
rewrites the stale recorded versions (root 0.0.163, kernel 0.0.164) and
fails. Pure recorded-version sync via npm install --package-lock-only;
no dependency or semantic change.
@ranxianglei

Copy link
Copy Markdown
Owner Author

(ai: sglang-gpu0/qwen3.8-27b)
本 PR 的全部内容已随合集 PR #5918 合入 master(2026-11-08),此 PR 重复,关闭。

@ranxianglei ranxianglei closed this Nov 8, 2026
Louie0806 pushed a commit to Louie0806/billion-context that referenced this pull request Nov 8, 2026
@github-actions github-actions Bot mentioned this pull request Nov 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Pi + claude-bridge: native sends no model requests to proxy; launcher compress returns 404

1 participant