Skip to content

fix+docs: dsh sessions default to renderTags=none — no env var needed (#3198) - #3208

Closed
ranxianglei wants to merge 2 commits into
masterfrom
2026-10-15_render-none-dsh-docs
Closed

ranxianglei wants to merge 2 commits into
masterfrom
2026-10-15_render-none-dsh-docs

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Oct 14, 2026 •

Copy link
Copy Markdown
Owner

Closes #3198 (implements @Dog's item 3 「在不设置环境变量情况下修复」 plus the original suggestion 1 「document ACP_RENDER_NONE」).

Commits

  1. f2226ff48 docs — document ACP_RENDER_NONE as the dsh render-seam mitigation (CONFIGURATION.md en+zh, /acp-cache client-bucket hint in formatSeam(), web tooltip).
  2. 3d4b9bca5 fix — make the validated treatment the DEFAULT for dsh-stamped sessions.

Behavior change (explicit disclosure)

  • OLD: renderTags resolved ACP_RENDER_NONE > diagnostics.renderNone > false for ALL hosts; dsh users had to set the env var per host to avoid seams.
  • NEW: resolution is ACP_RENDER_NONE > diagnostics.renderNone > host-default(dsh:true, else false). A dsh-stamped session (x-bili-plugin: dsh header → sticky session.metadata.pluginAgent) renders none with NO variable set; every other host is byte-for-byte unchanged; an explicit file/env value (including explicit false) always beats the host default.
  • WHY: dsh re-serializes tag-shaped bytes in its own persisted history non-byte-stably, so every newly-tagged message breaks the upstream prefix cache on first resend. The issue's A/B measured exactly this: hit rate 85.6% → 91.2%, seams gone, folds still healthy (7 folds, net +12.8M tok). Making the treatment automatic removes the operator action that was the only cure.
  • Cost for dsh sessions: lose per-message ref citation in the model view (refs stay assigned internally; growth-gated nudges still list compressible ranges, so folding keeps working). One-time re-pay when the default first applies after upgrade (~23K tok in the A/B), then stable.
  • Scope discipline: dsh-only by evidence (KDD release v0.1.2 #9 permit-list precedent). Rejected alternatives: global default flip (would strip refs from every other host without evidence); inbound tag-canonicalization (undecidable legit-vs-mangled bytes, [bug] 插件透传会剥掉工具调用参数里的 render tag(arguments 流挂了 tag-echo 过滤器) #1039-class corruption risk).

What changed where

  • src/knobs.ts: renderNone(dshHost = false) — 4-tier resolution; an explicit file boolean is now honored both ways (previously only === true mattered).
  • All 10 strategy/prompt-decision sites pass the session's dsh flag (4 prepare lanes × strategy line + tagsOnly gate, 3 compact processTurn paths, injectSystem) — the NEVER-echo prompt follows the rendered tags ([bug] ACP 标签泄漏:<acp tokens=...> 标签被模型原样复述到回复正文,仅靠系统提示劝阻不足 #1881).
  • Tests: new tests/issue3198-dsh-render-default.test.ts (wire-level e2e: dsh default none / non-dsh unchanged / explicit-false wins) + knobs precedence tier test.
  • Docs: CONFIGURATION.md en+zh (config table row, diagnostics description, env table row, full entry).

Verification

Typecheck clean; build clean; targeted suites 59/59 green locally (issue3198-dsh-render-default, knobs-config-precedence, issue2483-render-strategy, cache-friendly-proxy, cache-seam-client-insert, cache-seam-detector, web-i18n). Full-suite verdict = the CI test lanes on this head.

Note: the investigation side of #3198 (exact byte-level break pattern) still awaits the reporter's raw seam-sample lines + control bili version; if those ever show SEAM-bucket attribution on ≥v0.1.197 builds, a follow-up issue will be filed per the escalation rule stated in-thread.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重: 不重复。检索 open+closed 的 ACP_RENDER_NONE / render-seam 相关条目(22 条命中):唯一在途的就是本 PR;#3198 是它的来源 issue(A/B 实验),#2483/#1747/#1882 等均为已关闭的历史修复/配置收敛,与本 PR「补文档 + 报告提示」的范围无重叠。无并列的重复文档 PR。

开始按 PR Review 规范审查:先拉取分支核对代码与既有行为,再核对 CI 状态,结论按结构化八问回复。

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-15_render-none-dsh-docs (3d4b9bc)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3687-pr.3208.5c60e65

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

Option B — Download artifact

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

Install instructions are refreshed on each push.

ranxianglei pushed a commit that referenced this pull request Oct 14, 2026
…3208)

The original commit edited the diagnostics.renderNone param row inside the generated bili:gen param-ref block without updating the single source of truth (website/config-reference/diagnostics.yaml, #2107); the docs-sync CI job (generate + git diff --exit-code) would revert the row and go red. Seed now carries the row text and regeneration reproduces the committed artifacts byte-for-byte (verified locally).
@ranxianglei
ranxianglei force-pushed the 2026-10-15_render-none-dsh-docs branch from f6c36a0 to cb93f6c Compare October 14, 2026 17:42
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

PR #3208 审核结论(方向关 / 回归关 / 代码关 / 测试关全过,发现并修复 1 处缺陷)

① 原 issue 方向核实:#3198 的 A/B 数据与 OP 原文一致(对照 85.6% → 实验 91.2%,seam 消失);机制成立——dsh 在自己重发的历史里重渲染 bili 注入的标签,字节漂移产生缓存缝,ACP_RENDER_NONE=1 从源头去掉注入。「建议 2 归因半边已发布」的说法也核实过:v0.1.197 随 #3027 落地的 client arm(src/cache-ledger.ts:822-847)对入站指纹对的任何中段失配触发(insert 或 rewrite),记 prov:"client" 并有显式 warn 日志——PR 描述无夸大。

② 回归审查(既有行为逐项):

  • /acp-cache 报告:新提示行只在 client 桶有样本时出现(在 if (r.seam.client.count > 0) 块内),其余报告文本零变化 ✓
  • 段标题 insert → insert/rewrite:与代码事实一致(该 arm 对改写同样触发),测试宽松正则 /CLIENT MID-HISTORY REWRITE/ 仍匹配 ✓;旧措辞全仓仅存于 cache-ledger.ts 注释与该行本身,无 web/测试引用残留 ✓
  • i18n:仅扩 det.attr_client_tip 的值(en+zh),不加 key,键集不变(web-i18n 套件绿)✓
  • 配置 schema、持久化格式、wire 形态、kernel、自动更新路径:零触碰 ✓

③ 发现并已修复的缺陷(独立标注 commit cb93f6c8e):原提交把 diagnostics.renderNone 参数行(CONFIGURATION.md/.zh-CN.md 生成块 bili:gen param-ref 内)直接手改,但没更新唯一真源 website/config-reference/diagnostics.yaml(#2107 纪律)——CI 的 docs-sync job(generate + git diff --exit-code)会把这两行还原回旧文案并变红。已在 PR 分支补 commit:seed 写入同一文案,重新生成后与已提交产物逐字节一致;本地按 CI 同命令复现 docs-sync 绿。手写区(env-map 块外的 ACP_RENDER_NONE 条目)不受此约束,保持原样。

④ 基线与验证:分支落后 master 181 个提交(其中 706508a3d 恰好动过 cache-ledger.ts 的 client arm 区域),已 rebase 到当前 master 并核对全部 hunk 语义完好;本地 typecheck 干净、定向 5 套件 50/50 绿(cache-seam-client-insert / cache-seam-detector / knobs-config-precedence / issue2483-render-strategy / web-i18n)。已 push(rebase + seed-fix 两笔),全量回归以推送 head 上的 CI test lanes 为准。

行为变更披露(旧→新+原因):

  • /acp-cache CLIENT 段:新增一行 render-tag check (#3198) 提示(仅 client 桶非空时)——让看到症状的人直接找到开关;
  • 同段标题 (host-side insert — NOT a bili seam) → (host-side insert/rewrite — NOT a bili seam)——对齐代码事实;
  • web client 桶 chip tooltip 双语各加一句指向 ACP_RENDER_NONE=1——仅 tooltip;
  • 无新配置项:ACP_RENDER_NONE / diagnostics.renderNone 均既有键、语义未变。

结构化八问

  1. 是什么问题:A/B experiment: ACP_RENDER_NONE=1 (renderTags=none) eliminates dsh render seams — hit rate 85.6% -> 91.2% #3198 证明了 ACP_RENDER_NONE=1 能消除 dsh 渲染缝,但该缓解手段此前无处可查——文档只写了「raw wire study mode」,诊断报告也不提示它。
  2. 什么原因导致的:默认 text-only 把 mNNNNN 渲染标签注入重建历史;dsh 重发时重渲染这些标签导致字节漂移(宿主侧 churn),缝是宿主自己产生的——本 PR 不治缝,治「用户不知道有现成开关」。
  3. 影响范围与严重程度:受益面 = 会在自有历史里重渲染 ACP 标签的宿主(dsh);纯 token 成本问题(命中率 ~5pp 落差),无正确性影响。
  4. 怎么修复的:三处文档化(CONFIGURATION en/zh 两处条目、/acp-cache 报告提示行、web tooltip 双语)+ 测试钉住提示行;提示行体例仿照同函数内既有的 render tags on echoed assistant text break session continuity on stateful upstreams (magpie / Claude Code), causing full-history cache misses #2483 stateful-upstream 提示。
  5. 是否有回归问题:无——上述②逐项审过;唯一实际风险(docs-sync 红)已在本轮修复并本地复现变绿。
  6. 是否破坏缓存:不涉及——纯文档与报告文案变更,缓存/重试/游标/去重逻辑零改动。
  7. 是否改了设计方向:不涉及。建议 2 的归因半边已在 v0.1.197 落地(feat: attribute client-side mid-history rewrites in the cache ledger (#3023) #3027),dsh 侧渲染稳定性属宿主侧改动,超出本仓库边界。
  8. 是否引入了新的配置:没有——均为既有键,语义未变,只扩了文档。

判定:修复后可合——待推送 head 上的 CI(docs-sync + test lanes)转绿即可由你合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

CI 状态补充(接上条「待 CI 转绿」):run 38608883073 上 40 个 check 38 绿 2 红——红的两个(test ubuntu 22/24 shard 2)是同一测试 zone live: marked upgrade-replacement fails fast on an occupied port instead of hopping (#3044),失败形态 listen EADDRINUSE: address already in use 127.0.0.1:18787(tests/port-zone-live.test.ts)。

判定:与本草稿无关的既有 CI 故障,非本 PR 引入——依据:

  1. 本 PR diff 只动文档/报告文案/i18n 值,与端口、自重启、launcher 零路径重叠;
  2. 同签名在 master 自身最近三次 CI 全红(CI 的端口占用/自重启 e2e 测试间歇性误红,拖住无关 PR 合并 #3206 floor 2 已记录),当前 master 无全绿基线;
  3. 已对该 run 执行 rerun-failed-jobs,同一测试再次以同一签名失败(区间占用是持续性的,非一次性偶发);
  4. 该失败域已有跟踪单 CI 的端口占用/自重启 e2e 测试间歇性误红,拖住无关 PR 合并 #3206(修复方向 PR ci: per-file zone-port bands for live suites + bounded TOCTOU retries (#3182/#3184/#3188) #3197:per-file zone-port bands + TOCTOU retry)与机制分析 CI 全量测试 shard-3 端口冲突:两个固定端口 attach 用例与同分片的监听泄漏邻居撞车,四平台全挂(#3144 暴露) #3207,我已在 CI 的端口占用/自重启 e2e 测试间歇性误红,拖住无关 PR 合并 #3206 下补充了本实例证据。

本 PR 自身验证面全部通过:docs-sync(seed 修复后绿)、static-gates ×4(typecheck/build)、kernel-guard / pi-subagents-guard / lane-guard / config-surface-guard / version-guard / lock-sync / docs-coverage / unused-exports、全部 e2e lane(registry×2、codex×5、dsh/opencode/pi native、image billing、OC V2 WS)、本地定向 5 套件 50/50。

收工判定更新:代码面可合;红灯是 #3206 家族的既有误红。两条出路任选——① 等 #3197 落地后本 PR 自然转绿;② 若你判断本 PR 验证面已足够,可忽略这两个已知误红 job 直接合并(合并后 master 的红灯与本 PR 无关)。按规则我不自行合并。

awork added 2 commits October 15, 2026 02:09
dsh re-serializes tag-shaped bytes in its own persisted history non-byte-stably, so every newly-tagged message breaks the upstream prefix cache on first resend (A/B: hit rate 85.6% -> 91.2% with renderTags=none). Make the validated treatment the DEFAULT for dsh-stamped sessions (x-bili-plugin: dsh -> sticky session.metadata.pluginAgent): renderNone resolution is now env > file > host-default(dsh:true, else false); an explicit diagnostics.renderNone (true OR false) or ACP_RENDER_NONE always beats the host default. All ten strategy/prompt-decision sites follow the same effective value (#1881: the NEVER-echo prompt follows the rendered tags). Refs stay assigned internally, so growth-gated folds keep working; cost is losing per-message ref citation in the model view for dsh sessions. One-time re-pay on upgrade for affected dsh sessions (~23K tok in the A/B), then stable. Docs: CONFIGURATION.md en+zh.
@ranxianglei
ranxianglei force-pushed the 2026-10-15_render-none-dsh-docs branch from cb93f6c to 3d4b9bc Compare October 14, 2026 18:13
@ranxianglei ranxianglei changed the title docs: ACP_RENDER_NONE documented as the dsh render-seam mitigation (#3198) fix+docs: dsh sessions default to renderTags=none — no env var needed (#3198) Oct 14, 2026
@ranxianglei

Copy link
Copy Markdown
Owner Author

触碰红线

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.

A/B experiment: ACP_RENDER_NONE=1 (renderTags=none) eliminates dsh render seams — hit rate 85.6% -> 91.2%

1 participant