Introduction

In a host like DeepSeek Harness (DSH) where “everything is a plugin,” model calls typically generate continuous Token consumption for input, output, cache read/write, etc. Viewing a single usage record is often insufficient: it is also necessary to know how much a session costs, how much is spent today, if it is approaching the budget, and whether the cost remains accurate after official price adjustments.

dsh-usage-ledger is a DSH plugin maintained by beijingwahw used to track Token/usage, calculate costs, control budgets, and provide a Web dashboard. It listens to session/event, converts the usage of every assistant/message into costs, and aggregates and persists the data by session, Beijing day, and lifecycle.

Positioning

dsh-usage-ledger is a Token/usage statistics and cost control plugin for DSH: it aggregates consumption by conversation, dynamically follows official pricing, supports budget interception, and includes a built-in Web dashboard.

The maintainer is beijingwahw, and the license is MIT.

Core Features

Statistics by Session

The plugin listens to session/event, converts the usage of every assistant/message into costs, and aggregates and persists the data across three dimensions:

  • By session
  • By Beijing day
  • By lifecycle

Dynamic Official Pricing

The plugin periodically scrapes the official pricing page, automatically parses it, and performs a hot update on the prices. After official price adjustments, the prices can be updated based on the scraping results without requiring manual code modification.

DeepSeek Peak/Valley Time Pricing

The plugin identifies the official peak/idle time tables and their effective dates, and retrieves prices in real-time based on the Beijing time at which the call occurs.

Multi-Vendor Price Catalog

The plugin covers price catalogs for multiple vendors, including:

  • DeepSeek
  • Zhipu GLM
  • Moonshot Kimi
  • Alibaba Tongyi
  • ByteDance Doubao
  • MiniMax
  • Baidu Wenxin (ERNIE Bot), etc.

Budget Control

The plugin supports three levels of budgets:

  • Daily budget
  • Total budget
  • Per-session budget

It enters an alert state when a threshold is reached; when exceeding the budget, model calls can be intercepted via the llm/stream hook.

Setting a budget value to 0 disables that specific budget.

Web Dashboard

The plugin registers a /usage-ledger route via dsh-host-webserver, providing usage visualization and a JSON API.

User-Overridden Prices

customPrices can be used to override or supplement prices based on model ID, with the highest priority.

Installation and Enablement

First, install the plugin:

dsh plugin add beijingwahw/dsh-usage-ledger --profile web

After installation, Harness automatically loads the plugin via dsh.plugin.json and cordis.patch.yml. The lib/ directory is distributed with the repository and does not require local building.

Next, configure the plugin in Harness’s cordis.yml. Verified configuration items include:

  • ledgerPath
  • saveIntervalMs
  • pricingTimeoutMs

Typical Usage

Setting Custom Prices

When you need to set an override price or supplementary price for a specific model, you can configure customPrices. The price unit is Yuan per million tokens.

Example:

{"glm-4.6": {"inputCacheHit": 1, "inputMiss": 5, "output": 5}}

Viewing Usage Report

You can use the usage_report tool to output a report of current usage, costs, and budget status.

Accessing the Dashboard and JSON API

To access the dashboard page:

GET /usage-ledger

To access the JSON API:

GET /usage-ledger/api/...

Budget and Failure Handling

The plugin’s budget control supports daily, total, and per-session budgets. It enters an alert state when a threshold is reached; when exceeding the budget, model calls can be intercepted via the llm/stream hook.

If pricing scraping fails, the plugin will fall back to the last successful price, so network anomalies will not affect accounting.

Applicable Scenarios and Notes

Suitable for the following scenarios:

  • Need to view Token consumption by session, by Beijing day, or by lifecycle
  • Need to convert model calls into costs
  • Need to set budgets for daily, total, and per-session
  • Need to intercept model calls when exceeding the budget
  • Need to view usage and JSON API via a Web dashboard

Note: The plugin runs with the permissions of the current dsh process. It registers tools and routes and periodically scrapes the official pricing page. You should check the source code and license before installation. The license for this plugin is MIT.

Links

Confirmed source code repository:

https://github.com/beijingwahw/dsh-usage-ledger