dsh-model-surplus

dsh-model-surplus

在会话标题右侧显示当前模型的用量 / 套餐额度 / 账户余额 —— 用到哪个模型，就显示哪一份。

它做什么

• 会话标题右侧的小组件，按当前选中的模型决定显示哪一份，切模型立即显示或隐藏。
• OpenCode Go：滚动 / 周 / 月三个窗口的百分比，外加所选模型的月度上限（如 上限 $60）。
• DeepSeek：账户余额（总 / 赠送 / 充值）；余额不可用时显示「余额不足」。
• Command Code：5 小时 / 周两个窗口的已用与上限，以及账户剩余额度。
• 三个分区各自独立上报：只配一个密钥时另外两半照常工作，缺的那半显示原因（no key / usage n/a）。

安装

• 用 DSH Ready GUI（推荐）：插件随 GUI 内置，打开 GUI → 设置窗口 →「第三方插件」勾选模型余量，装完按提示刷新页面（它带页面半边）。

• 其它 DSH 宿主（dsh web / CLI）—— 任选一条：

  # 推荐：直接从 GitHub 装
  dsh plugin --profile web add github:itchenshi/dsh-model-surplus
  
  # 备选：从本仓库 Release 的 tarball 装
  dsh plugin --profile web add https://github.com/itchenshi/dsh-model-surplus/releases/download/v0.4.6/dsh-model-surplus-0.4.6.tgz
  

  两条命令装到的都是这个仓库的完整内容（含 cordis.patch.yml），装完不需要额外配置。

本包还不在 npm 上（registry.npmjs.org 查无此包），只能用上面两种方式装。

使用

装好、重启引擎、刷新页面后，小组件出现在会话标题右侧，每 60 秒向宿主路由取一次数据。

上游请求都在宿主端发出，密钥按引用从引擎的凭据服务读取（先看路由自己声明的 apiKeyEnv，再看分区的默认引用名）；密钥不会下发到浏览器。

分区	默认凭据引用
OpenCode Go	OPENCODE_GO_API_KEY
Command Code	COMMANDCODE_GOAT_API_KEY
DeepSeek	DEEPSEEK_API_KEY

配置

cordis.patch.yml 里 id: model-usage 这一行的 config，全部可选：

键	默认	说明
enabled	true	false 时整个插件直接返回
opencodeGo.baseUrl	https://opencode.ai/zen/go/v1	上游根地址
opencodeGo.apiKeyRef	OPENCODE_GO_API_KEY	凭据引用名
opencodeGo.providers	[opencode-go, opencode]	视为 OpenCode Go 的路由
deepseek.baseUrl	https://api.deepseek.com	上游根地址
deepseek.apiKeyRef	DEEPSEEK_API_KEY	凭据引用名
deepseek.providers	[deepseek-official]	视为 DeepSeek 的路由
commandcode.baseUrl	https://api.commandcode.ai	额度接口根地址；写聊天地址 .../provider/v1 也认
commandcode.apiKeyRef	COMMANDCODE_GOAT_API_KEY	凭据引用名
commandcode.providers	[commandcode-goat, commandcode]	视为 Command Code 的路由

顶层直接写 baseUrl / apiKeyRef / providers 仍按 opencodeGo 分区读（插件早期只有 OpenCode Go）。

兼容性

• 需要 DSH >= 0.1.5-rc.2；清单里 0.1.5-rc.2 与 0.2.0-rc.2 标为 compatible。
• Node >= 20。
• 更早的引擎版本没有测试过；三个分区各自独立降级。

常见问题

看不到小组件？ 只有当前选中的模型属于受跟踪路由时才出现；自定义路由名要加进对应分区的 providers。

显示 no key？ 那个分区没取到密钥。宿主启动时会打 [model-usage] active (opencode-go: providers=opencode-go|opencode key=OPENCODE_GO_API_KEY; ...)，日志里没有它说明插件没加载。

数据多久更新一次？ 每个分区缓存 120 秒（失败后 30 秒内不重试）。单模型月度上限取自公开文档页 https://opencode.ai/docs/zh-cn/go/（不需要密钥），缓存在 <DSH_HOME>/logs/model-surplus-limits.json，每 24 小时刷新一次，抓取失败时回退到缓存、再回退到内置表（日志：[model-usage] limits refreshed from docs (...) 或 limits refresh failed (...)）。

百分比和上限为什么对不上？ 用量百分比是账户级的（上游接口忽略单模型参数），月度上限是所选模型的。

开发

node --check lib/index.js
npm test        # node tests/test.mjs：本地行为测试（不联网、不需要引擎）

tests/e2e.cjs 是针对真实引擎 + 浏览器的集成检查，需要跑着的 profile，所以不在 npm test 里。

许可

MIT