LL-cmyk-so/dsh-balance-widget

中文 | English

A balance & cost widget for the DeepSeek Harness (DSH) Web GUI: a persistent sidebar footer card shows the account balance and today's cost; clicking opens a five-tier cost breakdown (balance / last prompt with its session name / today-this-session / today-this-workspace / today-all-workspaces).

Preview

Sidebar card	Five-tier cost popover

How it differs from similar plugins

Aspect	This plugin	Others (dsh-balance / dsh-token-price / ...)
Zero external dependencies	✅ Imports no @deepseek-ai/* packages, no native modules	❌ Most depend on dsh SDK packages
Node 24 ready	✅ Works out of the box on any profile layout	⚠️ Many community plugins still error on Node 24
Boot stability	✅ Registers routes via official ctx.webServer; never conflicts with apiproxy	⚠️ Some self-host HTTP servers that crash dsh web on boot
On-demand queries	✅ Fetches balance only on click; no polling, zero background requests	Some always-on badges refresh on a timer
Peak/off-peak pricing	✅ Built-in official 2026-08-17 rate table, auto-switches by window	Partial support
Security	✅ API key stays in the host process; loopback-only guard	Varies

In one line: The zero-dependency, Node 24-ready balance/cost widget that never breaks dsh web boot.

Features

• Account balance — On click, the host proxies DeepSeek's official GET /user/balance and shows the ¥ balance; the balance number is color-coded by threshold (healthy / amber below lowThreshold / red below criticalThreshold). The API key is resolved through the host credentials service and never leaves the host process; the browser only talks to same-origin routes.
• Last prompt cost (estimate) — Parses the most recent session file and prices the last turn's token usage, answering "how much did that last prompt cost", with the session name labeled underneath.
• Today · this session cost (estimate) — The current session's usage today (calendar day) × DeepSeek's official peak/off-peak price table. Follows the configured model (default deepseek-v4-flash, switchable to deepseek-v4-pro) and the Beijing-time peak/off-peak windows automatically.
• Today · this workspace cost (estimate) — Sums today's token usage × price across every session in the current workspace (anchored by the current session).
• Today · all workspaces cost (estimate) — Walks every session under ~/.dsh/sessions/ and sums today's (calendar day) token usage × price.
• Peak/off-peak status — The card and popover borders are tinted by the current window (orange at peak / green at off-peak), a "Peak/Off-peak" tag sits next to the popover title, and hovering it shows the current price tier (input/output per 1M tokens).
• Token usage — Also shows the session's input (incl. cache hits) / output tokens.
• One-click top-up — a "Top up" link in the popover footer jumps to the official DeepSeek top-up page (platform.deepseek.com/top_up) in a new tab.
• Sidebar card — a persistent card at the sidebar footer shows balance and today's cost; globally visible, refreshes every 60s.
• Balance color warning — the balance number is tinted in three tiers: default (healthy) → amber (below lowThreshold) → red (below criticalThreshold).
• Official price auto-sync — fetches the DeepSeek official pricing page on startup and every 12h; falls back to built-in rates on failure.
• Agent tool — a deepseek_billing tool lets the model answer "how much balance do I have / how much did today cost".
• On-demand refresh — No polling, no background requests; endpoints are only hit when you click the icon. Costs zero tokens to use.

Why this plugin

• Zero external dependencies — the host half imports no @deepseek-ai/* packages and no native modules, so it loads from any profile layout and works on Node 24 (many community cordis plugins still lag on Node 24).
• Uses official APIs only — routes are registered through ctx.webServer (the same seam dsh-ssh uses) with loopback-only guards; no conflicting custom HTTP servers.

Architecture

host half (lib/index.js)
  ctx.webServer.register:
    GET /api/dsh-balance/balance     → official /user/balance (loopback-only guard)
    GET /api/dsh-balance/active-cost → last prompt + today-this-session (with session name, most recent session)
    GET /api/dsh-balance/today-cost  → today's costs (dual: current workspace + all workspaces)
  Zero @deepseek-ai/* imports; loads from any profile layout.
  Also registers a deepseek_billing tool for model-driven queries.

client half (lib/client.js)
  ctx.slots.inject("sidebar.footer.action")
    → persistent sidebar footer card (balance + today's cost, peak-tinted border)
    → click opens five-tier cost popover + peak tag + ⓘ term explanations

Installation

From npm (once published):

dsh plugin --profile web add dsh-balance-widget

From GitHub (development):

git clone https://github.com/LL-cmyk-so/dsh-balance-widget.git
cd dsh-balance-widget
dsh plugin --profile web add "link:$(pwd)"

Then restart dsh web.

Configuration

Where the config file lives

DSH plugin configuration lives in:

~/.dsh/profiles/web/cordis.patch.yml

All options

Append to cordis.patch.yml (only change the lines you need; the rest stay at defaults):

- id: balance-widget
  name: dsh-balance-widget
  config:
    balanceBaseURL: https://api.deepseek.com   # official balance endpoint (rarely changed)
    balanceApiKeyEnv: DEEPSEEK_API_KEY          # credential ref for the API key (rarely changed)
    requestTimeoutMs: 5000                      # balance request timeout (ms)
    modelId: deepseek-v4-flash                  # pricing model (or deepseek-v4-pro)
    lowThreshold: 5                             # balance below this (¥) turns the icon amber
    criticalThreshold: 1                        # balance below this (¥) turns the icon red

Example: custom balance thresholds

By default the icon turns amber below ¥5 and red below ¥1. To warn at ¥10 / ¥3 instead:

- id: balance-widget
  name: dsh-balance-widget
  config:
    lowThreshold: 10
    criticalThreshold: 3

Restart dsh web for changes to take effect.

Example: price with V4-Pro

If you mainly use DeepSeek-V4-Pro, point the pricing model at it for a more accurate estimate:

- id: balance-widget
  name: dsh-balance-widget
  config:
    modelId: deepseek-v4-pro

Note: cordis.patch.yml may already contain lines for other plugins — append new lines without touching existing ones.

Pricing

Built-in DeepSeek official peak/off-peak pricing (CNY per 1M tokens), effective 2026-08-17. Peak windows are Beijing time 09:00–12:00 and 14:00–18:00; prices are double the off-peak rates:

Model	Window	Cache hit (input)	Cache miss (input)	Output
V4-Flash	Off-peak	0.05	1.5	4.5
V4-Flash	Peak	0.10	3.0	9.0
V4-Pro	Off-peak	0.15	4.5	13.5
V4-Pro	Peak	0.30	9.0	27.0

deepseek-chat / deepseek-reasoner aliases map to Flash / Pro pricing respectively. Costs are estimates; actual billing from the provider is authoritative.

Changelog

v0.5.0 — Five-tier costs & peak/off-peak status

• ✨ Added: the cost breakdown is now five tiers — balance / last prompt / today-this-session / today-this-workspace / today-all-workspaces
  • The last-prompt row labels the session name underneath (based on the most recent session)
  • "Today · this session" = the current session's usage today; "Today · this workspace" = all sessions in the current workspace today (workspace anchored by the current session); "Today · all workspaces" = everything across all workspaces today
• ✨ Added: peak/off-peak status visuals — card and popover borders tinted by window (orange at peak / green at off-peak), a "Peak/Off-peak" tag next to the popover title with a hover tooltip showing the current price tier
• 🎨 Changed: removed the remaining-ratio bar; the balance number is now color-coded directly by threshold (healthy / amber / red)
• 🗑️ Removed: the "This session" row (all-time session total) from the popover

v0.2.0 — Last prompt & today total cost

• ✨ Added: popover now shows "last prompt cost" and "today total cost"
  • Last prompt: prices the current session's last turn from the session file
  • Today total: walks every session under ~/.dsh/sessions/ and sums today's usage
• 🐛 Fixed: session-id prefix duplication in the last-cost route (both session--prefixed and bare ids resolve)

v0.1.0 — Initial release

• 🎉 Account balance (official /user/balance) + session cost (estimate) + token usage
• On-demand refresh: no polling, queries only on click, costs zero tokens

Verify

• Config tree: dsh --profile web --dump-config should show a balance-widget entry.
• Balance route: after restarting dsh web, curl -s http://127.0.0.1:3080/api/dsh-balance/balance should return { ok, balance_infos, modelId }.
• Cost routes: curl -s "http://127.0.0.1:3080/api/dsh-balance/last-cost?session=SESSION_ID" and curl -s http://127.0.0.1:3080/api/dsh-balance/today-cost should return { cost, inputTokens, outputTokens, modelId }.

License

MIT