Bug Report：多轮对话缓存失效

[cityblack1]

概要

通过 --resume 恢复一个已有会话时，每发起一个新的 user turn，
skill_listing 和 skill_discovery（learned-gap 触发的）这两类 attachment
都会被重新生成，并经由 reorderAttachmentsForAPI 浮动到本回合最新的
user 消息位置。与此同时，T1 写盘后的 transcript 在 T2 加载时丢掉了原本
inline 在 user 消息里的对应 <system-reminder> 内容块。

结果：T2 发往 Anthropic API 的 messages 数组里，T1 那条 user 消息的
content 形态与 T1 当时实际发出去的不一致。Anthropic 端按 prefix 哈希
做命中判断，于是从该消息往后整段失效，每回合都付一遍 cache write 的钱。

影响

• cache_read_input_tokens 长期只命中 Anthropic 服务端对 claude_code preset 的全局共享前缀（约 22K），命中率被压在 10%~76% 之间（轮数越多命中率越低）
• 用户每回合多付全量 prompt 的 cache write 成本
• 消息不连贯，导致模型 Agent 性能劣化

环境

• Claude Code 版本：<填你跑的版本>
• Node：<v?>
• 平台：Linux x86_64
• 模型：claude-opus-4-7

复现步骤（最小化）

1. 在系统层挂一个抓 HTTPS 的代理（mitmproxy 即可），让 CLI 的请求经过它：

   mitmdump -p 18080 -s capture.py        # 把 api.anthropic.com 的 POST body 落盘
   export HTTPS_PROXY=http://127.0.0.1:18080
   export NODE_EXTRA_CA_CERTS=$HOME/.mitmproxy/mitmproxy-ca-cert.pem

起一个新会话，发一条短消息：

claude -p "你好"

用相同的 sessionId resume，再发一条：

claude --resume <sid> -p "你好"

2. 此时 diff 两个抓到的 /v1/messages 请求体的 messages[] 数组，即可发现问题。

问题包demo

T1

{
  "messages": [
    { "role": "user", "content": "<available-deferred-tools>...</available-deferred-tools>" },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<system-reminder>\nNo high-confidence active skill was auto-loaded for this request.\nA learned skill was promoted for future turns: ...\n</system-reminder>" },
        { "type": "text", "text": "<system-reminder>\nThe following skills are available for use with the Skill tool:\n...\n</system-reminder>" },
        { "type": "text", "text": "<system-reminder>\n# currentDate\nToday's date is ...\n</system-reminder>" },
        { "type": "text", "text": "你好", "cache_control": { "type": "ephemeral", "ttl": "1h" } }
      ]
    }
  ]
}

T2

{
  "messages": [
    { "role": "user", "content": "<available-deferred-tools>...</available-deferred-tools>" },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<system-reminder>\n# currentDate\n...\n</system-reminder>" },
        { "type": "text", "text": "你好" }
      ]
    },
    { "role": "assistant", "content": [ { "type": "text", "text": "你好！..." } ] },
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "<system-reminder>\nNo high-confidence active skill was auto-loaded for this request.\nA learned skill was promoted for future turns: ...\n</system-reminder>" },
        { "type": "text", "text": "<system-reminder>\nThe following skills are available for use with the Skill tool:\n...\n</system-reminder>" },
        { "type": "text", "text": "你好", "cache_control": { "type": "ephemeral", "ttl": "1h" } }
      ]
    }
  ]
}

Usage 证据

回合	tokens_in	cache_read	cache_create	cache_hit
t1	6	22207	6979	76.1%
t2	6	22207	7008	76.0%
t3	6	22207	7038	75.9%

[claude-code-best]

main 和 1.10.0 都尝试修复了, 麻烦测试一下 @cityblack1

[cityblack1]

Cache 仍在 T2 失效（修复未覆盖该路径）

感谢修复！我在最新版本上又抓了一组 mitm 包验证，T3 及以后已经 OK（99.7% 命中），但是 T2 这一轮缓存仍然会丢失大约 6.7k tokens。

现象（来自 server 日志）

T1  你好            cache_read=22207  cache_create=7259  hit=75.3%
T2  你吃了吗？      cache_read=22207  cache_create=6752  hit=76.7%   ← 仍在重建缓存
T3  你为什么不吃？  cache_read=28959  cache_create=  74  hit=99.7%   ← 正常

如果只看 T3，会以为已经修好；但 T2 实际上把 T1 已经写入的那段 ~6.7k 缓存又重建了一次。

根因

messages[1]（即第一轮的 user turn）的 content 在 T2 请求里被改写了，不再等于 T1 发出去时的样子。

T1 发出的 messages[1].content 有 4 个 text block：

idx	内容
0	<system-reminder> — "No high-confidence active skill was auto-loaded ... A learned skill was promoted: learned-gap"
1	<system-reminder> — "The following skills are available for use with the Skill tool: ..."（很长的 skills 列表）
2	<system-reminder> — currentDate
3	"你好"（带 cache_control: ephemeral/1h）

