Skip to content

[PR] feat(web): per-request cache hit-rate line chart with drop-cause markers - #3523

Merged
ranxianglei merged 3 commits into
masterfrom
2026-10-17_hit-rate-line-chart
Oct 20, 2026
Merged

ranxianglei merged 3 commits into
masterfrom
2026-10-17_hit-rate-line-chart

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What

Session detail page gains a per-request cache hit-rate line chart (issue #3484, item 1): fixed 0–100% axis over the ledger lines the detail API already returns, per-sample hover columns (seq · time · in · cached · missed · hit %), and drop-cause dots colored by ledger attribution — cold / comp / seam / PT (provider TTL) / PS (prompt-side) / rewind / client — with a legend that only shows causes actually present in the session.

This is the decision-independent part of #3484: it is contained in every scope option proposed in the issue thread, so it ships ahead of the owner's A/B/C pick for the global chart (item 2), which will land on this same branch/PR to keep one closed loop.

How

  • Data was already complete in session.metadata["cacheLedger"] and returned by buildSessionDetail; only the render layer was missing. No backend, wire, config, or persistence change.
  • New hitRateSvg renderer in src/web/client.ts, hand-rolled SVG like the feat(web): add zoom-to-selection (brush) to the session context-trajectory chart #2489 trajectory chart (zero runtime deps).
  • classifyLineCauses hoisted out of trajectorySvg so both charts share the exact same classification — hit-chart cause dots stay in lockstep with trajectory bands (asserted by test).
  • Fold/seam mark renderers and seq/time tick renderer extracted and shared between the two charts.
  • Brush zoom-to-selection (drag → zoom, reset via button / double-click / Esc) refactored into a makeChartZoom({elId,statusId,resetId,render}) factory used by both charts; the trajectory chart keeps its full zoom contract.
  • Golden tests/golden/web-hitrate/small-full.svg + regen script scripts/update-web-hitrate-golden.ts (mirrors the trajectory golden discipline).
  • i18n en+zh: det.hitrate, det.hitrate_sub, det.hitrate_empty, det.legend_hitline.

Behavior surface

  • Additive UI card on the session detail page (between the trajectory chart and the seam-events table). No existing view changed.
  • Trajectory chart output stays byte-stable against its golden (tests/golden/web-trajectory/small-full.svg) — the extraction was a verbatim move; verified by the existing feat(web): add zoom-to-selection (brush) to the session context-trajectory chart #2489 suite passing unchanged.
  • No wire/message-shape change, no config schema change, no kernel change, no default/threshold/timing drift.

Tests

Targeted local runs on the rebased head (full-suite verdict = remote CI):

tests/web-hitrate-chart.test.ts   3/3  (new: golden byte-stability, cause-dot/band parity, brush contract)
tests/web-trajectory-brush.test.ts 13/13 (unchanged, still green after refactor)
tests/web-i18n.test.ts            key parity green
npm run typecheck                 clean

Refs #3484

@github-actions

github-actions Bot commented Oct 17, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-17_hit-rate-line-chart (b20877d)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.4195-pr.3523.475b224

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-pr3523.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)

查重:不重复。 open+closed 全检索(hit-rate chart / hit rate line / cache trend):唯一实现命中率折线的就是本 PR,需求源头是 #3484 item 1(单会话折线);相邻条目 #2489(轨迹图)、#1557/#1856/#2795(账本归因)都是被复用的既有机制,不是平行实现。本 PR = #3484 item 1 的落地,方向与 issue 一致。

开始独立审核:拉分支核对 diff、验证「数据零后端改动」「轨迹图 golden 字节稳定」「提取是逐字搬运」三项声明、本地定向跑测试、看 CI。结论稍后按八问给。

awork added 3 commits October 17, 2026 18:07
Session detail page gains a hit% line chart over the per-request ledger
lines already returned by the detail API: fixed 0-100% axis, per-sample
hover columns, and cause dots colored by ledger attribution (cold / comp /
seam / PT / PS / rewind / client).

