前言¶
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
