# 第 14 章：缓存与成本工程

> 本章目标：把"便宜"从玄学变成工程——对话缓存机制、命中率实测与优化、成本模型、推理档位联动、真实任务预算，以及怎么"看见"每笔 token 花在哪。

## TL;DR（本章核心，30 秒版）

1. **缓存是成本第一变量**：DeepSeek context cache 对重复输入按 **98% 折扣（Flash）/ 99%+ 折扣（Pro）** 计费——Agent 工作负载输入占比高，命中率直接决定成本量级
2. **手册实测命中率 97%**：会话延续 + 稳定工具 schema + Agent 多步工作负载特性（第 5 章 5.1.1）；社区长跑实测可达 99.7%（[#560](https://github.com/deepseek-ai/deepseek-harness/discussions/560)）
3. **命中率三原则**：会话延续（别频繁新建）、前缀稳定（别老改配置）、少打断（一次写清验收标准）
4. **两个独立杠杆**：推理档位管"思考 token 量"，缓存管"输入单价"，可叠加——`low` 档 + 高命中 = 最便宜组合
5. **成本要看得见**：会话统计行看缓存命中 %；每轮 token 显示官方待实现（[#735](https://github.com/deepseek-ai/deepseek-harness/discussions/735)），先用统计行 + 社区 cost-tracker 插件

<details><summary>本章导航</summary>
- [14.1 对话缓存机制原理](#141-对话缓存机制原理)
- [14.2 命中率实测：97% 怎么来的](#142-命中率实测-97-怎么来的)
- [14.3 命中率优化实践](#143-命中率优化实践)
- [14.4 成本模型：命中率如何决定账单](#144-成本模型-命中率如何决定账单)
- [14.5 推理档位联动：low/high/max 成本矩阵](#145-推理档位联动-lowhighmax-成本矩阵)
- [14.6 预算实战：案例 A 成本估算](#146-预算实战案例-a-成本估算)
- [14.7 测量方法：让 token 消耗可见](#147-测量方法让-token-消耗可见)
- [14.8 成本相关踩坑清单](#148-成本相关踩坑清单)
- [14.9 决策建议速查](#149-决策建议速查)
</details>

## 14.1 对话缓存机制原理

DeepSeek API 的 **context cache**（提示词缓存）：重复/相似的输入 token 按**缓存价**计费，而不是全价。dsh 每次模型请求的输入 = 系统提示 + 技能目录 + 对话历史 + 工具 schema（第 8 章 8.3），**其中不变的前缀部分就是缓存的天然候选**——这决定了 Agent 工作负载的缓存潜力远高于普通聊天。

**计费规则**（第 5 章 5.1.1 定价表）：

| 计费项 | 未命中价 | 缓存命中价 | 折扣 |
|---|---|---|---|
| 输入（Flash） | $0.14/M | $0.0028/M | **98%** |
| 输入（Pro） | $0.435/M | $0.003625/M | **99%+** |

**每次请求的输入结构**（第 8 章 8.3），决定了哪些 token 能命中：

```text
系统提示（稳定） + 技能目录（稳定） + 对话历史（增量） + 工具 schema（稳定） + 本轮消息（增量）
      └────────────── 缓存命中区（重复） ──────────────┘   └── 未命中区（新增量） ──┘
```

**命中区越大、增量越小 → 命中率越高**。理解这个结构，14.3 的三个优化杠杆本质上都是"让命中区变大"。

**缓存不只省钱，还提速**：冷启动首轮含上下文注入约 110s，热缓存约 1s（第 1 章实测）——命中时首 token 时间量级性缩短。

> **严格前缀缓存规则（社区分析，#1052 weijiafu14，官方文档 [kv_cache](https://api-docs.deepseek.com/guides/kv_cache/)）**：DeepSeek 是**严格的前缀缓存**——前缀单元在**用户输入结束、模型输出结束等位置持久化**；下一次请求只能命中"已经完整匹配"的前缀。关键推论：
> - **工具结果天然 miss 一次**：工具结果是在"上一轮模型输出"之后才追加的，它**第一次进入下一次请求时必然是新后缀、必 miss 一次**——不论传原文还是压缩预览（这与截断方式无关）。
> - **"截断会避开缓存"是误读**：只要截断是确定性的（同输入同输出），后续回放的是同一份字节，已有前缀照常命中；只有首次出现的压缩结果、以及之后主动读取 artifact 新增的内容各自 miss 一次。**压缩工具不会绕开 DeepSeek 缓存，反而把"必然首次 miss"的工具结果缩小**（#1052 weijiafu14 实测：原生工具输出 42,299 字符 → 压缩持久化 7,885 字符，后续 derive/replay 哈希一致）。
> - **代价提醒（#1052 fnsii + weijiafu14）**：缓存本身是 best-effort、官方不承诺 100% 命中（weijiafu14 转述官方说明）；若完全不保留上下文前缀（如每轮重写/清空历史、换新会话丢全部前缀），则完全无法命中缓存，等于按新输入全价计算（fnsii）。**快封顶时优先做 summary 压缩再续**（保留前缀摘要），而不是直接开新会话丢全部前缀（fnsii 建议）。

## 14.2 命中率实测：97% 怎么来的

手册在**真实 dsh 会话统计**中实测缓存命中率**可达 97%**（第 5 章 5.1.1）。为什么 dsh 的命中率特别高：

| 原因 | 说明 |
|---|---|
| 会话延续 | 同会话多轮对话，系统提示/技能目录/历史重复 → 命中 |
| 稳定的工具 schema | 每步请求携带相同的工具定义 → 命中 |
| Agent 工作负载特性 | 多步工具链反复携带相同上下文 → 命中率天然高 |

**边界（诚实版）**：97% 依赖"对话模式重复"——**全新任务/冷启动场景会明显下降**（第 12 章 12.5）。社区长跑实测可达 **99.7%**（[#560](https://github.com/deepseek-ai/deepseek-harness/discussions/560)），印证"越长的会话命中率越高"。

**实测方法**：Web UI 底部会话统计行看"缓存命中 %"（第 6 章 6.6）；对比基准是 5.1.1 的"50 步工具链任务、2.4M 输入 token"——它是输入量级的典型样本。

> **口径注意（#1234 社区补充）**：Harness 界面显示的「缓存命中 %」是**对话内**口径——只统计当前会话这一路请求。若同一时间段开过多个对话，其他对话命中率较低时，会把**多对话整体/后台口径**拉低（社区实测对照：后台/整体约 94.5% vs 界面（对话内）98%，[#1234](https://github.com/deepseek-ai/deepseek-harness/discussions/1234)）。**测量命中率时先明确口径**：对话内（界面统计行）还是多对话整体（后台/API 侧）；对比命中率只在同口径下才有意义。

| 指标 | 看哪里 | 命中时的表现 |
|---|---|---|
| 缓存命中 % | 会话统计行（Web UI 底部） | 稳定在高位（长会话 97%+） |
| 首 token | 每轮结束行 | 从 10s+ 量级性降到 1s 以下（第 6 章 FAQ Q4） |
| 总 token | 会话总览 | 增量小 = 命中区在变大（14.1 结构） |

## 14.3 命中率优化实践

三个杠杆，按性价比排序：

| 杠杆 | 做法 | 原理 |
|---|---|---|
| **会话延续** | 长任务保持会话延续，避免频繁新建会话；批量任务放同一会话/同前缀 | 历史消息重复 → 命中 |
| **稳定提示词** | 系统提示/技能目录等前缀保持稳定，不频繁改配置；工具 schema 不变 | 前缀一致 → 命中 |
| **少打断** | 一次把验收标准写清楚（第 5 章 5.7 / 第 10 章案例启示），减少"重开会话重讲上下文" | 避免前缀重建 → 全价重来 |

**落地检查**：命中率低于预期时，第一反应查"前缀是否变了"——改过配置、换过档位、动过技能目录，都会让缓存失效（第 6 章 6.6 监控行）。

## 14.4 成本模型：命中率如何决定账单

**成本模型速记**（第 6 章 6.6）：`总成本 ≈ 输出token×输出价 + 输入未命中×未命中价 + 输入命中×命中价`——Agent 工作负载输入占比高，**缓存命中率是成本的第一变量**。

用第 5 章 Flash 输入价算一笔账（**10k 输入 token**，命中率对比）。算术示例（90% 命中）：`9,000 × $0.0028/M + 1,000 × $0.14/M ≈ $0.000165`——先把命中/未命中拆开，再分别乘各自单价：

| 命中率 | 命中 token | 未命中 token | 输入成本（Flash） | 相对成本 |
|---|---|---|---|---|
| **90%** | 9,000 | 1,000 | ≈ $0.000165 | 1× |
| 50% | 5,000 | 5,000 | ≈ $0.000714 | ≈ 4.3× |
| **10%** | 1,000 | 9,000 | ≈ $0.001263 | ≈ 7.6× |

放大到 1M 输入 token：90% 命中 ≈ **$0.0165**，10% 命中 ≈ **$0.126**，全价 $0.14——**差近一个数量级**。

再放大到手册实测量级（5.1.1：50 步工具链、2.4M 输入 token）：97% 命中 ≈ **$0.017**，全价 ≈ **$0.34**，约 **20×**。这就是 5.1.1"成本远低于按未命中价计算的预期"的数字来源。

> 注：本表只算输入侧——第 5 章定价表只收录输入价，输出侧请按官方定价页补充。输入占比高的 Agent 场景下，输入侧就是主变量。

## 14.5 推理档位联动：low/high/max 成本矩阵

推理档位管"思考量"，与缓存是**两个正交杠杆**：档位影响 token 总量，缓存影响输入单价，两者相乘。思考 token 减少 → 总 token 下降（第 6 章 6.6），且随上下文重复的部分同样吃缓存折扣（推断，待实测）。

| 档位 | 思考 token 量 | 相对成本 | 适用场景（第 6 章 6.2） | 成本策略 |
|---|---|---|---|---|
| `low` | 最少 | 最低 | 简单/确定性轮次：文件操作、批量、工具链中的廉价步 | 批量任务的默认档 |
| `high` | 中等 | 中等 | 日常 Agent 任务（默认） | 质量与成本的默认平衡 |
| `max` | 最多 | 最高 | 复杂推理、长链规划、debug | 单次复杂任务可用，别开进批量循环 |

**联动要点**：
- **长工具链任务（20-50 步）收益最大**：每步思考降档的累计效果显著（第 6 章 FAQ Q2）——档位 × 命中率两个杠杆同时作用于每一步
- 简单轮次用 `low` 档质量几乎无差别；复杂推理用 `low` 可能漏关键步骤（第 6 章 FAQ Q3）
- **叠加示例**（2.4M 输入量级任务，Flash 价）：`low` + 97% 命中 ≈ $0.017 以下（思考量更低，实际更少，推断，待实测）；`max` + 反复冷启动 ≈ $0.34 以上——**同一任务，两个杠杆全开与全关差 20×+**
- 注：`low/high/max` 为本手册实测网关（pi-ai/opencode-go）档位；默认 deepseek-official 适配器为 `off/high/max`（第 6 章 6.2 注释）

## 14.6 预算实战：案例 A 成本估算

以第 10 章**案例 A（数据质量分析，186 秒）**为样本做预算：工具链 `read → write(clean.py) → bash → write(visualize.py) → bash → read → 总结`，约 6-8 步。按 5.1.1 量级折算（50 步 ≈ 2.4M 输入 token），案例 A 输入量级约 **50 万 token（推断，待实测）**：

| 场景 | 命中率 | 输入成本（Flash，估算） |
|---|---|---|
| 会话延续 + 前缀稳定（推荐做法） | 97% | ≈ **$0.0035** |
| 中途新开会话/前缀变动 | 10% | ≈ $0.063 |
| 极端：每次全价 | 0% | $0.07 |

**步骤级拆解**（为什么会话延续省钱）——只有首轮是冷启动全价，后续每轮只有"本轮消息 + 工具结果"这一小段新增量未命中（推断，待实测）：

| 步骤 | 内容 | 输入 token（推断，待实测） | 命中状态 |
|---|---|---|---|
| 1 | read(sales_data.json) | ~5 万 | 冷启动（未命中） |
| 2-6 | write/bash/write/bash/read/总结 | ~45 万 | 前缀命中区，增量极小 |

**结论**：一次 3 分钟的真实任务，输入侧成本不到 **1 美分**；同样的活，做法不同（会话延续 vs 反复冷启动）成本差 **约 18×**。输出侧（两个脚本 + 总结）量级远小于输入，总成本仍为美分级（推断，待实测）。这就是"dsh 配 V4-Flash 成本约为 Claude 的 1/10~1/30"（第 1 章实测）在单任务维度的来源。

## 14.7 测量方法：让 token 消耗可见

**现状（有的）**：
- Web UI 底部会话统计行：`N 轮 · M 步 | LLM Xs · 工具调用 Ys | 首 token 平均 ...`（第 6 章 6.3）
- 每轮结束行：`10:14 · 用时 9分34秒 · 首 token 1.7秒 · 79 tok/s`（[#735](https://github.com/deepseek-ai/deepseek-harness/discussions/735) 原帖截图）
- 会话总览有总 token 统计；统计行可见"缓存命中 %"（第 6 章 6.6）——**对话内口径**，多对话整体命中率会被其他低命中对话拉低（[#1234](https://github.com/deepseek-ai/deepseek-harness/discussions/1234) 社区补充，见 14.2 口径注意）

**缺口（没有的）**：**每轮 token 数**。官方讨论区 [#735](https://github.com/deepseek-ai/deepseek-harness/discussions/735)（2026-08-14 提出，标题「【友好显示】希望在每轮对话中加入本轮对话token消耗量」）正是这个需求——已在帖子中确认存在，官方尚未实现。

**另一个缺口（#735 评论区 Jianye）**：希望在每轮显示中带 **provider 与 model id 标识**（原帖截图里 `xtoken：gpt-5.6-sol` 这类"provider + modelid"信息用户希望界面直接给出）——同一需求帖下的补充诉求。

**社区建议（已同步到 #735 评论区）**：每轮显示应拆成**两个数**——① 本轮总 token（粗看消耗）；② 本轮缓存命中/未命中 token（看成本优化空间）。只看总 token 会误判：同样 10k token，命中率 90% 和 10% 成本差 7.6×（见 14.4）。

**过渡期工具**：社区 `dsh-plugin-cost-tracker`（第 9 章 9.5/9.6，实时 token 成本追踪，插件/MCP 形态）——实现层面走第 4 章的插件扩展点，在请求/会话事件上统计 usage（推断，待实测）；或按会话日志/API usage 字段手工核算。第 11 章预测"缓存命中率工具化"是中期主线（11.2）——#735 落地后成本透明化闭环。

**更完整的社区实测工具：dsh-usage**（作者 kestiany，[#1169](https://github.com/deepseek-ai/deepseek-harness/discussions/1169) 收录授权）。npm 已发布 `0.1.0`（`dsh plugin --profile web add dsh-usage` 即可安装），基于 Harness 持久化会话日志计算、无需独立统计数据库。核心能力：
- **每轮对话结束位置固定展示**：`Total · Input · Cache · Output · Cost`——正好补齐 #735 缺的"每轮 token 数"，且区分输入/缓存命中/输出
- **Settings → Usage 完整用量页**：总 token、输入、缓存命中、输出、调用次数及**预估费用**（需为 Provider/模型配置价格；缺 usage/价格时费用显示 `--`，对话底部省略 Cost，避免把不完整费用当总费用）
- **52 周用量热力图**（GitHub Contributions 风格）+ 按模型/会话/单轮查看
- 支持 DeepSeek Harness 中的其他模型和 Provider；`Cost` 为估算值，不代表供应商最终账单

**记忆/压缩生态工具**（#1052 长会话降本专题评论区，2026-08-14）——针对"长会话 token 暴涨"（原帖实测 70M→100M），社区给出两个互补方案：

| 工具 | 作者 | 定位 | 机制 |
|---|---|---|---|
| **dsh-sgme**（[freehul/sgme](https://github.com/freehul/sgme)，npm 包 `dsh-sgme`） | freehul | 记忆引擎（治本） | 「对话历史」与「长期记忆」分层：每轮零成本落盘（L0，不走 LLM）→ 会话结束提炼去重合并（L1/L1.5/L2，提炼前先**剪枝**剔除无用工具调用/中间产物，实测省 **65%～96%** 会话内容）→ 新会话按场景只注入相关记忆块（纯结构化查询，不烧 token）→ 需要细节时 `memory_search` 按需检索 |
| **pi-quiet-tools**（经 [pi2dsh](https://github.com/weijiafu14/pi2dsh) 挂载） | weijiafu14 提供（freehul 亦推荐） | 工具输出压缩（治标） | 在**进入模型上下文前**压缩大工具结果：默认超过 12,000 字符或 240 行时只把确定性的头尾预览交给模型，完整结果存本地 artifact、需要时模型再读；阈值可用 `QUIET_TOOLS_MAX_CHARS` / `QUIET_TOOLS_MAX_LINES` 调整。对 MCP/Playwright 大返回体有效（作者实测 40,799 字符闭环压缩）。与缓存兼容：见 14.1 严格前缀缓存规则——不绕开缓存，反而缩小"必然首次 miss"的工具结果 |

安装示例（pi-quiet-tools，摘自 #1052 作者实测）：

```sh
npm i -g pi2dsh
pi2dsh host --packages pi-quiet-tools@0.2.0 --out ./dsh-pi-quiet
dsh plugin --profile web add file:$PWD/dsh-pi-quiet
```

> 两者不冲突：pi-quiet-tools 解决"大工具结果反复进上下文"，dsh-sgme 解决"长会话越用越贵/延续性"——前者立即生效，后者适合需要跨会话迁移记忆的场景（#1052 评论区共识：把"对话历史"和"长期记忆"分开，历史该滚就滚、记忆按需注入）。

## 14.8 成本相关踩坑清单

| # | 坑 | 现象 | 解法 |
|---|---|---|---|
| 1 | 缓存命中误判成"模型变快" | A/B 对比被 1s vs 110s 误导（第 6 章坑 #6） | 对比测试用**全新 prompt** |
| 2 | 频繁新建会话烧钱 | 每个任务都冷启动，输入全价 | 长任务/批量保持会话延续 |
| 3 | 改配置悄悄杀掉命中率 | 命中 % 突然下降，成本上涨 | 监控统计行命中 %，前缀稳定 |
| 4 | 只看总 token 误判成本 | 10k token 90% vs 10% 差 7.6× | 拆命中/未命中看（#735 建议） |
| 5 | 预算漏了输出侧 | 只按输入价算，账不对 | 按官方定价页补输出价（第 5 章只收录输入价） |
| 6 | 档位乱开 | 批量任务开 `max`，成本翻倍 | 批量用 `low`，复杂任务才 `max` |

## 14.9 决策建议速查

| 场景 | 建议 |
|---|---|
| 长工具链任务（20-50 步） | `high` + 会话延续 + 前缀稳定；2.4M 输入量级 ≈ $0.017（97% 命中） |
| 批量/简单轮次 | `low` + 同会话批量（命中红利最大） |
| 复杂推理/debug | `max`（成本换质量），单次任务可接受冷启动 |
| 成本敏感批处理 | `low` + headless + 单会话串行 |
| 性能/成本对比测试 | 全新 prompt + 固定档位 + 多次取中位数（第 6 章 6.4/6.6） |
| 命中率异常下降 | 先查前缀是否变动（配置/技能目录/模型档位） |

---

## 动手练习（检验你是否真懂了）

1. **理解题**：为什么说"缓存命中率是成本的第一变量"？用 14.4 的 10k token 表格解释 90% 与 10% 命中差多少倍
   > 自查：参考 14.4 对比表（7.6×）与 6.6 成本模型速记
2. **动手题**：跑一个 3 步任务，观察 Web UI 底部的会话统计行和每轮结束行（时间/首 token/tok/s），判断这次任务大概命中了多少缓存
   > 自查：参考 14.7 测量方法与 6.3 统计行格式
3. **动手题**：把同一批任务分别用"每项新开会话"和"同会话连续跑"两种方式执行，对比耗时差异——新开会话大概率首轮明显变慢（冷启动）
   > 自查：参考 14.1 冷启动 110s vs 热缓存 1s 的实测
4. **思考题**：为什么"只看本轮总 token"会误判成本？#735 评论区建议把每轮显示拆成哪两个数？
   > 自查：参考 14.7 节"社区建议"段落
5. **动手题**：按 #735 的建议口径，把一个会话的总 token 手动拆成"命中/未命中"两部分，用 14.4 的单价分别核算，验证"差一个数量级"的说法
   > 自查：参考 14.4 对比表与 14.2 测量方法表

## 常见疑问 FAQ

**Q1：缓存命中率最高能到多少？**
手册实测 97%（第 5 章 5.1.1）；社区长跑实测可达 99.7%（[#560](https://github.com/deepseek-ai/deepseek-harness/discussions/560)）。但**全新任务/冷启动会明显下降**（第 12 章 12.5）——命中率是"做法"的函数，不是模型的常数。

**Q2：`low` 档会明显降低质量吗？**
简单确定性任务（文件操作、批量处理）几乎无差别；复杂推理、长链规划、debug 用 `low` 可能漏掉关键步骤（第 6 章 FAQ Q3）。建议日常 `high`，批量/简单任务切 `low`。

**Q3：官方什么时候提供每轮 token 显示？**
[#735](https://github.com/deepseek-ai/deepseek-harness/discussions/735) 是 2026-08-14 提出的需求帖（每轮 token + provider/model 标识，见 14.7），**尚未实现**。过渡期用：会话统计行命中 % + 社区 `dsh-plugin-cost-tracker`（第 9 章）或 `dsh-usage`（14.7）。

**Q4：第三方网关/自建 provider 也吃缓存折扣吗？**
缓存折扣是 DeepSeek API 侧能力（第 5 章定价表）；第三方网关的缓存支持与计费需查对应定价页（推断，待实测）。

**Q5：为什么缓存命中后任务会明显变快？**
命中的前缀部分无需重新计算，首 token 时间量级性缩短（冷启动 ~110s vs 热缓存 ~1s，第 1 章实测）。判断方法：首 token 突然从 10s+ 降到 1s 以下，大概率命中（第 6 章 FAQ Q4）。做性能对比时用全新 prompt，避免缓存干扰（第 6 章坑 #6）。

---

*本章信息截至 2026-08-14（dsh 0.1.0-rc.6）。定价与缓存策略以官方文档为准；标注"（推断，待实测）"处为推算或预估，欢迎实测后 PR 修正。*