dsh-balance-quota (dsh-balance)

dsh-balance-quota displays provider balance or quota below the DSH chat composer. It can also consume third-party JSON status APIs and show model health, availability, TTFT, response time, history, and custom metrics.

Current development version: 0.3.5 · Previous npm release: 0.3.3

DSH compatibility: 0.3.4 requires DSH 0.1.5-rc.1 or newer (@deepseek-ai/dsh-settings ≥ 0.1.5-rc.2), which removed the settingsNamespace() helper in favour of passing the namespace string straight to settings.register(). Use 0.3.3 on DSH 0.1.4 and older.

Complete feature map

Area	Features
Official presets	DeepSeek balance and OpenCode Go rolling/weekly/monthly quota
Custom balance	Public HTTPS, GET/bodyless POST, custom headers, timeout, refresh interval
JSON extraction	Property paths, array indexes, optional chaining, up to five ?? fallbacks
Amount handling	Static/dynamic currency, amount divisor, unsaved-draft testing
Status bar	Balance, update time, force refresh, and health entry below the composer
Provider selection	Default provider, inline switching, per-conversation memory
Model settings	Model catalog, context window, text/image input, reasoning levels
Health monitoring	External JSON API, status, availability, TTFT, response time, history
Visual binding	Select a preview slot, then select a JSON field; preview updates immediately
All-model preview	Preview up to 50 models with current mappings without another request
Transforms	Text, number, percentage, status, status-value maps, percentage multipliers
Number formatting	Per-field input unit, display unit, and 0–2 decimal places
Custom fields	Error rate, empty response, common errors, or any model metric
Cache and refresh	Shared Host balance cache, health-preview cache, pause while hidden
Credential security	Reuses DSH credential refs; API keys never enter browser configuration
Network security	Public HTTPS, DNS pinning, rebinding protection, private-IP/redirect blocking

Installation

Requires Node.js 22+ and the DSH CLI.

dsh plugin --profile web add dsh-balance-quota
dsh web

Restart dsh web after installation or upgrade. Verify installation with:

dsh plugin --profile web list

Complete walkthrough

All seven screenshots come from the current plugin running in DSH Web. Provider names, URLs, balances, and model names were replaced with demo values; the UI layout and controls were not redrawn.

1. Where to configure balance

Open Settings → Plugins → Plugin configuration → 供应商状态 (Provider Status).

This page controls balance queries, provider editing, Advanced Settings, the default provider, the chat status bar, and manual refresh.

• DeepSeek and OpenCode Go can use built-in official presets.
• Click 编辑 (Edit) for a custom balance API.
• 高级设置 (Advanced Settings) contains Model Settings and Health Monitoring.
• The default-provider option controls new conversations.
• The status-bar option controls the strip below the chat composer.

2. Edit a balance provider

Click 编辑 (Edit) on a provider row:

Configure the display name, endpoint, GET/bodyless POST, balance JSON path, static or dynamic currency, amount conversion, headers, refresh interval, and timeout.

Balance: $.remaining ?? $.quota?.remaining ?? $.balance
Currency: $.unit ?? $.quota?.unit ?? "USD"

测试 (Test) validates only the current unsaved draft. It does not write formal configuration, credentials, or production cache. Save after the result is correct.

3. Advanced Settings tab 1: Model Settings

Click 高级设置 (Advanced Settings). The first tab is 模型设置 (Model Settings):

It manages the provider's model ID/display name, context window, text/image input capabilities, and default/available reasoning levels.

This is separate from balance and health: Edit owns balance settings; the second Advanced Settings tab owns external monitoring.

4. Advanced Settings tab 2: Health Monitoring

Switch to 健康监测 (Health Monitoring):

Setup flow:

1. Enable health monitoring.
2. Select a custom request.
3. Enter a public HTTP or HTTPS GET JSON endpoint.
4. Click 测试 (Test).
5. Inspect the full JSON tree on the left.
6. Bind fields and preview status on the right.
7. Use 预览全部模型 (Preview all models) to validate every mapping.
8. Save the monitor.

