# [Feedback] 一个会话的提示词缓存命中率从 ~97% 掉到 ~11% —— 疑因会话中途工具集变化导致前缀缓存失效

[clearkurt]

[Feedback] 一个会话的提示词缓存命中率从 ~97% 掉到 ~11% —— 疑因会话中途工具集变化导致前缀缓存失效

注：仓库关闭了 GitHub Issues，所以把反馈发到这里（Discussion）。这是一个效率/成本优化的反馈，不是崩溃型 bug。

TL;DR

在一次会话（"Magic Roguelike 3D Game Design"）里，缓存命中率只有 ~11%，而同机的其他会话都在 86–98%。排查后发现,大概率是会话中途工具（function）列表发生了变化，导致 DeepSeek 的前缀缓存从这一步起大面积失效,整条会话的命中率被拉垮。

背景 / 目的

dsh 每个 step 都会把完整消息历史重新序列化发给模型。DeepSeek 的提示词缓存是自动前缀缓存——只有两次请求的前部逐字节一致才能命中。请求前部 = system prompt + 工具定义 + 历史消息，而工具定义紧跟在 system prompt 后面、位于前缀最前面。一旦工具被增删，前缀就从那里断开,后面一大堆历史全部无法命中。

我想请官方/社区确认：会话执行中途不应增删工具集（至少不应破坏一个 turn 内的前缀稳定），并希望据此优化。

实测数据（session session-e3ec5725）

来自 ~/.dsh/storages/session_projcache.json：

• uncachedInputTokens = 56,659
• cacheReadTokens = 6,656
• 命中率 = 6656 / (6656 + 56659) ≈ 11%

（GUI 显示口径即 dsh-client-ui-conversation 的 cacheHitPercent：round(cacheReadTokens / (uncachedInput + cacheRead + cacheWrite) * 100)）

现场时间线（来自 session JSONL）

1. Step 1 —— 请求头带 26 个工具，含一个自定义/运行时工具 win_terminal_probe（request/header reason: initial）。这一步冷启动（该步 usage cacheReadTokens: 0）；且模型为 deepseek-v4-pro + reasoningEffort: max，输出巨大——step 1 usage 里 reasoningTokens: 45148。
2. Step 1 → Step 2 之间 —— 出现新的 request/header 且 reason: change：工具从 26 → 25，win_terminal_probe 被移除。
3. Step 2 —— 由于工具定义在前缀区，删掉一个工具后，前面已经累积的大量历史（含那 4.5 万推理 token）无法命中缓存 → uncachedInput = 47,728，仅命中 6,656。

合计 63,315 个输入 token 计费、只有 6,656 命中 ⇒ 11%。

为什么重要

• harness 每个 step 都重发完整历史，但"前缀稳定"的前提被会话中途的工具集变化打破。
• 叠加 reasoning-max 模型把 prompt 撑得很大，一次前缀断裂就要重复计费几万 token，在 3 步的 turn 里就是一笔不小的、本可避免的开销尖峰。

复现模式（猜测，欢迎补充）

1. 起一个会话，让 step 1 注册了一个条件/运行时工具（例如插件加了 *_probe 工具）。
2. 到 step 2 时该工具消失（热重载、插件启用/禁用、后端状态变化等）。
3. 观察缓存命中骤降、uncachedInputTokens 涨到接近完整历史大小。

建议改进（开放式，欢迎讨论）

• 让一个 turn 内的工具集（前缀区）保持稳定。若某插件工具是临时的：
  • 把工具增删推迟到 turn 边界（turn/start），而不是 turn 中间的 step 之间；或
  • 将易变/条件工具从缓存前缀区挪走/单独下发，让"常驻工具"在一个 turn 内固定不变。
• 在 token/trajectory 视图里给出"工具列表变化导致前缀失效"的单步提示，方便用户/开发者一眼看出某步为何脱缓。
• 若工具集必须变化，尽量放在新 turn 开头（首个请求本来就要重写缓存），而不要在打开中的 turn 内中途变。

环境

• dsh 0.1.0-rc.6（@deepseek-ai/dsh）
• provider deepseek-official，模型 deepseek-v4-pro（reasoningEffort max）/ deepseek-v4-flash
• Windows + Web GUI（:3080）

参考 artifacts

