dsh-balance
English | 中文
A DeepSeek Harness plugin that adds a
/balance slash command and a composer-dock balance readout to the web GUI, querying the
DeepSeek account balance live.
It calls DeepSeek's official Get User Balance
endpoint and returns the total, topped-up, and granted balance per currency. The API key is
resolved through the credential seam (ctx.credentials) or the environment on every call —
it is never written into configuration, into the returned text, or into the browser.
Features
/balance — human slash command that prints the full balance breakdown in the session.- Web GUI readout — the conversation stats area (below the cache-hit figure) shows a
compact
Balance: ¥… line with hover details (topped-up / granted), a Top up link to
the DeepSeek platform top-up page, a manual refresh button, and an estimated
Session ≈ ¥… spend figure (hover shows the token buckets × unit prices). The readout
copy is bilingual and follows the active dsh language (Chinese / English). The browser
fetches the host's /dsh-balance route; the API key never leaves the host.
- Daily-spend chart — hovering
Last {days}d ≈ ¥… floats a comic speech bubble upward
from the summary: a titled SVG bar chart of the last usageDays days' estimated spend,
with a Y axis of ¥ ticks, an X-axis date per bar, and per-bar hover details (date, amount,
request count, tokens). Moving away closes it. Data comes from the host's /dsh-usage
route, which folds assistant/message usage across persisted sessions, pricing each
request at the tier in effect at its own time.
Session-cost estimate
The Session ≈ ¥… figure prices the session's cumulative token usage — the same
tokenUsage projection the cache-hit stat reads — at DeepSeek's published per-million-token
rates (peak/off-peak, selected by the current Beijing time). It is an estimate, not a
billing record: the model used is the configured estimateModel (not per-request model
selection), and cache-write tokens are unpriced. Prices can be adjusted through the
offpeakPrices / peakMultiplier / peakWindows config fields.
Compatibility
Tested against DeepSeek Harness 0.2.0-rc.2 (web profile, Windows 11) and earlier 0.1.0-rc.x
builds — the /balance command and the composer-dock readout were verified live on 2026-08-14
against 0.1.0-rc.6, and the 0.2.x port against 0.2.0-rc.2. Version 0.2.0 requires dsh
0.2.x: dsh retired @deepseek-ai/dsh-client-runtime and removed
sessionPersistence.inspect(), both of which 0.1.0 used. The npm @deepseek-ai/dsh-* packages
are pre-release (no compatibility promise); if a newer dsh version changes the
conversation.composer.dock slot or the webServer service, re-run the check below and file an
issue.
Install
Option A: dsh plugin (recommended)
After pushing to GitHub:
dsh plugin --profile web add github:deepforce/dsh-balance
Replace github:deepforce/dsh-balance with your actual git URL. The bundle installs both
halves: the host plugin (slash command + /dsh-balance route) and, because the package
declares dsh.client, the browser-side composer-dock plugin. Restart dsh web after
installing so the client plugin table picks the new entry up.
Option B: --patch overlay
# balance.cordis.yml
- insert:
- id: balance
name: '@deepforce/dsh-balance'
dsh web --patch "$PWD/balance.cordis.yml"
Configuration
| Field | Default | Meaning |
|---|
apiKeyEnv | DEEPSEEK_API_KEY | Credential reference (environment-variable name), resolved per call |
baseURL | https://api.deepseek.com | API endpoint base |
timeoutMs | 10000 | Per-request timeout in milliseconds |
estimateModel | deepseek-v4-flash | Model whose prices the session-cost estimate uses |
offpeakPrices | {input: 1.5, cacheHit: 0.05, output: 4.5} | Off-peak CNY per-million-token prices (uncached input / cache hit / output) |
peakMultiplier | 2 | Peak-hour multiplier over the off-peak prices |
peakWindows | [[9,12],[14,18]] | Beijing-time peak windows as [startHour, endHour) pairs |
topUpUrl | https://platform.deepseek.com/top_up | DeepSeek platform top-up page the readout links to |
usageDays | 7 | Default historical window (in days) for the daily-spend chart |
Usage
-
Type /balance in the session composer:
Balance (CNY): 110.00
Topped up: 100.00
Granted: 10.00
-
In the web GUI, the stats area under the composer shows Balance: ¥110.00 ⟳; hover
reveals the topped-up / granted split, and the ⟳ button refreshes.
Security
apiKeyEnv is a credential reference: resolved through the dsh credential service first,
then the environment. The key is never hard-coded or printed.- The browser readout only ever sees the public balance figures via the host's
/dsh-balance route; the key stays on the host.
- Only
GET https://api.deepseek.com/user/balance is called; no other data leaves the process.
Building locally
pnpm install # uses pnpm-workspace.yaml overrides for upstream npm gaps
pnpm run build # tsc (node half + types) then tsdown (lib/client.js browser bundle)
pnpm run typecheck
The upstream @deepseek-ai npm release (0.0.1-rc.1) declares a few dependencies that do not
exist on npm; pnpm-workspace.yaml aliases them to the real packages so this repo can
install and build. The dsh runtime resolves those dependencies from its own tree, so the
overrides do not affect the installed plugin.
License
MIT
