Preface¶

Connecting to multiple model providers simultaneously is a common scenario for DSH users: Kimi For Coding uses subscription quotas, DeepSeek Official deducts balance based on usage, and OpenRouter tracks points. To know “how much is left and how much was spent this month,” one typically has to log in to each provider’s console separately, switching back and forth. After checking one round, the work at hand is long since interrupted.

dsh-token-monitor brings this into DSH Web: a permanent balance badge in the session header, an extra “Usage” tab in the main area, and local SQLite recording the token usage and estimated costs for each call. Below is an introduction to its features, installation, and configuration.

What is it¶

dsh-token-monitor is a Large Model Balance and Usage Monitor plugin for the DSH Web interface, by author licyer, version 1.0.2, MIT license. It solves a specific problem: balance and usage data are scattered across various provider consoles, and cannot be seen in DSH.

The plugin does three things:

1. Display the current provider’s balance in real-time in the session header;
2. Provide a “Usage” tab parallel to “Chat/Trajectory” in the main area, with statistics for tokens, estimated costs, and usage trends;
3. Automatically collect DSH session logs, recording the token and cost of each call into a local SQLite (token-monitor.db).

Core Features¶

Balance Badge¶

The badge displays the current provider’s balance, formatted like k3 · 5h remaining 82%. The display logic differs for two types of providers:

1. Subscription providers (e.g., Kimi For Coding): shows rolling window and weekly quota percentages;
2. Pay-as-you-go providers (e.g., DeepSeek Official): shows account balance.

Clicking the badge opens a detail layer containing current provider metrics, this session’s token usage (can switch sessions), a collapsed section for all providers, a cc-switch data sync hint bar, update time, and manual refresh.

Usage Tab¶

The “Usage” tab is parallel to “Chat/Trajectory”. At the top are filters (Client / Provider / Model cascade, providers grouped by vendor) and time windows (Today / Yesterday / 7 / 30 / 90 days / All). The stats cards show total consumption, request count, estimated cost, average TTFT, new input, cache hits, output, and cache hit rate. Going down sequentially:

• Usage Trend: Gradient area chart, left axis token composition, right axis switchable between estimated cost / request count; daily view has minute-level scale (2~60 min adaptive, at least 12 buckets, no bucket crossing days), hover tooltip shows bucket interval (e.g., 15:00~15:30);
• Provider Consumption Stats: X-axis is provider, stacked by model within bars, right side switchable between cost / count;
• Annual Usage Heatmap: GitHub calendar style, covering the last 12 full months, color depth corresponds to daily tokens, beginning and end filled by week;
• Usage Ranking: Aggregated by Model / Provider / Client three dimensions, default sorted by total consumption descending;
• Request Records: Paginated detail table, time reversed, page number jump, rows per page selectable 10/20/50/100.

Auto-Collect and Storage¶

The plugin automatically collects session logs under $DSH_HOME/sessions, incrementally writing to local SQLite (token-monitor.db). Collection is triggered by background timers, manual refresh, and opening tabs; page queries read directly from the database. Data stays local.

History Import and Cross-device Sync¶

Two entry points for replenishing data:

1. cc-switch history record import, repeated import does not generate duplicate data;
2. JSON snapshot export/import (includes details and aggregation), allowing merging usage records from different devices onto one device, idempotent and non-repeating.

Both entry points are under “Data Source” at the bottom of the “Usage” tab.

Language Following¶

Interface copy follows DSH’s Chinese/English toggle, no separate setup required.

Installation and Enablement¶

Prerequisites: Node.js ≥ 22 (relies on built-in node:sqlite), and only supports DSH Web (platform: web). Install from npm (recommended):

dsh plugin --profile web add dsh-token-monitor

Can also install from GitHub:

dsh plugin --profile web add github:licyer/dsh-token-monitor

Installation automatically registers, writing bundles and dependencies to the profile’s package.json, no need to manually edit config. After the steps above, it takes effect after restarting the dsh web process. The balance badge should appear in the session header, and the “Usage” tab should appear in the main area.

Credential Configuration¶

Balance queries read DSH’s existing credentials, written in ~/.dsh/.credentials.yaml, or provided via environment variables, such as DEEPSEEK_API_KEY, KIMI_CODING_API_KEY. When credentials are not configured, the badge will prompt “API Key not configured”; it will automatically recover after configuration.

Plugin Configuration¶

The config file is located at $DSH_HOME/storages/token-monitor/config.json. The settings entry is in DSH’s settings panel (bottom-left gear) → Token Monitor page. The form saves back to the file immediately. There are three settings items:

Below the settings page is also an adapted provider list, indicating which providers are adapted and whether the developer has verified with real credentials.

When encountering endpoint drift (provider API address changes, common 404), you can override the endpoint address in the plugin configuration using providers.<id>.url.

Provider Adaptation¶

The latter two groups have passed mock testing but have not been calibrated with real keys; if the actual response structure differs from the reference implementation, you can submit the raw original text returned by the interface to help calibrate.

Frequently Asked Questions¶

Badge not showing or prompts “Query Failed”¶

First look at the text: “API Key not configured” means credentials are not set, just fill them in according to the credential configuration above; “Query Failed” means credentials are configured but the balance interface query failed. Troubleshoot item by item: network unreachable or timeout, endpoint drift (use providers.<id>.url to override), or response field structure abnormal causing parsing failure. If it prompts “Plugin not adapted to this provider”, it is an adaptation scope issue, unrelated to the above.

Usage tab has no data¶

Usage comes from session log collection: first confirm that there are session logs under $DSH_HOME/sessions, then click “Refresh” at the top (collect first, then query); cc-switch data needs to be manually imported in “Data Source”.

Is the cost accurate¶

Costs are estimated based on local list prices from pi-ai, for reference only, not actual bills; subscription plans do not generate real deductions; und priced models are counted in tokens but not in cost.

Local Development¶

After cloning the repository, mount it with a local path:

git clone https://github.com/licyer/dsh-token-monitor.git
dsh plugin --profile web add link:/path/to/dsh-token-monitor

Modify frontend (lib/client.js) to use HMR hot swap, refresh to apply; modify backend (lib/index.js / lib/util/) requires restarting the dsh web process.

Suitable Scenarios and Precautions¶

Suitable for developers who use both subscription and pay-as-you-go providers simultaneously and want to see balance and usage details directly in DSH Web; also suitable for those who need to retain call records locally and perform cross-device merging.

Notes before use:

1. The plugin runs with the permissions of the current dsh process; it is recommended to check the source code and license (MIT) before installing;
2. Costs are estimated based on local list prices, do not use as a reconciliation against bills;
3. The minimax and zai groups of adaptations have not been verified with real keys; results are subject to the actual situation;
4. Only supports Web platform, Node.js version must be ≥ 22.

Related Links¶

DSH’s philosophy is “Everything is a plugin”, dsh-token-monitor brings balance queries and usage statistics into the same interface, keeps data local, and installation only requires one command.

• GitHub Repository: https://github.com/licyer/dsh-token-monitor
• Community Directory Entry: https://www.skillhub.cn/plugins/licyer/dsh-token-monitor (The community directory is an independent site and has no official affiliation with DeepSeek / Huanfang)