前言¶
在 DeepSeek Harness（dsh）里跑长会话时，系统提示、工具列表和上下文开头一旦能被前缀缓存命中，后续轮次会按缓存价计费。反过来，只要前缀被改写，整段前缀会重新按未缓存全价重计——这是省 token 费用的关键约束。
单看 usage 里的 inputTokens（未缓存输入）变高，无法区分「正常变长」（例如大工具结果、长粘贴）和「前缀真被重写」。前者 cacheRead 往往仍高；后者未缓存暴涨的同时，cacheRead 会相对自身基线塌陷。下面介绍维护者 121212165 的插件 dsh-plugin-cache-guard：监听 usage 流，用三闸门把两类形状分开，估算重写多付的 token，并在出现新的前缀重写时向模型注入一次诊断提示。
这是什么¶
dsh-plugin-cache-guard 是 dsh 生态下的 admin-security 类插件，当前版本 0.2.0（MIT 许可证）。它不负责改模型行为，只做前缀缓存健康诊断：区分「前缀重写（rewrite）」与「变长（growth）」，并给出命中率、判定档位与多付合计。
与同系列的 price-aware（花了多少）、cost-ledger（台账）互补——本插件回答 为什么多花。
目录页：SkillHub - dsh-plugin-cache-guard
源码：GitHub - 121212165/dsh-plugin-cache-guard
核心功能¶
三闸门尖峰判定¶
只有同时满足下面三步，才记一次 前缀重写：
- 未缓存输入超过滑动基线带（大小闸）；
- 该步
cacheRead相对自身基线塌陷（形状闸）； - 重计的量约等于上一步整个 prompt（归因闸）。
只过大小的步（大工具结果、长粘贴：未缓存暴涨但前缀仍命中）记为 变长（growth），不算抖动、不计入浪费。
dsh 的 usage 三桶互斥（@deepseek-ai/dsh-llm 的 TokenUsage：inputTokens 仅为 uncached input；计费输入 = inputTokens + cacheReadTokens + cacheWriteTokens）。真重写时 cacheRead 常塌到 128（块粒度残值，不是 0），因此判定用比值塌陷，而不是 cacheRead === 0。
/cache 与 cache_status¶
/cache：展示命中率、判定（稳定 / 观察 / 不稳定）、重写明细（含塌陷前后与上一步 prompt）、变长步数、多付合计。cache_status工具：供 agent 在会话中自查缓存健康。
adviseModel（默认开启）¶
出现 新的 前缀重写时，通过 tools/post-execute 向上下文注入插件提示（与 price-aware 同一条注入路径）。同一次断裂只提醒一次，避免后续每一步重复刷屏。v0.2.0 使用 session format v4 的 plugin:<name> 来源 kind，修复 v0.1.0 在 dsh 0.1.7 上因旧 source 包装导致会话中断的问题。
配置项¶
在 profile 中按需覆盖下列字段（默认值来自 README）：
| 字段 | 默认 | 说明 |
|---|---|---|
window |
8 | 基线滑动窗口（同时也是「最近」的跨度） |
factor |
2.5 | 大小闸：未缓存基线倍数 |
floorTokens |
1500 | 大小闸：绝对地板（正常增长不误报） |
collapseRatio |
0.25 | 形状闸：cacheRead 低于自身基线该比例算塌陷 |
collapseMinBaseline |
2000 | 形状闸：基线低于此值不判塌陷 |
rebillShare |
0.6 | 归因闸：重计量需达到上一步 prompt 的该比例 |
adviseModel |
true |
上下文内提醒 |
前 window 步不参与判定（滑动窗口未填满），冷启动阶段的塌陷不会被报。
安装与启用¶
README 给出的方式是：克隆或 npm 安装到 profile 的 node_modules；从源码安装需先在插件目录执行 npm install（prepare 会自动构建）。
运行环境要求 Node.js >= 22.18。插件通过 cordis.patch.yml 挂载到 Cordis 事件面（session/event → tools/post-execute 注入）。资料中未给出统一的 dsh plugin add … 一行命令，安装前请对照仓库 README 与 profile 的插件加载方式。
本地校验可执行：
npm run check
包含 typecheck、13 个 node --test 单测与 build。真实 usage 回放：
npm run replay
在 test/replay-corpus.json（39 个会话 / 206 条 assistant/message 记录，仅 token 分桶与 turn/step）上，旧单闸规则 17 次「指控」中 6 次被三闸门降级为变长，11 次真重写全部保留。
典型用法¶
- 将插件按上述方式装入当前 dsh profile 并启用。
- 在长会话中观察 usage：若怀疑前缀被反复改写，在客户端执行
/cache查看判定与重写明细。 - 若希望模型主动排查，在工具列表可用时调用
cache_status（实跑日志中可见模型连续调用，输出形如「缓存命中率 … · … 步 · 判定: ✅ 前缀稳定」一类摘要）。
出现新的前缀重写且 adviseModel 为 true 时，插件会注入一次诊断，无需人工每步盯 inputTokens。
适用场景与注意¶
适合谁：依赖 DeepSeek 前缀缓存、上下文较长、工具结果或粘贴频繁变长的 dsh 用户；需要区分「真重写浪费」与「正常变长」时。
权限与安全：插件以当前 dsh 进程的权限运行，会读取会话 usage 流并在重写时注入上下文。安装前应阅读 源码仓库 与 MIT 许可证，确认符合你的环境策略。SkillHub 目录为社区站点，与 DeepSeek / 幻方无官方从属关系。
已知边界（README 原文要点）：
- 判定只看 usage 流，无法区分「头部被重渲染」与「缓存 TTL 过期」——计费形状相同，提示只标轮次/步骤边界。
cacheWriteTokens参与 prompt 与命中率口径，不参与重写判定（部分 relay 不返回该字段）。- 持续断裂会被滑动基线吸收：同一会话里若每一步都在塌，可能只报开头几次，之后计数静默；此时应看命中率与逐步
cacheRead明细，而不只看重写次数。
结尾¶
dsh-plugin-cache-guard 把前缀缓存从「未缓存数字变高就慌」变成可解释的三闸门诊断，并用 /cache、cache_status 和一次性 adviseModel 提醒，帮助在长会话里盯住前缀是否稳定。
