Skip to main content

dsh-usage-plugin

33Stars2Forks2Issues0Watchers

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.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
JavaScript
License
MIT
Branch
main
deepseekdeepseek-harnessdeepseek-v4deepseek-v4-prodshdsh-plugin

Install

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

Run the command above in your terminal to install this plugin via the dsh CLI. You can switch Profile in the top-right corner. New to dsh? Read the beginner tutorial

Install via your agent

Install the DeepSeek Harness plugin feiyang-dev/dsh-usage-plugin for me: review the repository at https://github.com/feiyang-dev/dsh-usage-plugin first, then run the install command and verify the plugin loads successfully.

Paste this instruction to the DSH Web GUI assistant — it will install and verify for you.

One-Line Description

A usage and consumption statistics plugin for DeepSeek Harness. After installation, two additional tabs appear at the top of the WebUI: "Usage & Consumption" and "Balance Inquiry". It automatically records tokens and costs for each model invocation.

Core Features

  • Automatically records input, output, cache hits, cache writes, inference tokens, and completion reason for each model call
  • Automatically calculates consumption based on DeepSeek's official peak/off-peak pricing (peak hours: Beijing time 9:00–12:00 / 14:00–18:00), switches to peak/off-peak pricing after 2026-08-17
  • Provides aggregated tables by model and by "provider × model", supporting filtering for today / last 7 days / last 30 days / all / custom date range
  • Monthly usage calendar heatmap with daily detail view
  • Queries DeepSeek / SiliconFlow / DigitalOcean account balances; panel allows managing DigitalOcean account-level Tokens
  • Export to CSV / JSON / PNG long image (up to 2000 recent records), optional default directory or system native folder picker, automatically opens directory after export
  • Import CSV / JSON and deduplicate merge with existing records by timestamp; price table can be edited and persisted within the panel

Technical Implementation

  • Language: JavaScript (ES Module, "type": "module", no TypeScript)
  • Key Dependencies: @deepseek-ai/cordis (peer, ^4.0.1), host-provided webServer / fs / subprocess / credentials / settings / sandboxPolicy / agents Cordis services; no third-party runtime dependencies
  • Architecture Pattern: Dual half-package (Host + Client) integration: lib/index.js is the host page Cordis plugin, subscribes to llm/stream events to capture usage chunks and exposes POST /usage/api; lib/client.js is the browser page React component, mounts two tabs via slots.inject("conversation.view") and slots.inject("settings.section"); automatically recognized and loaded by DSH through dsh.bundle.patch (cordis.patch.yml) + dsh.client declaration
  • Entry Files: lib/index.js (host, exports.default is the Cordis plugin object), lib/client.js (client, exposed via exports["./client"])

Use Cases

DSH users who need to continuously track multi-provider account balances and token consumption such as DeepSeek / SiliconFlow / DigitalOcean. Especially suitable for monthly bill reconciliation, estimating cost differences between peak and off-peak hours, team cost allocation, and bringing historical usage data to external analysis tools (CSV/JSON export).

Prerequisites and Compatibility

DependencyMinimum VersionDescription
DSH (DeepSeek Harness)Not declaredConnects via @deepseek-ai/cordis ^4.0.1 interface, requires host support for webServer / fs / subprocess / credentials / settings / sandboxPolicy / agents seven services
Node>= 18package.json#engines.node declaration
Operating SystemmacOS / Windows / LinuxDirectory picker uses system native: macOS uses osascript, Linux uses zenity or kdialog, Windows uses PowerShell FolderBrowserDialog
Native ModulesNoneNo node-gyp native extensions required, persistence via host process node:fs direct read/write

Installation

dsh plugin --profile web add github:feiyang-dev/dsh-usage-plugin

Configuration

This plugin requires no additional configuration. All behavior is determined by the package's internal PRICING / path resolution logic and the host's settings.llm-pi-ai provider configuration. Prices can be adjusted in the panel's "Price Table" tab and persisted to <data root>/dsh-usage/pricing.json. The DSH_USAGE_DATA_DIR environment variable can be used to override the default data directory when needed.

FAQ

Q: After installation, the "Usage & Consumption" and "Balance Inquiry" tabs don't appear. What should I do?

A: This is usually because the plugin's inject list is missing or truncated. Check whether dsh-usage-boot.log was generated in the data root (default Windows %LOCALAPPDATA%\dsh-usage-plugin\dsh-usage\, macOS/Linux ~/dsh-usage-data/dsh-usage/). It will indicate which specific step failed during activation; normally you should see a route-registered line. If the patch file was manually edited and lost fields, run npm run wire to execute scripts/wire.js and rewire everything.

