Introduction¶

The plugin architecture of DSH breaks the extensibility of the Web GUI into installable, removable packages. When using DSH for model calls, local usage, balance, and cost estimates are often scattered in different places. dsh-billing centralizes this monitoring into the DSH Web GUI: the sidebar displays the balance, the settings page manages unit prices and ledgers, and the Agent can query balance and usage.

What is this¶

dsh-billing is a real-time billing monitoring plugin for the DSH Web GUI. It tracks local model call usage and costs, billing based on provider and model unit prices. It supports DeepSeek v4 peak-valley pricing, official balance synchronization, official unit price synchronization, and ledger persistence. The account in the repository is nianpangzhi233, and the license is MIT. The plugin is implemented via the official interface and the client slots system, without modifying DSH source code.

Core Features¶

Real-time Balance¶

A balance pill appears at the bottom of the sidebar, with a refresh cycle of 2 seconds. The balance status dot distinguishes “Sufficient / Insufficient / Exhausted”, and flashes when an alert occurs.

Overview Panel¶

After clicking the balance pill, a panel expands within the sidebar, showing consumed amount, call count, input tokens, output tokens, and recent transactions. Transactions carry peak-valley labels. The panel automatically collapses when the sidebar is collapsed.

Providers and Peak-Valley Unit Prices¶

The unit price matching order is:

Provider+Model → Same Name Model → Provider Default → Global Default

DeepSeek v4 has adopted peak-valley pricing since 08-17: Peak hours are Beijing 9–12 and 14–18, with idle times priced at half rate; cache hits for input are charged at a lower unit price.

Official Balance and Unit Price Synchronization¶

After entering a DeepSeek API Key, you can call the official interface:

GET /user/balance

This fetches total balance, bonus credit, and top-ups, and automatically anchors to the plugin balance; manual paste calibration is also supported.

Official unit price synchronization allows one-click fetching of DeepSeek’s official model unit prices, merged based on built-in base prices and persisted overrides. This capability only takes effect when the official price page is accessible and requires the platform web provider.

Settings Page and Agent Tools¶

A “Billing” section will appear in DSH settings, covering:

Balance, Threshold, Default Unit Price, Provider Unit Price Table, Data Management

Tool descriptions will automatically appear in the Agent prompt:

billing_balance

It is used to query balance, costs, token usage, and details by model.

Persistence¶

The ledger JSON is written atomically to the workspace. DSH will automatically restore balance, unit prices, and transactions after restart.

Installation and Enablement¶

First, confirm that the local environment meets the following requirements:

Node: ^22.19.0 || >=24.0.0
peerDependencies:
- @deepseek-ai/cordis ^4.0.1
- @deepseek-ai/dsh-tools ^0.1.0-rc.6
- react ^18.2.0
- react-dom ^18.2.0

This package is pure JavaScript with no build steps. lib/ is the published artifact; it works with a simple git install without a prepare script or build authorization.

Install from repository:

dsh plugin --profile web add github:nianpangzhi233/dsh-billing

Local checkout or tarball installation is also possible:

dsh plugin --profile web add ./dsh-billing
dsh plugin --profile web add ./dsh-billing-0.1.0.tgz

After the above steps, restart dsh web. Afterwards, a balance pill will appear at the bottom of the sidebar, a “Billing” section will appear in DSH settings, and the billing_balance tool description will automatically appear in the Agent prompt.

Typical Usage¶

Enter the configuration entry point:

DSH Settings → "Billing" section

You can also click the balance pill at the bottom of the sidebar to expand the panel.

Configure Balance: Use DeepSeek API Key to automatically sync official balance, or manually paste to anchor; you can also set an initial balance and a low-balance alert threshold, with a default threshold of ¥20.
Configure Unit Prices: Set a default unit price for unknown providers (unit: ¥ / 1M tokens); maintain a provider/model unit price table with add/delete row capabilities; click “Sync Official Unit Prices” to fetch DeepSeek’s official pricing when needed.
Manage Data: View ledger path and save time, save configuration, reset usage; resetting usage requires two clicks for confirmation.
Query Usage: Use the billing_balance tool in the Agent to query balance, costs, token usage, and details by model.

Data and Environment¶

The ledger file is:

.dsh-billing-ledger.json

The lookup order prioritizes the workspace directory, falling back to spRoot. The v2 structure contains:

config / usage / ledger / startedAt

Token usage is counted separately:

inputTokens
cacheReadTokens
outputTokens

Route restrictions are:

/api/dsh-billing/*

Restricted to loopback with same-origin validation.

Applicable Scenarios and Notes¶

Only tracks local DSH model calls; official balance includes consumption from other channels, so periodic sync calibration is recommended.
The API Key is stored in plaintext in the local ledger file, using the same trust model as ~/.dsh/dsh-ssh.json, with file permissions set to 0600; sync requests are only sent to api.deepseek.com, and only the balance field is taken from the response.
Billing results are estimates, with unit prices and rates based on the official DeepSeek rates.
The plugin runs with the permissions of the current dsh process. It is recommended to check the source code, license (MIT), and dependency requirements before installation.
The DSH plugin ecosystem emphasizes pluggability. The community directory is an independent site and is not equivalent to the official app store.

Conclusion¶

The value of dsh-billing lies in putting the local DSH usage, balance, and cost estimates into the Web GUI and Agent tools for easy viewing during daily use.

GitHub:

https://github.com/nianpangzhi233/dsh-billing

If installed via the DSH plugin directory, you can find the specific entry by searching for the plugin name dsh-billing.

dsh-billing: DSH Web GUI Real-time Billing Monitoring Plugin