dsh-deepseek-usage

English | 中文

A DeepSeek Harness plugin that shows real-time DeepSeek API usage.

• 💰 Account balance — polls the DeepSeek /user/balance endpoint (default every 30s): total / granted / topped-up balance and availability, with multi-key aggregation (apiKeys)
• 📊 Usage stats — real-time request counts and tokens (input / output / cache-read / cache-write / reasoning) via the llm/stream waterfall, in three windows: total / today / last-60s, with the cache-hit rate
• 💾 Persistent history — daily usage survives restarts (~/.dsh/deepseek-usage/usage.json), powering the trend charts and CSV exports
• 💸 Estimated cost — per-model pricing (built-in deepseek-chat / deepseek-reasoner table, overridable via config), computed per window, with peak/off-peak pricing (offPeakHours / offPeakDiscount)
• 🖥️ Web UI dock — a live stats line under the composer (conversation.composer.dock), auto-refresh + manual refresh
• ⚠️ Low-balance alerts — dock turns amber below the threshold (default 20) and red below threshold/5, with one browser notification per threshold crossing; optionally block LLM requests while below the threshold (blockOnLowBalance)
• 📋 Settings usage panel — settings.section seat: balance card + per-key accounts, three-window usage, in-panel config editor (writes back through the host), history heatmap & 30-day bars, per-model pricing table, per-session usage table, and CSV exports
• 🛠️ Model tool — deepseek_usage, so the agent can query balance and usage on demand
• ✅ Tests & CI — vitest unit tests and a GitHub Actions pipeline (typecheck + test + build)

Install

From GitHub (recommended)

dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage

⚠️ First install requires build authorization: pnpm ≥ 10 refuses to run prepare scripts of git-hosted dependencies (the plugin builds lib/ from source at install time). The first add fails with a hint — copy the exact package key pnpm prints into that profile's pnpm-workspace.yaml, then re-run:

allowBuilds:
  dsh-deepseek-usage: true

Pin a commit for reproducible installs: dsh plugin --profile web add github:yyb16yyb-hub/dsh-deepseek-usage#<sha>.

Local directory / tarball

dsh plugin --profile web add /path/to/dsh-deepseek-usage     # local dir (pre-built lib/)
dsh plugin --profile web add ./dsh-deepseek-usage-0.1.0.tgz  # pnpm pack output

Restart dsh web after installing — the client module table is scanned at boot.

Uninstall:

dsh plugin --profile web remove dsh-deepseek-usage

Configuration

The API key is resolved in this order (re-resolved on every poll, so changes take effect immediately):

1. Plugin config apiKey
2. The dsh credentials seam (ctx.credentials): process env → ~/.dsh/.credentials.yaml → project .env → user .env. A DeepSeek key entered on the Web Settings → Models page lands in ~/.dsh/.credentials.yaml, which this plugin picks up automatically — no extra config needed
3. A stored apiKey in the registered llm-deepseek settings section (if any)

Override the plugin row in the profile's cordis.patch.yml to configure:

…