Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture and supports a Web GUI. When developing or using DSH, developers often need to precisely track the cost of API calls, including per-session real-time spending, itemized details, and account balance. Existing Web interfaces lack this kind of fine-grained billing display, making cost estimation difficult. The dsh-token-billing plugin solves this problem by mounting projections and badges on the session title bar. It pushes the cost calculation logic down to the Host process, while the display side is only responsible for rendering, thereby providing visualized billing and balance querying capabilities without accessing any API key.

Plugin Overview

mrtomtao/dsh-token-billing is a session token billing plugin designed for the DeepSeek Harness Web GUI.

The plugin registers a tokenBilling projection on the Host side to calculate costs and query balances, while the browser side reads data through read-only routes and renders the UI. It does not rely on any network scraping or live fetching; price data comes directly from official documentation, and it operates entirely without accessing the DeepSeek API key.

Installation and Activation

Before installing, make sure the environment meets the requirements: DSH (Web / web profile), Node 22+, and pnpm installed and available in the PATH.

Install from GitHub

This is the most convenient installation method. The plugin is installed as a dependency into the profile, and the profile does not record the file path.

dsh plugin --profile web add github:<you>/dsh-token-billing

Install from a Release

Suitable for scenarios that require verification or offline deployment.

dsh plugin --profile web add ./dsh-token-billing-0.2.3.tgz

Install from a Directory

Used for local development and debugging.

dsh plugin --profile web add C:\path\to\dsh-token-billing

Verify and Restart

After installation, you can verify the mounting with the following commands:

# 查看组合层，应能看到 # == dsh-token-billing
dsh --profile web --dump-config

# 验证挂载且不绑定端口
dsh --profile web --help

After restarting the DSH Web profile, open any session. A spending and balance badge will appear on the right side of the title bar.

Core Features

  • Real-time billing badge: Displays the real-time cost of the current session in the session title bar. If no records have been generated yet, it displays ¥--; once records are generated, it updates immediately.
  • Itemized details: Click the spending badge (the 28px official header control specification) to open a dialog showing itemized details for input, cache hit, cache write, output, and reasoning.
  • Model billing: Displays token statistics and total cost grouped by model.
  • Time-of-day pricing display: Shows whether the current period is a peak period or an off-peak period, and provides a one-click toggle.
  • Balance inquiry: Displays an account balance badge. Click it to view the top-up balance, gift balance, and total amount. Balance inquiries are executed on the Host side; the browser side only calls local routes.

Billing Logic

The plugin includes complete built-in billing logic and calculates costs based on the official price list.

Price Source

Price data is taken directly from the original text in the official documentation, without live network fetching. It supports both CNY and USD, and the currency can be switched with one click in the panel.

Peak and Off-Peak Periods

Peak determination is based on the actual occurrence time of tokens:
* Peak period: Monday to Friday, 09:00–12:00 and 14:00–18:00 (Beijing Time).
* Off-peak period: All other times outside the peak period.
The unit price during the off-peak period is 0.5 times the peak price.

Bucket Statistics

The plugin groups token statistics into four non-overlapping buckets:
1. Input · cache miss
2. Input · cache hit
3. Cache write
4. Output (reasoning is included in Output)

Note: Cache write is billed at the missed-input price, because the official pricing does not separately charge for this item.

Retries and Unpriced Models

  • Retry logic: Consistent with DSH’s tokenUsage projection, retries for the same conversational turn use a replacement strategy rather than accumulation, ensuring that the token count displayed by the badge matches the GUI native panel.
  • Unpriced models: For models not listed in the official price list, the plugin estimates the cost using the price of deepseek-flash and marks the detail with an “estimated” label.

Balance Inquiry

Balance display uses a “Host calculates, browser displays” architecture.

Data Flow

  • Host side: Responsible for querying the DeepSeek platform. The query order is: first prioritize the balance of the logged-in DeepSeek account (top-up + gift), then query the account balance associated with the API key.
  • Browser side: Does not directly request DeepSeek endpoints; instead, it calls the Host-provided same-origin read-only route GET /token-billing/balance to retrieve the numbers.

Caching Strategy

To reduce request frequency, balance inquiry results are cached:
* Successful results are cached for 60 seconds.
* Failed results are cached for 15 seconds.

Disable Balance Inquiry

If balance display is not needed, you can disable the balance inquiry feature in the configuration. In that case, the Host side will not initiate requests, and the browser side will hide the balance badge.

Configuration and Notes

Manual Installation

If you do not use the bundle mechanism, you can manually add the following to the profile’s cordis.patch.yml:

- insert:
    - id: token-billing
      name: dsh-token-billing

Price Configuration

Prices can be overridden through the composed configuration without modifying code. Override config.prices in cordis.patch.yml:

- id: token-billing
  config:
    prices:
      CNY:
        deepseek-flash: { hit: 0.04, miss: 2, output: 8 }
        deepseek-v4-pro: { hit: 0.3, miss: 9, output: 27 }

Important Notes

  1. The lib/ folder must be committed: Because pnpm refuses by default to run build scripts for git dependencies (ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED), the plugin cannot be compiled on the fly during installation. The repository must commit the compiled lib/index.js and lib/client.js files to support git installation.
  2. Do not delete after installing the tarball: The profile remembers the file path; if the file is lost, subsequent commands will report ENOENT.
  3. Directory installation requires node_modules: When installing from a directory, the plugin directory must contain node_modules (including zod), otherwise the plugin import may fail.

Conclusion

dsh-token-billing fills the gap in billing and balance monitoring for the DeepSeek Harness Web GUI through a plugin-based approach. It uses DSH’s projection mechanism to provide precise cost breakdowns, while local routes help avoid cross-origin and API key leakage risks. For users who need fine-grained control over API costs, this is a ready-to-use tool.