# dsh-usage-center

<p align="center">
  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a>
</p>

A native usage and cost dashboard for DeepSeek Harness Web. It adds a dedicated **Usage & Cost** section to DSH Settings and keeps provider usage, subscription quotas, balances, API estimates, and annual activity in one place.

![Usage overview with annual token activity heatmap](docs/images/usage-overview.png)

![Provider usage, balance, and subscription quota details](docs/images/provider-details.png)

## Features

- Daily input, cached-input, and output token usage grouped by provider and model.
- A 365-day token activity heatmap with total tokens, peak daily tokens, current streak, and longest streak.
- DeepSeek account balance, including available, topped-up, and granted balances.
- Z.ai Coding Plan quota percentages for the current session window, weekly window, and billing cycle.
- Kimi Code membership tier plus rolling 5-hour and weekly quota percentages.
- API-equivalent cost estimates calculated from public model rates.
- Persistent snapshots with stale-while-revalidate loading for instant repeat visits.
- English and Chinese UI that follows the active DSH language setting.
- Local-only aggregation and a loopback-only read API.

## Estimate vs. actual charge

API estimates answer: “What would the same token usage cost at public API rates?” They are not invoices and are not treated as subscription charges.

- Metered providers show today’s estimated API cost and any supported account balance.
- Subscription providers show quota consumption percentages plus an API-equivalent estimate.
- Pricing source links and effective dates are shown directly in the UI.
- Rates come from the public [models.dev](https://models.dev) catalog, cached for 12 hours and revalidated conditionally; `DSH_USAGE_CENTER_CATALOG_URL` points it at another source.
- A model the catalog knows needs no configuration at all. An entry in `src/pricing.js` dated later than the catalog entry wins, so hand-verified rates (and DeepSeek’s off-peak figures, which bill double during peak hours) stay authoritative.
- If the catalog cannot be fetched, the last cached copy is used and the local table still covers known models. Prices fall back to the model name, so the same model reached through a proxy such as LiteLLM still prices.

## Requirements

- DeepSeek Harness Web with plugin support.
- Node.js `>= 22.19.0`.

## Quick install

```sh
dsh plugin --profile web add dsh-usage-center
```

Restart DSH Web after installing:

```sh
dsh web
```

The npm package and repository include a prebuilt plugin bundle, so installation does not require pnpm `allowBuilds` configuration. To install directly from GitHub, use `github:Tieboyh/dsh-usage-center` as the package name.

## Install from source

```sh
git clone https://github.com/Tieboyh/dsh-usage-center.git
cd dsh-usage-center
npm install
npm run check
dsh plugin --profile web add "$PWD"
```

Use the source workflow when developing or modifying the plugin. Restart DSH Web after installing, upgrading, or removing it.

## Credentials

The plugin reuses DSH credentials. API keys are resolved only by the server process and are never returned to the browser or written into the snapshot.

| Credential | Purpose |
| --- | --- |
| `DEEPSEEK_API_KEY` | Reads the DeepSeek account balance. |
| `ZAI_CODING_CN_API_KEY` | Reads quota windows for a China-region Z.ai Coding Plan. |
| `ZAI_API_KEY` | Fallback credential for a Z.ai Coding Plan. |
| `ZAI_API_REGION` | Optional Z.ai region override. |
| `KIMI_CODING_API_KEY` | Reads the Kimi Code membership tier and subscription quota windows. |

## Data and refresh behavior

Usage is derived locally from DSH session events. Repeated cumulative usage samples for the same turn and step replace earlier samples instead of being double-counted.

- Live sessions are read incrementally through `ctx.sessions` `snapshotEvents`; stored sessions through `sessionPersistence` `open`/`read`, skipping any session whose `revision` and read cursor are unchanged.
- Forked sessions are counted from `inheritedEventCount`, so inherited parent history is never counted twice.
- A refresh reads only newly appended events; the first cold pass reads the full history once, and later refreshes normally finish in tens of milliseconds.
- The last successful result is saved to `<DSH_HOME>/storages/usage-center-snapshot.json`.
- Opening the page or restarting DSH immediately displays the current-day snapshot.
- Snapshots older than one minute remain visible while a refresh runs in the background.
- A manual refresh answers with the current data immediately and updates in the background.
- If an upstream balance or quota request fails, the last successful snapshot remains available.
- The snapshot contains aggregated usage and displayed balance/quota results, but no API keys.
- A stored session that cannot be read (an older on-disk format, for instance) is warned about once and not retried until its `revision` changes.
- The fetched model rates are cached at `<DSH_HOME>/storages/usage-center-catalog.json` and not downloaded again within 12 hours.

## Privacy and security

- The overview endpoint accepts read-only `GET` requests from loopback clients only.
- Session contents and raw event logs are not exposed to the browser.
- Credentials stay behind the DSH credentials service.
- The only outbound request besides provider balance/quota checks is a read-only `GET` for public model rates; no local data is uploaded.
- No external analytics or telemetry are included.

## Development

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

`npm run check` performs syntax checks and runs the Node test suite. `npm run build` updates the committed DSH client and server bundle in `lib/`; the committed bundle makes the GitHub one-line install work without dependency build approval.

## License

[MIT](LICENSE)