@ljcscp/dsh-session-cost

Readme

# dsh-session-cost

DeepSeek account balance and session-cost readout for the [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (DSH) Web GUI.

- **Account balance** — queries the official `GET /user/balance` endpoint (the API key stays on the host, resolved per refresh through the DSH credentials seam)
- **Session spend** — token usage × **official DeepSeek prices**, auto-fetched from the [official pricing page](https://api-docs.deepseek.com/zh-cn/quick_start/pricing/) every 6h, so price changes never require a plugin update
- **Peak/off-peak pricing** — the 2026-08-17 rollout is applied automatically: peak hours 09:00-12:00 / 14:00-18:00 (Beijing), off-peak at half price
- **Per-model costing** — the session's actual model (deepseek-v4-flash / deepseek-v4-pro) is read from the newest assistant message's provenance and priced at its own bucket

The composer dock shows one readout under the shipped stats line:

```
本会话 ¥0.90 · 余额 ¥30.82
```

Hover for the breakdown (input / cache read / output, model, pricing source) and the balance split (granted + topped up).

## Requirements

- DeepSeek Harness `0.1.0-rc.5` or newer (web profile)
- A DeepSeek API key stored through the DSH credentials seam (`DEEPSEEK_API_KEY` — the web Models page writes it)

## Installation

From a git URL (no npm account needed):

```sh
dsh plugin --profile web add https://github.com/ljcscp/dsh-session-cost
```

From npm:

```sh
dsh plugin --profile web add @ljcscp/dsh-session-cost
```

From a local checkout (development):

```sh
git clone https://github.com/ljcscp/dsh-session-cost.git
dsh plugin --profile web add link:$(pwd)/dsh-session-cost
```

Restart `dsh web`, then refresh the page. The readout appears in the composer dock below the conversation stats line.

## Configuration

Zero-config by default. Optional composition settings:

```yaml
- insert:
    - id: session-cost
      name: '@ljcscp/dsh-session-cost'
      config:
        refreshMs: 60000          # balance cache lifetime (ms)
        pricingRefreshHours: 6    # official-pricing page refresh cadence
        apiKeyEnv: DEEPSEEK_API_KEY
        baseURL: https://api.deepseek.com
```

| Key | Type | Default | Meaning |
|---|---|---|---|
| `refreshMs` | `number` | `60000` | Balance cache lifetime in ms (failures retry after 10s) |
| `pricingRefreshHours` | `number` | `6` | Hours between official-pricing page refreshes |
| `apiKeyEnv` | `string` | `DEEPSEEK_API_KEY` | Credential ref storing the DeepSeek API key |
| `baseURL` | `string` | `https://api.deepseek.com` | Endpoint base; `/user/balance` is appended |
| `trustedHosts` | `string[]` | `[]` | Non-loopback authorities served beyond the trust fence |

## How it works

- **Host half** (`src/index.ts`): registers one trusted webserver route `/session-cost` that serves the balance snapshot (cached `refreshMs`) and the effective pricing snapshot (official page parsed per `pricingRefreshHours`, peak/off-peak band applied by the current Beijing hour once the rollout is live). The API key never leaves the host.
- **Browser half** (`src/client/`): a `conversation.composer.dock` entry that reads the `tokenUsage` projection, detects the session's model from the newest assistant provenance, applies the effective bucket, and renders the readout — refreshed every minute.

Cost formula (matches the official billing rule `扣减费用 = token 消耗量 × 模型单价`):

```
spend = uncachedInput × inputPerMillion + cacheRead × cacheReadPerMillion + output × outputPerMillion   (per 1M tokens)
```

Cache writes bill at the uncached input rate (DeepSeek reports only hit/miss buckets). The readout is an estimate at official rates; the official bill on platform.deepseek.com/usage lags by a few minutes of settlement.

## License

MIT. The browser-bundle build preset (`shared/`) is adapted from [dsh-balance-meter](https://github.com/Ghost011118/dsh-balance-meter) (BSD-3-Clause), which adapted it from [deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) (MIT).