DeepSeek Harness Token 用量統計插件

DeepSeek Harness（DSH）的設計理念是「一切皆插件」。在智能體開發與調試過程中，對會話中 input、output 以及 cache-read token 的統計需求很常見。dsh-token-usage 插件旨在解決這一需求，它通過讀取本地會話日誌，聚合 Token 用量數據，並提供 Web 側邊欄面板與 Agent 工具兩種訪問方式。

插件簡介¶

這是一個由 joyiok 維護的 Token 用量統計插件。它的核心價值在於“權威計數”：不依賴估算，而是直接讀取 DSH 的會話日誌文件，對每個 (turn, step) 只計一次，並內置多幀 zstd 解碼能力，無需外部依賴。

核心功能¶

該插件主要提供以下能力：

1. Web 側邊欄：在 Web 客戶端底部新增 Tokens 按鈕，點擊可查看全部累計、今日以及每個會話的 input、output、cache-read token 詳情。
2. Agent 工具：在 headless 或 Web 會話中，通過註冊的 token_usage 工具獲取統計數據，支持通過 scope 參數限定查詢範圍。
3. 權威計數：讀取 $DSH_HOME/sessions/**/session.jsonl(.zstd)，利用內置解碼器解析數據，確保統計口徑準確。

安裝與啓用¶

安裝插件需要將插件目錄添加到 DSH 的 profile 中。請根據你的使用場景（Web 或 Headless）執行對應命令。

cd /home/joy/Documents
dsh plugin --profile web add /home/joy/Documents/token-usage-dsh-plugin
dsh plugin --profile headless add /home/joy/Documents/token-usage-dsh-plugin

安裝完成後，重啓 dsh web。客戶端會掃描與 Typert 清單，重啓後配置纔會生效。你可以通過 dsh --profile web --dump-config 驗證，輸出中應出現 dsh-token-usage 配置段。

使用方法¶

Web 側邊欄¶

在任意活躍會話頁面，左下角會出現 Tokens 圖標。點擊後，面板將展示以下內容：

• 彙總視圖：全部累計 / 今日的輸入、輸出、輸入+輸出、緩存讀取、含緩存總計以及 LLM steps。
• 會話明細表：列出各會話的標題、模型、輸入/輸出/緩存讀取 Token 數以及最近活動時間。

Agent 工具¶

在對話中直接詢問 Token 用量，Agent 會調用 token_usage 工具並返回結果。

示例：

用戶：我一共用了多少 token？
Agent：調用 token_usage(scope: "all") 後回答

工具參數：

配置¶

插件支持在 profile 的 cordis.patch.yml 中進行覆蓋配置。注意，這裏需要覆蓋整行 config。

- id: token-usage
  config:
    cacheTtlMs: 8000        # 聚合緩存毫秒數
    maxToolSessions: 20     # token_usage 工具最多返回的會話數

若需禁用插件，可在配置中添加：

- id: token-usage
  disabled: true

技術細節與說明¶

• 日誌路徑：插件讀取 $DSH_HOME/sessions/**/session.l(.zstd)。
• 計算公式：totalTokens = inputTokens + outputTokens。含緩存的總計 totalWithCache 會額外計入 cacheReadTokens 和 cacheWriteTokens。
• 解碼機制：插件內置多幀 zstd 解碼。若內置解碼失敗且系統 PATH 中存在 zstd CLI，會自動回退調用該命令行工具。

參考資料¶

• 插件目錄頁
• GitHub 倉庫