Skip to content

feat: tiered release-notes visibility (#1870) - #1873

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-01_release-notes-visibility
Oct 2, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-01_release-notes-visibility

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Fixes #1870. Implements the design agreed in issue #1870: a tiered (routine | recommended), model-written release-notes channel + release gates + two visibility surfaces.

Why

The self-updater is a silent courier on native lanes: installed X → Y. Restart to finish. only reaches a log file pi/opencode/dsh users never open, so the disk runs new while the process runs old for days (real case observed on this machine). #1577 fixed advisory visibility the same way; #1870 extends the pattern to ordinary releases.

What

  • Companion payload release-notes/package.json (schema 1, mirrors advisories/ 搞一个自动强制更新,针对重大bug的版本 #1481): newest-first entries {version, date?, tier: routine|recommended, summary ≤400ch}, cap 20; seeded with 0.1.176–0.1.179. release-notes/README.md documents the process.
  • Auto-publish .github/workflows/release-notes.yml: validates the payload (semver, tier, summary, date, dupes, cap) and publishes the companion package on every release-notes/** push to master — version churn handled by CI, never by hand.
  • Release gates: release-manual.yml fails at dispatch time, release.yml re-checks before tag/publish, if the version being released has no entry — a stable release can no longer ship invisible. Prereleases (dev channel) exempt.
  • Watcher src/update-notes.ts: fetch + cache only (throttled by the updater's CHECK_INTERVAL_MS, 5s timeout, fail-open, never installs). Derives:
    • pendingRestart — disk version newer than the running process (the actionable case),
    • the user-side span — every release strictly newer than the running version, i.e. exactly what a restart buys them.
  • Surfaces (both read cached state; zero network on the hot path):
  • Config: releaseNotesCheck (default ON, env BILI_RELEASE_NOTES_CHECK), releaseNotesUrl (BILI_RELEASE_NOTES_URL); documented in CONFIGURATION.md + zh-CN.

Tier policy: recommended = worth restarting soon (correctness/cache/self-heal fixes). Critical defects stay in advisories/ (#1481) — this doc never claims critical.

Tests

  • tests/update-notes.test.ts (6): doc parsing/validation (bad entries skipped, broken doc = error, empty feed legal); span derivation (strictly-newer, ascending, invalid base = none); visibility matrix (pendingRestart beats all; recommended-only still visible; clean/garbage invisible); wording byte-stability; acp_status section content + clean-state byte-absence; panel line placement before footer, single footer, $-safety, clean-state byte-absence.
  • Full suite: 3572 tests / 3553 pass / 0 fail / 19 skipped. Typecheck clean.

Note for ework: per the issue, review-only — no implementation help needed.

The self-updater is a silent courier on native lanes: 'Restart to finish'
only reaches a log file, so disk runs new while the process runs old for
days. Ship a tiered, model-written release-notes channel and surface it
where users and agents actually look.

- src/update-notes.ts: watcher for the companion package
  billion-context-release-notes (same mechanics as advisories/, #1481):
  fetch + cache only, never installs. Derives the user-side span (every
  release strictly newer than the running version) and the restart-pending
  signal (disk newer than running).
- Surfaces: acp_status 'UPDATE READY/AVAILABLE (instance-level)' section
  with the full span; /acp panel one-liner before the footer (same
  stripper-safe slot + $-escape as the #1577 advisory line). Clean
  installs stay byte-identical to pre-#1870 output.
- release-notes/: companion payload (schema 1; routine|recommended tiers,
  model-written summaries, newest-first, cap 20) + process README.
- .github/workflows/release-notes.yml: validate + publish the companion
  package on release-notes/** pushes (mirrors advisories.yml, version
  churn handled by CI).
- Release gates (#1870): release-manual.yml checks the entry at dispatch
  time, release.yml re-checks before tag/publish — a stable release
  without a tiered entry fails the run. Prereleases exempt.
- Config: releaseNotesCheck (default ON, env BILI_RELEASE_NOTES_CHECK) +
  releaseNotesUrl (BILI_RELEASE_NOTES_URL); documented EN/zh.

Fixes #1870
@github-actions

github-actions Bot commented Oct 1, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-01_release-notes-visibility (58125b0)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.1868-pr.1873.219f2b3

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-pr1873.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

[bot] 🏷 开始 review PR #1870(tiered release-notes visibility)。按 PR Review 规范执行:先审原 issue #1870 方向,再回归审查 + 代码审查 + 测试有效性 + diff 整洁度。初步结论稍后给出,最终按结构化七问作答。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

PR #1873 review 完成(head 613326ea,base master@95a30be7,单 commit、13 文件 +866/−1)。CI 全绿(unit ubuntu/windows × 22/24、build-artifact、version-guard、hermetic registry e2e、pi/opencode/codex/dsh 四条真实 lane e2e 全部 success)。本地定向验证:tests/update-notes.test.ts 6/6 通过;semver.gt 对非法版本号的抛错行为已实测。

① 原 issue(方向关)

对照设计 #1870 逐条核对,三部分实现到位:

  • 发布侧:companion 包 billion-context-release-notes(schema 1,newest-first ≤20,routine|recommended,summary ≤400ch)+ CI validate/publish(workflow 与 advisories.yml 逐行同构,含 max(local,registry)+patch 的版本推导,git 里占位版本永不手改)✓;双 gate(release-manual dispatch 时 fail-fast + release.yml tag/publish 前复查,prerelease 按 *-* 豁免)✓;critical 仍归 advisories/(README 与 workflow 注释都声明本文档 never claims critical)✓
  • 用户侧:span = 严格新于运行版本的升序集合(「重启能买到的东西」),pendingRestart = disk>running,fetch+cache 复用 CHECK_INTERVAL_MS(180s,感知 BILI_UPDATE_CHECK_INTERVAL_MS),never installs ✓
  • 表面:acp_status UPDATE READY/AVAILABLE 段(完整 span;非 pending 时带手动 npm install -g 命令);/acp 面板一行插在 PANEL_BOX_FOOTER 前——复用 [follow-up #1483] Advisory visibility in native/plugin lanes: all three surfaces are effectively invisible #1577 的 stripper-safe 槽位,plugin.ts:872 的 $-escape 作用于插值后的整个替换串,远端文档里的 $&/$' 字节级存活(有测试钉住);与 ⚠️ CRITICAL ADVISORY 视觉区分(纯文本无 emoji 皮肤)✓
  • 非目标遵守:无 wire/turn 注入、无自动重启、只读展示 ✓
  • 验收标准:clean-state 两个表面字节不变(代码核实 + byte-absence 测试)、渲染正确性(测试覆盖)、gate 拦截(逻辑核实,fail-closed)、全套 0 fail(CI 绿;PR 声称 3572/3553 pass/19 skip,与 CI 一致)✓
  • 一处范围差:原 issue 发布侧的「GitHub Release 的 label 跟随 tier」未实现(Create GitHub Release 步骤无 label 接线)——请确认是否有意砍掉。

② 回归审查(既有行为清点)

  • src/acp-status.ts handleAcpStatus:既有各段(header/blocks/ranges/ADVISORY/blind-tunnel)顺序与内容未动;新段仅在 visible=true 时 push,否则零字节 → clean/最新安装输出字节不变。结论:保持(测试钉住)
  • src/plugin.ts /acp 面板:preFooter 机制未改(escape 在插值后对整个串施加,既有 advisory 行行为不受影响);新行条件 push,footer 单次渲染有测试。结论:保持
  • src/cli.ts main():尾部新增 watcher 启动(受新开关控制,默认 ON)。有意行为变更(旧→新):无此流量 → 启动 ~15s 后一次 registry GET,之后每 180s 一次;新增缓存文件 ~/.cache/billion-context/.release-notes-check;fail-open(fetch/parse 失败仅 warnOnce 一次,状态不变 → 不显示)。模块只 import findInstallDir/readDiskVersion 用于读取,不触碰任何安装机制。已在 PR 披露,属功能固有。
  • src/config.ts:两个新可选字段,优先级模式与 advisoryCheck/advisoryUrl 完全同构(env > file===false > 默认 ON);与 fix(#1815): warn on unknown top-level config keys with compress-placement hint #1817 unknown-key 警告兼容(键已登记进 FileConfig,不误报)。旧版 bili 读到新键会短暂 unknown-key 警告——配置新增的正常代价。
  • release-manual.yml / release.yml:gate 分别插在 Bump/push 之前和 tag/publish 之前,只读 release-notes/package.json,缺条目或 releases 非数组均 exit 1(fail-closed,正确方向);prerelease 豁免。既有正常流程(有条目)不受影响。有意变更,已披露。
  • CONFIGURATION.md / CONFIGURATION.zh-CN.md:各纯新增两行,EN/ZH 同步 ✓
  • release-notes/:新目录,结构与 advisories/ 同构(嵌套 package.json 随根 tarball 打包——advisories/ 现状相同,inert,无新风险)
  • wire / 两种压缩模式:零 wire 变更(plugin/proxy 模式均不受影响)
  • 高危模式逐项:无语义漂移;无 fail-fast 变吞错(gate 是 fail-closed,watcher 按设计 fail-open 且文档化);无阈值/时序/输出格式漂移(clean-state 字节不变);无缓存/重试策略静默失效。

③ 代码审查发现

  1. 【合并前应修】悬空指针:acp_status 段末 Live state: GET /__bili/status → update. —— 但 sendStatus(src/server.ts:6760)返回 {version, diskVersion, stale, autoRestartOnUpdate, advisory, inFlight, conflicts},没有 update 字段,且本 PR 不动 server.ts。advisory 先例指向真实字段(→ advisory.),这里会把照做的 agent 引向不存在的字段,测试还把这个悬空引用钉死了。两条路:(a) 一行改成 → stale / diskVersion(匹配本 PR 零 server 变更的定位);(b) 给 sendStatus 加 update: {pendingRestart, diskVersion, lastCheckAt, lastError}(可从 getReleaseNotesState() 取),指针变真,脚本还能拿到含 feed 健康度的活状态——会碰热文件 server.ts,你定。
  2. 【nit】死选项:ReleaseNotesWatcherOptions.currentVersion(src/update-notes.ts:231)声明后全程未读(cli.ts 仍传 VERSION);可见性派生实际由 getUpdateVisibility(runningVersion) 完成。删掉或注明用途。
  3. 【nit】防御缺失:getUpdateVisibility 里 semver.gt(diskVersion, runningVersion) 守了 diskVersion 没守 runningVersion——非法输入抛 TypeError(实测 semver.gt("0.1.181","dev") → TypeError: Invalid Version)。spanNotes 守了 base 而这条路径没守。实践不可达(VERSION 来自 package.json,fallback "dev" 需要 pkg 不可读,与磁盘可读矛盾),但导出的 API 加一行 semver.valid(runningVersion) 自洽。
  4. 【范围确认】label 镜像未实现(见 ①)。
  5. 【吹毛求疵】弱断言:tests/update-notes.test.ts 中 assert.ok(routineOnly !== undefined) 恒真(变量必然定义);周边实质断言足够,这行可删或换成对 routineOnly.span 的真断言。
  6. 【流程】config surface:PR 正文在 "Config:" bullet 下记录了两个新键,而非 AGENTS.md 要求的正式 "config surface" 小节。机制映射清晰(advisoryCheck/advisoryUrl 的同构镜像,载体由你在 发版可见性:分级标签的 release 元数据(模型撰写摘要)+ 用户版跨 span 更新说明 + acp_status //acp 面板送达「更新已就绪待重启」(#1577 延伸) #1870 拍板),不构成阻塞——建议正文补一句「为何现有表面表达不了」(答案:advisory 通道 critical-only,普通发版没有载体)。

处置说明:六条都能在本分支合并前一个 commit 内解决,故不单独立项(loop guard);按你「review-only」指示,我不直接推分支,留你处置。

④ 测试有效性

6 个测试都有牙:解析契约(bad-entry 跳过 vs broken-doc 报错 vs 空 feed 合法)、span 语义(严格新于/升序/非法 base 安全)、可见性矩阵(pendingRestart 压倒一切;仅 recommended 也显示;clean/garbage 不可见——钉住验收标准)、措辞字节稳定、两表面内容 + clean-state 字节缺席、面板位置/footer 唯一性/$& 存活。回归捕获力:gating 松动(visible 恒真)→ clean-state 测试抓;$-escape 退化 → dollar-summary 测试抓;span 排序翻转 → spanNotes 测试抓。缺口(不阻塞):没有驱动 runReleaseNotesCheck 打假 registry 的集成测试(throttle 文件写入/dispatcher 接线只在生产路径被覆盖);advisory 有 e2e-advisory-rollback 作同类参照,notes 后续可补一个类似 e2e——建议记为 follow-up,不阻塞本 PR。

⑤ diff 整洁度

单一线性 commit,13 个文件全部与本 PR 目的直接相关,无跑题文件、生成物、lock 漂移或空白噪音。干净。

结构化七问

  1. 是什么问题:native lanes 上自更新是「沉默信使」——下载完成信号只进日志文件,磁盘跑新版而进程跑旧版可以持续数天,用户/agent 无从知道「重启即完成」或「存在推荐更新」。
  2. 什么原因导致的:更新器的完成通知通道(日志行)与用户实际注视的通道(acp_status//acp 面板)错位;且不存在任何机器可读的发版元数据(版本没有面向用户的摘要/分级)。
  3. 怎么修复的:伴生发版说明包(机器可读分级摘要,CI 发布)+ 发版 gate(stable 无条目即失败)+ watcher(只 fetch/cache,派生 pendingRestart 与用户侧 span)+ 两个表面(acp_status 段、面板 footer 前行);可见性由「下载完待重启 或 recommended+」门控,重启即可清除,全程 fail-open。
  4. 是否有回归问题:审过的既有行为见 ②,均保持或有意图且已披露;高危模式逐项未命中。唯一缺陷是悬空指针(发现 1)——误导性的引用文本,不是数据/行为损坏,合并前修掉。
  5. 是否破坏缓存:否。零 wire 变更(prefix cache 不受影响);更新节流用独立文件(.release-notes-check),与 updater/advisory 节流互不干扰;会话持久化/去重未触碰。
  6. 是否改了设计方向:无转向——严格按 发版可见性:分级标签的 release 元数据(模型撰写摘要)+ 用户版跨 span 更新说明 + acp_status //acp 面板送达「更新已就绪待重启」(#1577 延伸) #1870(你本人设计)扩展 搞一个自动强制更新,针对重大bug的版本 #1481 的 companion-package 模式。一处范围差:原 issue 的 GitHub Release label 镜像未实现,请确认。
  7. 是否引入了新的配置:是——releaseNotesCheck(默认 ON,env BILI_RELEASE_NOTES_CHECK=0 禁用)与 releaseNotesUrl(env BILI_RELEASE_NOTES_URL;默认 = 已配置 registry 上 companion 包的 latest 文档,感知 BILI_UPDATE_REGISTRY);CONFIGURATION.md EN/ZH 已同步。新增机器全局文件:~/.cache/billion-context/.release-notes-check(节流时间戳)。新增 npm 包:billion-context-release-notes(CI 管版本,git 占位 0.0.0)。迁移:无需(默认 ON,一个 env 关闭)。

判定

修掉发现 1 后可合并((a)/(b) 任选;想要脚本化活状态就选 (b))。发现 2/3/5 为 nit,顺手修或留后续均可;发现 4 需你确认范围;发现 6 为流程建议。整体质量高:机制与 #1481 逐行同构、gate 位置正确、字节不变性有测试钉死、CI 全绿含四条真实 lane e2e。

)

The 'Verify release-notes entry' step ended its node -e double-quoted script with a stray backslash-quote (\\\" ), which bash parses as a literal quote INSIDE the script, leaving the -e string unterminated. Result: 'unexpected EOF while looking for matching quote', the step fails for every stable release before tag/publish, and node never runs. Both gates (release.yml before publish, release-manual.yml at dispatch) were affected; the PR's own green CI never exercised them because those gates only fire on a master release-branch merge/dispatch.

Fix: drop the backslash so the -e string closes cleanly and $VER is passed as argv[1]. Verified end-to-end by extracting each real run block and executing it: present version -> exit 0 ('entry ok'), absent version -> exit 1.
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

PR #1873 审查完成。结论先行:可合并 —— 三件事都打到根因、回归面干净、测试有牙。审查中发现 1 个阻断发版的缺陷,已按「小问题直接修」推回分支(commit 58125b08,已端到端验证),除此之外无需返工。

① 方向关:issue 要的是"例行更新从哑巴快递变成可见+可行动"。方案 = companion-package(沿用 advisory #1481 机制)+ 只读 watcher + 两个按需状态面,不打 wire/不自动重启/不动更新判定 —— 完全命中边界与非目标,修的是"可见性缺失"这个根因而非贴补丁。✓

② 回归关(逐项过触碰路径的既有行为):

  • src/update.ts(load-bearing updater):零改动。新逻辑独立成 src/update-notes.ts,只 import 只读 helper(readDiskVersion/registryUrlFor/CHECK_INTERVAL_MS)→ 判定/安装/下载路径不受影响,不触发 §5 no-op-release 前置。比 issue 建议的"update.ts 内新增 getUpdateState()"更稳。✓
  • handleAcpStatus(src/acp-status.ts):新段落在 upd.visible 门控下 push,清洁态零行 → 字节不变;既有 Nudge/STORE/RETRIEVAL/BLOCK SPANS/advisory/blind/unrecognized 各段未动。✓
  • /acp panel(src/plugin.ts):复用既有 preFooter→footer 前 .replace(PANEL_BOX_FOOTER,…) 槽位,footer 仍为最后一行 → endsWith(PANEL_BOX_FOOTER) stripper 锚不变;$ 转义是既有代码,自动覆盖新行;清洁态 preFooter 无新增 → 字节不变。✓
  • advisory(搞一个自动强制更新,针对重大bug的版本 #1481/feat: surface active advisories in acp_status, /acp panel and bili doctor (#1577) #1585):未触碰,critical 唯一权威源保持(release tier 仅 routine/recommended,parse 层直接丢弃 critical 条目)。bili doctor 未动。✓
  • 发现并已修的缺陷:两个 release gate(release.yml publish 前 / release-manual.yml dispatch 时)node -e "…\" "$VER" 结尾多一个反斜杠引号,bash 把 \" 当脚本内字面引号 → -e 字符串未闭合 → unexpected EOF while looking for matching '"',对每次稳定发版都失败且 node 根本不执行(发版阻断级)。PR 自身绿 CI 抓不到,因这两 gate 只在 master release-branch merge/dispatch 触发、不在 PR 的 ci.yml。已删反斜杠(单字符×2)并"抽取真实 run block 逐个执行"验证:present→exit 0、absent→exit 1。

③ 代码关:fail-open 贯穿(fetch/parse 出错只 warnOnce 不阻断);garbage diskVersion fail-closed(不 crash、不误报 pending);span 严格 newer+升序;slice(0,20) 与 producer ≤20 cap 双保险(spanNotes 反正重排,顺序无关);watcher 独立于 autoUpdate(关自动更新的机器也看得到 recommended)。无 as any/@ts-ignore,server 侧走 loggerLog。

④ 测试有效性:真测试、断言有牙。清洁态两面"字节缺席/无更新行"有钉;panel footer「恰好一次 + 更新行在其前」直接锚定 stripper;$ 转义用真实 replace() 元字符($&/$'/反引号)验字节存活;parse 层逐条 pin 错误串。唯一小瑕疵:describeUpdateReady 的 byte-stability 那条是"同一纯函数自比"(恒真、低价值),周边断言已足够,不拦。

⑤ diff 整洁度:13 文件全与本 PR 目的相关,无跑题/生成物/锁文件 churn,无大段重排。干净。✓

行为变更披露(Deliverables 第4条) —— 两处均为有意新增:

  1. 稳定发版现强制带 release-notes 条目:旧=可无说明直发;新=release.yml/release-manual.yml 缺对应 version 条目即挡下(prerelease/dev 豁免)。原因=issue 核心诉求(不发哑巴版本)。
  2. 新增默认开启 watcher:releaseNotesCheck 默认 ON,首查 15s、之后每 ~180s(CHECK_INTERVAL_MS)拉一次 companion 文档并读磁盘版本(纯只读、fail-open)。新键:BILI_RELEASE_NOTES_CHECK(默认开)/BILI_RELEASE_NOTES_URL(默认=companion 包@已配置 registry);en/zh CONFIGURATION 已同步。迁移:无需,默认即生效,想关设 BILI_RELEASE_NOTES_CHECK=0。

结构化七问:

  1. 是什么问题:例行自动更新下载完只在日志留一行,原生 lane(pi/opencode/dsh)看不到 → 磁盘新版/进程旧码长期并存,自动更新价值迟迟不兑现。
  2. 什么原因导致:更新器是"哑巴快递";送达面(acp_status//acp 面板)此前没有"待重启/有推荐更新"的可读状态,[follow-up #1483] Advisory visibility in native/plugin lanes: all three surfaces are effectively invisible #1577 只为 critical advisory 建了可见性、没覆盖例行更新。
  3. 怎么修的:companion 包承载分级+模型摘要 → 只读 watcher 缓存 running/disk/span → 两面按需渲染(visible 才出现,可被重启/安装消掉);发版侧加 gate 保证不发无说明稳定版。
  4. 是否有回归问题:无。update.ts 零改动;两面清洁态字节不变;stripper 锚/$转义/footer 均保;advisory/critical 权威源不动。(gate 引用 bug 属本 PR 新代码缺陷,已当场修复并验证。)
  5. 是否破坏缓存:不涉及。不碰 prefix cache/重试游标/去重键;watcher 自带 throttle 文件(cacheDir()/.release-notes-check),不干扰既有 advisory throttle。
  6. 是否改了设计方向:不涉及架构转向。沿用 advisory companion-package + 按需状态面模式([follow-up #1483] Advisory visibility in native/plugin lanes: all three surfaces are effectively invisible #1577/搞一个自动强制更新,针对重大bug的版本 #1481),只是套到例行更新;实现放独立模块而非塞进 update.ts 反而更贴单一职责。
  7. 是否引入新配置:是,见上「行为变更披露」第 2 条。

可选清理(非阻断):startReleaseNotesWatcher({ currentVersion }) 传入了 currentVersion,但 runReleaseNotesCheck 从未读取它(running 版本在送达面用 VERSION 取)——是个死参数,留着无害,你可自行删或保留。

判定:可合并。 唯一阻断性缺陷(gate 引用 bug)已以标注 commit 58125b08 推回并验证,其余无需改。你合之前留意一点:这次改动会让下一次真实稳定发版第一次真正跑到这两个 gate——若届时哪次发版漏写条目被挡下,那是预期行为,按 release-notes/README.md 补条目即可。

@ranxianglei
ranxianglei merged commit f7cc681 into master Oct 2, 2026
12 checks passed
ranxianglei pushed a commit that referenced this pull request Oct 2, 2026
The acp_status/panel tests render through the real process VERSION, so
their hardcoded 0.1.179-running spans broke on the first release after
#1873 landed (0.1.180): pull_request CI runs the merge tree, and PR #1896
inherited the red lanes. Derive the UI fixtures with patchBump(VERSION, ±n)
instead; pure-function tests keep the static ENTRIES (running is explicit
there). Adds a teeth assertion: at-or-below-running entries stay out of
the span.
@ranxianglei
ranxianglei deleted the 2026-10-01_release-notes-visibility branch October 15, 2026 05:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

1 participant