提示词缓存策略
用途
本技能用于在重复的 API 请求中复用可缓存内容，以降低输入成本并改善延迟。它以提示词组织为核心：把稳定、可复用的指令、工具模式与示例放在前缀，把会变化的问题、时间戳与检索结果放在允许的后缀位置。
激活时机
适用于多个 API 请求共享已授权的指令、工具或参考材料的场景。使用前需先确认提供方端点、模型、服务层级与缓存模式，并查阅其当前文档以获取费率、最小前缀长度与保留策略。缓存不会减少上下文窗口的占用。
主要能力
- 保留稳定前缀：复用指令、工具 schema 与示例保持稳定，变化内容放到其后。需遵循提供方序列化顺序，例如 Claude 使用 tools、system、再 messages。
- 区分可缓存与不可缓存内容，并识别动态后缀是否可能被再次缓存。
- 维护用户与工作区边界：在缓存查找或复用前先做访问授权，缓存键是路由与计费提示，不是授权闸门或沙箱。
- 成本对比计算：将用量归一化为不重叠类别，用同一货币每百万 token 价格计算基线与实际成本。
- 提供离线算术示例与可执行计算函数 compareCacheCost。
提供方要求与证据
- OpenAI：需核实按模型自动/显式模式、最小长度、保留与写入/读取价格。计数器可记录 Responses 的 usage.input_tokens_details.cached_tokens，以及存在时的 cache_write_tokens；Chat Completions 使用 prompt_tokens_details.cached_tokens。
- Claude：需核实支持的平台、模型最小值、cache_control 支持与 TTL。计数器可记录 input_tokens、cache_creation_input_tokens、cache_read_input_tokens、output_tokens，并按 TTL 拆分写入。
- Gemini：需核实模型最小值与 API；Interactions 支持隐式缓存，显式缓存对象需 GenerateContent。计数器可记录 Interactions 的 usage.total_cached_tokens，GenerateContent 的 usage_metadata 缓存/输入/输出计数器及显式缓存 token 数与保留时长。 应记录端点与 SDK 版本，因为不同版本可能暴露不同字段名。
使用方式
- 从当前文档捕获可缓存前缀大小与模型/平台要求。
- 在 ECC 仓库运行离线示例与边缘用例：
node tests/skills/prompt-caching-strategy.test.js。 - 若授权访问提供方流量，则对比匹配请求并聚合实际缓存 token 计数、各类输入、输出、存储、延迟与已实现成本。
- 报告缓存读取除以总输入 token 作为 token 命中率，并单独报告请求命中率，注明分母与采样周期。
- 若未测量流量，则命中率、延迟改善与实际节省应标注为未测量。
成本对比公式
baseline = (ordinary + written + read) * ordinary_input_rate / 1e6
+ output * output_rate / 1e6
actual = ordinary * ordinary_input_rate / 1e6
+ written * cache_write_rate / 1e6
+ read * cache_read_rate / 1e6
+ output * output_rate / 1e6
+ storage_token_hours * storage_rate / 1e6
savings = baseline - actual
该反事实假设提示词与输出量固定。不存在类别设为零。不得将缓存折扣应用于总账单或输出 token。
示例（假设价格，非报价）
十次调用，每次含 10,000 token 稳定前缀、2,000 token 变化后缀与 2,000 输出 token；一次前缀写入、九次完整前缀读取。 基线为 120,000 输入 token 按 $3 计加上相同输出，合计 $0.6600；启用缓存后为 $0.4245，节省 $0.2355，写入溢价已计入，$0.3000 输出账单不变。若显式缓存保留 10,000 token 两小时、按假设 $1 每百万 token 小时计，加 $0.0200 存储，实际成本为 $0.4445。一次性调用时，前缀写入 $0.0375 而非 $0.0300 普通输入，多 $0.0075 且无读取节省。低于文档最小值的 500 token 前缀应按未缓存处理。
适用场景
- 多次 API 请求共享相同授权指令、工具或参考材料。
- 需要量化缓存对输入成本与延迟影响的场景。
限制
- 运行时缓存命中与实际节省未在本技能中测量，文中示例仅验证算术，不调用提供方。
- 缓存不减少上下文窗口占用。
- 节省取决于模型、平台、缓存资格、写入、保留、复用与输出量。
- 只应选择相关上下文，为达到资格阈值而填充提示需单独论证成本与质量。
与其他技能的关系
- prompt-optimizer 在优化复用前改善提示词质量。
- context-budget 识别不必要的上下文；缓存仍会消耗该上下文。
- cost-aware-llm-pipeline 将缓存与路由、重试及其他成本比较。