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.1.0-rc.6 (web profile, Windows 11) — the /balance command and the composer-dock readout were both verified live on 2026-08-14. 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