Introduction

DeepSeek Harness (DSH) uses a plugin-based architecture that allows developers to extend core capabilities. When developing agents or running long-running tasks, tracking token consumption, precise billing, and budget management are common requirements. The dsh-billing plugin is designed to address these issues. It provides a complete ledger system with support for persistent storage, official account balance synchronization, and peak/off-peak pricing strategies.

Core Features

This plugin mainly provides the following capabilities:

  1. Persistent Ledger
    All cost records are stored in $DSH_HOME/storages/dsh-billing/ledger.json. Writes use atomic operations and a debouncing mechanism to ensure data consistency.

  2. Precise Billing
    The plugin listens to usage blocks at the tail of the llm/stream waterfall chain and captures the actual consumption of each model call. The cost calculation formula (unit: USD / 1M tokens) is:
    成本 = 未命中输入 × cacheMiss + 输出 × output + (缓存读 + 缓存写) × cacheHit
    Ledger amounts are always stored in USD. The display currency defaults to Chinese Yuan (fixed exchange rate of 7.2).

  3. Official Balance and Budget
    It uses a valid API key to call the official API and query the account balance. Balance data is cached based on refreshMinutes and supports manual forced refresh. Budget management provides alerts (≥80%) and overspend notifications (≥100%), but only issues reminders without blocking calls.

  4. Peak/Off-Peak Pricing
    Supports peak/off-peak time-window pricing. Time windows are maintained through official synchronization (default effective time is 2026-08-16 16:00 UTC, and peak windows are UTC 01:00-04:00 and 06:00-10:00). The plugin automatically synchronizes the official price table at startup.

  5. Session Statistics and History
    Displays real-time estimated cost in the session statistics row, and shows today/month/cumulative summaries in the sidebar and settings page. History records are pruned based on retention days (default 180 days) and aggregated by day.

Installation and Activation

Installing the plugin requires Node.js ≥ 20 and an installed DeepSeek Harness CLI.

  1. Run the following command to install from GitHub:
    dsh plugin --profile web add github:mahiro6/dsh-billing

Or use a local path (recommended for development and debugging):

    dsh plugin --profile web add link:<本仓库绝对路径>
  1. After installation, you must restart the dsh web service for the plugin to take effect:
    dsh web

Configuration and Usage

Plugin configuration is mainly persisted in the ledger.json file. Except for budget, most configuration items (such as currency symbol, exchange rate, price table, and peak/off-peak time windows) are automatically maintained by the plugin or have fixed default values. Manual modification is not recommended.

  • Budget configuration: Can be modified in the UI settings page, including enable status, quota, and period (today/this month/cumulative/custom).
  • Balance query: Click the “Refresh Balance” button in the UI to force a new query. This operation does not depend on a timer and is triggered by the client.
  • Price synchronization: The plugin automatically fetches the official pricing page at startup. If you need to skip synchronization at startup (for example, in an offline environment), set the environment variable DSH_BILLING_SKIP_STARTUP_SYNC=1.

Technical Implementation and Limitations

  • Runtime mechanism: The plugin does not rely on Cordis Service or Context runtime classes. It only uses Node.js built-in modules and specific dependencies, and shares the same runtime instance with the host.
  • Data precision: The cost in the session statistics row is an estimated value for the current tier; today/month/cumulative costs are based on the ledger.
  • Price override: Official price synchronization replaces the entire model set. Old models that do not exist on the official page are removed.
  • Permission requirements: Balance querying requires a valid API key and access to api.deepseek.com; the API key is only sent to the official domain.

Summary

dsh-billing provides DeepSeek Harness with a complete cost-control view, from the micro level (single call) to the macro level (account budget). For developers who require fine-grained operations and cost monitoring, this plugin offers a reliable solution.