dsh-usage-unified

Machine-wide token accounting for DeepSeek Harness (dsh). One dashboard over every session log on the machine: trends, per-model breakdown, a session ranking, call details, exports, and an optional local cost estimate. Everything runs locally — the plugin never contacts the network.

English | 中文

Contents

• What it is
• Features
• Requirements
• Install
• Usage
• Configuration
• Data and privacy
• Cost estimate (opt-in)
• Known limitations
• Architecture
• Development
• Compatibility
• Cross-agent leaderboard (opt-in)
• Credits

What it is

dsh writes a session log per conversation. Reading those logs is the only way to answer "what did this machine actually spend, and on what" — the harness's own projection only covers the home it is running against.

This plugin merges two earlier plugins into one, at the data layer rather than side by side, so one index feeds one dashboard and the numbers agree everywhere:

Upstream	What it contributed
lanlandeli/dsh-usage-stats	The dashboard: sidebar entry and overlay, per-day trend, per-call detail table with filters and pagination, CSV/JSON export, workspace and task-scope filters, zh/en, theme-adaptive styling.
zoyluoblue/deepseek-harness-token	The machine-wide core: discovery of every dsh home, raw zstd log reading, a pure resumable fold, an incremental durable index, streaks, peak hour, per-model disjoint-bucket split, coverage disclosure, settings section.

Features

• Every dsh home, both log generations. ~/.dsh, ~/.dsh_desktop/<version>, $DSH_HOME, plus any extra roots you list. Reads legacy session.jsonl[.zstd] and versioned session.v<N>.jsonl[.zstd], and never depends on the harness's private decoder.
• One range governs the whole page. Today / 7 days / 14 days / 30 days / all time, plus a custom span, drives the headline cards, the trend, the model panel, the session ranking, the call table and the cost. A custom span has two modes: start–end, or start → now, which the host resolves against today so the window keeps extending as the calendar moves. Only the streaks are all-time facts, and those two cards say so.
• One model panel. Per row: share of the total, the stacked input / cache-read / cache-write / output bar, the call count and (when priced) the cost. The long tail sits behind a toggle.
• Session ranking with drill-down. Sessions ranked by tokens for the selected window; click a row to filter the call table to that session.
• Smooth multi-series trend (total / input / output / cache read) with a legend you can toggle and a hover readout, over any range including all-time. Today has one day bucket and so plots the 24 hourly buckets instead; those carry totals only, so that view offers the total series alone.
• The open panel refreshes itself every 60 seconds.
• Call details: time, response time, input, output, cache rate, model, thinking effort, with model/provider/threshold filters, pagination and a configurable row cap.
• CSV / JSON export of the current window.
• Collapsible panels, zh/en, light/dark, and a coverage footer that discloses what was skipped or replaced rather than quietly dropping it.
• Optional cost estimate from a local pricing table, with off-peak/peak weighting (below).

Requirements

