Prompt Cache Optimizer
提示缓存优化器
Overview
概述
Runtimes that cache prompts bill a stable prefix only once. If the first K tokens of every request are identical, the runtime caches them and you stop paying for them per turn. The win is largest for long-lived, reference-heavy sessions. This skill makes your context cache-friendly by construction.
会缓存提示的运行时只对稳定前缀计费一次。如果每次请求的前 K 个 token 完全相同，运行时便会缓存它们，你无需在每轮为其付费。对于长期、重度依赖参考内容的会话，收益最大。本技能从结构上让你的上下文天然具备缓存友好性。
When to use
何时使用
-
A large reference (schema, index, style guide, spec) is reused every turn.
-
每轮都会复用的大型参考内容（schema、索引、风格指南、规范）。
-
Sessions are long and context-heavy, with repeated boilerplate.
-
会话时间长、上下文繁重，且存在大量重复模板内容。
-
Cost is dominated by re-sent context, not by model generation.
-
成本主要由重复发送的上下文主导，而非模型生成。
Core rules
核心规则
-
Stable prefix first. Put large, unchanging references at the very top of the context. Keep that block byte-identical across turns.
-
稳定前缀优先。 将庞大、不变的内容参考置于上下文最顶部，并保持该块在各轮之间逐字节完全一致。
-
Volatile text last. Timestamps, random ids, turn counters, and live tool results go at the bottom. Only the changing tail breaks the cache; the long stable head stays cached.
-
易变文本放最后。 时间戳、随机 id、轮次计数器、实时工具结果放在底部。只有变化的尾部会使缓存失效，而长而稳定的头部仍保持缓存。
-
No cache-breakers in the stable block. Never inject volatile content (dates, uuid, rotating examples, re-ordered lists) into the cached region.
-
稳定块中不要放入破坏缓存的内容。 切勿将易变内容（日期、uuid、轮换示例、重排列表）注入缓存区域。
-
Keep the cached block minimal. Include only what is reused every turn. A 2000-token stable prefix cached beats a 6000-token one that's also cached — less to hold even cached.
-
保持缓存块精简。 仅包含每轮复用的内容。一个被缓存的 2000 token 稳定前缀，优于同样被缓存的 6000 token 前缀——即便已缓存，需要保留的也更少。
-
Deterministic ordering. Keep lists/tables in a fixed order; re-sorting them each turn changes the prefix and defeats caching.
-
确定性排序。 保持列表/表格顺序固定；每轮重新排序会改变前缀并破坏缓存。
Cache-breaking pitfalls (avoid)
破坏缓存的陷阱（应避免）
-
Inserting
Today: <date>or a timestamp into the stable region. -
在稳定区域插入
Today: <date>或时间戳。 -
Auto-including "recent files" that change every turn inside the prefix.
-
在前缀中自动包含每轮都变化的“最近文件”。
-
Re-ordering retrieved chunks (e.g. by relevance) before the cached block.
-
在缓存块之前对检索到的分块重新排序（例如按相关性）。
-
Interleaving conversation transcript into the reference region.
-
将对话记录交错插入参考区域。
-
Emitting a fresh UUID/run-id at the top each turn.
-
每轮在顶部生成新的 UUID/run-id。
What belongs where
内容归属
-
Cached (stable): schema, symbol index, style guide, standing project facts, fixed instructions.
-
已缓存（稳定）： schema、符号索引、风格指南、固定项目事实、固定指令。
-
Ephemeral (tail): this turn's question, tool results, intermediate analysis, live state summary, timestamps.
-
临时（尾部）： 本轮问题、工具结果、中间分析、实时状态摘要、时间戳。
Ordering helper
排序辅助工具
scripts/cache_layout.py takes a list of context blocks tagged stable/volatile and (a) orders them stable→volatile, (b) flags any volatile block placed inside the stable region, (c) prints the resulting layout. Use it to audit a context before a long session.
scripts/cache_layout.py 接收一组标记为 stable/volatile 的上下文块，并（a）将其按 stable→volatile 排序，（b）标记任何被放入稳定区域的易变块，（c）打印结果布局。可在长时间会话前用它审计上下文。
Edge cases
边界情况
-
Not all runtimes cache; verify support. Where unsupported, the stable-prefix discipline still helps (predictable, smaller diffs) but yields no billing win.
-
并非所有运行时都支持缓存，请确认支持情况。即使不支持，稳定前缀规范仍有帮助（可预测、差异更小），但不会产生计费收益。
-
Very small stable blocks (a few hundred tokens) gain little; focus on blocks >1k tokens.
-
非常小的稳定块（数百 token）收益甚微；应聚焦于 >1k token 的块。
Resources
资源
-
scripts/cache_layout.py— order/audit context blocks for cache friendliness. Execute, don't load. -
scripts/cache_layout.py—— 对上下文块进行排序/审计以提升缓存友好性。应执行而非加载。 -
references/cache_patterns.md— worked examples of cache-friendly vs cache-breaking layouts. -
references/cache_patterns.md—— 缓存友好与破坏缓存布局的实例。 references/error-handling.md—— 本技能脚本（cache_layout.py）的文件缺失 / JSON 损坏报错指引。
