zcode-usage-stats：DeepSeek Harness 的 Token 用量統計插件

插件簡介¶

DeepSeek Harness（DSH）提供了會話管理能力，但通常缺乏對歷史 Token 消耗的詳細統計。zcode-usage-stats 插件通過掃描全歷史會話，聚合每天、每小時以及每個模型的 Token 用量，並以趨勢圖、儀表盤和熱力圖的形式展示。

該插件由 qianxiao1213 維護，屬於客戶端插件。它解決了開發者查看歷史資源消耗的需求，支持多種時間粒度的切換與數據可視化。

安裝與啓用¶

在安裝前，請確保宿主環境滿足以下依賴條件：
* @deepseek-ai/dsh 版本鎖定爲 >=0.1.0-rc.5
* 依賴 DSH 宿主提供的 sessionPersistence、webServer 服務
* 依賴客戶端運行時的 @deepseek-ai/dsh-client-runtime、@deepseek-ai/dsh-client-ui-slots

執行以下命令安裝：

dsh plugin --profile web add zcode-usage-stats

安裝完成後，重啓 DSH 進程，在 設置 → 使用統計 路徑下即可看到統計頁面。

核心功能¶

該插件主要包含以下能力：

多種時間範圍：支持今天、昨天、最近 7 天、最近 30 天、本月、上月，以及自定義區間。自定義區間支持年/月/日點選，且起止日期會自動校驗防止倒序。
智能粒度切換：當選擇今天、昨天或單日自定義時，趨勢圖橫軸會自動從「天」切換爲「小時」。
數據可視化：
- 多模型面積趨勢圖：採用 Catmull-Rom 平滑曲線，提供參考線吸附和數據點提示。圖例支持點擊顯隱單系列。
- 模型用量儀表盤：環形佔比展示，口徑與趨勢圖統一。
- 活躍熱力圖：GitHub 風格，支持按窗口日摺疊列，Hover 放大並顯示提示。
主題與性能：
- 顏色與 DSH 主題聯動（<body data-ds-dark-theme>）。
- 採用磁盤+內存雙層緩存，支持後臺刷新（SWR），保證首屏秒開。

使用指南¶

切換時間範圍：在頁面頂部點擊預設的時間按鈕（如“最近7天”），或點擊“自定義”彈出日期選擇卡片。
查看趨勢：將鼠標懸停在趨勢圖上，可查看參考線聯動的具體數據；點擊圖例可單獨顯示或隱藏某個模型的數據。
刷新數據：如果需要強制重新掃描全量會話，點擊“刷新”按鈕即可。

技術細節與數據口徑¶

數據來源：
- Token 用量：以 assistant/message 事件攜帶的全量 usage 爲準，並進行了去重處理。
- Turns 計數：以 step/end 事件按新 turn 計數。
- 模型歸類：未知模型會被歸併爲 other。
緩存策略：採用後臺刷新策略，過期後自動更新緩存，避免阻塞首屏渲染。

適用場景¶

適合需要精細化管理 DeepSeek 會話成本、分析不同模型使用頻率的開發者或團隊。通過熱力圖和趨勢圖，可以快速識別活躍時間段和模型偏好。