# dsh-cost-tracker · LLM Cost Tracking Plugin

[![npm version](https://img.shields.io/npm/v/dsh-cost-tracker.svg)](https://www.npmjs.com/package/dsh-cost-tracker)
[![npm downloads](https://img.shields.io/npm/dm/dsh-cost-tracker.svg)](https://www.npmjs.com/package/dsh-cost-tracker)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![GitHub](https://img.shields.io/badge/GitHub-lyfZhixing%2Fdsh--cost--tracker-181717?logo=github)](https://github.com/lyfZhixing/dsh-cost-tracker)

**English** | [中文](README.md)

A DeepSeek Harness Web (`dsh --profile web`) plugin that records **daily LLM call costs** and lets you inspect them per session, per model, and per day.

![Entry points](docs/screenshot-entry.png)

## Features

- Automatically records usage for every model call: input (cache miss), cache hit, output, and reasoning tokens
- Estimates cost from a configurable pricing table (¥ / 1M tokens) with an optional **peak-hour multiplier** (default: Beijing time 9–12 and 14–18, 2×); weekends are billed at the valley (base) price
- Entry points:
  - "¥ 花费统计" button at the sidebar footer (opens the dashboard)
  - "¥ 花费" button in the session header (shows that session's cost)
  - Per-session cost readout above the composer
- Dashboard tabs: **Overview** (today / 7 days / total), **By Model**, **By Session**, **Recent Calls**, **Pricing**
- Pricing can be edited in-app at any time; historical records are recalculated on save
- **Zero token consumption**: it only reads the usage data already returned by the model API and does local arithmetic — it never calls a model itself

## Install

### Option 1: npm (recommended)

```bash
dsh plugin --profile web add dsh-cost-tracker
```

Then **restart dsh web** and refresh the page — the "¥ 花费统计" entry appears at the bottom of the sidebar.

> If you use the npmmirror registry in China, note that newly published packages take a few minutes to hours to sync. If install reports 404, point pnpm at the official registry temporarily:
> `dsh plugin --profile web add dsh-cost-tracker --registry=https://registry.npmjs.org/`

### Option 2: install from GitHub

```bash
dsh plugin --profile web add github:lyfZhixing/dsh-cost-tracker
```

(No build step — nothing extra to configure.)

### Option 3: local directory (development / internal sharing)

```bash
dsh plugin --profile web add /path/to/dsh-cost-tracker
```

### Uninstall

```bash
dsh plugin --profile web remove dsh-cost-tracker
```

Uninstalling removes only the plugin; your local data file `~/.dsh/cost-tracker.json` is kept.

## Usage

1. Use any session as usual — every model reply is recorded automatically
2. Click "¥ 花费统计" at the sidebar footer to open the dashboard:
   - **Overview**: today / last-7-days / total cost, a 30-day daily bar chart, top models and sessions
   - **By Model**: calls, tokens, cost, and share for each model
   - **By Session**: cost and last-call time for each session
   - **Recent Calls**: the latest 200 call details
   - **Pricing**: edit peak hours, the default price, and per-model prices; one click adds any unpriced model that appears in your records
3. Close the panel with the ✕ button, clicking the backdrop, pressing `Esc`, or toggling the sidebar button

## Pricing

![Pricing settings](docs/screenshot-pricing.png)

- Unit: **¥ / 1M tokens**; `inputMiss` = uncached input price, `inputHit` = cache-hit input price, `output` = output price
- Default prices (`deepseek-v4-pro` / `deepseek-v4-flash`) are **estimates** — adjust them in the Pricing tab to match your real billing
- The peak-hour multiplier applies to both input and output; timezone offset defaults to +8 (Beijing time); weekends are billed at the valley (base) price

## Data & Privacy

- All data stays on your machine: `~/.dsh/cost-tracker.json` (records, session titles, pricing table)
- **No API keys or credentials**: the plugin only reads usage data included in model responses and never calls any model API itself
- No network reporting; the page pulls stats from a local HTTP endpoint (`/cost-tracker/data`) every 4 seconds
- Cost calculation consumes zero extra tokens

## FAQ

**Q: No records / shows 0 after install?**
A: The plugin only records calls made **after** it is installed; past calls cannot be recovered. Also check the Pricing tab — unpriced models are flagged and fall back to the default price.

**Q: The numbers don't match my bill?**
A: Default prices are estimates. Edit them in the Pricing tab (unit: ¥ / 1M tokens) to match your actual billing.

**Q: Will uninstalling lose my data?**
A: No. The data file `~/.dsh/cost-tracker.json` is independent; reinstalling the plugin restores it automatically.

**Q: Install fails with 404 on the npmmirror registry?**
A: The mirror lags on new packages. Install with `--registry=https://registry.npmjs.org/` temporarily, or retry later.

## Development

```
dsh-cost-tracker/
├── package.json        # dsh.bundle + dsh.client declarations
├── cordis.patch.yml    # plugin-row insert layer applied on install
└── lib/
    ├── index.js        # host half: usage recording, persistence, HTTP routes
    └── client.js       # browser half: UI (plain JS bundle, no build step)
```

- `lib/client.js` is served live by the server (`cache-control: no-cache`) — **edits take effect after a page refresh**
- `lib/index.js` is host-side code — changes require **restarting dsh web**
- No TypeScript / no bundling / no external runtime dependencies; the client must be written in the `window.__ModuleLoader__.load({ id, factory })` format
- Source: [github.com/lyfZhixing/dsh-cost-tracker](https://github.com/lyfZhixing/dsh-cost-tracker)

## Changelog

- **v1.0.1** (2026-08-17): added English README (README.en.md) and UI screenshots; documentation polish.
- **v1.0.0** (2026-08-17): first public release. Automatically records usage per model call and estimates cost from a configurable pricing table; dashboard with Overview / By Model / By Session / Recent Calls / Pricing; peak-hour multiplier and custom pricing support.

## License

MIT