Skip to content

[PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 - #5452

Merged
ranxianglei merged 2 commits into
ranxianglei:masterfrom
whickerpoplawski-arch:docs/responses-subagent-split-scope
Nov 3, 2026
Merged

ranxianglei merged 2 commits into
ranxianglei:masterfrom
whickerpoplawski-arch:docs/responses-subagent-split-scope

Conversation

@whickerpoplawski-arch

@whickerpoplawski-arch whickerpoplawski-arch commented Nov 1, 2026 •

Copy link
Copy Markdown

摘要

CONFIGURATION.md(及中文版)写着 BILI_SUBAGENT_SPLIT=0 会关掉两套 subagent-split 机制。这只在 anthropic 线路上成立。

Claude Code 走 /v1/responses 时由 instructionsFingerprintApplies() 路由——WIRE_CLIENTS → claude-responses 写死了 instructionsFingerprintKeyed: true,没有配置面,所以那边设 BILI_SUBAGENT_SPLIT=0 等于没设。本 PR 仅改文档:

  1. 在 ### subagentSplit 下补作用域说明(Responses 线路 / personaSplit / stableSystemAnchor)。
  2. 在配置总表 subagentSplit 行、环境变量表 BILI_SUBAGENT_SPLIT 行各加一句 Responses 无效提示(中英两份),方便查表的人看到。

基于上游 HEAD e226544f556712e33f3ef1d9fe5b4dc2b7715e15(包版本 0.1.211)。

改动位置(以该 HEAD 为准,不是 0.1.207 手册行号):

  • CONFIGURATION.md — 总表 subagentSplit(约 107);### subagentSplit @ 770;BOTH-mechanisms 句 @ 775 后的作用域说明;环境表 BILI_SUBAGENT_SPLIT(约 2011)。
  • CONFIGURATION.zh-CN.md — 对应四处(总表约 107,详述约 770/775,环境表约 1989)。

变更

  • CONFIGURATION.md / CONFIGURATION.zh-CN.md — Responses 作用域说明 + subagentSplit / BILI_SUBAGENT_SPLIT 表行 no-op 提示。

测试计划

  • 仅文档,无代码改动
  • 作用域说明准确:Responses 用的是 instructionsFingerprintKeyed,不是 claudeSubagentSplit
  • 配置表 + 环境表写明 Responses 无效,并指向作用域说明

Closes:

Clarify that subagentSplit / BILI_SUBAGENT_SPLIT only covers the
anthropic claudeSubagentSplit path; Responses fingerprint keying is
unaffected and needs personaSplit or stableSystemAnchor instead.
@ranxianglei ranxianglei changed the title docs: note Responses wire ignores BILI_SUBAGENT_SPLIT [PR] docs: note Responses wire ignores BILI_SUBAGENT_SPLIT Nov 1, 2026
@whickerpoplawski-arch whickerpoplawski-arch changed the title [PR] docs: note Responses wire ignores BILI_SUBAGENT_SPLIT docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 Nov 1, 2026
Put the Responses-wire no-op wording in the config-reference seed so
gen-config-docs produces the param-ref table text. Stops docs-sync from
wiping the hand-edited table rows on CI.
@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复。本内部 issue(#5455)对应已开的上游 PR #5452(文档),配套代码 PR 是 #5453(新增 personaSplit 开关)。两者是「代码 + 文档」互补的一对,不是重复项。本任务是审阅 #5452,不是重新实现(重开 = 违反「一 issue 一 PR」+ 重复立项)。

结论先行: #5452 的文档改动本身准确、干净、可合,但有一个合并顺序硬依赖——作用域说明里指向的 personaSplit / BILI_PERSONA_SPLIT 开关在 #5453 合入前不存在于 master。所以 #5452 必须在 #5453 之后合入,不能单独先合。

核心声明已逐行核实(对当前 master 代码):

  • anthropic 线路: src/server/handle.ts:1077(带 agent-id 对的 claudeSubagentSplit)和 :1097(无头 VS Code 构建的 order resolver)都被 opts.subagentSplit !== false 门控 → BILI_SUBAGENT_SPLIT=0 确实在 anthropic 线上关掉两套机制。✓
  • Responses 线路: src/server/handle.ts:1121–1183 分支里没有任何 subagentSplit 引用;Claude-over-Responses 走 :1153 的 instructionsFingerprintApplies(req.headers)。✓
  • src/session-id.ts:142 的 instructionsFingerprintApplies 只返回 resolveWireClientProfile(...).instructionsFingerprintKeyed,纯由 profile 决定、没有配置面;src/server/lane-decisions.ts:122 的 claude-responses 条目写死 instructionsFingerprintKeyed: true(按 x-claude-code-session-id 命中)。✓
    → 结论成立: BILI_SUBAGENT_SPLIT=0 在 Responses 线上是 no-op,文档纠正是对的。

结构化八问:

  1. 是什么问题: 文档说 BILI_SUBAGENT_SPLIT=0 关掉两套 subagent-split 机制,但那只对 anthropic 线成立;Responses 线上该 env 实际无效,文档没限定作用域,会误导设了这个变量的用户。
  2. 什么原因导致的: 两条线路走不同路由代码。anthropic 分支把 claude subagent 交给 claudeSubagentSplit/order resolver,且都挂在 subagentSplit 开关下;Responses 分支没有这个门控,Claude 是按 instructions 指纹键控(registry 写死 true)。文档当初只按 anthropic 路径写的,漏了作用域限定。
  3. 影响范围与严重程度: 仅文档,无运行时行为变化。受影响面 = 读了 CONFIGURATION.md 并设了 BILI_SUBAGENT_SPLIT=0、期望它也能停掉 Responses 线 persona 分叉的人——会静默不生效。严重度: 文档准确性/配置预期误导(p3~p2,无数据丢失、无崩溃);实际影响较小,因为逃生口存在(今天就有 stableSystemAnchor,#5453 后还有 personaSplit)。
  4. 怎么修复的: 纯文档。① ### subagentSplit 下加「Scope — anthropic wire only」说明,点明真实机制(instructions 指纹,非 claudeSubagentSplit)和两个逃生口;② 配置总表 subagentSplit 行 + 环境表 BILI_SUBAGENT_SPLIT 行各加一句 no-op 指引(中英);③ 同步 website/config-reference/server.yaml seed 让生成表一致(docs-sync 已过)。
  5. 是否有回归问题: 未动任何代码 → 无行为回归。改动文字逐条对照了两条真实代码路径,声明均准确。需 flag 的一点: 作用域说明把 personaSplit:false 列为逃生口,但该开关要等 [PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 合入才存在(见下)。
  6. 是否破坏缓存: 不涉及,纯文档。
  7. 是否改了设计方向: 不涉及,这是文档纠错。(配套 [PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 引入新开关且有意把它也覆盖到 codex 的指纹键控——那是 owner 批 [PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 时要权衡的设计点,不属于 [PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 #5452。)
  8. 是否引入了新的配置: [PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 #5452 本身不新增任何配置;它只是引用了 personaSplit/BILI_PERSONA_SPLIT,这两个由 [PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 引入(尚未进 master)。正是这个引用构成下面的硬依赖。

阻塞项(处理完再合):

  1. 合并顺序硬依赖: git grep personaSplit origin/master 确认 master 上只有既有的内部 flag personaOrderKeyed,没有 personaSplit/BILI_PERSONA_SPLIT。若先合 [PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 #5452,等于上线一份描述「尚不存在的配置项」的文档(文档随 npm 包 + web UI 一起发出去)。→ [PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 先合,[PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 #5452 后合。
  2. 冲突风险: 两个 PR 都改 CONFIGURATION.md 和 website/config-reference/server.yaml 的相邻区域([PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 在 subagentSplit 旁插 personaSplit seed;[PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 #5452 改 subagentSplit 的 desc)。后合的那个会撞冲突,需 rebase 收敛。
  3. 两者都 behind master: 都基于 e226544(v0.1.211);master 已在 f248a9e,v0.1.212 release 分支([PR] release v0.1.212 #5454/[PR] release v0.1.212 #5439)在途。两个 PR 都 mergeable_state: behind,合前要 rebase。
  4. CI(读镜像缓存,非 gh 轮询): [PR] docs: clarify that BILI_SUBAGENT_SPLIT is ineffective on the Responses pipeline | docs: 说明 Responses 线路上 BILI_SUBAGENT_SPLIT 无效 #5452 各 gate 全绿(static-gates/gate/lock-sync/lane-guard/docs-sync/config-surface-guard = success),test 分片仍在跑(0 failed / 6 pending),rebase 后看一轮即定;[PR] fix: use personaSplit to disable the instructions fingerprint fork in Responses | fix: 用 personaSplit 关闭 Responses 的 instructions 指纹分叉 #5453 还在跑(lifecycle-ledger-guard/docs-sync/gate 已过,test 分片因 rerun 部分 cancelled,0 failed)。

给 owner 的建议:

收工判定: #5452 文档质量合格、内容准确,但当前不可单独合——卡在 #5453 的合并顺序依赖上。按上面顺序推进即可闭环。

@whickerpoplawski-arch

Copy link
Copy Markdown
Author

感谢审阅。

同意合并顺序:先合 #5453,再 rebase 本 PR 后合入。本 PR 文档里指向的 personaSplit / BILI_PERSONA_SPLIT 确实依赖 #5453,单独先合会把尚不存在的配置写进发布文档。

两边目前都 behind master;等 #5453 合入后我们会 rebase 本分支并处理 CONFIGURATION.md / server.yaml 冲突。需要你那边帮忙 rebase 再说一声即可。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

收到,顺序一致:先合 #5453 → 再 rebase 本 PR(#5452)后合入,不单独先合。

刚查了当前状态:#5453 仍 open、未合入、behind master;#5452 同样 open/behind。所以 rebase 这一步现在还不能动——要等 #5453 真正合进 master(CI 全绿 + 你对 personaSplit 新开关拍板,含「也会关掉 codex 指纹键控」那个有意副作用)之后,再 rebase 本分支解掉 CONFIGURATION.md / server.yaml 的冲突即可。

按你说的,rebase 这步你们来;我这边随时待命,需要我代跑 rebase + 解冲突就说一声。在那之前本 PR 维持 hold、不单独合。

@ranxianglei

Copy link
Copy Markdown
Owner

🤖 Powered by ework · qwen3.8-27b

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

这条与你上一条内容相同(重复投递,无需重复处理)。状态没变:#5453 仍 open / 未合入,所以 rebase 本 PR(#5452)这一步现在还不能动。维持原判断——先 #5453、再 rebase 本 PR;rebase 你们来,需要我代跑 rebase + 解冲突就说一声。在那之前本 PR 保持 hold、不单独合。

@ranxianglei
ranxianglei merged commit a473894 into ranxianglei:master Nov 3, 2026
47 checks passed
@github-actions

github-actions Bot commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.1013-master.a473894 (rolling master tag).

npm install -g billion-context@0.0.1013-master.a473894  # this exact build
npm install -g billion-context@master  # always the newest merged build

npm view billion-context@master prints the current version at any time.

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.

2 participants