dsh-get-balance

A balance & cost plugin for DeepSeek Harness:

• Multi-account balance — enumerates every DeepSeek provider (pi-ai routes / official route / extra keys), folds the same account into one row, and shows every account balance at a glance;
• Real-time stats — live per-session token usage and cost estimation, with online-editable price tiers (model × peak/off-peak);
• Bilingual UI — copy follows the host language (Simplified Chinese / English);
• Friendly & simple — one unified modal (Balance / Cost / Prices) plus a sidebar entry and a live session-header button; intuitive and ready to use.

Simplified Chinese · Screenshots

Features

Balance tab

• Enumerates every DeepSeek provider:
  • entries from the host llm-pi-ai settings whose baseURL points at DeepSeek,
  • the official llm-deepseek route,
  • manually attached extra API keys (see below).
• Each API key row shows "Today spend ≈xx CNY | Balance xx CNY" (numbers green) — the key's own today cost (matched from the per-key cost stats by provider route, ≈0.00 when unused) plus its account balance.
• One row per account: when several routes resolve to the same API key (e.g. a pi-ai route named deepseek derives the credential ref DEEPSEEK_API_KEY, colliding with the official llm-deepseek default), they are folded into a single row — the row keeps its first entry and shows a chip for every route sharing the key (tooltip: "shares API key with …"). The balance query runs once per distinct key, so the same account is never displayed twice with different names.
• For each provider the plugin resolves the configured apiKeyEnv via the host credentials service and calls the official GET https://api.deepseek.com/user/balance (proxied by the host — keys never reach the browser). Each row shows total_balance / granted_balance (+ topped-out flag) or the failure reason. Results are cached in memory for 60s; "Refresh" bypasses the cache.
• Extra API keys: keys outside any providers config can be attached directly from the modal (label + key, masked echo), persisted to $DSH_HOME/settings.yaml.

Cost tab — per-API-key breakdown

• One table: columns token / category / input (miss) / input (cache hit) / output / hit rate / est. cost. Every API key is a group of four rows (Last question / This session / Today·project / Today·all) with the token cell merged across them (label + masked key + official/non-official chip); a Total group comes first, key groups follow sorted by token volume. Numbers are compact (K/M/B/T/P); hit rate = cache-hit ÷ all input-side tokens.
• Token usage is counted per key regardless of officialness; cost is only computed for official keys (API domain api.deepseek.com) — non-official keys show a "not billed" chip instead of an amount. Multiple official keys (several routes pointing at the official API) each get their own group and their own bill.
• Multi-provider sessions are strictly split per provider: token stats and cost estimates follow each request's own request/context provider, and each group carries a source chip (pi-ai route / official route) plus the official/non-official chip (alias routes are judged by baseURL hostname, so a pi-ai route pointing at api.deepseek.com bills as official), so providers never mix. The Last question entry prices every sample with its own model (per-sample model from request/context), not a session-wide model.
• Aligned with the balance tab: every configured provider is listed as a group whether or not it has usage — providers without usage (or without a credential) show zero tokens and a "—" amount.
• Official detection: the provider field of request/context events → that provider's baseURL in host settings → hostname equals api.deepseek.com (trailing slash / case normalized; lookalike domains such as api.deepseek.com.xx.com are not official).
• Last turn / session: in-memory event folding (same (turn,step) last-value-wins semantics as the official tokenUsage projection). Today entries: on-demand scan of dshHomePath('sessions') logs (.jsonl and .jsonl.zstd, frame-wise zstd decode, per-file memoized).

Price settings tab — official pricing-table layout

• Mirrors the official price table layout minus the category column: Model version (colspan=2) + one column per model; three metric groups (input cache-hit / cache-miss / output, each rowspan=2) + off-peak/peak rows; only the price cells are input boxes (peak red, off-peak green).
• Each model has peak and off-peak sets of four prices (per million tokens: input / cache read / cache write / output, CNY).
• Periods are configurable: peak windows (cross-midnight supported) + a timezone-offset slider (UTC-12..+12, shown as UTC±0 / UTC+8 / UTC-5)
  • a "weekends half price" toggle (Saturdays & Sundays excluded from peak windows and billed at off-peak rates all day). Official default: Beijing 9:00–12:00 & 14:00–18:00 are peak; off-peak = peak × 0.5.
