前言¶
Agent 对话通常是 assistant -> tool -> assistant -> tool 的循环。一轮对话中，第一次模型调用往往是供应商提示缓存过期、需要整段重新 prefill（重建缓存）的时机；同轮后续的调用往往能命中刚重建的缓存。
DSH 自带的 token/缓存统计在输入框下方，产物文件行在轮尾，这两处都无法在 miss 真正发生的位置就地提示。在缓存重建频繁或上下文较长时，这种信息滞后会增加排查成本。
下面介绍 dsh-cache-miss 插件，它能在轮首第一条 assistant 回复正下方，仅当该请求确为缓存未命中时渲染一条黄色单行提示。
这是什么¶
dsh-cache-miss 是一个 DSH 网页插件，属于“记忆”类别，由开发者 wefio 维护。
该插件旨在解决 Agent 开发中难以即时定位缓存命中率低的问题。它通过在 Web 界面直接展示缓存未命中的详细数据，帮助开发者快速评估上下文管理和缓存配置的效果。
核心功能¶
该插件主要提供以下能力：
- 即时 Miss 提示：在一轮对话的第一条 assistant 回复正下方，仅当该请求确认为缓存未命中时，渲染一条黄色单行提示。
- 详细数据展示：提示中包含以下字段：
idle：距上一轮结束的空闲时长。re-billed：该轮首次请求未命中缓存的输入 token 数（缩写为 k）。cached：同一 prefill 中命中的缓存部分。ttft：首 token 时延。
- Provider 兼容性处理：当 provider 不回 cache 字段时，显示灰色提示“无法确认”。
- 纯前端实现：不写入 session log，不修改 DSH 源码，不占用 turn-tail 链，因此不会与产物文件行冲突（例如
DSH-better-sidebar）。
安装与启用¶
安装命令如下：
dsh plugin --profile web add dsh-cache-miss
执行完上述命令后，需要重启 dsh web（或对正在运行的 GUI 进行硬刷新）以加载客户端 bundle。
典型用法¶
当缓存未命中时，界面会显示类似以下格式的提示：
Cache miss after 3m idle: 182k tokens re-billed · 0.8k cached · ttft 2.1s ↑
↑：上箭头示意重建 prefill 通常更慢。- 数据取自流中的
usagechunk，提示会在 usage 到达时就出现（回复仍在生成中），不必等到 assistant 消息结束。
适用场景与注意¶
该插件适合在调试 Agent 长上下文、优化提示缓存策略时使用。
需要注意以下细节：
- TTFT 显示范围：TTFT 取自会话事件时间，即 step 的
step/start事件到首个非空 token delta 事件的墙钟间隔。当任一边界落在已加载窗口之外时，视为缺省，不显示· ttft ...段。 - Miss 判定逻辑：插件通过
hitRatio判定 miss，需满足inputTokens > 0、hitRatio < 80%且inputTokens >= 1000。 - Provider 兼容性：对于从未回传过 cache 字段的 provider，首次出现时会提示“无法确认”，不做启发式猜测；后续出现该 provider 时，若仍无 cache 字段则保持静默。
- 日志输出：每一步至多输出一条控制台日志，命中轮不产生可见行。
短结尾¶
经过上面的步骤，dsh-cache-miss 即可在 DSH 网页端提供实时的缓存命中率反馈。它不修改系统核心逻辑，仅通过前端展示辅助开发者优化上下文策略。
插件目录：https://www.skillhub.cn/plugins/wefio/dsh-cache-miss
GitHub 仓库：https://github.com/wefio/dsh-cache-miss
