Skip to main content

How to use dsh-usage-plugin

Records token usage and cost for each DSH LLM call, calculates fees using DeepSeek's peak/off-peak pricing, supports balance queries, usage calendar, and CSV/JSON/PNG export, with data automatically saved to a fixed directory.

This article is auto-derived from indexed fields (wiki / faq / compatibility_json), not freshly AI-generated.

This article is derived from the plugin's already-indexed fields (wiki / faq / compatibility_json / readme), not freshly generated by AI. Source field is noted at the end of each section.

Quick start

dsh-usage-plugin

— source: plugin_wiki.wiki_content

Install & verify

dsh plugin --profile web add @feiyang666/dsh-usage-plugin

Run the command above in your DSH Web Profile. Then enable the plugin in the plugin list.

— source: plugins.install

Key points

  • Balance Query: queries your DeepSeek account balance using the configured DEEPSEEK_API_KEY.
  • Import: merge-imports JSON / CSV files, deduplicated by time.
  • Persistence: records are written live to <session workspace>/dsh-usage/usage-records.json and restored on restart (cap 100000 records).
  • UI adaptation: panel typography scales with the app's display-size setting (em-relative fonts); table wrapping and spacing are tuned so large display sizes stay readable.
  • DeepSeek Harness installed (npm install -g @deepseek-ai/dsh, or a desktop app built on it, or npx @deepseek-ai/dsh web).

— source: plugin_wiki.readme_en (fallback readme_raw)

FAQ

What to do if the 'Usage & Consumption' and 'Remaining Balance Query' tabs are not visible after installation?

Usually it's due to missing inject list in the plugin line of cordis.patch.yml or the service is not ready. Check the log dsh-usage-boot.log in the data root to confirm that fs / webServer / subprocess / credentials / settings / sandboxPolicy / agents are all listed in the patch file, then restart DSH (see README.zh.md:256-258).

Where is the data stored? Will it be lost when switching workspaces?

Since v1.9.2, data is written to a dedicated directory. v1.9.4 changed to the host process node:fs writing directly, no longer constrained by workspace-write sandbox; default Windows writes to %LOCALAPPDATA%\dsh-usage-plugin\dsh-usage\, macOS/Linux writes to ~/dsh-usage-data/dsh-usage/, can be overridden with environment variable DSH_USAGE_DATA_DIR. Switching workspaces won't lose data, scattered old records will be deduplicated and merged by time on first launch (lib/index.js:398-413 / CHANGELOG.md:39-49).

How to check DeepSeek / SiliconFlow / DigitalOcean balance?

Click the corresponding service provider in the 'Remaining Balance Query' tab, then click 'Query Balance'. DeepSeek uses DEEPSEEK_API_KEY in settings, SiliconFlow reuses the API Key referenced by the provider named 'siliconflow' in 'Settings → Models', DigitalOcean needs to save account-level Personal Access Token starting with dop_v1_ in the panel (lib/index.js:778-850, lib/balance.js:1-41).

What does the 'PersistEnable' persistence not enabled message mean?

This prompt appears when all candidate data roots (environment variables, AppData, dsh-usage-data under user home directory) cannot be written to, and the plugin falls back to workspace. This is a very rare situation, mostly caused by permissions or full disk (lib/index.js:407-411 / README.zh.md:243).

What formats can be exported? Will the directory open automatically after export?

Supports CSV, JSON, and PNG long screenshots (up to 2000 most recent records), can choose default directory or use native folder selector to specify export directory (macOS calls osascript, Linux calls zenity/kdialog, Windows calls PowerShell FolderBrowserDialog), after export automatically calls open / xdg-open / explorer.exe to open the directory (lib/index.js:892-958).

Can historical records be migrated from other devices or old versions?

Can import from CSV or JSON files, deduplicates and merges by time field; on first plugin installation, it also automatically merges records from %USERPROFILE%\dsh-usage, .dsh/dsh-usage and old workspace to the new fixed directory (lib/index.js:1068-1110 / 365-389).

How do peak/off-peak prices take effect?

Starting from Beijing time 2026-08-17 00:00, calculated by peak/off-peak rates (peak 9:00-12:00 / 14:00-18:00, off-peak other times), before that still based on base rate; the 'Price List' tab in the panel can be edited online and persisted to pricing.json, click 'Restore Default' to restore with one click (lib/index.js:80-82 / 985-1019).

How to uninstall?

Recommended: dsh plugin --profile web remove @feiyang666/dsh-usage-plugin with one command; for manual installation, delete the usage-plugin line from cordis.patch.yml then pnpm remove / npm uninstall. Data directory won't be deleted by uninstall, can be manually cleaned (README.zh.md:182-190).

— source: plugin_wiki.faq_json

Compatibility

  • DSH: 未声明（依赖 @deepseek-ai/cordis ^4.0.1，请使用支持该 Cordis 版本的 DSH）
  • Node: >=18
  • Platforms: macOS, Windows, Linux

— source: plugin_wiki.compatibility_json

Pitfalls

Review the upstream repo before installing. This guide is auto-derived from indexed fields and may lag the latest release. If anything contradicts the official docs, treat the upstream source as authoritative.

— source: general rule