Introduction

The plugin-based architecture of DeepSeek Harness (DSH) allows developers to extend functionality as needed. When developing or deploying intelligent agents using the DeepSeek API, having real-time visibility into account balance, token consumption, and estimated cost is fundamental for cost control and ensuring service continuity. dsh-deepseek-usage is a plugin maintained by yyb16yyb-hub. It provides DSH with real-time usage monitoring capabilities through a Web UI dock and model tools.

Core Features

This plugin primarily addresses usage and cost monitoring for the DeepSeek API. Its capabilities include:

  • Account Balance and Multi-Key Aggregation: The plugin periodically polls the DeepSeek /user/balance endpoint, by default every 30 seconds. It supports aggregating balances across multiple API keys, displaying total balance, used balance, and top-up status.
  • Real-Time Usage Statistics: It tracks requests through the llm/stream pipeline and provides input/output/cache read/write/reasoning token statistics. It supports three time windows: total, today, and the last 60 seconds, including cache hit rate.
  • Cost Estimation: It calculates cost based on the built-in pricing tables for deepseek-chat and deepseek-reasoner (overridable via configuration). It supports off-peak pricing strategies with configurable discounts during off-peak hours.
  • Web UI Dock: It provides a floating display below the chat editor, showing real-time balance, today’s request count, token count, and estimated cost. It supports automatic and manual refresh.
  • Low-Balance Alerts and Blocking: When the balance falls below a threshold, the dock UI changes color (amber/red) and triggers browser notifications. It can be configured to block LLM requests when the balance is too low.
  • Settings Panel: It provides a full configuration editor, allowing modification of thresholds, polling intervals, pricing tables, and blocking policies. The panel includes a historical heatmap, a 30-day bar chart, and CSV export.
  • Model Tool: It provides the deepseek_usage model tool, enabling an agent to actively query balance and usage summaries during conversations.

Installation and Enabling

Install the plugin by running the official installation command. Because it depends on pnpm >= 10, the initial installation may require build authorization.

  1. Run the installation command:
dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage

  1. Handle the initial build authorization issue:
    If installation reports that pnpm >= 10 refuses to run the prepare script, add the package name to the corresponding profile’s pnpm-workspace.yaml file, or install using a specific commit SHA to obtain reproducible build results.

  2. Restart the service:
    After installation, restart the dsh web service. The client module table scans and loads the plugin on startup.

Configuration

The plugin resolves the API key in the following order:
1. The apiKey in the plugin configuration file.
2. The DSH credentials layer (ctx.credentials), giving priority to environment variables, followed by ~/.dsh/.credentials.yaml, the project .env, and the user .env. The DeepSeek key configured in Web settings is automatically written to ~/.dsh/.credentials.yaml.
3. The apiKey in the registered llm-deepseek settings.

To override the default configuration, edit the profile’s cordis.patch.yml file. Key configuration options include:
* pollIntervalMs: Balance polling interval (milliseconds, minimum 5000).
* alertThreshold: Low-balance alert threshold.
* blockOnLowBalance: Whether to block requests when the balance is insufficient.
* offPeakHours: A list of hours considered off-peak.
* offPeakDiscount: The off-peak discount ratio.
* pricing: Custom input, output, and cache read/write prices for each model.

Usage Examples

  1. Query via the model tool:
    Invoke the deepseek_usage model tool during a conversation.
    * No arguments: Query balance and usage summaries for all windows.
    * Argument scope: Specify total, today, or rolling (last 60 seconds).

  2. View and configure via the Web UI:
    After starting dsh web, you can see the real-time usage dock below the chat editor. Click the “DeepSeek usage” settings panel in the sidebar to view detailed historical charts, edit configuration, or export CSV data.

Notes

  • Initial Installation: As mentioned above, initial installation in a pnpm >= 10 environment may require additional configuration in pnpm-workspace.yaml.
  • Cost Estimation: The costs displayed by the plugin are estimates based on common public pricing, not official real-time billing. It is recommended to periodically verify the official pricing tables.
  • Security: API keys are stored only on the host side, are not sent to the browser, and are not accepted or persistently stored through the Web UI editor.
  • Browser Notifications: Browser notification permission must be granted manually. The plugin itself does not proactively pop up a request.
  • Data Persistence: Daily historical data is persisted in the ~/.dsh/deepseek-usage/usage.json file.

Summary

dsh-deepseek-usage is suitable for developers who need fine-grained control over API costs and monitoring of call status in the DeepSeek Harness environment. Through real-time dock feedback and in-depth analysis in the settings panel, it can effectively improve development and operations efficiency.