前言¶
在 DSH 里切换不同厂商的模型时，余额往往分散在各家的控制台或账单 API 里，要确认「当前会话用的是哪家、还剩多少」通常得另开页面或自己记。下面介绍的 dsh-balance-card（npm 包名 @utmotc/dsh-balance-card）把各厂商 API 余额或订阅额度聚合到 dsh Web 左侧：一张贴在设置按钮上方的卡片，随当前会话所选模型切换厂商，并可在原地展开详情，不跳转页面。
这是什么¶
dsh-balance-card 由社区维护者 Utmotc 发布，分类为客户端插件（面向 dsh Web）。它解决的是：在当前对话所用模型背后，一眼看到该厂商的余额、额度或积分，并区分金额（元 / 美元等）与积分，避免把不同量纲混在同一套展示里。
读数经宿主解析 API Key 等凭据后，通过 GET /api/dsh.balance 提供给浏览器；设置走 GET/POST /api/dsh.balance.settings，与 Connection 同一套鉴权。密钥不写入插件磁盘，浏览器侧只收到数字。
核心功能¶
侧边栏卡片与详情¶
- 卡片显示当前会话所用模型对应厂商的余额：环形进度、百分比、各套餐进度条及最后更新时间。
- 切换模型，卡片跟着切换；点击卡片在原地展开详情面板，会话不离开当前页。
内置厂商与数据来源¶
插件通过各厂商官方账单接口或生态内其它插件的状态路由读数，主要包括：
| 类型 | 厂商 / 场景 | 说明 |
|---|---|---|
| API 余额 | DeepSeek、StepFun、Kimi Coding、OpenRouter、MiniMax、xAI/Grok | 各自官方 GET 接口；金额或额度按读数类型展示 |
| 积分 | WorkBuddy、Qoder | 不重复实现登录逻辑，读取 dsh-workbuddy-connect / dsh-qoder-connect 已发布的状态路由 |
| 订阅额度 | ChatGPT (Codex)、Claude、Grok (X Premium)、GitHub Copilot、Google Antigravity | 与 dsh-plugin-subscriptions 联动，展示订阅配额与重置时间等 |
另可在用户文件 $DSH_HOME/model-balance-providers.json（默认 ~/.dsh/model-balance-providers.json）中声明额外厂商或覆盖内置 endpoint，无需改插件代码。
没有 API 级账单的厂商（如部分仅控制台计费的路线）会显示「暂不支持」，有控制台链接时会给出链接。
单位与展示¶
- 金额用
¥/$等及「元 / 美元」等词；积分单独标「积分」；额度用次数等形式；无法辨认单位时显示「单位未知」，不强行当成人民币。 - 余额监测设置页可配置：显示位置（侧边栏卡片 / 输入框胶囊 / 两处 / 都不显示）、轮询间隔、告警阈值、单位写法、更新时间格式、千位分隔等；写入插件自有配置，不触发 loader 重建、无需重启 dsh。
安全与降级¶
- 构造上不要求 dsh 额外授权；某服务缺失时仅少显示一块，不阻止应用启动。
- WorkBuddy / Qoder / 订阅类读数在对应插件未安装、未登录或路由失败时，会显示「未安装」「未登录」「读取失败」等明确状态，而不是 silent 错误。
安装与启用¶
需要 dsh 0.1.7 或更新，Node 22.19+（或 24+），与 dsh 本体要求一致。当前 npm 发布版本为 1.4.0（MIT 许可证）。
方式一：终端安装（推荐）¶
在终端执行（资料原文命令）：
dsh plugin --profile web add @utmotc/dsh-balance-card
若使用带社区安装统计的 dsh1024 CLI，也可执行：
dsh1024 plugin --profile web add @utmotc/dsh-balance-card
安装会自动将包加入 $DSH_HOME/profiles/web、通过 dsh.bundle.patch 写入 dsh.profile.bundles 并应用 loader 补丁，从而自动激活。升级可在插件页更新，或执行：
dsh plugin --profile web add @utmotc/dsh-balance-card@latest
方式二：Web 插件页¶
在 dsh Web 侧边栏插件页的安装框中粘贴并确认：
- npm 包名（推荐）：
@utmotc/dsh-balance-card - 或 GitHub 归档：
https://github.com/Utmotc/dsh-balance-card/archive/refs/tags/v1.4.0.tar.gz
安装后在同一页面可开关插件。
典型用法¶
1. 配好凭据后随模型看余额¶
各厂商通过 dsh 凭据或环境变量解析，例如 DeepSeek 常用 DEEPSEEK_API_KEY（设置命名空间 llm-deepseek-api-key 或 llm-pi-ai），OpenRouter、MiniMax、xAI 等多在 llm-pi-ai 下配置。在 Web 里选好某厂商路由上的模型，侧边栏卡片应显示该厂商名称与读数；若失败，点开详情面板查看 HTTP 或解析错误信息。
2. 与 WorkBuddy / Qoder 联用¶
选中 workbuddy / workbuddy-ai 或 qoder / qoder-global 模型组时，需已安装并登录对应 connect 插件；本插件从环回状态路由读取积分，例如：
workbuddy→/plugins/dsh-workbuddy-connect/statusqoder-global→/plugins/dsh-qoder-connect/global/status
3. 自定义厂商（零代码）¶
- 确认厂商提供带 Bearer API Key 的账单
GET接口。 - 编辑
~/.dsh/model-balance-providers.json（或DSH_MODEL_BALANCE_CONFIG指向的文件），在providers下增加条目，例如：
{
"providers": {
"my-vendor": {
"name": "My Vendor",
"baseURL": "https://api.example.com",
"endpoint": "/v1/balance",
"keyEnv": "MY_VENDOR_API_KEY",
"response": { "type": "currency", "currency": "CNY", "balance": "data.balance" }
}
}
}
- 将
MY_VENDOR_API_KEY存入凭据或环境变量，重启 dsh（厂商列表按进程缓存），再选中该my-vendor路由上的模型验证侧边栏读数。
厂商 id 须与 harness 路由 id 一致；可用 aliases 声明别名。
4. 调整展示与轮询¶
打开 dsh Web 中的 余额监测 设置页，选择显示位置与轮询间隔、告警阈值等，保存后即可生效，无需重启。
适用场景与注意¶
适合：经常在 dsh Web 里切换多厂商模型、希望在不离开对话页的前提下核对 API 余额、订阅窗口或 WorkBuddy/Qoder 积分的开发者。
注意：
- 插件在当前 dsh 进程权限下运行，凭据由宿主解析；安装前建议阅读 GitHub 仓库 源码与 MIT 许可证，确认符合你的安全策略。
- 订阅类额度依赖 dsh-plugin-subscriptions 及相应登录/OAuth；未安装或未登录时会降级显示。
- 自定义
providers.json中若使用expr表达式，配置文件相当于受信代码，应保证仅本人可写。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-balance-card 把「当前模型对应厂商」的余额、额度或积分收到 Web 侧边栏一张卡里，并与其他 connect / subscriptions 插件分工协作，单位展示也做了区分。若你需要在 harness 里常驻看账，可按上文命令安装 @utmotc/dsh-balance-card，再在插件页或「余额监测」设置里按需开关与调参。
- 目录页：https://www.skillhub.cn/plugins/Utmotc/dsh-balance-card
- GitHub：https://github.com/Utmotc/dsh-balance-card
