前言¶

用 DSH 做日常会话时，切换模型或服务商之后，常常想知道账户里还剩多少额度。已有做法是另开浏览器、登录对应服务商的控制台查看，一次切换就是一次中断。dsh-balance 把这个动作收进输入框：余额以小段文本显示在 composer 的模型席位旁，选中模型后即可看到。

DSH 的理念是「一切皆插件」，这个需求也正好由一个插件承担。下面介绍它的实现、安装方式和注意事项。

这是什么¶

@kkbsgg/dsh-balance 是一个 DeepSeek Harness（DSH）插件，由 kkbsgg 维护，当前版本 0.2.0，许可证为 MIT。它做的事情一句话可以说完：在选中模型及其 reasoning effort 之后，把当前所选模型服务商的账户余额，以小文本形式显示在输入框模型席位旁。

实现方式¶

插件分为 host 与 client 两半，各管一段。

Host half：一条回环路由¶

lib/index.js 是一个 Cordis 插件，负责在 webserver 上挂载一条回环 HTTP 路由：

GET /dsh-balance/balance?provider=<route>

路由收到请求后，先通过标准 credentials service 解析所选 provider 自己的 API key：DeepSeek 官方路由使用 llm-deepseek 配置段，自定义或其他路由使用 llm-pi-ai 的 providers 表。密钥只在 host 进程内解析和使用，不跨越线路边界。

拿到密钥后，先请求 DeepSeek 风格的 GET <baseURL>/user/balance，失败时回退到 OpenAI 风格的 GET <baseURL>/v1/dashboard/billing/credit_grants。

Client half：输入框右侧的席位¶

client/client.js 是 web 客户端插件，向 conversation.input.right 槽位注册一个 seat，位置紧邻模型选择器。它订阅活动会话的 modelDirectories，把选中的 provider 传给上面的路由。

渲染有一条门槛：只有当选中具有非空 id 的模型后才显示；选择被清空时直接隐藏文本，而不是保留一份过期的余额。刷新策略是每 60 秒轮询一次，点击余额文本可立即刷新。

安装与启用¶

从源码安装（任意 DSH profile）¶

包声明了 dsh.bundle manifest，仓库可被解析后，用标准插件命令安装：

dsh plugin add @kkbsgg/dsh-balance

手动安装（打包版 DSH Desktop）¶

前提是包能从 profile 的 node_modules 解析。满足后，在 profile patch（$DSH_HOME/profiles//cordis.patch.yml）中添加一行 loader 配置：

- insert:
    - id: balance
      name: 'dsh-balance'

然后重启应用，让 loader 把新行组合进去。之后对客户端 bundle 的修改，可以通过 client HMR 通道热更新。

打包版 DSH Desktop 中，包位于应用解包后的 node_modules，并以 junction 链接到 $DSH_HOME/profiles/node_modules，profile loader 因此能像解析内置插件一样解析它。

有一个已知注意点：该包是手工安装进 pnpm 管理的 hoisted store 的，未来 profile 内的 pnpm install 可能将其剪除。如果通过插件市场安装后余额文本消失，需要重建这条链接。

响应格式与自测¶

路由返回 JSON。成功时返回余额信息：

{ "ok": true, "isAvailable": true, "balanceInfos": [{ "currency": "CNY", "totalBalance": "110.00", "grantedBalance": "10.00", "toppedUpBalance": "100.00" }], "fetchedAt": "2026-01-01T00:00:00.000Z" }

失败时给出错误码，例如未配置密钥：

{ "ok": false, "code": "no-api-key", "message": "no credential configured for DEEPSEEK_API_KEY" }

仓库自带的 smoke 测试覆盖 host half，运行方式：

node test/smoke.test.mjs

适用场景与注意¶

适合的使用者：在 DeepSeek 官方路由与自定义服务商之间切换、希望随时掌握余额、又不想为此离开会话界面的 DSH 用户。

几点注意：

1、插件以当前 dsh 进程的权限运行。安装前应先检查源码与许可证（MIT），确认可以接受再装。

2、声明了三个 peerDependencies：@deepseek-ai/cordis ^4.0.1、@deepseek-ai/dsh-credentials ^0.1.0-rc.7、@deepseek-ai/schemastery ^3.18.1。

3、仓库是 source of truth：当前安装在 DSH Desktop 应用 node_modules 里的实时副本以它为准，改代码后需要重新同步到已安装副本，或者从本仓库安装并重建 profile 链接。

小结¶

经过上面的步骤，dsh-balance 会在输入框模型席位旁常驻一段小文本，把「查余额」从一次浏览器登录压缩成一瞥。插件源码与文档见 GitHub：https://github.com/kkbsgg/dsh-balance