Introduction

When running DeepSeek sessions via DSH, there are two tasks that always require switching away: checking the remaining balance requires opening the DeepSeek platform page; knowing how many tokens were consumed and which models were used requires opening another page. The longer the session runs, the more frequent this back-and-forth switching becomes.

ds-balance brings both of these into the session interface: the balance stays permanently as a badge in the session header; clicking it shows details and usage charts, and also allows direct jumping to the official checkout for top-up. Below is an introduction to its features, installation, and usage process.

What is this

ds-balance is a DeepSeek Harness (DSH) plugin maintained by Lateautumns, current version 1.1.0, license MIT. One-sentence positioning: a permanent DeepSeek official balance badge in the session header, accompanied by balance details, usage statistics, historical backfilling, and an in-app top-up floating window.

Instead of using a small floating window or persistent card, it embeds the balance as a badge in the top-right of the session; clicking the badge enters the details, usage, and top-up entry points.

Core Features

Balance Badge and Auto-refresh

The badge stays on the right side of the session header, showing a status dot plus the current balance, e.g., DeepSeek ¥88.69. The dot color indicates the status:

  • Green: Normal
  • Yellow: Below warning threshold (¥10 / $2)
  • Red: Balance unavailable or query failed

The refresh frequency is a code constant: normally once every 5 minutes, increased to once every 1 minute when the balance is low, and retries after 30 seconds if the query fails.

Balance Details

Clicking the badge pops up details: total balance, top-up/gift split, availability status, update time, and an overview of today’s and the last 7 days’ usage.

Usage Statistics and Charts

The plugin listens to DSH session events (assistant/message carrying official usage data) and aggregates API request counts, input (cache hit/miss), output Tokens, and turns/steps/tool calls by day × hour × model.

Clicking “Usage Details” switches the time range: today is a 24-hour stacked bar chart, while the last 7 days / last 30 days are daily stacked bar charts; hovering anywhere shows an official-style tooltip.

At the bottom, there are three sections: current period total breakdown, breakdown by model (one line per model: colored dot, name, requests/Tokens/consumption and consumption proportion bar, currently covering V4 Flash / V4 Pro), and a daily detail table (date, requests, input·hit, input·miss, output, consumption).

Cost Estimation

Consumption is estimated based on official pricing and token usage: built-in dual price tables for v4-flash / v4-pro, including peak/valley adjustments effective 8/17 (Beijing peak hours 9-12/14-18 are peak price, rest half price, previously flat rate), automatically selecting the price tier based on event time. The interface marks “Estimated”; the actual amount is subject to the official bill.

Historical Backfill

Automatically backfills the last 15 sessions and 30 days on startup. The “Backfill History” button is in the top-right of the usage details popup, allowing one-click deep backfill for up to 90 days or 60 sessions; if there are gaps in data, it prompts “Current data only available for X/Y days”.

The backfill limit is 90 days, consistent with DSH session log retention; older logs prior to this are usually compressed and cleaned up and cannot be recovered.

In-App Top-up

Clicking “Top-up” opens the in-app floating window: displays current balance, preset amounts ¥10/50/100/200/500, also supports custom input. After confirmation, proceed to the DeepSeek official checkout to complete payment via Alipay or WeChat Pay; the balance refreshes automatically upon receipt.

Installation and Activation

Prerequisite: DEEPSEEK_API_KEY must be configured in the local DSH credential store (e.g., ~/.dsh/.credentials.yaml). If not configured, the badge displays “Not Configured” with a prompt.

Installation consists of two steps:

# 1. Install plugin (web profile)
dsh plugin --profile web add <repository path or github:Lateautumns/ds-balance>

# 2. Restart DeepSeek Harness

After restarting, open any session, and the balance badge appears in the top-right. This package mounts the Host side via dsh.bundle.patch (injected ds-balance line in cordis.patch.yml) and loads the Client side via dsh.client (on the web platform, taking effect immediately). After restart, both are in place without manual configuration changes.

If you want to try it out temporarily, you can have the agent load the repository root host.js + client.js (dynamic Cordis plugin form) inside the session without installation. Note that dynamic plugins become invalid when the DSH process restarts; for long-term use, please use static installation.

Typical Usage

Daily operations follow this order:

  1. Check Balance: The badge in the top-right of the session directly shows the balance, with the dot color indicating health status.
  2. Balance Details: Click the badge to view total balance / top-up / gift / availability status / overview of today and last 7 days usage.
  3. Usage Details: Click “Usage Details” to switch between today / last 7 days / last 30 days ranges to view charts and details.
  4. Backfill History: When “Current data only available for X/Y days” is displayed, click “Backfill History” in the top-right to complete up to 90 days.
  5. Top-up: Click “Top-up” → Select amount (preset or custom) → “Proceed to Official Checkout” → Complete payment via Alipay/WeChat → Balance refreshes automatically upon return.

Implementation and Security Considerations

When evaluating this plugin, a few details are worth knowing:

  • RPC Channel: Balance queries use the official interface https://api.deepseek.com/user/balance; usage aggregation supports range parameters 1d/7d/30d/all; deep backfill parameters are limited to days≤90, sessions≤60.
  • Key Security: DEEPSEEK_API_KEY is read from the DSH credential store and used for curl only within the Host process; it never enters the browser; the browser side only receives parsed numbers.
  • Query Method: The query command runs with danger-full-access (shell + curl). The reason is that Windows ACL sandbox runners are unavailable on some machines, and web.fetch does not support custom Headers or carrying Bearer authentication. The command is a fixed curl (hardcoded official URL) with no injection surface.
  • Tunable Constants: The warning threshold ¥10 / $2 (LOW_CNY / LOW_USD) and refresh frequency are code constants that can be modified; the price tables include two tiers: flat rate before 8/17 and peak/valley rate after 8/17 (PRICE_TABLES).

Uninstallation

dsh plugin --profile web rm ds-balance

After execution, you also need to remove the ds-balance line from cordis.patch.yml (if the installation script didn’t clean it up automatically).

Use Cases and Notes

ds-balance is suitable for developers who use DSH to call the DeepSeek API and want to keep track of balance and token consumption without leaving the session. If you regularly go to the platform page to check usage and top up, the badge, charts, and top-up entry can save you these switches.

Note a few points before use:

  • Consumption is estimated; actual amount is subject to the official bill.
  • Historical data depends on session logs; backfill limit is 90 days; older logs cannot be recovered.
  • The query command runs with the current dsh process permissions (including danger-full-access). Before installing, you should check the plugin source code and license (MIT) to confirm it is acceptable.

Conclusion

ds-balance incorporates three high-frequency operations—balance checking, usage analysis, and top-up—into the DSH session via a permanent badge. It takes effect automatically after static installation and restart, while dynamic loading is suitable for trying it out first before deciding.

  • Plugin Directory Page: https://www.skillhub.cn/plugins/Lateautumns/ds-balance (The community directory is an independent site with no official affiliation to DeepSeek / Shanghai Huafan Technology)
  • GitHub Repository: https://github.com/Lateautumns/ds-balance