前言¶
在 DeepSeek Harness（DSH）裏跑智能體，模型調用會分散在多個會話、多個 provider 路由上。若只靠各家控制台或賬單頁，很難和「本機實際發生了多少次調用、各模型各用了多少 token」對齊；本地也沒有統一視圖把用量、預估費用和賬戶餘額放在同一處。
下面介紹社區插件 token-usage-statistic（維護者 zhiwuli0228）。它作爲 客戶端 類 DSH 插件，從 DSH 會話事件採樣 token，寫入可重放賬本，並在 DSH Desktop 與 DSH Web 的側邊欄面板展示用量、賬戶與導出。Desktop 與 Web 共用同一份 Web 客戶端包和同一套 Host 邏輯，只有一份實現。
插件目錄頁：skillhub.cn/plugins/zhiwuli0228/token-usage-statistic。源碼與完整說明見 GitHub 倉庫（當前 npm 包版本 1.0.2，MIT 許可證）。社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係；該插件尚未收錄官方插件庫，在 Discover / 市場搜不到時按包名安裝即可。
這是什麼¶
token-usage-statistic 是 DeepSeek Harness 插件：統計本機所有模型調用的 token 用量與按事件時間估算的費用，支持歷史回填、賬戶餘額/訂閱額度、日/月預算與無憑據導出，並在側邊欄面板中呈現。
Host 側監聽 assistant/message、assistant/chunk、compaction/summary 等會話事件；Client 側通過 sidebar.panellist 與 main (key=token-usage) 注入「模型用量統計」面板。賬本默認落在 %DSH_HOME%\token-usage-statistic\usage.jsonl，費用不落盤，重放時按價格規則重算。
核心功能¶
用量採樣與歷史回填¶
- 三源採樣：
assistant/message、assistant/chunk、compaction/summary；同一turn:step的後續樣本會替換先前樣本。 - 啓動後增量掃描
sessionPersistence；賬本中每個會話的最高 seq 作爲游標，fork 從inheritedEventCount起讀。
費用估算¶
每個樣本按自己的事件時間匹配歷史價格規則（DeepSeek 峯谷時段、上海時區）；未定價時 fail-closed。內置 DeepSeek 官方 USD 價（每 1M tokens），覆蓋 deepseek-v4-flash / deepseek-v4-pro 的歷史分段；只有 pricing.providers 內的路由會被計價，第三方網關默認未定價。
賬戶與預算¶
自動發現三類來源：DSH Desktop 賬戶（deepseekAccount）、官方 DeepSeek API Key（llm-deepseek）、以及 llm-pi-ai provider 的公開餘額接口。accounts.monitors 可配置私有監控端點。憑據僅在 Host 內通過 ctx.credentials 解析，不落盤到導出內容。
日/月預算通過 budgets.daily / budgets.monthly 與 budgets.currency 配置；達到 80% 爲預警，100% 爲超限；費用不完整時不拿部分和比較。
面板與導出¶
側欄三個標籤：用量 / 賬戶 / 導出。時間範圍支持今天 / 7 天 / 30 天 / 全部；圖表指標可在 Tokens、調用次數、預估費用之間切換（1.0.2 起切換控件在圖表標題旁，並顯示「當前指標 · 合計」摘要）。
只讀 HTTP API 僅接受迴環 GET/HEAD，例如：
| 方法 | 路徑 | 說明 |
|---|---|---|
| GET | /token-usage-statistic/api/summary |
用量、費用、預算、回填狀態 |
| GET | /token-usage-statistic/api/export/daily.csv |
按日 provider/model CSV |
| GET | /token-usage-statistic/api/export.json |
版本化 JSON，無憑據 |
CSV 導出帶 UTF-8 BOM 與公式注入防護，不含提示詞、回覆或密鑰。
安裝與啓用¶
Desktop 與 Web 使用不同 profile（desktop / web），兩端都要用時各執行一次。Desktop 安裝前先完全退出 App（含托盤圖標）。本地安裝腳本需要 Node.js ≥ 20；只走圖形界面安裝則不需要。
DSH Desktop（不需要 PATH 上有 dsh）：
npm run plugin:install -- desktop # 鏈接當前倉庫
npm run plugin:install -- desktop --npm # 安裝 npm 上已發佈的包
DSH Web：
dsh plugin --profile web add token-usage-statistic
dsh web
Web 走 npm 安裝的 dsh，需要 PATH 上有 pnpm；Desktop 自帶的 dsh 已內置 pnpm。
圖形界面（Desktop）：插件 / Plugins → 輸入 token-usage-statistic → 安裝 → 重啓 Desktop。
裝完後側欄應出現「模型用量統計」。若入口未出現，可查看 %DSH_HOME%\token-usage-statistic\activation.json 中的路由註冊結果。
兼容性概覽：
| 運行環境 | 支持 | 面板 |
|---|---|---|
| DSH Desktop | ✅ | 側邊欄「模型用量統計」 |
DSH Web (dsh web) |
✅ | 同一側邊欄面板 |
| DSH CLI / headless | ⚠️ 僅採集 | 無側邊欄；賬本仍寫入 |
典型用法¶
- 打開側欄 →「模型用量統計」。
- 在 用量 頁選擇時間範圍與圖表指標；點擊每日柱子可查看當天會話、模型與工作區名稱。
- 在 賬戶 頁查看餘額或訂閱額度，必要時點「刷新賬戶」立即觸發 Host 刷新。
- 在 導出 頁或通過迴環 API 拉取 CSV/JSON，用於離線分析或備份（仍不含憑據）。
最小配置示例（刷新間隔與日/月預算）：
- override:
- id: token-usage-statistic
config:
refreshMs: 15000
budgets:
currency: USD
daily: 5
monthly: 50
完整字段（dataFile、sessionLimit、backfill、modelAliases、pricing、accounts.monitors 等）見倉庫 README 中的配置參考。
適用場景與注意¶
適合誰：長期在 DSH Desktop 或 Web 上開發、調試智能體，需要本機維度的 token 彙總、DeepSeek 相關路由的預估費用，以及把用量與賬戶/預算放在同一側邊欄的開發者。
運行權限：插件以當前 DSH 進程權限運行，會讀取會話持久化、寫入 %DSH_HOME% 下賬本與賬戶快照，並在 Host 內解析憑據以查詢餘額。安裝前應自行審閱 源碼 與 MIT 許可證，確認符合你的安全與合規要求。
侷限：CLI / headless 場景僅採集、無面板；第三方網關默認未納入內置計價；賬戶查詢有 HTTPS、超時與響應大小邊界，無公開接口的 provider 不會猜測性請求。
結尾¶
token-usage-statistic 把 DSH 會話事件變成可重放的用量賬本，並在 Desktop / Web 側邊欄統一展示 token、預估費用、賬戶與導出——適合需要「本機真相來源」而非只看雲端賬單的使用方式。
- 目錄頁：https://www.skillhub.cn/plugins/zhiwuli0228/token-usage-statistic
- GitHub：https://github.com/zhiwuli0228/token-usage-statistic