• Built-in fallback is the official V4 tiers (deepseek-v4-flash / deepseek-v4-pro / deepseek-v4-flash-vision-exp). Old flat-format config migrates automatically on first read (legacy built-in defaults upgrade to the official three tiers).

Session-header live button

• Registered on conversation.session.header.utilities, showing Session xxM | ≈¥xx (both green, digits roll vertically odometer-style) — the current session's total tokens (compact K/M/B/T/P format) and its estimated cost.
• Clicking the button refreshes once; auto-refreshes at the configured interval; refreshes on session switch; and refreshes the moment each AI request completes (the host session snapshot gains a new assistant message node — request-level, not per streamed token), so a turn with several requests updates after each one. Only completions that hit the official DeepSeek API (api.deepseek.com) also force-refresh the footer balance (bypassing its 60s cache) — requests to non-official endpoints update tokens & cost only, without a balance query.
• Per-provider breakdown popover: since a session may switch providers mid-way, the button shows the merged totals; clicking opens a bubble popover listing each provider's own stats (ds-self 268K | ≈¥0.41, non-official rows show "not billed").

Entry button (sidebar footer)

• sidebar.footer.action Balance button: the label and a period dot on the left, the amounts right-aligned ("Balance ¥110.00 | ¥99.50") — currency symbol prefix, digits in green and rolling vertically odometer-style on change. One segment per provider (account), separated by |; an account whose balance could not be fetched (no API key configured / query failed) shows a red -- placeholder (hover shows the reason). The period is a small dot (red for peak hours / green for off-peak, half price) whose hover tooltip shows the full info "Currently peak hours · full price billing" / "Currently off-peak hours · half price billing" (full price in red / half price in green); the amounts come from the balance API.

Auto refresh

• An Auto button (left of the Refresh button in the modal header) opens a config dialog: set the interval (seconds) → Start/Stop. While running, the input and the Start button are disabled; stopping re-enables them.
• At each interval, balance & cost refresh automatically (the modal when open, the header button otherwise). The interval is persisted to $DSH_HOME/settings.yaml (autoRefreshJson) and survives restarts.

Config / packaging

• Schemastery Config + a settings namespace (dsh-balance): extra keys, price config and auto-refresh interval persist to $DSH_HOME/settings.yaml.
• dsh.bundle + dsh.client(web) manifests; the official deepseek-harness project is never modified — everything rides existing slots and the HTTP / command channel.

Layout

