小丹尼DannyData1. Claude Code中的Prompt Caching机制解析
在构建Claude Code这类AI代理系统时，prompt caching（提示词缓存）机制的设计直接影响着系统的响应速度和运营成本。这个机制的核心思想是：当连续对话中大部分内容保持不变时，系统可以复用之前已经处理过的部分，只对新增加的内容进行计算。
1.1 缓存工作原理详解
Claude Code的prompt caching采用前缀匹配机制。每次请求时，系统会将当前请求的开始部分（称为前缀）与最近处理过的内容进行比对。在典型的对话回合中，前缀就是整个先前的请求内容，只有最新的一次交互是新增部分。
这种设计带来了几个关键特性：
- 匹配必须是精确的，前缀中任何位置的改动都会导致其后所有内容需要重新计算
- 没有按文件或按段的独立缓存，整个前缀作为一个整体被缓存
- 系统会智能组织请求内容，将不常变动的部分放在前面，提高缓存命中率
在实际应用中，Claude Code将请求内容分为三个层次：
- 系统提示层（System Prompt）：包含核心指令、工具定义和输出样式
- 项目上下文层（Project Context）：包括CLAUDE.md文件内容、自动记忆和无范围规则
- 对话层（Conversation）：包含用户消息、AI响应和工具调用结果
1.2 缓存键的组成要素
缓存的有效性依赖于缓存键的精确匹配。除了请求内容本身外，还有两个关键因素会影响缓存键：
- 模型选择（Model）：每个AI模型都有独立的缓存空间。即使内容完全相同，切换到不同模型也会导致缓存失效。
- 工作量级别（Effort Level）：同一模型的不同工作强度设置也会产生不同的缓存条目。
提示：在对话开始时就确定好模型和工作量级别，避免在会话中途更改这些设置，可以显著提高缓存命中率。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. Prompt Caching的性能优化实践
2.1 缓存位置与生命周期管理
Claude Code的prompt caching可以发生在不同的服务端位置，具体取决于认证方式：
- 使用API密钥或Claude订阅时：缓存位于Anthropic的基础设施中
- 使用Amazon Bedrock或Google Cloud时：缓存位于对应云服务商的基础设施中
- 自定义部署场景：缓存位置取决于请求最终转发到的服务节点
缓存条目都有生存时间（TTL）限制，系统提供两种TTL设置：
- 5分钟TTL：默认设置，成本较低
- 1小时TTL：保持缓存更长时间，但写入成本略高
在Claude订阅环境下，系统会自动使用1小时TTL，因为这部分成本已包含在订阅费用中。而对于按量付费的场景，默认使用5分钟TTL以控制成本。
2.2 缓存命中率监控技巧
开发者可以通过以下方式监控缓存性能：
-
实时查看API响应中的两个关键指标：
cache_creation_input_tokens：本轮写入缓存的token数量cache_read_input_tokens：本轮从缓存读取的token数量
-
计算缓存命中率：
code复制命中率 = cache_read_input_tokens / (cache_read_input_tokens + cache_creation_input_tokens)高命中率表明缓存工作良好，低命中率则提示可能需要优化对话结构。
-
使用OpenTelemetry导出器获取组织级的缓存性能数据
3. 影响缓存有效性的关键操作
3.1 会导致缓存失效的操作
以下操作会立即导致缓存失效，使下一个请求需要完整重新处理：
- 切换模型（/model命令）
- 更改工作量级别（/effort命令）
- 启用快速模式
- 连接或断开MCP服务器
- 启用/禁用插件（某些类型）
- 添加全局工具拒绝规则
- 压缩对话（/compact命令）
- 升级Claude Code版本
特别需要注意的是，opusplan模型在规划模式和执行模式间切换时，实际上是在Opus和Sonnet模型间切换，这也会导致缓存失效。
3.2 保持缓存有效的操作
以下操作不会影响缓存有效性：
- 编辑项目文件（内容变更会作为新增部分附加）
- 在会话中编辑CLAUDE.md（修改不会立即生效）
- 更改输出样式（需要重启才生效）
- 切换权限模式（除Plan Mode外）
- 调用技能和命令
- 生成摘要（/recap命令）
- 回滚对话（/rewind命令）
- 创建子代理
4. 高级应用场景与疑难解答
4.1 多代理协作中的缓存管理
在涉及子代理的复杂工作流中，缓存管理需要特别注意：
- 子代理拥有独立的缓存空间，与父代理完全隔离
- 子代理总是使用5分钟TTL，即使主对话使用1小时TTL
- 分叉（fork）的代理会继承父代理的缓存状态
- 父代理的缓存不受子代理操作的影响
这种设计保证了代理间的操作隔离，同时也提供了必要的灵活性。
4.2 常见缓存问题排查
当发现缓存命中率不理想时，可以按照以下步骤排查：
- 检查是否有频繁的模型切换
- 确认工作量级别是否保持稳定
- 审查工具使用模式，避免频繁连接/断开MCP服务器
- 减少会话中的/compact操作频率
- 避免在长会话中途启用快速模式
- 检查插件配置，避免某些类型的插件频繁加载/卸载
一个典型的优化案例是：某开发团队发现他们的缓存命中率只有30%，经过排查发现是因为在对话中频繁切换模型和快速模式设置。固定使用一个模型并仅在会话开始时启用快速模式后，命中率提升到了85%。
4.3 缓存禁用场景
在某些特殊情况下可能需要禁用缓存：
- 调试缓存相关问题时
- 使用特定模型进行性能测试时
- 某些云服务商环境不支持缓存时
可以通过设置环境变量来禁用缓存：
DISABLE_PROMPT_CACHING：全局禁用DISABLE_PROMPT_CACHING_[MODEL]：针对特定模型禁用
5. 设计理念与最佳实践
5.1 Claude Code的缓存设计哲学
Claude Code团队在构建prompt caching系统时，遵循了几个核心原则：
- 透明性：缓存操作对用户透明，但提供足够的可见性
- 确定性：缓存行为完全可预测，没有隐藏规则
- 隔离性：不同会话、不同代理间的缓存相互隔离
- 经济性：在保证性能的同时，尽可能降低使用成本
这种设计使得开发者既能享受缓存带来的性能优势，又不必担心不可预期的行为。
5.2 提高缓存效率的实用技巧
基于实际项目经验，总结出以下提升缓存效率的方法：
-
会话结构优化：
- 将不常变动的内容放在对话前面
- 保持系统提示尽可能稳定
- 避免频繁切换对话主题
-
工作模式选择：
- 在任务自然中断点执行/compact操作
- 使用/rewind代替/compact来放弃不需要的对话路径
- 批量处理相关操作，减少设置变更频率
-
工具使用策略：
- 优先使用延迟加载的工具
- 避免在会话中途添加全局工具拒绝规则
- 保持MCP服务器连接稳定
-
环境配置：
- 在订阅环境下启用1小时TTL
- 为重要项目固定工作目录
- 避免频繁切换git分支
在实际项目中，合理应用这些技巧可以将平均缓存命中率从60%提升到90%以上，显著降低API调用成本和响应延迟。