Preface¶

DeepSeek Harness (CLI name dsh) treats models, tools, sessions and interfaces as plugins. The official repository deepseek-ai/deepseek-harness uses the slogan “Everything is a Plugin”: developers can add or remove capabilities at the configuration layer without modifying the Harness source code. When running dsh web daily, what is often hard to keep track of is not the sessions themselves, but the usage: how many Tokens were burned today, what the cache hit rate is, how much balance remains in the DeepSeek account, and how much each model costs when using the official routing vs.中转 routing respectively.

The default web interface does not display these figures openly. The community plugin dsh-usage-stats addresses this: it adds a “Usage/Balance” entry at the bottom of the sidebar, uses a calendar heatmap and per-model breakdowns to view local Token aggregates, and pulls account balance or Token Plan quota according to the current provider.

This article is organized after cross-checking the plugin directory page, GitHub README, package.json and GitHub API. The community directory deepseek-harness-plugin.com is an independent site for discovering and installing community plugins, and has no official affiliation with DeepSeek or HyperGAN. Do not treat it as an official app store.

What is this¶

dsh-usage-stats is a UI enhancement plugin maintained by GitHub user Ychris12138, with its source code at Ychris12138/dsh-usage-stats. The current version in package.json is 0.2.0, the primary language is JavaScript, and the license is MIT. The GitHub repository was verified to have 56 stars on 2026-08-17.

The directory page positions it as: providing Token usage heatmaps, per-model breakdowns and DeepSeek account balance for the DSH web interface. The repository README is more comprehensive — it monitors multi-provider accounts, not just DeepSeek: API providers show balance, Token Plan providers show per-window quota; Token usage analysis does not rely on additional credentials.

It solves these problems:
- You cannot see today’s / this month’s / cumulative Token usage or cache hit rate on the web interface
- When using multiple providers, models with the same name will be mixed together, making it impossible to tell which routing the cost was incurred on
- You need to open the upstream console separately to check account balances for DeepSeek, OpenRouter, Moonshot, etc., and subscription quotas for Z.ai, Kimi For Coding, MiniMax Coding Plan, etc.
- You do not want to send API Keys, Cookies or admin PATs to the browser

The README states: the demo images use anonymized demonstration data; the plugin will not send API Keys, Cookies, admin PATs or upstream raw responses to the browser.

Core Features¶

Unified Account Card¶

The panel only displays the current provider at a time. API providers use the balance mode, while Token Plan providers use the per-window quota mode. For providers without a public account interface, Token statistics will still work normally, and the account card will clearly show “Not supported” without guessing the balance.

The built-in adapters listed in the README include:
- Balance: DeepSeek (/user/balance), OpenRouter (/api/v1/credits), Moonshot / Kimi API, New API
- Subscription / Token Plan: OpenCode Go, Z.ai / ZhiPu, Kimi For Coding, MiniMax Coding Plan
- Auto Detection: Sub2API / Passion (balance response shows balance; responses with quota_limited or subscription switch to quota window)
- Custom: General balance template, and declarative JSON Pointer queries (only supports restricted GET + JSON, no JavaScript execution)

The browser only requests the currently selected provider. Background refresh is independent of whether the panel is open. Manual refresh will update usage, the provider list, and force-refresh the current account, without batch-refreshing other providers.

Token Usage Analysis¶

The usage panel provides today’s, this month’s, cumulative usage, cache hit rate, calendar heatmap, and drill-down by date / provider / model. The interface supports both Chinese and English.

The statistics are sourced from the usage reported by the provider in assistant/chunk or assistant/message, not local estimates. Subsequent samples of the same turn/step will replace old samples, and are aggregated by provider/model. Therefore, the same model using different providers will be counted separately, such as deepseek-official · deepseek-chat and ark · deepseek-chat.

The “Last 14 Days” is calculated according to the local calendar, and only dates with usage within the window are displayed; future timestamps are not counted.

Background Monitoring¶

The service refreshes immediately on startup, and then updates all configured accounts and local Token aggregates every five minutes. The usage cache is written to ~/.dsh/storages/usage-stats-cache.json, which only saves aggregated Tokens, session IDs, opaque revisions and collapsed cursors, and does not save prompts, replies or file paths.

Local Security Boundary¶

The five HTTP endpoints only accept loopback GET requests, and simultaneously verify the peer socket and Host header:

Non-GET requests return 405, and non-loopback requests return 403. Credentials are only parsed on the server side and sent to verified provider addresses. The custom monitor defaults to requiring HTTPS, same-origin relative paths, manual redirects and JSON responses, with a 1 MiB body limit.

Installation and Activation¶

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

dsh plugin add github:Ychris12138/dsh-usage-stats

The repository README specifies that the plugin requires the web profile of DeepSeek Harness, and requires @deepseek-ai/dsh >= 0.1.0-rc.6. A more explicit way is to include the profile:

dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"

After installation, restart the running dsh web and hard refresh the browser. A “Usage/Balance” entry will appear at the bottom of the sidebar.

For reproducible installation, the directory page recommends pinning the commit hash. The latest commit on the main branch verified on 2026-08-17 is 24e6d0ff9b2cb98495f3f362958d7f6ef586e8c0:

dsh plugin add github:Ychris12138/dsh-usage-stats#24e6d0ff9b2cb98495f3f362958d7f6ef586e8c0

