dsh-token-stats: DeepSeek Harness Token 用量統計插件

前言¶

DeepSeek Harness（DSH）採用插件化架構，旨在爲智能體開發提供靈活的運行環境。在開發或調試過程中，精確統計 Token 消耗、監控緩存命中情況以及分析不同時間段的調用趨勢是必要的。雖然 DSH 提供了基礎的計量能力，但在需要聚合歷史數據、查看多維度折線圖或關注緩存效率時，往往缺乏現成的可視化方案。

dsh-token-stats 插件旨在解決這一問題。它通過讀取 DSH 的 Session 日誌，聚合全部會話的 Token 使用情況，並在本地生成可視化的統計報表。

插件信息¶

名稱：dsh-token-stats
維護者：IZRINO
類別：聯網工具
許可證：MIT

核心功能¶

全會話統計：統計全部會話的 Token 消耗與調用次數，不按 workspace 過濾。
多維聚合：支持按小時、天、周、月四種粒度聚合數據。
可視化圖表：生成 SVG 折線圖，同時展示輸入、緩存讀、緩存寫、輸出和總 Token。
緩存分析：支持緩存命中率計算。
本地化：所有數據存儲在本地，不涉及雲端傳輸。
歷史回溯：支持對歷史會話進行自動回填。

安裝與啓用¶

需要安裝一個可用的 dsh web profile，並使用 dsh plugin 命令。

將插件代碼拉取到本地目錄，或使用 Git 地址。
執行安裝命令：

dsh plugin --profile web add /home/izrino/code/dsh-token-stats

重啓 dsh web，打開設置面板，找到「Token 統計」頁面。

配置¶

在 DSH 的 profile 配置文件 cordis.patch.yml 中，找到 token-stats 插件行，添加或修改 config 字段。注意不要重複添加插件行。

- insert:
    - id: token-stats
      name: dsh-token-stats
      config:
        timezone: Asia/Shanghai
        weekStart: monday
        retainDays: 365
        dataDir: ''
      inject:
        - webServer
        - sessions
        - sessionPersistence

配置項	默認值	說明
`dataDir`	`''`	緩存目錄。空值使用 `$DSH_HOME/storages/dsh-token-stats`；支持絕對路徑或相對路徑。
`timezone`	`system`	天/周/月統計的時區。`system` 爲宿主機時區，也可指定 IANA 名稱（如 `UTC`）。
`weekStart`	`monday`	周統計的起始日。
`retainDays`	`365`	小時桶數據保留的天數，範圍 7-3650。

配置錯誤會導致插件加載失敗。

架構與指標¶

插件不監聽實時流，而是直接讀取持久化的 Session 日誌作爲真源。對於流式輸出中的 Usage chunk，插件會將其與最終 assistant/message 的 Usage 進行替換，確保數據口徑與官方 dsh-token-meter 一致。

指標定義¶

inputTokens：未緩存的輸入 Token。
outputTokens：模型輸出 Token。
cacheReadTokens / cacheWriteTokens：緩存讀 / 寫 Token。
totalTokens：上述四項之和，不包含 reasoning Token。
calls：最終採用的 Usage 樣本數。
cacheHitRate：緩存命中率。計算公式爲 cacheReadTokens / (inputTokens + cacheReadTokens + cacheWriteTokens)。無 prompt token 時返回 null。

Host API¶

插件提供了一組 HTTP 接口用於查詢數據。所有接口僅接受來自 127.0.0.1 的 GET 請求。

接口列表¶

/api/token-stats/series：獲取折線圖數據。
/api/token-stats/summary：獲取範圍彙總數據。
/api/token-stats/breakdown：按模型或供應商分組統計。
/api/token-stats/health：查詢插件健康狀態。

API 參數與示例¶

以 series 接口爲例：

curl 'http://127.0.0.1:3080/api/token-stats/series?granularity=day&metric=totalTokens'

參數說明：
* granularity：hour | day | week | month。
* metric：統計指標。
* fromMs / toMs：時間範圍（毫秒）。
* timezone：可選時區。

注意事項¶

數據落盤時機：緩存數據僅在 API 請求、實時事件防抖以及 session/flush 操作時寫入磁盤，非實時刷新。
DSH 版本狀態：DSH 目前處於 pre-release 階段，插件契約隨版本變化，本插件基於 0.1.0-rc.x 實現。
顯示限制：設置頁僅展示彙總數據，不保存原始調用明細。
時區處理：天/周/月統計按配置時區歸桶。DST 地區的小時桶可能跨越兩個本地日期，按 UTC 小時的本地起始歸屬。
安全性：API 僅允許 Loopback 訪問。

結語¶

dsh-token-stats 提供了一套輕量級、本地化的 Token 統計方案，適合需要深入分析調用成本和緩存效率的開發者。通過 SVG 圖表和聚合 API，可以快速定位異常調用或優化緩存策略。

GitHub：https://github.com/IZRINO/dsh-token-stats
目錄頁：https://www.skillhub.cn/plugins/IZRINO/dsh-token-stats