Introduction

DeepSeek Harness (DSH) uses a plugin-based architecture. In agent development or long-form conversation scenarios, developers need to continuously track token consumption, cache hit rates, and provider balances. The dsh-usage plugin injects a panel into the sidebar and centrally displays balances, usage curves, cost estimates, and heatmaps, allowing you to view data without switching windows.

Core Features

The plugin injects a “Usage” button above the “Settings” button in the sidebar. Clicking it opens a single-page modal panel that includes the following five sections:

  • Provider Balances: Supports DeepSeek (DEEPSEEK_API_KEY) and OpenRouter (OPENROUTER_API_KEY). Credentials are resolved only on the host side and are never passed to the browser.
  • Usage and Hit Rate: Toggle between “All Sessions” or “Single Session.” The hit rate is the input-side cache hit rate.
  • Line Chart: Displays the hourly aggregated token and cost curves for the current day. Hover over the chart to view the specific data bucket for that hour (miss, hit, output).
  • Heatmap: A GitHub-style contribution view. Supports “Time Mode” (daily for the last 13 weeks) and “Session Mode” (each turn for each session).
  • Historical Details: Displays the full detail list with pagination and supports CSV export (with BOM, so it can be opened directly in Excel).

Installation and Enablement

Install the plugin with the official command. The change takes effect after restarting DeepSeek Harness Web.

dsh plugin --profile web add @dshd/dsh-usage

After installation, the “Usage” button appears above the “Settings” button in the sidebar.

Usage

  1. View Balances: Switch the provider at the top of the panel (DeepSeek / OpenRouter) to refresh the balance.
  2. Filter Sessions: Use the dropdown menu to switch between “All Sessions” or a specific session; the panel data will update accordingly.
  3. Analyze Trends: Observe the line chart to understand the daily token and cost distribution, and use the heatmap to locate high-frequency interaction periods.
  4. Export Data: On the Historical Details page, click the export button to obtain a CSV file for offline analysis.

Data and Configuration

  • Data Source: Parses DSH session logs (active in memory + persisted on disk) and extracts usage data from assistant/chunk and assistant/message events.
  • Calculation Logic:
    • Hit rate = cacheRead / (uncachedInput + cacheRead + cacheWrite).
    • Cost = uncached input × miss + hit × hit + output × out. Prices are applied according to the official peak/off-peak price list at the request time, and the official price page is synced online periodically (falling back to built-in pricing on failure).
  • Security: The plugin does not save credentials, does not upload data, and all calculations are performed locally.
  • Configuration Items:
    • cnyPerUsd: USD exchange rate, defaults to 6.76.
    • pricing: Unit price override configuration, supports defining peak/off-peak time windows.

Applicable Scenarios and Notes

  • Applicable Scenarios: Developers who need fine-grained API cost control, cache effectiveness monitoring, and multi-provider account balance management.
  • Notes: The cost is an estimated value calculated based on the official list price and request time, and may differ from the actual invoice. The plugin runs with the current dsh process permissions; it is recommended to review the source code and license (MIT) before installation.

Conclusion

dsh-usage provides a standardized usage monitoring solution, suitable for DSH users who seek cost transparency and development efficiency.