context-kv-cache-friendly

name	context-kv-cache-friendly
description	当你在设计系统提示词、工具定义、消息历史的布局与顺序，或排查 KV Cache/Prompt Cache 命中率低、首 token 延迟高、推理成本异常时使用。核心目标：让上下文前缀字节级稳定，最大化缓存复用。不适用于状态注入（见 context-status-bar）或为上下文做减法（见 context-compression）。

KV Cache 友好设计（KV-Cache-Friendly Design）

角色与读者

面向构建生产级 Agent 的开发者。本 Skill 服务的目标：让上下文布局对 KV Cache / Prompt Cache 友好——缓存经济性不是事后优化，而是前置架构约束。核心直觉：模型每生成一个 token 都要回头看前文所有 token 的中间计算结果，缓存前文后下一轮只需算新增部分；但前提是复用的前缀保持字节级不变。

三条核心结论（必须记住，可跳过原理）

1. 系统提示词和工具定义一旦确定就不要改——任何改动（哪怕多一个空格）都可能改变 token 序列，使首个不同 token 及其后的缓存失效；改动越靠前，延迟和成本影响越大。
2. 动态信息永远追加到末尾——时间戳、用户状态等变化内容作为新消息追加，而非修改已有系统提示词。
3. 使用标准 API 格式，不要自行拼接消息——结构化消息会被 Chat Template 翻译成训练时见过的固定 token 序列；自行拼接会偏离训练格式，削弱多步思考能力。

核心原则（配正例/反例）

1. 静态前缀 + 轨迹分离

   • system 消息 + 核心工具定义 = 静态前缀（跨请求缓存）；用户消息 + 模型回复 + 工具结果 = 轨迹（随交互增长）。
   • 反例：某团队在 system prompt 加 Current time: {{now}}，导致首 token 延迟从 0.5s 涨到 3-5s、月度推理账单近乎翻倍。

2. 提示词结构由缓存边界决定（Claude Code 实践）

   • system prompt 用一个缓存边界标记分两部分：标记前可跨用户/跨会话全局缓存，标记后含用户/会话特定信息。所有动态元素放到边界之后。
   • 反例：N 个二值条件（OS 类型/模式/语言）放边界之前 → 产生 2^N 种缓存键组合（3 个条件 = 8 种）。

3. 子 Agent 与父 Agent 字节级对齐（继承上下文时）

   • 主 Agent 派生子 Agent 或旁路查询时，若子 Agent 继承父上下文，则提示词、工具定义、模型配置、消息前缀、思考配置必须逐字节匹配，才能命中 Prompt Cache。
   • 例外：使用不同上下文/提示词的子 Agent 不要求对齐。

4. 新工具 schema 追加到轨迹末尾，而非插回前缀

   • 因果注意力决定每个 token 的 KV 只依赖之前 token，末尾追加不改变任何已缓存 token 的 KV。
   • 注意："追加到末尾"只发生在工具被发现那一轮；此后 schema 固定在轨迹原位置，成为普通历史消息继续命中缓存。

5. 工具结果替换字符串在首次出现时冻结

   • 大工具输出替换为摘要预览时，替换字符串持久化保存；会话重启也用相同字符串，保证恢复后消息序列与缓存字节流一致。

执行流程（SOP 检查清单）

1. 确定静态前缀内容（system + 核心工具定义），写死、固定顺序。
2. 给 system prompt 划缓存边界：边界前放全局共享内容，边界后放用户/会话特定信息。
3. 动态信息（时间戳/状态/用户配置）一律追加到末尾。
4. 工具定义保持固定顺序（不按频率动态排序）；需新工具时追加 schema 到轨迹末尾。
5. 子 Agent 继承上下文时做字节级对齐；工具输出替换字符串冻结。
6. 验证：改前缀前后对比首 token 延迟（缓存命中 vs 失效的差异）。

禁止清单（写清合法例外）

• 禁止动态系统提示词（时间戳注入 system）。例外：时间信息作为 user 消息追加末尾，或需要时用工具获取。
• 禁止动态用户配置嵌入（余额、配额每次更新）。例外：用专门状态管理机制按需提供。
• 禁止工具定义动态排序（改变顺序使缓存从首个变动工具起失效，对选择能力几乎无影响）。例外：固定顺序。
• 禁止滑动窗口直接丢弃历史（破坏前缀一致性 + 丢失关键工具结果，Agent 反复执行相同调用）。例外：接近预算时上下文感知压缩后替换。
• 禁止文本格式化（把 role-content 转 "USER: ... ASSISTANT: ..." 纯文本）。例外：偏离训练格式会导致重复执行、忽略工具结果、该调工具时生成文本，必须用标准 API 格式。
• 禁止修改/移除/重排已加载的工具集（缓存从变动点起失效）。例外：Prompt Cache TTL 过期整段重算不算工具特有代价。

参考资料

• 本书第 2.3 节《KV Cache 友好的上下文设计》（三条结论、注意力机制、Chat Template、五种错误模式、缓存作为架构约束、可编辑可组合 KV Cache）。
• 笔记 02-上下文工程.md 第 2.3 节。
• Claude Code "How Claude Code uses prompt caching"；OpenAI "Tool search" / Anthropic "Tool Search"（工具 schema 追加到末尾的原生支持）。