dsh-get-balance

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/dsh-get-balance.json.

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 — platform sub-tabs + official pricing-table layout

• Platform sub-tabs (currently DeepSeek only; more providers' pricing can be added later as additional sub-tabs).
• 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.
• Show in menu preference (default on, localStorage key dsh-get-balance.show-in-menu): when off, the entry button renders nothing at all (no placeholder, and no balance polling behind it). The same switch sits at the top of the modal's Prices tab and at the top of the host Settings → Balance section page (settings.section, order 42, which stays reachable and is then the only way back in; both switches share one store, so flipping either updates the other immediately.

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/dsh-get-balance.json and survives restarts.

Config / packaging

• Schemastery Config (no required options) + a plugin-owned config file $DSH_HOME/dsh-get-balance.json: extra keys, price config and the auto-refresh interval are persisted there (JSON, versioned), never into the host's settings.yaml. Existing data stored in the old dsh-balance settings namespace is migrated automatically on first run.
• dsh.bundle + dsh.client(web) manifests; the official deepseek-harness project is never modified — everything rides existing slots and the HTTP / command channel.

Plugin config file

• Location: $DSH_HOME/dsh-get-balance.json (next to settings.yaml).

• Contents (all fields optional on read; invalid values fall back to defaults):

  {
    "version": 1,
    "extraKeys": [ { "id": "k1", "label": "main", "apiKey": "sk-..." } ],
    "prices": {
      "tiers": [
        { "id": "deepseek-v4-flash", "name": "deepseek-v4-flash", "currency": "CNY",
          "match": "deepseek-v4-flash",
          "peak": { "input": 2.0, "cacheRead": 0.04, "cacheWrite": 0, "output": 8.0 },
          "offPeak": { "input": 1.0, "cacheRead": 0.02, "cacheWrite": 0, "output": 4.0 } }
      ],
      "timezoneOffsetMinutes": 480,
      "peakWindows": [ { "start": "09:00", "end": "12:00" }, { "start": "14:00", "end": "18:00" } ],
      "weekendOffPeak": false
    },
    "autoRefreshSeconds": 0
  }
  

• It is read on every query and written atomically (temp file + rename) on save, so hand-editing takes effect immediately (no restart). A corrupted file is renamed to dsh-get-balance.json.bak-<timestamp> and defaults are used.

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, config-file.ts (plugin config
│                       # file read/write + legacy settings migration),
│                       # 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/dsh-get-balance.json.

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, settings.section, shell.overlay, conversation.session.header.utilities) and the HTTP / command channel.
• Style isolation: every rule in the injected stylesheet is scoped to .dshb-* with one deliberate exception — :where(div:has(> [data-slot="sidebar.footer.action"] > .dshb-footer-group)){flex-direction:column}, which stacks the host footer container (the host lays it out as a flex row, so several plugin entries would squeeze onto one line). It can only match a container that already holds this plugin's own entry, and :where() drops its specificity to 0 so the host can always override it. Keyframe names are dshb--prefixed and the style tag is marked data-plugin-css="dsh-get-balance/settings.css"; no other global selector, no :root/body/* rule, no body-style mutation.