DeepSeek Harness 如何做到 99% 缓存命中率（原理详解）
DeepSeek Harness 缓存命中率详解：DeepSeek API 的上下文缓存（前缀 KV cache）叠加 dsh 只追加式的会话架构，让实际命中率冲到 97%-99%。
DeepSeek Harness（dsh）便宜不是靠什么定价戏法，而是两件事叠在一起：DeepSeek API 本身的上下文缓存（一种前缀匹配的 KV cache，命中部分按远低于正常输入的价格计费），加上 dsh 的会话架构恰好是几乎最适合喂给这套缓存的形状。单独任何一个都解释不了 Reddit 上不断被贴出来的那些数字；两者叠加，才解释了为什么恰恰是 agent 场景——而不是聊天机器人、也不是一次性补全——省钱效果最猛。
DeepSeek 上下文缓存到底是什么
每一次对大模型 API 的请求都从 prefill（预填充） 阶段开始：模型要先处理完整个输入 prompt（系统提示词、对话历史、工具 schema，一切），才能开始生成第一个输出 token。prefill 是计算密集型的，而对一个长期运行的 agent 会话来说，同样那批 token——系统提示词、历史里的前 40 条消息——在每一轮都会被重新处理一遍，因为每一新轮不过是在不断增长的 prompt 末尾追加一条用户消息或工具结果而已。
DeepSeek 的上下文缓存（官方文档见 api-docs.deepseek.com/guides/kv_cache）利用的正是这种冗余。每次请求，DeepSeek API 都会检查新 prompt 的前缀——从第 0 个 token 开始逐字节匹配——有多少已经在之前的某次请求里算过、缓存过。凡是匹配上的部分，按更便宜的缓存输入价计费；只有 prompt 新增的尾部（以及输出部分）才按正常价格计算和计费。这没有任何开关要你去打开——它是自动的，是 API 本身的特性，跟 dsh 无关。
关键在"前缀"两个字。缓存命中要求的是从 prompt 起始位置开始、逐 token 完全一致。只要在某个位置之前插入、删除或调整了顺序，这个位置之后的一切都会缓存未命中。
为什么 dsh agent 会话能冲到 97%-99%
"必须是完全相同的前缀"这个要求，正是 dsh 架构起作用的地方——而不是巧合。一个多轮 agent 会话天然就是只追加式（append-only）的前缀：每一轮只是把模型上一轮的回复、它调用的工具、新的用户输入追加到已有对话的末尾。只要上游没有任何改动，之前每一轮都必然是缓存命中，只有新追加的尾部需要重新计算。
dsh 的会话存储从结构上支撑了这一点，而不是碰巧如此：会话是事件溯源日志（见 session-persistence-jsonl / session-persistence-sqlite 两个包），历史一旦写入就不可变；给定会话的系统提示词也保持固定，除非你主动切换 agent 模式。系统提示词不变 + 历史严格只追加，这个组合已经很接近前缀缓存最理想的输入形状。
Reddit 上的数字印证了这一点，但照例要标注：这些都是自述数字，未经独立核实：
- 在 dsh 发布贴（r/LocalLLaMA）下，多位用户报告用 dsh 系家族的 harness 接 DeepSeek 时缓存命中率约 97%——其中一位用的是第三方 harness reasonix 而非 dsh 本身——有人提到一次 one-shot 的 SPA 构建总花费只有 0.06 美元。（reddit.com/r/LocalLLaMA/comments/1vnb66j）
- r/DeepSeek 上另一位长会话用户报告，在单个 dsh 会话累计约 6150 万 input token 后，缓存命中率涨到了 99%——样本量足够大，不太像巧合，但依旧只是一个人的自述，不是经过审计的 benchmark。（reddit.com/r/DeepSeek/comments/1vnpt5n）
- r/DeepSeek 另一个帖子里，"100% 缓存命中"一度成了玩梗素材（"你以为你的消息是独一无二的，其实早有人发过了"/"DeepSeek 发明了时间旅行"），随后一条详细的社区科普长评论讲清了 prefill 和前缀匹配的原理，并引用了 DeepSeek 官方 KV cache 文档——说明不少用户早就注意到了这个效果，只是不理解背后的机制。（reddit.com/r/DeepSeek/comments/1vnfz2l）
这里面 dsh 并没有对 API 做什么特殊操作——它只是没有意外破坏这套本来就奖励"长、稳定、只追加"prompt 的缓存机制。
什么会打破缓存
反过来说，任何改动了 prompt 共享前缀（而不是纯粹追加在末尾）的操作，都会让下一次请求触发全部或部分重新 prefill。具体来说：
| 操作 | 对缓存的影响 |
|---|---|
| 在同一会话里发一条新消息 | 无影响——这正是缓存机制为之设计的"只追加"场景 |
切换 agent 模式（如 minimal ↔ 标准 ↔ PTC） | 会改变系统提示词和工具 schema，从这一点起缓存前缀失效 |
| 会话中途换模型或换 provider | 缓存是按模型区分的；换 provider 相当于从头开始 |
| 插件往 prompt 里注入动态内容（时间戳、实时计数器、随机排序） | 每次触发都会破坏逐字节匹配要求，即使历史其余部分没变 |
| 会话分叉（fork） | 分叉点之前共享的历史仍然逐字节一致，理应照常命中缓存；只有分叉之后的轮次会产生分歧 |
| 工具输出是否计入被缓存的前缀 | 确实不清楚——DeepSeek 文档没有明确说明这一点，社区讨论也没有定论，两种说法都应当视为未经证实 |
实用结论已经在社区非正式流传：一个会话生命周期内尽量保持系统提示词和插件集合稳定，避免任何往早期上下文里注入非确定性内容的做法。
怎么看自己的缓存命中率
不需要靠猜——dsh 的 Web UI 会直接在每个会话里显示缓存命中率。这个功能存在已经有一段时间了，但显示本身有个粗糙的地方：早期版本对 99.x% 这类数字的四舍五入方式，恰好在大多数长 agent 会话所处的那个区间丢失了精度。v0.1.1-rc.1 版本（2026-08-21）专门优化了 99.x% 缓存命中率的显示精度，同版本还修了一个 Bubblewrap 沙箱漏洞、新增了 DeepSeek-V4-Flash-Vision-Exp 模型适配器。如果你还停留在旧的 0.1.0-rc.x 版本，升级前可以先看看升级指南了解还有哪些改动。
一份实用的省钱清单
以下都不是 DeepSeek 官方建议——而是社区反复报告的经验，能确认来源的都已标注：
- 留意分时定价的波动。 dsh-token-anxiety 插件的作者——这个插件专门追踪每个任务的花费并对照峰谷价时段——在 Reddit 上表示"峰谷时段差异巨大"（"peak vs valley hours make a HUGE difference"）会明显影响实际成本。这是一条社区报告，我们没有独立对照 DeepSeek 定价页面核实过。（reddit.com/r/DeepSeek/comments/1vph1ig）
- 难题留给 Pro，其余都用 Flash。 同一来源：把日常任务路由到更便宜/更快的模型档位，把大模型留给真正需要它的问题。
- 谨慎使用子代理。 同一条 Reddit 帖明确提醒，除非你能严格控制，否则不要随意开子代理（subagents）——每个子代理通常会起自己的一份上下文，也就意味着自己的一次 prefill，会稀释父会话已经积累的缓存优势。在大量依赖委派之前，可以先看看 DeepSeek Harness 子代理是怎么运作的。
- 系统提示词和已装插件尽量精简。 另一条 r/LocalLLaMA 高赞帖详细论证了这一点：系统提示词臃肿的 harness，无论有没有缓存，每一轮都要多付一份 prefill 成本；插件集合越精简，一旦有变动需要作废的部分也越少。如果你要找的正是成本追踪类插件，可以逛逛 Usage & Billing 分类；想看别的插件就去完整的插件目录。
安装这个成本追踪插件的方式和装其他插件一样：
dsh plugin --profile web add github:mov-eax-eax/dsh-token-anxiety
这是否意味着 dsh 免费？
缓存能显著降低你的实际单 token 成本，但不代表 dsh 免费——你仍然需要所用 provider 的 API 额度，而 dsh 软件本身是否免费/MIT 协议，跟缓存机制无关。完整说明见 DeepSeek Harness 是免费的吗？；如果你想比较的是不同 harness 之间的总体成本，而不只是 dsh 内部的缓存表现，可以看 哪个 Harness 跑 DeepSeek V4 效果最好？。
FAQ
一句话说清 DeepSeek 上下文缓存是什么？
DeepSeek 的 API 会自动复用之前请求里已经计算过、且与本次 prompt 前缀逐字节匹配的那部分 KV cache，匹配上的部分按更低的缓存输入价计费。
为什么偏偏是 dsh 的会话命中率能这么高？
因为 dsh 的会话是只追加的事件日志，每种模式下的系统提示词保持稳定——对话只会在末尾增长，这正是前缀缓存奖励的那种形状。
97%-99% 这个数字适用于所有 dsh 会话吗？
不适用——这是长期、稳定、agent 模式和插件集合都没怎么变的会话自述出来的数字。如果一个会话频繁切模式、切模型，或者往早期上下文注入动态内容，命中率会更低。
工具调用的输出会计入被缓存的前缀吗？
目前没有清楚的官方说明，社区也没有定论——任何关于"工具输出是否被缓存"的具体说法，在 DeepSeek 文档明确回应之前都应当视为未经证实。
我需要配置什么才能用上缓存吗？
不需要——上下文缓存在 DeepSeek API 侧是自动生效的。你唯一能控制的是 prompt 的形状（系统提示词、插件集合、模式）是否足够稳定，能持续命中缓存。
Next steps
升级到 v0.1.1-rc.1 后，去 dsh Web UI 里看看自己会话的缓存命中率——这个版本改进了 99.x% 的显示精度。如果子代理是你工作流的一部分，在扩大委派规模、稀释缓存之前，先读一读 DeepSeek Harness 子代理。想做更全面的跨 harness 成本对比（不只是缓存机制本身），见哪个 Harness 跑 DeepSeek V4 效果最好？；想找成本追踪类插件，去 Usage & Billing 分类或完整的插件目录逛逛。