dsh-token-stats

Token usage & cost statistics plugin for DeepSeek Harness (DSH).

Tracks token consumption per model, per date, and per session with cost estimation in USD / CNY, served as a native page under Settings → 📊 Token Stats. Installed as an external DSH plugin, it loads automatically at DSH startup — no manual activation needed.

中文说明

Features

• 📊 Native settings page (dark/light aware, follows DSH theme tokens, i18n zh/en)
• 📈 Daily / weekly / monthly trends with an SVG line chart (zero dependencies)
• 💰 Cost estimation (USD & CNY) from a built-in pricing table for DeepSeek, GPT, Claude, Gemini, Qwen…
• 🔁 History backfill: scans all persisted session logs at startup, so stats survive restarts
• ⚡ Fast: batched session-title reads with an in-memory cache (TTL 5 min), single-pass summaries, memoized pricing
• 📤 CSV / JSON export, filterable by model and session

Screenshot

Installation

The plugin is installed as an external DSH profile dependency.

1. Clone this repository to a local folder, e.g. D:\dev\dsh-token-stats

2. In your DSH profile manifest (~/.dsh/profiles/web/package.json):

   {
     "dependencies": {
       "dsh-token-stats": "link:D:/dev/dsh-token-stats"
     },
     "dsh": {
       "profile": {
         "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-token-stats"]
       }
     }
   }

3. cd ~/.dsh/profiles/web && pnpm install

4. Restart DSH web. Open Settings → 📊 Token Stats.

cordis.patch.yml declares the bundle-layer mount point so the plugin auto-loads at startup. With a link: dependency the profile mounts the source folder directly — after editing the plugin, just restart DSH web (no copy step). file: also works but needs a re-copy per change (.\sync-deploy.ps1 automates that). Alternatively, dsh plugin --profile web add link:<path> forwards the install to pnpm; the dsh.profile.bundles entry still needs adding by hand.

Compatibility

Declared per the official plugin contract and enforced by DSH ≥ 0.2.0 at install/startup preflight:

• engines.dsh / peerDependencies["@deepseek-ai/dsh"]: >=0.1.0-rc.6 <0.3.0
• Verified on 0.1.7-rc.2 (latest stable line) and 0.2.0-rc.1 (next preview line): server APIs (sessionQuery, tokenMeter.estimateMessage, session/event, llm/stream, webServer.register) and the settings.section client slot are all present in both lines.

DSH is developer preview and iterating rapidly. If the runtime version falls outside the declared range, DSH rejects the plugin at startup — update the range only after re-testing, or grant an exact-version exemption with dsh plugin allow-version.

How it works

• Authoritative data = DSH persisted session logs: assistant/message events carry real usage (input / output / cache-read / cache-write / reasoning tokens), request/header events carry provider/model.
• A one-shot backfill at startup (sessionQuery) rebuilds the in-memory aggregation index from all history (bounded concurrency).
• llm/stream usage chunks are captured for live (display-only) in-flight totals.
• When an adapter reports no usage, tokenMeter.estimateMessage is used and the record is flagged estimated.

HTTP API (/token-stats/api)

Development

node --check index.js      # server half
node --check client.js     # browser half
node test-plugin.js        # standalone mock tests: correctness + performance benchmarks
.\sync-deploy.ps1          # only needed for file: installs; link: mounts restart to reload

Performance

Measured on the author's machine (14 sessions / ~10k records):

License

MIT © 2026 quansheng