前言¶

用 DSH（DeepSeek Harness）跑智能體，token 是最直接的成本信號：某段時間用了多少、緩存讀寫了多少、哪個 provider 和 model 消耗最大，都需要一本能持久保存、隨時查詢的賬。DSH 內置了 usage accumulator 和對應的用量頁面，滿足基本查看沒有問題；但如果你想把服務商上報的四類用量分開記賬、按本地日統計活動，或者在自己的插件裏讀取這些數據，就需要一個獨立的統計組件。

下面介紹的 Mu-scorpio/token-usage-counter 就是這樣一個插件。

這是什麼¶

它的定位一句話：爲 DeepSeek Harness 提供持久化的、服務商上報的 token 用量統計，支持累計、每日、按會話和按模型查看。

• 維護者：Mu-scorpio
• npm 包名：dsh-token-usage-counter，當前版本 0.4.0
• 許可證：MIT（README 與 package.json 均爲 MIT）
• 兼容環境：Node.js 22.13.0 或更新版本；DSH 0.1.2-alpha.3 至 0.1.2-alpha.5；Profile：web

核心功能¶

插件提供的能力如下：

• 分桶統計：將服務商上報的未緩存輸入、緩存讀取、緩存寫入、輸出四類用量分開保存；
• 持久化總量：數據存儲在插件專有的 dsh-token-usage-counter 設置命名空間；
• 多視圖：提供全局、會話、provider/model 三類彙總；
• 每日活動：按本地日統計 token 總量與調用次數；
• 內置設置頁：自帶 Web 設置視圖和熱力圖；
• 安全計數：僅在成功完成錨點（completion anchor）之後才計入用量；
• 交互命令：命令服務掛載時註冊 /tokens；
• API：提供 ctx.tokenUsageCounter（getSummary / getSession / getModel / formatSummary）。

計數規則¶

統計是否可信取決於計數規則。插件監聽持久化的會話事件流，規則如下：

1、assistant/message.usage 只計一次；
2、compaction/summary.usage 計爲一次 provider 調用；
3、僅有 usage 的 assistant/chunk 會先暫存，等到匹配的 assistant/message 到達再入賬；
4、chunk 與最終消息描述同一輪次和步驟時，以最終值替換早先的採樣；
5、失敗請求、重試與 fork seed 歷史不會重複計數。

前兩條決定入賬粒度，後三條避免流式採樣和重試帶來的重複計數；再配合「僅在成功完成錨點之後才計入用量」的策略，統計口徑是比較剋制的。

安裝與啓用¶

先確認運行環境滿足上面的兼容性要求，再把已發佈的 Bundle 安裝進 web profile：

dsh plugin --profile web add -w --config.auto-install-peers=false dsh-token-usage-counter
dsh web

第一條命令把 dsh-token-usage-counter 安裝到 web profile，第二條啓動 dsh web。經過上面的步驟，插件即可隨 dsh web 一起運行。

需要注意，這個 Bundle 是增量式的：它只掛載插件自己的 token-usage-counter 條目，DSH 內置的 usage accumulator 和用量頁面保持啓用，二者並存。

升級注意¶

0.4.0 把持久化從共享的 usage-stats 命名空間遷移到插件專有的 dsh-token-usage-counter 命名空間。由於共享命名空間屬於內置插件，0.3.x 的既有總量不會被靜默遷移，升級後新計數器從一份獨立快照開始。如果你還在用 0.3.x 且在意舊累計數據，升級前先確認這一點。

本地開發¶

如果要在本地改這個插件，先在倉庫 checkout 內完成構建：

npm install --ignore-scripts --legacy-peer-deps --no-package-lock
npm run build
npm run verify

構建生成的 host 與 client bundle 提交在 lib 目錄下。

調試時用下面的命令把源碼疊加進 dsh web，不替換內置組件：

dsh web --patch ./cordis.yml

也可以手動組合，只添加插件自己的條目：

- insert:
    - id: token-usage-counter
      name: './src/index.ts'

典型用法¶

交互命令¶

命令服務掛載時，插件會註冊 /tokens 命令，在會話中調用即可查看統計。

API¶

其他插件可以通過 ctx.tokenUsageCounter 讀取數據：

ctx.tokenUsageCounter.getSummary()
ctx.tokenUsageCounter.getSession(sessionId)
ctx.tokenUsageCounter.getModel(provider, model)
ctx.tokenUsageCounter.formatSummary()

四個方法分別對應全局彙總、按 sessionId 查會話用量、按 provider 和 model 查模型用量，以及格式化後的摘要文本。

適用場景與注意¶

適合的場景：

• 需要按四類口徑（未緩存輸入、緩存讀取、緩存寫入、輸出）覈算成本；
• 需要按本地日回看 token 總量與調用次數，或藉助設置頁的熱力圖觀察活動分佈；
• 想在自己的插件裏通過 ctx.tokenUsageCounter 消費用量數據做進一步處理。

使用前注意：

• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。本項目源碼公開在 GitHub，許可證爲 MIT；
• 逐版本驗證結果與一次性 profile 證據記錄在 docs/VERIFICATION.md，選擇版本前可先查閱；
• 從 0.3.x 升級到 0.4.0 後舊總量不會自動遷移，處理方式見上文。

小結¶

token-usage-counter 做的事很專注：把服務商上報的四類 token 用量分開、持久化地記下來，並提供全局、每日、會話、模型四個視角查詢，還能通過 API 被其他插件複用。如果你的 DSH 工作流需要一份可信的用量賬本，可以用上面的命令直接安裝試用。

• GitHub：https://github.com/Mu-scorpio/token-usage-counter
• npm：https://www.npmjs.com/package/dsh-token-usage-counter
• 社區目錄頁：https://www.skillhub.cn/plugins/Mu-scorpio/token-usage-counter （該目錄爲社區獨立維護，與 DeepSeek / 幻方無官方從屬關係）