前言¶

用 DSH 做日常任務時，token 花在哪裏並不直觀。會話日誌裏雖然帶着每次模型調用 provider 上報的用量，但數據分散在所有持久化會話中——包括 subagent 會話。想知道「最近 7 天某個模型用了多少」，只能手工翻日誌或臨時寫腳本聚合，插件安裝之前的歷史數據更是難以覆蓋。

dsh-plugin-token-usage 把這件事做成了插件：按 (date, provider, model) 分桶聚合，一條 /usage 命令出報表，Web GUI 側也有對應面板。下面介紹它的定位、設計與用法。

這是什麼¶

dsh-plugin-token-usage 由 lovedheart 維護，定位是「QwenPaw 風格的 DSH 跨會話 token 用量統計」：把所有持久化會話（含 subagent 會話）中每次模型調用的 provider 上報用量，聚合到 (date, provider, model) 桶裏，通過 /usage 命令與 Web GUI 的 Token 用量面板展示。當前版本 0.2.0，許可證爲 MIT。

核心設計¶

會話日誌即事實來源¶

插件直接讀取 ~/.dsh/sessions 下的會話日誌作爲持久事實來源。這意味着兩點：

1、插件安裝之前的歷史數據也能統計；
2、寫入側不需要任何額外記賬，正常使用 DSH 即可，聚合由插件增量掃描完成。

防重複計數與冪等¶

統計口徑的處理規則如下：

1、已落盤的 assistant/message.usage 優先採用；
2、沒有產生消息的失敗步驟，回退到最後一個 streaming usage chunk（在 turn/end 時落盤）；
3、每個會話文件維護一個持久化水位（{hiSeq, framesIngested}），保證增量掃描在跨重啓、崩潰恢復重編碼的場景下依然冪等，不會重複累計。

零運行時依賴¶

運行時只使用 Cordis 的 ctx API 與 Node 22 內置的 node:zlib（zstd）。@deepseek-ai/cordis ^4.0.1 以 optional peer dependency 的形式聲明。

安裝與啓用¶

README 沒有提供官方安裝命令。插件是 out-of-tree 模塊，通過 profile patch 掛載，與 telegram、thinking-mode 插件是同一模式。步驟如下：

1、將 GitHub 倉庫克隆到本地；
2、編輯 ~/.dsh/profiles/web/cordis.patch.yml，添加一段 insert 行：

- insert:
    - id: token-usage
      name: '/path/to/dsh-plugin-token-usage/lib/index.js'
      config:
        defaultDays: 30
        backfillIntervalSec: 30
        enableCommand: true
        verbose: true

name 指向倉庫內 lib/index.js 的絕對路徑，config 四項來自 README 示例，可按需調整。

另外一個細節：commands 是可選依賴（通過 optional child fiber 消費），因此插件在沒有命令註冊的程序集中也能加載——只是不註冊交互命令，存儲照常工作。

用法：/usage 命令¶

查詢入口是單一命令 /usage，支持時間範圍與模型過濾：

/usage                 # 最近 30 天（defaultDays 可配置）
/usage 7d              # 最近 7 天
/usage 7d qwen3.8      # 最近 7 天，模型過濾（provider/model 子串匹配）
/usage qwen3.6         # 默認時間範圍，模型過濾

時間範圍不寫時取 defaultDays；過濾參數對 provider/model 字符串做子串匹配。

README 給出的示例輸出，按總量、按模型、按天三段展示：

📊 Token Usage  2026-07-17 → 2026-08-16

Total: 906.9M tokens · 4954 calls
  input 473.3M · output 3.4M · cache read 430.1M

By model:
  sglang/Qwen3.8-27B  —  719.4M tokens · 3320 calls
      in 337.7M · out 2.8M · cacheR 378.9M
  sglang/Qwen3.6-27B  —  187.4M tokens · 1634 calls
      in 135.6M · out 669900 · cacheR 51.2M

By day:
  2026-08-13  42.6M tokens · 481 calls
  2026-08-14  195.7M tokens · 1587 calls
  2026-08-15  380.5M tokens · 1513 calls
  2026-08-16  288.1M tokens · 1373 calls

數字以縮寫展示：達到百萬級顯示 M（如 1.2M），達到十億級顯示 B（如 1.5B），以下爲普通整數；統一保留一位小數，末尾 .0 去掉。

配置項¶

Web GUI 面板¶

package.json 提供 ./client 導出，dsh.client 字段聲明 platform 爲 web，並注入 @deepseek-ai/dsh-client-runtime 與 @deepseek-ai/dsh-client-locale，對應 Web GUI 中的 Token 用量面板。

開發與測試¶

代碼結構：

• src/frames.js — zstd 幀掃描器（對應 DSH 的 scanZstdFrames）
• src/store.js — 分桶聚合、去重、持久化、summarize
• src/backfill.js — 增量遍歷會話日誌 + listSessionFiles
• src/render.js — fmtTokens、renderUsageReport、parseUsageArgs
• src/index.js — 插件入口（name/inject/Config/apply）
• test/ — 單元與 harness 測試

倉庫自帶的開發命令：

npm install        # 爲 harness 測試安裝 cordis peer
npm test           # node --test test/*.test.mjs
npm run prepare    # 從 src/ 同步 lib/

npm run prepare 會把 src/*.js 複製到 lib/。由於掛載路徑指向 lib/index.js，修改源碼後需要同步一次。

適用場景與注意事項¶

適合的場景：DSH 會話多、常跑 subagent，想按天、按模型看用量分佈；或者想在統計口徑裏包含插件安裝之前的歷史數據。

使用前注意：

1、插件以當前 dsh 進程權限運行，可讀寫 sessionsRoot 與 stateFile 指向的路徑（默認 ~/.dsh/sessions 與 ~/.dsh/token-usage.json），啓用前確認目錄權限符合預期；
2、安裝前建議自行檢查源碼與許可證（當前爲 MIT）；
3、統計對象是 provider 上報的用量，來自會話日誌本身，不需要改動任何寫路徑配置。

結尾¶

dsh-plugin-token-usage 的思路很剋制：不引入新依賴、不改動寫路徑，把會話日誌當作唯一事實來源，做好去重與冪等，然後用一條 /usage 命令交付結果。如果你在 DSH 上有多會話用量的統計需求，它值得一看。

• GitHub：https://github.com/lovedheart/dsh-plugin-token-usage
• 社區目錄收錄頁：https://www.skillhub.cn/plugins/lovedheart/dsh-plugin-token-usage

其中社區目錄爲獨立站點，與 DeepSeek / 幻方無官方從屬關係。