Skip to main content

dsh-usage-dashboard

8Stars1Forks1Issues0Watchers

Add a balance and usage dashboard for DSH Web: display official account balance, today's and monthly consumption, model and session cost rankings, cache savings, and bill estimation for peak-valley pricing effective 2026-08-17.

Evidence5/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
TypeScript
License
MIT
Branch
master
cordisdeepseekdeepseek-harnessdshdsh-plugin

Install

cmdweb profile
$ dsh plugin --profile web add @cassius0924/dsh-usage-dashboard

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 Cassius0924/dsh-usage-dashboard for me: review the repository at https://github.com/Cassius0924/dsh-usage-dashboard 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.

At a Glance

Give DSH Web a pair of "eyes": a draggable floating balance window showing remaining balance and how many days it will last based on the recent 7-day average; the session top bar gets an extra "Quota" tab displaying today/month-to-date/cumulative spending, cost rankings by model and session, how much caching has saved you, and bill estimates before/after DeepSeek's August 17, 2026 peak-valley price change—all in the GUI.

Core Features

  • Account Balance & Available Days: Both the floating window and "Quota" page show real-time balance, calculating "Estimated X days remaining" based on the average daily consumption of the last 7 calendar days (including unused days); turns red when under 3 days
  • Today / Month-to-Date / Cumulative Spending Overview: Today shows "vs Yesterday", month-to-date shows "vs Same Period Last Month", expandable to see the actual applied pricing—it's not a black box
  • Peak-Valley Bill Estimation: DeepSeek implements two-tier peak pricing from 2026-08-17 in Beijing timezone (09:00–12:00 and 14:00–18:00); before生效, it recalculates your historical usage at the new rates so you can see the increase; after生效, it shows "how much you could save by moving peak to off-peak"
  • Cache Hit Savings: Each usage record calculates the difference between "non-hit price vs cache-hit price", aggregated into "Caching saved you X CNY"; gives recovery suggestions when hit rate drops below 60%
  • Model & Session Cost Rankings + Current Session Instant Consumption: Model Top N (sorted by cost descending, with input/output/cache three columns), Session Top 6 for quick identification of costly conversations; when entering any session's top "Quota" tab, it first shows "This session has spent X", with each assistant message showing its round consumption
  • Usage Time Distribution & Local Visualization: Last 30 days daily bar chart, 0–23 hour hourly bar chart (multi-select models to stack as grouped bars), last 12 weeks heatmap—all support keyboard exploration and touch tap; data range / corrupted records coverage is explicitly disclosed at dashboard bottom

Technical Implementation

  • Language: TypeScript (host-side ESM, client-side React 18.2 + TSX, esbuild single-file closure bundling)
  • Key Dependencies: @deepseek-ai/cordis ^4.0.0 (host service discovery and plugin runtime), react ^18.2.0 (client UI), @deepseek-ai/dsh-client-runtime / dsh-client-locale / dsh-client-ui-conversation (client bootstrap inject items), esbuild ^0.25.0 + typescript ^5.6.0 (build)
  • Architecture Pattern: DSH standard dual-half (bundle + client). Host half registers prefix routes /api/dsh-usage-dashboard/{balance,usage,session} via ctx.inject(['webServer','credentials','sessionPersistence']): balance calls DeepSeek official /user/balance, usage traverses all local DSH session logs, buckets assistant/message.usage by model (read from latest request/header.config) × Beijing time window; 5-minute server-side memoization to avoid repeated replay. Client half triggers parallel fetchBalance/fetchUsage prefetch on load, mounting to shell.overlay (floating window), conversation.view ("Quota" tab), conversation.chat.assistant-actions (message row cost) three slots; all styles use DSH's --dsw-alias-* theme variables, following host theme
  • Entry Files: Host-side src/index.ts (route registration + memoization); Client-side src/client/index.tsx (three slot registration + prefetch + locale registration); pricing table concentrated in src/pricing.ts, aggregation and billing in src/usage.ts; build output lib/index.js + lib/client.js

Use Cases

When you're running token-intensive agent tasks with DSH and want to know "how much did I spend this month, which sessions and models contributed, how much did caching save me, how much impact will DeepSeek's August 17 price hike have"—it pulls all numbers from local session logs with estimation formulas, letting you answer in the GUI. Suitable for heavy users starting to worry about DeepSeek bills, tuning budgets, or doing cost reviews for the team.

