English | 简体中文
dsh-balance-monitor
DeepSeek balance and spend windows, right in the dsh sidebar footer.
A minimal DeepSeek Harness (dsh) plugin that shows the current session's channel balance/usage in the sidebar footer, styled with the stock design tokens. The DeepSeek official channel shows balance plus today / 7-day / 30-day spend windows (official usage data when a platform token is set); the Volcano Ark channel shows Agent Plan quota bars (5h / weekly / monthly).
<p align="center"> <img src="docs/preview/balance-wide.png" alt="dsh-balance-monitor in the sidebar footer" width="280"> <img src="docs/preview/balance-rail.png" alt="dsh-balance-monitor collapsed to the rail" width="56"> </p>
Features
| What | How |
|---|---|
| Live balance | Queries GET https://api.deepseek.com/user/balance through the host half, using the DEEPSEEK_API_KEY from $DSH_HOME/.credentials.yaml (env var wins) |
| Today / 7d / 30d spend (official) | With DEEPSEEK_PLATFORM_TOKEN set, the host queries the official usage API platform.deepseek.com/api/v0/usage/cost (the same data the platform console shows) and sums per-day windows: 7d = today minus 6 days, 30d = today minus 29 days (both inclusive). Accurate no matter where else the API key is used |
| Balance-delta fallback | Without the platform token (or when the official API fails), today falls back to a balance-drop ledger (only accumulating drops; refills never inflate or wash out spend); 7d/30d show — |
| Channel awareness | The card follows the current session's model provider: the DeepSeek official channel shows balance/spend; the Volcano Ark channel shows Agent Plan bars; other channels show a "channel not supported" placeholder; no session renders nothing |
| Volcano Ark Agent Plan | With AK/SK configured, calls the GetAFPUsage control-plane API (SigV4 signed) and shows 5h / weekly / monthly quota bars, colored by usage (green → amber → red) |
| Placement | Registered on the official sidebar.footer.action slot — above Settings, no patch hacks |
| Collapsed rail | Shrinks to a 36px circle with a compact balance and a tooltip |
| Resilience | 60s polling + re-poll on tab visibility; on upstream failure the last known numbers stay visible (dimmed as stale) instead of an error flash |
Install
Works from source directly — the browser bundle is a hand-written classic script with no build step, so a git install needs no prepare script:
dsh plugin --profile web add "github:alanzhao0128/dsh-balance-monitor#main"or from npm (once published):
dsh plugin --profile web add dsh-balance-monitorThen restart the Web UI (dsh --profile web). The widget appears at the bottom of the expanded sidebar, above Settings.
Configuration
Both credentials live in $DSH_HOME/.credentials.yaml (write them from the Web UI Models page, or edit the file directly):
| Credential | Required | Purpose |
|---|---|---|
DEEPSEEK_API_KEY | ✅ | Balance lookup api.deepseek.com/user/balance |
DEEPSEEK_PLATFORM_TOKEN | optional | Official usage (today/7d/30d). Get it: sign in at platform.deepseek.com → DevTools Console, run JSON.parse(localStorage.getItem('userToken')).value, store the output as the credential |
> ⚠️ DEEPSEEK_PLATFORM_TOKEN is a web-session token and expires (the official API returns code 40002/40003 when stale). On expiry the plugin silently falls back to the balance-delta estimate; refresh the token from the console and update the credential. Balance lookup is unaffected.
| Credential | Required | Purpose |
|---|---|---|
ARK_ACCESS_KEY_ID | Volcano Ark channel | Volcengine access key for the control-plane API (Agent Plan quota) |
ARK_SECRET_ACCESS_KEY | Volcano Ark channel | Volcengine secret access key |
> Get Ark AK/SK: sign in at console.volcengine.com → Access Control → API Access Keys → create a key. Note: AK/SK are IAM account-level credentials that can operate all resources — keep them private.
How it works
One combined plugin row (dsh.bundle patch + dsh.client roster declaration):
- Host half (
lib/index.js) — registers two RPC channels (loopback trust fence) onctx.connection:/balance(DeepSeek balance + official usage windows + fallback ledger) and/ark-quota(Volcano Ark Agent Plan quota, signed with AK/SK SigV4 againstGetAFPUsage, cached for 40s — strictly below the browser's 60s poll so every poll triggers a fresh upstream fetch). - Browser half (
lib/client.js) — a zero-dependency classic-script bundle registering asidebar.footer.actionentry. It tracks the current session's provider viasessions.listsubscription plus a light 1s poll ofsession.models(a local RPC), then dispatches through the channel registry:deepseek-officialrenders the balance card (60s polling, re-poll on tab visibility);huoshanrenders the Ark quota bars; unregistered channels render the unsupported placeholder; no session renders nothing. Thellm/adapters-updatedremote event triggers an immediate re-check.
State file ($DSH_HOME/storages/balance-monitor.json):
{
"date": "2026-08-17",
"dayStart": 100.0,
"lastTotal": 97.7,
"lastCurrency": "CNY",
"spent": 1.65,
"spent7d": 5.24,
"spent30d": 18.54,
"spentSource": "official",
"updatedAt": 1755400000000
}spentSource is official (platform API) or estimate (balance-delta ledger).
Security notes
- The API key, platform token, and Ark AK/SK never leave the host: the browser half only ever sees balance/spend/quota numbers over the RPC channel, never the credentials.
- The channel is served under the
loopbacktrust authority. - No telemetry, no network beyond the official balance, usage, and Ark quota endpoints.
Layout
dsh-balance-monitor/
├── package.json # dsh.bundle (patch) + dsh.client (browser roster)
├── cordis.patch.yml # inserts the one combined plugin row
└── lib/
├── index.js # host half: /balance + /ark-quota RPC channels
├── client.js # browser half: sidebar footer card (hand-written, no build)
└── signature.js # Volcengine OpenAPI SigV4 signing (AK/SK)Development
No toolchain required. Edit lib/*.js directly; the bundle format mirrors what the official tsdown preset emits (window.__ModuleLoader__.load({ id, factory })).
License
MIT