Introduction

The core philosophy of DeepSeek Harness (DSH) is “Everything is a plugin.” When using DSH for agent orchestration or daily development, tracking Token consumption, calculating costs, and diagnosing performance anomalies are common needs. dsh-usage-board is a client plugin designed for this scenario, aiming to provide real-time usage monitoring and cost accounting.

What This Is

dsh-usage-board is a usage and cost visualization dashboard plugin designed specifically for DSH, maintained by zhm20001. It solves the problem of difficulty in intuitively viewing resource consumption during long-running sessions or complex call chains by presenting data through a visual interface.

Core Features

This plugin has the following core capabilities:

  1. Real-time monitoring: captures Token consumption, Step duration, and anomaly metrics within the session in real time.
  2. Historical backfill: supports cold-start incremental backfill of all historical sessions.
  3. Relationship analysis: performs tree-based aggregation and reverse drill-through based on Sub-agent DAG call relationships.
  4. Zero-dependency architecture: built on Node.js 22.5+ native node:sqlite, with no runtime dependencies.
  5. CQRS architecture: adopts CQRS, using DSH session files as the read-only source of truth and the SQLite database as a rebuildable read-only view.
  6. Two-tier read model: supports a warm/hot two-tier read model, leveraging SQLite and in-memory snapshots to improve read performance.
  7. Cost insights: supports DeepSeek official balance pass-through and real-time quota prediction, and includes counterfactual savings calculations for night-time/tiered pricing.
  8. UI mounting: provides three seamless UI integration points, located in the session page tab, sidebar entry, and full-screen dashboard.

Installation and Enablement

Enabling this plugin requires meeting environment requirements and running installation commands.

  1. Environment setup
    Ensure Node.js >= 22.5.0 is installed.

  2. Register plugin
    Run the following command in the plugin directory to register the plugin to the DSH Web Profile:

    dsh plugin --profile web add "$(pwd)"
  1. Start host
    Start the DSH Web host:
    dsh --profile web --port 3099

After startup, visit `http://127.0.0.1:3099` to use the feature. The first launch performs cold-start backfill and scans all historical sessions.

Configuration and Data

The plugin requires attention to configuration items and data storage paths during runtime.

Balance Query Configuration

If you need to view the DeepSeek official balance and real-time quota prediction, configure an API Key:
* Option 1: Enter DEEPSEEK_API_KEY in DSH’s “Settings → Models”.
* Option 2: Write the Key in ~/.dsh/.credentials.yaml (permissions must be set to 0600).

Note: Balance query is the only outbound network request of this plugin; all other processing runs locally. If the Key is not configured, the balance card only shows a placeholder and does not affect local statistics.

Data Storage Paths

The plugin maintains two key data paths:
* Source of truth: ~/.dsh/sessions/<projectKey>/<sessionId>/session.jsonl.zstd. This is the raw DSH session file, read-only, and must not be deleted.
* Projection store: ~/.dsh/data/usage.sqlite. This is the SQLite index and aggregation database maintained by the plugin, and can be safely rebuilt.

Usage and API

The plugin provides query interfaces for embedded development or scripting.

Query Interface

After creating an engine instance with createEngine, you can call the following query interfaces:

import { createEngine } from 'dsh-usage-board'

// ctx 为结构化 HostContext，无需真实 Cordis 运行时
const engine = createEngine(ctx, { dbPath, sessionsRoot })

// 等待冷启动/增量 Backfill 就绪
await engine.ready

// 查询接口调用示例
const rollup = engine.query.getRollupBySession(rootSessionId)
// 其他查询...

Conclusion

dsh-usage-board provides DSH users with a lightweight and reliable usage monitoring solution through its zero-dependency architecture and CQRS design. For developers who need fine-grained cost control and performance diagnosis, this is a practical tool.

  • Plugin homepage: https://github.com/zhm20001/dsh-usage-board
  • Ecosystem directory: https://www.skillhub.cn/plugins/zhm20001/dsh-usage-board