Balance Panel — DSH 的可擴展餘額/用量面板

前言¶

在使用 DeepSeek Harness (DSH) 進行智能體開發時，如果同時接入多個模型後端，切換 provider 後查看餘額或用量通常需要跳轉頁面或打開新標籤。Balance Panel 旨在解決這個問題。這是一個可擴展的餘額/用量面板，以浮動卡片的形式固定在 DSH Web UI 的右側邊緣。它根據當前會話使用的後端自動選擇顯示內容，同一時刻只顯示一張面板。

核心功能¶

浮動與自動隱藏：面板常駐右側邊緣。噹噹前會話的模型命中某個已接入的後端時，面板顯示；切換到未接入的 provider 時自動隱藏。
多後端支持：內置三種後端邏輯，適配不同的計費模式：
- OpenCode Go：適配訂閱配額，支持進度條和重置倒計時。
- Zhipu：適配按量計費的現金餘額。
- DeepSeek：適配按量計費的現金餘額。
可擴展架構：通過修改配置文件中的 BACKENDS 數組，可以添加新的供應商支持，無需修改客戶端代碼。

安裝與啓用¶

    bash install.sh

該腳本會執行 `npm pack` 並通過 `dsh plugin add` 安裝到默認的 web profile。

啓用面板：
- 打開 DSH Web UI。
- 進入 設置 -> 餘額面板。
- 開啓開關。
- 設置刷新間隔（可選：15/30/60/120s）。
升級方式：
- 先移除舊版本包（例如通過 pnpm --dir ~/.dsh/profiles/web remove @deepseek-ai/dsh-opencode-go-usage）。
- 運行 bash install.sh。
- 更新 dsh.profile.bundles 中的舊包名爲 @deepseek-ai/dsh-balance-panel。
- 重啓 DSH。

後端語義與展示¶

不同後端的數據展示邏輯不同：

OpenCode Go：顯示訂閱配額。包含三行數據：剩餘百分比、重置倒計時、進度條。顏色閾值：剩餘 ≤30% 爲橙色，≤10% 爲紅色。
Zhipu / DeepSeek：顯示按量計費現金餘額。包含純金額行：可用餘額（加粗）、累計充值、累計消費。贈送和凍結僅在非零時出現。不顯示進度條和重置倒計時。

擴展新供應商¶

在 lib/index.js 的 BACKENDS 數組中添加後端對象。主要邏輯包括：

匹配路由：實現 matchesProvider(id, node) 方法，在設置 providers 字典中認領路由。
數據解析：實現 resolvePanel(ctx, providerId, node) 方法，拉取上游數據並歸一化爲面板結構。
返回結構：返回包含 panel 對象的對象。panel.rows 定義行數據（支持 bar 進度條，僅配額語義使用）；panel.chip 定義摺疊徽章；panel.foot 定義底部註腳。

安全與緩存¶

服務端解析：API Key 僅在 DSH 服務端進程內解析，絕不發送到瀏覽器或寫入日誌。
獨立緩存：不同後端有獨立的緩存策略（OpenCode Go 爲 15s，其他爲 5min）。失敗時不緩存，下次輪詢重試。
路由防護：包含同源和 loopback 保護，跨站讀取請求返回 403。

適用場景與注意¶

此插件適合需要在 Web UI 實時監控多個 API 後端餘額和用量的開發者。安裝前請確保已閱讀源碼，並檢查許可證（MIT）是否滿足需求。