前言¶

在 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