Claude Code 的秘密武器：Prompt Caching 如何重塑 AI 代理开发

type

status

date

slug

summary

Prompt Caching：AI 代理的“基础设施”

Claude Code 作为一款广受欢迎的 AI 编程助手，其背后强大的性能并非偶然。Anthropic 在博客中强调，Prompt Caching 的命中率被视为“基础设施级别”的指标，其重要性不亚于服务器的正常运行时间（uptime）。一旦缓存命中率下降，系统会触发告警，工程师必须像处理线上故障一样进行排查。这清晰地表明，Prompt Caching 对于 Claude Code 而言，是实现流畅交互和低延迟的关键前提，而非可有可无的锦上添花。

为什么 Prompt Caching 至关重要？长对话的挑战

AI 代理，尤其是像 Claude Code 这样需要进行多轮交互的产品，其一个核心特性是“长对话”。用户在一次会话中可能与 AI 进行数十轮甚至上百轮的交流。在每一轮交互中，都需要将之前的对话历史（上下文）一并发送给模型进行处理。如果每次都从零开始计算，模型的延迟将急剧增加，同时计算成本也会呈指数级增长，这对于用户体验和商业可行性都是毁灭性的打击。

Prompt Caching 的核心原理相对简单：前缀匹配。当用户发送一个请求时，API 会缓存从请求开始到特定“断点”之间的所有内容。如果下一次请求的前缀与之前被缓存的请求前缀完全一致，系统就能直接复用之前计算好的结果，而无需再次调用大模型进行推理。这种机制极大地减少了重复计算，显著降低了延迟和成本。

最佳实践：精心排布你的 Prompt

既然缓存依赖于前缀匹配，那么如何构建和组织你的 Prompt 就变得至关重要。Anthropic 提出的最佳实践围绕着“越不容易变的东西，越往前放”的原则展开：

静态系统 Prompt 和工具定义：这部分内容是全局性的，对所有会话都通用，变化最少，应放在最前面，以实现最高粒度的缓存共享。

CLAUDE.md 文档：这通常与特定项目相关，可以在同一项目内的不同会话中共享，属于项目级缓存。

Session 上下文：指当前会话的对话历史，其变化频率高于全局和项目级，但低于单次消息，属于会话级缓存。

对话消息：即用户当前发送的最新消息，这是最动态的部分，每轮都会增长。

这种结构的设计，就像整理书桌一样：将常年不动的参考书放在最底层（静态 Prompt），本周要看的资料放在中间（Session 上下文），而今天正在写的草稿则放在最上面（最新消息）。这样，每次开始工作时，你只需关注桌面最上层的内容，而无需翻动整个书桌。

易踩的“缓存断链”坑：

动态信息嵌入：在静态 Prompt 中不慎嵌入时间戳、用户ID等每秒都在变化的信息，会导致缓存失效。

工具定义顺序不确定：若工具定义使用字典（dict）或集合（set）等无序数据结构，或其排列顺序不固定，会导致每次请求的前缀不同，缓存无法命中。

工具参数微小变动：即使是工具定义中一个字段的微小变动，也可能导致整个前缀缓存失效。

“别动 Prompt”：信息更新的智慧

当信息确实过时（如时间戳、文件状态变更）需要更新时，Anthropic 的建议是：不要直接修改 Prompt。而是将这些更新信息封装在下一轮的消息中，通过 <system-reminder> 标签或在用户消息（user message）或工具返回结果（tool result）中传递。这样，核心的系统 Prompt 保持不变，缓存链得以完整保留。这体现了一种“Prompt 是不可变基础设施，消息是流动信息层”的设计哲学，将稳定性和动态性清晰地分离。

“别换模型”：理解缓存的绑定性

一个常见的直觉是，在对话过程中根据任务难度切换模型（例如，简单任务用便宜的模型，复杂任务用强大的模型）来优化成本。然而，Anthropic 的经验表明，缓存是与特定模型绑定的。一旦切换模型，之前积累的所有缓存将全部作废，需要从头重建。重建缓存的成本往往高于让更强大的模型直接处理简单问题。