• dsh 0.1.5-rc.1 or newer on the plugin API (see Compatibility).
• Node ^22.19.0 || >=24.0.0 — the runtime the harness itself uses.
• No runtime dependencies. react and the @deepseek-ai/* modules are peers, provided by the harness.

Install

# from GitHub
dsh plugin --profile web add github:satan9394/dsh-usage-unified

# from a local checkout
dsh plugin --profile web add E:\path\to\dsh-usage-unified

Then restart the Web profile. The dashboard appears as 使用统计 / Usage Stats in the sidebar footer, and as a section under Settings.

DSH STORE status. The marketplace lists this plugin as blocked. Its automatic admission policy refuses any plugin whose runtime source touches the filesystem, the network, commands or credentials, and this one must: the host half reads session logs from disk and the browser half fetches its own loopback route. The catalog keeps the manual install path above, and docs/SECURITY.md states exactly what the runtime does with those capabilities. Nothing about the plugin's behaviour differs from the description here.

Updating

The runtime (lib/) is loaded when the harness starts, so a new build only takes effect after a restart of the Web profile.

• From a checkout or a link: — git pull in that directory, rebuild if the source changed (npm run build), then restart. A link: dependency is a directory junction, so there is no copy to refresh: the profile reads the checkout itself.
• From GitHub or npm — dsh plugin --profile web add <same target> again. That install is pinned to a commit, so re-adding is what moves it.

Only a change to the runtime needs the restart; documentation and scripts/ changes do not.

Usage

Open the sidebar footer entry (or Settings → Usage Stats). Pick a range; the caption under the range control and the trend panel's header both spell out the exact window being reported.

The host serves four same-origin, loopback-only routes under /usage-unified/v1: /snapshot, /calls, /export.csv, /export.json. Non-loopback callers get 403.

Configuration

Set these in the profile's plugin row (the bundle patch in cordis.patch.yml shows the shape).

Key	Type	Default	Meaning
extraSessionRoots	string[]	[]	Extra dsh home directories to scan. Home discovery is a heuristic, so a home only reachable through an unset $DSH_HOME has to be listed here.
includeCompaction	boolean	true	Count the tokens spent generating compaction summaries. Set false to reconcile 1:1 with the harness's own projection.
refreshIntervalMs	number	30000	How often to re-scan for appended sessions.
indexChunkYieldMs	number	16	Cooperative yield interval during a scan, so a cold build stays responsive.
indexConcurrency	number	4	Sessions decoded in parallel. Measured: 2–4 is the sweet spot; 8+ regresses.
apiPath	string	/usage-unified/v1	Same-origin read-only API prefix.
cachePath	string	$DSH_HOME/usage-unified/index-v1.json	Index cache location.
pricingPath	string	$DSH_HOME/usage-unified/pricing.json	Cost table. Absent file means no cost is shown.
cacheWriteDelayMs	number	1000	Debounce before the index is written. It is written only when it actually changed.

Data and privacy

This is the whole picture; docs/SECURITY.md has the details and the failure bounds.

• Reads — session logs under every discovered dsh home, and (for the cost estimate) one optional pricing file. Read-only: it never writes to a session or to another home.
• Writes — exactly one file, the index cache at $DSH_HOME/usage-unified/index-v1.json, atomically (temp + rename) with mode 0600, and only when the index changed.
• Network — none. The runtime makes no outbound request and opens no socket of its own. It registers one route on the harness-provided web server and answers loopback callers only (anything else gets 403). Its imports are node:fs/promises, node:path, node:os, node:zlib and @deepseek-ai/*.
• Processes and credentials — none. No child_process, no shell, no eval, and no secret is read, written or logged.
• Tool surface — none. The plugin registers no model-facing tool and appends no session event, so mounting it costs a conversation nothing.

Cost estimate (opt-in)

dsh ships no price list, so the plugin shows no cost by default. When a pricing table exists, an "Est. cost" card and a per-model cost appear; a model with no entry is counted as unpriced, never as free, and the card plus the footer disclose the priced share.

npm run pricing:setup     # writes $DSH_HOME/usage-unified/pricing.json

Two sources are merged, the second winning:

1. Primary — CC Switch's ~/.cc-switch/model-pricing.json (--source can point at any file in this project's own { models: { id: {...} } } shape).
2. Override — scripts/pricing.override.json (in git): the models the primary table lacks, plus two-tier rates. It lives here rather than in CC Switch because a models.dev re-sync can drop hand-added rows; every pricing:setup re-applies it.

Time-of-day tiers. DeepSeek prices its whole Flash/Pro line by clock: peak is UTC Mon–Fri 01:00–04:00 and 06:00–10:00 (35 of the week's 168 hours). An entry may declare both an off-peak table and a peak tier; the plugin folds them into the effective rate as offPeak × (1 − peakShare) + peak × peakShare, with peakShare defaulting to 0.2083, and discloses that share on the card — neither the optimistic off-peak bound nor the peak one. The values shipped match DeepSeek's pricing page, OpenCode Go and Command Code.

Known limitations

Disclosed rather than hidden — the footer repeats the ones that apply to the current data.

• Retried steps keep only the final usage. A step whose provider report was replaced was billed for both attempts; the log only preserves the survivor. Surfaced as retried in the footer.
• A bounded range can total less than all-time. Tokens whose timestamps fail the clock-skew guard belong in a total but not on a calendar, so all-time reads authoritative per-session counters while a bounded range sums day slices.
• Days are bucketed in the host process's timezone, fixed when the index is built. On a machine whose system zone differs from the user's, "today" means today in that zone; changing it forces a full rebuild.
• The call table is capped by the configurable detail limit (default 1,000, max 10,000).
• A cold index takes minutes on a large history (this machine: ~1,380 log files, ~790 MB compressed). The panel renders partial results and reports progress.
• The activity heatmap was removed — it duplicated the trend chart.

Architecture

src/
  index.ts          host entry: Config, mount index + routes + refresh loop
  homes.ts          discover every dsh home (deduped by sessions realpath)
  reader.ts         walk session logs; decode both on-disk formats (no private API)
  zstd-frames.ts    scan concatenated zstd frames (resume cursor is frame-aligned)
  fold.ts           pure resumable fold: session → totals, day/hour slices, calls
  aggregate.ts      snapshot + session ranking + call rows + streaks/peak hour + CSV
  pricing.ts        optional pricing table: load, match by model id, cost + coverage
  index-store.ts    incremental index (parallel decode), file-backed cache under DSH_HOME
  transport.ts      /snapshot, /calls (incl. ?session= drill-down), /export.* (loopback only)
  types.ts          the wire contract shared by both halves
  client/
    index.tsx       sidebar + overlay + settings registrations, dashboard
    i18n.ts         zh/en dictionaries
    source.ts       the one transport seam
    styles.ts       dashboard stylesheet

Design decisions worth knowing (full rationale in PLAN.md):

• The reader is harness-version-agnostic. Legacy logs are JSONL storage records where streaming content is packed with no seq; versioned logs are plain events. Accounting only needs the sequenced events, so the reader keeps any line with a string type and numeric seq — no dependency on the harness's private decodeStorageRecord, which has moved between releases.
• One row per (turn, step). A usage report arrives twice per step (a streaming chunk and the final message); the fold replaces rather than accumulates, and keeps one call row per step. Compaction summaries are their own rows.
• File-backed cache, no optional services. The index persists to a plain file under $DSH_HOME rather than ctx.storageDomain, so a missing optional service can never stop the panel from loading.
• No invented numbers. Unpriced models are reported as unpriced; coverage, retried steps and skipped logs are always disclosed.

Development

npm install          # .npmrc sets legacy-peer-deps for the @deepseek-ai peer tree
npm run typecheck    # tsc --noEmit
npm run test         # vitest (68 tests)
npm run build        # tsdown → lib/index.js + lib/client.js
npm run check        # typecheck + test + build
npm run verify:realdata   # read-only pass over this machine's real dsh homes
npm run smoke:local       # local HTTP self-test against real ~/.dsh (no install)
npm run smoke:serve       # keep the local viewer up (prints the URL)
npm run pricing:setup     # build the cost table from this machine's CC Switch
npm run report            # static self-contained report (all-time) → opens in browser
npm run report:30d        # same, last 30 days

smoke:local is the "run it in the workspace, point at the real data" path: it does not touch the DSH profile. It mounts the same host routes over a plain Node server on a free loopback port, points the index at the real ~/.dsh, and runs nine HTTP assertions. verify:realdata walks every real session log and cross-checks the folded tokens against an independently coded reconstruction (exact match, zero-token delta on this machine).

lib/ is committed, because DSH STORE requires the runtime artifacts to exist inside the fixed commit. CI therefore asserts that the committed build output matches the source, so a source change that was never rebuilt cannot be installed as the old code.

The static report is generated from the same snapshot and reads the same way: --range drives the headline cards, it carries the same merged model panel, session ranking and cost card, and it drops the heatmap for the same reason the panel did.

The scripts under scripts/ are only available from a source checkout; they are not part of the published package.

Compatibility

• Plugin API: the @deepseek-ai/* peerDependencies (currently ^0.1.5-rc.1); Node ^22.19.0 || >=24.0.0.
• Session logs: legacy session.jsonl[.zstd] and versioned session.v<N>.jsonl[.zstd].
• Platform: Windows, macOS and Linux. The optional leaderboard task uses Windows Task Scheduler; its scripts are cross-platform otherwise.
• dsh.compatibility in package.json declares only what has actually been verified: >=0.1.5-rc.2 <0.1.6 with dshReleases["0.1.5-rc.2"] = "compatible". A caret range is deliberately not used — it would claim rc.3+ as well, which nobody has tested.

Details and the evidence behind each claim: docs/COMPATIBILITY.md.

Cross-agent leaderboard (opt-in)

The dashboard is DSH-only and works entirely offline. Aggregating every agent on the machine (DSH, Claude Code, Codex, OpenCode, …) into one number and posting it to the tokscale leaderboard is opt-in, and only happens if you run the guided setup from a clone:

git clone https://github.com/satan9394/dsh-usage-unified && cd dsh-usage-unified
npm install
npm run leaderboard:setup     # guided: install/login tokscale, export, first submit
npm run leaderboard:off       # undo: remove the daily task, stop submitting

leaderboard:setup follows docs/LEADERBOARD.md, which states exactly what leaves the machine and asks before anything is uploaded. A submit carries aggregates only — token buckets per day, estimated cost, message counts, client and model names, MCP server names, session timing metrics, a random device key and the CLI version. It never carries prompts, responses, source code or workspace paths. Two items cannot be redacted at upload: model/provider names and MCP server names (rename your MCP servers if those are sensitive).

Credits

MIT — see LICENSE and NOTICE. Derived from two MIT-licensed plugins, lanlandeli/dsh-usage-stats and zoyluoblue/deepseek-harness-token; their sources are kept under _upstream/ for comparison.

Change history: CHANGELOG.md.