dsh-balance-meter
English | 中文
DeepSeek account balance and session-cost readout for the DeepSeek Harness (DSH) Web GUI.
- Explicit balance sources: official API, proxy-compatible endpoint, or a
manual balance accounted and persisted locally
- Current session estimated spend (token usage x official pricing)
- Per-model pricing: reads the model actually driving each session from its
request header (flash vs pro), so the cost tracks the model you used instead
of a fixed default
- Auto-fetches the official pricing page every 6h, so price changes and the
2026-08-17 peak/off-peak pricing rollout never require a plugin update
- Peak-hour band (Beijing 09:00-12:00 / 14:00-18:00) applied automatically
once the peak pricing goes live
Features
The composer dock shows a chip with the account total balance and the
current session's estimated cost:
Balance CNY 4.16 · This session CNY 2.57
Clicking the chip reveals the per-currency balance breakdown (granted +
top-up) and the per-bucket cost breakdown (input / cache read / output).
Clicking while an error is shown forces an immediate refresh.
Requirements
- DeepSeek Harness
0.1.0-rc.6 or newer (web profile)
- A DeepSeek API key stored through the DSH credentials seam
(
DEEPSEEK_API_KEY — the web Models page writes it)
Installation
From a git URL (no npm account needed):
dsh plugin --profile web add https://github.com/Ghost011118/dsh-balance-meter
Or from a local checkout:
git clone https://github.com/Ghost011118/dsh-balance-meter.git
dsh plugin --profile web add link:$(pwd)/dsh-balance-meter
Restart dsh web, then refresh the page. The balance chip appears in the
composer dock next to the conversation stats line.
Configuration
The plugin is zero-config by default (uses DEEPSEEK_API_KEY and the
official pricing page). Optional composition settings:
- insert:
- id: balance
name: 'dsh-balance-meter'
config:
source: official # official (default) | proxy | manual
model: auto # 'auto' (default) | 'flash' | 'pro'
pricingRefreshHours: 6
| Key | Type | Default | Meaning |
|---|
source | 'official' | 'proxy' | 'manual' | official | Provenance of the displayed balance. A legacy custom baseUrl with no source is automatically classified as proxy |
balanceEndpoint | string | /user/balance | Proxy balance path or absolute HTTP(S) URL |
proxyBalancePath | string | unset | Dot path (for example data.balance) to a numeric balance when the proxy does not return DeepSeek-compatible balance_infos |
proxyCurrency | string | CNY | Currency paired with proxyBalancePath |
manualBalance | number >= 0 | unset | Current balance entered by the user; changing it creates a new local accounting baseline |
manualCurrency | string | CNY | Currency of the manual balance |
model | 'auto' | 'flash' | 'pro' | auto | auto detects each session's model from its request header (flash/pro); flash/pro force that preset regardless of auto-detection |
pricingRefreshHours | number | 6 | Hours between automatic official-pricing refreshes |
apiKeyEnv | string | DEEPSEEK_API_KEY | Credential ref storing the DeepSeek API key |
baseUrl | string | https://api.deepseek.com | API base URL (gateway/compat override) |
refreshIntervalSeconds | number | 30 | Minimum seconds between balance queries |
Proxy and manual modes
proxy mode keeps the API key on the DSH host and sends it only as a Bearer
credential to the configured endpoint. A DeepSeek-compatible relay may return
balance_infos directly. Other relays must configure proxyBalancePath; a
missing or non-numeric value is reported as a proxy error and is never labelled
as an official balance.
manual mode requires a writable DSH settings provider. The hidden ledger is
stored inside the existing balance settings namespace, not in a separate
plaintext file and never in the browser response. It records a baseline,
remaining amount, locally charged spend, and per-session cumulative-token
checkpoints. Only positive token deltas after the last persisted checkpoint are
charged, so polling or restarting DSH cannot deduct the same cumulative session
usage twice. Changing manualBalance or manualCurrency intentionally creates
a new baseline and checkpoints all currently live sessions.
How the cost is estimated
The plugin reads DSH's durable tokenUsage projection (the same accounting
the built-in stats line uses) and converts the four buckets — uncached
input, cache read, cache write, output — to money using prices parsed from
the official pricing page. Cache-write tokens are not billed separately by
DeepSeek and default to 0.
For the price set, in auto mode (the default) it uses the model actually
driving the session: each session's request header records the provider/model
of the most recent request, and the plugin maps that id (deepseek-v4-flash
→ flash, deepseek-v4-pro → pro) to the matching per-million prices. A
session is therefore priced at whatever model produced its usage, not a
hard-coded flash. When no header exists yet or the model id is unrecognized,
auto falls back to flash. Setting model: flash or model: pro explicitly
forces that preset and ignores auto-detection, so you can pin the estimate to
one model when you want to.
Before the 2026-08-17 peak-pricing rollout the current single prices stay
authoritative; after it, the peak/off-peak band for the current Beijing hour
is applied. If the pricing page cannot be fetched, built-in presets (flash:
0.02 / 1 / 2 CNY per 1M) are used. Explicit cost.* overrides in the
composition config take precedence over any preset. The cost JSON also
reports pricingKey and model so the chip can show which model was priced.
Troubleshooting
"no API key for provider route `deepseek-official`"
The host reads your key from the DSH credentials store — the file
<harness home>/.credentials.yaml (default ~/.dsh/.credentials.yaml), the
same store the web Models page writes. This plugin's balance query and the
LLM route resolve through that same seam.
- If this error appears, make sure the document contains
DEEPSEEK_API_KEY: sk-... (a strict mapping of reference to non-empty
string). Editing it while DSH runs is fine — the provider hot-reloads and
re-reads the file.
- When a credentials seam is mounted, both the LLM route and this plugin read
the key only from the credential store; a plain
export DEEPSEEK_API_KEY
is ignored in that case. Exporting still helps for the plugin's own fallback
when no seam is present.
- Prefer running
dsh web through a single supervised instance (e.g.
dsh-autostart) instead of launching several ad-hoc npx dsh web
processes that can race on the same port and settle different credential
snapshots. If you encounter this right after killing a manual instance,
confirm the other (still-supervised) instance read the key — the balance
chip recovering to a live total means the key resolved.
- The error is transient-friendly: the balance chip auto-recovers, because an
error state is never cached as fresh — the next poll re-queries the
provider.
Balance stuck on "unavailable" and only updates on click
An error/unavailable snapshot used to be served from the cache until it aged
out, so a transient failure could hold the chip on "unavailable" until you
clicked to force a refresh. Now an erroneous view is never reused as a
fresh cache: every poll re-queries the provider, so the chip recovers on its
own as soon as the underlying condition clears (balance reachable, network
back, key stored).
License
BSD-3-Clause. Copyright (c) 2026, Ghost011118.