T2 重放这同一段历史时，messages[1].content 只剩了 2 个 block：

idx	内容
0	<system-reminder> — currentDate
1	"你好"

也就是说 idx 0/1 那两个跟 skill 相关的 <system-reminder> 在第二轮被吞掉了。前缀变了，所以 T1 在 messages[1] 末尾打的 cache_control 断点对 T2 完全失效——必须从这里开始重建。

到了 T3，messages[1] 又跟 T2 完全一致（同样只剩 currentDate + 你好），结构稳定下来了，所以 T3 才能拿到 99.7% 的命中。Bug 没有彻底修复，只是从 T3 开始绕过去了。

修复方向

历史 turn 的 user content 应当原样持久化重放，而不是在每一轮都按"当前 turn 的注入策略"重新生成 system-reminder 块。当前实现看起来是：每轮只把"和当前 turn 相关"的 reminder（如 currentDate）注入到第一个 user message 里，其它 per-turn 的 reminder（skill 自动加载提示、skills 列表）在后续 turn 重放时被过滤掉了。

只要让第一轮 user message 的 content 在 T2/T3/... 中保持 byte-for-byte 一致，T2 就会和 T3 一样得到接近 100% 的命中。

Demo: 三个 turn 的 messages payload

为了方便复现，下面贴出三轮抓包里 messages 数组的结构（system / tools 三轮完全相同，省略；只保留差异部分）。

T1 — 006-...req.json（"你好"）

{
  "messages": [
    {
      "role": "user",
      "content": "<available-deferred-tools>\nEnterWorktree\n...\n</available-deferred-tools>"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<system-reminder>\nNo high-confidence active skill was auto-loaded for this request.\nA learned skill was promoted for future turns: learned-gap (...).\n</system-reminder>"
        },
        {
          "type": "text",
          "text": "<system-reminder>\nThe following skills are available for use with the Skill tool:\n\n- update-config: ...\n- keybindings-help: ...\n- simplify: ...\n- dream: ...\n- schedule: ...\n</system-reminder>"
        },
        {
          "type": "text",
          "text": "<system-reminder>\nAs you answer the user's questions, you can use the following context:\n# currentDate\nToday's date is 2026-04-25.\n...\n</system-reminder>"
        },
        {
          "type": "text",
          "text": "你好",
          "cache_control": { "type": "ephemeral", "ttl": "1h" }
        }
      ]
    }
  ]
}

T2 — 008-...req.json（"你吃了吗？"）— ❌ 缓存断点丢失

{
  "messages": [
    {
      "role": "user",
      "content": "<available-deferred-tools>\n...\n</available-deferred-tools>"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<system-reminder>\nAs you answer the user's questions, you can use the following context:\n# currentDate\nToday's date is 2026-04-25.\n...\n</system-reminder>"
        },
        {
          "type": "text",
          "text": "你好"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "你好！有什么我可以帮你的吗？" }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "你吃了吗？",
          "cache_control": { "type": "ephemeral", "ttl": "1h" }
        }
      ]
    }
  ]
}

与 T1 对比：messages[1].content 的 block 0、1（两条 skill 相关的 <system-reminder>）被丢弃，且 "你好" 这块原本带的 cache_control 也没了。前缀不一致 → T1 在此处打的缓存断点完全失效，需要重建 ~6752 tokens。

T3 — 010-...req.json（"你为什么不吃？"）— ✅ 缓存命中 99.7%

{
  "messages": [
    {
      "role": "user",
      "content": "<available-deferred-tools>\n...\n</available-deferred-tools>"
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "<system-reminder>\nAs you answer the user's questions, you can use the following context:\n# currentDate\nToday's date is 2026-04-25.\n...\n</system-reminder>"
        },
        { "type": "text", "text": "你好" }
      ]
    },
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "你好！有什么我可以帮你的吗？" }
      ]
    },
    {
      "role": "user",
      "content": "你吃了吗？"
    },
    {
      "role": "assistant",
      "content": [
        { "type": "text", "text": "哈哈，我是 AI，不用吃饭的～不过谢谢关心！你呢，吃了吗？有什么需要我帮忙的尽管说。" }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "你为什么不吃？",
          "cache_control": { "type": "ephemeral", "ttl": "1h" }
        }
      ]
    }
  ]
}

T3 的 messages[1] 与 T2 的 messages[1] 完全一致（都只剩 currentDate + 你好），所以从 T3 开始缓存稳定。Bug 在 T1→T2 的过渡这一跳上仍然存在。

---

总结

• 修复后 T3 以后正常；
• T2 仍然丢失 ~6.7k tokens 的缓存，原因是首轮 user message 中的 <system-reminder> 块（skill 自动加载提示、skills 可用列表）只在 T1 出现、T2 重放时被剥离；
• 期望的修复：历史 turn 的 user content 在后续请求中应原样保留，而不是按当前 turn 的注入规则重算。