前言¶
用 DeepSeek Harness（DSH）跑會話時，token 用量分散在各個會話日誌裏。想知道這個月每個模型各消耗了多少、哪幾天用得最頻繁，只能手動翻日誌或自己寫腳本統計，費時且容易算錯。dsh-token-stats 是爲 DSH Web UI 打造的 Token 消耗統計插件，它以會話日誌爲數據源，把用量聚合成按天、按模型的視圖，直接顯示在設置面板裏。下面介紹它的功能、安裝方式和工作原理。
這是什麼¶
dsh-token-stats 由 MoonlitDropOfBlood 維護，遵循 MIT License。README 中聲明：本項目是基於 DeepSeek Harness 構建的社區插件，並非 DeepSeek 官方產品。
它的定位很明確：不改會話流程，不解析請求頭，直接把 DSH 會話日誌作爲唯一權威數據源，聚合出每個模型每天、每個統計區間的 token 用量。
核心功能¶
圖表能力：
- 兩個統計 Tab：近 7 天 / 近 30 天，兩個區間都包含今天
- 堆疊柱狀圖：統計區間內每個模型每天的消耗，懸停查看具體數字
- 餅圖：統計區間內每個模型的總消耗佔比，圖例帶精確值和百分比
- GitHub 風格熱力圖：近一年每日活躍，天數隨容器寬度自適應，最多顯示 365 天（一年）
- 彙總卡片：區間總 Tokens / 輸入(含緩存) / 輸出
數據與體驗：
- 本地持久化：聚合結果落盤
<DSH_HOME>/data/dsh-token-stats/stats.json，冷啓動只掃描新會話、秒開 - 自動刷新：頁面打開期間每 30s 刷新；歷史回填期間每 2s 輪詢進度
- 主題適配：全部使用 DSH 設計 token，明暗主題自動跟隨
- 去重：按 session+seq 水位線去重，歷史回填與即時監聽合併後不重複計數
安裝與啓用¶
這是一個標準 DSH bundle：package.json 聲明 dsh.bundle.patch，包內自帶 cordis.patch.yml，用官方 dsh plugin 命令安裝：
dsh plugin --profile web add https://github.com/MoonlitDropOfBlood/dsh-token-stats/releases/download/v1.2.0/dsh-token-stats-1.2.0.tgz
dsh plugin add 會把插件裝成 profile 的 npm 依賴並追加到 dsh.profile.bundles，啓動時 DSH 自動應用包內的 cordis.patch.yml 掛載插件。
本地開發時可以軟鏈到本倉庫，改代碼即生效：
dsh plugin --profile web add /path/to/dsh-token-stats
重啓 DSH 後，打開 Web UI 的設置（側欄底部），左側導航會出現 Token 統計頁。
卸載：
dsh plugin --profile web remove dsh-token-stats
典型用法¶
1、打開 設置 → Token 統計。
2、在 近 7 天 / 近 30 天 兩個 Tab 間切換：
- 柱狀圖展示區間內每天、每個模型的消耗（堆疊）
- 餅圖展示區間內每個模型的總消耗佔比
- 頂部卡片給出區間總 Tokens / 輸入 / 輸出
3、下方 每日活躍 熱力圖展示更長時間範圍：格子越多 = 容器越寬，最多覆蓋近一年。
如果想強制全量重掃歷史數據，刪除聚合文件即可，下次啓動會重新掃描全部會話：
rm <DSH_HOME>/data/dsh-token-stats/stats.json
工作原理¶
數據採集分即時和歷史兩條路，合併後統一落盤：
- LIVE：插件啓動後，監聽 session/event 中的 assistant/message（usage）即時累計
- HISTORY：通過 sessionQuery.readSession() 回填歷史，僅掃描從未回填過的會話
- DEDUP：按 session+seq 水位線去重，絕不重複計數
- PERSIST：聚合結果和水位線落盤 stats.json（防抖寫盤 + 停止時 flush）
歷史回填只統計插件啓動前發生的調用，即時監聽只統計啓動後的，兩者通過每個會話的事件序號水位線合併，不會重複。
聚合規則：
- 數據按本地日曆天 × 模型（
provider::model）聚合 total = input + output + cacheRead + cacheWrite- 模型信息來自 assistant/message 的
message.source（kind = ‘model’）
代碼結構：
dsh-token-stats/
├── index.js # Host 半：TokenStatsService（Remote 服務，採集 + 回填）
├── client.js # Client 半：設置頁「Token 統計」UI bundle
├── typert.host.js # Typert Host manifest（tokenStats/getStats 描述）
├── cordis.patch.yml # dsh bundle patch（掛載行）
├── AGENTS.md # 面向 AI agent 的開發指南（含踩坑）
└── LICENSE # MIT
依賴方面，peerDependencies 聲明 @deepseek-ai/cordis ^4.0.1 和 @deepseek-ai/dsh-typert-protocol ^0.1.0-rc.7，運行時依賴 zod ^4.4.3。
適用場景與注意¶
適合兩類人：
- 日常使用 DSH 的開發者，想了解每個模型的消耗分佈和長期活躍趨勢
- 想寫 DSH 插件的開發者，AGENTS.md 記錄了 DSH 正式插件（Host/Client/Typert 三件套）的完整機制和踩坑，可以作爲參考
安裝前注意：插件以當前 dsh 進程的權限運行，建議安裝前檢查源碼與許可證。本項目爲社區插件，並非 DeepSeek 官方產品。
小結¶
裝好 dsh-token-stats 後，每個模型每天的 token 消耗、長期活躍趨勢都能在 Web UI 裏直接看到，不用再手動翻會話日誌。倉庫地址：https://github.com/MoonlitDropOfBlood/dsh-token-stats ，社區目錄頁：https://www.skillhub.cn/plugins/MoonlitDropOfBlood/dsh-token-stats 。