Prerequisites & Compatibility

DependencyMin VersionDescription
DeepSeek Harness (DSH)No specific version declaredcordis.patch.yml registers one line dsh-usage-dashboard in web profile; runtime mounts to three slots provided by host: shell.overlay, conversation.view, conversation.chat.assistant-actions
Node.js>=20package.json#engines.node = ">=20"; build target node22
PlatformCross-platformPure JS/TS, no native module dependencies; balance interface forced to only send to https://api.deepseek.com (official domain)
Native ModulesNoneOnly built-in modules like node:http / node:fs, no node-gyp dependencies
peerDependencies@deepseek-ai/cordis ^4.0.0 / react ^18.2.0Provided by host web profile
Required DataDEEPSEEK_API_KEY configuredFilled in DSH "Settings → Models", or written to $DSH_HOME/.credentials.yaml; when not configured, balance follows { ok:false, error: '未配置 DEEPSEEK_API_KEY' } path, dashboard other parts still display local usage

Installation

dsh plugin --profile web add @cassius0924/dsh-usage-dashboard

After installation, you must restart dsh web: route registration happens in host process, browser refresh alone won't bring /api/dsh-usage-dashboard/* online; after startup, floating window appears at bottom-right, and when entering any session, you can click "Quota" among the three tabs Chat / Trajectory / 额度.

You can also install from GitHub checkout or local path:

dsh plugin --profile web add github:Cassius0924/dsh-usage-dashboard
dsh plugin --profile web add ./path/to/dsh-usage-dashboard

Configuration

This plugin exposes all adjustable fields in the "Settings" card at the end of the "Quota" tab, all persisted to browser localStorage (with version suffix, safe fallback to defaults when old values become invalid). Here's the human-readable field explanation:

ConfigTypeDescriptionDefault
Balance Warning ThresholdNumber (CNY)Warning banner appears at dashboard top and floating window turns warning color when account balance falls below this value; set to 0 to disable10
Monthly BudgetNumber (CNY)Progress based on Beijing timezone month; progress bar turns yellow at 80%, turns red above 100% with estimated month-end overspend amount; set to 0 to disable budget0
Statistics Period7 / 30 / 90 / 365 days (single select)Data window for usage trends, model rankings, session rankings, cache and peak-valley cards in "Quota" tab; switching doesn't clear the 30-day overview cache30
Chart Metricstokens / cost / calls (single select)Primary axis display for bar charts and heatmaps; switching reveals different perspectives on the same windowtokens
Floating Window ToggleSwitchAfter closing, floating window no longer appears at bottom-right (enabled by default)true
Floating Window Visible TabsTab ID multi-selectDetermines which session tabs the expanded floating window can appear under—for example, if you only want it under "Chat", check it here; when newly installing a plugin, won't auto-check if previously hand-modifiedAll tabs

Built-in port, pricing table, cache TTL (balance 60 seconds, usage 5 minutes), memoization reset and other behavioral parameters are not in user configuration; see comments at top of src/usage.ts, src/pricing.ts, src/index.ts for details.

FAQ

Q: After installation, I can't see the "Quota" tab. What should I do?

A: The "Quota" tab is attached to individual session top bar (not the New Session homepage). Open any existing session first, then refresh to see the three tabs Chat / Trajectory / 额度; the floating window at bottom-right is not subject to this limitation—it appears on any page.

Q: Balance is incorrect or shows "未配置 DEEPSEEK_API_KEY"?

A: Balance uses the official https://api.deepseek.com/user/balance endpoint, relying on the DeepSeek API Key already configured in DSH. Please fill in the Key in DSH "Settings → Models" (or put it in $DSH_HOME/.credentials.yaml as DEEPSEEK_API_KEY), then restart dsh web to pull the balance; the endpoint is hard-bound to the official domain, balance requests will be rejected when using a custom baseURL.

Q: Why does the displayed "cost" not match the DeepSeek official bill?

A: This is an estimate, not billing reference. All rules are concentrated in src/pricing.ts: pricing is calculated per usage record based on "model + whether it falls in Beijing timezone peak window (09:00–12:00, 14:00–18:00)"; usage before 2026-08-17 uses old fixed rates, after uses peak-valley two-tier (off-peak is half of peak). Unrecognized models estimate at the higher deepseek-v4-pro side, conservatively not underestimating. Platform discounts, gift credit consumption order and other invisible items are not included—refer to official bill.

