前言¶

在 DSH Web GUI 裏使用多個 LLM provider 時，常見做法是分別打開各 provider 的查詢頁面查看餘額或配額。GPIOX/dsh-api-balance 是一個面向 DeepSeek Harness（DSH）Web GUI 的插件，把這些信息做成可拖動、可縮放的懸浮徽章。下面介紹它的功能、安裝方式和注意事項。

這是什麼¶

它是由 GPIOX 維護的 DSH 插件，包名爲 dsh-api-balance-badge，許可證爲 MIT。作用是在 DSH Web GUI 中懸浮顯示 LLM API 賬戶餘額或配額。

已覈實的 package.json 信息包括：

• 版本：1.6.6
• 包名：dsh-api-balance-badge
• peerDependencies 要求：@deepseek-ai/cordis ^4.0.1

核心功能¶

• 在 DSH Web GUI 中懸浮顯示 LLM API 賬戶餘額。
• 每個配置的 provider 一個徽章。
• 徽章可拖動，並可用右下角手柄從 70% 縮放到 250%。
• 採用磨砂玻璃/亞克力視覺：半透明中性色調、背景模糊、細邊框。
• 文字顏色根據徽章下方內容明暗自適應，約每 1.5 秒採樣一次。
• 支持 DeepSeek、Moonshot、OpenAI、OpenCode Go 和自定義 GET 餘額/配額端點。
• OpenCode Go 顯示滾動 5 小時、每週、每月配額，包含已用/剩餘百分比和重置倒計時。
• 點擊徽章會刷新所有徽章；數據默認每分鐘刷新，可配置到 30 秒。
• API key 保存在 DSH 憑據服務 ~/.dsh/.credentials.yaml，不發送到瀏覽器。
• Settings › API Balance 可管理 provider 列表、密鑰、餘額/配額詳情、徽章可見性和位置重置。
• 可作爲 dynamic plugin 通過 cordis_define 和 cordis_run 注入，無需構建或重啓。

安裝與啓用¶

先執行安裝命令，把插件加入 DSH 的 web profile：

dsh plugin --profile web add https://github.com/GPIOX/dsh-api-balance/archive/refs/heads/main.tar.gz

安裝後重啓 DSH，停止 dsh 進程後重新運行，例如：

dsh web

然後刷新頁面，打開 Settings › API Balance，選擇 provider 並保存密鑰。之後即可看到徽章。

如需卸載或回滾：

dsh plugin --profile web remove dsh-api-balance-badge

本地開發可添加本地路徑：

dsh plugin --profile web add link:/path/to/dsh-api-balance-badge

典型用法¶

已安裝插件¶

1、完成上面的安裝。

2、重啓 DSH 並刷新頁面。

3、打開 Settings › API Balance。

4、選擇 provider，粘貼 key 並保存。

5、在頁面中拖動或縮放徽章；點擊徽章可刷新所有徽章。

Dynamic plugin 快速啓用¶

也可以將插件作爲 dynamic plugin 注入當前 DSH Web GUI session：

1、調用 cordis_define，設置 kind: "new"，使用任意 3-6 字母前綴，並將 plugins/api-balance/host.js 與 plugins/api-balance/client.js 作爲 code.host / code.client 粘貼。

2、使用 cordis_run 激活返回的 Package，並在 run card 上點擊 Approve。

3、打開 Settings › API Balance，選擇 provider，粘貼 key 並保存。

注意：dynamic plugin 存在於進程內存而非磁盤，DSH 重啓後需要重新定義並激活。

適用場景與注意¶

適合使用 DSH Web GUI，並且需要同時查看多個 provider 餘額或 OpenCode Go 配額的使用者。

使用前注意：

• 插件以當前 DSH 進程權限運行，安裝前應檢查源碼與許可證；本插件許可證爲 MIT。
• 瀏覽器只能看到是否已配置 key，明文 API key 不會回傳到頁面。
• OpenAI 使用瀏覽器會話 token（sess-...），會話 token 會過期。
• 安裝命令寫入的是 DSH profile，卸載命令使用包名 dsh-api-balance-badge。
• dynamic plugin 不落在磁盤，重啓 DSH 後需要再次定義並激活。

結尾¶

GPIOX/dsh-api-balance 將 API 餘額/配額查看放在 DSH Web GUI 內，減少切換頁面和手動查詢的步驟。GitHub 地址：

https://github.com/GPIOX/dsh-api-balance