Skip to main content

DeepSeek-Balance-Whale-Widget

208Stars8Forks0Issues0Watchers

DSH Web interface whale-shaped balance widget in the bottom right corner: displays DeepSeek API balance and today's usage in real-time (supports differential accounting or peak/off-peak pricing), draggable with snap-to functionality and customizable.

Evidence4/5methodologySourceInstallMaintenanceDSH versionSecurity scan
Machine-auditedInstall commandRepo verifieddsh-plugin topicLicenseREADMEAI wiki
Language
JavaScript
Branch
main
cordisdeepseekdeepseek-harnessdeveloper-toolsdshdsh-plugindsh-pluginsfloating-widget

Install

cmdweb profile
$ dsh plugin --profile web add dsh-whale-widget

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 MeteorNOX/DeepSeek-Balance-Whale-Widget for me: review the repository at https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget 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 resident whale balance widget in the bottom-right corner of the DSH Web interface that automatically fetches DeepSeek API balance every 60 seconds and displays the daily consumption amount. It automatically records expenses through balance differences, or reads platform tokens for real-time peak-valley price conversion, allowing you to monitor account usage without opening the DeepSeek dashboard.

Core Features

  • Automatically display DeepSeek API account balance, refresh every 60 seconds, click the whale to manually refresh immediately; balance numbers have scrolling animation
  • Automatically accumulate today's consumption through balance differences, reset across days and retain 30 days of history, no platform token required
  • Optional "Real-time·Token" mode: after reading platform session token, convert today's consumption in real-time based on peak-valley pricing (9–12 / 14–18 peak, 6x price)
  • Mouse drag to move position, auto-snap to screen edge midpoints (left/right/top/bottom) after release; when snapped to left, the entire widget flips horizontally with text reversed
  • Click whale to show current time period (peak/idle) and today's usage; click bubble to switch 6 groups of weighted random lines (including cute/吐槽/peak-valley tips), auto-collapse after 5 seconds
  • Hamburger menu to adjust size (0.6–2.5x), sound effects (rubber duck / sound 1), volume, usage mode; optional press/release sound effects

Technical Implementation

  • Language: JavaScript (ESM)
  • Key Dependencies: Only uses Node built-in modules (node:fs, node:path, node:os, node:url) and global fetch, AbortSignal.timeout, no third-party npm packages
  • Architecture: Standard DSH bundle plugin, declares insertion into Web profile via dsh.bundle.patch (cordis.patch.yml); host side registers 6 webServer routes + tapIndex to inject client script into index.html
  • Entry File: lib/index.js (contains both host-side Node logic and embedded browser-side WIDGET_JS string)

Use Cases

DeepSeek API power users want to see current balance and daily consumption at a glance when opening DSH Web, avoiding repeated logins to DeepSeek console. Regular users can grasp approximate spending with the default "Whale Accounting" mode; users willing to configure platform tokens can switch to "Real-time·Token" mode for precise peak-valley split costs. Suitable as a consumption dashboard for long-running tasks, long-running Agents, and multi-session concurrency.

Prerequisites & Compatibility

DependencyMin VersionDescription
DSHNot declaredStandard DSH bundle plugin, requires Web profile loading; mounted as dsh-whale-widget in cordis.patch.yml
Node.js≥ 18Source uses native fetch, AbortSignal.timeout, node:fs and other built-in APIs; DSH actual runtime usually ≥ 22
PlatformCross-platformOnly reads/writes JSON/PNG/MP3 files, no native modules; source code retains a few Windows dev machine hardcoded paths (D:/TestBox/deepseek/...) as legacy fallback
Native ModulesNoneDoes not depend on any native Node extensions
Credentials—DEEPSEEK_API_KEY (required) for fetching balance; DEEPSEEK_PLATFORM_TOKEN (optional) for "Real-time·Token" mode

Installation

dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget

Configuration

Widget preferences are adjusted via the hamburger menu in the top-right corner of the Web interface and automatically persisted to ~/.dshw-size.json, no manual config file needed:

