Introduction

DeepSeek Harness (DSH) adopts a plugin-based architecture and aims to provide a flexible runtime environment for AI agent development. During development or debugging, it is necessary to accurately track Token consumption, monitor cache hits, and analyze invocation trends across different time periods. Although DSH provides basic metering capabilities, ready-made visualization solutions are often lacking when aggregating historical data, viewing multi-dimensional line charts, or focusing on cache efficiency.

The dsh-token-stats plugin is designed to solve this problem. It reads DSH Session logs, aggregates Token usage across all sessions, and generates localized visual statistics reports.

Plugin Information

  • Name: dsh-token-stats
  • Maintainer: IZRINO
  • Category: Network tool
  • License: MIT

Core Features

  1. All-session statistics: Aggregates Token consumption and call counts across all sessions, without workspace filtering.
  2. Multi-dimensional aggregation: Supports aggregating data by hour, day, week, and month.
  3. Visual charts: Generates SVG line charts showing input, cache read, cache write, output, and total Tokens.
  4. Cache analysis: Supports calculating cache hit rates.
  5. Local storage: All data is stored locally and is not transmitted to the cloud.
  6. Historical backfill: Automatically backfills historical sessions.

Installation and Activation

A working dsh web profile is required, along with the dsh plugin command.

  1. Pull the plugin code into a local directory, or use the Git URL.
  2. Run the installation command:
dsh plugin --profile web add /home/izrino/code/dsh-token-stats
  1. Restart dsh web, open the settings panel, and locate the “Token Statistics” page.

Configuration

In the DSH profile configuration file cordis.patch.yml, find the token-stats plugin entry and add or modify the config field. Do not add the plugin entry more than once.

- insert:
    - id: token-stats
      name: dsh-token-stats
      config:
        timezone: Asia/Shanghai
        weekStart: monday
        retainDays: 365
        dataDir: ''
      inject:
        - webServer
        - sessions
        - sessionPersistence
Config Item Default Description
dataDir '' Cache directory. An empty value uses $DSH_HOME/storages/dsh-token-stats; absolute or relative paths are supported.
timezone system Time zone for day, week, and month statistics. system means the host time zone; an IANA time zone name can also be specified, such as UTC.
weekStart monday Start day for weekly statistics.
retainDays 365 Number of days to retain hourly bucket data, range 7 to 3650.

Incorrect configuration will cause the plugin to fail to load.

Architecture and Metrics

The plugin does not listen to the real-time stream. Instead, it directly reads persisted Session logs as the source of truth. For Usage chunks in streaming output, the plugin replaces them with the Usage from the final assistant/message, ensuring consistency with the official dsh-token-meter metric definition.

Metric Definitions

  • inputTokens: Non-cached input Tokens.
  • outputTokens: Model output Tokens.
  • cacheReadTokens / cacheWriteTokens: Cache read / write Tokens.
  • totalTokens: The sum of the above four items; reasoning Tokens are not included.
  • calls: Number of finally adopted Usage samples.
  • cacheHitRate: Cache hit rate. Formula: cacheReadTokens / (inputTokens + cacheReadTokens + cacheWriteTokens). Returns null when there are no prompt tokens.

Host API

The plugin provides a set of HTTP endpoints for querying data. All endpoints accept GET requests only from 127.0.0.1.

Endpoint List

  • /api/token-stats/series: Retrieve line chart data.
  • /api/token-stats/summary: Retrieve summary data for a time range.
  • /api/token-stats/breakdown: Group statistics by model or provider.
  • /api/token-stats/health: Query plugin health status.

API Parameters and Examples

Using the series endpoint as an example:

curl 'http://127.0.0.1:3080/api/token-stats/series?granularity=day&metric=totalTokens'

Parameter description:
* granularity: hour | day | week | month.
* metric: Metric to aggregate.
* fromMs / toMs: Time range in milliseconds.
* timezone: Optional time zone.

Notes

  1. Data persistence timing: Cached data is written to disk only during API requests, debounced real-time events, and session/flush operations; it is not refreshed in real time.
  2. DSH version status: DSH is currently in the pre-release stage, and plugin contracts may change between versions. This plugin is implemented based on 0.1.0-rc.x.
  3. Display limitation: The settings page displays only summary data and does not save raw call details.
  4. Timezone handling: Day, week, and month statistics are bucketed according to the configured time zone. Hour buckets in DST regions may span two local dates and are attributed based on the local time at the start of the UTC hour.
  5. Security: The API allows loopback access only.

Conclusion

dsh-token-stats provides a lightweight, local Token statistics solution, suitable for developers who need to analyze invocation costs and cache efficiency in depth. Through SVG charts and aggregation APIs, users can quickly identify abnormal invocations or optimize caching strategies.