dsh-usage-meter-harness

English | 简体中文

A real-time usage / cost / balance meter plugin for DeepSeek Harness (DSH). See tokens, spending and real wallet balance right next to the chat input — for the official DeepSeek models and any custom model registered in DSH.

Install

Prerequisite (methods 1 & 2): the DSH CLI itself runs on pnpm — install it once per machine: npm install -g pnpm (or corepack enable), then verify with pnpm --version.

Pick one of the three methods. Methods 1 and 2 need pnpm (a one-time machine setup used by the DSH CLI itself): npm install -g pnpm or corepack enable.

Method 1 — npm registry via DSH CLI (needs pnpm)

dsh plugin --profile web add --verbose @faith1688/dsh-usage-meter-harness@latest

(--verbose shows the install progress; drop it if you prefer a quiet install. @latest explicitly requests the newest release — always install this way.)

Method 2 — GitHub via DSH CLI (needs pnpm)

dsh plugin --profile web add --verbose github:faith1688/dsh-usage-meter-harness#main

(--verbose shows the install progress. #main always installs the latest main branch — the newest release.)

Method 3 — one-line installer, no pnpm (recommended)

npx -y @faith1688/dsh-usage-meter-harness@latest

One command: installs into the DSH web profile and registers the bundle (idempotent). (@latest explicitly requests the newest release — always install this way.)

Prefer not to use npx? The same logic ships as scripts in the repo:

Windows (cmd):

curl -fsSL https://raw.githubusercontent.com/faith1688/dsh-usage-meter-harness/main/scripts/install.cmd -o "%TEMP%\um-install.cmd" && "%TEMP%\um-install.cmd"

Linux / macOS:

curl -fsSL https://raw.githubusercontent.com/faith1688/dsh-usage-meter-harness/main/scripts/install.sh | sh

The script does everything for you: cd into the DSH web profile, installs the package with visible progress, and registers the bundle in dsh.profile.bundles (idempotent — safe to re-run after upgrades).

Note: Method 3 uses plain npm and does not do pnpm coordination. If your profile is managed with pnpm (the default for dsh plugin), prefer Method 1.

After any method: restart dsh web.

Updating

Two cases — pick the right one:

Fresh install (never had the plugin), or the npx method: just run the install command; it always fetches the latest release.

Upgrading an existing install (plugin already present): the profile's package.json / pnpm-lock.yaml may be pinned to an old version, and a bare add can be skipped by pnpm as "already satisfied". Always ask for the new version explicitly:

dsh plugin --profile web add @faith1688/dsh-usage-meter-harness@latest

or, from inside the profile directory (~/.dsh/profiles/web):

pnpm update @faith1688/dsh-usage-meter-harness

(You may also pin an exact version, e.g. ...@1.0.28.)

Marketplace update failed? If it reports "targeted vX but installed vY; the previous version was restored automatically", that is pnpm's new-release cooldown (minimumReleaseAge — a freshly published version is skipped for roughly 24h). Your install is not broken and nothing in your config or data was touched. Wait 24 hours and click update again, or upgrade right away with the npx command below (or add this package name, without a version, to minimumReleaseAgeExclude in your profile's pnpm-workspace.yaml).

If your package.json binds the plugin via a file: path or a pin that add won't override (you see Already up to date / downloaded 0), use the one-line installer instead — it always requests @latest, which rewrites the binding to ^<latest> and upgrades in a single command:

npx -y @faith1688/dsh-usage-meter-harness@latest

(Re-running this same command is the permanent update path: it is idempotent and upgrades regardless of whether you currently bind via file:, a pin, or ^.)

After updating: restart dsh web (or reload the browser page). Note that restarting alone never fetches a new version — it only reloads what is already in node_modules.

Why this never duplicates the mount entry and never touches your config:

• The mount entry lives inside the package (cordis.patch.yml, the dsh.bundle mechanism). Every release ships its own complete entry; DSH reads it from the installed package at startup — installing a newer package automatically brings the correct entry with it.
• Installers only edit the profile's package.json (dsh.profile.bundles, de-duplicated) and node_modules. They never write the profile-root cordis.patch.yml, so anything you added there yourself (or your other plugin configs) stays untouched.
• A duplicate mount entry can only happen if you manually added the same id to the profile-root cordis.patch.yml yourself — the installers never do that.

Features

Conversation usage card (next to the chat input)

