dsh-ui-usage-stats

中文 | English

@dsh-external/ui-usage-stats

Introduction

ui-usage-stats is a usage statistics plugin for the DSH Web client. It adds a "Usage Stats" page to Settings, displaying token usage and cost in a workspace → session → period → model hierarchy, with totals at each level, session type filtering, fork deduplication, persistent caching, and incremental calculation.

Installation

dsh CLI (Official Project Way)

If you have the dsh CLI installed, follow the official project tutorial to install with dsh plugin:

# Install from a local plugin directory
dsh plugin --profile web add C:/Users/<user>/.dsh/plugins/ui-usage-stats

# Or install from the GitHub repository
dsh plugin --profile web add github:xiyue718/dsh-ui-usage-stats

Start after installation:

dsh --profile web

View the composed configuration:

dsh --profile web --dump-config

See the project documentation for details: docs/user/develop/basic/publish.md.

Build artifacts: host lib/index.js (self-contained), client lib/client.js, package dsh-external-ui-usage-stats-0.1.0.tgz.

Build once before installing: DSH_CHECKOUT=<dsh checkout> bash scripts/build.sh. Once a profile installs this package, the host resolves the plugin's runtime imports from the package's own directory only, so the host half is bundled into a self-contained module (inlining schemastery, zod, and the @deepseek-ai/dsh-* helpers); an unbundled lib/index.js leaves the row disabled with failed to import.

Usage

1. Start the DSH Web client.
2. Open the Settings panel.
3. Click "Usage Stats" in the sidebar or navigation.
4. The page shows the DeepSeek account balance at the top.
5. Wait for the statistics to load, then view usage and cost by workspace, session, period, and model.
6. Use the "Total" at the top of the page to see the summary across all workspaces.
7. Check or uncheck session types on the far right of the refresh row; the page shows only the selected types.
8. Click "Refresh" to re-check the revision of all sessions and recalculate only changed ones, while also refreshing the balance.

Features

• Adds a Settings entry: Settings → Usage Stats.
• Balance display at the top of the page: queries the DeepSeek GET /user/balance endpoint and shows currency, total balance, granted balance, and topped-up balance.
• Displayed fields:
  • Workspace path
  • Session ID
  • Session title
  • Peak/off-peak period
  • Model
  • Cache miss tokens (uncached input)
  • Cache hit tokens (cached input)
  • Output tokens
  • Cost (CNY)
• Level totals:
  • Page-level "Total": aggregates usage and cost across all workspaces
  • Workspace total
  • Session total
  • Period total
  • Model rows are the finest granularity
• Session type filtering:
  • Four checkboxes on the far right of the refresh row: normal user sessions, subagent sessions, fork sessions, and other sessions
  • By default only "normal user sessions" is selected
  • The page only shows data matching the selected types
  • Filter state is persisted through the project storage domain and survives refresh/reopen
• Chat window statistics line:
  • Automatically replaces "cache hit xx%" with "cache hit xx.xx%" based on the real token ratio, keeping two decimal places
  • Calculated by the plugin-side component from the tokenUsage projection, not by simply appending .00, and without modifying core project files
• Sorting: workspaces and sessions are sorted by last modification time (last session activity time) in descending order, not by cost.
• Collapse: workspace, session, and period titles can be expanded/collapsed; collapsed by default to reduce rendering.
• Performance: the host reads session logs in parallel and aggregates tokens directly from raw JSONL to avoid full log replay.
• Persistent cache: per-session statistics are persisted through the project storage domain; only sessions whose persistence revision changed are re-read and recalculated, while unchanged sessions reuse cached results.
• Fork deduplication: chat records inherited from the original session through seedLength are not double-counted; only usage produced after the fork is counted.
• Clicking "Refresh" re-checks the revision of all sessions and only recalculates updated ones.

Pricing Calculation

Based on DeepSeek's official peak/off-peak pricing. Peak hours are Beijing time 9:00-12:00 and 14:00-18:00; all other hours are off-peak. Saturdays and Sundays use off-peak pricing all day, with no peak pricing.

Cost formula:

cost = cache miss tokens / 1_000_000 × cache miss unit price
     + cache hit tokens / 1_000_000 × cache hit unit price
     + output tokens / 1_000_000 × output unit price

Models not listed above display a cost of 0.

Host API

GET /@dsh-external/ui-usage-stats/api/stats

GET  /@dsh-external/ui-usage-stats/api/filters
POST /@dsh-external/ui-usage-stats/api/filters

GET /@dsh-external/ui-usage-stats/api/balance

How It Works

The plugin consists of a host half and a client half.

On the host side, it reads session logs through sessionPersistence.readRaw or sessionQuery.readSession, focusing on the model usage data in assistant/message events. It aggregates cache miss, cache hit, and output tokens by model and peak/off-peak period, then calculates cost using DeepSeek's official pricing. Peak hours are Beijing time 9:00-12:00 and 14:00-18:00; Saturdays and Sundays are billed at off-peak prices all day. Fork sessions skip chat records inherited from the original session using header.seedLength to avoid double counting.

Balance lookup uses DeepSeek's GET https://api.deepseek.com/user/balance endpoint. The API key is read from the project credentials service under DEEPSEEK_API_KEY, and the balance_infos response is mapped to the balance card at the top of the page.

Statistics are cached per session in the storage domain, keyed by the session's persistence revision. When /api/stats is requested, only sessions whose revision changed are re-read and recalculated; unchanged sessions reuse the cache. Sessions are processed in parallel with a mapLimit concurrency of 4. Finally, results are grouped by workspace path and returned as a tree sorted by last activity time.

On the client side, it renders the Usage Stats page, calls /api/stats for data, displays it level by level by workspace, session, period, and model, and provides collapse, totals, session type filtering, and refresh operations. The balance card calls /api/balance. The percentage correction in the chat window is calculated by a plugin-side component from the tokenUsage projection and displayed with two decimal places.