Preface¶

Starting from August 17, 2026, DeepSeek API will adopt peak-off-peak pricing based on Beijing Time: peak hours are 9:00–12:00 and 14:00–18:00 daily, with all other times being off-peak. The off-peak price is half of the peak price. When running continuous tasks in DeepSeek Harness, users often need to check their balance in the console manually, then calculate the approximate remaining number of sessions based on the current model by cross-referencing the official pricing list and historical usage.

DeepSeek Harness (dsh) operates under the architectural slogan of “Everything is a plugin”. There is a session and messaging plugin in the community directory that displays the real balance from the official GET /user/balance endpoint, as well as an estimated remaining task count based on the model, directly in the Web session header. This article organizes what the plugin does, how to install it, how the estimation is calculated, and its limitations, after cross-checking against the plugin directory page, GitHub repository README/source code, and DeepSeek’s official balance API and pricing page.

What is this¶

DeepSeek-Harness-billing-plugin is an open-source plugin maintained by WilliamLIiii, licensed under MIT, primarily written in TypeScript. Its GitHub repository is tagged with dsh-plugin. The community directory categorizes it under “Sessions and Messaging”, and it currently has 9 stars. The workspace version in the root package.json is 0.1.0-rc.5.

It solves a very specific problem: displaying the account balance in the Web session header of DeepSeek Harness, and estimating the approximate number of remaining tasks based on the current model. The balance comes from the real number returned by the DeepSeek official API endpoint GET /user/balance; the “remaining number of tasks” is an estimate, not a billing commitment. This is stated in the same sentence on both the directory page and the repository README.

The repository uses a pnpm workspace, split into two packages:

The package names use the @deepseek-ai prefix, and the repository maintainer is WilliamLIiii. The official DeepSeek Harness repository is at deepseek-ai/deepseek-harness; the plugin directory site is a community-curated page and has no official affiliation with DeepSeek or FunPlus. Do not treat it as an official app store.

Core Features¶

Session Header Badge¶

The browser package contributes an entry to conversation.session.header.utilities, rendering a label box in the top-right corner. The trigger has two lines:
- Remaining balance: Remaining Balance: ¥X
- Estimated remaining tasks based on the current model

Clicking it expands the details: remaining amount, a manual refresh button, and remaining tasks for each model. Models with no consumption history will show “No consumption records yet” instead of fabricating numbers; when the calculated consumption is less than 1 task, the copy will read “Based on your usage, you can run less than 1 task, time to top up your balance”.

The repository README and UI copy also agree on these behaviors:
- Do not render anything while the first request is in transit.
- Retain the last valid value if the refresh fails; the old numbers will not disappear first.
- When the API key is not configured, credentials are rejected, or a transmission error occurs, display a dimmed “Balance unavailable” with the error message returned by the Remote.
- The badge displays account-level data. Although the slot is mounted on the session title bar, the displayed value does not change with the current session switch.
- Only manual refresh is supported. Pull data once when mounting, then you need to click “Refresh”; the balance will not update automatically during long sessions.

Per-Model Remaining Task Estimation¶

The host package turns “balance + one estimate per configured model” into getEstimate(). The algorithm is clearly documented in the README and packages/llm-billing/src/billing.ts:
1. 1 task = 1 session. Online sessions and persisted sessions are deduplicated by session ID to avoid double-counting the same session.
2. Each model accumulates three billing token buckets: Cached prompt tokens, Uncached prompt tokens (uncached input + cache write), and Completion tokens (including inference). The source code takes cacheReadTokens, inputTokens + cacheWriteTokens, and outputTokens from the usage field of the assistant/message event.
3. Calculate the average cost per task by multiplying the historical average per-session consumption of that model by the current peak/off-peak unit price.
4. Estimated remaining tasks = floor(CNY balance ÷ average cost per task).

If there is no historical usage, no pricing row, or the balance is not in CNY, no estimate will be provided for that model. When switching between multiple models in one session, the usage will be counted separately for each model actually called; the average is calculated per “session invocation”, not per “declared task”.

The default displayed models are deepseek-v4-flash (DeepSeek-V4-Flash) and deepseek-v4-pro (DeepSeek-V4-Pro). It is a read-only projection and does not modify prompts, messages, schemas, streams, or tool results.

Peak-Off-Peak Pricing Table¶

The source code constant DEFAULT_MODEL_PRICING specifies the official V4 pricing implemented on August 17, 2026, in units of yuan per million tokens. This matches the DeepSeek Models and Pricing page:

The peak window defaults to 09:00–12:00 and 14:00–18:00 Beijing Time, with all other times being off-peak. The source code uses UTC+8 hours corresponding to Asia/Shanghai for judgment, without considering daylight saving time.

