前言¶
在 DeepSeek Harness (DSH) 的開發流程中，監控模型調用的 Token 消耗、評估緩存命中率以及分析不同模型的用量分佈是成本控制與性能優化的基礎需求。通常這需要手動解析日誌或依賴零散的計數器，缺乏一個統一、直觀的儀表盤。dsh-plugin-usage-stats 插件通過直接讀取 adapter 的 usage 數據，在 Web 界面提供了一份整頁的用量統計報告。
插件簡介¶
該插件由 fakeNihilist 維護，核心職責是回答“這些會話一共用了多少 token”這個問題。它不註冊工具、不注入提示詞、不修改請求，對模型完全不可見，不影響 prompt 與 KV 緩存。安裝後，Web GUI 左側欄會新增「用量統計」入口，主區域展示整頁儀表盤。
核心功能¶
儀表盤僅包含兩個交互控件：整頁的「刷新」按鈕，以及一組「7 天 / 30 天 / 全部」的時間範圍切換。切換範圍僅改變視圖窗口，所有視圖共享同一份載荷與統計口徑。
- 概覽卡片：顯示當日 Token、累計 Token（含輸入、輸出、緩存讀拆分）以及緩存命中率，並附帶當日緩存率、當日與累計請求數。
- Token 活動：展示一年期的日熱力圖，採用 GitHub 風格的藍色四級色階。懸停任意格子可查看該日的全部指標。
- 每日 Token 趨勢圖：堆疊柱狀圖顯示輸入與輸出，背景疊加淺黃色命中率柱（右軸 0–100%）。
- 模型用量：左側爲環圖，右側爲圖例（模型名、佔比、Token 數）。懸停扇區或圖例可查看佔比、調用數與緩存率。
- 按模型明細表：按供應商分組，展示模型、調用數、未緩存輸入、輸出、緩存讀、緩存率及合計。表頭吸頂，內容可滾動。
數據特性：
* 無設置項：安裝即用，無配置文件或需調參數。
* 無推斷：所有數字直接取自 adapter 上報的 usage，不推斷、不按字數折算、不補零。
* 懸停讀數：熱力圖格子與趨勢柱的 token 值一律縮寫成 K/M/B 單位（如 698.9M），調用數與緩存率仍爲完整數值。
安裝與啓用¶
通過 DSH 的包管理器安裝插件：
dsh plugin add https://github.com/fakeNihilist/dsh-plugin-usage-stats
安裝完成後，需重啓 Host 進程以加載新代碼，隨後刷新 Web 界面即可在左側欄看到「用量統計」入口。
典型用法¶
- 打開 Web GUI，在左側欄點擊「用量統計」。
- 點擊主區域的「刷新」按鈕更新數據。
- 使用頂部的「7 天 / 30 天 / 全部」按鈕切換時間範圍，視圖同步更新。
- 懸停熱力圖格子、趨勢柱或環圖扇區查看詳細數值（熱力圖與趨勢使用獨立窗口）。
適用場景與注意¶
該插件適合需要精細化監控 Token 消耗、評估緩存策略效果以及進行模型成本分攤的開發者。
注意事項：
* 時區：統計使用宿主本地時區，進程啓動時固化偏移量。
* 子會話：子智能體會話的用量計入總量。
* 緩存寫入：當前 DeepSeek adapter 上 cacheWriteTokens 恆爲 0，明細表不再列出該列。
* 工作區：按會話的 cwd 分組，無 cwd 的會話以 session id 分組。
* 參數含義：days 參數是下限而非上限；「全部」等於語料自身的跨度（非建庫以來全部）。
* 熱力圖：沒有計費輸入的日期不畫柱。
* 主題兼容：淺色主題下的邊框與說明文字由插件自己派生。
生態背景¶
DSH 理念是“一切皆插件”，社區目錄與 DeepSeek 官方無從屬關係。