ConfigTypeDescriptionDefault
Widget SizeNumber slider (0.6–2.5)Overall scale of whale icon, persisted locally1.5
Sound Effect ToggleSwitchWhether to play sound on press/releaseEnabled
Sound TypeEnum (rubber duck / sound 1)Which set of sound files to useRubber Duck
VolumeNumber slider (0–1)Sound playback volume0.9
Usage ModeEnum (whale accounting / real-time·token)Calculation method for "Today's Usage"Whale Accounting

Credentials are injected via DSH credential service (ctx.credentials.resolve), plugin does not write to disk:

CredentialRequiredPurpose
DEEPSEEK_API_KEYRequiredDeepSeek official API Key, used to fetch balance
DEEPSEEK_PLATFORM_TOKENOptionalDeepSeek platform session token, only needed for "Real-time·Token" mode

FAQ

Q: What needs to be configured first to see the balance?

A: You must first configure DEEPSEEK_API_KEY (DeepSeek official API Key) in the DSH credential service, otherwise the balance area will display "DEEPSEEK_API_KEY not configured".

Q: What mode does "Today's Usage" display by default?

A: The default is "Whale Accounting" mode, which doesn't require any platform token—the widget accumulates the difference to daily usage every time it observes a balance decrease, automatically resets across days and archives. If you want more precise numbers, switch to "Real-time·Token" mode in the hamburger menu and fill in DEEPSEEK_PLATFORM_TOKEN.

Q: What if the widget moves to the middle of the screen after dragging?

A: Drag the whale to any edge midpoint (left/right/top/bottom), and it will automatically snap to the corresponding edge after release; the middle area stays where you released it. When snapped to the left, the entire widget flips horizontally with text reversed.

Q: What if there's no sound?

A: Check if assets/Ya1.mp3, Ya2.mp3, D1.mp3, D2.mp3 are bundled with the release. When audio files are missing, the plugin silently degrades to no sound (no error reported).

Q: Source code changes don't take effect?

A: ESM modules are cached, you need to restart dsh web after modifying the source. If using a published npm version, you need to npm publish to bump the version then dsh plugin --profile web update dsh-whale-widget.

Q: How long is balance history retained?

A: In "Whale Accounting" mode, .dshw-usage.json retains up to 30 days of daily consumption history, automatically cleaning up the oldest records afterwards.

Q: Will the widget error out during network fluctuations?

A: No. The balance interface retries once for network errors and 5xx, during transient fluctuations it uses the most recently successful balance, marking the response as stale=true, and the frontend continues showing the old value instead of throwing an error.

Q: Does this plugin save my API Key?

A: No. The key is always read only from the DSH credential service (ctx.credentials.resolve), the plugin neither caches nor writes it to disk; the ledger file .dshw-usage.json only stores balance differences and dates, containing no sensitive credentials.

Difficulty Level

Beginner — ready to use after installation, the only required item DEEPSEEK_API_KEY can be configured in a few clicks in DSH credentials; advanced features (real-time token, peak-valley pricing) are optional.

Known Issues & Limitations

  • Source code hardcodes Windows dev machine paths D:/TestBox/deepkey/... as fallback for image/audio/ledger files (lib/index.js:17-22, lib/index.js:44-50), no impact on non-Windows users but will appear in fallback candidate list
  • "Real-time·Token" mode depends on DeepSeek platform session token, needs to be manually copied from browser DevTools usage request Authorization header (README.md:110-111), DeepSeek has no official public token acquisition process
  • Whale body image is a fixed cut-out PNG (assets/DSniang1.png), bubble is drawn by code SVG; if changing image, ensure transparent background cut-out, otherwise need to sync adjust geometry parameters (README.md:136)
  • Price table (PRICING) is hardcoded as source constant (lib/index.js:67-74), after DeepSeek adjusts pricing, source needs modification and new version release
  • "Whale Accounting" mode only accumulates differences when "balance decreases", balance increases from same-day account top-ups or refunds are not recorded as negative values (difference logic in lib/index.js:1167-1191), meaning if top-up and consumption interleave on the same day, final daily usage may differ from actual consumption

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/MeteorNOX/DeepSeek-Balance-Whale-Widget)

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