Q: Where is data stored? Will switching workspaces cause data loss?

A: Starting from v1.9.2, data goes to an independent directory, and v1.9.4 uses the host process node:fs directly, completely bypassing the workspace sandbox: defaults to Windows %LOCALAPPDATA%\dsh-usage-plugin\dsh-usage\ and macOS/Linux ~/dsh-usage-data/dsh-usage\. Switching workspaces no longer causes loss, and uninstalling the DSH desktop app won't clear it together. Records scattered in the user home directory or old workspaces from previous versions get deduplicated and merged when this version first runs based on the time field. Use the DSH_USAGE_DATA_DIR environment variable to force pointing to any path.

Q: How do I check DeepSeek / SiliconFlow / DigitalOcean account balances?

A: Go to the "Balance Inquiry" tab, select a provider and click query. DeepSeek uses the DEEPSEEK_API_KEY configured in "Settings → Models"; SiliconFlow reuses the API Key referenced by the provider with Provider ID or display name "siliconflow" in "Settings → Models"; DigitalOcean requires saving an account-level Personal Access Token starting with dop_v1_ in the panel first (DO AI Inference Key won't work). AMD GPU Cloud shows "Balance query endpoint currently not publicly available".

Q: What does the "Persistence not enabled" prompt mean?

A: This fallback message appears only when all three candidate paths—environment variable, AppData, and user home directory dsh-usage-data—are unwritable. Data then falls back to the current workspace. This indicates abnormal permissions or disk space, often occurring in restricted containers. After seeing this, please check write permissions for those directories, or use DSH_USAGE_DATA_DIR to point to a writable location.

Q: What formats can be exported? Does it automatically open the directory after export?

A: CSV, JSON, and PNG long image. Export directory can be the default (under data root: csv/, json/, images/) or select via "Export Target Directory / Choose Directory…", which opens the system's native folder picker on Linux/macOS/Windows. After export completes, it uses open / xdg-open / explorer.exe to automatically open the directory. PNG long image displays up to 2000 recent records; exceeding this shows a prompt.

Q: Can I migrate records from another device or old version?

A: Just import via CSV or JSON file, which deduplicates and merges using the time field; if you just want to continue using it on another machine, copy usage-records.json from the old data root to the new machine's same location—no import needed.

Q: When do peak/off-peak pricing take effect? How do I change it?

A: Peak/off-peak pricing automatically activates at Beijing time 2026-08-17 00:00; prior historical calls are billed at base pricing. Peak hours are Beijing time 9:00–12:00 / 14:00–18:00. The panel's "Price Table" tab allows runtime modification with immediate persistence, and "Restore Defaults" resets everything with one click.

Q: How do I uninstall?

A: Recommended: dsh plugin --profile web remove @feiyang666/dsh-usage-plugin. If manually installed, please delete the usage-plugin line from cordis.patch.yml and then run pnpm remove / npm uninstall on that package. Uninstalling won't delete the data directory—if no longer needed, please clean it up manually.

Difficulty Level

Beginner — one-command installation with no config file required. Just fill in the API Key for the corresponding provider in "Settings → Models" before querying balances.

Known Issues and Limitations

  • AMD GPU Cloud currently has no publicly available balance query endpoint callable via inference API Key; clicking query in the panel only shows a prompt and directs to AMD Developer Cloud console (lib/balance.js:31-40)
  • DigitalOcean balance queries only work with account-level dop_v1_... Personal Access Tokens—DigitalOcean AI Inference Keys can't be used for this interface (lib/index.js:749-751, lib/balance.js:21-30)
  • The old npm package @feiyang666/deepseekharnessdesktop is no longer maintained; use @feiyang666/dsh-usage-plugin for new installations (README.zh.md:19-26)
  • Don't manually modify files under ~/.dsh/profiles/<name>/node_modules/@feiyang666/dsh-usage-plugin/, as every pnpm update or upgrade repackages from npm and overwrites locally—your changes will be silently discarded (README.zh.md:230)
  • Only DeepSeek official, SiliconFlow, and DigitalOcean (USD) have billing price tables; consumption for other third-party provider calls (amd / aliyun / qwen etc.) is counted as 0 (lib/index.js:107-148)

Read the usage guide →

Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.

Listing badge

Listed on deepseek-plugin.org
[![Listed on deepseek-plugin.org](https://img.shields.io/badge/listed_on-deepseek--plugin.org-007EC6)](https://deepseek-plugin.org/plugins/feiyang-dev/dsh-usage-plugin)

Paste this markdown into your GitHub README to link back to this listing. The badge only states the listing — not a security endorsement.

← Back to plugin directory