★ FEATURED ARTICLE 做 Coding Agent 的人迟早会盯上同一个指标缓存命中率。原因很直接。Coding Agent 是典型的「长上下文 多轮迭代」场景——读文件、跑命令、改代码、再读再改每一轮都要把完整历史重新发给模型。历史越长重复付费越多。业界对这件事的重视程度可能超出你的想象Manus 团队曾公开表示如果只能选一个指标KV 缓存命中率是生产级 AI Agent 最重要的单一指标Anthropic 的 Claude Code 团队更是对命中率设置了告警——一旦命中率过低就触发严重事件SEV和对待系统宕机一个级别。更关键的是在 Coding Agent 里缓存不是「优化项」而是「架构地基」。你的提示词结构、工具设计、会话管理方式几乎都要围着它设计。这篇文章就把「怎么把命中率做上去」讲清楚。一、先记住一条规则缓存按「前缀」逐字匹配所有优化都从这一条衍生而来缓存匹配是逐字的、从前向后的。请求开头只要有任何一个 token 变了从变化点往后的全部内容都得重算。一个典型的 Agent 请求长这样[tools 工具定义] → [system 提示词] → [项目规则 CLAUDE.md] → [对话历史] → [工具返回结果] → [本轮用户消息]只有这段序列的前面部分与上次请求逐字一致时匹配上的那一段才能按缓存价计费。三家主流厂商的实现方式略有不同先看清差异维度ClaudeOpenAIDeepSeek控制方式显式用cache_control指定断点自动前缀够长1024 token 起自动尝试默认开启无需改代码命中条件断点之前内容逐字一致精确前缀匹配需先完整持久化前缀单元缓存读取价约0.1x写入 5m 为 1.25x、1h 为 2x提供折扣读价价差最大可达数十倍有效期默认 5 分钟可选 1 小时通常 5–10 分钟不活跃失效数小时至数天自动清理一句话Claude 最可控但工程要求最高OpenAI 最省心但控制感弱DeepSeek 价差最猛但依赖链路透明。二、为什么 Coding Agent 天生不容易命中如果你直连 API写个固定 prompt 很容易命中。但 Coding Agent 没那么简单——它已经不是一个 agent而是一整套调度系统要管工具、压缩上下文、切模式、拉子任务。麻烦就出在这里请求前缀里塞满了工具定义、项目规则、权限模式、MCP schema、git 状态、历史消息……该长期稳定的和每轮都变的混在了一起。四个反复出问题的环节1. 动态 system prompt。当前时间、工作目录、git 状态、权限模式、token 预算——这些每轮都可能变。一旦混进靠前的 system prompt就把原本稳定的前缀拖成了动态前缀。2. tool schema。MCP server 一多工具定义又长又容易变直接扰动前缀。3. 中途切换模型。缓存是按模型隔离的切了模型缓存完全不通用。你以为「复杂任务用强模型、简单任务用便宜模型」能省钱实际是——在强模型上攒的 10 万 Token 稳定缓存切到便宜模型后要全额重建重建成本远大于模型差价。4. 自动压缩与子代理。compaction 能降总 token但会改写 messages 前缀、打断缓存链subagent 各有自己的 prompt、工具与规则不必然共享主会话缓存反而可能让 token 烧得更快。此外还有一个容易被忽略的坑统计口径。很多框架统一成简单格式只留一个总输入 tokencache_creation与cache_read全被抹平你根本看不到缓存到底有没有生效。三、六条实操技巧来自 Claude Code 团队的经验技巧一静态前置动态后置。这是最基础、也最重要的一条。Claude Code 的请求是分层的层内容缓存粒度最外层静态 system 提示词 工具定义全局缓存跨会话共享第二层项目规则CLAUDE.md项目内缓存第三层会话上下文会话内缓存末尾对话消息不缓存每轮都变越稳定的越往前放越易变的越往后放。cache_control断点要打在稳定内容之后这样后面的用户问题随便变前面那段前缀仍能复用。技巧二动态信息走「消息」别改系统提示词。「现在是星期三」「用户刚改了某个文件」这类信息直觉上是直接改 system 提示词。但这么做代价极大——整段缓存直接失效。正确做法把动态信息作为一条消息追加在对话末尾。Claude Code 的做法是在用户消息里加一个标签注入这类信息前缀完全没动缓存自然保住。由此得出一条黄金规范长期规则写进项目文件CLAUDE.md临时变化全部进对话消息。技巧三会话中途不要切模型。理由前面已经说了——缓存按模型隔离。真想用不同模型正确姿势是用子代理subagent做侧活主线模型不动、长前缀不动子代理独立跑自己的缓存。技巧四工具定义延迟加载。工具一多光工具定义就吃掉大量 token而且经常变动。Claude Code 的解法是「延迟加载」默认只发轻量的工具存根工具名 defer_loading: true标记模型真正需要时再通过一个「工具搜索」工具去发现完整定义。这样即使你装了个新插件也不会把整个前缀打翻。技巧五让子代理共享父级缓存前缀。多代理不是简单「多发几份请求」。让子代理复用主会话已建立的稳定前缀能让「派 5 个子 agent 并行干活、账单却几乎只算一份」成为可能——这也是 Claude Code 架构里最值得学的设计之一。技巧六上下文压缩时复用同一前缀。这一条特别精妙。当历史太长需要压缩时天真做法是另起一个 prompt、把历史拍平发过去——这次调用必然全部 miss。正确做法是复刻会话原本的[系统提示词][工具定义][历史]前缀只在尾部追加一句「请把以上内容压缩成摘要」。于是这次摘要调用的前缀正是上一轮刚被缓存的那一段压缩本身也命中了缓存。四、一张风险分级清单把日常操作按「是否摧毁缓存」分级执行起来最直观级别操作影响高危中途换模型、增删工具 / 重载 MCP、改项目规则文件、装新 Skill、闲置超 TTL缓存几乎必废中危改 thinking 开关 / 推理预算、重载插件视实现而定低危正常对话只在末尾追加消息、侧线探索走 subagent、反复读同一文件基本安全文件内容也能被复用五、怎么监控盯「写读比例」别只看总量Claude 场景下最该盯的是两个字段的比例cache_creation_input_tokens写入cache_read_input_tokens读取判断逻辑很简单写入高、读取低→ 前缀不稳或复用次数不够读取高、普通输入低→ 稳定前缀真的被复用了单看总 token 极易误判输入看起来很多但如果大部分是 cache read实际非常便宜。六、别忘了接入层中转站会吃掉你的缓存红利很多人把前缀优化做得很漂亮最后却在接入层翻了车。原因在于经过中转站后缓存信息可能直接消失——不少 OpenAI 兼容接口会把 usage 统一成简单格式只留一个总 input token。而更麻烦的是三层「猫腻」吃差价上游已按缓存读取的低价结算中转站却按普通输入卖给你打散路由在多个 key、账号、区域之间轮询同一会话的请求被分散模型名一致不代表缓存位置一致改写请求插入自己的 system 提示词、修改 tool schema、重排 messages——你的前缀早被改了而你在日志里根本看不到最终请求影响有多大算笔账就清楚了。设普通输入价为 1、缓存读取为 0.1方案计算实际单位成本3 折、命中率 50%(0.5×1 0.5×0.1) × 0.30.1656 折、命中率 95%(0.05×1 0.95×0.1) × 0.60.087结论很反直觉**折扣只作用在明面单价上而命中率改变的是计费基数。**长上下文任务里命中率差一点价格排序就可能反过来。所以选接入方式时至少看三件事usage 字段是否透传最好保留供应商原始字段能看到缓存读写明细缓存输入按什么价计费同一会话是否有路由粘性这也正是向量云在解决的问题通过火山方舟官方 API 与独享推理接入点让请求路由固定、缓存空间隔离——缓存不被其他用户挤占前缀才能稳定命中独享场景下命中率可达 70%~90%而不是公共资源池里随波逐流的 20%~40%。获取 API Keyhttps://ark.tokenrize.cn/一句话总结前缀稳定性管住前半段独享接入点守住后半段命中率才是省出来的。七、写在最后四条保命口诀把全文压成四句话可以直接贴到团队规范里静态在前、动态在后——时间戳、git 状态塞进用户消息绝不写进 system 正文要换模型就用 subagent 做侧活——主线模型不变、长前缀不动临时指令写进当前对话——别去改项目规则这种长期记忆压缩也要复用前缀——别另起 prompt 把历史拍平最后回到那句话**在 Coding Agent 里缓存不是优化项而是架构地基。**你越早把它当成设计的第一性原理后面要还的技术债就越少。
阅读完成 · 觉得有帮助？
