Claude 提示词缓存诊断功能上线：精准定位缓存未命中分歧点

Claude 推出 Prompt cache diagnostics 测试版功能，开发者传入指定 beta header 与上一条响应 ID 即可对比连续请求，精准定位导致缓存失效的具体位置。据 Anthropic 官方文档，该功能可识别模型参数、system prompt、工具定义或消息历史中首次出现差异的节点，帮助开发者修复根因而非盲目猜测。

工作原理与数据结构

启用该功能需在 API 请求头中包含 cache-diagnosis-2026-04-07。API 会为每条响应存储一份轻量级请求指纹，以响应 ID 为键。下次请求时传入 diagnostics.previous_message_id 指向前一条响应，API 重建新请求指纹并与存储版本对比，将首次分歧点附在响应的 diagnostics 对象中返回。

指纹仅包含哈希值与 token 计数估算，永不包含原始提示词内容。数据保留期限有限，按组织与工作区隔离，且仅用于诊断目的。该功能符合 Zero Data Retention (ZDR) 政策，技术保留范围受限。

缓存失效的常见原因与诊断价值

Prompt caching 仅在提示词开头与近期请求字节级完全一致时生效。工具顺序调整、时间戳插入 system prompt、早期消息编辑等操作均会静默使缓存失效。此前开发者只能通过 usage.cache_read_input_tokens 突降至零感知缓存未命中，却无法获知具体变化位置。

Cache diagnostics 填补了这一空白。响应中的 diagnostics 对象会明确指出分歧发生在模型参数、system prompt、工具定义还是消息历史，使开发者能够直接修复根因，而非反复尝试猜测问题来源。

启用方式与平台限制

当前该功能处于 beta 阶段，仅在原生 Claude API 上可用，不支持 Amazon Bedrock 或 Vertex AI。开发者需在请求头中加入 anthropic-beta: cache-diagnosis-2026-04-07 方可激活。

建议将诊断结果与 usage.cache_read_input_tokens 结合阅读：后者显示缓存是否命中，前者解释未命中的结构性原因。二者结合可完整评估提示词工程的优化效果。

真正需要记住的是：缓存诊断对比的是请求结构而非原始内容，传入前一条响应 ID 即可获得分歧点定位，但务必确认平台支持后再投入生产环境使用。