Skip to content

feat: add per-client remediation hints to compression-conflict surfaces - #2220

Merged
ranxianglei merged 2 commits into
masterfrom
2026-10-06_conflict-remediation-hints
Oct 8, 2026
Merged

ranxianglei merged 2 commits into
masterfrom
2026-10-06_conflict-remediation-hints

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

Closes #2219

What

The compression-conflict surfaces told users WHAT happened (two compressors coexisting on one session) plus the generic imperative "keep exactly one compressor" — but no path to HOW. Answering correctly in the #917 board case (unannounced-rewrite — 2/55 incoming message(s) carry pre-turn refs of 217 known, user: "keeps warning, don't know what to do") required digging out four separate doc locations, none linked from any conflict surface.

This adds a short per-client remediation block to every conflict surface, keyed on the client identity already recorded at request time (#1426: x-bili-plugin header / wire UA fingerprinting):

  • src/conflict-watch.ts — new conflictClientOf(session) (pluginAgent wins; mcp falls through per #760b; clientHint exact scan-client names pass through, codex UA truncations normalize via isCodexClient), conflictRemediation(client) (one-line map: opencode / claude / codex / pi·omp / generic fallback), CONFLICT_DOCS_POINTER. formatConflictSection() gains an optional client param and appends Fix (<client>): … + the docs pointer; ConflictSummary gains clients[] (distinct resolved clients of sessions carrying events).
  • src/acp-status.ts — passes this session's resolved client into the section.
  • Web UI — banner renders one i18n line per distinct client (capped at 3 with an overflow note; unknown clients → generic hint; payloads without clients[] degrade to generic only); the per-session conflict card on the Sessions page shows this session's own hint (new conflictClient field in the detail payload). zh+en conflict.hint.* keys in src/web/i18n.ts.
  • src/launcher.ts — the pre-launch co-resident-plugin WARNING gains a fix (<client>) line from the same map.

Each hint is one line and points at CONFIGURATION.md → "Detecting other compression plugins (#1206)" for the full matrix instead of duplicating it.

Behavior changes (additive output only)

  • acp_status conflict section: +2 lines (blank + Fix … + docs pointer) whenever a session has conflict events — model-visible text grows slightly in that case only.
  • /__bili/status & /__bili/stats JSON: new additive field conflicts.clients (array; old consumers ignore it).
  • Session detail payload: new additive field conflictClient (absent when unresolvable or no conflicts).
  • Web conflict banner: new hint block between the summary line and the details pointer.
  • Launcher stderr: one extra fix (<client>) line after each co-resident WARNING.

No change to detection gates/thresholds (src/session.ts unannounced-rewrite detector untouched — it worked correctly in the reported case); no config surface changes. Both compression modes unaffected (display-only, no wire changes).

Tests

New tests/conflict-remediation.test.ts: client-resolution order (incl. mcp fall-through and the #1641 token-level codex UA guard), the hint map (one-line invariant, generic fallback for dsh/kimi/hermes/zcode), the section suffix (active AND historical branches), summarizeConflicts().clients, zh/en i18n parity + server-map↔web-key drift guard, and functional extraction of the browser hint block (per-client lines, cap-at-3, unknown→generic, both locales) plus wiring drift guards. Existing suites re-run green: conflict-lifecycle, web-conflict-banner, issue1206-thirdparty-scan, web-sessions, text-safe, acp-status, launcher.

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 收到,开始 review #2220(对应 issue #2219)。初查:PR head 3afec278 基于 5e43209(master 已前进约 40 个提交),GitHub 报告 mergeable=false(dirty)——存在与 master 的文本冲突;head commit 上暂无 CI check-runs。计划:拉分支逐文件审(冲突面既有行为 + 代码 + 测试有效性)→ rebase 到当前 master 解冲突 → 本地跑定向测试(conflict-lifecycle / web-conflict-banner / acp-status / launcher / 新测试)→ push → 按结构化七问给结论。稍后回最终结论。

@ranxianglei
ranxianglei force-pushed the 2026-10-06_conflict-remediation-hints branch from 3afec27 to efdf2d1 Compare October 6, 2026 02:32
@github-actions

github-actions Bot commented Oct 6, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-06_conflict-remediation-hints (03c7964)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2356-pr.2220.ab2c926

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

Install instructions are refreshed on each push.

@ranxianglei
ranxianglei force-pushed the 2026-10-06_conflict-remediation-hints branch from efdf2d1 to 33b5ac0 Compare October 6, 2026 02:35
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 进度更新

代码审查已完成,分支已 rebase 到当前 master 并重新验证:

Rebase(两次)

本地定向验证(rebase 后 head)

  • tsc --noEmit clean(首次失败是本地 kernel dist 过期,重建后过)。
  • 8 个定向套件全绿:conflict-remediation(新增)、conflict-lifecycle、web-conflict-banner、issue1206-thirdparty-scan、web-sessions、text-safe、acp-status、launcher —— 346 pass / 1 skip / 0 fail。

CI:新 head 已触发全套 10 个 workflow(CI ubuntu+windows × node22/24、kernel suite、e2e 各 lane),跑完给结构化七问结论。

注:master 仍在滚动(#2194 刚合),PR 状态 behind 不影响合并(GitHub 会带最新 master 出 merge commit);若合并前 master 再动且与 launcher 有交互,我会以 CI 结果为准再定向排查。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 Review 完成 — 结构化七问

PR: https://github.comranxianglei/billion-context/pull/2220 · 最终 head 3844207c(feat + 1 个 review 修复 commit)

1. 是什么问题:冲突表面(acp_status / web banner / session 卡片 / launcher)只告诉用户 WHAT(两个压缩器共存)+ 一句通用命令"keep exactly one compressor",没有 HOW。#917 board case 里用户反复看到 unannounced-rewrite 警告却不知道该做什么——正确回答要翻四个互不链接的文档位置。

2. 什么原因导致的:检测输出在"事件+通用劝令"处止步;处置知识分散在 README opencode 段 / CONFIGURATION.md claude 对齐 / BILI_CODEX_COMPACT / pi·omp 接管证据四处,没有任何表面链接它们。而客户端身份(#1426:x-bili-plugin header / UA 指纹)请求时已记录,却没被用于引导。

3. 怎么修复的:按已记录的客户端身份给每个冲突表面加一行处置提示(pluginAgent 优先、mcp 按 #760b fall-through、codex UA 截断经 isCodexClient 归一化、干净单 token 直通、未知→generic);提示 map 镜像文档锚点;所有表面统一指向 CONFIGURATION.md「Detecting other compression plugins (#1206)」完整矩阵而不复制。四个表面全部覆盖,zh/en i18n 齐全。

4. 是否有回归问题:无(逐项过过):

5. 是否破坏缓存:不涉及——display-only,未触碰 wire 字节、持久化格式、prefix-cache 键、重试/去重路径;本 PR 对 session metadata 只读。

6. 是否改了设计方向:否——沿用既有"冲突台账→人类可读文本"模式,只是把内容从 WHAT 扩展到 HOW,键值来自请求时已有身份;无新子系统/边界/数据流转向。

7. 是否引入新的配置:无——不加 env/config key/CLI flag;config surface 零变更。

行为变更披露(均为附加输出,PR body 已声明、逐条核实):acp_status 冲突节 +2 行(仅当事件存在)/ JSON 新增 conflicts.clients 与 conflictClient / web banner 新增提示块 / launcher 每 WARNING 多一行 fix。旧值→新值即"无该行→有该行",语义不变。

验证:最终 head 全套 CI 绿(CI ubuntu+windows × node22/24:typecheck + kernel suite + 全量 npm test + build;version-guard/lane-guard/kernel-guard/docs-sync/docs-coverage;e2e 全 lane)。git merge-tree 对当前 master 0 冲突(rebase 后 master 又前进 19 个提交,与本 PR 唯一重叠是 launcher.ts 的 Windows argv 修复与 SQLite WAL winner,均在不相交区域)。

判定:可合并 —— 请人工 merge:#2220

@ranxianglei

Copy link
Copy Markdown
Owner Author

冲突

ework-agent added 2 commits October 6, 2026 21:03
…2219)

The conflict surfaces told users WHAT happened (two compressors coexisting) plus the generic 'keep exactly one compressor' imperative, but no path to HOW — answering correctly required four separate doc locations, none linked from any surface (#917 board case: repeated unannounced-rewrite warnings, user had no idea what to do).

Add a one-line per-client remediation hint keyed on the client identity already recorded at request time (#1426):
- conflict-watch.ts: conflictClientOf() resolves pluginAgent ('mcp' falls through, #760b) then clientHint (exact scan-client names pass through; codex UA truncations normalize via isCodexClient); conflictRemediation() holds the opencode/claude/codex/pi/omp + generic map mirroring the doc anchors; CONFLICT_DOCS_POINTER. formatConflictSection() gains an optional client param and appends the Fix line + docs pointer; ConflictSummary gains clients[].
- acp_status passes this session's resolved client.
- Web banner: one i18n line per distinct client (capped at 3, unknown -> generic, old payloads without clients[] degrade to generic only); session-detail card shows its own client's hint (new conflictClient field in the detail payload).
- Launcher co-resident-plugin warning gains a 'fix (<client>)' line from the same map.
- i18n zh+en conflict.hint.* keys; tests pin resolution, the map, the section suffix, clients[], i18n parity/drift, and web wiring.

Guidance-only: detection gates/thresholds untouched (#2219 non-goal); no config surface changes.
…t is invisible to the #1024 i18n liveness gate

CI caught it: tests/web-i18n.test.ts only sees literal t("…") / zh("…") / data-i18n references, so "conflict.hint." + cl read as five dead catalog keys. Replace the key builder with an explicit switch of literal branches (same rendered output for every input; whitelist mirrors the server map); unknown/absent clients still fall back to the generic line.
@ranxianglei
ranxianglei force-pushed the 2026-10-06_conflict-remediation-hints branch from 3844207 to 03c7964 Compare October 6, 2026 13:05
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 冲突已解决 — 结构化七问

分支已 rebase 到当前 master(818d24e7,rebase 期间 master 又前进了 ~104 个提交),新 head 03c79640。GitHub 状态:mergeable: true / clean,全套 CI 绿。

1. 是什么问题:master 滚动后 PR 与目标分支文本冲突(dirty),无法合并。冲突集中在三个文件:src/conflict-watch.ts(3 处)、src/web/client.ts(1 处)、src/web/sessions-data.ts(1 处)——都是 master 侧 #2261(bili 自家 sibling 扩展不再被误报为第三方压缩器)与本 PR #2219(按客户端给处置提示)改到了同一区域。

2. 什么原因导致的:两个 PR 并行开发、先后落 master——#2261 在 formatConflictSection 脚注链里插入了 siblingsOnly 新分支并给 ConflictSummary 加了 sibling 字段,web banner 加了 risk_sibling 措辞;本 PR 在同一函数尾部追加 Fix 行/文档指针、同一结构体追加 clients[]。纯并发写热点文件,无语义对立。

3. 怎么修复的:逐 hunk 按意图取并集——imports 双保留;ConflictSummary 初始化同时含 sibling: 0 与 clients: [];banner 保留 master 的 risk 变量(含 sibling 分支)并在其后插入 conflictHintBlock(c.clients);sessions-data imports 并入 master 新增的 displayContextBest/ContextBest。另加一处跨分支语义修正:#2261 的 siblingsOnly 脚注说"没有第二个压缩器在跑,清台账即可",若紧跟一行 per-client "Fix …" 会与"无需处置"自相矛盾——故 Fix 行+文档指针在 siblingsOnly 时跳过(带注释说明原因)。

4. 是否有回归问题:无。#2261 的 sibling 分类行为(脚注四分支、kinds.sibling 计数、banner 措辞)原样保留;#2102 active/historical 标注、#1736 suspected 软脚注未动;检测门限零改动;两种压缩模式不受影响(display-only)。本地定向验证:typecheck clean + 9 套件(conflict-remediation/conflict-lifecycle/web-conflict-banner/issue1206-thirdparty-scan/web-sessions/text-safe/acp-status/launcher/web-i18n)366 pass / 1 skip / 0 fail;远端全套 CI 绿(CI 矩阵 + kernel suite + 全量测试 + build + 全部 e2e lane)。

5. 是否破坏缓存:不涉及——display-only,未触碰 wire/持久化/prefix-cache 路径。

6. 是否改了设计方向:否。唯一新增判断是 siblingsOnly 时省略提示块,属于把 #2261 与 #2219 的语义对齐,不改变任何数据流或边界。

7. 是否引入新的配置:无。

判定:可合并(状态 clean,CI 全绿)——请人工 merge:#2220

@ranxianglei
ranxianglei merged commit 5621457 into master Oct 8, 2026
21 checks passed
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.131-master.5621457 (rolling master tag).

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

@ranxianglei
ranxianglei deleted the 2026-10-06_conflict-remediation-hints 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

Development

Successfully merging this pull request may close these issues.

feat: add per-client remediation hints to compression-conflict surfaces (web banner / acp_status)

1 participant