Preface¶

When running multiple sessions and models in DeepSeek Harness (DSH), token consumption is scattered across various llm/stream calls, making it difficult to answer questions like “How much did I spend this month?” or “Which sessions consumed the most?” afterward. The official console provides a balance, but the correspondence between it and local Harness sessions is not intuitive.

Below, we introduce the community plugin dsh-usage-billing (maintained by 940842546): it monitors all local session model calls, calculates fees based on DeepSeek’s official tiered pricing, and provides a graphical usage dashboard in the main interface and settings page. The current version is 0.6.0, licensed under MIT, with approximately 9 stars on GitHub.

What is This¶

dsh-usage-billing is a build-free two-part plugin for DeepSeek Harness (Host side: lib/index.js + Client side: lib/client.js). It automatically tracks all DeepSeek model calls from local sessions, categorizes them into three pricing tiers based on Beijing time (“pre-price-adjustment old price / post-price-adjustment peak / post-price-adjustment off-peak”), and persists data to .dsh-usage-billing.json in the writing policy root directory (before v0.5.4, it was .dsh-usage-stats.json; automatic migration occurs upon upgrade).

The billing criteria are as follows: before 2026-08-17 00:00 (Beijing time), the old pricing applies; after that, peak and off-peak pricing are used—peak hours are weekdays 9:00–12:00 and 14:00–18:00 (effective from 2026-08-23; weekends were previously counted as peak), and off-peak pricing is half of the peak price.

Core Features¶

Statistics and Billing¶

• Fully Automatic Statistics: Listens to llm/stream, recording input/output/cache hit/miss tokens for each call.
• Historical Backfill: On first startup, scans local session logs to reconstruct historical usage and costs, including session titles.
• Tiered Billing: Automatically categorizes into three pricing tiers based on Beijing time; models are classified by name substring (those containing flash fall under the flash tier, those containing pro under the pro tier, and the rest are categorized as “unpriced/free”).
• Configurable Pricing: Price tables, peak hours, price adjustment boundary dates, and USD exchange rates are editable (changes apply only to subsequent calls), with support for one-click restoration to defaults.

Interface and Interaction¶

• Main Interface: A “Token Usage” card at the bottom of the sidebar (showing current model and session tokens/costs) → clicking opens the “Token Usage and Cost Statistics” popup (¥/USD toggle, overview, tables by model/session, budget progress, official balance, tier proportion, usage heatmap); a persistent row below the input box displays current session usage.
• Settings Page → Usage Statistics: Statistics card, budget progress, tier proportion, daily/weekly/monthly/yearly/cumulative heatmaps, top 8 sessions (clickable to open corresponding sessions), by model, recent calls, backfill/clear/export, billing and budget settings.
• Bilingual Support: Interface text switches according to the application language setting.

Budget, Balance, and Export¶

• Budget Alerts: Desktop toast reminders when crossing 80%/100% thresholds (once per day per tier); the progress bar turns orange near the threshold and red when over budget; the settings page displays recent alert records.
• Official Balance Fetch: Detects configured DeepSeek API Keys to fetch account balance (total balance/top-up/gratuity), refreshing every 10 minutes; silently skips if no Key is configured.
• Balance Endurance Estimate: Estimates available days and projected depletion date based on average daily spending over the last 7 days.
• Data Export: One-click export to CSV (by day/session) or JSON, with filenames containing the date range.

Dynamic Tools and Robustness¶

• Dynamic Tool usage_billing: Models can directly query statistics, supporting ranges like today / month / all (e.g., “How much have I spent now?” “What about today?”).
• Write Protection: Statistics files include a temp copy; automatic recovery occurs if the main file is corrupted; heartbeat detection for dual instances with alerts.

Installation and Activation¶

Recommended via one-click npm installation (pre-built package):

dsh plugin --profile web add dsh-usage-billing

npm package address: https://www.npmjs.com/package/dsh-usage-billing

The plugin automatically mounts on application startup via the package’s dsh.bundle.patch (cordis.patch.yml), requiring no additional configuration. If the panel does not appear after installation, restart the application and refresh the page (the client bundle is discovered by the clientModules service).

Local path format is also supported:

dsh plugin --profile web add <this repository path>

Alternatively, add the contents of the repository root’s cordis.patch.yml to the user-level patch %USERPROFILE%\.dsh\cordis.patch.yml:

- insert:
    - id: usage-billing
      name: 'dsh-usage-billing'

Note: Do not directly modify the official bundle (e.g., @deepseek-ai/dsh-web-app/cordis.patch.yml), and do not place the plugin in the npm-cache\_npx cache.

Typical Usage¶

Viewing Main Interface Usage¶

After installation and restart, a “Token Usage” card appears at the bottom of the main interface sidebar. Clicking it opens the statistics popup, where you can toggle between ¥/USD in the top right corner. A persistent row below the input box displays the current session’s tokens and costs.

Settings Page Details and Export¶

Navigate to Settings → Usage Statistics to view the last 30 days’ daily trends, heatmaps, session/model rankings, and perform backfill, clear, or export to CSV/JSON.

Allowing the Model to Query Costs¶

The plugin registers a dynamic tool usage_billing, enabling direct queries about usage in conversations, such as checking today’s or monthly cumulative costs (range parameters support today, month, all).

Billing Reference¶

Pricing units are yuan / million tokens (extracted from the README; full table see repository):

Official pricing reference: DeepSeek API Pricing

Use Cases and Notes¶

Who is this for: Developers who need to continuously track token consumption and costs on local DSH for budget management or reconciliation.

Usage Notes:

• The plugin runs with the current DSH process permissions. Before installation, review the source code and MIT license.
• Statistics files are located in the writing policy root directory (typically the user’s home directory). Running multiple instances simultaneously will overwrite each other’s data, so maintain a single instance.
• If older versions show doubled statistics, v0.2.0 and later automatically perform a one-time reconstruction fix on restart via the schemaVersion migration marker.

The DSH ecosystem follows an “everything is a plugin” approach; the community directory SkillHub is an independent site with no official affiliation with DeepSeek / High-Flyer.

Links¶

• Community directory page: https://www.skillhub.cn/plugins/940842546/dsh-usage-billing
• GitHub repository: https://github.com/940842546/dsh-usage-billing

If you’ve been running long-term multi-session tasks on Harness, this plugin can consolidate scattered token calls into readable bills and charts, proactively alerting you when approaching budget limits.