前言¶
DeepSeek Harness (DSH) 的插件系統允許對核心功能進行擴展。在智能體開發或日常使用中，追蹤 Token 消耗、查看模型活躍度是常見需求。dsh-usage-stats 是一個面向 DSH 官方桌面版的「使用統計」插件，它在設置頁新增了專門的統計分區，提供五格終身摘要、GitHub 風格熱力圖及趨勢折線等可視化功能。該插件的數據全部在本地落盤，不涉及網絡上傳，且不引入額外的運行時依賴。
核心功能¶
該插件主要提供以下可視化與數據功能：
- 五格終身摘要條：展示累計 Token 數、單日峯值 Token 數、最長聊天時長、當前連續天數以及最長連續天數。
- Token 活動熱力圖：呈現 52 周的 Token 活動情況，支持每日、每週/累計三檔視圖切換。
- 趨勢折線：提供今日、近 7 日、近 30 日三種時間維度的趨勢折線圖，支持按模型查看。
- 模型用量環形圖：顯示選定時間範圍內各模型的 Token 佔比。
- 歷史會話回填：插件啓動時會自動掃描並回填歷史會話數據；用戶也可在頁腳手動點擊「回填歷史」按鈕觸發。
- 本地 JSONL 落盤：數據以 JSONL 格式保存在本地，作爲唯一真源。
- 零上傳與零依賴：不向遠程服務器發送任何數據，且無需執行
npm install。
安裝與啓用¶
安裝該插件需要使用 DSH 的插件管理命令。確保宿主環境滿足要求：DSH 版本 0.2.0-rc.2 及以上，宿主 Node.js 版本 >= 22.15。
使用 GitHub tag tarball 渠道安裝（推薦）：
dsh plugin --profile desktop add https://github.com/axuan-1314/dsh-usage-stats/archive/refs/tags/v0.2.0.tar.gz
安裝後，插件會自動生效，並在設置頁增加「使用統計」分區。若使用 web 或 headless profile，需將命令中的 --profile desktop 替換爲對應 profile 名稱。
數據與配置¶
數據位置¶
所有統計數據均存儲在本地文件系統，不上傳。默認路徑爲 ~/.dsh/usage-stats/。數據包括按月輪轉的 JSONL 流水文件（records-YYYY-MM.jsonl）和日聚合緩存文件等。
配置項¶
插件支持以下配置鍵（通常在配置文件中設置）：
enabled：是否啓用插件，默認爲true。storageRoot：自定義數據存儲根目錄。sessionsRoot：自定義會話文件路徑。
典型用法¶
安裝並重啓 DSH 後，可在設置頁「使用統計」分區查看數據。若需通過 API 直接獲取數據，可訪問以下接口：
- 獲取摘要：
GET /api/dsh-usage-stats/summary - 查看熱力圖：
GET /api/dsh-usage-stats/heatmap?days= - 查看趨勢：
GET /api/dsh-usage-stats/trend?days=1|7|30 - 查看模型用量：
GET /api/dsh-usage-stats/models?days=7|30
對於歷史數據，若插件未自動完成回填，可點擊頁腳的「回填歷史」按鈕。該操作採用 202 受理制，會在後臺分片執行，不會凍結界面。
適用場景與注意事項¶
適用場景¶
該插件適合需要詳細監控 Token 消耗成本、分析使用習慣以及管理多模型使用場景的開發者。
注意事項¶
- 單寫者鎖：若同時開啓兩個 DSH 實例，後加載的實例將降級爲只讀鏡像，僅展示數據而不進行採集和回填。
- 內存狀態：Live 摺疊槽數據存儲在內存中，進程重啓後會丟失。
- 版本要求：請確保 DSH 版本不低於 0.2.0-rc.2，宿主 Node.js 版本不低於 22.15，否則無法正常工作。
總結¶
dsh-usage-stats 插件通過本地採集和回填機制，爲 DSH 提供了一套輕量級的用量統計方案。它不需要複雜的依賴配置，數據完全可控，適合作爲開發者監控和優化智能體成本的基礎工具。
