前言¶
用 DSH（DeepSeek Harness）Web GUI 接多家模型服务商时，查余额是个高频但麻烦的动作：要么登录各家的控制台，要么手动调一遍余额接口。账户一多，这个动作每天要重复好几次。
下面介绍的 dsh-balance 把这件事收进了 Web GUI：在页面右下角放一个可拖动的余额悬浮卡片，每 60 秒自动刷新，支持 DeepSeek / 硅基流动 / Moonshot / OpenRouter 四家的余额接口，并在插件设置页提供总开关。
这是什么¶
dsh-balance 是一个面向 DeepSeek Harness Web GUI（dsh-web-ui 插件生态）的客户端插件，仓库路径为 Mystery-God/dsh-balance，许可证为 MIT。package.json 显示包名为 @linxin666/dsh-balance、版本 0.1.2（包名与仓库所有者不一致，归属以仓库路径为准），engines 要求 node ^22.19.0 || >=24.0.0，peerDependencies 为 react ^18.2.0。
它解决的问题很单一：把模型账户余额常驻显示在 Web GUI 里，并且不把 API key 暴露给浏览器。
核心功能¶
悬浮卡片¶
悬浮卡片出现在页面右下角，可以拖动。内容分三块：
- 总余额，大字显示；
- 充值 / 赠送明细和更新时间；
- 三个操作按钮：
⟳手动刷新、–收起成小胶囊、×关闭。关闭后会留一枚¥胶囊，随时可以唤回。
刷新与缓存¶
插件每 60 秒自动查询一次余额，查询结果在 host 侧缓存 30 秒，不会频繁打服务商接口。需要立即看最新数值时，用卡片上的 ⟳ 手动刷新。
总开关¶
「设置 → 插件 → 模型余额悬浮窗」里有一个「显示余额悬浮窗」总开关，设置持久化到 ~/.dsh/balance/settings.json。设置页与悬浮窗共享同一份内存 store，开关切换即时生效，不用重启。
密钥安全¶
余额查询全部在 host 端发 fetch，API key 有两种提供方式：
- 在设置页直接填写，存于本地
~/.dsh/balance/settings.json，接口只回传脱敏预览； - 经 credentials 服务解析，查找顺序为：环境变量 →
~/.dsh/.credentials.yaml→.env。
两种方式下，key 都不会下发到浏览器。
多服务商¶
插件按配置的 baseURL 域名自动识别服务商，各家的余额接口如下：
| 服务商 | 接口路径 |
|---|---|
| DeepSeek | /user/balance |
| 硅基流动 | /v1/user/info |
| Moonshot | /v1/users/me/balance |
| OpenRouter | /api/v1/credits |
其他域名的请求会明确提示不支持，不做猜测式的兼容。
实现与安全围栏¶
插件零运行时依赖：host 半体纯 Node，浏览器半体纯 React，无需构建，lib/ 目录就是发布产物。API 路由带 loopback + same-origin 围栏，即使部署在 LAN 暴露的环境，这些接口也不会对外提供服务。
安装与启用¶
通过 dsh CLI 安装到 web profile：
dsh plugin --profile web add github:Mystery-God/dsh-balance
也可以不走路由安装，直接改 profile 的 package.json，往 deps 和 bundles 里加条目后执行 pnpm install。
安装后重启 dsh web，进入「设置 → 插件 → 模型余额悬浮窗」完成配置：填 API key（或走 credentials 服务解析），打开「显示余额悬浮窗」总开关，右下角就会出现悬浮卡片。
工作原理¶
仓库里三个关键文件对应插件的三个部分：
lib/index.js — host 半体：读写 ~/.dsh/balance/settings.json，
提供 /api/dsh-balance/* 路由（设置读写、余额查询），并向 agent 公告
lib/client.js — 浏览器半体：设置页（settings.plugins.tab，总开关 + 余额预览）、
悬浮卡片（shell.overlay）、60s 轮询
cordis.patch.yml — bundle patch：把插件行注入 profile 组合
本仓库没有 TypeScript，也没有打包器：src/ 是手写源码，lib/ 是发布产物。lib/ 需要提交，因为 dsh 插件市场校验安装包时要求入口文件存在。
开发与测试¶
改完源码后，先做构建，再做测试：
node scripts/build.mjs # 把 src/ 复制为 lib/，无编译步骤
node scripts/test.mjs # host 路由冒烟测试：mock 余额接口，使用临时 DSH_HOME
适用场景与注意¶
适合的人：在 DSH Web GUI 里同时接了 DeepSeek / 硅基流动 / Moonshot / OpenRouter 中一家或多家，想随时看到余额，又不想把 key 暴露在浏览器端的开发者。
几点注意：
- 插件只支持上述四家的余额接口，其他域名会明确提示不支持，接入前先确认自己的服务商在列表内。
- 插件以当前 dsh 进程的权限运行，可以读写
~/.dsh/下的文件、在 host 端发起网络请求。安装前建议先检查源码和许可证（本项目为 MIT）。 - Node 版本需满足
^22.19.0 || >=24.0.0。
结尾¶
dsh-balance 只做一件事，但做得完整：余额常驻可见、刷新有节奏、密钥不下发浏览器、设置即改即生效，是 DSH「一切皆插件」理念下一个典型的小而完整的客户端插件。
- 社区插件目录页：https://www.skillhub.cn/plugins/Mystery-God/dsh-balance
- GitHub 仓库：https://github.com/Mystery-God/dsh-balance
目录页为社区独立站点，与 DeepSeek / 幻方无官方从属关系。
