提示词缓存（Prompt Caching）

概述

提示词缓存是 Anthropic API 的缓存优化机制，通过在消息中标记 cache_control 断点，将固定不变的前缀内容（如系统提示、工具定义）缓存复用，减少重复 token 的计费和延迟。

关键内容

基本机制

在消息内容中添加 cache_control 标记：

{
  "type": "text",
  "text": "You are a helpful assistant...",
  "cache_control": { "type": "ephemeral" }
}

ephemeral 类型：缓存在会话生命周期内有效
缓存命中时：跳过重新处理，降低延迟和成本
缓存未命中时：正常处理并写入缓存

与上下文压缩的协同

上下文压缩与提示词缓存配合效果良好：

关键优化策略：在系统提示词末尾添加 cache_control 断点，将系统提示与对话内容分开缓存。

当压缩发生时： 1. 系统提示缓存保持有效 — 从缓存读取，无需重新处理 2. 仅压缩摘要需写入新缓存 — 作为新的缓存条目 3. 原始压缩内容被忽略 — 不破坏已有缓存

这对长系统提示词特别有益，即使多次压缩事件，系统提示仍保持缓存状态。

在上下文工程中的位置

Context-Engineering 的 Prompt 位置编排推荐布局中，Cached Prefix 占据约 10% 的 token 预算，包含： - 系统指令 - 工具契约 - Output schema

这些是最稳定的内容，最适合缓存。

缓存失效场景

以下情况会导致缓存失效： - 缓存断点之前的内容发生变化 - 会话结束（ephemeral 缓存清除） - 模型版本切换

生产环境最佳实践（来自 Manus）

Manus 团队总结了提高 KV 缓存命中率的三大实践：

保持提示前缀稳定：避免在系统提示开头包含时间戳（尤其是精确到秒的），单个 token 差异会使之后所有缓存失效
使上下文只追加：避免修改之前的动作或观察，确保序列化确定性（JSON 键顺序不稳定会悄无声息破坏缓存）
明确标记缓存断点：在需要时手动插入缓存断点，至少确保包含系统提示的结尾

Agent 特殊考量：Agent 的输入/输出 token 比约 100:1，高度倾斜于预填充阶段，KV 缓存优化比聊天机器人更重要。工具定义的变更会使后续所有动作和观察的缓存失效——这是"遮蔽而非移除"工具策略的动机之一。

计费影响

缓存命中：按降低费率计费（通常约为正常价格的 25%）
缓存写入：按正常费率计费一次
缓存读取：按折扣费率计费

Claude Code 的提示词缓存优化经验

Claude-Code 团队从大规模优化提示词缓存中总结了 5 条核心经验：

1. 提示缓存采用前缀匹配机制 - 前缀中任意位置的更改都会使其后的所有内容失效 - 围绕这一约束设计整个系统 - 排序合理时，大部分缓存功能都能自动实现 - Claude Code 的提示布局： 1. 静态系统提示和工具（全局缓存） 2. CLAUDE.md（项目内缓存） 3. 会话上下文（会话内缓存） 4. 对话消息

2. 使用消息而非修改系统提示 - 当提示中的信息过时时（如时间变化、用户修改文件） - 不要更新提示（会导致缓存未命中且成本高昂） - 在下一轮消息中传递更新信息 - Claude Code 在下一条用户消息或工具结果中添加 <system-reminder> 标签

3. 不要在对话中途更换模型 - 提示缓存是模型特定的 - 在 Opus 对话 100k tokens 后切换到 Haiku 实际上更昂贵（需要为 Haiku 重建缓存） - 如需切换模型，最佳方式是使用子智能体（Opus 准备"交接"消息给另一个模型）

4. 不要在对话中途添加或移除工具 - 工具是缓存前缀的一部分 - 添加或移除工具会使整个对话的缓存失效 - 规划模式案例：不切换工具集，而是使用 EnterPlanMode 和 ExitPlanMode 作为工具本身 - 工具搜索：使用 defer_loading: true 发送轻量级存根，模型需要时通过 ToolSearch 发现

5. 像监控正常运行时间一样监控缓存命中率 - 缓存中断时发出警报，并将其视为故障事件 - 缓存未命中率仅几个百分点的变化，就可能对成本和延迟产生显著影响

Fork 操作需要共享父进程的前缀： - 压缩操作需要使用与父对话完全相同的系统提示、用户上下文、系统上下文和工具定义 - 从 API 的角度看，请求与父进程的上一次请求几乎完全相同 - 唯一新增的标记就是压缩提示本身

来源

raw/articles/ai-engineering/anthropic-developer/Compaction.md — Anthropic 官方文档（压缩与缓存协同部分）
Context-Engineering — 上下文工程中的缓存策略
raw/articles/ai-engineering/claude-blog/AI代理的上下文工程：构建Manus的经验教训.md — Manus 生产环境 KV 缓存最佳实践