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.