- new hitRateSvg renderer; classifyLineCauses hoisted out of trajectorySvg
  so both charts share the exact same classification (hit-chart dots stay
  in lockstep with trajectory bands)
- fold/seam mark and seq/time tick renderers extracted and shared
- brush zoom-to-selection refactored into a makeChartZoom factory used by
  both charts; trajectory output stays byte-stable vs its golden
- golden tests/golden/web-hitrate/small-full.svg + regen script
- i18n en+zh: det.hitrate / det.hitrate_sub / det.hitrate_empty /
  det.legend_hitline
…3484)

Same failure class as #1305/#2631/#2489 already pinned in this file:
Git-for-Windows' default autocrlf=true checked tests/golden/web-hitrate/
small-full.svg out CRLF, so the byte-equal golden gate failed every
windows-latest run (job 117352125307, test shard 22-1) while linux passed.
…dot (#3484)

A 1-line cold session drew an accent placeholder dot ON TOP of its own
cold cause dot (r=3 over r=2.5), so the dot read 'hit line' while the
hover column named the sample 'cold start'. Draw the accent placeholder
only when the sample carries no cause dot of its own.
@ranxianglei
ranxianglei force-pushed the 2026-10-17_hit-rate-line-chart branch from d5fc9da to b20877d Compare October 17, 2026 10:07
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

查重:不重复(首条已述)——唯一实现命中率折线的就是本 PR,源头 #3484 item 1。

① 原 issue 方向:#3484 item 1(单会话命中率折线,掉点归因着色)与本 PR 范围一致;item 2(全局折线)正确留待 A/B/C 拍板后落同分支。声明的「数据零后端改动」成立——diff 仅 6 个文件(client.ts / i18n.ts / harness / 新测试+golden+regen),数据确实全部来自 detail API 已有的 ledger.lines。

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

  • 轨迹图 SVG 输出:golden 字节稳定测试本地绿(web-trajectory-brush.test.ts 3/3),提取是逐字搬运(dt→fmtDT 等价替换不改字节)✅
  • 缩放/brush 契约:全视图不过滤 fold/seam、缩放按时间窗过滤、min-samples/全宽拖拽忽略、button/dblclick/Esc 三复位路径——原套件不变仍绿 ✅
  • Esc 键:从「只复位轨迹图」变为「复位任一缩放的图」——纯增量超集,只有轨迹图缩放时行为与原来一致 ✅(属有意变更,PR 已披露)
  • 离开详情页的重置路径:轨迹图语义等价(state/range 清空),扩展到 hit 图 ✅
  • i18n:纯新增 4 键 en+zh,parity 测试绿 ✅
  • wire / config / persistence / kernel:均未触碰 ✅

③ 代码审查:共享化做得对——classifyLineCauses/fold/seam/seqTick 提取后两图共用同一分类,cause dot 与 band 的同步是结构保证而非约定;makeChartZoom 工厂逻辑与原 traj* 函数逐段等价;无死代码、命名贴合现有风格、测试 seam(bili_hitSvg/bili_causes)沿用 #2489 惯例。

④ 测试有效性:3 个新测试有牙——golden 字节钉死渲染器漂移;parity 测试断言精确 cause 列表(Array(20).fill("comp") + tail 窗口退役点)不是恒真断言;brush 契约走真实事件派发覆盖太窄/全宽拒绝路径。

审核中发现的问题(均已处置):

  1. Windows CI 红(确定性,非 flaky)→ 已修 dbbdae354:新 golden SVG 是多行文件(title 内含真实 LF),但 .gitattributes 漏了 eol=lf pin——Git-for-Windows 默认 autocrlf=true 把它 checkout 成 CRLF,字节相等门禁在 windows-latest 必挂(job 117352125307 日志证实:expected 串里只有 golden 内容带 \r\n)。本文件早已为同一失败类 pin 过 trajectory golden(feat(web): add zoom-to-selection (brush) to the session context-trajectory chart #2489/test: wire-contract anti-regression system — parity fakes, goldens, unified ledger #1305/Windows CI 全红:#2610 新增的 bundle-patch 测试对 CRLF 签出的 yml 做字节级精确匹配(.gitattributes 未覆盖) #2631 先例),照抄一行修复。
  2. 单样本点颜色冲突 → 已修 b20877d85:只有 1 条 ledger 行的冷启动会话,accent 占位点(r=3)画在自己的 cold 归因点(r=2.5)上面,点读作「命中率线」而 hover 说是 cold start。现改为该样本已有归因点时不画占位点。
  3. PR 描述小误:tests/web-trajectory-brush.test.ts 13/13 —— 该文件实际只有 3 个 test(node 报告 3 pass,全绿)。正文数字请顺手更正(不影响代码)。
  4. 观察项(不拦):hit 卡图例按「分类器实际出现的 cause」显示,轨迹卡图例按「账本桶计数」显示——同一会话两卡图例集合理论上可不同(如账本计了 pt 但该行被分类为其它 cause)。 cosmetic,且改轨迹卡图例会动既有视图,不建议塞进本 PR。

rebase:分支原落后 master 18 提交;master 侧这 18 个提交与本 PR 六个文件零重叠,已 rebase 到 c9da03dd1(无冲突),rebase 后定向测试 16/16 + typecheck 干净,head 现为 b20877d85,CI 运行中(gates 已过,test lanes 跑着)。


八问:

  1. 是什么问题:Cache hit-rate line chart: per session and global | [Feature] 缓存命中率折线图:单会话 + 全局 #3484 item 1——会话详情页缺逐请求命中率走势视图,掉点原因只能看数字卡片猜。
  2. 什么原因导致的:非缺陷,功能缺失——数据(cacheLedger.lines 含 hitPct+归因字段)早由 codex 命中率问题分析 #2929/feat: cache-seam hardening — probes, property fuzz, production seam reporting, round-2 basis fixes #1606 备齐且 detail API 已返回,只差渲染层。
  3. 影响范围与严重程度:新增 UI 卡片,所有打开会话详情页的用户可见;不影响任何既有行为;纯增量。
  4. 怎么修复的:手写 SVG 折线图(固定 0–100% 轴),复用轨迹图的几何、分类器、事件标记与 brush-zoom 机制(提取为共享函数/工厂),golden 字节钉死防漂移。
  5. 是否有回归问题:无。轨迹图输出对 golden 字节稳定(提取逐字搬运+测试证明);zoom 契约、Esc、i18n parity 均不变或纯增量;唯一行为面变化是 Esc 现也复位 hit 图缩放(有意、已披露)。
  6. 是否破坏缓存:不涉及(纯前端渲染,不碰缓存/重试/游标/去重)。
  7. 是否改了设计方向:不涉及——沿用 feat(web): add zoom-to-selection (brush) to the session context-trajectory chart #2489 轨迹图的全部设计语言(几何/标记/brush/golden 纪律),未引入新依赖。
  8. 是否引入了新的配置:不涉及。

判定:代码可合——待 b20877d85 的 CI test lanes 转绿即合入(我盯着,绿了回一条确认)。item 2(全局折线)等 owner 在 #3484 拍板 A/B/C 后落同分支闭环。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

CI 确认:rebase 后 head b20877d85 全绿——6/6 test shards(ubuntu 22×3、ubuntu 24×1、windows 22×2)+ 全部 static gates,0 failure。之前红的 test (windows-latest, 22, 1)(CRLF golden)已随 .gitattributes pin 转绿。

收工判定:可合并。合并动作留给人工:#3523 (item 2 全局折线待 #3484 拍板 A/B/C 后落同分支)。

@ranxianglei
ranxianglei merged commit 1cc1cb8 into master Oct 20, 2026
40 checks passed
@ranxianglei ranxianglei changed the title feat(web): per-request cache hit-rate line chart with drop-cause markers [PR] feat(web): per-request cache hit-rate line chart with drop-cause markers Oct 20, 2026
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.669-master.1cc1cb8 (rolling master tag).

npm install -g billion-context@0.0.669-master.1cc1cb8  # 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.

1 participant