前言¶
使用 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（来自插件线索，已核实事实中标记为不确定）
