很多人以为 AI Agent 的成本失控，是因为模型太贵；很多人以为响应变慢，是因为模型变笨。真正落到工程现场，问题往往更隐蔽：缓存悄悄断了。
缓存一旦断掉，系统不会大声报错。它只是让 cache_read_input_tokens 突然下降，让输入 token 重新计费，让延迟悄悄升高。用户看到的是“怎么突然慢了”，团队看到的是“怎么账单突然涨了”，但真正的根因藏在请求前后的细节里。
这套缓存中断检测系统的价值，就是把“静默失效”变成“可观测事件”：先在请求前记录证据，再在响应后确认是否真的击穿，最后给出能让工程师看懂的原因。
一、为什么缓存中断检测这么重要：看不见的问题最贵
Prompt Cache 的本质，可以理解为“把重复的大段上下文提前存起来”。如果系统提示词、工具定义、历史消息前缀都没有变化，后续请求就不用每次重新处理整段内容。这样既省钱，也能降低延迟。
但它有一个天然难点：缓存命中依赖“前缀一致”。只要缓存范围内的内容发生变化，例如工具 schema 变了、系统提示词动态注入了新内容、模型切换了、beta header 翻转了、缓存策略变化了，都可能让服务端认为这是一个新的前缀，从而重新写缓存。
更麻烦的是，缓存中断没有普通错误码。请求仍然成功，答案仍然返回，只是缓存读取 token 变少了。这种问题如果没有专门检测，往往只能靠账单、延迟、用户体感倒推。
二、核心思想：请求前拍快照，响应后查账单
这套机制最关键的设计，是把检测拆成两个阶段。第一个阶段发生在请求发送前，负责记录当前状态；第二个阶段发生在响应返回后，负责用缓存 token 数据确认是否真的发生中断。
为什么必须分两步？因为原因和结果不在同一个时间点。原因通常发生在请求发送前，比如系统提示词、工具、模型、header 发生变化；结果只能在响应后看到，比如 cache_read_input_tokens 是否明显下降。
如果只做响应后检测，虽然知道缓存读少了，但已经丢失了请求发送前的状态证据；如果只做请求前检测，虽然知道客户端变了，但不知道这个变化是否真的导致服务端缓存击穿。两阶段合在一起，才形成完整证据链。
三、PreviousState：把所有可能影响缓存键的因素放进一个状态盒子
检测系统不是简单保存一段文本，而是保存一个“全量状态快照”。这个快照可以理解为缓存前缀的体检报告，里面包含系统提示词、工具定义、缓存控制、模型、header、模式状态、上次缓存读取 token 等信息。
字段类型 | 保存内容 | 为什么重要 |
提示词类 | 系统提示词哈希、字符数量、cache_control 哈希 | 判断内容是否变了，以及缓存范围或 TTL 是否变了 |
工具类 | 工具列表、工具总哈希、单工具哈希 | 判断工具新增、移除，或单个工具描述变化 |
请求类 | 模型、beta header、effort、额外 body 参数 | 这些字段可能影响服务端缓存键 |
模式类 | Fast Mode、Auto Mode、Overage、Cached MC | 这些模式会影响真实发送的请求形态 |
运行类 | 调用次数、上次缓存读取 token、待确认变化 | 用于跨请求比较和响应后归因 |
四、哈希拆分：不要只问“变没变”，还要问“哪里变了”
如果只给整段请求做一个大哈希，确实能发现变化，但无法定位变化来源。工程排查最怕的就是一句“它变了”，却不知道是提示词变了、工具变了、缓存标记变了，还是请求参数变了。
因此系统采用多层哈希：系统提示词内容单独算，cache_control 单独算，工具整体单独算，必要时再算每个工具的独立哈希。这样既能快速发现问题，又能精确定位到哪个模块导致缓存前缀变化。
这里最值得借鉴的是 systemHash 与 cacheControlHash 的分离。系统提示词文本没变，不代表缓存范围没变；缓存范围或 TTL 变化，也可能让服务端缓存行为变化。把内容和缓存控制拆开，才能避免漏报。
五、跟踪键隔离：主线程、SDK、子 Agent 不能混在一起算
一个成熟的 AI Agent 系统里，请求来源可能很多：主线程对话、SDK 调用、内置子 Agent、自定义子 Agent、压缩任务、短生命周期建议任务等。如果这些请求都共用一个状态，很容易互相污染。
因此检测系统为不同来源维护独立状态。普通对话和压缩共享主线程状态，因为它们使用相同的缓存安全参数；子 Agent 按 agentId 隔离，避免多个并发 Agent 互相制造误报；短生命周期任务则不跟踪，避免制造噪音。
这种设计体现了一个重要原则：可观测性不是记录越多越好，而是记录“可比较、可解释、可行动”的对象。没有前后对比价值的短任务，不如直接排除。
六、PendingChanges：把变化清单先存起来，等结果回来再判案
请求前检测到变化时，系统不会立刻断言“缓存中断”。它只是把变化保存成 PendingChanges。这个名字可以理解为“待确认的变化清单”：先记账，不急着定罪。
变化清单不仅保存布尔值，还保存具体细节，比如新增了哪些工具、移除了哪些工具、哪些工具 schema 变了、系统提示词字符数增减多少、模型从哪个切到哪个、beta header 增删了什么。
这一步的价值很大。等响应回来后，如果 cache_read_input_tokens 真的大幅下降，系统就能把“缓存读少了”和“请求前发生了哪些变化”关联起来，从而输出人能理解的诊断。
七、双重门槛：只有真正值得关注的下降才报警
缓存读取 token 有自然波动。如果只要下降一点点就报警，工程师很快会被噪音淹没。因此系统使用双重门槛：相对下降超过 5%，并且绝对下降超过 2000 tokens，两个条件同时满足才认为是值得关注的缓存中断。
这个判断很朴素，但非常实用。相对阈值能发现大比例下降，绝对阈值能避免小基线下的比例误判。比如 1000 tokens 掉 60 tokens，比例超过 5%，但实际影响很小，不应该惊动系统。
八、特殊情况：有些下降是正常的，不应该报警
并不是所有 cache_read_input_tokens 下降都是坏事。比如缓存编辑主动删除了一部分缓存块，下降就是预期行为；压缩操作减少历史消息，下降也是自然结果。
系统为这些情况设置了专门通知机制：缓存删除时标记 cacheDeletionsPending，响应后如果发现下降就视为预期；压缩发生后重置上次缓存读取 token，让下一次请求重新建立基线。
这背后有个很重要的工程思想：检测系统不仅要发现异常，还要理解“合法变化”。不知道业务语义的监控，很容易把正常行为当事故。
九、中断解释引擎：把 token 下降翻译成人话
确认中断后，系统并不是简单输出“缓存击穿”。它会尝试解释原因：模型是否切换、系统提示词是否变了、工具是否增删、工具 schema 是否变了、beta header 是否变化、缓存策略是否切换。
如果没有发现客户端变化，系统会继续判断时间间隔。如果距离上次 assistant 消息超过 5 分钟或 1 小时，就倾向于解释为 TTL 过期。如果没有超过 TTL，且客户端也没有变化，就更可能是服务端路由、缓存驱逐或计费统计差异。
这一步改变了排查体验。过去看到缓存读下降，可能要从所有模块开始怀疑；现在可以先看诊断分类，把时间花在最可能的方向上。
十、可观测性闭环：日志、事件、Diff 文件，一个都不能少
成熟的检测系统不能只在控制台打一行日志。它需要同时满足三类需求：现场排查、长期分析、细节复盘。
现场排查需要 debug log，告诉工程师当前请求为什么被判定为缓存中断；长期分析需要 analytics 事件，把变化标志、token 统计、请求 ID、调用次数等信息送入数据仓库；细节复盘需要 diff 文件，对比前后状态到底哪里不同。
这里还有一个隐私细节：MCP 工具名称可能来自用户配置，里面可能包含敏感路径或业务信息。因此上报时会把 mcp 前缀工具统一安全化，避免把用户自定义名称带入分析系统。
十一、最有价值的洞察：不是所有缓存中断都该由客户端背锅
这套机制的一个关键发现是：当客户端没有检测到变化，且时间间隔还没超过 TTL 时，大量缓存中断更可能来自服务端原因，例如路由到没有缓存的实例、缓存被服务端驱逐、计费统计与推理侧存在差异。
这个结论非常重要。它会改变优化方向：团队不必为了追求 100% 缓存稳定而疯狂压缩客户端变化，而是应该先保证客户端变化可控、可解释、可度量。剩下那部分服务端波动，则通过数据监控和策略容错来处理。
十二、普通团队如何照搬这套方法
如果你正在做自己的 AI Agent、企业知识库问答、自动化研发助手、智能客服或多工具 Agent，这套思路完全可以复用。
步骤 | 做法 | 收益 |
1. 建立基线 | 记录正常会话的 cache_read_input_tokens 区间 | 知道什么才叫异常下降 |
2. 请求前快照 | 保存提示词哈希、工具哈希、模型、header、缓存策略 | 响应后能回溯原因 |
3. 响应后比对 | 同时设置相对阈值和绝对阈值 | 过滤噪音，减少误报 |
4. 分类归因 | 区分客户端变化、TTL 过期、服务端原因 | 避免盲目排查 |
5. 持续优化 | 把高频动态内容移出缓存前缀 | 降低可控缓存中断 |
最简单的落地方式，是先别急着做复杂平台，而是在每次请求前记录关键状态摘要，在响应后记录缓存读写 token。只要积累一段时间，就能看到哪些变化最容易破坏缓存。
十三、写给工程团队的 7 条实战建议
1. 不要把时间戳、随机数、实时状态放在缓存前缀里。高频变化内容越靠前，缓存越容易断。
2. 把稳定规则放前面，把动态状态放后面。前面像宪法，后面像临时通知。
3. 工具定义要稳定。动态工具列表、动态描述、动态命令清单都可能让工具 schema 变化。
4. 对 MCP 类工具要特别谨慎。工具重连、工具发现、工具名称变化，都可能影响缓存诊断。
5. 不要只看命中率，还要看 cache_read_input_tokens 的下降幅度。命中率无法解释成本波动细节。
6. 检测系统要理解业务语义。压缩、缓存删除、清空会话等行为要设置排除逻辑。
7. 可观测性先于优化。没有诊断数据，所谓优化只是猜测。
十四、总结：缓存中断检测，本质是 AI Agent 的“黑匣子记录仪”
Prompt Cache 能省钱、提速，但它也带来一个新问题：缓存什么时候断、为什么断、该不该报警。没有检测系统，缓存就像一个黑盒，只有账单和延迟告诉你它可能出事了。
Claude Code 的缓存中断检测系统给出的答案，是建立一套两阶段可观测性架构：请求前记录状态快照，响应后根据 token 统计确认中断，再用变化清单、TTL 判断、服务端归因、日志、事件和 Diff 文件形成完整诊断链。
这套方法对所有 AI Agent 工程都有启发：未来真正稳定、便宜、可规模化的 Agent，不只是会调用模型，更要会管理上下文、守住缓存前缀、发现静默失效，并把每一次异常变成可分析的数据。
参考资料：https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd=6fkr
