Skip to content

fix(#2626): key decompress image-mode dispatch on a valid imageRef - #2633

Merged
ranxianglei merged 1 commit into
masterfrom
2026-10-10_decompress-image-ref-dispatch
Oct 10, 2026
Merged

ranxianglei merged 1 commit into
masterfrom
2026-10-10_decompress-image-ref-dispatch

Conversation

@ranxianglei

Copy link
Copy Markdown
Owner

What & why

decompress carries two modes — text block/range restore and image recovery (#1995) — and they were dispatched on whether imageRef was present rather than whether it carried a valid value. Hosts and models emit "" / whitespace / null for optional fields, so decompress({blockId:"b1", imageRef:""}) jumped into image mode and returned the success-shaped [No restorable images right now …] receipt instead of restoring b1. The data never left the session, but callers read that receipt as "text restore done."

Fix

Key the mode selection on a non-blank value in the shared resolveDecompress resolver — the single entry point every wire/plugin lane funnels through (src/loop/core.ts executeProxyTool, src/stream.ts executeAnthropicProxyTool) — so one fix covers all lanes:

  • undefined / null / "" / whitespace → unspecified → fall through to block/range text restore.
  • non-blank string → image mode (the documented "list" / mNNNNN semantics are unchanged).
  • non-string non-null (number/object/boolean/array) → loud param error, instead of silently defaulting to the image list.

Behavior change (old → new)

input before after
{blockId:"b1", imageRef:""} image-list receipt (bug) restores b1 text
{blockId:"b1", imageRef:" "} image-list receipt (bug) restores b1 text
{blockId:"b1", imageRef:null} image-list receipt (bug) restores b1 text
{blockId:"b1", imageRef:42} image-list receipt (bug) FAILED: imageRef must be a string
{imageRef:"list"} / " LIST " image list image list (unchanged)
{imageRef:"m00042"} image restore image restore (unchanged)
{imageRef:""} (no blockId) image-list receipt FAILED: blockId is required

No change to any documented image call; no new config / knob / env / CLI surface; no schema or wire-shape change (goldens untouched).

Scope note (deferred item from the issue)

The issue's suggested item 4 — add wording to the advertised imageRef schema description noting blank = omitted — is deliberately not included here. The existing description already documents "list" as the enumeration keyword (it never said "" means list), so post-fix behavior matches the documented contract; editing that string would force regeneration of the three wire-contract golden files and escalate this clean single-module bugfix into a human-review-required wire-shape change. Happy to add it as a trivial follow-up if you want the explicit wording. Item 5 (Pi-side stripping of optional empty fields) is unnecessary — the shared-resolver fix already covers every lane.

Tests

New tests/decompress-image-ref-dispatch.test.ts pins every routing case against the real resolver (valid block + empty/whitespace/null imageRef → text restore; invalid types → param error; list/padded/any-case and concrete refs still reach image mode). Updated the one assertion in tests/image-restore.test.ts that pinned the old empty==list behavior. Typecheck clean; targeted decompress / image / wire-contract suites green on the rebased head; full suite via CI.

Closes #2626

@github-actions

github-actions Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

📦 Built Package Artifact

Branch: 2026-10-10_decompress-image-ref-dispatch (9435154)

Option A — Install this exact build (recommended)

npm install -g billion-context@0.0.2857-pr.2633.8fdb173

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

Install instructions are refreshed on each push.

decompress carries two modes (text block/range restore vs image recovery) that
were dispatched on whether imageRef was PRESENT rather than whether it carried
a VALID value. Hosts and models emit ""/whitespace/null for optional fields, so
decompress({blockId:"b1",imageRef:""}) jumped into image mode and returned the
"No restorable images" receipt instead of restoring b1 — a success-shaped
receipt that made callers believe the text restore had completed.

Key the selection on a non-blank value in the shared resolveDecompress resolver
(every wire/plugin lane funnels through it): blank/null/undefined => unspecified
=> fall through to block/range restore; a non-blank string => image path
("list"/mNNNNN semantics unchanged); a non-string non-null value => a loud param
error instead of silently defaulting to the image list.

Closes #2626
@ranxianglei
ranxianglei force-pushed the 2026-10-10_decompress-image-ref-dispatch branch from 3f3dea5 to 9435154 Compare October 10, 2026 09:31
@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 这是我上一轮针对 #2626 开的 PR。按 [PR] 规则我没有重做,而是拉分支核对代码 + 查 CI。发现一处 Windows-only 的 CI 失败,定位后确认是陈旧基线(本 PR 分叉在 #2634 之前)带进来的既有 master 级 CRLF 故障(#2631),不是本 PR 引入的回归。已把 PR rebase 到当前 master(含 #2634 的 eol=lf 修复)并 force-push(lease 保护,未覆盖他人提交)。现在 PR mergeable=true,CI 在新 head 943515418 上重跑中。

① 审原 issue(方向关)

#2626(xiaozhu1337 报):空 imageRef(""/空白/null)抢占文本恢复路径,返回成功形式的图片列表回执却没恢复 blockId。作者把修法放在共享 resolver 的分派源头(把判据从「字段是否存在」改成「是否有有效值」),而不是在中途过滤 payload——这正是根因所在,通过「疏而非堵」的试金石(同样的根因换个形态出现,此修法仍成立)。方向正确。

② 回归审查(整体关)

触碰路径 = src/decompress-shared.ts 的 resolveDecompress 顶部那道分派门(函数体其余部分一行未动)。逐项过既有行为:

  • 显式 imageRef:"list"(任意大小写/带空白)→ 图片列表:保持(新测试钉住);
  • 合法 mNNNNN ref → 图片字节恢复:保持(tests/image-restore.test.ts 覆盖);
  • 无索引 + 具体 ref → 图片失败回执:保持;
  • 无 blockId 但带合法 imageRef → 图片模式、不触发 blockId 门:保持;
  • 省略 imageRef → 文本恢复:保持(基线用例);
  • 整块/range 恢复机制(toFile、restoredInline 标记、跨轮缓存):未触碰(gate 在这些逻辑之前就 return 了)。
  • 有意变更(已披露):空/null/纯空白 + blockId → 现走文本恢复;非空的非 string → 现显式参数错误;空/null + 无 blockId → 现报 blockId is required。这三处正是本 issue 要修的,且都已在 PR 描述披露。
  • fail-fast 没有被改成吞错——非法类型现在是显式报错(改进而非回归)。
  • 结论:无意外回归。

③ 代码审查(主关)

  • 分派逻辑对每一类输入都正确:undefined/null/""/纯空白 → 文本路径;非空 string → 图片路径;非空非 string → 参数错误。逐类 trace 过。
  • 用了 toolFail('[decompress FAILED: …]') —— 正确。这个前缀是 load-bearing 的:loop 的重复失败守卫和 plugin 模式的成功头检测都靠它识别失败(见同文件注释)。这里若误用 toolOk 会是隐蔽 bug。
  • 单一漏斗点核实:resolveDecompress 恰好两个调用方(src/loop/core.ts 的 executeProxyTool、src/stream.ts 的 executeAnthropicProxyTool);resolveImageRestore 是模块私有函数,仅被 resolveDecompress 调用。没有任何 lane 自带一套按存在性分派的副本 → 一处修改覆盖所有 wire/plugin 入口。grep 证实。
  • resolveImageRestore 内部的 raw==="" 兜底现在经 resolver 不可达(防御性死路,无害),保留即可,删除只会撑大 diff。
  • 安全面:无新增输入解析(仅 typeof/trim),只读分派。src 侧无 as any;新测试里的 as unknown as ProxyToolCtx 双重断言沿袭了既有 image-restore.test.ts 的写法,测试文件可接受、符合仓库惯例,不拦。

④ 测试有效性(质量关)

  • 新 tests/decompress-image-ref-dispatch.test.ts:8 个用例,断言有牙。文本路径用例通过真实 core.processTurn + applyRanges 造出真压缩块(非 mock)。双向钉死:空/null/省略 → 文本恢复(旧代码下会失败的真正回归测试),以及合法 list/ref → 仍进图片模式(防回归护栏)。用例 feat: persistent + namespaced sessions, multi-tenant session isolation, stream robustness #5 精确钉住行为变更(空 + 无 blockId → blockId is required);fix: post-merge review fixes + per-route context window + XDG config #6 钉住 42/true/false/{}/[] 的新参数错误。hermetic(BILI_PERSIST=0、随机 session id、一次性 XDG_STATE_HOME)。无恒真断言——每条都能区分新旧行为。
  • tests/image-restore.test.ts:原本钉住「空 == list」旧行为的那一条断言正确翻转为新契约,并补了空白用例。grep 确认全仓没有其它测试钉住旧的「空 == list」。
  • 能否兜底:能,双向都能抓住回归。

⑤ diff 整洁度

3 个文件,+172/-5,单一线性 commit,每一行都服务于本修法(gate + 其注释、聚焦的新测试文件、一条修正的断言)。无无关改动、无大规模空行/缩进扰动、无 lockfile/生成物连带变更。golden 未动(作者有意避开 schema description 措辞编辑以不升级为 wire-shape 变更——判断合理)。干净。

结构化八问

  1. 是什么问题:decompress 的两个模式(文本块恢复 vs 图片恢复)原来按「字段是否存在」分流,而非「是否有有效值」,所以宿主/模型给可选空字段填了 ""/空白/null 时,带 blockId 的调用误入图片模式、返回成功形式的图片列表回执,真正的文本块没被恢复——调用方会把这条成功回执误当「文本已恢复」。
  2. 什么原因导致的:根因在共享 resolver resolveDecompress 的分派门——旧代码 if (args.imageRef !== undefined) return resolveImageRestore(...),字段一存在(哪怕空值)就走图片分支;图片分支内部又把非 string/空值归一成 "" 再按 "list" 处理。属「按存在性而非有效性分派」,与 [Bug] OMP plugin: empty optional decompress range fields cause failures and unsupported-range retries #1712 修过的 startId/endId 空串语义同类,只是新加的图片分支没沿用非空判断。
  3. 影响范围与严重程度:所有走 decompress 的入口(Responses/OpenAI loop、Anthropic stream、各 plugin lane,均汇聚同一 resolver)。触发条件:带 blockId 的 decompress 同时传了空 imageRef 或非法类型。严重程度:特定条件下的功能性误导——文本块没恢复却收到成功回执,模型可能据此以为已完成而漏掉真正需要的历史(实测近期 11 次这类误分派)。数据不丢、会话不坏,非完全不可用。
  4. 怎么修复的:把分派键从「存在性」改为「有效性」,修在分派源头一处覆盖所有入口:未指定(undefined/null/空/纯空白)→ 落回原有 block/range 文本恢复;非空 string → 图片模式(保留显式 "list"/mNNNNN 的既有优先级与语义);非空非 string → 显式参数错误,不再静默默认成图片列表。改的是决策点本身,不是中途遮罩。
  5. 是否有回归问题:无意外回归。既有行为逐项保持(见 ②);fail-fast 未被改成吞错(非法类型现显式报错)。唯一行为变化就是本 issue 要修的三处,已披露。
  6. 是否破坏缓存:不涉及。decompress 是只读 copy-paste(块保持 active、缓存保留、重复 decompress 免费),本次只改模式分派,不动任何缓存/重试/增量游标/去重键。
  7. 是否改了设计方向:不变。仍是「一个工具两种模式」,只把分派键从存在性修正为有效性;未引入新的必填 mode 字段,未改变架构/边界/数据流。
  8. 是否引入了新的配置:否。无新 env/config/CLI/默认值。

行为变更披露(旧 → 新)

输入 旧 新
{blockId, imageRef:""} 图片列表回执(bug) 恢复该块文本
{blockId, imageRef:" "} 图片列表回执(bug) 恢复该块文本
{blockId, imageRef:null} 图片列表回执(bug) 恢复该块文本
{blockId, imageRef:42} 图片列表回执(bug) FAILED: imageRef must be a string
{imageRef:""}(无 blockId) 图片列表回执 FAILED: blockId is required
{imageRef:"list"} / mNNNNN 图片模式 不变

关于 PR 里明确排除的第 4 条(schema 措辞)

同意有意排除:现有 description 已把 "list" 写为枚举关键字、从未说 "" 等于 list,修复后行为与文档一致;改那行字符串会触发三个 wire-contract golden 重新生成,把这个干净的单模块 bugfix 升级成需人审的 wire-shape 变更。若要显式措辞,单独开 trivial follow-up 即可,不阻塞本 PR。第 5 条(Pi 端删可选空字段)确实不必要——共享 resolver 已覆盖所有入口。

CI 说明

新 head 943515418 上 CI 重跑中。之前仅有的两处失败(windows-latest Node 22/24)是 tests/issue2605-dsh-retry-patch.test.ts 里对 dsh.bundle.patch.yml 的 byte-exact 断言,因 Git-for-Windows autocrlf 把文件检出成 CRLF 而挂——那是 master 自 #2610 起就一直红着、阻塞所有 PR 必需检查的既有故障(#2631),与本 PR 无关。rebase 带入的 #2634 已用 .gitattributes 的 eol=lf + 测试内 replaceAll("\r\n","\n") 双保险修掉,故这两腿预期转绿;其余门禁(kernel/version/lane-guard、docs-sync、build-artifact、各 e2e lane)此前均已全绿。

判定

代码正确、单一漏斗点覆盖全入口、行为变更已完整披露、diff 干净无无关改动;Windows 失败系陈旧基线带入的既有 CRLF 故障,rebase 后应转绿。可合并——等 CI 在新 head 全绿即收工,我会盯到确认。

@ranxianglei

Copy link
Copy Markdown
Owner Author

🤖 Powered by ework · qwen3.8-27b

[bot] 🏷 CI 更新(接上一轮 review):rebase 后的 head 943515418 上 CI 现 22/24 绿、零失败。唯一还在跑的就是之前红的两腿 test (windows-latest, 22) / test (windows-latest, 24)——即 #2631 那处既有 CRLF 故障对应的测试。其余全部通过:ubuntu 全量 test(含本次 decompress 相关套件)、所有 e2e lane(codex/pi/dsh/opencode/registry)、以及 build-artifact、kernel/version/lane/pi-subagents-guard、docs-sync 等门禁。PR 保持 mergeable=true。

判定不变:可合并;rebase 带入的 #2634(.gitattributes eol=lf + 测试内 CRLF 归一)预期把最后这两腿转绿。等它们落地我确认即收工。

@ranxianglei
ranxianglei merged commit 51942ba into master Oct 10, 2026
34 of 35 checks passed
@github-actions

Copy link
Copy Markdown
Contributor

📦 Merged Build Published

This merge to master was published as 0.0.235-master.51942ba (rolling master tag).

npm install -g billion-context@0.0.235-master.51942ba  # 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-10_decompress-image-ref-dispatch branch October 15, 2026 05:33
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.

[Bug][decompress] 空 imageRef 抢占文本恢复路径,返回图片列表成功回执但未恢复 blockId(0.1.190)

1 participant