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
Token Stats dashboard
Installation
The plugin is installed as an external DSH profile dependency.
-
Clone this repository to a local folder, e.g. D:\dev\dsh-token-stats
-
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"]
}
}
}
-
cd ~/.dsh/profiles/web && pnpm install
-
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)
| op | description |
|---|
summary | today / week / month / total aggregates |
query | time series (day/week/month) + per-model / per-session aggregates; filters: model, sessionId, from, to |
models | built-in pricing table (USD per 1M tokens) + USD→CNY rate |
sessions | session list (id + title) |
export | CSV / JSON dump (format=csv|json, optional model / sessionId) |
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):
| endpoint | before | after |
|---|
sessions | ~1700 ms (N serial readTitle calls) | ~12 ms (one batched readTitleSnapshots + cache) |
summary | ~110 ms (4× full-array filters) | <1 ms (single pass) |
query | ~10 ms | ~18 ms at 10k records (memoized cost) |
License
MIT © 2026 quansheng
