Skip to content

[PR] Snapshot Rendering Shadow Reconciliation: The outbound snapshot engine defaults to dry-run; alerts are raised only for m | 快照渲染影子对账:出站快照引擎默认干跑,机械可证错误才报警 - #3865

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-19_snapshot-shadow
Oct 20, 2026

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

这是什么

#3759 的出站快照引擎仍处灰度 0%(BILI_ROLLOUT_SNAPSHOT_RENDER)。本 PR 加一条影子对账车道,让它在每轮已折叠会话上干跑:

  • 每轮 armed turn 用引擎现算一份快照视图 → 与 legacy 实际出站比对分类 → 记账后丢弃
  • 出站字节零变化(shadow 永不改变发送内容),纯观测
  • 默认开启,这是灰度翻转前的全舰队干跑:error 率连续一版本 ≈0 才翻 rollout

分类纪律(用户定调 m37616:不是每个 diff 都报警,只有确切 bug 透出)

级别 类别 处置
info 覆盖压制/锚(预期差异) 只计数
warn 已知降级:seam-too-short/block-unanchored/storage-off 等(#3812 修过的保守门) 记 lastReason,不进 errors
error 机械可证:lost-tail(非覆盖客户端消息从视图消失)/duplicate(非锚消息重复)/unstable-prefix(同输入异视图) 计数+一次性 error 日志+面板报警

暴露面

  • GET /__bili/status → snapshotShadow: {enabled, watching, errors, worst}
  • web 会话列表逐会话 snapshotShadow: {turns, errors, lastClass, lastReason?} 字段
  • 诊断主题 snapshot-shadow(逐会话 blob,最多 40 条)—— banner 上 GitHub 一键上报按钮
  • 面板 banner:仅 errors > 0 时出现(i18n en/zh)

配置(用户要求:JSON 配置文件而非只有环境变量)

BILI_SNAPSHOT_SHADOW 环境变量 > 配置文件 snapshot.shadow 布尔 > 缺省 true

{ "snapshot": { "shadow": false } }

测试(打桩先行,6 组 5 绿)

  1. knobs 矩阵(env 全拼写 > file > 缺省 on)
  2. classifier 纯函数四形状(lost-tail=3/duplicate/unstable/干净 suppressed=2)
  3. e2e 干跑不改字节:shadow-off 基线 vs 默认开重跑,上游 bodies 逐字节相同+metadata 记账+render latch 不动+三暴露面全断言
  4. seam-too-short 降级记账(errors=0, lastClass=degraded)——修掉一个真 bug:降级时不应跑分类器(空视图会把所有消息判成 lost-tail 假 error)
  5. error 注入 → status 汇总 errors=2 + 诊断 blob 含 lost-tail
  6. opt-out 无记账

回归:snapshot-render 12/12、web-sessions 24/24、acp-status 7/7、tsc 0、docs 种子重生成(273 条)。

kernel-change: none

@github-actions

github-actions Bot commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-19_snapshot-shadow (05e9b1a)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.4574-pr.3865.6a1bd28

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-pr3865.tgz
npm install -g package

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title 快照渲染影子对账:出站快照引擎默认干跑,机械可证错误才报警 [PR] Snapshot Rendering Shadow Reconciliation: The outbound snapshot engine defaults to dry-run; alerts are raised only for m | 快照渲染影子对账:出站快照引擎默认干跑,机械可证错误才报警 Oct 19, 2026
@ranxianglei
ranxianglei force-pushed the 2026-10-19_snapshot-shadow branch 2 times, most recently from 4c48264 to 9307b27 Compare October 19, 2026 16:49
@ranxianglei

Copy link
Copy Markdown
Owner Author

master 的 unused-exports 门自 #3765(eada5e5)起就红(maskUrlForPublish 被孤儿化,三连 run failure)。本 PR 顺手修掉:去掉该函数与我这三个内部符号的 export,本地 gate clean(5 waived)。

…#3756 follow-up)

- snapshot-render.ts: buildView/maybeSnapshotView split; shadow lane classifies
  the would-be view against the legacy outbound (lost-tail / duplicate /
  unstable-prefix = mechanical error classes; degrade reasons = known costs,
  never errors), per-session snapshotShadow blob, snapshotShadowStatusWire
- knobs.ts resolveSnapshotShadow + config.ts snapshot.shadow (env
  BILI_SNAPSHOT_SHADOW > file > default ON)
- admin status JSON snapshotShadow aggregate; sessions list per-session
  counters; snapshot-shadow diagnostics topic; web banner with report buttons
  (i18n en/zh); docs seeds + generated reference

Fixes the rollout flip precondition: error rate ~0 across a full version.
…low-up)

