Skip to content

[PR] docs: unified announcement surface — README/CONFIGURATION en+zh/AGENTS KDD/architecture map (#5548 P4) - #5565

Closed
ranxianglei wants to merge 10 commits into
masterfrom
2026-11-02_notices-docs-p4
Closed

[PR] docs: unified announcement surface — README/CONFIGURATION en+zh/AGENTS KDD/architecture map (#5548 P4)#5565
ranxianglei wants to merge 10 commits into
masterfrom
2026-11-02_notices-docs-p4

Conversation

@ranxianglei

@ranxianglei ranxianglei commented Nov 2, 2026

Copy link
Copy Markdown
Owner

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

Part of #5548 (unified announcement panel, design v2 approved) — phase 4 of 4, final. Stacked on #5557 (P1 registry) → #5561 (P2 local JSON) → #5563 (P3 remote + CI gate); merge those first, then this.

What ships (docs only, no code)

Verification: docs-only diff (6 files, +21/−2), gate script smoke still green (node --import tsx scripts/validate-remote-announcements.ts → OK), no code touched so no test/typecheck delta. Exit criterion from §七: 文档评审通过 — this PR is that review surface.

八问

  1. 是什么问题：四期收尾——把已批准的公告面设计落到全部文档面（README/CONFIGURATION en+zh/AGENTS KDD/architecture 模块图）。
  2. 什么原因导致的：Unified Announcement Panel Design (Approved): Built-in declarations + local JSON + remote GitHub raw — a single renderer | 公告面统一设计（已批准）：内置声明 + 本地 JSON + 远程 GitHub raw，三来源一套渲染器 #5548 §七 排期要求；P1–P3 已交付代码，文档是最后一块。
  3. 影响范围与严重程度：纯文档，零运行时影响。
  4. 怎么修复的：按设计 §五/§六 的既成契约写文档，不引入新语义；env 变量按「document or don't ship」纪律随本 PR 落 CONFIGURATION en/zh。
  5. 是否有回归问题：不涉及（无行为变更）；architecture.md 顺带补回了 [PR] fix(dsh): carry the thrown error's bounded stack into the gate refusal logs (#5067 option A) #5079 起缺失的 pck-notice.ts 行（修图不删图，ledger 只增）。
  6. 是否破坏缓存：不涉及。
  7. 是否改了设计方向：否——文档内容与 P1–P3 已合入代码逐条对应。
  8. 是否引入了新的配置：无新增——仅记录 P3 已出厂的 BILI_ANNOUNCEMENTS_URL（默认官方 raw 地址）与 announcements/ 目录。

ci-check added 4 commits November 3, 2026 00:27
ci-check
feat: unified announcement surface — built-in registry + single rende…
3166877 
…rer (lane A, #5548 P1)

Part of #5548 (approved unified announcement panel design, phase 1 of 4).

Converge the hand-copied panel banners (pck-default-off #5079, wm-fastpath-intro #5469) into one registry (src/notices.ts) with a shared record schema, kind-priority/tone/dismiss-mode pure functions, and one client render loop (textContent only, max 5 header banners + overflow list card). Overview payload now carries a unified notices array; new GET /__bili/notices endpoint. Dismissal store, endpoint and allowlist semantics preserved (allowlist widened to registered dynamic ids for lanes B/C). No config surface change.
ci-check
feat: local JSON announcements lane — validator, targeting gates, has…
ed69860 
…h-dismiss (#5548 P2)
ci-check
feat: remote GitHub raw announcements lane + CI validation gate (#5548 …
e287ec9 
…P3)
ci-check
docs: unified announcement surface — README/CONFIGURATION en+zh/AGENT…
53c4948 
…S KDD/architecture map (#5548 P4)
@ranxianglei ranxianglei mentioned this pull request Nov 2, 2026
Closed
@github-actions

github-actions Bot commented Nov 2, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-11-02_notices-docs-p4 (802aa1a)

Latest build — install this exact version

npm install -g billion-context@0.0.7927-pr.5565.8f61e31

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

Recent builds (commit → version)

commit version build
802aa1a billion-context@0.0.7927-pr.5565.8f61e31 build
76e9d2b billion-context@0.0.7925-pr.5565.78b28e1 build
f4b60ce billion-context@0.0.7924-pr.5565.9d1353a build
53c4948 billion-context@0.0.7921-pr.5565.ba08913 build

Download artifact

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

Install instructions are refreshed on each push.

@ranxianglei ranxianglei changed the title docs: unified announcement surface — README/CONFIGURATION en+zh/AGENTS KDD/architecture map (#5548 P4) [PR] docs: unified announcement surface — README/CONFIGURATION en+zh/AGENTS KDD/architecture map (#5548 P4) Nov 2, 2026
ci-check added 5 commits November 3, 2026 02:37
ci-check
fix: register BILI_ANNOUNCEMENTS_URL in config-docs seed + lifecycle …
e00013e 
…ledger (#5548 P3)
ci-check
Merge branch '2026-11-02_notices-remote-ci-p3' into 2026-11-02_notice…
f4b60ce 
…s-docs-p4
ci-check
docs: KDD #16 — remote feed shares update cadence+egress, not the thr…
76e9d2b 
…ottle (review fix)

The #5548 unified-announcement-surface PR (P4 docs) described the remote feed as
'搭自更新节流便车' (riding the self-update throttle piggyback). The code
(src/remote-announcements.ts) only reuses update.js's CHECK_INTERVAL_MS cadence
and egressDispatcher, on its own timer with its own warnOnce + last-known-good
failure path — its log line reads 'independent of auto-update'. Tightened the
phrase to state the two things actually shared (cadence + egress) so the spec
doesn't imply shared throttle/backoff. README already phrased this correctly.
ci-check
fix: de-export internal notice-surface declarations for unused-export…
89996f6 
… gate (#5548 P3)
ci-check
Merge branch '2026-11-02_notices-remote-ci-p3' into 2026-11-02_notice…
810f8ce 
…s-docs-p4
@ranxianglei

ranxianglei commented Nov 2, 2026

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

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

PR 审核结论：可合并（stacked——需先合 P1 #5557 → P2 #5561 → P3 #5563，再合本 PR）。纯文档 PR，我把 KDD #16 与四个文档面的每条具体断言都对照 P4 head 的代码逐条核实过，全部成立；发现并顺手修掉了 1 处「措辞与代码事实不符」（见末节，独立标注 commit）。

结构化八问

  1. 是什么：Unified Announcement Panel Design (Approved): Built-in declarations + local JSON + remote GitHub raw — a single renderer | 公告面统一设计（已批准）：内置声明 + 本地 JSON + 远程 GitHub raw，三来源一套渲染器 #5548 统一公告面四期收尾——把 owner 已批准的设计 v2 落到全部文档面（README/CONFIGURATION en+zh、AGENTS KDD release v0.1.5 #16、reference/architecture 模块图）。
  2. 为什么做：Unified Announcement Panel Design (Approved): Built-in declarations + local JSON + remote GitHub raw — a single renderer | 公告面统一设计（已批准）：内置声明 + 本地 JSON + 远程 GitHub raw，三来源一套渲染器 #5548 §七排期的最后一块；P1–P3 已交付代码，文档是收尾。
  3. 影响范围/严重度：纯文档，零运行时影响。
  4. 怎么做的：按 P1–P3 既成契约写文档，不引入新语义；env 变量按「document or don't ship」纪律随本 PR 落 CONFIGURATION en/zh。
  5. 是否有回归：无行为变更。唯一非纯文档效果是 architecture.md 补回 [PR] fix(dsh): carry the thrown error's bounded stack into the gate refusal logs (#5067 option A) #5079 起缺失的 pck-notice.ts 行——ledger 只增，且该行注释与其真实头注（shared dismissal store / id@hash16 / legacy bare-id compat）一致。
  6. 是否破坏缓存：不涉及。
  7. 是否改设计方向：否——文档与已合入代码逐条对应，未转向。
  8. 是否引入新配置：本 PR 无新增——仅记录 P3 已出厂的 BILI_ANNOUNCEMENTS_URL（path-relocation 类，缺省官方 raw）与 announcements/ 目录。

逐条核实（对照 P4 head 代码，均真）

  • 渲染器 renderAnnouncementBanners：textContent-only、零 innerHTML 外部数据、顶部最多 5 条（NOTICE_MAX_HEADER_BANNERS=5，client.ts:435；head/rest 在该边界切片，其余进面板列表 :495-501）。
  • 三源汇入同一 notices[]：GET /__bili/notices（admin.ts:448）+ overview（admin.ts:1403）；POST /__bili/notices/dismiss（admin.ts:446）。
  • A=BUILTIN_NOTICES（notices.ts，带 active(ctx) 评审门）；B 本地 ≤64KB（LOCAL_FILE_CAP_BYTES=64*1024）+ name:size:mtime memo + 坏文件 skip/warnOnce；C 远程 timeout 8s（FETCH_TIMEOUT_MS=8000）+ last-known-good 快照名 <cacheDir>/announcements-remote-snapshot.json + 失败不回抛。
  • 冲突 B>C>A（mergeNoticeLayers）；校验器上限 title≤120/desc≤600/hint≤300、ctaUrl http(s)≤200；targeting：since 闭/until 开、脏版本按数值体比、本地版本不可解析→带 gate 记录隐藏（宁缺毋滥）、percent=sha256(installId|id)%100、installId 为 state 目录持久化 uuid（不可持久化则隐藏而非闪动）。
  • 关闭三态：persistent（默认，键 id@sha16(normalized)，旧裸 id 仍生效，FIFO 上限 200）/ instance（进程内存）/ always（无关闭按钮、永不隐藏）；priority 阶梯 incident 90 > upgrade-advisory 80 > warning 70 > deprecation 60 > suggestion 50 > new-feature 40 > other 30，显式 priority 覆盖。
  • CI gate announcements-gate.yml 仅在触碰 announcements/remote.json 时触发、跑与客户端同一校验模块；scripts/validate-remote-announcements.ts 覆盖 schema+体量帽(512KB)+matcher 可解析性+时间格式；announcements/remote.json = {v:1,entries:[]}。
  • en/zh 同步核对一致；PR 引用的 12 个文件在 P4 head 全部存在。

发现并已修（小问题直接修 · 独立标注 commit）

  • KDD release v0.1.5 #16 一处措辞与代码不符：原文「fetcher src/remote-announcements.ts 搭自更新节流便车」暗示共享自更新的节流/回退机制；实际该 fetcher 只复用 update.js 的 CHECK_INTERVAL_MS（节奏）与 egressDispatcher（出口），用自己的计时器与独立的 warnOnce + last-known-good 失败路径——其日志明写「independent of auto-update」。README 侧本就写得准确（"fetched on the self-update cadence"），仅 KDD 这一句偏松。
    • 旧 → 新：搭自更新节流便车 → 按自更新同节奏(复用其 egress 出口、独立计时)。纯精度收紧、非语义变更；因属 owner 批准的 KDD 文本，单独标注供你复核。已推 commit 76e9d2bf7 到 PR 分支（fast-forward，远端 ref 已确认指向它）。同类措辞已全 PR 扫过，无其他实例。

diff 整洁度 / CI

6 个 .md 文件，无代码/test/lockfile/生成物改动，无无关变更。CI：docs-only，常规 test/typecheck/build 车道不受影响；announcements-gate 因本 PR 未触碰 announcements/remote.json 不会触发。按纪律未在本地预跑全量套件，全局判定交远程 CI。

判定：可合并（待 P1–P3 先落地后）。

@ranxianglei ranxianglei mentioned this pull request Nov 3, 2026
Closed
@ranxianglei ranxianglei mentioned this pull request Nov 10, 2026
Closed
@ranxianglei

ranxianglei commented Nov 10, 2026

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

🔶 需要决策
(ai: qwen/qwen3.8-27b)

Why I stopped (auto-fix lane, attempt 1/3): PR #5565 conflicts with master, but this is not a mechanical conflict — it is two mutually-incompatible implementations of the same #5548 announcement feature, one on each side. Resolving it requires choosing which implementation is canonical. That is a product decision, not a rebase, so I am not pushing anything to the branch; the PR is left untouched (still conflicting).

What I found (verified against live git this run):

Net effect: the PR's code is a stale snapshot of work master has since redone more completely, and most of its docs are already present in master's docs/. What may still be worth salvaging is likely small (a few doc rows + deduping KDD #16), but confirming "nothing unique is lost" before dropping the PR's code is a judgment call I will not make unilaterally.

八问（决策请求）

  1. 是什么问题: PR [PR] docs: unified announcement surface — README/CONFIGURATION en+zh/AGENTS KDD/architecture map (#5548 P4) #5565 与 master 冲突无法机械合并——不是普通文本冲突，而是同一 Unified Announcement Panel Design (Approved): Built-in declarations + local JSON + remote GitHub raw — a single renderer | 公告面统一设计（已批准）：内置声明 + 本地 JSON + 远程 GitHub raw，三来源一套渲染器 #5548 公告功能存在两套互不兼容的实现（master 一套、PR 一套）。
  2. 什么原因导致的: PR 于 2026-11-02(v0.1.212)分叉、11-03 完成 P1–P4；此后 master 独立落地了同一功能的另一套更新实现并持续一周 review fix（配置键改名、统一存储 dismissal、feed read bound、iot-thinking 警告），PR 分支未再同步 → 双实现并行分叉。
  3. 影响范围与严重程度: 仅本 PR 的合并被阻塞；不影响线上运行时（master 已有一套可用实现在跑）。严重度 = 阻塞级（该 PR 卡死），非线上故障。
  4. 怎么修复的: 尚未修复——需先定 canonical 实现（A/B/C）。推荐 A：master 为准，notices 源码全取 master，仅把 PR 净新增文档迁到 docs/ 布局 + 去重 KDD#16，丢弃 PR 过期代码模块；丢弃前逐项核对 PR 是否含 master 缺失的特性。
  5. 是否有回归问题（按选项）: A = 不引入回归（保留 master 既有行为，只补文档）；风险点 = 若 PR 确有独有特性而误丢会丢功能（故丢弃前必须核对）。B = 回退 master 已合并的新实现，可能丢一周 review fixes 与 iot-thinking，回归风险高。C = 融合过程本身有破坏两套既有行为的风险。
  6. 是否破坏缓存: 不涉及——dismissal 存储布局以所选 canonical 为准（A = master 的统一存储 kv_store namespace "notices"，不变）。
  7. 是否改了设计方向: 取决于选项——A 维持 master 既定方向（三来源 B>A>S shadow，KDD#16 已写入 AGENTS）；B/C 会改向 PR 的模块化设计。
  8. 是否引入了新的配置: 不涉及新配置键——BILI_ANNOUNCEMENTS_URL / remoteAnnouncementsUrl 两边都已有，master 文档已列。

Options

Option 方案 做法 工作量 主要风险
A（推荐） master 为准，PR 视为过期 notices 全部源码取 master；仅把 PR 净新增文档落到 docs/configuration.md(en+zh)/README/AGENTS(KDD#16 去重，master 已有英文版)/architecture map；丢弃 PR 过期代码模块与重复测试/CI gate；丢弃前逐项核对无独有特性丢失 小–中 误丢 PR 独有特性（用「丢弃前核对」兜住）
B PR 为准 以 PR 的 v2 架构为规范，删 master 分歧模块，把 master 独有的 iot-thinking 警告 + review fixes 移植进 PR，重写 consumer 到 PR API 大 回退 master 已合并的更新实现，回归风险高
C 融合两套 把 PR 的 v2 机制与 master 新增合为一套，需先明确目标架构 最大 融合本身有破坏两套既有行为的风险

Recommendation: A — master is newer, carries a week of review fixes plus a user-facing feature (iot-thinking warning) the PR lacks, and its own AGENTS KDD #16 already documents the target architecture; the PR branch went stale on Nov 3. Treat master as canonical, salvage only genuinely new docs, dedupe KDD #16.
Default if undecided: A.

Once you pick, I'll execute that option in a follow-up pass (it exceeds the small-mechanical scope of this auto-fix attempt).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

needs-decision

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@ranxianglei