Upgrade or uninstall (from the README):

dsh plugin --profile web update dsh-usage-stats
dsh plugin --profile web remove dsh-usage-stats

When dsh plugin is unavailable, the README provides a compatible installer:

npx --yes github:Ychris12138/dsh-usage-stats

The installer will copy the runtime files to ~/.dsh/profiles/node_modules/dsh-usage-stats, and idempotently enable the plugin in profiles/web/cordis.patch.yml. Use the DSH_HOME directory if it is set. dsh plugin and npx are two independent installation paths, choose one of them; do not keep both manual Cordis entry and bundle registration at the same time, otherwise the plugin will be mounted twice.

Both the directory page and the README remind: the plugin runs with the permissions of the current dsh process, and may execute code during installation. Please check the source code repository and license before installing.

Typical Usage¶

1. Open the Panel and Drill Down¶

The operating steps given in the README:
1. Click “Usage/Balance” in the sidebar.
2. Switch account cards using “Current Provider”; only one provider is displayed at a time.
3. Use ‹ / › to switch months, and click the heatmap date to view the provider / model details for that day.
4. Refreshing the title bar will update Tokens, the provider list, and force-refresh the current account.

2. Configure Account Credentials¶

Credentials are parsed by Harness from ~/.dsh/.credentials.yaml. The installer will not read, create or modify this file. Do not submit real Keys, Cookies or admin tokens to Git, public issues, or paste them to coding Agents.

Providers such as DeepSeek and Moonshot reuse the apiKeyEnv of their corresponding provider profiles by default. For example:

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here

OpenRouter is a clear exception: the official account credits interface requires a Management Key, and cannot reuse the regular inference OPENROUTER_API_KEY. If not configured, it will show “Not configured”, and will not attempt to use the inference Key:

# ~/.dsh/.credentials.yaml
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-your-management-key

The plugin displays the OpenRouter balance as total_credits - total_usage. The /api/v1/key of a regular Key only describes the spending limit of a single Key, and will not be treated as an account balance.

Token Plan providers use their respective environment variable names, such as OPENCODE_GO_API_KEY, ZAI_API_KEY, KIMI_API_KEY, MINIMAX_API_KEY. For Z.ai in mainland China, you can set ZAI_API_REGION: bigmodel-cn; for MiniMax in mainland China, you can set MINIMAX_API_REGION: cn. OpenCode Go will also try the Harness credentials and the local ~/.local/share/opencode/auth.json in sequence.

3. Add a Monitor for Relays¶

The monitor configuration must be merged into the existing Cordis entry with name: dsh-usage-stats, do not add a second plugin entry. The monitor key must be a real provider ID existing in Harness; unknown providers, adapters or invalid mappings will prevent the plugin from starting before routing and timer registration.

New API uses the provider inference Token to query /api/usage/token/ by default:

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: dsh-usage-stats
      config:
        monitors:
          relay-a:
            adapter: new-api

Declarative custom queries only support restricted GET + JSON Pointer. warning.warnBelow and warning.criticalBelow are absolute balance thresholds. Balances with total quota and Token Plans will automatically generate normal / warning / critical remaining proportion statuses (default 30% / 10%).

Applicable Scenarios and Notes¶

It is suitable for these people and scenarios:
- Daily users of dsh web who need to view Token consumption and cache hits locally, instead of opening the upstream console
- Users who have configured multiple providers such as DeepSeek, OpenRouter, Moonshot, Z.ai, Kimi, MiniMax or multiple relays, and want to view balance or subscription quota by provider
- Users who use the same model name across multiple routings, and need to split and reconcile accounts by provider/model

Please note the following points, all from the directory page and repository documentation, not extra additions:
1. The plugin runs with the permissions of the current dsh process. Check the source code and MIT license before installing; pin the commit for reproducible installations.
2. Do not expose the endpoints to the LAN or public network via reverse proxy. The five interfaces are only designed for loopback access. A local reverse proxy will make the plugin see the proxy’s own loopback address, bypassing this restriction; if proxying is necessary, you must add authentication and access control at the proxy layer.
3. Only store credentials in Harness’s credentials file. The installer does not touch .credentials.yaml. OpenRouter must use a Management Key. When reporting issues or asking Agents to help with installation, do not paste Keys, Cookies, raw logs or unredacted balances.
4. Harness is still in developer preview. The README notes that the current version is 0.2.0, relying on the client module loader, Cordis services and session persistence; it may need to adapt synchronously when pre-release interfaces change.
5. Do not mix the two installation paths. Choose either dsh plugin or the npx installer. Custom monitors must be attached to the existing entry, and unknown adapters will directly prevent the plugin from starting.
6. Report security issues privately according to SECURITY.md. Do not include exploitable details or real balances in public issues.

Summary¶

dsh-usage-stats adds a local usage panel to dsh web: use the heatmap and per-model breakdowns to view Tokens, use the account card to view balance or subscription quota, refresh in the background every five minutes, and the browser cannot access credentials. For users who run DeepSeek Harness in the web interface and need to keep track of consumption, it turns “opening the upstream console to reconcile accounts” into a single click in the sidebar.

Related links:
- Directory page: https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-usage-stats/
- GitHub: https://github.com/Ychris12138/dsh-usage-stats
- DeepSeek Harness official repository: https://github.com/deepseek-ai/deepseek-harness