Q: First time opening the dashboard takes a long time?

A: "Usage" requires traversing all local DSH session logs for aggregation, about 5 seconds in local testing. Two things are done to avoid repeated replay: server memoizes the result for 5 minutes; client triggers balance and usage prefetch in parallel on load, by the time user actually clicks the tab, data is likely already prefetched into cache, first screen renders immediately. Skeleton placeholders show instead of empty text when there's no data. Click the top-right "↻" refresh button to see latest numbers immediately (with ?refresh=1 to bypass memoization).

Q: This shows local data—will multiple devices/accounts be counted together?

A: No. The coverage card (dashboard bottom) explicitly states the data range is "DSH session logs on current device", excluding other devices, DeepSeek platform direct calls, or deleted local logs. It simultaneously shows how many sessions were scanned, how many corrupted records were skipped, earliest/recentest valid record timestamps, allowing users to calibrate their understanding of this estimate.

Q: How do I adjust the balance warning threshold? When does it trigger?

A: Change the warning threshold in the "Settings" card at the end of "Quota" tab, default ¥10, set to 0 to disable. When breached, a warning banner appears at dashboard top with "Can sustain X days + Go to recharge", floating window dot and balance number simultaneously turn warning color; after threshold is changed, both sides' alert status sync, no inconsistency.

Q: When monthly budget reaches 100%, will it automatically stop model calls?

A: No, this plugin's budget and overspend warnings are only reminders, not blockers. Progress bar turns yellow at ≥80%, turns red at ≥100% and dashboard shows estimated month-end overspend at current rate. For hard limits, please handle at the model layer.

Q: What should I watch out for when uninstalling?

A: After dsh plugin --profile web remove @cassius0924/dsh-usage-dashboard, just restart dsh web, routes and services are all revoked. Plugin writes no files, spawns no background processes; the only residual is preferences and cache in browser localStorage prefixed with dsh-usage-dashboard:pref: / dsh-usage-dashboard:balance / :usage, manually clear if needed, or they'll reappear on next reinstall.

Q: If I modify the built-in pricing table, can it keep up with DeepSeek price changes?

A: When DeepSeek changes prices, just modify the two tables in src/pricing.ts (LEGACY_RATES and PEAK_RATES, per pro/flash two tiers × cache hit/miss/output three columns). This plugin has no "one-click fetch official pricing page" feature; after manual maintenance, run pnpm run build to take effect.

Getting Started

Beginner — one line dsh plugin --profile web add @cassius0924/dsh-usage-dashboard plus restart dsh web, after restart zero configuration needed to see floating window and "Quota" tab.

Known Issues & Limitations

  • Data range limited to local: Coverage card explicitly states dashboard statistics only cover "DSH session logs on current device", excluding other devices, DeepSeek platform direct calls, or deleted local logs
  • Cost is estimate: Excludes DeepSeek platform discounts, gift credit consumption order and other invisible items;口径不完全一致 with official bill; peak-valley periods are judged by Beijing timezone, not by browser timezone
  • First cold start replays all session logs: Server memoizes result for 5 minutes to avoid replay on every tab switch, forced refresh still possible (?refresh=1 / floating window ↻)
  • Unrecognized models estimated at higher deepseek-v4-pro side: Deliberately conservative, interface simultaneously shows "Unknown model priced as deepseek-v4-pro" (src/pricing.ts:47 / src/client/locales.ts:55)
  • Single interface口径: Balance only trusts DeepSeek official domain (api.deepseek.com), balance request returns error when pointing to non-official domain, won't redirect or fallback for misconfiguration
  • Client preferences and cache in browser localStorage (with version suffix): Not synced across devices; silently degrades in private mode / quota exhausted (no error), user may experience "suddenly forgot settings"
  • Floating window "click to jump to Quota tab" capability: DSH public client API doesn't expose view switch entry, avoids fragile binding via DOM text clicking; currently positions via drag/collapse to corners, main entry still "Quota" tab in session top bar (TODO.md:9-10)
  • Must restart dsh web after install/update to take effect: Route registration happens at host process startup, browser refresh alone won't bring /api/dsh-usage-dashboard/* online

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/Cassius0924/dsh-usage-dashboard)

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