前言¶
DeepSeek Harness (DSH) 是一個本地運行的智能體開發環境。在使用本地模型調用 DeepSeek API 時，開發者通常需要追蹤具體的 Token 消耗量和賬戶餘額。現有的監控方式往往依賴第三方工具或手動計算，缺乏統一的後端記錄和可視化的實時狀態。
下面介紹的 dsh-deepseek-usage-monitor 插件專爲解決這一痛點設計。它運行在 DSH Host 進程中，負責記賬，同時通過 DSH Web 界面提供可視化的卡片，實時展示用量統計與餘額狀態。
核心功能¶
令牌用量記錄¶
插件在 Host 端監聽 DSH 的 session/event，通過 assistant/message 中的 TokenUsage 字段作爲主要數據源，同時也兼容 assistant/chunk 的備用數據。它會以 session:turn:step 爲鍵進行去重，確保同一個步驟不會重複計費。
統計邏輯自動處理兩種字段格式：DSH 的標準字段 (inputTokens, outputTokens 等) 以及 DeepSeek 原始響應字段 (prompt_tokens 等)。對於原始字段中缺失的 prompt_cache_hit_tokens，插件會自動通過 prompt_tokens - hit 補全。
統計數據按 模型 和 提供商 分組展示，並保留最近的會話記錄。所有數據持久化到本地 JSON 文件 (~/.deepseek-harness/deepseek-usage.)，重啓 DSH 後數據依然保留。
餘額查詢¶
插件會在後臺開啓定時任務，輪詢 DeepSeek 官方接口 GET /user/balance（默認間隔 60 秒）。查詢邏輯會自動解析並複用 DSH 配置中已有的 API Key，無需手動配置。如果在啓動後添加了新的 Key，下次輪詢時會自動生效，無需重啓進程。
Web 狀態卡片¶
安裝完成後，DSH Web 界面的右下角會出現一個 “Usage” 卡片。該卡片由 Web 端 (client.js) 渲染，通過輪詢 GET /plugins/deepseek-usage-monitor/state 接口獲取數據（默認間隔 5 秒，標籤頁隱藏時暫停）。
卡片支持以下交互：
* 拖拽與調整大小：拖動標題欄可移動卡片，拖動右下角手柄可調整大小。
* 展開/摺疊：默認摺疊，點擊 “+” 展開，”−” 摺疊。狀態保存在瀏覽器 localStorage 中。
* 刷新：點擊卡片上的 “Refresh” 按鈕可強制調用 ?refresh=1 接口立即更新余額。
* 多語言：卡片界面語言跟隨瀏覽器區域設置（如 zh-* 顯示中文）。
安裝與啓用¶
在安裝前，請確保環境滿足以下要求：
* Node.js >= 22.19
* pnpm
DSH 的插件通過 pnpm dlx 運行，無需全局安裝。請根據實際情況替換 0.1.1-rc.2 爲你當前使用的 DSH 版本號。
1、在任意目錄運行以下命令，將插件安裝到 DSH 的 Web Profile 中：
pnpm dlx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add dsh-deepseek-usage-monitor
該命令會自動將插件依賴添加到 ~/.dsh/profiles/web/node_modules，並將其加入到 dsh.profile.bundles 中，無需手動編輯 YAML 配置文件。
使用說明¶
安裝完成後，重啓 DSH Web Profile 並打開 Web 界面。右下角將出現 “Usage” 卡片。
- 查看數據：卡片展開後顯示總 Token 數、請求次數、緩存命中率、各模型/提供商的用量分組，以及 DeepSeek 賬戶餘額。
- 訪問數據接口：你可以通過 HTTP 接口獲取數據，例如：
GET http://localhost:PORT/plugins/deepseek-usage-monitor/state
添加 `?refresh=1` 參數可強制刷新余額。
- 重置統計：如果想清空本地歷史記錄，刪除
~/.deepseek-harness/deepseek-usage.文件並重啓 DSH 即可。
注意事項¶
- API 密鑰安全：插件的 API Key 僅存在於 DSH Host 進程內存中，絕不會發送到瀏覽器端。
- 版本依賴：確保 Node.js 版本不低於 22.19，否則插件無法運行。
- 數據隱私：持久化的 JSON 文件僅包含數字、分組名稱和時間戳，不會記錄提示詞或模型回覆內容。
總結¶
dsh-deepseek-usage-monitor 爲 DSH 用戶提供了一個輕量級的用量監控方案。它將記賬邏輯置於 Host 端，利用 DSH 的事件流保證準確性，並通過 Web 卡片提供直觀的實時反饋，適合需要在本地環境中精細化管理 DeepSeek API 成本的開發者。
- 插件目錄: dsh-deepseek-usage-monitor
- GitHub 倉庫: KamChiHei/dsh-deepseek-usage-monitor
