一、先说结论Prompt Cache 不是小优化而是 Agent 成本护城河很多人理解大模型应用只盯着模型能力、提示词技巧、工具调用和多 Agent 编排。但在真实工程里成本和延迟往往不是被模型本身拖垮而是被“重复上下文”拖垮。一个复杂编码助手每一轮都可能携带系统规则、工具定义、历史消息、文件摘要、计划状态和安全约束。如果这些内容每次都从零处理Token 消耗会像滚雪球一样变大。Prompt Cache 的核心价值就是把稳定不变的前缀缓存起来。后续请求只要前缀保持一致就可以直接复用已有结果只处理新追加的部分。对长会话、工具密集型任务和企业级 Agent 来说这不是锦上添花而是决定能不能长期跑下去的基础设施。更关键的是缓存并不是“加一个开关”就完事。真正难的是哪些内容能缓存哪些内容不能缓存缓存断点放哪里功能开关变化会不会击穿缓存用户配额变化会不会改变请求形态外部工具动态加入后怎么办这些才是缓存架构的核心难点。二、为什么缓存会成为 AI Agent 的隐形成本中心把一次 Agent 请求想象成寄快递系统提示词是说明书工具定义是配件清单消息历史是沟通记录用户新问题是最新需求。如果每次都把整箱说明书和配件清单重新寄一遍当然浪费。在复杂编码助手里固定开销可能非常大系统规则、工具说明、权限提示、安全限制、输出规范、项目上下文叠加起来很容易达到数万 Token。若连续几十轮都重复传输和处理成本会被放大很多倍。Prompt Cache 的思路很直接第一次完整处理后续在前缀不变的情况下复用。它像给大模型请求装了一个“高速 ETC”稳定内容走缓存通道新内容走普通通道。三、前缀匹配缓存能不能命中取决于开头是否稳定3.1 缓存不是语义相似而是精确匹配很多人容易误会只要提示词意思差不多缓存就能命中。实际不是这样。Prompt Cache 更像“逐字节核对”同一个位置只要出现差异差异之后的部分就不能继续复用。这意味着缓存友好的请求必须把稳定内容放在前面把变化内容放在后面。比如工具定义、系统规则、固定背景资料适合靠前时间戳、用户输入、临时附件、会话变量适合靠后。3.2 请求顺序决定缓存损失范围对于工具型 Agent 来说请求通常可以理解为三段工具定义、系统提示词、消息历史。越靠前的内容变化影响越大。工具定义变了后面系统提示词和消息历史都会受影响只是末尾用户消息变了前面的大块稳定内容仍然有机会复用。位置内容类型变化后的影响工程建议最前面工具定义影响最大可能导致全链路缓存失效保持工具集合稳定动态工具不要随意插入前缀中间系统规则影响系统规则之后的缓存把固定规则与动态变量分开靠后历史消息主要影响后续消息增量长会话要配合压缩和断点末尾用户新输入影响最小尽量让变化只发生在末尾四、缓存断点把“值得复用的边界”明确标出来缓存断点可以理解为给请求打上书签告诉模型服务端“到这里为止的内容希望下次还能复用”。断点放错缓存就会变成摆设断点放对重复前缀就能持续产生价值。最常见的错误是把断点放在变化内容之后。比如最后一个块里含有时间、用户问题、临时参数下一次请求这个块必然变化缓存自然无法命中。正确做法是把断点放在“最后一个稳定块”的末尾。多个断点的价值在于不同内容变化频率不同。工具定义可能很少变系统规则偶尔变项目上下文可能阶段性变消息历史则持续增长。把它们切成多个缓存段比把所有内容混成一团更稳。五、三级缓存范围global、org、null 的分层设计一个成熟的缓存系统不会一刀切。它会先判断内容的共享范围有些内容所有用户都一样有些内容只在同一组织内一样有些内容每个人每次都可能不同。5.1 global只给绝对静态内容global 适合所有用户都完全一致的内容比如通用能力说明、固定行为规范、不会夹带用户身份和组织信息的稳定规则。它的复用范围最大但要求也最苛刻。这里的核心原则是只要内容里可能出现用户、组织、时间、实验开关、动态工具就不要轻易放进 global。否则命中率看似变高实际会频繁被击穿。5.2 org组织内可复用的稳定内容org 适合组织级稳定内容例如同一团队共用的配置、规则或工具说明。它比 global 保守但更容易保证稳定。对于企业内部 Agent这通常是更实用的缓存范围。5.3 null动态内容不硬缓存null 不是失败而是理性放弃。用户身份、计费归属、临时状态、时间敏感信息、动态上下文如果硬塞进缓存反而会增加复杂度让命中率更差。缓存范围复用粒度适合内容不适合内容global跨用户复用完全静态的基础规则用户信息、组织信息、动态工具org组织内复用组织级稳定规则、常驻工具说明个人身份、临时状态null不做缓存标记高度动态内容稳定大段前缀六、TTL 层级5 分钟与 1 小时不是谁更高级而是谁更合适TTL 可以理解为缓存的保质期。默认短 TTL 适合连续高频对话长 TTL 适合长时间任务、批处理、用户中途停顿或 Agent 慢慢执行的场景。短 TTL 的优势是成本更轻、命中后持续刷新缺点是用户一旦停顿太久缓存就会过期。长 TTL 的优势是可以跨越更长停顿缺点是写入成本更高因此要用于真正需要保活的长任务。工程上最容易踩坑的是会话开始时用 1 小时 TTL进行到一半因为配额、开关或策略变化突然降回 5 分钟。这个变化会改变请求形态进而导致缓存键不一致。于是系统需要锁存。七、锁存机制保护缓存键稳定的关键模式锁存可以理解为“会话内只做一次关键判断”。第一次判断某个用户是否具备长 TTL 资格、某个功能开关是否进入请求、某个 Header 是否需要发送之后在同一轮会话中保持稳定不要一会儿开一会儿关。锁存背后的哲学很朴素宁可在当前会话里使用一个略微过时但稳定的判断也不要每一轮都让请求结构变来变去。因为缓存系统最怕的不是少缓存而是缓存键反复漂移。锁存对象为什么要锁存不锁存的风险TTL 资格防止配额状态中途变化缓存控制字段变化前缀被击穿Feature Flag 配置防止实验配置刷新请求参数忽有忽无Beta Header防止功能开关改变缓存键服务端缓存键发生变化Thinking 清理状态防止过期后继续携带冗余内容长会话负担持续增加八、Beta Header sticky-on功能可以关但缓存键别乱变在模型 API 请求中一些实验能力、模式状态、缓存编辑能力可能通过 Header 进入请求。Header 往往也是缓存键的一部分所以它们的变化会影响缓存命中。例如自动执行模式、快速模式、缓存编辑能力在会话中可能被开启或关闭。如果每次开关都导致 Header 添加或移除那么请求在服务端看来就是不同形态缓存自然容易中断。sticky-on 的意思是某个 Header 一旦在当前会话中被发送过就持续发送。即使触发它的功能后来关闭也不让 Header 从请求里消失。这样做不是为了功能逻辑而是为了缓存键稳定。这是一种非常值得借鉴的工程模式凡是会进入缓存键的动态字段都要特别谨慎。功能开关可以动态缓存键最好稳定。九、外部工具缓存命中率最大的变量之一外部工具的动态性很强工具可能来自远端服务可能会新增、删除、排序变化也可能因为连接状态不同而出现不同定义。对于前缀缓存来说这些变化非常危险。如果把动态工具定义直接塞进最前面的工具列表每次工具集合变化都可能让整个后续前缀失效。更稳的做法是核心工具常驻且缓存动态工具延迟加载或单独引用尽量不要污染主缓存前缀。这也是为什么工具系统设计不能只看“能不能调用”还要看“调用方式会不会破坏上下文稳定性”。一个会省钱、会提速的 Agent 工具层必须从缓存角度设计。十、Thinking Clear缓存过期后旧思考内容该清就清长会话中模型可能积累大量中间思考、分析片段或状态说明。当缓存仍然命中时这些内容可能还有复用价值但当缓存已经自然过期再继续携带它们就容易变成负担。Thinking Clear 的思路是如果距离上次模型完成已经超过长 TTL 级别说明缓存大概率已经不可复用。此时可以清理一部分旧 thinking 内容减少后续请求体积。这背后其实是上下文工程的一个原则上下文不是越多越好而是要根据缓存状态、任务阶段、信息价值不断治理。十一、完整缓存架构从请求构建到命中观测把这些机制组合起来就能看到一套完整缓存架构先构建请求再切分稳定范围再决定 TTL再锁存动态字段最后通过指标观察命中健康度。这套架构的目标不是“尽可能缓存所有东西”而是“只缓存值得缓存、能稳定复用、不会泄露边界、不会频繁变化的内容”。成熟 Agent 的缓存系统本质是成本、性能、安全、灵活性的平衡缓存范围太激进容易命中不稳范围太保守又浪费大量 Token断点太少长会话找不到旧前缀断点太乱又增加维护复杂度。十二、面向普通开发者的落地方法12.1 把稳定内容放到最前面系统角色、固定规则、常驻工具、长背景资料应尽量放在请求前部。这样后面的用户输入、临时变量、文件片段变化时不会影响前面大段缓存。12.2 动态内容永远不要污染静态前缀时间、随机数、请求编号、用户身份、临时开关、实验分组如果放在系统提示词前部就像在缓存钥匙上反复刻新字。每变一次缓存就可能失效。12.3 功能开关要么不进缓存键要么会话内锁住Feature Flag 很好用但它一旦影响请求结构就会影响缓存稳定。工程上最好在会话开始时固定避免运行中不断刷新配置。12.4 工具定义要分常驻与延迟高频、稳定、核心工具适合常驻并缓存低频、外部、动态工具更适合延迟加载。这样既能保持能力扩展又能保护主前缀。12.5 监控 cache_read_input_tokens判断缓存有没有价值不能靠感觉。最直接的指标是缓存读取 Token。如果输入很大但缓存读取几乎为零就说明缓存设计存在问题需要排查断点、动态字段、工具变化和 Header 变化。十三、爆款总结Prompt Cache 的本质是给 Agent 装上“上下文复用大脑”1. Prompt Cache 不是简单省钱技巧而是 AI Agent 长会话工程的底层能力。2. 缓存命中依赖前缀稳定稳定内容必须靠前动态内容必须靠后。3. 三级范围 global、org、null 解决的是“哪些内容能被谁复用”的问题。4. 5 分钟和 1 小时 TTL 解决的是“缓存应该保留多久”的问题。5. 锁存机制解决的是“会话中途状态变化不要击穿缓存键”的问题。6. 外部工具、功能开关、Header、时间戳都是缓存稳定性的常见敌人。7. 真正成熟的 Agent 系统不只是会调用模型和工具还要会管理上下文、控制成本、保护缓存、观测命中率。一句话收尾Prompt 写得好只能让模型单次表现更好缓存架构设计得好才能让 Agent 在长任务、长会话、高频工具调用里稳定、便宜、快速地跑下去。资料参考https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd6fkr
Claude Code 缓存架构与断点设计全解析：Prompt Cache、上下文工程、Token 成本优化、AI Agent 长会话性能治理
一、先说结论Prompt Cache 不是小优化而是 Agent 成本护城河很多人理解大模型应用只盯着模型能力、提示词技巧、工具调用和多 Agent 编排。但在真实工程里成本和延迟往往不是被模型本身拖垮而是被“重复上下文”拖垮。一个复杂编码助手每一轮都可能携带系统规则、工具定义、历史消息、文件摘要、计划状态和安全约束。如果这些内容每次都从零处理Token 消耗会像滚雪球一样变大。Prompt Cache 的核心价值就是把稳定不变的前缀缓存起来。后续请求只要前缀保持一致就可以直接复用已有结果只处理新追加的部分。对长会话、工具密集型任务和企业级 Agent 来说这不是锦上添花而是决定能不能长期跑下去的基础设施。更关键的是缓存并不是“加一个开关”就完事。真正难的是哪些内容能缓存哪些内容不能缓存缓存断点放哪里功能开关变化会不会击穿缓存用户配额变化会不会改变请求形态外部工具动态加入后怎么办这些才是缓存架构的核心难点。二、为什么缓存会成为 AI Agent 的隐形成本中心把一次 Agent 请求想象成寄快递系统提示词是说明书工具定义是配件清单消息历史是沟通记录用户新问题是最新需求。如果每次都把整箱说明书和配件清单重新寄一遍当然浪费。在复杂编码助手里固定开销可能非常大系统规则、工具说明、权限提示、安全限制、输出规范、项目上下文叠加起来很容易达到数万 Token。若连续几十轮都重复传输和处理成本会被放大很多倍。Prompt Cache 的思路很直接第一次完整处理后续在前缀不变的情况下复用。它像给大模型请求装了一个“高速 ETC”稳定内容走缓存通道新内容走普通通道。三、前缀匹配缓存能不能命中取决于开头是否稳定3.1 缓存不是语义相似而是精确匹配很多人容易误会只要提示词意思差不多缓存就能命中。实际不是这样。Prompt Cache 更像“逐字节核对”同一个位置只要出现差异差异之后的部分就不能继续复用。这意味着缓存友好的请求必须把稳定内容放在前面把变化内容放在后面。比如工具定义、系统规则、固定背景资料适合靠前时间戳、用户输入、临时附件、会话变量适合靠后。3.2 请求顺序决定缓存损失范围对于工具型 Agent 来说请求通常可以理解为三段工具定义、系统提示词、消息历史。越靠前的内容变化影响越大。工具定义变了后面系统提示词和消息历史都会受影响只是末尾用户消息变了前面的大块稳定内容仍然有机会复用。位置内容类型变化后的影响工程建议最前面工具定义影响最大可能导致全链路缓存失效保持工具集合稳定动态工具不要随意插入前缀中间系统规则影响系统规则之后的缓存把固定规则与动态变量分开靠后历史消息主要影响后续消息增量长会话要配合压缩和断点末尾用户新输入影响最小尽量让变化只发生在末尾四、缓存断点把“值得复用的边界”明确标出来缓存断点可以理解为给请求打上书签告诉模型服务端“到这里为止的内容希望下次还能复用”。断点放错缓存就会变成摆设断点放对重复前缀就能持续产生价值。最常见的错误是把断点放在变化内容之后。比如最后一个块里含有时间、用户问题、临时参数下一次请求这个块必然变化缓存自然无法命中。正确做法是把断点放在“最后一个稳定块”的末尾。多个断点的价值在于不同内容变化频率不同。工具定义可能很少变系统规则偶尔变项目上下文可能阶段性变消息历史则持续增长。把它们切成多个缓存段比把所有内容混成一团更稳。五、三级缓存范围global、org、null 的分层设计一个成熟的缓存系统不会一刀切。它会先判断内容的共享范围有些内容所有用户都一样有些内容只在同一组织内一样有些内容每个人每次都可能不同。5.1 global只给绝对静态内容global 适合所有用户都完全一致的内容比如通用能力说明、固定行为规范、不会夹带用户身份和组织信息的稳定规则。它的复用范围最大但要求也最苛刻。这里的核心原则是只要内容里可能出现用户、组织、时间、实验开关、动态工具就不要轻易放进 global。否则命中率看似变高实际会频繁被击穿。5.2 org组织内可复用的稳定内容org 适合组织级稳定内容例如同一团队共用的配置、规则或工具说明。它比 global 保守但更容易保证稳定。对于企业内部 Agent这通常是更实用的缓存范围。5.3 null动态内容不硬缓存null 不是失败而是理性放弃。用户身份、计费归属、临时状态、时间敏感信息、动态上下文如果硬塞进缓存反而会增加复杂度让命中率更差。缓存范围复用粒度适合内容不适合内容global跨用户复用完全静态的基础规则用户信息、组织信息、动态工具org组织内复用组织级稳定规则、常驻工具说明个人身份、临时状态null不做缓存标记高度动态内容稳定大段前缀六、TTL 层级5 分钟与 1 小时不是谁更高级而是谁更合适TTL 可以理解为缓存的保质期。默认短 TTL 适合连续高频对话长 TTL 适合长时间任务、批处理、用户中途停顿或 Agent 慢慢执行的场景。短 TTL 的优势是成本更轻、命中后持续刷新缺点是用户一旦停顿太久缓存就会过期。长 TTL 的优势是可以跨越更长停顿缺点是写入成本更高因此要用于真正需要保活的长任务。工程上最容易踩坑的是会话开始时用 1 小时 TTL进行到一半因为配额、开关或策略变化突然降回 5 分钟。这个变化会改变请求形态进而导致缓存键不一致。于是系统需要锁存。七、锁存机制保护缓存键稳定的关键模式锁存可以理解为“会话内只做一次关键判断”。第一次判断某个用户是否具备长 TTL 资格、某个功能开关是否进入请求、某个 Header 是否需要发送之后在同一轮会话中保持稳定不要一会儿开一会儿关。锁存背后的哲学很朴素宁可在当前会话里使用一个略微过时但稳定的判断也不要每一轮都让请求结构变来变去。因为缓存系统最怕的不是少缓存而是缓存键反复漂移。锁存对象为什么要锁存不锁存的风险TTL 资格防止配额状态中途变化缓存控制字段变化前缀被击穿Feature Flag 配置防止实验配置刷新请求参数忽有忽无Beta Header防止功能开关改变缓存键服务端缓存键发生变化Thinking 清理状态防止过期后继续携带冗余内容长会话负担持续增加八、Beta Header sticky-on功能可以关但缓存键别乱变在模型 API 请求中一些实验能力、模式状态、缓存编辑能力可能通过 Header 进入请求。Header 往往也是缓存键的一部分所以它们的变化会影响缓存命中。例如自动执行模式、快速模式、缓存编辑能力在会话中可能被开启或关闭。如果每次开关都导致 Header 添加或移除那么请求在服务端看来就是不同形态缓存自然容易中断。sticky-on 的意思是某个 Header 一旦在当前会话中被发送过就持续发送。即使触发它的功能后来关闭也不让 Header 从请求里消失。这样做不是为了功能逻辑而是为了缓存键稳定。这是一种非常值得借鉴的工程模式凡是会进入缓存键的动态字段都要特别谨慎。功能开关可以动态缓存键最好稳定。九、外部工具缓存命中率最大的变量之一外部工具的动态性很强工具可能来自远端服务可能会新增、删除、排序变化也可能因为连接状态不同而出现不同定义。对于前缀缓存来说这些变化非常危险。如果把动态工具定义直接塞进最前面的工具列表每次工具集合变化都可能让整个后续前缀失效。更稳的做法是核心工具常驻且缓存动态工具延迟加载或单独引用尽量不要污染主缓存前缀。这也是为什么工具系统设计不能只看“能不能调用”还要看“调用方式会不会破坏上下文稳定性”。一个会省钱、会提速的 Agent 工具层必须从缓存角度设计。十、Thinking Clear缓存过期后旧思考内容该清就清长会话中模型可能积累大量中间思考、分析片段或状态说明。当缓存仍然命中时这些内容可能还有复用价值但当缓存已经自然过期再继续携带它们就容易变成负担。Thinking Clear 的思路是如果距离上次模型完成已经超过长 TTL 级别说明缓存大概率已经不可复用。此时可以清理一部分旧 thinking 内容减少后续请求体积。这背后其实是上下文工程的一个原则上下文不是越多越好而是要根据缓存状态、任务阶段、信息价值不断治理。十一、完整缓存架构从请求构建到命中观测把这些机制组合起来就能看到一套完整缓存架构先构建请求再切分稳定范围再决定 TTL再锁存动态字段最后通过指标观察命中健康度。这套架构的目标不是“尽可能缓存所有东西”而是“只缓存值得缓存、能稳定复用、不会泄露边界、不会频繁变化的内容”。成熟 Agent 的缓存系统本质是成本、性能、安全、灵活性的平衡缓存范围太激进容易命中不稳范围太保守又浪费大量 Token断点太少长会话找不到旧前缀断点太乱又增加维护复杂度。十二、面向普通开发者的落地方法12.1 把稳定内容放到最前面系统角色、固定规则、常驻工具、长背景资料应尽量放在请求前部。这样后面的用户输入、临时变量、文件片段变化时不会影响前面大段缓存。12.2 动态内容永远不要污染静态前缀时间、随机数、请求编号、用户身份、临时开关、实验分组如果放在系统提示词前部就像在缓存钥匙上反复刻新字。每变一次缓存就可能失效。12.3 功能开关要么不进缓存键要么会话内锁住Feature Flag 很好用但它一旦影响请求结构就会影响缓存稳定。工程上最好在会话开始时固定避免运行中不断刷新配置。12.4 工具定义要分常驻与延迟高频、稳定、核心工具适合常驻并缓存低频、外部、动态工具更适合延迟加载。这样既能保持能力扩展又能保护主前缀。12.5 监控 cache_read_input_tokens判断缓存有没有价值不能靠感觉。最直接的指标是缓存读取 Token。如果输入很大但缓存读取几乎为零就说明缓存设计存在问题需要排查断点、动态字段、工具变化和 Header 变化。十三、爆款总结Prompt Cache 的本质是给 Agent 装上“上下文复用大脑”1. Prompt Cache 不是简单省钱技巧而是 AI Agent 长会话工程的底层能力。2. 缓存命中依赖前缀稳定稳定内容必须靠前动态内容必须靠后。3. 三级范围 global、org、null 解决的是“哪些内容能被谁复用”的问题。4. 5 分钟和 1 小时 TTL 解决的是“缓存应该保留多久”的问题。5. 锁存机制解决的是“会话中途状态变化不要击穿缓存键”的问题。6. 外部工具、功能开关、Header、时间戳都是缓存稳定性的常见敌人。7. 真正成熟的 Agent 系统不只是会调用模型和工具还要会管理上下文、控制成本、保护缓存、观测命中率。一句话收尾Prompt 写得好只能让模型单次表现更好缓存架构设计得好才能让 Agent 在长任务、长会话、高频工具调用里稳定、便宜、快速地跑下去。资料参考https://pan.baidu.com/s/1Fm6rZSZkY3q2NcrmTfTMeQ?pwd6fkr
