@dsh/dsh-balance
DeepSeek Harness 插件：识别当前路由背后的提供商，并查询其 API 余额或订阅配额。不使用子进程，不具备执行权限，仅使用官方端点。
插件会安装到这里；不确定时保持 web。
npx -y @deepseek-ai/dsh plugin --profile web add github:zhujiuyi/dsh-balance-meter#bb6edb838cdff6d01d93a969f1e408559d60446fBalance 以 @dsh/dsh-balance 发布，当前版本为 0.1.0。Plugin Hub 会校验它的 manifest，并保存精确安装来源，便于复现安装结果。
中文 | English
A native DeepSeek Harness (DSH) plugin: read the provider behind your current model route, then query its API balance or subscription quota.
A readout sits in the session header, with a popover listing every route. On the model side a balance_check tool lets the agent answer "how much credit is left?" on demand.
This is the DSH counterpart of ccgui-plugin-balance-meter. Because DSH exposes natively what that host lacked, this version requests no exec capability, spawns no subprocess, and probes no relay stations:
| CC GUI version | This plugin | |
|---|---|---|
| Credentials | parses each engine's config file, needs exec:curl | ctx.credentials, no shell |
| Network | host egress required a declared domain, so exec:curl | plain fetch in the host process |
| Route identity | sniffs gateway hostnames | ctx.llm.listProviders() + profile config |
The npm package is @dsh/dsh-balance. Install it from the release tarball:
dsh plugin --profile desktop add https://github.com/zhujiuyi/dsh-balance-meter/releases/latest/download/dsh-dsh-balance-0.1.0.tgz
Or straight from the repository:
dsh plugin --profile desktop add github:zhujiuyi/dsh-balance-meter
Do not run
dsh plugin add dsh-balance-meter. That unscoped name belongs to an unrelated package on npm, and the command would install that one instead.
Restart DSH. A @dsh/dsh-balance card appears on the Plugins page and the readout appears on the composer status row.
After editing the source, run the same command again to overwrite it (same package name) — no uninstall first.
Uninstall:
dsh plugin --profile desktop remove @dsh/dsh-balance
The status row under the composer — the same row as the built-in 1 turn 6 steps · 165 tok/s pills, to their left. A balance route shows money (¥12.34); a subscription shows remaining quota (每月 剩 47%). Click for a popover with:
It reports only the provider the current session actually uses. The route comes from that session's model selection (current.provider in modelDirectories), not from every adapter registered in the build — listProviders() reports built-ins like deepseek-official and deepseek-account that the user never configured, and listing those is noise.
Readings can be stale. When an automatic query fails but a previous one succeeded, the readout keeps the older figure, labels it stale, and the popover states the failure. A stale number is never presented as current.
Official domains only; no request ever goes anywhere else.
| Provider | Endpoint | Billing |
|---|---|---|
| DeepSeek | GET /user/balance | API balance |
| OpenRouter | GET /api/v1/key | API balance |
| Moonshot / Kimi | GET /v1/users/me/balance | API balance |
| SiliconFlow | GET /v1/user/info | API balance |
| 智谱 GLM / Z.AI | GET /api/monitor/usage/quota/limit | Subscription windows |
| Kimi Coding | GET /coding/v1/usages | Subscription windows |
| MiniMax | GET /v1/token_plan/remains | Subscription |
| OpenCode Go | GET /zen/go/v1/usage | Subscription windows |
The credential variable is resolved per route: an adapter-declared apiKeyEnv first, then the matching llm-* row in the profile's cordis.patch.yml, then the catalog default (e.g. DEEPSEEK_API_KEY).
The core promise is never to guess a number. Every non-success lands in exactly one of these, each saying what to do next:
| Status | Meaning |
|---|---|
no-credential | the credential variable exists but is unset — names the variable to configure |
unknown-provider | this plugin has not catalogued the route and the preset chain below missed too — which is not the same as the vendor having no endpoint |
no-public-endpoint | catalogued, and that vendor definitively has no public endpoint |
parse-failed | HTTP 200, but the response shape is unrecognised — echoes a raw response fragment |
A route outside the built-in catalogue is not given up on. A fixed sequence of conventional relay-panel endpoints is tried, and the first that yields a readable figure wins:
| # | Endpoint | Where it comes from |
|---|---|---|
| 1 | GET /api/usage/token/ | New-API ≥ v0.9.0 — remaining quota in one call |
| 2 | GET /v1/dashboard/billing/subscription | OpenAI-style billing, in cents |
| 3 | GET /v1/usage | Sub2API family |
| 4 | GET /api/v1/me/quota | claude-code-hub, which uses an X-Api-Key header |
| 5 | GET /dashboard/billing/credit_grants | CloseAI family |
| 6 | GET /api/v1/credits | — |
| 7 | GET /api/user/self | New-API variants |
Presets 1 and 7 first make one unauthenticated GET /api/status read to pick up the panel's own quota_per_unit — a New-API operator can change the accounting unit, and hardcoding 500000 would be off by orders of magnitude.
An endpoint you set outranks all of them: the value written by balance_set_endpoint or routes[].endpoint is tried first, because that is the thing you actually know. If none of the presets fit, setting one is the fix.
A 401 or 403 stops the chain — every remaining path would use the same credential.
Scope of the claim: the mechanism (order, short-circuit, calibration, fallback) is tested and every extraction path has a fixture, but the preset shapes themselves are transcribed from the reference project's panel catalogue and could not be re-verified per vendor. A preset that mismatches therefore reports parse-failed and echoes its response, rather than returning a wrong number.
Adapters name their own routes deepseek-official, deepseek-account and the like. Those resolve to the vendor's entry once the suffix is stripped, instead of being called uncatalogued — the vendor is plainly known. A genuinely unrelated id (say deepseek-proxy) is still reported as uncatalogued.
Echoing the body on parse-failed is deliberate: the eight response shapes were compiled from vendor documentation, and the author holds no keys for these vendors, so none could be verified against a live API during development. The echo is how you see what actually came back.
Echoed bodies are redacted (sk-…, Bearer …, { "api_key": … } and similar become ***) and truncated to 800 characters.
exec capability, no subprocess. No shell, no curl, no process spawning.ctx.credentials.resolve(), placed in a request header, never written to disk, logs, or the browser snapshot. The snapshot carries the credential variable name and no value — there is a test asserting this.balance_set_endpoint edits only this plugin's own row config.Plugins page → the @dsh/dsh-balance card → the form edits the primary route, the auto-refresh switch, and the minimum interval.
Route overrides (custom endpoints, different credential variables) go through the tool, or by editing the balance-meter row in the profile's cordis.patch.yml:
- id: balance-meter
name: "@dsh/dsh-balance"
config:
primary: deepseek
routes:
- id: my-provider
baseURL: https://api.example.com/v1
apiKeyEnv: MY_PROVIDER_API_KEY
endpoint: '{origin}/v1/balance'
Endpoint templates accept {origin} (the route's scheme and host) and {base} (the route's base URL). Prefer {origin}: it stays correct no matter which path segment the configured base URL carries.
balance_check — { route?, refresh? }, returning structured JSON: route, vendor, billing mode, status, figure or quota windows, endpoint, query time. With no route it queries the route the header shows.
balance_set_endpoint — { route, endpoint }, persists a custom endpoint into this profile's cordis.patch.yml, applied immediately. An empty endpoint clears the override.
Writing
routessends the plugin row through the Loader's normal lifecycle (effectively a reload), so the in-memory cache resets and the readout re-queries on its next poll. That is a schemastery structural limit rather than a choice: array elements are always validated as "blocked", so a volatile field can never appear inside an array — and since route ids are user-chosen, no schema shape would make route overrides volatile (and volatile is what buys an in-place update without a reload).
DSH host process browser
┌────────────────────────────────────┐ ┌────────────────────┐
│ @dsh/dsh-balance (host half) │ │ @dsh/dsh-balance │
│ │ │ (browser half) │
│ ctx.llm.listProviders() ─┐ │ │ │
│ llm-* rows via ├→ routes│ │ header readout │
│ configEditor ─┤ │ │ ↓ fetch │
│ built-in catalog ─┘ │ │ /api/balance- │
│ ↓ │ │ meter/snapshot │
│ ctx.credentials.resolve() │ │ ↑ │
│ ↓ │ │ │ │
│ fetch(vendor) → parse → cache │──────→│ │ │
│ ↓ │ JSON │ │ │
│ ctx.tools.register ×2 │ │ config form │
└────────────────────────────────────┘ └────────────────────┘
Refresh policy. The host holds no timer, and nothing guesses when a turn ended.
turn/end event and refreshes the current route. That event name is not guessed — it was read out of a real session.v4.jsonl.zstd ({"type":"turn/end","data":{"turn":1,"reason":{…}}}).turn/end or your own refresh.minIntervalSec (default 30s) and the failure cooldown, so a burst of turns cannot become a burst of vendor requests. A hidden page does not poll.stale, so the readout keeps showing it labelled stale with the reason in the detail panel. Only a route that has never succeeded reads as Unavailable.Caching. The endpoint that worked is cached per route; after every candidate fails the route enters a 10-minute cooldown; concurrent queries for one route coalesce into a single in-flight request.
conversation.composer.dock — the row the built-in session-stats pills use.The eight parsers were written from vendor documentation, and the author holds no keys for these vendors — only OpenCode Go has been checked against a live response, which is what fixed it:
{"usage":{"rolling":{"status":"ok","percent":0,"resetsAt":"…"},
"weekly":{"status":"ok","percent":8,"resetsAt":"…"},
"monthly":{"status":"ok","percent":53,"resetsAt":"…"}}}
percent here is a used share, not a remaining one. That is inferable rather than assumed: a live account read rolling: 0 while actively completing turns, which cannot mean "0% remaining". The remaining figure is derived from it, and the raw value is kept in the window note (原始 percent=53) so a change of convention at the vendor would be visible immediately.
If any of the other seven disagrees with its documentation, it reports parse-failed and echoes the response — send that echo and it can be corrected.
npm run verify # static contract check + the full test suite
npm test # 209 tests, no DSH required
npm run check # static contract check only
Tests come in three layers, all runnable without DSH:
@deepseek-ai/* packages and the real apply() runs, covering tool registration, credential resolution, the snapshot route, and config writes.package.json, cordis.patch.yml and the browser half checked for self-consistency: every bare import declared, the bundle patch naming this package, the module id equal to the package name, and files shipping both entry points.test/config-schema.test.mjs) — validates Config's volatile paths against a stub that mirrors the real rule. Mirroring it rather than waving it through matters: a structurally invalid Config fails no behavioural test, it just stops the plugin activating in a user's install. routes[].id escaped that way once.The design spec is at docs/superpowers/specs/2026-10-14-dsh-balance-meter-design.md (Chinese).
MIT