dsh-plugin-usage

Deployment-level 用量 / Usage plugin for DeepSeek Harness (DSH).

A real-time token & cost dashboard tab for the current session, placed next to Chat / Trajectory in the conversation view ring. It records input / output / cache-hit tokens and prices every model call with both the DeepSeek official peak/off-peak rate card and the OpenCode Go plan rate card, refreshes every second, shows animated gradient-blue status bars, supports a fully editable custom price table (persisted across restarts) and CSV/JSON export.

中文文档见 README.zh.md（Chinese documentation is in README.zh.md）。

---

✨ Features

• New "用量" tab in the conversation view ring — sits right after Trajectory (order: 11), native DSH UI style (theme tokens, compact toolbar, card sections).
• Real-time live tracking — wraps every llm/stream model call: a "generating" row appears the moment a call starts, output/reasoning tokens are estimated per chunk and updated every second, then replaced by the adapter's exact usage; the committed assistant/message finalizes the record (15s match window, no duplicates).
• Per-session accounting — input (cache miss), output (incl. reasoning), cache hit, cache write; totals and per-call details with timestamps.
• History preload — the first time a session is opened, the full history is rebuilt from the persisted session log (seq-level dedup against live collection).
• Dual pricing, auto-adjusted — every call is priced by its own timestamp:
  • DeepSeek official (CNY / 1M tokens, effective 2026-08-17): peak hours (Beijing 09:00–12:00, 14:00–18:00) are 2× off-peak. V4 Pro: peak 9/0.3/27, off 4.5/0.15/13.5 (in/cache/out); V4 Flash: peak 3/0.1/9, off 1.5/0.05/4.5.
  • OpenCode Go plan (USD / 1M tokens + monthly quota): 20 built-in models (DeepSeek V4 Pro/Flash, Grok 4.5, GPT 5.6 Luna, GLM, Kimi, MiMo, MiniMax, Qwen3, Hy3), e.g. V4 Flash off-peak 0.22/0.007/0.66 and peak 0.44/0.014/1.32 with $15/month quota (DeepSeek plan models are billed in two peak tiers); plan is $10/month ≈ 6× usage value.
  • Three display modes: Auto (both), Official only, Plan only.
• Animated gradient-blue status bars — input / output / cache-hit distribution, smooth width transitions refreshed every second.
• OpenCode Go official quota — reads the official account quota (rolling 5h / weekly / monthly windows with reset times) straight from the opencode.ai/zen/go/v1/usage API, matching the console numbers.
• Custom price table — add, edit or remove prices for any model (official peak/off + plan prices + quota). Custom entries override the built-in cards, are persisted to /.dsh-usage-prices.json, and historical costs are re-priced immediately after a change.
• CSV / JSON export — one-click download links (60s validity) for the full call detail list with per-call prices and totals.
• Peak/off-peak indicator — the toolbar shows whether the current Beijing time is peak or off-peak.

---

🔐 Privacy

• No API keys, credentials, tokens or machine-specific paths are read, logged, or stored. Only usage numbers are kept in memory.
• The custom price file stores prices only (no conversation content, no tokens, no keys).
• The plugin never sends data anywhere: all computation is local; exports are served from the local DSH HTTP server as one-shot links.

---

🚀 Install

⚠️ Important: register the plugin exactly once. Do not combine installation paths.

• dsh plugin add (Method A / B) adds the plugin to dsh.profile.bundles; the bundled cordis.patch.yml is applied automatically as a bundle layer — do not also add ui-usage manually.
• ./install.sh or manual patching (Method C / D) registers through cordis.patch.yml — do not also use dsh plugin add.
• If two ui-usage entries exist, DSH fails with duplicate loader entry id: ui-usage. Fix: remove one. ./install.sh automatically removes the plugin from dsh.profile.bundles to prevent this.

Prerequisites

• DeepSeek Harness installed and the web profile initialized at least once (dsh web), so ~/.dsh/profiles/web exists.

Method A: install from the GitHub repository (recommended)

dsh plugin --profile web add github:GHJIVHIDD/dsh-plugin-usage

Pin a commit for reproducibility:

dsh plugin --profile web add github:GHJIVHIDD/dsh-plugin-usage#

pnpm ≥ 10 build authorization: if the first run fails because pnpm refuses to run the git dependency's prepare script, add this to the profile's pnpm-workspace.yaml:

#     - id: ui-usage

#       name: '@deepseek-ai/dsh-plugin-usage'

Verify the installation

## 🧭 Usage guide

1. Start a conversation and let the agent run (each model call is tracked).
2. Open the **用量** tab (next to Trajectory).
3. The page refreshes every second:
   - **Session overview** — input / output (incl. reasoning) / cache hit / cost (official ¥ and plan $), current model and call count.
   - **Usage distribution** — gradient-blue bars for input, output and cache hit (with a pulsing dot and "generating" label on the in-flight call).
   - **OpenCode Go official quota** — rolling (5h) / weekly / monthly usage percentages with reset times, identical to the OpenCode console; requires the API key (see below).
   - **Call details** — time, model, input/output/cache tokens and per-call official ¥ / plan $ costs; the in-flight row shows a blue pulse indicator.
   - **Price table** (collapsible) — full merged rate card; `Edit` any model, `+ Add model` for new ones, `Remove` for custom entries.
4. **Export** — click `Export` in the Call details header, then download **CSV** or **JSON** (links valid for 60 s; click again to regenerate).
5. **Pricing mode** — toolbar switches: Auto (both) / Official / Plan.

### OpenCode Go official quota

- The official quota card queries `GET https://opencode.ai/zen/go/v1/usage` with your OpenCode Go API key and shows the **account-level** rolling (5h) / weekly / monthly usage percentages and reset times — the same numbers as the OpenCode console.
- The key is read from the environment only (never stored or logged), in order:
  - `DSH_OPENCODE_GO_KEY` — dedicated key (recommended), or
  - `OPENCODE_GO_API_KEY` — the env name used by the llm-pi-ai `opencode-go` provider config, or
  - `DEEPSEEK_API_KEY` — used automatically when your deepseek provider points at the OpenCode Go gateway.
- Set it before starting dsh, e.g. `export DSH_OPENCODE_GO_KEY=sk-...`, then restart. The card refreshes every 30 s.
- The session-scoped plan cost (¥/$ in the overview) is separate from the account quota: it reflects only this session.

### Custom price table

- Units: official CNY per 1M tokens (peak & off-peak), plan USD per 1M tokens + monthly quota.
- Leave a field empty to omit that price group field.
- Changes apply immediately to the whole session history (dynamic re-pricing) and are saved to `/.dsh-usage-prices.json`.
- Removing a custom entry falls back to the built-in card.

### Peak / off-peak

Peak hours are **Beijing time 09:00–12:00 and 14:00–18:00**; official prices are 2× during peak. The toolbar badge shows the current period; per-call prices use the call's own timestamp, so history stays correct after the period changes.

---