Preface¶
DeepSeek Harness (dsh) treats model adaptation, tool registration, session logging, and agent loops as plugins, with the official repository positioning itself as “everything is a plugin”. When running tasks daily in the web interface, users often need to open a separate browser to check their quota: whether the balance is sufficient, how many tokens this session has consumed, and if there are low-balance alerts. This information is not available in the default interface.
The community-maintained dsh-balance-plugin adds balance display, recharge portals, and usage statistics right next to the input bar. This article is organized after cross-checking with the plugin directory page, GitHub repository README, and package.json: what this plugin is, what it can do, how to install it, and what to note when using it. The community plugin directory is an independent site with no official affiliation to DeepSeek / FangTian, and should not be treated as an official app store.
What it is¶
dsh-balance-plugin is a UI enhancement plugin for the DeepSeek Harness web interface, maintained by Francis-Xavier-code, licensed under MIT, with the current version number 1.0.0. The package.json marks the client platform as web, meaning it attaches to the web interface rather than a headless process.
The directory page positions it as: DeepSeek Balance Monitoring & Usage Statistics (DSH Dynamic Cordis Plugin), covering balance monitoring, official recharge portals, usage statistics, and third-party plugin management. The repository README provides more details: it will query both RMB and USD balance pools in parallel, automatically read the locally configured DEEPSEEK_API_KEY, and add three entry points to the right of the input toolbar.
At the time of writing this article, the GitHub repository had 31 stars; the community directory page showed 8 stars at that time, and the star count should be referenced from the repository page.
Core Features¶
Balance Monitoring and Low-Balance Alerts¶
The plugin queries the DeepSeek API balance. The implementation path given in the README is: use curl to access api.deepseek.com/user/balance in the host process with Bearer authentication. It supports two sets of balances for RMB and USD, and can also add multiple accounts for parallel queries.
If the DEEPSEEK_API_KEY from the DSH credentials is detected at startup, it will automatically create an “Auto-read · DSH Credentials” account, eliminating the need to manually enter the Key again. You can also continue to add accounts: each account can have a name and an API Key, which can be written in plaintext or as an environment variable reference like $env:DEEPSEEK_API_KEY.
The low-balance thresholds are set separately by currency, with defaults of 10 yuan for RMB and 2 USD. These can be modified. When the balance drops below the threshold, the entire balance bar below the input box will turn red. The refresh interval can be selected between 30 seconds and 30 minutes, with the default being 5 minutes; clicking “Save Configuration” will trigger an immediate refresh.
The README’s note on the Key states: it only stays in the memory of the local plugin process and is not uploaded to third parties, and only the desensitized value is displayed on the interface. This is the security promise of the repository itself, but you should still review the source code before installing.
Official Recharge Portal¶
The balance panel provides one-click redirection to the official recharge page platform.deepseek.com/top_up, as well as a link to the usage details page. The persistent balance bar below the input box also includes a recharge link.
Miyu-style Usage Statistics¶
According to the repository description, the usage page is modeled after the Miyu WebUI Usage Page, including:
- Interval switching and statistical cards
- Usage calendar in the style of GitHub contribution graphs
- Three-segment stacked trend bar charts
- Model consumption pie charts and detailed breakdowns
- Last 50 recent invocation records
The chart color scheme follows Miyu’s blue, gold, rose, and purple tones, as well as blue-purple heatmaps, and adapts to both dark and light themes.
Performance metrics are listed separately: rounds, steps, LLM latency, tool call latency, average first token latency, tok/s, and cache hit rate. Usage data comes from real-time session/event listening, and at startup it will also scan the last 90 days of history and deduplicate by seq. The FAQ clearly states: the average first token latency only counts streaming data captured after the plugin starts running, and historical data before installation will not be supplemented with this metric.
Third-Party Plugin Management¶
The third entry point lists unofficial web plugins that are not from @deepseek-ai, with fields including package name, local path, Bundle rev, dependencies, and provides an “Open Directory” button to locate the source code. This is very useful for users who frequently install community plugins and need to verify local files.
query_api_quota Model Tool¶
The plugin will register the query_api_quota tool. When you ask questions like “How much balance does DeepSeek have left” in a conversation, the model can call this tool to get a balance summary without having to click the panel manually.
Installation and Activation¶
The prerequisite is that DeepSeek Harness is already installed and running on your local machine. The API Key is optional: without a Key, you will not be able to check the balance; if you have already configured DEEPSEEK_API_KEY locally, the plugin will automatically read it at startup without requiring you to enter it again. You can apply for an API Key at platform.deepseek.com.
The installation command given on the community directory page, to be run in the DeepSeek Harness terminal:
dsh plugin add github:Francis-Xavier-code/dsh-balance-plugin
For reproducible installations, the directory page requires fixing the commit hash:
dsh plugin add github:Francis-Xavier-code/dsh-balance-plugin#commit
Replace #commit with the actual commit hash.
The manual installation steps in the repository README are more complete, explicitly mentioning the --profile web flag, and requiring you to append the plugin line to ~/.dsh/cordis.patch.yml:
# 1. Install dependencies using the github: source (do not use the bare package name, see below)
dsh plugin --profile web add github:Francis-Xavier-code/dsh-balance-plugin
# 2. If it does not already exist in ~/.dsh/cordis.patch.yml, append:
# - insert:
# - id: dsh-balance-plugin
# name: 'dsh-balance-plugin'
# 3. Restart DeepSeek Harness
The README also provides a one-click script that follows the process: install dependencies → write the compose patch → prompt for a restart:
curl -fsSL https://raw.githubusercontent.com/Francis-Xavier-code/dsh-balance-plugin/main/install.sh | bash
Executing remote scripts via a pipeline is equivalent to running foreign code on your local machine. The directory page also notes: the plugin runs with the permissions of the current dsh process, and may execute code during installation. You should inspect the source code repository and license before installing; if you use the script, first open and review install.sh before executing it. When specifying other profiles, the README notes that you can use DSH_PROFILE=.
Do not use dsh plugin add dsh-balance-plugin. The FAQ in the README explains: the third-party package dsh-balance-plugin@0.1.0 already exists on npm, and using the bare package name will install the wrong package. You must use github:Francis-Xavier-code/dsh-balance-plugin or the installation script above.
After installation, restart DeepSeek Harness. The entry points will appear on the right side of the input box, which are three icons for wallet, usage statistics, and plugins respectively; a persistent balance bar will also be added below the input box.
The corresponding one-click uninstall script is:
curl -fsSL https://raw.githubusercontent.com/Francis-Xavier-code/dsh-balance-plugin/main/uninstall.sh | bash
Manual uninstallation:
dsh plugin --profile web rm dsh-balance-plugin
You will also need to delete the corresponding two lines from ~/.dsh/cordis.patch.yml, then restart.
Typical Usage¶
After installing and restarting, use the entry points as follows:
1. Click the wallet icon on the right side of the input toolbar to open the balance monitoring panel: view the balance table, set low-balance thresholds, add accounts, change the refresh interval, and access the official recharge page from here.
2. Check the persistent balance bar below the input box: real-time summary, manual refresh, and recharge link; the entire bar turns red when the balance is low.
3. Click the bar chart icon to open the usage statistics panel: switch time ranges, view calendars and trends, verify model consumption and recent calls.
4. Click the four-grid icon to open the third-party plugin list, and use “Open Directory” to locate local source code when needed.
5. Ask about the balance in a conversation and let the model call query_api_quota.
All panels are centered floating layers, and you can exit by clicking the mask or “Close”.
When the balance query fails, the panel will provide a reason. The README lists several categories: API Key not configured (API Key not configured), environment variable not found (Environment variable xxx not set), invalid Key (401). Fix the Key or check your credentials according to the prompt.
If there is no history in the usage page: the plugin only scans session events from the last 90 days at startup; earlier records are out of scope. The average first token latency also requires that the plugin was already running and captured streaming data at the time.
Applicable Scenarios and Notes¶
This plugin is suitable for these situations:
- You mainly use the DSH web interface to run DeepSeek official API and want the balance to be always visible
- You need dual RMB/USD balances, multiple accounts, or low-balance color alerts
- You want to view calendars, model breakdowns, and call details using the Miyu-style usage page
- You want the model to directly check the balance mid-conversation
- You need to browse the paths of locally installed unofficial web plugins
There are several things you need to accept before using:
The official DeepSeek Harness repository clearly states that the project is still in developer preview, and compatibility-breaking changes may occur. Community plugins will also change along with the Cordis plugin mechanism and web UI slots.
The entry points are not at the bottom of the sidebar. The FAQ explains: the bottom slot of the DSH sidebar is occupied by the official Cordis panel plugin, so this plugin’s entry points are fixed to the right of the input toolbar and do not rely on that slot. If you cannot find the buttons, first look to the right of the input box, not at the very bottom of the sidebar.
Manually configured account Keys will be reset after restart; the automatically created DEEPSEEK_API_KEY account does not need to be reconfigured, and will restore itself after restart. If you rely on multiple accounts with plaintext Keys, you will need to refill them after restarting.
The plugin runs with the permissions of the current dsh process, and can read local credentials, send network requests, and modify compose patches. You should read the repository source code and MIT license before installing, and confirm that github:Francis-Xavier-code/dsh-balance-plugin points to the version you want to install, not the identically named package on npm.
Balance queries will access api.deepseek.com. If there are network issues or Key permission problems, the panel not displaying the balance is expected behavior, not a broken interface.
Summary¶
dsh-balance-plugin adds DeepSeek API balance display, official recharge portals, usage statistics, and a third-party plugin directory right next to the DSH web input box, and additionally provides the query_api_quota tool for model calls. It solves the problem of “running agents while unable to see your quota at a glance”, without modifying the core of Harness.
Install using the github: source from the directory page, or follow the steps in the README with --profile web and compose patch edits; do not use the bare package name. Inspect the source code and license before installing, restart after installation, and access the three icons on the right side of the input box.
Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-balance-plugin/
GitHub: https://github.com/Francis-Xavier-code/dsh-balance-plugin