很多人做 AI Agent只盯着模型、工具和提示词却忽略了一个真正会影响成本、延迟和稳定性的底层问题缓存到底能不能持续命中。一个看似无关紧要的日期、路径、功能开关、工具列表都可能让前面已经缓存好的大段内容重新计算。这套缓存优化思想的核心很朴素先找到变化源再判断它是否必须放在请求前面。如果必须放前面就降低变化频率如果不必须就尽量移动到消息尾部如果是用户差异就用占位符统一如果是列表膨胀就用预算管住。一、为什么缓存优化是 AI Agent 的隐藏胜负手AI Agent 的一次请求通常不只是用户的一句话还包括工具定义、系统规则、历史消息、项目上下文、技能说明、权限说明等大量内容。随着会话变长这些内容会越来越重。Prompt Cache 的价值就是把前面稳定、重复的大块内容复用起来避免每次都从零处理。问题在于缓存依赖稳定前缀。只要前缀里的字节发生变化缓存命中就会下降。模型并不会因为两段内容“意思差不多”就复用缓存它更像是在比较一串精确的输入。Anthropic 官方文档建议把稳定、可复用的内容放在提示开头例如系统指令、背景资料、大上下文或常用工具定义并使用缓存断点管理不同变化频率的内容。工具相关文档也强调工具定义同样可以与 Prompt Caching 结合用来降低重复工具 Schema 的成本。二、整体方法论识别变化源把动态变静态缓存优化不是单点技巧而是一套工程纪律。每当某段内容要进入请求体时都要问四个问题它会不会变多久变一次必须放在前面吗能不能通过标准化、记忆化、预算、附件化来减少变化三、模式一日期记忆化让跨天不再打穿缓存很多系统都会在提示中放入当前日期用来帮助模型理解时间背景。看起来很自然但它有一个致命问题午夜一过日期就变。假设前一轮还是 2026-04-01下一轮变成 2026-04-02即使只变了一个字符也可能让前面大段缓存失效。解决思路是把日期固定为“会话开始时的日期”。第一次获取后就记住后续请求一直使用同一个值。这样做的本质不是追求绝对实时而是承认编程任务里日期通常不是核心变量缓存稳定性比跨午夜的日期精度更重要。这个设计背后的取舍很清晰宁愿日期在极少数场景下稍微滞后也不要让整个稳定前缀因为午夜切换而重新计算。对于长时间连续工作的用户这种优化非常实用。四、模式二月度粒度让工具提示少受日期影响系统提示需要日期工具提示有时也需要时间信息。但工具 Schema 通常更靠前、更敏感一旦变化影响更大。因此工具提示里的时间不一定要精确到天很多场景只需要“当前月份和年份”。把完整日期降级成月份年份本质是降低变化频率从每天变化一次变成每月变化一次。变化频率越低缓存越容易稳定。这体现了一个重要原则越靠近请求前端的内容越应该低频变化越靠近消息尾部的内容才适合承载高频变化。五、模式三Agent 列表附件化别把动态清单塞进工具描述Agent 列表是一类典型的动态内容。插件加载、MCP 连接变化、权限模式切换都可能改变可用 Agent 的数量、名称和描述。如果把这份列表直接写在工具描述里每次列表变化都会让工具 Schema 跟着变化。更好的办法是工具描述只保留静态能力说明真正动态的 Agent 列表通过消息附件追加到后面。这样即使 Agent 清单变化也只是尾部内容变化不会打穿前面已经缓存的工具定义。原始材料中提到动态 Agent 列表曾贡献了约 10.2% 的 cache_creation tokens。这个数字说明很多成本浪费不是来自模型“不聪明”而是来自请求结构“不稳定”。六、模式四技能列表预算用 1% 窗口管住膨胀技能列表和 Agent 列表类似也会随着项目、插件、配置变化而增长。如果把所有技能的详细说明都塞到工具提示里会带来两个问题一是 token 成本变高二是列表稍有变化就容易影响缓存。解决方案是给技能列表设置预算比如限制在上下文窗口的 1% 左右同时限制单个技能描述的长度。这样做不是削弱能力而是把“发现能力”和“完整加载能力”拆开列表只负责让模型知道有什么真正使用时再加载完整内容。预算的意义不只是省 token更重要的是减少抖动。当列表达到预算上限后新增内容不会轻易改变前缀结构缓存键更稳定。七、模式五$TMPDIR 占位符消除用户维度差异缓存命中要求内容一致。但不同用户的本地路径往往不同例如临时目录里带有 UID。用户 A 是一条路径用户 B 是另一条路径语义上都是临时目录但字节不一样跨用户缓存就难以共享。解决方式是用统一占位符表达临时目录例如 $TMPDIR。运行时由环境变量指向真实目录提示里不再暴露用户特定路径。这个模式的启发很大不要把用户 ID、机器路径、临时目录、项目绝对路径这类高度个性化内容放进稳定前缀。能抽象成变量就不要写死成每个人不同的字符串。八、模式六条件段落省略功能开关不要搅动前缀很多工程系统喜欢用 feature flag 控制提示词片段开关打开时加一段说明关闭时删掉一段说明。这样很灵活但对缓存不友好。因为远程配置一刷新前缀内容就可能变。更稳的做法有三种能一直保留就一直保留能一直省略就一直省略必须动态变化的内容放到动态边界或消息附件之后。核心原则是前缀中的内容要尽量单调稳定不要因为开关翻转一会儿出现、一会儿消失。九、模式七工具 Schema 会话级缓存把中途变化挡在外面工具 Schema 的生成过程可能受到很多因素影响例如功能开关、工具描述、MCP 工具变化、结构化输出配置等。如果每次请求都重新生成工具 Schema中途任何一个配置变化都可能造成缓存中断。会话级缓存的思路是第一次请求时把工具 Schema 渲染出来并锁定后续请求直接复用同一份结果。这样即使远程配置中途刷新也不会让会话内的工具定义突然变化。这里还有一个关键细节缓存键必须设计正确。普通工具可以用工具名做键但如果某类工具名称相同、内部结构不同就必须把结构信息纳入缓存键。否则缓存不是优化而是 bug 放大器。十、共同本质先后移再统一再降频最后限幅把这些模式放在一起看会发现它们不是零散技巧而是一条固定决策链。遇到动态内容优先判断能不能后移不能后移再看能不能标准化无法标准化就降低变化频率再不行就用预算限制变化幅度。这条链路可以应用到任何 AI Agent 系统中日期、路径、用户配置、工具列表、插件列表、权限说明、外部服务状态、模型开关都可以按这套方法审计。十一、普通开发者最容易踩的坑常见坑为什么危险更稳的做法在提示前缀里放时间戳每次请求都变使用会话级时间或放到尾部工具列表实时拼接插件变化会改 Schema工具说明静态化动态列表附件化路径写成绝对地址不同机器不同字节使用环境变量或占位符feature flag 直接控制提示片段远程配置刷新会抖动固定文本或放到动态边界后技能说明无限增长成本高且列表易变预算控制调用时再加载十二、落地检查清单把缓存稳定性纳入工程规范真正成熟的 AI Agent 工程不会等到费用暴涨、延迟变高才开始优化而是在设计提示词、工具、插件、技能、上下文结构时就把缓存稳定性作为基础指标。可以从三个指标观察系统是否健康cache_creation_input_tokens 是否只在前几轮偏高cache_read_input_tokens 是否逐步成为主导长会话中是否频繁出现缓存读数突然下降。如果读数突然下降大概率说明某个前缀块发生了变化。十三、总结缓存优化不是小技巧而是 Agent 成本治理体系Claude Code 的缓存优化模式给 AI Agent 工程带来一个非常重要的启发成本优化不是最后做的运维工作而应该前置到架构设计阶段。只要一段内容会进入请求前缀就必须考虑它的变化频率、变化范围和稳定性。日期记忆化解决跨天变化月度粒度降低时间精度Agent 列表附件化保护工具 Schema技能预算管住列表膨胀$TMPDIR 占位符消除用户差异条件段落省略减少功能开关抖动工具 Schema 缓存把中途变化锁在会话之外。一句话总结AI Agent 越复杂越不能只靠“写好提示词”。真正的长期稳定来自上下文工程、缓存工程、工具工程和可观测性工程的协同。谁能让上下文稳定复用谁就能在成本、速度和体验上建立优势。参考资料https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd6fkr
Claude Code 缓存优化模式全解析：AI Agent 上下文工程、Prompt Cache、工具 Schema 缓存、Token 成本优化
发布时间：2026/5/16 21:07:33
很多人做 AI Agent只盯着模型、工具和提示词却忽略了一个真正会影响成本、延迟和稳定性的底层问题缓存到底能不能持续命中。一个看似无关紧要的日期、路径、功能开关、工具列表都可能让前面已经缓存好的大段内容重新计算。这套缓存优化思想的核心很朴素先找到变化源再判断它是否必须放在请求前面。如果必须放前面就降低变化频率如果不必须就尽量移动到消息尾部如果是用户差异就用占位符统一如果是列表膨胀就用预算管住。一、为什么缓存优化是 AI Agent 的隐藏胜负手AI Agent 的一次请求通常不只是用户的一句话还包括工具定义、系统规则、历史消息、项目上下文、技能说明、权限说明等大量内容。随着会话变长这些内容会越来越重。Prompt Cache 的价值就是把前面稳定、重复的大块内容复用起来避免每次都从零处理。问题在于缓存依赖稳定前缀。只要前缀里的字节发生变化缓存命中就会下降。模型并不会因为两段内容“意思差不多”就复用缓存它更像是在比较一串精确的输入。Anthropic 官方文档建议把稳定、可复用的内容放在提示开头例如系统指令、背景资料、大上下文或常用工具定义并使用缓存断点管理不同变化频率的内容。工具相关文档也强调工具定义同样可以与 Prompt Caching 结合用来降低重复工具 Schema 的成本。二、整体方法论识别变化源把动态变静态缓存优化不是单点技巧而是一套工程纪律。每当某段内容要进入请求体时都要问四个问题它会不会变多久变一次必须放在前面吗能不能通过标准化、记忆化、预算、附件化来减少变化三、模式一日期记忆化让跨天不再打穿缓存很多系统都会在提示中放入当前日期用来帮助模型理解时间背景。看起来很自然但它有一个致命问题午夜一过日期就变。假设前一轮还是 2026-04-01下一轮变成 2026-04-02即使只变了一个字符也可能让前面大段缓存失效。解决思路是把日期固定为“会话开始时的日期”。第一次获取后就记住后续请求一直使用同一个值。这样做的本质不是追求绝对实时而是承认编程任务里日期通常不是核心变量缓存稳定性比跨午夜的日期精度更重要。这个设计背后的取舍很清晰宁愿日期在极少数场景下稍微滞后也不要让整个稳定前缀因为午夜切换而重新计算。对于长时间连续工作的用户这种优化非常实用。四、模式二月度粒度让工具提示少受日期影响系统提示需要日期工具提示有时也需要时间信息。但工具 Schema 通常更靠前、更敏感一旦变化影响更大。因此工具提示里的时间不一定要精确到天很多场景只需要“当前月份和年份”。把完整日期降级成月份年份本质是降低变化频率从每天变化一次变成每月变化一次。变化频率越低缓存越容易稳定。这体现了一个重要原则越靠近请求前端的内容越应该低频变化越靠近消息尾部的内容才适合承载高频变化。五、模式三Agent 列表附件化别把动态清单塞进工具描述Agent 列表是一类典型的动态内容。插件加载、MCP 连接变化、权限模式切换都可能改变可用 Agent 的数量、名称和描述。如果把这份列表直接写在工具描述里每次列表变化都会让工具 Schema 跟着变化。更好的办法是工具描述只保留静态能力说明真正动态的 Agent 列表通过消息附件追加到后面。这样即使 Agent 清单变化也只是尾部内容变化不会打穿前面已经缓存的工具定义。原始材料中提到动态 Agent 列表曾贡献了约 10.2% 的 cache_creation tokens。这个数字说明很多成本浪费不是来自模型“不聪明”而是来自请求结构“不稳定”。六、模式四技能列表预算用 1% 窗口管住膨胀技能列表和 Agent 列表类似也会随着项目、插件、配置变化而增长。如果把所有技能的详细说明都塞到工具提示里会带来两个问题一是 token 成本变高二是列表稍有变化就容易影响缓存。解决方案是给技能列表设置预算比如限制在上下文窗口的 1% 左右同时限制单个技能描述的长度。这样做不是削弱能力而是把“发现能力”和“完整加载能力”拆开列表只负责让模型知道有什么真正使用时再加载完整内容。预算的意义不只是省 token更重要的是减少抖动。当列表达到预算上限后新增内容不会轻易改变前缀结构缓存键更稳定。七、模式五$TMPDIR 占位符消除用户维度差异缓存命中要求内容一致。但不同用户的本地路径往往不同例如临时目录里带有 UID。用户 A 是一条路径用户 B 是另一条路径语义上都是临时目录但字节不一样跨用户缓存就难以共享。解决方式是用统一占位符表达临时目录例如 $TMPDIR。运行时由环境变量指向真实目录提示里不再暴露用户特定路径。这个模式的启发很大不要把用户 ID、机器路径、临时目录、项目绝对路径这类高度个性化内容放进稳定前缀。能抽象成变量就不要写死成每个人不同的字符串。八、模式六条件段落省略功能开关不要搅动前缀很多工程系统喜欢用 feature flag 控制提示词片段开关打开时加一段说明关闭时删掉一段说明。这样很灵活但对缓存不友好。因为远程配置一刷新前缀内容就可能变。更稳的做法有三种能一直保留就一直保留能一直省略就一直省略必须动态变化的内容放到动态边界或消息附件之后。核心原则是前缀中的内容要尽量单调稳定不要因为开关翻转一会儿出现、一会儿消失。九、模式七工具 Schema 会话级缓存把中途变化挡在外面工具 Schema 的生成过程可能受到很多因素影响例如功能开关、工具描述、MCP 工具变化、结构化输出配置等。如果每次请求都重新生成工具 Schema中途任何一个配置变化都可能造成缓存中断。会话级缓存的思路是第一次请求时把工具 Schema 渲染出来并锁定后续请求直接复用同一份结果。这样即使远程配置中途刷新也不会让会话内的工具定义突然变化。这里还有一个关键细节缓存键必须设计正确。普通工具可以用工具名做键但如果某类工具名称相同、内部结构不同就必须把结构信息纳入缓存键。否则缓存不是优化而是 bug 放大器。十、共同本质先后移再统一再降频最后限幅把这些模式放在一起看会发现它们不是零散技巧而是一条固定决策链。遇到动态内容优先判断能不能后移不能后移再看能不能标准化无法标准化就降低变化频率再不行就用预算限制变化幅度。这条链路可以应用到任何 AI Agent 系统中日期、路径、用户配置、工具列表、插件列表、权限说明、外部服务状态、模型开关都可以按这套方法审计。十一、普通开发者最容易踩的坑常见坑为什么危险更稳的做法在提示前缀里放时间戳每次请求都变使用会话级时间或放到尾部工具列表实时拼接插件变化会改 Schema工具说明静态化动态列表附件化路径写成绝对地址不同机器不同字节使用环境变量或占位符feature flag 直接控制提示片段远程配置刷新会抖动固定文本或放到动态边界后技能说明无限增长成本高且列表易变预算控制调用时再加载十二、落地检查清单把缓存稳定性纳入工程规范真正成熟的 AI Agent 工程不会等到费用暴涨、延迟变高才开始优化而是在设计提示词、工具、插件、技能、上下文结构时就把缓存稳定性作为基础指标。可以从三个指标观察系统是否健康cache_creation_input_tokens 是否只在前几轮偏高cache_read_input_tokens 是否逐步成为主导长会话中是否频繁出现缓存读数突然下降。如果读数突然下降大概率说明某个前缀块发生了变化。十三、总结缓存优化不是小技巧而是 Agent 成本治理体系Claude Code 的缓存优化模式给 AI Agent 工程带来一个非常重要的启发成本优化不是最后做的运维工作而应该前置到架构设计阶段。只要一段内容会进入请求前缀就必须考虑它的变化频率、变化范围和稳定性。日期记忆化解决跨天变化月度粒度降低时间精度Agent 列表附件化保护工具 Schema技能预算管住列表膨胀$TMPDIR 占位符消除用户差异条件段落省略减少功能开关抖动工具 Schema 缓存把中途变化锁在会话之外。一句话总结AI Agent 越复杂越不能只靠“写好提示词”。真正的长期稳定来自上下文工程、缓存工程、工具工程和可观测性工程的协同。谁能让上下文稳定复用谁就能在成本、速度和体验上建立优势。参考资料https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd6fkr
