前言¶
使用 DeepSeek Harness（DSH）跑 web 會話時，切換不同 provider 後，餘額或訂閱用量往往需要到對應供應商頁面查看。dsh-balance 是 GeekRicardo 維護的 DSH web 插件，MIT 許可。它把當前 provider 的餘額/用量展示到輸入框下方狀態欄，並按 provider 即時切換，減少手工查詢。
這是什麼¶
dsh-balance 是一個 DSH web 插件，核心能力是：
- 在輸入框下方狀態欄展示當前供應商的餘額/用量；
- 按當前 provider 即時切換；
- 2 秒輪詢更新；
- 餘額/用量 5 分鐘緩存；
- 緩存優先展示，切會話不空白。
插件從 ~/.dsh/.credentials.yaml 讀取對應供應商密鑰，由 Host 端註冊 /dsh-balance/status HTTP route，Client 端輪詢該 route 並渲染狀態。判斷當前 provider 使用 agentDefaultModel.currentSelection()。
package.json 聲明 react 爲可選 peerDependency，版本要求 ^18.2.0。
支持的供應商¶
下面是當前支持列表。其他 provider 不顯示，返回 null。
| provider | 展示內容 | 密鑰 | 接口 |
|---|---|---|---|
deepseek / deepseek-official / deepseek-vision |
DeepSeek 官方餘額 + 本會話花費估算 | DEEPSEEK_API_KEY |
GET api.deepseek.com/user/balance |
kimi-coding |
Kimi Coding 訂閱用量 | KIMI_CODING_API_KEY，兼容 KIMI_CODE_API_KEY / KIMI_API_KEY |
GET api.kimi.com/coding/v1/usages |
opencode-go |
OpenCode Go 訂閱用量 | OPENCODE_GO_API_KEY，兼容 OPENCODE_API_KEY |
GET opencode.ai/zen/go/v1/usage |
zai-coding-cn / zai |
智譜 GLM Coding Plan 訂閱用量 | ZAI_CODING_CN_API_KEY / ZAI_API_KEY |
GET open.bigmodel.cn 或 api.z.ai/api/monitor/usage/quota/limit |
minimax-cn / minimax |
MiniMax Coding Plan 訂閱用量 | MINIMAX_CN_API_KEY / MINIMAX_API_KEY |
GET api.minimaxi.com 或 api.minimax.io/v1/api/openplatform/coding_plan/remains |
openrouter |
OpenRouter 餘額 | OPENROUTER_API_KEY |
GET openrouter.ai/api/v1/credits |
openai-codex |
OpenAI Codex 訂閱用量 | OPENAI_CODEX_ACCESS_TOKEN，可選 OPENAI_CODEX_ACCOUNT_ID |
GET chatgpt.com/backend-api/wham/usage |
即時性與緩存¶
下面幾點決定了狀態欄的更新節奏：
- Client 每 2 秒輪詢一次
/dsh-balance/status，因此切換模型或切換對話後，狀態欄最多 2 秒更新。 - Host 端按 provider 緩存餘額/用量，同一 provider 下每 5 分鐘重新查詢一次。
- Client 會把上一次成功讀數緩存在內存和
localStorage。切換會話或刷新頁面時，先渲染緩存，再後臺請求最新數據。 - 跨會話緩存會把 DeepSeek「本會話花費」清零，但餘額/用量照舊展示。
- 當前 provider 的判斷依賴
agentDefaultModel.currentSelection()，不依賴最近一次請求的模型。
安裝與啓用¶
前置條件¶
安裝前需要滿足：
- DeepSeek Harness 已初始化 web profile，即
~/.dsh/profiles/web存在； Node.js >= 20可用；pnpm可用；- 對應供應商密鑰已配置在
~/.dsh/.credentials.yaml。
官方安裝命令¶
下面是一條命令安裝：
curl -fsSL https://raw.githubusercontent.com/GeekRicardo/dsh-balance/main/install.sh | bash
安裝腳本可先 --dry-run 預覽。
腳本會做以下事情：
- 在
~/.dsh/profiles/web/package.json寫入依賴"dsh-balance": "github:GeekRicardo/dsh-balance"； - 把
dsh-balance追加進dsh.profile.bundles； - 執行
cd ~/.dsh/profiles/web && pnpm install； - 校驗 bundles 已註冊，並提示重啓 DSH。
重啓 DSH¶
如果用 pm2 託管，可以執行：
pm2 restart dsh-web
否則使用你原來的 DSH 啓動方式重啓。
重啓後硬刷新頁面，狀態欄生效。
典型用法¶
- 在
~/.dsh/.credentials.yaml配置對應供應商密鑰。 - 安裝插件並重啓 DSH。
- 在 DSH web 頁面切換 provider、模型或對話。
- 觀察輸入框下方狀態欄：
- 切換模型/切換對話後，狀態欄最多 2 秒更新；
- 同一 provider 下餘額/用量每 5 分鐘重新查詢一次；
- DeepSeek 本會話花費按 session 分別累計；
- DeepSeek 本會話花費是插件加載後開始累計，重啓清零，不持久化。
計費與用量口徑¶
DeepSeek¶
DeepSeek 官方 API 不返回金額，只返回 token 數。插件中的金額是 token 數 × 單價 的估算，不是賬單。
單價來自 models.dev，按 USD/百萬 token 計算，按模型前綴匹配。拉取失敗時回落到內置單價。匯率固定爲 7.2。
Kimi Coding¶
Kimi Coding 用量僅當 provider 爲 kimi-coding，即 api.kimi.com/coding 時展示。
OpenCode Go¶
OpenCode Go 用量僅當 provider 爲 opencode-go，即 opencode.ai/zen/go 時展示。
該接口要求同時攜帶兩個請求頭：
Authorization: Bearer <token>
x-api-key <key>
卸載¶
卸載時按下面步驟處理：
# 1. 從 ~/.dsh/profiles/web/package.json 的 dsh.profile.bundles 移除 "dsh-balance"
# 2. 移除 dependencies 裏的 "dsh-balance"
# 3. cd ~/.dsh/profiles/web && pnpm install
# 4. 重啓 DSH
故障排查¶
| 現象 | 原因與處理 |
|---|---|
| 輸入框下方什麼都不顯示 | 當前 provider 不在支持列表，或 Host 尚未加載；檢查 provider 列表並重啓 DSH |
| 顯示「餘額不可用」 | 對應供應商密鑰未配置，或接口認證失敗；檢查 ~/.dsh/.credentials.yaml 中對應 key 是否存在且有效 |
| 切換模型後讀數沒有立即變 | 輪詢間隔爲 2 秒；如果仍不更新，確認當前選擇已保存，currentSelection() 已生效 |
| 餘額數字一直不變 | 同一 provider 下餘額/用量每 5 分鐘重新查詢一次，屬於緩存預期 |
安全提示¶
dsh-balance 會在當前 DSH 進程權限下運行，並讀取 ~/.dsh/.credentials.yaml 中的供應商密鑰。安裝前建議先檢查源碼與 MIT 許可證，確認來源可信。
相關鏈接¶
- GitHub：https://github.com/GeekRicardo/dsh-balance
- 目錄頁：https://www.skillhub.cn/plugins/GeekRicardo/dsh-balance（來自插件線索，已覈實事實中標記爲不確定）
