# dsh-token-stats

[中文](README.zh.md)

Cross-session token usage statistics for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness): a Settings panel with a **monthly stacked cost chart** broken down by provider and model (USD), month navigation, provider/model filters, and a per-model legend.

Built as a standalone **bundle** (the harness's installable plugin format) — no changes to the core repository needed.

## Features

- **Overview** — usage-bearing session count, the four provider-reported token buckets (uncached input, cache read, cache write, output), the grand total, and the estimated cost split per matched price table.
- **Monthly cost chart** — stacked bars of each day's per-model cost for the displayed month, with `<`/`>` month navigation, provider and model filters, gridlines with fixed two-decimal USD ticks, and a color-coded legend.
- **Per-model pricing** — usage is priced via exact provider/model table matches (seeded with a `deepseek / deepseek-v4-flash` row), everything else falls back to the default table. Prices are fixed constants in this version; adjust `DEFAULT_PRICES` / `DEFAULT_PRICE_TABLES` in `src/client/usage-aggregate.ts` and rebuild if you need different rates.
- **Data honesty** — sessions whose cached projections predate the per-model units (or deployments without them) are counted as "no model data" and priced at the default table, with an explicit hint.

## How it works

The bundle has two halves:

- **Host half** (`src/host/`) — registers two session projection units, `modelUsage` (per provider/model session totals) and `modelDailyUsage` (per provider/model/UTC-day cells), following the `@deepseek-ai/dsh-token-meter` pattern. Registration is idempotent against deployments that already ship the same units (the registry shares same-`stateVersion` keys), so it is safe on both release builds and source checkouts that already carry them.
- **Client half** (`src/client/`) — a `settings.section` contribution (`Token 用量`) that reads the `session.list` projection column (zero log loads) and renders the panel. Day cells are shifted from UTC to your local days for display.

## Install

Prerequisite: a DeepSeek Harness installation (the `dsh` CLI or a source checkout).

### From npm (once published)

```sh
dsh plugin --profile <name> add dsh-token-stats
dsh --profile <name> web
```

### From this repository

```sh
git clone https://github.com/qiushui0901/dsh-token-stats.git
cd dsh-token-stats
npm install && npm run build
dsh plugin --profile <name> add ./dsh-token-stats
dsh --profile <name> web
```

### From a source checkout of DeepSeek Harness

```sh
pnpm dsh web --patch /path/to/dsh-token-stats/cordis.patch.yml
```

(with `dsh-token-stats` linked into the checkout's `node_modules`, or installed into the profile the checkout boots.)

Open `http://127.0.0.1:3080` → Settings → **Token 用量**.

## Build

```sh
npm install
npm run build
```

Produces `lib/host.js` (self-contained Node entry) and `lib/client.js` (browser closure-factory bundle registered via `window.__ModuleLoader__.load`).

## Known limitations

- **Model data fills forward** — sessions that ran before the `modelUsage`/`modelDailyUsage` projections existed stay unattributed until their projection cache rows rewrite; their usage is priced at the default table.
- **Day bucketing is UTC-shifted** — the host folds cells under UTC days and the client shifts by its timezone offset rounded to whole days, so a day's cells can sit on the neighbouring local day near the boundary.
- **Prices are constants** — the price tables are baked into the bundle; there is no in-UI editor (the editor was removed by request).

## License

MIT — see [LICENSE](LICENSE). Built on the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin system (MIT), which this project gratefully builds upon.