dsh-usage-stats：DSH 側邊欄 Token 用量統計與額度監控

前言¶

在 DeepSeek Harness (DSH) 的插件生態中，開發者往往需要實時追蹤 Token 的消耗情況，並查看各類服務的餘額額度。dsh-usage-stats 插件將用量統計與額度監控掛載於 Web 側邊欄底部，點擊即可打開詳情面板，按模型、會話、日期三個維度展示數據。

插件介紹¶

這是一個 DSH Web 插件，用於統計 Token 使用量並展示餘額。它掛載於側邊欄底部展示今日用量，點擊後打開詳情面板進行多維度的數據查看。

核心功能¶

側邊欄今日統計
在側邊欄底部展示今日統計，支持寬列與 56px rail 自適應展示。
詳情面板
面板按概覽、日期、會話、模型、設置五個標籤頁組織信息。
模型統計重定向
在設置頁配置規則，將某個供應商的某個模型的用量算到另一個供應商的某個模型名下，模型頁按規則歸併展示，賬本原始數據保持不變。
額度監控
- OpenCode Go：展示滾動 5 小時、本週、本月三檔剩餘額度。
- DeepSeek：展示多幣種餘額。
- Z.ai：展示滾動 5 小時與本週百分比，以及每月 Web 搜索次數。
會話 ID 徽標
在會話標題旁顯示 session-id 徽標，懸停可複製。默認開啓，可在設置頁關閉。

安裝與啓用¶

使用官方命令安裝插件：

dsh plugin --profile web add @xfqz86/dsh-usage-stats

卸載命令：

dsh plugin --profile web remove @xfqz86/dsh-usage-stats

配置與使用¶

設置位置¶

設置位於詳情面板的“設置”標籤頁，配置保存在 DSH 該 profile 的配置文件 ~/.dsh/profiles/<profile>/cordis.patch.yml 中。換瀏覽器或換設備登錄同一臺 DSH 時，偏好設置保持一致。

基礎配置¶

啓用額度監控（如 DeepSeek 餘額、OpenCode Go 額度、Z.ai 額度）與側邊欄展示。額度抓取間隔默認爲 5 分鐘，下限爲 3 分鐘。

在配置文件中只修改需要調整的字段，例如將 Go 額度抓取間隔改爲 10 分鐘：

- id: usage-stats
  name: '@xfqz86/dsh-usage-stats'
  config:
    goFetchMinutes: 10

憑據配置¶

需在 DSH 憑據中心配置對應 Key：
* OpenCode Go：OPENCODE_GO_API_KEY
* DeepSeek：DEEPSEEK_API_KEY（兼容 DEEPSEEK_APIKEY、DEEPSEEK_API_TOKEN、DEEPSEEK_TOKEN）
* Z.ai：ZAI_CODING_CN_API_KEY 或 ZAI_API_KEY（前者優先）

會話 ID 徽標¶

默認在會話標題旁顯示會話 ID 徽標。若需關閉，可在詳情面板的“設置”標籤頁中關閉。

數據存儲與統計口徑¶

數據存儲¶

數據存儲爲 SQLite，位於 $DSH_HOME/storages/dsh-usage-stats/ledger.sqlite。首次啓動會自動掃描歷史會話並導入，後續隨事件實時增量更新，重啓後可從賬本恢復。

統計口徑¶

數據源：攜帶 data.usage 的記錄，包括對話調用 assistant/message 和壓縮上下文的調用 compaction/summary。
計算方式：
- total = input + output + cacheRead + cacheWrite
- reasoning 單列
維度劃分：
- 按模型維度取 provider 與 model（對話調用取 message.source，壓縮調用取事件頂層）。
- 按會話維度記錄標題、工作目錄、創建與最近活躍時間。
- 按本地自然日劃分日期。
不含內容：不含會話標題自動生成等輔助調用的用量（僅記錄請求，不記錄返回的用量）。

生態與鏈接¶

GitHub 倉庫：https://github.com/xfqz86/dsh-usage-stats
社區目錄：https://www.skillhub.cn/plugins/xfqz86/dsh-usage-stats
許可證：MIT

注意：該插件以當前 DSH 進程的權限運行，安裝前請檢查源碼與許可證。