Skip to content

[bug] Claude Code resume/分支永远命中不了 resume-inheritance:链哈希把 cache_control 断点算进去了 #2188

Closed

Description

@qiangu2020

现象

Claude Code 换 id 的 resume / 分支(claude --resume <parent> --fork-session --session-id <child>,经 bili claude 启动)从来不触发 resume-inheritance(#1486 / #1834 / #1850)。子会话从 0 个压缩块起步,父会话的折叠全部回到线上。

实例(bili 0.1.184):父会话 48 个块、上一轮 usage ≈ 118K;分支出来的子会话首轮原始历史 ≈ 295K tok,超过 200K 窗口 → 直接进 preflight(之后又撞上另一个问题,见 #2189)。本机所有 proxy 日志里 [resume-inheritance] 一次都没出现过。

根因

findResumeParent 要求子请求的链哈希在父深度处与父 tailHash 字节一致:

if (hashes[entry.depth-1] !== entry.tailHash) continue;

而 chainHashes / perItemHashes 用 stableStringify(message)(= JSON.stringify(sortKeys2(value)))把 cache_control 一起算进了哈希。

Claude Code 每个请求都会在「最后一条消息」和「最近一条 assistant 消息」的末尾 content block 上打 cache_control: {"type":"ephemeral","ttl":"1h"},断点随对话前移。所以:

  • 父会话最后一次 live 请求里,深度 depth-1 那条消息一定带断点(它就是当时的末尾消息);
  • 子会话 resume 后同一条消息已经不在末尾,断点被挪走 → 字节不同 → 链哈希从这一位起全部不同 → findResumeParent 确定性地返回 null。

这不是偶发,是所有 Claude Code resume/fork 的必然结果。0.1.185 的 chainHashes / findResumeParent / affinityMessageList(直接取 parsed.messages 原文)未变,问题仍在。

证据

  1. 最小复现(真 CLI + mock 上游,不需要 bili):Claude Code 2.1.289
    • claude -p "RUNTOOL please" --session-id S --allowedTools=Bash(mock 回一个 Bash tool_use → 第二个请求 4 条消息:user, system, assistant, user)
    • claude -p "second prompt" --resume S --fork-session --no-session-persistence(6 条消息)
    • 前 4 条逐条比较:msg0/msg1 完全一致;msg2/msg3 仅 cache_control 不同(live 请求断点在 msg2、msg3;fork 请求断点在 msg4、msg5);header 名集合相同。
    • 按 bili 算法(sha256(${prev}\0${stableStringify(m)})):父 tail 9ff6a532… vs 子 hashes[3] e3d99fc9… → 不匹配;两边去掉 cache_control 后 → 匹配。
  2. 真实长会话:用 stub 上游截获父会话 resume 后的请求(1019 条),与 prefix-affinity.json 里该父会话存的 128 个 itemHashes 逐位比较:127/128 相同,唯一不同的就是末尾那条(断点被挪走)。说明 Claude Code resume 重放的历史除断点外是字节级还原的,阻断匹配的只有 cache_control。

推测 tests/resume-ref-inheritance.test.ts(#1850)的 fixture 是无断点迁移的纯字节前缀,所以没覆盖到真实 Claude Code 的形状(未核实)。

建议

  • 链哈希规范化时剥掉 content block 上的 cache_control(以及 system 块上的,如果将来参与哈希)。它是传输层的缓存提示,不是会话内容。
  • 这会改变存量 prefix-affinity.json 的哈希:要么给条目加 hash 版本号、旧版本条目读取时按旧算法比较,要么接受一次性失效。
  • 回归测试:用「父 live 请求末尾带断点、子请求断点前移」的 fixture。

影响

所有 Claude Code 换 id 的 resume / 分支(CLI --fork-session、各类桌面端「分支」按钮)都丢全部压缩。父会话越依赖折叠撑在窗口内,子会话首轮越可能直接超窗 → preflight。

环境:macOS,Claude Code 2.1.288 / 2.1.289,bili 0.1.184(现场)/ 0.1.185(代码复核),anthropic 线,compress.modelContextLimit = 200000。

Activity

  1. ranxianglei commented on Oct 5, 2026

    @ranxianglei
    Owner

    🤖 Powered by ework · qwen3.8-27b

    [bot] 🏷 已修复并开 PR:#2191 — #2191

    先说查重:搜了 open+closed 的 issues/PRs,没有与本报告重复的条目(#1486/#1834/#1850 是 feature 原单、#2189 是另一条 preflight 问题,机制都不同)。你的根因分析我逐行核对过代码,成立且打到了核心。

    1. 是什么问题
    Claude Code 换 id 的 resume/fork(claude --resume <parent> --fork-session --session-id <child>,经 bili claude)永远触发不了 resume-inheritance:子会话从 0 个压缩块起步,父会话的折叠全部回到线上。不是偶发,是所有这类操作的必然结果。

    2. 什么原因导致的
    根因在 identity 哈希层,不在 resume 逻辑本身。src/prefix-affinity.ts 的 chainHashes/perItemHashes 用 stableStringify(message) 算链哈希,而它把 content block 上的 cache_control 一起算进去了。Claude Code 每请求把断点打在「最后一条消息」+「最近一条 assistant 消息」上并随对话前移 → 子会话重放的父历史里,原来带断点的那几条消息断点被挪走 → 字节不同 → 链哈希从该位起整体偏移 → findResumeParent 在 hashes[entry.depth-1] !== entry.tailHash 处确定性返回 null。我用最小 fixture 复现了同一形状:旧算法下 父 tail ≠ 子 hashes[depth-1](不匹配→null),剥掉 cache_control 后两者相等(匹配)——与你第 1、2 条证据同形。

    3. 怎么修复的
    在哈希规范化处剥掉 cache_control:新增 canonicalForHash(排序键 JSON + 递归删除所有 cache_control 字段),供 chainHashes 和 perItemHashes 共用。identity 链从此对断点位置不变,但仍要求真实内容逐字节一致。三个消费方(匿名解析 #309、identified 链跟踪 #1486、resume-fork 检测)都走这两个函数,一处修全覆盖;fork-adoption.ts 不做独立身份哈希、靠 resolver 的匹配,自动受益。stableStringify 保持不变仍导出(tool-ring.ts 还在用它做工具参数规范化)。

    4. 是否有回归问题
    既有行为逐项过:匿名前缀解析 / identified 链跟踪 / resume-fork 检测 / lineage(fork-LCP、truncated-run)/ 持久化 round-trip,语义都保持,只是哈希输入少了一个纯传输层字段。安全面:匹配依旧 sha256 逐字节,cache_control 不含会话机密,剥掉不降碰撞门槛。高危模式过一遍:无 fail-fast 变吞错、无阈值/默认值漂移(MIN_CANONICAL_BYTES=24 不变)、输出格式不变、不触碰转发给上游的 wire 字节(只改服务端内部哈希)。
    ⚠️ 一处有意行为变更(按政策披露):存量 ~/.local/state/billion-context/prefix-affinity.json 里升级前写入的链是「含 cache_control」算的,升级后与新格式 incoming 不再匹配 → 这些会话一次性 fork 成新的零状态会话,在其下一次 live 请求重新 note() 时自愈收敛。无假阳性(旧条目要误配需 sha256 碰撞)。我选了「接受一次性失效」而非加 hash 版本号——后者属 human-gated 持久化格式变更;若你想版本化,可另开 follow-up。

    5. 是否破坏缓存
    不影响 provider 前缀缓存或上游任何缓存策略——改动仅在 bili 服务端的 session-identity 哈希输入,不改转发字节,也不动 retry/dedup/增量游标。唯一的「失效」就是第 4 条那次性 affinity 链失效(自愈),非 provider 缓存。

    6. 是否改了设计方向
    没有。架构/边界/数据流不动,仍是「内容链是唯一不可变锚点」的设计;只是把锚点规范化从「含传输层提示」收紧为「仅会话内容」。

    7. 是否引入了新的配置
    无。没有新 env/config/默认值。

    收工判定:新增两个回归测试钉住机制(哈希对断点位置不变 + 断点前移仍命中父链),并验证了「旧算法必失配、新算法必命中」的牙口;本地定向套件(prefix-affinity / affinity-persist / resume-ref-inheritance)全绿 + typecheck clean,全量回归交 CI。可以合并。

  2. added a commit that references this issue on Oct 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workingp1

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions