Prompt Cache 为什么没省钱？用 prompt-cache-skills 排查 AI 编程缓存

你的 Claude Code 或 Cline 每月账单可能比实际应费高出 30-50%。不是因为用量大，而是 Prompt Cache 没生效。

很多 AI 编程 Agent 默认会开启 prompt caching，但配置里一个小改动就能让整个缓存前缀失效：系统提示塞了时间戳、cache key 计算错误、缓存开关没打开，或者 TTL 设得太短。这些变化不会报错，账单也不会提示，你只会看到每月的 API 成本居高不下。

prompt-cache-skills 是一个 drop-in 技能库，专门修复这些”悄悄失效”的缓存配置。合适场景下，缓存命中率可以从接近零提高到 80% 甚至更高。下面会解释缓存计费原理、列举四大失效原因、展示技能库的典型修复案例，并提供验证方法。

Prompt Cache 怎么帮你省钱

Prompt Cache 的省钱逻辑很简单：稳定的前缀内容可以被缓存，重复使用时计费远低于普通输入 token。

各家 API 的计费字段名不同，但原理一致：

计费类型	计费特点	适用场景	代表厂商
cache_creation_input_tokens	首次创建缓存，费用通常高于普通 token	长前缀首次请求	Anthropic
cache_read_input_tokens	缓存命中，费用远低于普通 token（约 10%）	稳定前缀多次复用	Anthropic
普通输入 token	按正常费率计费	短请求或前缀频繁变化	所有厂商
cached_tokens（OpenAI）	缓存命中，费用降低约 50%	稳定前缀复用	OpenAI
cached content（Gemini）	按缓存时长计费	长上下文场景	Google Gemini

以 Anthropic 为例，如果你的系统提示有 2000 token，每天通过同一个 Agent 复用 100 次，缓存命中时这 2000 token 会走 cache_read 计费，约为普通输入 token 的 10%。单这一项就能节省约 90% 的输入成本。

缓存真正有效的前提是：前缀内容稳定且会被多次复用。如果你的系统提示每次请求都变（比如包含时间戳或随机 ID），缓存前缀每次都会重新计算，cache_creation 的成本反而可能比普通请求更高。

为什么你的 Agent 缓存总是失效

这些失效原因不会报错，你只会看到账单数字，却找不到具体的浪费点：

1. 易变消息破坏前缀。系统提示前缀里塞了时间戳、随机 ID 或其他每次请求都会变的内容，导致整个缓存前缀作废。这是最常见的失效原因。

2. Cache key 错误或缺失。某些 Agent 工具没有正确设置缓存标记，或者使用自定义 cache key 但计算逻辑有误。缓存前缀虽然内容稳定，但 API 无法识别为可缓存内容。

3. 默认没开缓存。部分 Agent 工具默认关闭 prompt caching，需要手动在配置文件里开启。你以为 Agent 会自动处理，结果一直走普通 token 计费。

4. TTL 太短。缓存有效期设置过短（比如 1 小时），而你的实际请求间隔超过了 TTL，每次请求时缓存都已过期。

具体症状因 Agent 而异，prompt-cache-skills 仓库的 README 里有按工具分类的症状描述。如果你怀疑某个失效原因，可以先对照仓库里的 SKILL.md 看是否匹配你的工具。

prompt-cache-skills 是什么

prompt-cache-skills 是一组 drop-in 技能，任何 AI 编程 Agent 都能自己读取并应用：

维度	说明
定位	一组 drop-in 技能，AI 编程 Agent 可自行读取并应用的修复补丁
目标	在合适场景下将缓存命中率从坏的或部分的提高到 80-99%
适用 Agent	Claude Code、Codex、Cline、Cursor、Devin、Gemini CLI、OpenCode、Aider、Continue、Roo Code 等
仓库地址	https://github.com/OnlyTerp/prompt-cache-skills
使用方式	指向仓库 → Agent 自动应用 → 验证命中；或手动按 skills/ 目录 patch
省时优势	省去自己研究各家 API 缓存细节的时间

项目当前约 99 stars，skills 列表和命名可能会调整，具体以仓库 README 为准。

与手动排查相比，这套技能库的优势在于：你不需要自己去翻各家 API 的 prompt caching 文档、对比不同 Agent 的配置差异、猜测哪个字段破坏了缓存前缀。仓库里的每个 skill 都已经识别了具体的失效原因，提供了对应的修复 diff 和验证方法。

怎么用 prompt-cache-skills 修复你的 Agent

有两种方式：让 Agent 自动修复，或者手动按 skills/ 目录修改。

方式一：让 Agent 自动修复（推荐）

第一步，指向仓库。复制这句话发给你的 AI 编程 Agent：

读 https://github.com/OnlyTerp/prompt-cache-skills，把 skills/ 里匹配我当前使用的 harness 的每个技能都应用：确认目标 → 落 diff → 按 SKILL.md 验证

第二步，Agent 会识别你当前使用的工具（比如 Cline、Continue、Aider 等），然后列出匹配的技能清单。你会看到每个技能针对的失效原因。

第三步，审查 diff。每个技能目录下有 SKILL.md 文件，说明修改目标和具体改动。仔细阅读后确认这些修改是否安全。

第四步，应用修改。确认后让 Agent 落 diff，修改你本机或项目的配置文件。建议修改前先备份原配置。

第五步，验证命中。使用 tools/check_cache.py 工具验证缓存是否生效。具体方法见下文”怎么验证缓存真的命中了”。

方式二：手动修复

如果你不想让 Agent 自动修改配置，可以手动应用。

第一步，访问仓库：https://github.com/OnlyTerp/prompt-cache-skills

第二步，浏览 skills/ 目录，找到你使用的工具对应的技能。比如 cline-fix-volatile-msg 或 continue-enable-defaults。

第三步，阅读 SKILL.md。每个技能目录下都有说明：目标、症状、修复点、验证方法。

第四步，按说明手动修改你的配置文件。

第五步，使用 tools/check_cache.py 验证缓存命中。

安全提示

让 Agent 自动落 diff 意味着直接改你本机或项目的配置。建议先看 SKILL.md，理解每个修改点。确认后再让 Agent 自动改。修改前先备份原配置文件。

技能库详解（典型修复案例）

仓库里的每个技能都是一个完整的修复：有明确的目标 Agent、症状描述、修复 diff 和验证方法。以下是部分典型案例：

技能名	目标 Agent	症状	修复点
cline-fix-volatile-msg	Cline	系统提示前缀包含时间戳，每次请求前缀都变	移除或固定易变消息
cline-openai-cache-key	Cline + OpenAI	OpenAI 缓存 key 计算错误	修正 cache key 生成逻辑
cline-pin-timestamp	Cline	时间戳导致缓存失效	固定时间戳或移除
continue-fix-volatile-msg	Continue	系统提示包含易变字段	清理易变消息
continue-enable-defaults	Continue	默认未开启 prompt caching	启用缓存配置
continue-gemini-explicit	Continue + Gemini	Gemini 缓存配置缺失	显式设置缓存参数
aider-1h-ttl	Aider	缓存 TTL 仅 1 小时，频繁过期	延长 TTL 或调整请求频率
aider-cache-default-on	Aider	默认关闭缓存	启用默认缓存开关
opencode-detect-openai-compat	OpenCode	OpenAI 兼容模式缓存失效	检测并正确处理 OpenAI 兼容 API
opencode-bedrock-doc-blocks	OpenCode + Bedrock	Bedrock 文档块缓存问题	修正文档块缓存策略

技能列表持续增加，命名可能调整，以仓库 README 和 skills/ 目录为准。如果你使用的 Agent 不在当前列表里，可以参考现有技能的 SKILL.md 和 patch 文件，手动排查类似的缓存问题。

怎么验证缓存真的命中了

prompt-cache-skills 提供了一个验证工具：tools/check_cache.py。它会对比冷/热两次请求，计算缓存命中率。

使用步骤

第一步，获取 check_cache.py。从仓库下载：
https://github.com/OnlyTerp/prompt-cache-skills/blob/main/tools/check_cache.py

第二步，配置 API 凭证。设置环境变量：

• Anthropic: ANTHROPIC_API_KEY
• OpenAI: OPENAI_API_KEY
• Google Gemini: GOOGLE_API_KEY

第三步，运行冷请求（首次请求）。执行：

python check_cache.py --provider anthropic --prompt "你的系统提示" --message "你的用户消息"

观察 cache_creation_input_tokens 字段：

• 如果有值，说明创建了缓存
• 记录 input_tokens 数量

第四步，等待 1 秒后运行热请求（重复请求）。再次执行相同命令，使用完全相同的 prompt 和 message。

观察以下字段：

• cache_read_input_tokens：如果有值且大于 0，说明缓存命中
• cache_creation_input_tokens：应该为 0 或不存在
• input_tokens：应该明显减少（被缓存的部分不再计费）

第五步，计算命中率：

命中率 = cache_read_input_tokens / (cache_read_input_tokens + input_tokens)

示例：

• 首次请求：input_tokens=2000，cache_creation_input_tokens=1800
• 第二次请求：cache_read_input_tokens=1800，input_tokens=200
• 命中率 = 1800 / (1800 + 200) = 90%

第六步，判断是否生效：

• 缓存生效：热请求 cache_read_input_tokens > 0
• 缓存未生效：热请求 cache_read_input_tokens = 0 或不存在

指标说明

• cache_creation_input_tokens：Anthropic 字段，首次创建缓存的 token 数
• cache_read_input_tokens：Anthropic 字段，缓存命中读取的 token 数
• cached_tokens：OpenAI 字段，缓存命中的 token 数
• input_tokens：普通输入 token（未缓存部分）

热请求 cache_read_input_tokens = 0 就说明缓存没生效。你需要回到上文的四大失效原因，检查配置是否有易变消息、cache key 错误、默认未开启或 TTL 太短的问题。

什么时候推荐/不推荐用这套技能

这套技能库能修复已知的缓存失效问题，但并不是所有场景都适用：

场景	推荐/不推荐	原因
长系统提示 + 多次相似请求	推荐	稳定前缀可复用，缓存收益大
Agent 编程工具（Claude Code、Cline 等）	推荐	项目专为这些工具设计
月账单 > $50	推荐	可节省金额大，值得投入
已有 prompt caching 配置但不确信是否生效	推荐	验证工具帮你确认
短提示 + 单次请求	不推荐	缓存开销可能大于收益
系统提示频繁变化（如包含实时数据）	不推荐	前缀不稳定，缓存无法复用
请求间隔超过 TTL（如每天只调几次）	需评估	缓存可能过期，收益有限
使用不在支持列表的 Agent	需评估	需手动适配或等待社区贡献技能

如果你的月账单已经超过 50 美元，且使用的是支持列表里的 Agent，投入这套技能库的回报会比较明显。如果你的请求频率较低或前缀频繁变化，缓存收益可能有限，需要先评估是否值得改动配置。

风险与注意事项

在使用这套技能库之前，你需要了解以下风险：

1. 项目较新。当前约 99 stars，skills 列表和命名可能会调整，具体以仓库 README 为准。技能库会持续更新，命名和结构可能变化。

2. 自动修改配置需谨慎。让 Agent 自动落 diff 意味着直接改你本机或项目的配置文件。建议先看 SKILL.md 理解每个修改点，再决定是否让 Agent 自动改。

3. 各家计费字段不同。Anthropic 使用 cache_creation/cache_read，OpenAI 使用 cached_tokens，Gemini 使用 cached content。具体字段名以各家官方文档为准。

4. 缓存不是万能。一次性短调用、前缀频繁变化的场景，缓存基本没用甚至更贵。不要在所有场景都强求缓存。

5. 验证工具局限。check_cache.py 目前主要针对 Anthropic API 设计。OpenAI 和 Gemini 的缓存验证需查阅各自官方文档。

6. 命中率非保证。“80-99% 命中率”只是项目自述目标。实际命中率取决于前缀长度、请求频率、TTL 设置等多种因素。

下一步与延伸阅读

如果你想进一步降低 AI 编程成本，可以阅读：

• AI 服务商切换太麻烦？一个 AI Gateway 搞定监控、缓存和故障转移 — 了解如何用 AI Gateway 统一管理多个服务商，实现自动故障转移和全局监控，进一步降低成本

• Prompt 工程实战：让 AI 输出质量提高 10 倍的技巧 — 掌握 Prompt 改进技巧，从源头减少不必要的 token 消耗

• Computer-Use Agent：让 AI 操作你的电脑 — 了解 AI Agent 的计算机操作能力，改进工作流程

官方资源：

• prompt-cache-skills GitHub 仓库
• Anthropic Prompt Caching 文档
• OpenAI Prompt Caching 文档
• Google Gemini Context Caching 文档