dsh-balance-plugin
DeepSeek wallet balance at the sidebar foot — a DeepSeek Harness plugin.
DeepSeek-only: this plugin targets the DeepSeek platform exclusively — the official DeepSeek balance endpoint and DEEPSEEK_API_KEY. No other platforms or providers are supported.
English | 中文
Shows your DeepSeek account balance as a card icon + amount in the sidebar footer (beside Settings), tinted by how much is left. Refreshes when a conversation turn ends, on click, and on mount — no polling. When the amount changes, a signed delta (+¥3.14 / -¥1.97) floats up and fades next to it — every spend (or top-up) is visible at a glance.
screenshot placeholder: sidebar foot showing 💳 ¥12.34 in green
Features
- Status-tinted amount: only the amount carries the color, the icon stays neutral —
- ≥
lowBalanceThreshold (default 2): green
- above zero: amber
- zero or below: red
- Refresh on turn end: the host pushes an SSE
refresh event when any conversation turn ends — wallet spend settles with the turn.
- Click to refresh; in-flight refreshes are deduped (a click or turn-end tick during a pending query is a no-op).
- Float delta: on a visible amount change, a signed delta floats up and fades out — green when the balance rises, red when it falls. Zero or sub-cent changes are silent, the first load never floats, and the animation is suppressed under
prefers-reduced-motion.
- Silent failure: unconfigured credentials or a failed fetch render nothing — the readout is advisory and never surfaces an error.
- Original currencies: balances are displayed as the provider reports them; no conversion, no summing.
Install
Requires a DeepSeek Harness runtime that can load the plugin, plus a DeepSeek account credential. The package deliberately places no version restriction on DSH: there is no engines.dsh range and the optional @deepseek-ai/dsh peer is *, so the Harness plugin manager does not reject it on version grounds. Any Harness release that provides the plugin APIs it uses will run it; a future release that removes those APIs would fail at load time instead. The plugin resolves DEEPSEEK_API_KEY through the optional harness credential service (~/.dsh/.credentials.yaml) or the environment.
From npm (recommended)
dsh plugin --profile <name> add dsh-balance-plugin
From the GitHub Release (no npm account needed)
Download dsh-balance-plugin-<version>.tgz from the releases page, then:
dsh plugin --profile <name> add ./dsh-balance-plugin-<version>.tgz
Note: the plugin lives in the plugins/ subdirectory of the dsh-plugins monorepo, so dsh plugin add github:... cannot target it — use the tarball (or npm).
In the Desktop app
The Desktop app serves the same Web surface, so the plugin runs there unchanged — install it into the app's own desktop profile rather than web, either from the app's Plugins page or with dsh plugin --profile desktop add dsh-balance-plugin while the app is quit (Desktop owns that profile, so its CLI refuses to initialize it from scratch). Verified against Desktop 0.2.0-rc.2: the sidebar action registers and both /dsh-balance routes mount.
Update an existing install
For npm installs, update the package in the same profile, confirm that its bundle layer remains active, then restart the Web server:
dsh plugin --profile <name> update dsh-balance-plugin
dsh --profile <name> --dump-config # expect a "# == dsh-balance-plugin" layer
# restart dsh web, then hard-refresh the browser
dsh plugin forwards pnpm commands and reconciles the installed package's dsh.bundle declaration after a successful update. For a Release tarball, run dsh plugin --profile <name> add ./dsh-balance-plugin-<version>.tgz with the newer archive, then perform the same verification and restart.
Configuration
The plugin ships with sensible defaults; override via the bundle's plugin row:
# profile's cordis.patch.yml (or your home-level one)
- id: balance
name: dsh-balance-plugin
config:
apiKeyEnv: DEEPSEEK_API_KEY # credential reference, then the environment
baseURL: https://api.deepseek.com # provider base URL
timeoutMs: 12000 # per-request timeout; abort maps to balance-timeout
lowBalanceThreshold: 2 # amount at or above which the tint reads healthy
How it works
| Half | What it does |
|---|
| Host (Node) | Registers authenticated GET /dsh-balance (the wallet readout as JSON) and GET /dsh-balance/events (an SSE stream). Each route passes the Harness browser-auth and Origin fence before reading a credential. It listens on session/event and emits refresh per turn/end, resolving credentials per request through the optional service before falling back to the environment. |
| Client (browser) | Registers the sidebar.footer.action slot entry (the shell's reserved seat beside Settings; on the collapsed rail it stacks above the settings icon). Fetches the readout on mount, on refresh SSE events, and on click, with an in-flight guard. The card icon is self-contained (no dependency on the shell's icon library). |
Position and interaction follow the shell's own design: the sidebar.footer.action hole is the official extension point for "optional actions beside Settings".
Frequently asked questions
The balance looks stale right after a conversation ends. Provider settlement lags the turn by tens of seconds. The turn-end refresh may briefly show the pre-settlement amount; clicking later shows the settled value. This matches the official DeepSeek client behavior — the readout is advisory.
Nothing renders. No credential resolves (unconfigured) or the fetch failed — by design. Check dsh --profile <name> --dump-config for the plugin row, and that DEEPSEEK_API_KEY resolves through the credential seam or the environment.
How do I remove it?
dsh plugin --profile <name> remove dsh-balance-plugin
This removes the dependency and the bundle layer together.
Development
src/
balance-core.ts # pure query logic (credential resolution, HTTP, normalization)
index.ts # host plugin: routes + SSE + turn-end listener
client.tsx # browser plugin: the sidebar-foot action
scripts/build.mjs # esbuild: host ESM + browser __ModuleLoader__ bundle
tests/ # node:test unit tests for balance-core
pnpm install
pnpm run build # emits lib/index.js + lib/client.js
pnpm test # balance-core, float, and host-route unit tests
Local install check (official verification points):
dsh plugin --profile demo add ./
dsh --profile demo --dump-config # expect a "# == dsh-balance-plugin" layer
Release checklist
Before publishing a new version:
pnpm run build and pnpm test pass.- Local install and
dsh plugin --profile demo update dsh-balance-plugin both keep the --dump-config layer; the web profile renders the readout with a real credential.
- Version bumped (
npm version patch/minor/major); git tag matches.
pnpm pack — inspect the tarball: it must contain lib/, cordis.patch.yml, README.md (and nothing else heavy).npm publish — publishes prebuilt code, so users install with zero friction.- Push the tag; keep the GitHub release notes in sync with the npm version.
License
MIT
