前言¶
DeepSeek Harness (DSH) 採用插件化架構。在智能體開發或長對話場景中，開發者需要持續追蹤 token 消耗、緩存命中率以及供應商的餘額情況。dsh-usage 插件通過在側欄注入面板，將餘額、用量曲線、成本估算與熱力圖集中展示，無需切換窗口即可查看數據。
核心功能¶
該插件在側欄“設置”按鈕上方注入一個“用量”按鈕，點擊後展開單頁模態面板，包含以下五個部分：
- 供應商餘額：支持 DeepSeek（
DEEPSEEK_API_KEY）與 OpenRouter（OPENROUTER_API_KEY）。憑據僅在 host 側解析，不會傳入瀏覽器。 - 用量與命中率：可切換查看“全部會話”或“單個會話”。命中率爲輸入側緩存命中率。
- 折線圖：展示當日按小時聚合的 Token 和成本曲線。懸浮鼠標可查看該小時的具體數據桶（未命中、命中、輸出）。
- 熱力圖：GitHub 風格的貢獻度展示。支持“時間模式”（最近 13 周每日）和“會話模式”（每個會話的每輪）。
- 歷史明細：分頁展示全量明細，支持導出 CSV（含 BOM，可直接用 Excel 打開）。
安裝與啓用¶
通過官方命令安裝該插件，重啓 DeepSeek Harness Web 後生效。
dsh plugin --profile web add @dshd/dsh-usage
安裝完成後，側欄“設置”按鈕上方會出現“用量”按鈕。
使用方式¶
- 查看餘額：在面板頂部切換供應商（DeepSeek / OpenRouter）以刷新余額。
- 篩選會話：通過下拉菜單切換“全部會話”或特定會話，面板數據會隨之更新。
- 分析趨勢：觀察折線圖瞭解當日 Token 和成本分佈，通過熱力圖定位高頻交互時段。
- 導出數據：在歷史明細頁點擊導出按鈕，獲取 CSV 文件進行離線分析。
數據與配置¶
- 數據來源：解析 DSH 會話日誌（內存活躍 + 磁盤持久化），提取
assistant/chunk和assistant/message事件中的 usage 數據。 - 計算邏輯：
- 命中率 =
cacheRead / (uncachedInput + cacheRead + cacheWrite)。 - 成本 = 未命中輸入×miss + 命中×hit + 輸出×out。價格按請求時刻套用官方峯谷價目，並定期在線同步官方價格頁（失敗時回退內置價目）。
- 命中率 =
- 安全性：插件不保存憑據，不上傳數據，全部計算在本機完成。
- 配置項：
cnyPerUsd：USD 換算匯率，默認爲6.76。pricing：單價覆蓋配置，支持定義峯谷時段。
適用場景與注意¶
- 適用場景：需要精細化控制 API 成本、監控緩存效果以及管理多供應商賬戶餘額的開發者。
- 注意：成本爲按官方刊例價與請求時刻計算的估算值，可能與實際賬單存在差異。插件以當前 dsh 進程權限運行，安裝前建議檢查源碼與許可證（MIT）。
結語¶
dsh-usage 提供了一套標準化的用量監控方案，適合追求成本透明與開發效率的 DSH 用戶。
