dsh-api-balance-plugin

dsh-api-balance

DeepSeek Harness 内置余额显示 · npm package: dsh-api-balance-plugin

A DeepSeek Harness plugin bundle that keeps your DeepSeek

API balance in sight: a resident pill under the composer, a click-through detail popover, a /balance command,

and an api_balance tool the agent can call on its own.

This is a Harness plugin (a Host half + a browser half + a bundle patch), not a model-facing skill.

Installing it adds real UI and a real tool to the Harness; a skill only adds instructions to the prompt.

[中文说明](#中文说明) · [Install](#install) · [Configuration](#configuration) · [How it works](#how-it-works) · [Privacy](#data--privacy) · [Limitations](#limitations)

Features

• Resident pill in the composer dock, beside the built-in activity and usage entries: ¥128.40. It refreshes on

its own and never needs a click to stay current.

• Detail popover on click: total balance, topped-up credit, granted credit, the update time, and links to the

Platform pages for usage detail and top-up.

• /balance command: type it in the composer and the balance lands in the conversation as a plain text row.

Nothing is sent to the model and no tokens are spent.

• api_balance tool: ask the agent “how much credit is left?” and it reads the same values.
• Both credential styles: a signed-in DeepSeek account (wallet balances from the account grant) or a plain

DEEPSEEK_API_KEY. It picks whichever you actually have.

• Theme- and locale-aware: only --dsw-alias-* tokens are used, and the copy follows the active UI language

(English and Chinese are bundled).

Requirements

Requirement · Notes

DeepSeek Harness >= 0.2.1-rc.2 · Tested against 0.2.1-rc.2 (desktop and web).

A credential · A signed-in DeepSeek account in the app, or the DEEPSEEK_API_KEY credential reference.

A DeepSeek account · Other providers do not expose a balance endpoint; see [Limitations](#limitations).

Install

From this repository (works today) — clone it, then install the directory:

git clone https://github.com/Muzi1015/dsh-api-balance.git

Then tell your agent:

Install the plugin bundle at <absolute path>/dsh-api-balance.

From npm (once dsh-api-balance-plugin is published) — ask your agent:

Install the dsh-api-balance-plugin plugin bundle.

Either route runs Plugin Manager's install_bundle, links the package into your profile, and enables it. You can also

install by package name from the app's Settings → Plugins area. Both survive restarts because the bundle is recorded

in your profile, not in a session.

Configuration

Two knobs, both with safe defaults. Override them by targeting the row id api-balance in your profile patch layer

(~/.dsh/profiles/<profile>/cordis.patch.yml). A matching override replaces the whole config, so repeat every

key you still want:

- id: api-balance
  name: 'dsh-api-balance-plugin'
  config:
    refreshSeconds: 120
    lowBalance: 20

Key · Default · Meaning

refreshSeconds · 60 · How often the Host re-reads the balance (clamped to 15–3600). The pill polls the Host at the same rate.

lowBalance · 5 · Below this amount the pill switches to the warning tone and the popover adds a low-balance note. 0 disables it.

Usage

Surface · What happens

Composer dock · ¥128.40 with a state dot. Green = available, amber = low balance or a failed read, grey = unavailable.

Click the pill · Popover with 总余额 / 充值 / 赠送, update time, 用量明细 and 去充值 links, plus an Esc-to-close dialog and a manual refresh button.

/balance · A command row with the same numbers; errors (no credential, 401, timeout) print their reason.

Agent tool · api_balance with an optional fresh flag to bypass the Host cache.

The popover reads through the Host, so the API key never reaches the browser: the page only ever sees amounts.

Data & privacy

• The Host reads ctx.deepseekAccount.getBalance() when an account grant is stored; otherwise it resolves the

DEEPSEEK_API_KEY credential reference (provider store first, then the ambient environment) and calls

GET https://api.deepseek.com/user/balance.

• The browser receives a JSON snapshot of amounts only — no token, no key, no profile.
• The snapshot route is GET /plugin/api-balance/snapshot, same-origin guarded (a cross-site sec-fetch-site

is answered with 403; other methods get 405). It is registered on the local Harness web server only.

• The Host caches one snapshot for refreshSeconds so several surfaces never multiply upstream calls.
• Nothing is written to disk by this plugin; it keeps no history and sends no telemetry.

Limitations

• DeepSeek only. The plugin reads the DeepSeek Platform wallet. OpenAI, Anthropic and most other providers do not

publish a balance endpoint, so a generic “balance” panel is not something one adapter can cover.

• Balance, not itemized usage. The public API exposes the wallet, not a usage ledger, so “usage detail” is a link

into the Platform page where you are already signed in.

• Sign-in happens in the app. If you use an API key, that is all the plugin needs. Account wallets only appear when

the Harness account sign-in is complete.

• The pill needs a Web-surface client (the composer dock is a browser slot); /balance and the tool are Host-side and

work wherever a composer or an agent exists.

How it works

File · Role

index.js · Host half: one read() shared by the HTTP route, the /balance command and the api_balance tool, with a TTL cache and upstream failure reporting.

client.js · Browser half: a conversation.composer.dock entry that renders the pill and a fixed-position popover, polls the route, and follows ctx.locale.

cordis.patch.yml · Bundle patch: inserts row api-balance with its default confi

…(truncated)