Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture, and extended functionality relies on community contributions. When developing or using DSH, viewing the total balance alone does not reveal the number of remaining tasks. Bil812’s dsh-balance-tasks plugin addresses this issue: it displays the real-time balance, current peak/off-peak tier, and an estimated number of remaining tasks based on historical consumption in the bottom-right corner.

Core Features

The plugin provides the following core capabilities:

  1. Floating card display: A floating card in the bottom-right corner of the interface displays the account’s total balance, current peak/off-peak tier, and countdown until tier switching in real time.
  2. Task count estimation: Based on historical average consumption (including context increments, output tokens, and cache hit status), it estimates how many more tasks the current balance can run.
  3. Peak/off-peak pricing: Supports peak/off-peak time pricing (UTC peak periods 01:00–04:00, 06:00–10:00; off-peak price = peak price / 2).
  4. Data persistence: Ledger data is persistently stored and automatically restored after restart.
  5. API access: Provides RESTful APIs, allowing external programs to query balance and task counts.

Installation and Enablement

Before installing, ensure that DEEPSEEK_API_KEY has been configured in Settings → Model. The plugin reuses this key; it is not sent off the local machine.

Run the following command to install the plugin:

dsh plugin --profile web add github:Bil812/dsh-balance-tasks

After installation is complete, restart dsh web for the changes to take effect.

Configure Model Prices

The plugin requires model prices to be configured for correct calculation. Configure the balance-tasks.models list in Settings → Plugins → balance-tasks (or by directly editing $DSH_HOME/settings.yaml).

The configuration items include model ID, display option, and peak/off-peak prices. The built-in default models are deepseek-v4-flash, deepseek-v4-pro, and deepseek-v4-flash-vision-exp.

The example configuration is as follows:

balance-tasks:
  models:
    - { model: deepseek-v4-flash, show: true }
    - { model: deepseek-v4-pro, show: true }
    - { model: deepseek-v4-flash-vision-exp, show: true }
    # 自定义模型配置
    - model: deepseek-v5-xxx
      show: true
      peak: { miss: 4.0, hit: 0.15, out: 12.0 }
      offpeak: { miss: 2.0, hit: 0.08, out: 6.0 }

Data Scope and Logic

The plugin reuses usage data from llm/stream to stay consistent with official billing definitions. Billing prices are consistent with dsh-conversation-cost and include three billing types: input miss, cache hit, and output out.

Remaining task count calculation:
A unified calculation basis is used. Starting from the current context ctx, it accumulates the estimated price of the next task until the balance is exhausted. The formula is as follows:
Next task price = average added context (delta) × miss + current context (ctx) × hit + average output (outAvg) × out

  • Peak/off-peak determination: Determined by the time of the call; effective from 2026-08-17 00:00 Beijing time.
  • Storage location: The aggregated ledger is stored in $DSH_HOME/storages/balance-tasks.json. The data is throttled every 10 seconds and atomically written only when changed; it is fully read and restored automatically on startup.
  • Applicable scope: The estimation applies only to CNY balance; displays “No usage records” when there is no historical usage.

API Interface

The plugin provides RESTful APIs for querying balance and task counts.

Get balance data:

GET /api/balance-tasks

Force refresh balance:

GET /api/balance-tasks?refresh=1

The returned JSON includes balance (balance), tier (tier), stats (overall statistics), and perModel (per-model details, including remainingTasks, avgTokensPerTask, nextTaskCost, etc.).

Uninstallation

If you need to uninstall the plugin, run the following command:

dsh plugin --profile web remove dsh-balance-tasks