主播
节目简介
来源：小宇宙
核心发现
通过对 PR #19823 之后的生产数据进行分析，团队发现： 当客户端快照显示所有标志位均为“未变化”，且两次请求的时间间隔在缓存 TTL（5 分钟或 1 小时）范围之内时，约 90% 的缓存中断归因于服务端原因，而非客户端代码 Bug。
以下是该章节核心内容的详细总结：
1. 核心架构：两阶段检测逻辑
由于缓存中断的触发（请求前状态变化）与确认（响应后 Token 数下降）在时间上是分离的，Claude Code 采用了两阶段检测架构：
* 阶段 1：recordPromptState() (请求前)：在构建 API 请求时，捕获当前所有可能影响缓存键的客户端状态（如系统提示词哈希、工具定义、Beta Header 等），并与前次状态对比，记录变化清单（PendingChanges）,,。
* 阶段 2：checkResponseForCacheBreak() (响应后)：在收到 API 响应后，检查 cache_read_input_tokens。如果发现显著下降，则利用阶段 1 收集的信息来解释中断原因,。
2. 精密的“状态快照” (PreviousState)
系统通过 PreviousState 对象捕获了 15+ 个关键字段，确保不遗漏任何导致缓存失效的变量。
* 哈希分离设计：系统将 systemHash（提示词内容）与 cacheControlHash（缓存标记/TTL）分开计算。这样即使提示词内容没变，仅因缓存范围从 global 翻转为 org 导致的中断也能被捕获。
* 逐工具归因：当工具哈希变化时，系统会按需计算 perToolHashes。根据大数据分析，77% 的工具变化源于单个工具的描述改变（如 Agent 列表更新），这种设计能精确定位具体受影响的工具,。
* 隔离策略：使用 Map 存储不同查询源的状态，并通过 agentId 隔离并发的子代理，防止不同任务间的状态对比产生误报,。
3. 中断判定的“双重门槛”
为了过滤掉正常的 Token 波动，系统设定了严苛的中断判定标准：
* 相对阈值：缓存读取 Token 数下降超过 5%。
* 绝对阈值：下降总量超过 2,000 tokens。
* 只有两个条件同时满足，系统才会触发中断告警，从而避免因基数过小或细微波动导致的误报,。
4. 强大的中断解释引擎
一旦确认中断，系统会尝试进行人类可读的归因分析：
* 客户端归因：列举模型切换、系统提示词增减字符、工具集变动等具体信息。
* TTL 过期检测：如果没有客户端变化，系统会检查时间间隔。若超过 5 分钟或 1 小时，则判定为 TTL 自然过期,。
* “90% 服务端”发现：这是一个重大的工程洞察——数据分析显示，当客户端无变化且未超 TTL 时，约 90% 的中断源于服务端路由、缓存驱逐或计费不一致,。这一发现让开发团队避免了在客户端盲目排查不可控的 Bug,。
5. 调试与分析工具
* 自动化 Diff：检测到客户端中断时，系统会自动生成一个包含前后状态差异的 Diff 文件，供开发者在临时目录中查看具体的提示词变动,。
* 安全去敏：在发送 tengu_prompt_cache_break 遥测事件时，系统会自动将 MCP 工具名称安全化（统一标记为 mcp），防止泄露用户隐私信息,。
6. 工程设计洞察
* 时序决定架构：两阶段架构是处理此类异步问题的唯一正确方案，因为原始状态只存在于请求前，而确认只能在响应后。
* 可观测性先于优化：本系统本身并不优化缓存，但它是所有优化（如第15章提到的模式）的基石。没有精确的检测，就无法量化优化的效果，也无法发现新的优化机会。
总结而言：本章展示了如何构建一个数据驱动的“黑盒”监控系统。它将静默的缓存失效转化为透明的诊断报告，为后续的性能压榨和成本控制提供了科学依据。
通过对 PR #19823 之后的生产数据进行分析，团队发现： 当客户端快照显示所有标志位均为“未变化”，且两次请求的时间间隔在缓存 TTL（5 分钟或 1 小时）范围之内时，约 90% 的缓存中断归因于服务端原因，而非客户端代码 Bug。
以下是该章节核心内容的详细总结：
1. 核心架构：两阶段检测逻辑
由于缓存中断的触发（请求前状态变化）与确认（响应后 Token 数下降）在时间上是分离的，Claude Code 采用了两阶段检测架构：
* 阶段 1：recordPromptState() (请求前)：在构建 API 请求时，捕获当前所有可能影响缓存键的客户端状态（如系统提示词哈希、工具定义、Beta Header 等），并与前次状态对比，记录变化清单（PendingChanges）,,。
* 阶段 2：checkResponseForCacheBreak() (响应后)：在收到 API 响应后，检查 cache_read_input_tokens。如果发现显著下降，则利用阶段 1 收集的信息来解释中断原因,。
2. 精密的“状态快照” (PreviousState)
系统通过 PreviousState 对象捕获了 15+ 个关键字段，确保不遗漏任何导致缓存失效的变量。
* 哈希分离设计：系统将 systemHash（提示词内容）与 cacheControlHash（缓存标记/TTL）分开计算。这样即使提示词内容没变，仅因缓存范围从 global 翻转为 org 导致的中断也能被捕获。
* 逐工具归因：当工具哈希变化时，系统会按需计算 perToolHashes。根据大数据分析，77% 的工具变化源于单个工具的描述改变（如 Agent 列表更新），这种设计能精确定位具体受影响的工具,。
* 隔离策略：使用 Map 存储不同查询源的状态，并通过 agentId 隔离并发的子代理，防止不同任务间的状态对比产生误报,。
3. 中断判定的“双重门槛”
为了过滤掉正常的 Token 波动，系统设定了严苛的中断判定标准：
* 相对阈值：缓存读取 Token 数下降超过 5%。
* 绝对阈值：下降总量超过 2,000 tokens。
* 只有两个条件同时满足，系统才会触发中断告警，从而避免因基数过小或细微波动导致的误报,。
4. 强大的中断解释引擎
一旦确认中断，系统会尝试进行人类可读的归因分析：
* 客户端归因：列举模型切换、系统提示词增减字符、工具集变动等具体信息。
* TTL 过期检测：如果没有客户端变化，系统会检查时间间隔。若超过 5 分钟或 1 小时，则判定为 TTL 自然过期,。
* “90% 服务端”发现：这是一个重大的工程洞察——数据分析显示，当客户端无变化且未超 TTL 时，约 90% 的中断源于服务端路由、缓存驱逐或计费不一致,。这一发现让开发团队避免了在客户端盲目排查不可控的 Bug,。
5. 调试与分析工具
* 自动化 Diff：检测到客户端中断时，系统会自动生成一个包含前后状态差异的 Diff 文件，供开发者在临时目录中查看具体的提示词变动,。
* 安全去敏：在发送 tengu_prompt_cache_break 遥测事件时，系统会自动将 MCP 工具名称安全化（统一标记为 mcp），防止泄露用户隐私信息,。
6. 工程设计洞察
* 时序决定架构：两阶段架构是处理此类异步问题的唯一正确方案，因为原始状态只存在于请求前，而确认只能在响应后。
* 可观测性先于优化：本系统本身并不优化缓存，但它是所有优化（如第15章提到的模式）的基石。没有精确的检测，就无法量化优化的效果，也无法发现新的优化机会。
总结而言：本章展示了如何构建一个数据驱动的“黑盒”监控系统。它将静默的缓存失效转化为透明的诊断报告，为后续的性能压榨和成本控制提供了科学依据。
外观
