dsh-token-price

Readme

# dsh-token-price

<!-- README-I18N:START -->

**English** | [汉语](./README.zh-CN.md)

<!-- README-I18N:END -->

Accurate token-cost and account-balance readouts for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) Web chat UI.

## What it shows

- **Per-message cost**: the cost for completed request steps in that turn, shown as `¥...` after each assistant reply's statistics line on hover.
- **Session total**: the sum of every reported request step, including a cancelled request that emitted usage but no final assistant message.
- **Estimated CNY**: a market-rate USD/CNY conversion shown as `¥...`. USD is not rendered in the UI. This is not an account debit or official per-request CNY charge.
- **Account balance**: the official `GET /user/balance` result. The plugin prefers the returned CNY balance and otherwise preserves the API's returned currency.

USD remains the internal accounting value. An unknown provider/model route is shown as **未定价**, never as a zero-cost amount.

## Install

One command (requires pnpm):

```sh
dsh plugin --profile web add dsh-token-price
```

The package declares `dsh.bundle` and `dsh.client`, so this activates both the host service and browser readouts.

## Configuration

```yaml
- id: token-price
  name: dsh-token-price
  config:
    balanceBaseURL: https://api.deepseek.com
    balanceApiKeyEnv: DEEPSEEK_API_KEY
    balanceRefreshIntervalMs: 60000
    referenceRateRefreshIntervalMs: 3600000
    requestTimeoutMs: 5000
```

`balanceApiKeyEnv` names the credential holding the DeepSeek API key used for the balance request. The key remains on the host. A failed refresh keeps the last balance sample.

## Pricing and rates

`prices.json` is the local, versioned source of official USD rates per million tokens. It is an append-only history: each rule has an `effectiveFrom` timestamp, Beijing peak windows, and explicit prices for each supported route. New official prices must append a rule; past rules must not be changed.

The `tokenCost` projection snapshots the request route and time at `request/header`, then calculates each `(turn, step)` from the matching historical USD rule. Replaying the same session log therefore yields the same USD result. The host never scrapes the official price page at runtime.

USD/CNY is refreshed server-side from public market-rate sources every hour. When that refresh fails, the UI uses the current rule's bundled fallback rate. Both values remain estimates (`¥`) and never affect USD accounting.

## Development

```sh
npm install
npm test
```

`npm test` builds `lib/`, emits type declarations, and runs accounting tests. Restart the DSH Web process after rebuilding so it loads the new artifacts.

## License

MIT