因此，Claude Code 的策略是：主对话始终使用同一个模型。如果需要利用小模型完成特定子任务，则会创建“子 Agent”。这些子 Agent 拥有独立的上下文和缓存，不会影响主对话的缓存链。任务完成后，仅将结果返回。这好比在办公室，不会让实习生直接使用你的电脑，而是为其配备独立工作站，完成后提交结果。

特别注意：对于使用账号池或频繁切换账号的场景，务必注意缓存是按账号隔离的。混用账号可能导致缓存命中率骤降，反而得不偿失。

“别碰工具”：维护缓存的连续性

类似的原则也适用于工具集。Anthropic 建议在一次会话期间尽量不修改工具集。直观上，我们可能想只加载当前任务所需的工具，以减少 Token 开销。但工具集的增减会直接影响 Prompt 的前缀，导致缓存断裂，需要重建整个对话的缓存，其代价远超额外加载几个工具定义的 Token 开销。

Plan Mode 的缓存友好设计

以 Claude Code 的 Plan Mode 为例，其直觉做法可能是进入规划模式时移除执行类工具，退出时再加回。但 Anthropic 的解决方案是：保留所有工具不变，而是添加 EnterPlanMode 和 ExitPlanMode 两个特殊工具。模型在需要时调用 EnterPlanMode 进入规划模式，约束通过 System Message 传达。这种设计确保了工具集始终不变，缓存得以持续有效，同时还赋予了模型自主判断何时进入规划模式的能力。

延迟加载与压缩：应对上下文窗口的挑战

延迟加载工具：按需引入

当 AI 代理需要接入大量工具时，将所有工具的完整 Schema 直接载入 Prompt 会造成巨大的 Token 开销。按需增减工具又会破坏缓存。Anthropic 采用“延迟加载”的折中方案：初始阶段只加载一个包含工具名称和简短描述的“Stub”（存根），并标记 defer_loading: true。当模型真正需要使用某个工具时，才通过 Tool Search 获取其完整的 Schema。这样，Prompt 的前缀始终保持轻量，缓存得以稳固。这就像图书馆的目录，你先查目录，再取书，而非一次性搬空所有书籍。

Cache-Safe Forking：压缩对话的智能之道

长对话不可避免地会填满上下文窗口，此时需要对早期对话进行“压缩”，生成摘要以腾出空间。如果另起一次 API 调用进行压缩，很可能因为 Prompt 和上下文的变化而导致缓存失效，产生不必要的额外成本。Anthropic 提出的“Cache-Safe Forking”解决方案是：在进行压缩时，必须使用与主对话完全相同的 System Prompt、User Context 和工具定义，并将主对话的消息作为历史传递。然后在末尾追加一条压缩指令作为新的 User Message。这样，压缩请求就能与主对话共享同一条缓存链，新增成本仅限于最后一条压缩指令。同时，预留“压缩缓冲区”确保摘要有足够空间。这种方法几乎能复用主对话积累的全部缓存，成本增幅极小。

结论：缓存即架构，设计哲学引领未来

Anthropic 的这 7 条经验，核心都在围绕“Prompt Caching 是前缀匹配”这一基本约束展开。所有的设计决策，从 Prompt 的组织方式、信息更新策略，到模型选择、工具管理，再到上下文窗口的利用，都服务于维护缓存的连续性。

这不仅仅是关于缓存优化，更是一种深刻的系统设计哲学：先确定核心约束，再围绕约束进行设计。对于正在构建 AI 代理产品的开发者而言，Prompt Caching 不应被视为事后添加的优化，而应从项目第一天起就将其提升到架构约束的层面进行考量。

Anthropic 还提到，其 API 已内置 Compaction（压缩）功能，开发者可直接使用。这意味着，构建更强大、更经济高效的 AI 代理，正变得前所未有的便捷。理解并应用 Prompt Caching 的原理，将是解锁下一代 AI 应用潜力的关键。

如果您希望在构建 AI 应用时，能够更便捷地接入顶尖大模型，并获得更优的 API 服务体验，可以关注 Claude 官网，探索 Claude API 的强大功能。同时，我们也提供 Claude 镜像站及 Claude 官方中文版等资源，帮助您更顺畅地使用 Claude，了解 Claude 教程与使用指南，让您的 AI 开发之路事半功倍。