├── src/host/*.ts       # host half: index.ts, providers.ts (enum + official check),
│                       # balance.ts, cost.ts (fold + today scan + period pricing +
│                       # official filter), ops.ts, fence.ts, types.ts
├── src/client/*        # browser half: plugin.tsx (slots + timer), BalanceModal.tsx,
│                       # HeaderButton.tsx, FooterButton.tsx, rpc.ts, store.ts,
│                       # i18n.ts, styles.ts, logo.ts
├── lib/index.js        # host bundle (tsdown ESM), committed for git installs
├── lib/client.js       # browser bundle (__ModuleLoader__ factory), committed
├── lib/types/          # declarations (tsc -b)
├── scripts/            # verify-client.mjs
├── tsdown.config.ts    # tsdown config (host + client banner wrap)
├── tsconfig.json       # solution: tsconfig.host.json / tsconfig.client.json
├── cordis.patch.yml    # bundle patch
├── package.json        # dsh.bundle + dsh.client(web) manifests + peerDependencies
├── README.md           # this file (English, default)
└── README.zh-CN.md     # Simplified Chinese docs

Install

# published: npm / tarball / GitHub
dsh plugin --profile web add dsh-get-balance
dsh plugin --profile web add ./dsh-get-balance-0.1.0.tgz
dsh plugin --profile web add github:you/dsh-get-balance#<sha>

dsh --profile web --dump-config   # inspect the plugin layer
dsh --profile web                 # start

No static config required: extra keys, price config and the auto-refresh interval are edited in the modal and persisted to $DSH_HOME/settings.yaml.

Release

Toolchain: tsc + tsdown (no vite): tsc -b type-checks and emits declarations; tsdown (Rolldown core) bundles the host half (lib/index.js, ESM) and the browser half (lib/client.js, single-file CJS __ModuleLoader__ factory). Dependency manager: pnpm 10.

pnpm install     # per pnpm-lock.yaml
pnpm run build   # clean lib → tsc -b (types + declarations) → tsdown (both halves)
pnpm run verify  # simulate the host seed to validate lib/client.js (optional)
pnpm publish     # or pnpm pack / git push origin main (lib/ committed → git installs need no build)

Auto publish (GitHub Actions)

Pushing a v* tag (pnpm run release bumps the patch version, rebuilds and tags) triggers .github/workflows/publish.yml:

• release job: Setup Node → pnpm install --frozen-lockfile → pnpm run check → pnpm run build → pnpm pack → create GitHub Release;
• publish-npm job: publish to npm — requires the NPM_TOKEN repo secret.

Development

Requirements: Node ≥ 26 + pnpm 10 (pinned via the packageManager field).

pnpm install           # devDependencies: typescript, tsdown, @types/react, @deepseek-ai/* type packages…
pnpm run check         # full-tree TypeScript check (tsc -b)
pnpm run build         # rebuild both bundles after source changes (tsc -b && tsdown)
pnpm run verify        # validate lib/client.js against a simulated host seed

Attach the local checkout to a dsh instance (from the plugin repo):

cd dsh-get-balance
dsh plugin --profile web add ./

The host loads index.js as native Node ESM, so @deepseek-ai/schemastery, @deepseek-ai/dsh-tools, @deepseek-ai/dsh-settings, @deepseek-ai/dsh-home-paths must resolve from the plugin directory (run pnpm install there; node_modules is gitignored). Host-half (src/host/) changes need a dsh restart; browser-half (src/client/) changes apply on a page refresh.

• Host half lives in src/host/; browser half in src/client/;
• The window.__ModuleLoader__.load factory wrap of lib/client.js is generated by tsdown's banner/intro/footer; external deps (react etc.) resolve through the host module table (seed) at runtime.

Implementation notes

• Browser ↔ host: HTTP route /dsh-balance/api (POST JSON, host webServer + trust fence) with a ctx.remote.commands.execute fallback; errors carry a code that the client localizes.
• Credentials: the credentials service is looked up lazily per request (not captured at apply time), avoiding a "no credential" state when the host service starts late; the providers op returns credentialsPresent and per-entry keySource diagnostics.
• Pricing: (uncachedInput × p_input + cacheRead × p_cacheRead + cacheWrite × p_cacheWrite + output × p_output) / 1e6 per million tokens, priced by each event's time (peak/off-peak).
• Official filter: request/context provider → baseURL in host settings → hostname == api.deepseek.com; non-official tokens are counted only (per-provider four buckets), never billed.
• Today aggregation: dshHomePath('sessions')/<projectKey>/<sessionId>/session.jsonl(.zstd), decoded frame-wise via zstdDecompressSync from node:zlib.
• Peer deps (@deepseek-ai/cordis, dsh-tools, schemastery, dsh-settings, dsh-commands, dsh-session, dsh-api-remotes, client runtime / ui-slots / ui-settings / cordis-client-runner, react) are resolved by the host at install.
• The official deepseek-harness project is never modified; everything uses existing slots (sidebar.footer.action, shell.overlay, conversation.session.header.utilities) and the HTTP / command channel.