dsh-cache-report

命中率从 96% 掉到 80%，是谁吃的？

DSH（DeepSeek Harness）提示缓存命中率与工具块成本报表。一条命令告诉你：今天的 token 花在哪、哪次操作最贵、哪个插件在占位。

中文 | English · MIT · 零运行时依赖

它回答什么问题

大模型的输入分「命中缓存」和「未命中」两种价钱（DeepSeek 官方约 1 : 10）。缓存按前缀精确匹配，而请求的排布是：

[工具定义]   ← 一变，后面全部作废
[系统提示]
[历史消息…]  ← 缓存主要靠这里
[本轮新内容] ← 只有这里应该按未命中计费

于是：在长会话中途装一个插件、启停一个组件、切一次权限档，工具定义就变了——此后整段上下文（系统提示 + 全部历史）会按全价重算一遍。

多数人只看到命中率掉了，却不知道是谁吃的。这个工具就是回答这个的。

安装

前置：DSH（@deepseek-ai/dsh）+ Node.js ≥ 20。

方式 A：作为 DSH 插件（推荐）

dsh plugin --profile web add github:youran0faust/dsh-cache-report#main

重启 DSH（或依赖 profile 的 patchReload: live 热加载），然后在会话输入框打：

/cache-report

它只注册斜杠命令、不注册任何工具——因此不改变工具表、不会破坏你自己的缓存。常驻零成本。

方式 B：独立脚本（不需要插件机制）

git clone https://github.com/youran0faust/dsh-cache-report.git
node dsh-cache-report/lib/report.mjs today

零运行时依赖，只用 Node 内置模块（node:fs / node:path / node:zlib / node:os）。

命令

输入	作用
`/cache-report`	不带参数 = `today`：今天的命中率 + 大额重算归因
`/cache-report days 7`	近 7 天趋势表
`/cache-report tools 30`	工具块成本 / 按插件拆分 / 从未被调用的死重
`/cache-report before-after 24`	近 24 小时：工具表变化时间线 + 重算代价 + 真实台账花费
`/cache-report debug 7`	格式自检：DSH 会话格式是否仍符合预期
`/cache-report help`	用法

独立脚本用法相同：node lib/report.mjs days 7。

示例输出

以下数字为示意，用于展示输出形状。

$ /cache-report days 7

# 近 7 天缓存趋势（扫描 96 个会话文件）

日期          请求    命中率      未命中tok       命中tok   大额重算   归因Top
2026-10-09     412    95.8%       1,204,331    27,461,882       12   compaction 41%
2026-10-10     688    96.1%       1,988,204    48,932,110       19   compaction 52%
2026-10-11     903    95.4%       2,741,558    56,880,231       27   compaction 47%
2026-10-12     744    94.9%       2,105,772    39,204,118       22   compaction 55%
2026-10-13     611    92.3%       3,388,901    40,612,447       38   compaction 58%
2026-10-14     402    79.5%       6,120,338    23,742,905       61   compaction 74%
2026-10-15     288    73.6%       4,884,120    13,618,442       44   toolset-change 48%

拐点出现在 10-14，而且归因换了人：从 compaction（历史压缩）变成 toolset-change（工具表变化）——那正是当天连装了几个插件的日子。

$ /cache-report tools

来源               工具数      tok    占比   其中从未调用
  agent-teams           14    4,508   24.9%   ~4,407 tok
  host-core             21    4,308   23.8%   ~224 tok
  dsh-mnemon            17    3,579   19.8%   ~1,315 tok
  dsh-ops                5    2,056   11.4%   ~378 tok
  dsh-undo-savepoint    15    1,936   10.7%   ~1,557 tok
  shell/job              4    1,151    6.4%   -
  modsearch              4      520    2.9%   ~190 tok

## 从未被调用（共 37 个 / ~8,071 tok）
  ~  790 tok  agent_teams_create_task          agent-teams
  ~  752 tok  agent_teams_update_task          agent-teams
  ...

怎么读：命中率是比率陷阱

命中率 = 命中 / (命中 + 未命中)。但别只盯比率——它会被上下文长度稀释或放大：

	命中率	每次请求 token	实际花销
长会话	96%	190k	高
短会话	80%	148k	更低

比率掉了，账单可能反而降了。真正该看的是「未命中 token 的绝对值」，那才是按全价计费的部分。

工具把「单请求未命中 ≥ 5 万 token」（阈值 DSH_REPORT_BIG 可调）的事件称为大额重算，并按原因归类：

归因	含义	你能控制吗
`toolset-change`	装/卸插件、启停组件、切权限档	✅ 能 —— 攒着一起改，改完开新会话
`compaction`	历史压缩（长会话的必然代价）	⚠️ 半能 —— 会话别拖太长
`session-start`	新会话冷启动	⛔ 正常开销
`resume`	恢复旧会话	⛔ 正常开销

三条实用规则

插件攒着一起装，装完开新会话。 中途装一个，当前会话的历史就得全价重算一遍。
别在长会话里切模型 / 切权限档。 同理，都在改前缀。
看未命中 token 的绝对值，不看百分比。

数据来源与隐私

读的是本机 DSH 会话日志：$DSH_HOME/sessions/ 下的 session.v*.jsonl.zstd（多帧 zstd，脚本按魔数切帧逐帧解）。

只用其中的用量数字与工具表：

assistant/message → usage.inputTokens（未命中）/ usage.cacheReadTokens（命中）
request/header → 当时的工具定义列表 + reason（initial / series / resume / change）

不会打印任何对话内容、文件内容或密钥；tools 只输出工具名字。所有计算在本机完成，不联网、不上传。

局限（诚实说明）

token 数是估算：工具表按 ASCII字符/4 + 非ASCII字符/1.5 估算，误差约 ±10%。
归因是启发式的：按「大额重算之前最近的一个原因事件」判定，压缩与工具表变化挨得近时可能归错。
只覆盖能观测到的：读的是 DSH 落盘的会话日志，未落盘或被清理的会话不计入。
zstd 依赖 Node ≥ 22.15（node:zlib 的 zstd API）。更低的 Node 会报错。

卸载

dsh plugin --profile web remove dsh-cache-report

独立脚本直接删目录即可。它不写任何配置、不常驻进程、不留状态。

开发

node lib/report.mjs help        # 自检
node lib/report.mjs days 2      # 快速冒烟

License

MIT

安装

说明文档