dsh-usage-blance：DeepSeek Harness Web 界面的用量與餘額監控插件

DeepSeek Harness (DSH) 採用插件化架構，其 Web 界面允許通過自定義插件擴展功能。在本地調試或開發智能體時，頻繁切換到網頁後臺查看 API 消費和餘額不夠高效。dsh-usage-blance 插件通過將監控數據嵌入到聊天對話框輸入框上方的 conversation.input.dock 插槽中，實現了在對話過程中直接查看 DeepSeek API 的用量與餘額。

功能介紹¶

該插件在聊天界面的輸入框上方展示五項核心指標：本月消費、本月日均、昨日消費、今日消費以及賬戶餘額。

點擊任意一行賬單數據，會打開一個控制面板。該面板支持以下配置：
* 玻璃擬態調節：支持實時調節透明度、模糊度和飽和度。
* 位置切換：賬單條可固定在輸入框上方或下方，設置會持久化保存。
* 雙列布局：左側配置 userToken，右側調節主題與位置。
* 餘額預警：可設置餘額閾值，當餘額低於該閾值時，餘額數值會顯示爲紅色感嘆號，並出現充值按鈕。

數據每 60 秒自動刷新，每行數據在出現錯誤（如 Key 缺失、Token 過期、網絡故障）時會顯示錯誤狀態提示。界面顏色會跟隨 DSH 應用本身的主題色（--dsw-* tokens）。

安裝與啓用¶

安裝前需確保已安裝 DSH CLI 和 pnpm。

克隆倉庫並安裝：

    git clone https://github.com/zhou-yihang/dsh-usage-blance.git
    cd dsh-usage-blance
    dsh plugin --profile web add .

重啓 DSH Web 服務以加載插件：

    dsh web

打開 Web 界面並刷新頁面，賬單條將出現在對話框下方。

配置說明¶

插件需要兩個關鍵配置項來獲取不同維度的數據。

1. 獲取 userToken（用於用量數據）¶

用量數據（今日、昨日、本月消費）需要使用平臺會話令牌。點擊賬單行打開控制面板後：
1. 登錄 platform.deepseek.com。
2. 打開瀏覽器開發者工具（F12）。
3. 在 Console 中執行以下命令獲取 token：

    JSON.parse(localStorage.getItem('userToken')).value

將獲取的字符串粘貼到控制面板輸入框中，點擊“保存”。配置將存儲在 $DSH_HOME/storages/dsh-usage-blance.json。

2. 使用 DEEPSEEK_API_KEY（用於餘額數據）¶

餘額數據直接從官方接口獲取。插件會自動讀取環境變量或 ~/.dsh/.credentials.yaml 中的 DEEPSEEK_API_KEY。如果未配置，餘額行會提示 Key 缺失，但用量數據仍可正常顯示。

數據源與隱私¶

數據來源：
- 餘額：官方公開接口 GET https://api.deepseek.com/user/balance。
- 用量：平臺儀表板接口 GET https://platform.deepseek.com/api/v0/usage/by_api_key/cost（需 userToken）。
時間窗口：錨定北京時間 (UTC+8)。
隱私與安全：API Key 和 userToken 僅在本地路由傳輸，不會離開機器。所有數據請求由 DSH 進程發起，用戶偏好設置持久化存儲於 localStorage 和 $DSH_HOME/storages/dsh-usage-blance。

總結¶

dsh-usage-blance 通過將官方接口的數據聚合展示在 DSH Web 界面的輸入框上方，解決了本地開發時監控 API 成本的需求。插件遵循 MIT 許可證，代碼託管在 GitHub，適合需要在本地頻繁查看 DeepSeek API 使用情況的開發者使用。