Balance requests are sent to {baseURL}/user/balance, where the default baseURL is the environment variable $DEEPSEEK_BASE_URL, falling back to https://api.deepseek.com. The request header uses Authorization: Bearer <API key>. This matches the DeepSeek Query Balance API: the response includes is_available and balance_infos (with currency as CNY or USD, and total_balance / granted_balance / topped_up_balance). The estimation only reads the CNY balance row; pure USD accounts can display the balance but cannot convert it to task counts.

Installation and Activation¶

The installation command given on the directory page is as follows, run in the DeepSeek Harness terminal:

dsh plugin add github:WilliamLIiii/DeepSeek-Harness-billing-plugin

For reproducible installations, fix the commit hash as instructed on the directory page:

dsh plugin add github:WilliamLIiii/DeepSeek-Harness-billing-plugin#<commit>

Replace <commit> with the actual commit hash from the repository. The plugin runs with the permissions of the current dsh process, and may execute code during installation. Inspect the source repository and license before installing.

The GitHub README describes a more detailed procedure: first install the two packages into the web profile. The original repository text is:

dsh plugin --profile web add @deepseek-ai/dsh-llm-billing @deepseek-ai/dsh-client-ui-billing

The README also notes that these two packages are located in the packages/ directory of this repository, and need to be published to npm first (under @deepseek-ai or your own scope) for dsh plugin add to resolve them from the registry. In other words, the GitHub installation command on the directory page is the external usage for the curated listing; the repository itself defines the runnable form as two Cordis plugins. The official DeepSeek Harness documentation also states that installing from GitHub gives you the source code instead of built artifacts, and TypeScript packages usually require allowing the prepare build step and enabling allowBuilds for the package names in the profile’s pnpm-workspace.yaml. Use the installation path you actually use, and do not mix unpublished npm package names and unbuilt git source code.

To integrate the plugin, the README requires editing ~/.dsh/profiles/web/cordis.patch.yml:

- insert:
    - id: llm-billing
      name: '@deepseek-ai/dsh-llm-billing'
    - id: ui-billing
      name: '@deepseek-ai/dsh-client-ui-billing'

Then configure your DeepSeek API key, choose one of the two options: fill it in on the web “Models” page (which will write DEEPSEEK_API_KEY to ~/.dsh/.credentials.yaml), or export the environment variable:

export DEEPSEEK_API_KEY=sk-...

Finally, restart the Web UI:

dsh web

The browser package declares platform: web, so this interface is mounted on the Web session header, not the terminal TUI.

Typical Usage¶

After installing and configuring your own DeepSeek API key, open a Web session and you will see the header badge. You do not need to send instructions to the model, as the plugin does not register model-facing tools.

All optional configurations have default values. The host-side fields are as follows (extracted from the repository README):

To override only certain models without losing the default rows, provide a non-empty billing.models list; an empty or omitted value will fall back to the official default pricing in the source code.

Minimal host-side configuration example (from the package README):

- id: llm-billing
  name: '@deepseek-ai/dsh-llm-billing'
  config:
    # apiKeyEnv: DEEPSEEK_API_KEY   # default
    # baseURL: https://api.deepseek.com

The actions after clicking the badge are to view the balance, view per-model estimates, and click “Refresh”. The built-in UI copy also states the口径: only estimates for DeepSeek-related models; 1 task = 1 session; converts the average per-model token consumption across all historical sessions using the current peak/off-peak unit price.

Applicable Scenarios and Notes¶

This plugin is suitable for these situations:
- Daily use of the DeepSeek official API with the DeepSeek Harness Web UI, and you want to see your CNY balance at a glance.
- After the August 17 peak-off-peak pricing takes effect, you want to roughly estimate “how many more sessions of V4 Flash / V4 Pro can I run”.
- You need to view historical consumption per model to support estimation, rather than just looking at a total balance.

Before using, pay attention to the limitations stated in the repository:
- The estimate is not a bill. Actual deductions shall prevail by the DeepSeek service provider; product prices may also change, and the official pricing page is the authoritative source.
- Only CNY estimation. Non-CNY balances will not be converted to task counts; multi-currency conversion is marked as pending in the repository.
- Full folding on demand. Each estimation will re-fold the usage of reachable sessions, and the cost grows with the number of sessions and log size, rather than using an incremental ledger.
- Manual refresh only. It will not automatically refresh during long sessions.
- You need your own API key. The balance is read from the DeepSeek API, and each user uses their own key. The key should only be given to plugins you trust to request the baseURL you configured.

The plugin runs with the permissions of the current dsh process. Read the repository source code and MIT license before installing; for reproducible environments, fix the commit to avoid silent changes to installation content from subsequent pushes.

Summary¶

DeepSeek-Harness-billing-plugin turns the official balance API and remaining task estimation based on average per-session usage into a badge in the Web session header. The balance is real, the task count is an estimate, and the pricing aligns with the August 17 V4 peak-off-peak rates. The directory page and GitHub repository are as follows:
- Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/deepseek-harness-billing-plugin/
- GitHub: https://github.com/WilliamLIiii/DeepSeek-Harness-billing-plugin