dsh-quota-panel
English | 中文
Provider quota / balance status widget for the dsh web surface (DeepSeek Harness).
A zero-dependency host plugin: for every configured provider it registers one server-side proxy route /api/quota/<id> — the API key is resolved through the credentials seam and never reaches the browser — then injects a small Harness-native status widget (bottom-right) with two sizes:
- Collapsed (default) — a minimal glanceable capsule: one independent
"status dot + value" pair per account (e.g. ● ¥58.36 · ● 45%), no text labels — only the affected account's dot changes color. Click to expand.
- Expanded — the full card: "模型额度" header with refresh/collapse
buttons, then one structured row per provider (status dot, name, primary value, secondary line, progress bar for usage-style providers). The collapse button shrinks it back.
Both sizes auto-refresh (paused while the page is hidden; the refresh button spins while a manual refresh runs and re-entrant clicks are ignored).
In the capsule, usage percentages are battery-colored (green when healthy, amber when tight, red when critical), matching their independent dot; balance values are tinted only when their own state warns or errors.
The widget is styled with the Harness design tokens (--dsw-alias-*, --dsw-static-*, --dsw-shadow-*, --dsw-font-*) and falls back to sensible values when tokens are absent, so it follows the product theme (light/dark) instead of carrying its own palette.
Screenshots
Collapsed capsule (light / dark):
 
Expanded card (light / dark):
 
Full page, collapsed capsule (light / dark):
 
Install
dsh plugin --profile web add "github:brittanistrehlowll-oss/dsh-quota-panel"
# restart `dsh web` (bundle layers apply at boot)The package declares dsh.bundle.patch, so dsh plugin add activates it as a profile layer automatically.
Configuration
Each provider is one entry under providers. Two renderers ship:
| format | endpoint shape | row | |---|---|---| | deepseek-balance | { "balance_infos": [{ "currency", "total_balance", "granted_balance", "topped_up_balance" }] } | ¥58.36 + 余额充足/正常/紧张/建议充值 | | opencode-usage | { "usage": { "rolling"\|"weekly"\|"monthly": { "percent", "resetsAt" } } } | 五 10% · 周 45% · 月 22% + progress bar + 当前最高占用 |
Override the shipped defaults in your profile's cordis.patch.yml:
- id: quota-panel
config:
refreshMs: 30000
providers:
- id: deepseek
label: DeepSeek
credential: DEEPSEEK_API_KEY
endpoint: https://api.deepseek.com/user/balance
format: deepseek-balance
balanceTiers: { critical: 10, warn: 20, healthy: 50 }
- id: opencode-go
label: OpenCode Go
credential: OPENCODE_GO_API_KEY
endpoint: https://opencode.ai/zen/go/v1/usage
format: opencode-usage
windowLabels: { rolling: 五, weekly: 周, monthly: 月 }
warnPercent: 70
errorPercent: 90Fields:
| field | meaning | default |
|---|---|---|
id | route id (/api/quota/<id>), ^[a-z0-9-]+$ | required |
label | provider name on the card | required |
credential | credential reference ($DSH_HOME/.credentials.yaml or env) | required |
endpoint | quota JSON endpoint, GET with Authorization: Bearer <key> | required |
format | row renderer | deepseek-balance |
balanceTiers | (deepseek-balance) {critical, warn, healthy} levels | {10, 20, 50} |
lowBalance | legacy alias for balanceTiers.warn | — |
windowLabels | (opencode-usage) {rolling, weekly, monthly} | {滚, 周, 月} |
warnPercent / errorPercent | (opencode-usage) thresholds | 70 / 90 |
refreshMs | auto-refresh interval | 60000 |
DeepSeek balance levels
With the default balanceTiers {critical: 10, warn: 20, healthy: 50}:
| balance | state | secondary line |
|---|---|---|
<= 10 | error (red dot + value) | 建议充值 |
10 < x <= 20 | warn (amber) | 余额紧张 |
20 < x <= 50 | ok | 余额正常 |
> 50 | ok | 余额充足 |
OpenCode usage states
high = max(rolling, weekly, monthly):
| usage | state |
|---|---|
< warnPercent | ok (green dot, DeepSeek-blue progress) |
>= warnPercent | warn (amber dot + progress) |
>= errorPercent | error (red dot + progress) |
Changelog
- v0.3.0 — Two sizes: collapsed capsule (independent per-account dot +
battery-colored value) expands into the full card.
- v0.2.0 — Harness-native card: design tokens, balance tiers, progress bar.
- v0.1.0 — Initial floating panel: server-side quota proxies + page badge.
Security
- API keys are resolved server-side via
ctx.credentialsand only used in the
server-to-provider request; the browser only talks to /api/quota/<id>.
- The injected card builds DOM with
createElement/textContentonly; API
response values never pass through innerHTML. Technical errors (401, timeout, credential missing) go into title hover text, not the card body.
Local development
# Regenerate demo pages docs/demo.html + docs/demo-dark.html
node scripts/gen-demo.mjs
# Headless screenshots via Chrome DevTools Protocol
node scripts/shoot.mjs both
# Verify the rendered DOM of a demo page
node scripts/verify.mjs [dark]
# Syntax + content checks for the injected page script
node scripts/test-page-script.mjsLicense
MIT