dsh-plugin-usage-report

A usage & cost report plugin for DeepSeek Harness (DSH): aggregates tokens (input / cache-read / cache-write / output), turns, steps and estimated cost (USD) by local day and month, with monthly reports, budget alerts, and a Claude Code/Codex-style daily contribution grid with fun stats.

中文: README.md

Features

• Usage ledger: refolds only revision-changed session logs against sessionPersistence, accumulating tokens / turns / steps / estimated cost (USD) per day, broken down by model (provider:model key); persisted via storage-domain, no full rescan after restart
• Budget alerts: monthly budget (monthlyBudgetUsd) triggers alerts at threshold percentages (default 50/80/90/100%), deduplicated by month|threshold, reset automatically across months
• /usage command: /usage (today/month/budget progress/daily contribution grid/fun stats), /usage month [YYYY-MM] (monthly detail), /usage budget <usd> (0 disables), /usage export [dir] (Markdown report), /usage rescan (full rescan), /usage pricing (effective-price audit: price source per seen model — config / built-in / fallback)
• "Usage" tab under Settings > Plugins: Claude Code/Codex-style daily contribution grid (last 13 weeks), editable budget progress bar, fun stats cards and alert list (zh/en, auto-refreshes every 15 seconds)

Configuration

Optional config on the plugin row (cordis.patch.yml):

Built-in DeepSeek official prices (USD/M tokens): deepseek-chat 0.27/0.07/1.10, deepseek-reasoner 0.55/0.14/2.19 (input/cache-read/output; cache-write falls back to cache-read). Models missing from the config fall back to the deepseek-chat default price.

Install

Requirements: Node.js >= 22, pnpm, a local checkout of deepseek-harness (dependencies use link: to ../../../deepseek-harness).

git clone https://github.com/csiroqa/dsh-plugin-usage-report.git
cd dsh-plugin-usage-report
pnpm install
pnpm build

# Add to the web profile (link: points at plugins/usage-report)
dsh plugin --profile web add link:$(pwd)/plugins/usage-report        # POSIX
dsh plugin --profile web add link:E:\path\to\dsh-plugin-usage-report\plugins\usage-report   # Windows

Restart dsh web and hard-refresh the browser (Ctrl+F5).

Usage

1. Run /usage in a session to see today / this month / budget progress / daily contribution grid / fun stats; /usage month [YYYY-MM] for monthly detail
2. /usage budget <usd> sets the monthly budget; /usage export [dir] exports this month's report; /usage rescan does a full rescan
3. /usage pricing checks the effective price and source (config override / built-in official price / fallback) for every seen model
4. Settings > Plugins > Usage: daily contribution grid, editable budget progress and alert list

Development

# Typecheck
pnpm typecheck

# Build (tsdown: host ESM + browser closure factory + d.ts)
pnpm build

# Plugin watch (rebuilds lib/ on src/ changes)
pnpm watch

# Smoke (loads the host bundle and validates the export shape)
node scripts/smoke.mjs

CI (.github/workflows/ci.yml): three-OS matrix (ubuntu / windows / macos) — pins the harness commit (env.DSH_HARNESS_REF, matching the local dev checkout) → builds the full harness lib → install → typecheck → build → smoke. Versions are not hardcoded: pnpm comes from packageManager, Node from devEngines.runtime, both read by pnpm/setup.

Compatibility

• Developed against a DSH 0.1.0-rc.5 source checkout
• The client half depends only on platform modules (react, etc.)
• Build: tsdown (host lib/index.js + browser lib/client.js, standard window.__ModuleLoader__.load closure-factory format)

Security notes

• Usage data and budget live only on the local machine (storage-domain backend and the .dsh-reports export directory)
• /dsh-usage-report/* endpoints are loopback-only (DSH binds to 127.0.0.1 by default); do not expose the DSH port to the public internet

License

MIT License (see LICENSE). Use, modify, reference, or include it in your own plugin collections — just keep the license notice and credit this repository.

Related

• DeepSeek Harness
• Plugin form reference: dsh-schedule (dsh.bundle.patch + dsh.client declaration + slot registration + dual-half build)