Skip to content

feat: 支持下载完整会话报告(Markdown + PNG 图片) - #3099

Merged
ranxianglei merged 5 commits into
masterfrom
2026-10-14_download-session-report
Oct 14, 2026
Merged

ranxianglei merged 5 commits into
masterfrom
2026-10-14_download-session-report

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

背景

#3057:会话详情页目前只有「下载缓存报告 .md」(仅覆盖缓存账本),无法一键导出完整会话报告(基本信息 / 用量统计 / 上下文轨迹 / ⚠缓存接缝事件 / 体稳定性 / 缓存经济学)。诉求:一个按钮直接下载、掩码用户 title 等隐私、最好是一张网页图片、AI(含视觉模型)能识别。

方案(路线 B:确定性渲染,非 html2canvas 截图)

详情页头部新增两个按钮:下载报告 Markdown 与 下载报告 PNG,两种格式都产出(Markdown 供精确数字/AI 文本阅读,PNG 供人看与分享)。

  • 新增纯函数模块 src/web/report.ts(零依赖、无 DOM、可在单测中运行),把六个板块渲染成 Markdown 与闭合矢量 SVG;SVG 由浏览器原生 Image+canvas 栅格化为 PNG —— 不引入任何新依赖。
  • 新增 loopback-only 管理端点 GET /__bili/session-report?session=&format=md|svg&mask=on|off&lang=zh|en,与既有 /__bili/cache-report 同构(返回 JSON {md} / {svg,w,h})。

隐私

title / label(用户 PII)默认掩码为「会话 <id>」;保留 upstream host、模型名与全部指标(诊断必需)。掩码默认开启,可用 ?mask=off 关闭。

约束核对

  • 零新增运行时依赖:report.ts 仅 import ./i18n.js;dist/index.js 保持零依赖(build 输出 dist-import-annotations: OK)。
  • 不改配置面:新端点是 loopback 管理路由,不是 config 字段 / env / CLI flag。
  • 安全:管理端点维持 loopback-only(继承 handleAdminRoute 门禁)。
  • 纯增量:仅新增按钮 + 端点,未改动任何既有行为。

验证

  • rebase 到当前 master(8bcdb7f61)后复跑:npm run typecheck ✅、npm run build ✅。
  • 定向测试 tests/session-report.test.ts 8/8 ✅(掩码开/关、两种格式、zh/en、确定性、空数据兜底、SVG 闭合矢量)。
  • 全量回归交由远程 CI。

Closes #3057

@github-actions

github-actions Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-14_download-session-report (731b21a)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.3611-pr.3099.3c8b773

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

Install instructions are refreshed on each push.

ranxianglei pushed a commit that referenced this pull request Oct 14, 2026
The det.seam_events i18n strings already start with a warning glyph in both locales, so the hard-coded prefix rendered '⚠ ⚠ 缓存接缝事件' / '⚠ ⚠ Cache-seam events' in both the Markdown and SVG reports. Remove the prefix from both render paths and pin it with a regression assertion. Found while reviewing #3099.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

PR 审核结论(独立重审,非复读 issue):方向与 owner 在 #3057 的拍板一致(路线 B 确定性渲染、md + png 两份),实现干净、纯增量、零新依赖。审核中发现 1 个外观缺陷已直接修掉并推到分支(见下)。整体判定:可合并(feat,按规矩由人合并)。

