Preface¶

When using DSH for daily conversations, after switching models or service providers, you often want to know how much quota is left in your account. The existing method is to open a separate browser, log in to the corresponding provider’s console to check, which is an interruption every time you switch. dsh-balance incorporates this action into the input box: the balance is displayed as a short text snippet next to the model seat in the composer, and it becomes visible after selecting a model.

DSH’s philosophy is “everything is a plugin,” and this requirement is perfectly handled by a plugin. Below is an introduction to its implementation, installation method, and precautions.

What is it¶

@kkbsgg/dsh-balance is a DeepSeek Harness (DSH) plugin maintained by kkbsgg, current version 0.2.0, license is MIT. It can be summed up in one sentence: when a model and its reasoning effort are selected, it displays the current selected model provider’s account balance as small text next to the model seat in the input box.

Implementation¶

The plugin is split into a host and a client half, each managing a segment.

Host half：一条回环路由¶

lib/index.js is a Cordis plugin responsible for mounting a loopback HTTP route on the webserver:

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

Upon receiving the request, the route first parses the selected provider’s own API key via the standard credentials service: DeepSeek’s official route uses the llm-deepseek config section, while custom or other routes use the llm-pi-ai providers table. The key is only parsed and used within the host process and does not cross the boundary of the connection.

After obtaining the key, it first requests the DeepSeek style GET <baseURL>/user/balance, falling back to the OpenAI style GET <baseURL>/v1/dashboard/billing/credit_grants upon failure.

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

client/client.js is the web client plugin, registering a seat at the conversation.input.right slot, located right next to the model selector. It subscribes to the active session’s modelDirectories and passes the selected provider to the route above.

There is a rendering threshold: it only displays when a model with a non-empty ID is selected; when the selection is cleared, the text is hidden directly instead of keeping a stale balance. The refresh strategy is to poll every 60 seconds, and clicking the balance text immediately refreshes it.

Installation and Enablement¶

From source (any DSH profile)¶

The package declares a dsh.bundle manifest. Once the repository can be resolved, it can be installed using the standard plugin command:

dsh plugin add @kkbsgg/dsh-balance

Manual install (packaged DSH Desktop)¶

Prerequisite is that the package can be resolved from the profile’s node_modules. Once satisfied, add a loader configuration line in the profile patch ($DSH_HOME/profiles/<profile>/cordis.patch.yml):

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

Then restart the application to let the loader incorporate the new line. Subsequent modifications to the client bundle can be hot-reloaded via the client HMR channel.

In the packaged version of DSH Desktop, the package is located in the app’s unpacked node_modules and linked via a junction to $DSH_HOME/profiles/node_modules, so the profile loader can resolve it just like it resolves built-in plugins.

There is a known note: this package was manually installed into the pnpm-managed hoisted store, and a future pnpm install inside the profile might remove it. If the balance text disappears after installing via the plugin marketplace, you need to rebuild this link.

Response Format and Self-Test¶

The route returns JSON. On success, it returns balance information:

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

On failure, it provides an error code, for example, when no API key is configured:

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

The smoke tests included in the repository cover the host half and can be run as follows:

node test/smoke.test.mjs

Scenarios and Notes¶

Suitable users: DSH users who switch between DeepSeek’s official route and custom service providers, wish to keep track of their balance at any time, and do not want to leave the conversation interface for this purpose.

A few notes:

The plugin runs with the permissions of the current dsh process. Before installing, you should check the source code and license (MIT) to confirm you are willing to accept it.
It declares three peerDependencies: @deepseek-ai/cordis ^4.0.1, @deepseek-ai/dsh-credentials ^0.1.0-rc.7, @deepseek-ai/schemastery ^3.18.1.
The repository is the source of truth: the live copy currently installed in DSH Desktop’s node_modules follows it; if you modify the code, you need to resync it to the installed copy, or install from this repository and rebuild the profile link.

Summary¶

After the steps above, dsh-balance will display a short text snippet next to the model seat in the input box, compressing the “check balance” action from a browser login to a glance. For plugin source code and documentation, see GitHub: https://github.com/kkbsgg/dsh-balance

dsh-balance: Display account balance next to the DSH input box model seat