dsh-api-balance

DeepSeek Harness 内置余额显示 · npm: 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 · Configuration · How it works · Privacy · 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.

Install

From npm — ask your agent:

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

That runs Plugin Manager's install_bundle with the package name, links it into your profile, and enables it; the app's Settings → Plugins area accepts the same name. Reinstalling the package is how an upgrade lands.

From this repository — clone it and install the directory (handy while trying a local change):

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

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

Both routes 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 config.
locale/{en,zh}.json	Plugin Manager title and description.
icon.svg	Original artwork (circle + ¥), no third-party assets.

Registration points: ctx.webServer.register, ctx.commands.register, ctx.tools.register, ctx.slots.inject('conversation.composer.dock'). Everything is registered through ctx.inject/ctx.effect, so disabling the bundle removes the route, the command, the tool and the pill together.

Local development

npm run check          # node --check on both halves

The Host half is plain ESM and the browser half is plain JS registered through window.__ModuleLoader__, so there is no build step. After editing, reinstall the directory (or restart the Harness) to pick up a fresh module generation.

Releasing a new version

1.0.0 is published to npm and tagged v1.0.0 on GitHub. For the next release:

npm version patch        # bumps package.json, commits and tags
git push --follow-tags
npm publish              # npm asks for the interactive confirmation / 2FA

The bundle you run locally is a link to this checkout, so a local edit needs only a reinstall; a published release is the three lines above.

If you ever rename the package, change exactly three places — package.json name, the id in client.js, and the name in cordis.patch.yml — and reinstall the bundle.

A screenshot of the pill and popover is the one asset this repository cannot generate on its own — add one to the README before announcing it.

License

The Unlicense (public domain) — see LICENSE.

---

中文说明

这是什么：一个 DeepSeek Harness 插件包（Host 半 + 浏览器半 + bundle 补丁），不是 skill。装进 Harness 后会真实增加 UI 和一个工具；skill 只是给模型的提示词文本。

别人怎么用：让他的 agent 说「安装 dsh-api-balance-plugin 插件包」（install_bundle 会从 npm 拉取），或者在设置 → 插件里按包名安装；想试本地改动时，也可以 clone 仓库后直接安装那个目录。

他能看到什么：

• 输入框下方常驻小胶囊，显示实时余额，点击展开「总余额 / 充值 / 赠送」、更新时间，以及「用量明细」「去充值」链接；
• 在输入框输入 /balance，余额以文本行落在会话里，不发给模型、不花 token；
• 对 agent 说「查下余额」，它会调用 api_balance 工具。

凭据：优先用 App 里已登录的 DeepSeek 账户钱包；没有登录就用 DEEPSEEK_API_KEY 凭据去查 https://api.deepseek.com/user/balance。浏览器只能拿到金额，拿不到 Key。

配置：在 profile 的 cordis.patch.yml 里覆盖 api-balance 行，refreshSeconds（默认 60，15–3600）和 lowBalance（默认 5，低于它胶囊变橙色）。注意覆盖会替换整份 config，两个键都要写。

限制：只支持 DeepSeek（其他厂商没有余额接口）；只能看余额，明细跳平台页面；胶囊需要 Web 界面。

发布：已发布到 npm（dsh-api-balance-plugin@1.0.0，2026-10-20）和 GitHub（tag v1.0.0）。以后发新版： npm version patch → git push --follow-tags → npm publish（npm 会要一次浏览器/2FA 确认）。改包名时只需改 package.json 的 name、client.js 的 id、cordis.patch.yml 的 name 三处，再重装一次即可。