Goldens pin wire+state bytes for the render/storage shape; the shadow
observability blob is orthogonal and covered by its own suite.
@ranxianglei
ranxianglei force-pushed the 2026-10-19_snapshot-shadow branch from 3288386 to 05e9b1a Compare October 19, 2026 17:35
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

冲突已解完,rebase 到最新 master(39fb841)后强推,PR 分支现指向 05e9b1a。

冲突来源:master 合入的 #3737(dsh-authored compaction)与本 PR 各自在「仅环境变量」表的表头同一位置插入了新条目——#3737 加 BILI_DSH_AUTHORED_COMPACTION,本 PR 加 BILI_SNAPSHOT_SHADOW。三个文件文本冲突:CONFIGURATION.md、CONFIGURATION.zh-CN.md、website/config-reference/env-only.yaml(文档种子)。代码零冲突,全部自动合并。

解法:三处均取并集——master 的 DSH 行保留在表首(维持其原有位置),PR 的 SHADOW 行紧随其后;en/zh/yaml 种子三处一致。

八问:

  1. 是什么问题:PR 分支与目标分支 merge state dirty,无法合并——两侧在文档表同一锚点各插了一行。
  2. 什么原因导致的:纯插入位置竞争(同表头下各加一个新 env 变量条目),非语义分歧;两行内容互不相关、无取舍。
  3. 影响范围与严重程度:仅文档渲染顺序,无行为影响;不解决则 PR 一直不可合并。
  4. 怎么修复的:rebase 到最新 master,三处冲突按「并集」解决(双方条目都保留),force-push rebase 后的头。
  5. 是否有回归问题:无。做了逐字节校验:rebase 后 diff master..新头 与原 PR diff 旧base..原头 完全一致,差异仅为 hunk 行号偏移 + DSH 行从「新增」变为上下文(master 已含)。文档种子与生成产物保持同步,未引入任何代码变化。CI 会在新头上重跑全套。
  6. 是否破坏缓存:不涉及(rebase 未改任何代码)。
  7. 是否改了设计方向:不涉及。
  8. 是否引入了新的配置:rebase 本身没有;PR 自有的 BILI_SNAPSHOT_SHADOW / snapshot.shadow 面不变,文档行仍在。

收工判定:冲突已清,等 CI 绿即可合并。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

