前言¶
DeepSeek Harness（DSH）的插件化架構允許開發者根據需要擴展功能。在使用 DeepSeek API 進行開發或部署智能體時，實時掌握賬戶餘額、Token 消耗量以及預估成本是控制成本和保障服務連續性的基礎。dsh-deepseek-usage 是由 yyb16yyb-hub 維護的插件，它通過 Web UI Dock 和模型工具，爲 DSH 提供了實時的用量監控能力。
核心功能¶
該插件主要解決 DeepSeek API 的用量與成本監控問題，具體能力包括：
- 賬戶餘額與多 Key 聚合：插件會定期輪詢 DeepSeek 的
/user/balance接口，默認每 30 秒一次。它支持聚合多個 API Key 的餘額，顯示總餘額、已用餘額及充值情況。 - 實時用量統計：通過
llm/stream流水線追蹤請求，提供輸入/輸出/緩存讀寫/推理 Token 統計。支持三種時間窗口：總計、今日、最近 60 秒，並包含緩存命中率。 - 成本估算：基於內置的
deepseek-chat和deepseek-reasoner定價表（可通過配置覆蓋）計算成本。支持平峯定價策略，可配置非高峯時段的折扣。 - Web UI Dock：在對話編輯器下方提供懸浮顯示，實時展示餘額、今日請求數、Token 數量和預估成本，支持自動刷新和手動刷新。
- 低餘額提醒與阻斷：當餘額低於閾值時，Dock 界面會變色（琥珀色/紅色）並觸發瀏覽器通知。可配置在餘額過低時阻斷 LLM 請求。
- 設置面板：提供完整的配置編輯器，支持修改閾值、輪詢間隔、定價表和阻斷策略。面板內包含歷史熱力圖、30 天柱狀圖以及 CSV 導出功能。
- 模型工具：提供
deepseek_usage模型工具，允許 Agent 在對話中主動查詢餘額和用量摘要。
安裝與啓用¶
安裝該插件需通過官方安裝命令執行。由於依賴 pnpm >= 10，首次安裝時可能需要構建授權。
1、執行安裝命令：
dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage
2、處理首次安裝的構建授權問題：
如果安裝時提示 pnpm >= 10 拒絕運行 prepare 腳本，需將包名添加到對應 profile 的 pnpm-workspace.yaml 文件中，或者使用特定的 commit SHA 進行安裝以獲得可重現的構建結果。
3、重啓服務：
安裝完成後，必須重啓 dsh web 服務，客戶端模塊表會在啓動時掃描並加載該插件。
配置說明¶
插件通過以下順序解析 API Key：
1. 插件配置文件中的 apiKey。
2. DSH 的憑證層（ctx.credentials），優先讀取環境變量，然後是 ~/.dsh/.credentials.yaml、項目 .env 和用戶 .env。Web 設置中配置的 DeepSeek Key 會自動寫入 ~/.dsh/.credentials.yaml。
3. 註冊的 llm-deepseek 設置中的 apiKey。
若需覆蓋默認配置，可編輯 profile 的 cordis.patch.yml 文件。關鍵配置項包括：
* pollIntervalMs：餘額輪詢間隔（毫秒，最小 5000）。
* alertThreshold：低餘額告警閾值。
* blockOnLowBalance：是否在餘額不足時阻斷請求。
* offPeakHours：非高峯時段的小時數列表。
* offPeakDiscount：非高峯折扣比例。
* pricing：自定義各模型的輸入、輸出及緩存讀寫價格。
使用示例¶
1、通過模型工具查詢：
在對話中調用模型工具 deepseek_usage。
* 無參數：查詢所有窗口的餘額和用量摘要。
* 參數 scope：指定 total、today 或 rolling（最近 60 秒）。
2、通過 Web UI 查看與配置：
啓動 dsh web 後，在對話編輯器下方即可看到實時用量 Dock。點擊側邊欄的“DeepSeek usage”設置面板，可以查看詳細的歷史圖表、編輯配置或導出 CSV 數據。
注意事項¶
- 首次安裝：如前所述，
pnpm >= 10環境下首次安裝可能需要額外配置pnpm-workspace.yaml。 - 成本估算：插件顯示的成本是基於常見公開定價的估算，並非官方實時賬單。建議定期覈對官方定價表。
- 安全性：API Key 僅存儲在主機端，不會發送到瀏覽器，也不會通過 Web UI 編輯器接受或持久化存儲。
- 瀏覽器通知：瀏覽器通知權限需要手動授予，插件本身不會主動彈窗請求。
- 數據持久化：每日曆史數據持久化在
~/.dsh/deepseek-usage/usage.json文件中。
總結¶
dsh-deepseek-usage 適合需要在 DeepSeek Harness 環境中精細化控制 API 成本和監控調用狀態的開發者。通過 Dock 實時反饋和設置面板的深度分析，它能夠有效提升開發與運維效率。
