# Kv Cache Design

优化 Agent 推理延迟与成本、诊断首 token 变慢或缓存命中率下降时使用, , KV Cache 前缀不变性原则、三条铁律、五种破坏缓存的错误上下文管理模式、Chat...

- Repository: https://github.com/bojieli/ai-agent-book (56844 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-10-08
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add bojieli/ai-agent-book --skill kv-cache-design -g -a claude-code -y`
Codex: `npx skills add bojieli/ai-agent-book --skill kv-cache-design -g -a codex -y`
Cursor: `npx skills add bojieli/ai-agent-book --skill kv-cache-design -g -a cursor -y`
Gemini CLI: `npx skills add bojieli/ai-agent-book --skill kv-cache-design -g -a gemini-cli -y`

## Description

优化 Agent 推理延迟与成本、诊断首 token 变慢或缓存命中率下降时使用, , KV Cache 前缀不变性原则、三条铁律、五种破坏缓存的错误上下文管理模式、Chat Template 与历史思维链回传策略、缓存作为架构约束（缓存边界、子 Agent 字节级对齐、替换字符串冻结）。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# KV Cache 友好的上下文设计

KV Cache 把前文 token 的键值对（K/V）缓存下来，下一轮只计算新增部分。**前提是要复用的 token 前缀保持不变**, , 若序列从某位置开始不同，首个不同 token 及其后的 KV 状态需重新计算，此前位置不受影响。跨请求的对应机制叫 Prompt Cache。一行看似无害的动态代码，可能让整条推理链路慢一个量级。

## 何时使用

- 诊断首 token 延迟（TTFT）升高、推理账单翻倍、`cached_tokens` 命中率低
- 设计 Agent 的上下文布局（哪些内容进 system、哪些追加到末尾）
- 决定子 Agent 派生方式、工具定义加载方式、会话恢复机制
- 处理历史思维链（`reasoning_content` / thinking block）的回传与跨模型轨迹迁移
- 评估「动态信息该怎么送进上下文」的任何技术方案

## 核心原则

- **铁律一：系统提示词和工具定义一旦确定就不要改。** 任何改动，哪怕多一个空格，都可能改变 token 序列，使首个不同 token 及其后的缓存无法复用；改动越靠前，重新计算和计费的 token 越多，延迟影响通常越大（实测可达数倍）。
- **铁律二：动态信息永远追加到末尾。** 时间戳、用户状态、TODO 进度等变化内容作为新消息追加到对话末尾，而不是修改已有的系统提示词。
- **铁律三：使用标准 API 格式，不要自行拼接消息。** 结构化消息经 Chat Template 翻译成模型训练时见过的固定 token 序列；自行拼成 `USER: ... ASSISTANT: ...` 的根本问题是偏离训练格式，会削弱多步思考能力。
- **Transformer 层是串联的**：第 k 个 token 变化，k 之前状态不受影响，从 k 开始的表示逐层受影响, , 缓存只能保留到首个不同 token 之前。
- **无缓存时 prefill 注意力计算量随上下文长度平方级增长**；有缓存时省去历史 K/V 投影重算，但每个新 token 的注意力仍要遍历全部缓存 K/V（线性增长）, , 这是长上下文解码变慢、显存带宽成为瓶颈的原因。
- **Prompt Cache 的读取成本远低于首次计算**，约为十分之一（Anthropic、DeepSeek、GPT-5 量级）；各家启用方式与计费细节差异大，使用前查最新文档。
- **缓存是架构约束，不是事后优化。** 越早纳入设计，后续工程代价越小。

## 实践模式

### 1. 上下文分层布局

```
[ system prompt ][ tool definitions ]   静态前缀，字节级稳定，跨请求/用户/会话缓存
[ user / assistant / tool ... ]         轨迹，只追加不修改
[ 状态栏 / 新工具 schema / 动态信息 ]    追加到末尾
```

- 每个运行时条件（OS 类型、当前模式、用户偏好）若放在缓存边界之前，就会把缓存键的变体数量翻倍；N 个二值条件产生 2^N 种组合（3 个条件 = 2x2x2 = 8 种缓存键）。**所有动态元素放到边界之后。**
- 提示词的排列顺序首先由缓存的经济性决定，其次才是语义逻辑。
- 按需加载的工具 schema 追加到末尾是安全的：因果注意力决定每个 token 的 KV 只依赖它之前的 token，末尾追加不改变任何已缓存 token 的 K/V；新增 schema 首次出现时计算一次（一次性写入），此后并入持续增长的前缀，后续所有轮次持续命中。

### 2. 三种缓存一致性设计

- **子 Agent 字节级对齐**：主 Agent 派生子 Agent 或旁路查询时，子 Agent 的提示词、工具定义、模型配置、消息前缀和思考配置必须与父 Agent 逐字节匹配，才能命中服务商 Prompt Cache。若框架故意使用不同上下文/提示词，则不要求对齐。
- **替换字符串首次出现即冻结**：大型工具输出被替换为摘要预览时，替换后的字符串持久化保存；即使会话重启，也使用完全相同的替换字符串，保证恢复后的消息序列与缓存字节流一致。
- **思考配置与前缀一起冻结**：CoT 是否回传、回传哪些字段，属于前缀的一部分，改动同样使缓存失效。

### 3. Chat Template 与历史思维链

The rest: https://github.com/bojieli/ai-agent-book/blob/HEAD/skills/kv-cache-design/SKILL.md