Health monitoring reads third-party monitoring data. It does not invoke chat models or consume model quota.

Field binding

Bind the model list first: select the Model List slot on the right, then select an array such as $.models on the left.

Field	Example path	Purpose
Model name	$.model	Card title
Group	$.group	Group badge
Status	$.status	Healthy, failed, warning, unknown
Availability	$.availability	Current availability
TTFT	$.ttft_ms	Time to first token
Response time	$.latency_ms	Request duration
History array	$.history	Recent records
History status	$.state	Per-record state
History time	$.time	Per-record timestamp
History error	$.message	Per-record error

Transforms, status maps, and numeric formatting

• Text displays the original value.
• Number converts numeric values and applies units and precision.
• Percentage supports automatic scaling, forced ×100, or raw value plus %.
• Status converts values into healthy, failed, warning, or unknown.

Custom status values can use 值映射 (Value mapping):

healthy → healthy
warning → warning
offline → failed

Selecting Number for a custom field reveals three settings:

Setting	Values
Input unit	ms, s
Display unit	follow input, ms, s
Decimal places	0, 1, 2

For example, 1250ms displayed as seconds with two decimals becomes 1.25s. Settings are stored independently per field.

5. Where the status bar appears

Enable 状态栏 (Status bar) at the bottom of Provider Status, then return to any conversation. It appears directly below the chat composer:

From left to right: health dot, current provider, balance/quota, update time, force refresh, and the health-monitor icon.

6. Switch providers

Click the provider name in the status bar:

• The active provider has a check mark.
• Selection is remembered independently per conversation.
• New conversations use the configured default provider.
• ↻ bypasses cache and refreshes the current balance immediately.

7. View health after enabling monitoring

After health monitoring is enabled and saved for the current provider, an ECG icon appears next to refresh. Click it to request the endpoint and open details:

The dialog shows model/failure/warning counts, group and status, availability, average TTFT and response time, custom metrics, recent-history bars, and manual refresh.

Health represents the third-party monitor, not the current account itself.

Refresh and caching

• Each balance provider has its own refresh interval; default is 30 minutes.
• Automatic refresh pauses while the page is hidden.
• Multiple conversations share Host balance cache.
• Manual refresh bypasses cache.
• Health JSON previews are cached per monitor.
• Deleting a monitor deletes its preview cache.

FAQ

The status bar is missing

Configure at least one provider, enable Status Bar at the bottom of Provider Status, and restart dsh web after installation or upgrade.

The health icon is missing

Enable, test, and save Health Monitoring under Advanced Settings. The icon only appears when the current provider has an enabled health monitor.

Saving reports invalid external custom field

Bind the model list first, then select a field inside a model item. Name and path must be non-empty; $.last_errors[0] is valid. Version 0.3.3 trims whitespace and ignores unfinished blank fields.

A query fails

Confirm the endpoint is public HTTP(S) without redirects, the credential ref resolves, and JSON paths match the response. Private, loopback, and internal destinations are rejected.

Security boundary

• API keys are managed by DSH credentials and never enter browser configuration.
• Only public HTTP/HTTPS is allowed (set DSH_BALANCE_ALLOW_HTTP=0 to require TLS).
• Resolved public IPs are pinned to reduce DNS-rebinding risk.
• Private/loopback addresses, redirects, dangerous headers, and oversized responses are rejected.
• JSON paths reject __proto__, constructor, and prototype.
• Health monitoring does not execute page scripts, discover hidden browser APIs, or support Cookie/authenticated monitor endpoints.

See SECURITY.md.

Development and verification

packages/dsh-balance is the only public package.

pnpm install
pnpm dev:install
pnpm check
pnpm test
pnpm pack:check
pnpm verify

Project layout

packages/dsh-balance/
├── lib/host/       # Secure queries, validation, cache, config, health normalization
├── lib/client/     # DSH Web status bar and settings UI
├── docs/images/    # Real redacted README screenshots
├── test/           # Unit and security tests
├── README.md       # npm package guide
└── SECURITY.md     # Security boundary

License

MIT