Introduction

DeepSeek Harness (DSH) is a locally running agent development environment. When using local models to call the DeepSeek API, developers usually need to track specific token consumption and account balance. Existing monitoring methods often rely on third-party tools or manual calculations, lacking unified backend records and real-time visualized status.

The dsh-deepseek-usage-monitor plugin introduced below is specifically designed to solve this pain point. It runs in the DSH Host process, handles accounting, and simultaneously provides a visualized card through the DSH Web interface to display usage statistics and balance status in real time.

Core Features

Token Usage Records

The plugin listens to DSH’s session/event on the Host side, using the TokenUsage field in assistant/message as the primary data source, while also supporting the backup data from assistant/chunk. It deduplicates entries using session:turn:step as the key to ensure that the same step is not billed repeatedly.

The statistics logic automatically handles two field formats: DSH’s standard fields (inputTokens, outputTokens, etc.) and DeepSeek’s raw response fields (prompt_tokens, etc.). For the missing prompt_cache_hit_tokens in the raw fields, the plugin automatically completes it via prompt_tokens - hit.

The statistics data is grouped and displayed by model and provider, while retaining recent session records. All data is persisted to a local JSON file (~/.deepseek-harness/deepseek-usage.), and the data remains after restarting DSH.

Balance Query

The plugin starts a scheduled task in the background to poll the DeepSeek official endpoint GET /user/balance (default interval is 60 seconds). The query logic automatically parses and reuses the API Key already present in the DSH configuration, so no manual configuration is required. If a new Key is added after startup, it will automatically take effect on the next poll without restarting the process.

Web Status Card

After installation, a “Usage” card will appear in the bottom-right corner of the DSH Web interface. The card is rendered on the Web side (client.js) and retrieves data by polling the GET /plugins/deepseek-usage-monitor/state endpoint (default interval is 5 seconds, paused when the tab is hidden).

The card supports the following interactions:
* Drag and resize: Drag the title bar to move the card, or drag the handle in the bottom-right corner to resize it.
* Expand/collapse: Collapsed by default. Click “+” to expand and “−” to collapse. The state is saved in the browser’s localStorage.
* Refresh: Click the “Refresh” button on the card to force the ?refresh=1 endpoint to update the balance immediately.
* Multilingual: The card language follows the browser’s regional settings (for example, zh-* displays Chinese).

Installation and Enablement

Before installation, please ensure the environment meets the following requirements:
* Node.js >= 22.19
* pnpm

DSH plugins run through pnpm dlx and do not require global installation. Replace 0.1.1-rc.2 with the DSH version you are currently using according to your actual setup.

  1. Run the following command in any directory to install the plugin into DSH’s Web Profile:
pnpm dlx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add dsh-deepseek-usage-monitor

This command automatically adds the plugin dependencies to ~/.dsh/profiles/web/node_modules and includes it in dsh.profile.bundles, so there is no need to manually edit the YAML configuration file.

Usage Instructions

After installation, restart the DSH Web Profile and open the Web interface. A “Usage” card will appear in the bottom-right corner.

  • View data: When expanded, the card displays total token count, request count, cache hit rate, usage groups by model/provider, and the DeepSeek account balance.
  • Access the data endpoint: You can retrieve data through the HTTP endpoint, for example:
    GET http://localhost:PORT/plugins/deepseek-usage-monitor/state

Add the `?refresh=1` parameter to force a balance refresh.
  • Reset statistics: If you want to clear the local history records, delete the ~/.deepseek-harness/deepseek-usage. file and restart DSH.

Notes

  • API Key security: The plugin’s API Key exists only in the DSH Host process memory and will never be sent to the browser side.
  • Version dependency: Ensure the Node.js version is no lower than 22.19; otherwise, the plugin cannot run.
  • Data privacy: The persisted JSON file contains only numeric values, group names, and timestamps. It does not record prompts or model response content.

Summary

dsh-deepseek-usage-monitor provides DSH users with a lightweight usage monitoring solution. It places the accounting logic on the Host side, leverages DSH’s event stream to ensure accuracy, and provides intuitive real-time feedback through a Web card. It is suitable for developers who need to manage DeepSeek API costs with fine granularity in a local environment.