Feature	Description
Live cost	Session cost in CNY or USD, updated every step
Token breakdown	Input (miss) / cache hit / cache write / output
Turn usage panel	Per-turn subtotals with unit prices tagged peak/off-peak
Token speed	Live tokens/s while streaming; resets cleanly when output stops or tools run
Cache hit rate	Share of cached tokens for the session
Account balance	Real DeepSeek wallet balance; local-ledger estimate for other providers
Budget & remaining	Set a budget, see used / remaining / over-budget

Billing engine

Feature	Description
6 billing templates	Basic · Cache hit/miss · Peak/off-peak (DeepSeek official hours) · Cache write+hit · Combined input+output · Batch half price
Custom price rows	Up to 4 user-defined rows; the popup mirrors your setup verbatim
Peak/off-peak billing	Beijing-time weekday + hour windows, cross-midnight supported; each request is billed by its start time
Accurate turn attribution	Each turn is billed to the model that actually ran it — switching models mid-session never re-labels open or finished turns; the turn's currency is fixed at its first billed usage, so USD-priced turns convert correctly
Per-model pricing	Currency (CNY/USD), unit prices and balance per model
Shared provider wallet	One balance shared by all models of a provider — single checkbox
Official price prefill	DeepSeek official models come pre-filled with official prices and the official peak schedule
Built-in price table	137 models across 19 vendors bundled; optional LiteLLM-shaped remote price source
Exchange rate	USD→CNY fetched automatically, refreshed when older than 24 h
Sync official prices	One click on the settings page fetches the DeepSeek official price page, parses the latest prices and peak/off-peak windows, and writes them as overrides (a global API Key must be set first) — keep official pricing current at any time
Legacy migration	Old manual initial-balance/top-up settings migrate into provider wallets automatically

Settings & UX

Feature	Description
Bilingual UI	Language switch at the top-right of the settings page: Follow system / 中文 / English; applies everywhere instantly (popup included) and the choice is remembered. Display only — saved data never changes
Themes	20 built-in themes (light first, dark after; default forest-beach-dawn) plus per-theme custom pill & breathing colors — quick switch at the top of the usage popup, full palette on the settings page, saved locally
In-use lock	While a model is generating, its editor is locked so a running turn keeps consistent prices
WYSIWYG popup	Usage-card rows are copied verbatim from your template selection
Non-intrusive	Standard DSH cordis plugin; touches no other plugin and no DSH core files
Peak/off-peak capsule	The usage capsule turns light-green on off-peak and light-red on peak (with a soft breathing glow while billing), so the active tier is obvious at a glance
Unsaved / saved state	The model card shows Unsaved after you edit and Saved after you click Save — no more ambiguous "saving…"
Current-session dashboard	The popup opens straight into the Current session view (total + per-category cost + per-turn ledger); the axis labels use provider · model so official vs custom models with the same name are never confused
DS API Key guard	Non-official models picking "DS API Key" get a centered hint that the option is for DeepSeek models only; a custom model never falls back to the official global key — unset shows "未配置/not configured"

Supported models

• DeepSeek official models (deepseek-chat, deepseek-reasoner, …): official prices pre-filled; real wallet balance via API Key.
• Any custom model registered in DSH (OpenAI-compatible providers, Ollama, OpenRouter, …): set unit prices and balance yourself; everything else works the same.

Screenshots

Settings page:

Usage popup:

Configuration

All settings live in the usage-meter settings namespace and can be edited directly in the plugin UI:

Key	Type	Default	Description
currency	string	CNY	Display currency
budget	number	–	Session budget; shows "remaining" when set
priceSourceUrl	string	–	LiteLLM-shaped price JSON URL; optional
refreshIntervalMs	number	4 h	Price / balance / rate refresh interval
deepseekApiKey	secret	–	Only used to query the DeepSeek balance (stored AES-encrypted; never read from the DEEPSEEK_API_KEY env var)

Compatibility

• Node.js ≥ 22.
• Peer versions track the supported DSH releases (see package.json); updating DSH does not break the plugin, and it never modifies your other plugins.

License

MIT © faith1688

Privacy

• The plugin makes no telemetry and no analytics calls.
• Network requests are limited to four optional ones, all initiated by you: querying the official DeepSeek balance API with the API key you configure yourself, fetching a public USD→CNY exchange rate, fetching the official pricing page during a one-click price sync, and — only when rule parsing fails — sending that page's content to the DeepSeek API with your global key for extraction. Nothing else leaves your machine.
• The source is MIT-licensed and fully readable on GitHub.