• 会话 id：session-e3ec5725-40bc-435d-b08f-9ce85e5ce4dd（"Magic Roguelike 3D Game Design"）
• 证据：request/header seq 18（26 工具，initial）与 seq 45337（25 工具，change，移除 win_terminal_probe）；step-1 usage {inputTokens:8931, outputTokens:45423, cacheReadTokens:0, reasoningTokens:45148}；step-2 bucket {uncachedInputTokens:47728, cacheReadTokens:6656}。

[DRAG0NM]

答复草稿 · #935 提示词缓存命中率暴跌（工具集中途变化）

你的机制判断是对的，rc.6 源码可完整印证，并补充"为什么会变"的机制：

确认：request header 携带完整 tools，任何变化都记录 change 并必然击穿前缀缓存

• @deepseek-ai/dsh-agent-loop/lib/index.js buildRequest()：
  • L702-707：const header = canonicalHeader({ config, ..., ...tools.length > 0 ? { tools } : {} }) —— tools 定义是 header 的一部分（紧跟 system 后、位于请求最前部，与你的判断一致）；
  • L708-718：if (!headerEquals(baseline, header)) this.session.append("request/header", { header, reason: "change" }) —— 只要 tools 集合/顺序/定义有任何变化，header 不等 → reason: "change"。
• 因此 DeepSeek 自动前缀缓存从该 step 起整段失效（前缀 = system + tools + 历史，逐字节一致才命中），你实测的 11% 命中率是直接结果。

为什么会变：工具集是动态 registry，每 step 重新组装

• tools 参数来自 assembly.tools（agent-loop L613 buildRequest(turn, step, assembly.tools, ...)），每个 step 重新组装，不是会话级快照；
• 工具集由 registry 动态决定：@deepseek-ai/dsh-tool-cordis 目录文档 L3866 明确 "A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only)" —— 工具注册/注销、作用域限制变化都会改变下一个 step 的可用工具集；
• 你时间线里的 win_terminal_probe 不在官方 rc.6 包里（我在发布产物中检索无此工具名），属于你的自定义/第三方工具或插件——它在 step1 后从可用集消失（注册状态/作用域变化），正是 registry 动态性的体现。

建议方向（供官方/社区参考）

1. 会话级工具集快照：首次 request/header 后冻结该会话的工具集（或按 turn 冻结），registry 变化只影响后续新会话——前缀稳定收益最大，代价是会话中途新注册工具不可见；
2. 稳定排序：tools 按名称排序后进入 header，消除注册顺序抖动造成的无意义变化；
3. 至少：保持 turn 内 step 间工具集不变（当前工具集是 step 级组装），并把"工具集变化"作为显式事件提示给用户（成本可预期，避免悄然 97%→11%）。

另注意：4.5 万 reasoning tokens 落在前缀区，一次工具变化就把它和全部历史一起变成 uncached——工具集稳定性对长推理会话的成本影响远大于直觉。

[Yan-Zero]

看完这条里 26 → 25 个工具导致缓存从中间断掉的时间线，我沿着这个场景把一个实验方案整理成了可安装插件：dsh-progressive-tools。

它会把非 eager 工具的完整 schema 从每步顶层 tools 数组里收起来，稳定保留 search_tools、describe_tools 和必要的调用入口。search_tools({}) / search_tools({ query: "*" }) 返回当前目录的 name + description，选定后再用 describe_tools 取精确 schema。后续工具注册或注销只会改变 discovery 的结果，不会把整份动态 schema 表塞回请求前部。

Native 模式下，支持 deferred tool loading 的 pi-ai Responses / Anthropic 模型会收到原生披露；其他接口走 invoke_tool；Code 模式继续使用 run_code。执行最终仍回到当前 ToolRuntime，所以 policy、approval、guard 和工具是否还存在都照常生效。

目前发布到 npm 的版本是 0.2.3：

dsh plugin --profile web add dsh-progressive-tools

这个实现没有改 Harness checkout，也不用另建 preset。你的这组缓存数据正好说明了它想处理的成本尖峰；如果后面方便用同一个会话复测，前后 request/header 和 cache hit 数据会很有参考价值。

[DRAG0NM]

感谢把工具集稳定化做成了可安装插件（dsh-progressive-tools）——把非 eager 工具的完整 schema 移出每步顶层 tools 数组，正好对准 #935 时间线里工具增删击穿前缀缓存的问题。我们这边暂无现成复测数据，欢迎社区反馈前后 request/header 与 cache hit 对比，那会是很有价值的验证。