结构化八问

  1. 是什么问题:功能需求(支持下载缓存会话报告 #3057)——会话详情页原来只能下载「缓存报告 .md」(只覆盖缓存账本),无法一键导出完整会话报告(基本信息/用量统计/上下文轨迹/⚠缓存接缝事件/体稳定性/缓存经济学)。
  2. 什么原因导致的:不适用(新增功能,非缺陷修复)。缺口是既有 /__bili/cache-report 端点只产出缓存账本单一板块,详情页其余五个板块没有导出出口。
  3. 影响范围与严重程度:纯增量——详情页头部两个按钮 + 一个 loopback 管理端点 + 一个纯函数模块(+600/-0,未改任何既有行)。无受影响用户面;未合并前用户无感知。
  4. 怎么修复的:路线 B(确定性渲染,非截图):src/web/report.ts 纯函数(仅 import i18n,无 DOM)把六板块渲染成 Markdown 与闭合矢量 SVG;PNG 由浏览器原生 Image+canvas 对 SVG 栅格化(scale≈1.74、高度上限 14000,避开 canvas 尺寸限制),不引入任何依赖。新端点 GET /__bili/session-report?session=&format=md|svg&mask=on|off&lang= 与 cache-report 同构。隐私:title/label 默认掩码为「[已掩码]」,保留 upstream host 与全部指标;块摘要/handoff 正文不进报告。
  5. 是否有回归问题:逐项审过——① 安全门禁:实读 handleAdminRoute,新路由继承三重 loopback 门禁(tunnel header→403、非 loopback 源地址→403、不可信 Origin/Host→403),loopback-only 声明成立;② diff 为纯新增,触碰路径(server 路由分发、client 详情页 DOM、i18n 表)各自既有行为不变;③ 配置面未动(管理路由查询参数 ≠ config 字段/env/CLI flag);④ 本地复跑:typecheck ✅、build ✅(dist-import-annotations: OK,证实 dist/index.js 仍零外部依赖)、定向测试 8/8 ✅;⑤ 真实数据 smoke(非 fixture):取本机磁盘上的真实会话走 buildSessionDetail→两个 builder,六板块全部正常渲染、SVG 闭合矢量、掩码生效(title→[已掩码]、host 保留)。未发现回归。
  6. 是否破坏缓存:不涉及——未触碰缓存/重试/增量游标/去重任何逻辑。
  7. 是否改了设计方向:没有转向;完全沿用既有 cache-report 端点模式与详情页结构,只是把「报告导出」面从单板块扩到全量。
  8. 是否引入了新的配置:没有。?mask/?format/?lang 是端点查询参数,不是 env/config/CLI flag。

审核中发现并已修的小缺陷(小问题直接修):接缝事件板块标题渲染出重复警告符——## ⚠ ⚠ 缓存接缝事件 · N(md 与 svg 两条路径都中招,zh/en 皆然)。原因:report.ts 硬编码了 "⚠ " 前缀,而 i18n 串 det.seam_events 本身已带 ⚠。修法:删掉两处硬编码前缀(i18n 串是唯一来源)+ 在现有测试里加一条回归断言钉死。已作为独立 commit 推到 PR 分支:1f2cc6c80..4c418db20(fast-forward,2 文件 +4/-2,不想要可直接 drop 该 commit)。

顺带发现的小缺口(不拦,留你判断,未动代码):① 报告输出省略了 seam.providerTtl/seam.client 细分与 stability.tail(详情页有、报告没有)——完整性瑕疵,主数字都在;② 客户端按钮固定发 mask=on,UI 上没有解除掩码开关(端点支持 ?mask=off,可手动 curl)——符合「默认掩码」诉求,要不要给开关由你定。

CI:原 head 1f2cc6c 上多车道此前在跑(e2e-pi-codex-ws / e2e-native-dsh / e2e-dsh-plugin-lane / e2e-local-registry 等);我推了修复 commit 后 CI 会对新 head 4c418db 全量重跑,最终绿红以远程 CI 为准。分支基于当前 master(8bcdb7f),0 落后。

ranxianglei pushed a commit that referenced this pull request Oct 14, 2026
The det.seam_events i18n strings already start with a warning glyph in both locales, so the hard-coded prefix rendered '⚠ ⚠ 缓存接缝事件' / '⚠ ⚠ Cache-seam events' in both the Markdown and SVG reports. Remove the prefix from both render paths and pin it with a regression assertion. Found while reviewing #3099.
@ranxianglei
ranxianglei force-pushed the 2026-10-14_download-session-report branch from 4c418db to 4d53f46 Compare October 14, 2026 02:38
ranxianglei pushed a commit that referenced this pull request Oct 14, 2026
The unused-exports gate (#1440 P6) fails on this branch: ReportOpts/ReportData/SvgReport in src/web/report.ts are only referenced within their own file yet declared as exports. Drop the leading 'export' per the gate's prescribed INTERNAL_ONLY fix. No behavior change: admin.ts and the tests import only the two buildSessionReport* functions. Branch also rebased onto current master (6887bbd, +#3094; no file overlap with this PR). Found while reviewing #3099.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

CI 跟进(旧 head 4c418db 结果已到,红项已定位并修掉)

上一轮回复后 CI 跑完:25 车道中 24 绿(含全量 e2e、kernel-guard、config-surface-guard、各真实客户端 lane),唯一红项 unused-exports,它又导致依赖它的 test / static-gates 两车道被跳过(needs 链 fail-fast)。

根因(本 PR 引入,非既有问题):src/web/report.ts 导出了三个接口 ReportOpts / ReportData / SvgReport,但三者只在本文件内部引用(admin.ts 与测试都只 import 两个 buildSessionReport* 函数)——命中 #1440 P6 的 export-bloat 门禁(INTERNAL_ONLY)。已在 master(origin/master 干净通过该门禁)对照确认是 PR 引入,本地在两个 head 上复现了同一失败。说明:这不是对既有行为的回归,而是新代码违反了仓库自己的门禁,我在首审的静态审查里漏掉了这条(该门禁不看语义只看导出面),已补上。

修法:按门禁自身给定的 INTERNAL_ONLY 处置——删掉三个接口的前导 export(纯类型别名,零行为变化)。独立 commit,已推。同时把分支 rebase 到当前 master(6887bbd,新增的 #3094 只动 src/persist.ts + src/session.ts,与本 PR 零文件重叠)。

新 head 4d53f4638(feat + ⚠修复 + 导出修复,共 3 commit):本地已复跑 unused-exports 门禁 ✅、定向测试 8/8 ✅、typecheck ✅。远程 CI 对新 head 全量重跑中,绿了我再报最终结论;若还有红项我继续跟。

ework-agent added 4 commits October 14, 2026 11:17
Add one-click download of the complete session-detail report from the
web UI detail page (基本信息 / 用量统计 / 上下文轨迹 / 缓存接缝事件 /
体稳定性 / 缓存经济学):

- src/web/report.ts: pure, dependency-free, DOM-free builders rendering
  all sections as Markdown and as a closed-vector SVG (rasterizable to
  PNG by the browser without any new dependency).
- src/server/admin.ts: new loopback-only GET /__bili/session-report
  (?session=&format=md|svg&mask=on|off&lang=zh|en), mirroring the
  existing /__bili/cache-report endpoint. Title/label (user PII) masked
  by default; upstream host + metrics kept for diagnosis.
- src/web/client.ts: two buttons (Markdown / PNG) after the page header;
  fetches the server render and rasterizes SVG->PNG via native canvas.
- i18n zh/en keys + tests/session-report.test.ts (8 tests).

Closes #3057
The det.seam_events i18n strings already start with a warning glyph in both locales, so the hard-coded prefix rendered '⚠ ⚠ 缓存接缝事件' / '⚠ ⚠ Cache-seam events' in both the Markdown and SVG reports. Remove the prefix from both render paths and pin it with a regression assertion. Found while reviewing #3099.
The unused-exports gate (#1440 P6) fails on this branch: ReportOpts/ReportData/SvgReport in src/web/report.ts are only referenced within their own file yet declared as exports. Drop the leading 'export' per the gate's prescribed INTERNAL_ONLY fix. No behavior change: admin.ts and the tests import only the two buildSessionReport* functions. Branch also rebased onto current master (6887bbd, +#3094; no file overlap with this PR). Found while reviewing #3099.
… allowlist

#3099 adds src/web/report.ts, which references i18n keys via t()/tr() that the dead-key scanner (page.ts+client.ts only) never sees, and slices line/fold arrays for table tails. Both are array/code-level constructs, not string cuts — same class as the existing client.ts/conflict-watch.ts allowlist entries.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷

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

第三轮:CI 红项全部定位,PR 侧已修完,另立项一个 master 既有问题

上轮推送后 CI 的 3 个红 lane(test/ubuntu×2、windows)里共 6 个失败用例,逐一查证结论如下:

① 两个是 PR 引入的静态门禁违规(我静态审查漏掉,已在本分支修掉)

  • #1024 i18n 死键门禁:扫描器只读 page.ts+client.ts 收集引用,新增模块 report.ts 里的键全被当成死键。修法:把 report.ts 纳入引用扫描(t()/tr() 两种调用形)。
  • #816/#1615 家族门禁:report.ts 里 lines.slice(-12) / folds.slice(-15) 被原始负切片 lint 命中——这两处是数组取表格末 N 行,不是字符串切割。修法:按既有 client.ts/conflict-watch.ts 同款先例加白名单条目(注释标明 array receiver)。
  • 两者合计 +4 行测试文件,独立 commit 标注;本地 web-i18n+text-safe+session-report 36/36 ✅、typecheck ✅、build ✅(dist-import-annotations OK)。

② 四个 storage-render golden 失败 = master 既有问题,与本 PR 无关(证据链完整)

③ 分支已 rebase 到当前 master(1fcfe5260,期间 #3041/#3051 合入):无冲突;当前 head 7f81e5425。

CI 现状(写此回复时):29/33 绿——含 static-gates、unused-exports、全部 e2e lane;剩 4 条全量 test lane 仍在跑。本地已精确预测其结果:只会挂上述 ② 的 4 个既有用例,无其他失败。跑完我再补一条确认。

判定:PR 本体可合并(纯增量 web 功能,wire/存储零触碰;回归审查与上轮结论不变)。feat 类,合并留给你;若要一次看到全绿,建议先合 #3120。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷

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

CI 跑完了,与本地预测一致:

  • 33/33 lane 全部出结果。除 4 条全量 test lane 外全绿(含 static-gates、unused-exports、全部 e2e)。
  • 4 条 test lane 的失败已逐条核对 job 日志(ubuntu-24):6844 个用例中恰好只有 4 个失败,就是那 4 个 storage-render golden(chat/anthropic/responses/google),无一例外;其余 6820+ 全过。即本 PR 自身零回归失败。
  • 这 4 个既有用例在 #3120 合入后会转绿(该 PR 自己的 CI 还在跑最后几条 test lane)。

最终判定不变:可合并。feat 类留给你合;想一次看到全绿就先合 #3120,否则这 4 个红与本 PR 无关。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷

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

收工总结(本 issue 全部动作一览)

审核:独立复核通过——方向与 owner 拍板的路线 B 一致(确定性渲染,md + PNG 双格式);loopback-only 门禁、零新增依赖(build dist-import-annotations: OK)、title/label 默认掩码均逐条验证;真实磁盘会话冒烟渲染六板块正常。

本分支修掉的 3 个 PR 引入问题(独立标注 commit,均已推):

  1. 接缝事件标题 ⚠⚠ 双感叹号(report.ts 硬编码前缀 + i18n 文案自带)——含回归断言;
  2. unused-exports 门禁红:ReportOpts/ReportData/SvgReport 三个内部类型误加 export,去掉;
  3. 静态门禁配套:web-i18n 引用扫描纳入新模块 report.ts;家族门禁为两处数组取行加白名单(同 client.ts 先例)。

master 既有问题(与本 PR 无关,已单独处置):4 个 storage-render golden 失败,证据链完整(master worktree 与本分支 actual digest 逐字节相同;漂移仅限 metadata 段;根因 #3093 live-stamp 写入新字段未再生快照)。已立 #3118(来源标记 + [no-dispatch])+ 修复 PR #3120(再生快照,diff 限 4 文件 8 行),#3120 CI 已 31/31 全绿。

终态:分支已 rebase 到当前 master,head 7f81e5425,CI 除上述 4 个既有用例外全绿(job 日志核对:6844 用例恰好只挂这 4 个)。回归审查结论:纯增量 web 功能,wire/存储零触碰,无回归、不破坏缓存、不改设计方向、无新配置面。判定:可合并——feat 类留给你合;想一次全绿就先合 #3120。

@ranxianglei
ranxianglei merged commit 2720571 into master Oct 14, 2026
25 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.410-master.2720571 (rolling master tag).

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