前言¶
用 DeepSeek Harness（下稱 DSH）跑智能體的團隊都會遇到同一個問題：每個會話都在產生 token 用量，但這些數字分散在各自的會話裏。想知道這個月總共花了多少美元、哪幾天是消耗高峯、deepseek-v4-flash 和其他 provider/model 各佔多少，往往要逐個會話去看。
dsh-token-stats 把這件事做成一個設置面板：跨會話彙總 token 用量，按 provider 和模型拆分，畫成月度堆疊成本圖。它也是 DSH「一切皆插件」理念下的一個典型樣本——整個功能以獨立 bundle 提供，不需要改核心倉庫一行代碼。
下面介紹這個插件的定位、工作方式和安裝步驟。
這是什麼¶
dsh-token-stats 是 DeepSeek Harness 的一個插件，由 qiushui0901 維護，MIT 許可。一句話定位：爲 DSH 提供跨會話的 token 用量統計面板，核心是一張按 provider 和模型拆分的月度堆疊成本圖（USD）。
版本爲 0.1.0，依賴 zod ^3.23.8，可選 peerDependency react ^18.2.0，devDependencies 含 esbuild ^0.24.0 與 @types/react ^18.3.0。
核心功能¶
Overview 概覽。 顯示有用量記錄的會話數、四個 provider 上報的 token 分桶（uncached input、cache read、cache write、output）、總計，以及按匹配價格表估算的成本拆分。
月度成本圖。 按天、按模型的堆疊柱狀圖（USD），支持 < / > 月份導航、provider 與模型篩選，網格線刻度固定兩位小數，配彩色圖例。
按模型計價。 用量按精確的 provider/model 價格表匹配計價，內置一行 deepseek / deepseek-v4-flash，其餘回退到默認價格表。本版本中價格是固定常量。
Data honesty。 緩存投影早於 per-model 單元的會話（或部署本身就缺少這些單元）會被記爲 “no model data”，按默認價格表計價，並在界面上給出明確提示，不會靜默混進按模型的統計裏。
工作原理¶
bundle 分兩半。
Host 半部（src/host/）註冊兩個會話投影單元：modelUsage（按 provider/model 的會話總量）和 modelDailyUsage（按 provider/model/UTC 日的單元格），沿用了 @deepseek-ai/dsh-token-meter 的模式。註冊是冪等的——registry 會共享相同 stateVersion 的鍵，因此對已內置相同單元的部署（release 構建或源碼 checkout）都是安全的。
Client 半部（src/client/）通過 settings.section 貢獻一個「Token 用量」面板，讀取 session.list 投影列展示數據（零日誌加載），日單元格從 UTC 平移到本地時區顯示。
安裝與啓用¶
前置條件：已安裝 DeepSeek Harness（dsh CLI 或源碼 checkout 均可）。
方式一：npm 安裝。 README 將此方式標註爲 once published，撰寫本文時無法確認該包是否已在 npm 上架，如命令不可用請改用方式二：
dsh plugin --profile <name> add dsh-token-stats
dsh --profile <name> web
方式二：從倉庫安裝。 先克隆、構建，再把本地目錄加入對應 profile：
git clone https://github.com/qiushui0901/dsh-token-stats.git
cd dsh-token-stats
npm install && npm run build
dsh plugin --profile <name> add ./dsh-token-stats
dsh --profile <name> web
方式三：從 DSH 源碼 checkout 使用。 用 patch 文件直接掛載：
pnpm dsh web --patch /path/to/dsh-token-stats/cordis.patch.yml
使用此方式前，需要將 dsh-token-stats 鏈接進 checkout 的 node_modules，或安裝到 checkout 啓動時對應的 profile。
構建產物是 lib/host.js（自包含 Node 入口）和 lib/client.js（經 window.__ModuleLoader__.load 註冊的瀏覽器 bundle）。
經過上面的步驟，啓動後在瀏覽器打開 http://127.0.0.1:3080，進入 Settings → Token 用量 即可看到面板。
適用場景與注意¶
適合長期使用 DSH、需要按月覆盤 token 成本、關注各模型消耗佔比的開發者和團隊。
幾個使用前值得知道的限制：
1、模型數據向前填充。在 modelUsage / modelDailyUsage 投影存在之前運行的會話，在投影緩存行重寫之前無法歸屬到具體模型，這部分用量按默認價格表計價。
2、按天分桶基於 UTC。host 在 UTC 日下歸攏單元格，客戶端按整日時區偏移平移顯示，因此時區邊界附近的日單元格可能落在相鄰的本地日。
3、價格是編譯進 bundle 的固定常量，UI 中沒有編輯器。如果內置費率不符合你的情況，需要修改 src/client/usage-aggregate.ts 中的 DEFAULT_PRICES / DEFAULT_PRICE_TABLES 並重新構建。
最後提醒一點：插件以當前 dsh 進程的權限運行，安裝任何第三方插件前都應檢查其源碼與許可證。dsh-token-stats 採用 MIT 許可，倉庫地址見文末，可以自行審閱。
結尾¶
如果你的 DSH 部署缺一個按月、按模型看 token 成本的入口，dsh-token-stats 用不到一百行的安裝流程就能補上，且不侵入核心倉庫。
- 社區目錄頁：https://www.skillhub.cn/plugins/qiushui0901/dsh-token-stats
- GitHub 倉庫：https://github.com/qiushui0901/dsh-token-stats
社區目錄爲獨立站點，與 DeepSeek、幻方無官方從屬關係；插件本身基於 MIT 許可的 DeepSeek Harness 插件系統構建。