收到。冲突 rebase 之后顺手复核了这个顺带修复在新 base 上依然成立:

  • src/log-mask.ts 的改动在 rebase 后原样保留(export function maskUrlForPublish → function maskUrlForPublish);
  • master 自 [PR] fix: cold load after provider switch recovers the session fold ledger across routes (#3399) #3765 后又前进了 10 个提交,重新查过:maskUrlForPublish 在 src/ 与 tests/ 里只有 src/log-mask.ts:137 一处模块内调用,没有新出现的跨模块 import——去 export 不会编译断;
  • 在 rebase 后的头(05e9b1a)本地跑了 node scripts/check-unused-exports.mjs:✓ clean (5 waived),与你报的一致。

也就是说这个修复随 rebase 无损带上了,CI 的 unused-exports 门应该在新头上转绿。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重:不重复。检索 open+closed issue/PR 无其他「出站快照影子对账干跑车道」的同类实现;本 PR 是 #3759(出站快照引擎灰度)/#3756 的直接后续,机制唯一,无并列重复项。

标签:scope/kernel(主体改动是出站快照渲染引擎的影子对账车道)+ p3(纯观测干跑、出站字节零变化;最坏情况是面板误报或延后灰度信心,非用户不可用)。不打 bug——本质是功能(观测面),仅附带两处小修(log-mask.ts 去 export、降级时不跑分类器)。

这是 @ranxianglei 的 PR(正文无 ework-agent-pr 标记),我按 PR Review 规范做独立审核,不复读 issue 结论。核对到 rebase 后头 05e9b1a(master base 39fb841):2 commit、18 文件、~682 行,核心在 src/server/snapshot-render.ts(+208)与新测试 tests/snapshot-shadow.test.ts(+350)。正在通读 master..head 全量 diff 并做既有行为回归清点,随后按结构化八问给出可合/拦判定。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

独立审完整个 diff(18 文件 ≈682 增,base 39fb841d3 / head 05e9b1a5d),并查了 head 的 CI 状态。下面不复读 issue 侧结论,是我逐段读码后的判断。

结构化八问

  1. 是什么问题:出站快照渲染引擎([PR] Snapshot rendering: proxy lane outbound prefix rendered from server-side canonical history; existing sessions immune to | 快照渲染:proxy 车道出站前缀从服务端正史渲染,存量会话对内核升级免疫(#3756) #3759/Snapshot rendering: proxy-lane outbound is now rendered authoritatively server-side; existing sessions are immune to ker | 快照渲染:proxy 车道出站从服务端正史渲染,存量会话对内核升级免疫(#3752 根治) #3756)灰度还停在 0%,本 PR 加一条“影子对账”车道——每轮已折叠会话用引擎现算一份快照视图、和 legacy 实际出站做机械比对分类、记账后丢弃,纯观测,目的是翻灰度前攒一份全舰队 error 率干跑证据。顺带修掉 master 自 [PR] fix: cold load after provider switch recovers the session fold ledger across routes (#3399) #3765(eada5e54)起 unused-exports gate 的红(maskUrlForPublish 等 3 个符号只被模块内用却仍 export)。

  2. 什么原因导致的:不是修缺陷,是补观测面——根因是“引擎要翻灰度,但没有默认可见的健康度量”。影子车道把“现算但不使用”的视图和真实出站对齐,让 error 率变成可量化的翻闸依据。gate 红则是 [PR] fix: cold load after provider switch recovers the session fold ledger across routes (#3399) #3765 引入的未使用导出被 unused-exports 闸门抓到。

  3. 影响范围与严重程度:所有 proxy(非插件)车道里折叠过至少一次的会话——默认开启后每轮 armed turn 多跑一次完整 buildView(store 读 + 逐行 parse + 链式 identitySig 比对),结果丢弃;pre-arm(还没折叠)会话完全跳过。体验零变化(出站字节被 e2e 逐字节钉死),代价是长会话每轮额外 CPU/store 读,可用 BILI_SNAPSHOT_SHADOW=0 或 snapshot.shadow:false 关闭。p3 观测增强,非功能回归。

  4. 怎么修复的:maybeSnapshotView 拆成只读纯函数 buildView(不碰 session.metadata)+ 编排器,live 路径逐行保留(degrade reason 走 r.reason 进 legacyFor,noteRender/delete 挪进 live 分支);分类器 classifyShadowForTest 机械判 lost-tail / duplicate / unstable-prefix,覆盖压制记 suppressed(info);noteShadow 里降级直接记 degraded+reason 就 return、不跑分类器——正是钉住的那个真 bug(空视图会把每条消息误判 lost-tail 假报警)。暴露面:status 汇总 / web 逐会话 / snapshot-shadow 诊断主题(≤40 条)/ banner(仅 errors>0,worst label 走 escapeHtml)。

  5. 是否有回归问题:逐项过了既有行为——(a) live 渲染路径(rollout 打开时)字节级不变 ✓;(b) plugin 车道仍最先 if (pluginMode) return clientMsgs 旁路 ✓;(c) pre-arm 仍直接返回 ✓;(d) /__bili/status 只加 snapshotShadow 字段、旧字段不动 ✓;(e) web 列表/详情新增可选字段且 gated on turns>0,旧消费者不受影响 ✓;(f) golden 两套 wire/state 字节钉 BILI_SNAPSHOT_SHADOW=0,不被新 metadata 污染 ✓。高危模式:无 fail-fast→吞错、无阈值/时序/输出格式漂移(出站字节被 e2e 钉死)、无缓存策略变化。唯一实质变化 = 第 3 问默认开启带来的每轮计算成本,有意、已披露,不是回归。 未发现无意回归。

  6. 是否破坏缓存:不涉及。shadow 不改出站字节(前缀缓存前缀稳定),不碰 messageRefs/游标/去重键;buildView 纯只读,不写任何持久化或增量状态。

  7. 是否改了设计方向:不涉及架构转向。沿用 Inbound markers: one declarative strip engine for all four wires (#2789, #2798, #2811 plan B) #2815 storage shadow → Storage wrap-up: 6 fixes + switch default mode to full (single PR) | 存储收尾六修 + 缺省模式翻 full(一个 PR 统一处理) #3818 full-default 同款“干跑→翻闸”纪律套到渲染车道;数据流是新增观测支线,不动既有压缩/出站主链。

  8. 是否引入了新的配置:是。env BILI_SNAPSHOT_SHADOW(0/false/off 关,1/true/on 开,垃圾拼写落 file/default 层)+ 配置文件 snapshot.shadow 布尔,缺省 true(开)。无需迁移,缺省即新行为;想回到旧的零开销设 false 即可。CONFIGURATION.md en/zh + yaml 种子双文档齐全(env-var / config-surface / en-zh-mirror 三条纪律都满足)。

测试有效性(④)

强,不是恒真/mock-only。最关键两条都有牙:跨两次 harness 的出站 body 逐字节相等(assert.equal(h.bodies[i], baseline[i]),shadow-on vs shadow-off baseline)直接钉住“永不改字节”;#3812 双“继续”形状端到端驱动断言 errors=0 / lastClass=degraded / lastReason=seam-too-short,钉住“降级不误报”这个 bug 修复。另有分类器精确计数双向、knob truth table 双向、三暴露面全断言。

diff 整洁度(⑤)

干净。唯一“越界”的行是 CONFIGURATION.md/.zh-CN.md 里 reference 整段重生成(issue 里的“docs 种子重生成 273 条”)顺带同步了 master 上早已漂移的 storage.unified 重复行和 sqliteAutoDownload #3788 文案——属 generated 文件、源头在 yaml、量小、确定性输出,判为可接受(其实是把 stale 生成物修正了),列出供你知情。CHANGELOG [Unreleased] 有对应 zh 条目。

kernel-change: none —— 确认 diff 无任何 kernel/** 改动。

两个不影响合并的外观级小项

在你自己这条 PR 上我没擅自 push,列出来你定夺(要的话我一并收):

  • tests/snapshot-shadow.test.ts unstable 用例里 const base = {...}; void base; 是个死变量(构造后立刻 void),可删(⑤b 无死代码)。
  • banner 的 worstTxt 用全角括号 (…),英文 locale 也会跟着显示(纯 i18n 外观)。

CI 现状 + 合并判定

head 05e9b1a5d 上 mergeable=true(无冲突)但 mergeable_state=blocked,顶层 status pending,test/e2e/static-gates 各 lane 当前显示 skipped——权威全量绿还没在这条 head 上产出。我的代码 + 测试审核通过;可合的前提 = CI 转绿 + 你人工合并(它加了 config schema snapshot.shadow + env var + web surface,是 feat 非纯 fix,按 §7.4 不走 auto-merge)。建议等 CI 跑完转绿再合。

@ranxianglei
ranxianglei merged commit a3590e1 into master Oct 20, 2026
79 of 116 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.635-master.a3590e1 (rolling master tag).

npm install -g billion-context@0.0.635-master.a3590e1  # 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

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant