dsh-deepseek-usage：DeepSeek API 用量與餘額查詢插件

DeepSeek Harness (DSH) 的開發者在使用 API 進行開發或調試時，需要實時掌握賬戶餘額以及本機的 token 消耗情況。由於 DeepSeek 官方未公開詳細的用量查詢接口，手動統計本機會話日誌不僅繁瑣，還容易出錯。下面介紹一款由社區維護的插件，通過命令行接口同時解決餘額查詢與用量彙總的問題。

插件簡介¶

該插件名爲 dsh-deepseek-usage，由開發者 kane-le 維護，遵循 MIT 許可證。它是一個 DSH 插件，旨在通過 /usage 命令提供賬戶餘額的實時查詢，並彙總本機 DSH 會話日誌中的 token 用量。

核心功能¶

該插件主要包含以下能力：

實時查詢官方賬戶餘額：通過調用 GET https://api.deepseek.com/user/balance 接口，獲取賬戶可用狀態、各幣種總餘額 / 充值餘額 / 贈送餘額。
彙總本機 DSH 會話日誌：解析本機會話日誌文件，統計輸入 tokens、輸出 tokens、緩存讀取 tokens 和推理 tokens。
增量掃描：支持增量掃描會話日誌，首次掃描後，後續查詢僅讀取新增內容，節省時間。
自動處理壓縮日誌：支持自動解析 zstd 壓縮的日誌文件（session.jsonl.zstd），無需外部解壓工具。

安裝與啓用¶

插件通過插件管理器安裝。請確保已安裝 DeepSeek Harness。

將插件源碼下載到本地，例如保存爲 /path/to/dsh-deepseek-usage。
在終端中執行以下命令添加插件：

dsh plugin --profile web add /path/to/dsh-deepseek-usage

安裝完成後，重啓 dsh web 進程，插件會自動加入 profile 的 bundles。

典型用法¶

安裝並重啓後，可在 Web 界面或命令行中調用以下命令：

命令	說明
`/usage`	查看完整報告：本機累計 token 用量 + 實時餘額
`/usage balance`	僅查詢餘額，不進行日誌掃描
`/usage rescan`	強制重新掃描全部會話日誌後輸出完整報告

示例輸出：

DeepSeek API 用量與餘額
================================
[用量] 本機累計（會話日誌 + 實時跟蹤）
  輸入 tokens:      196,267
  輸出 tokens:      107,874
  緩存讀取 tokens:  6,773,172
  推理 tokens:      54,537
  會話數: 9 | 最近活動: 2026-08-24 18:11:51 UTC
  ...
[餘額] 實時查詢
  賬戶可用: 是
  CNY 總餘額 2.04 | 充值 2.04 | 贈送 0.00

技術細節¶

API Key 解析順序¶

插件會按照以下順序嘗試獲取 API Key：

官方 credentials 服務（Web 界面「設置 → 模型」寫入的配置）。
環境變量 DEEPSEEK_API_KEY。
本地配置文件 $DSH_HOME/.credentials.yaml 中的 DEEPSEEK_API_KEY 行。

接口與日誌路徑¶

接口地址：默認爲 https://api.deepseek.com，可通過環境變量 DEEPSEEK_BASE_URL 覆蓋。
日誌路徑：$DSH_HOME/sessions/*/*/session.jsonl[.zstd]。
數據存儲：用量賬本保存在 $DSH_HOME/storages/deepseek-usage.json。

數據與冪等性¶

去重機制：用量數據按 會話:回合:步驟 鍵進行去重合並。實時事件與日誌回掃共用同一鍵空間，不會重複計數。
增量掃描：日誌掃描基於文件大小和修改時間（mtime），首次全量掃描後，後續命令僅讀取新增內容。
解碼方式：日誌文件爲 zstd 多幀格式，插件使用 node:zlib 進行解碼，無需依賴外部工具。

適用場景與注意¶

適用對象：使用 DeepSeek Harness 進行開發或調試的用戶，需要監控 API 消耗。
數據來源說明：用量數據完全來自本機會話日誌。由於官方 API 未公開用量查詢接口，該插件通過解析日誌實現統計。
權限注意：插件以當前 dsh 進程權限運行，安裝前請檢查源碼與許可證。