MeteorNOX/DeepSeek-Balance-Whale-Widget

What the DeepSeek Balance Whale Widget does

The repository contains a plugin for the DeepSeek Web/desktop client (DSH). It adds a small, always‑on‑screen “whale” widget that shows:

• Your DeepSeek API balance (auto‑refreshes every 60 s, with a smooth rolling number).
• Today’s spend – calculated from the change in balance and from per‑turn token usage.
• Cost of the current turn – a bubble pops up after each model response showing the amount of money that turn cost.
• Customisable bubbles – you can edit the text, add random sentences, images, GIFs, or show balance/price information.
• Peak‑off‑peak pricing – the widget knows the DeepSeek “peak” schedule and can display the appropriate price.
• Budget / low‑balance alerts – pop‑ups when the balance falls below a threshold or when today’s spend exceeds a limit.
• Audio feedback – press‑/release sounds, turn‑end sounds, and optional prompts for questions/authorisations.
• Drag‑and‑drop positioning – the whale can snap to screen edges, be mirrored, or be freely placed.

How it works

1. Data source – The plugin first tries to read DEEPSEEK_API_KEY from the DSH credential store. If that key is missing it falls back to the logged‑in DeepSeek account that DSH can query internally.
2. Accounting core – lib/accounting.mjs watches the balance endpoint, records every increase/decrease, and keeps a ledger (90‑day roll‑up, up to 20 k entries). It also converts token usage (input, cache, output, reasoning) into a monetary cost using DeepSeek’s built‑in price table (or a custom price you can set per model).
3. UI – assets/whale-widget.js draws the whale and the bubbles in the bottom‑right corner of the DSH UI. All visual settings (size, colour, font, mirroring, etc.) are stored in $DSH_HOME/.dshw‑size.json.
4. Extensibility – The widget ships with a “module library” that lets you compose bubble rows from text, links, random sentences, images/GIFs, or built‑in placeholders such as {balance}, {cost}, {quota}. Modules can be saved and reused.
5. Multi‑vendor support – Through the “Custom API” panel you can add other providers (OpenRouter, Kimi, OpenAI‑compatible gateways, etc.). Each provider gets its own balance/quota modules, and the widget can display them alongside DeepSeek.

Installation paths

Target	Branch	Install command
DSH Web UI (bottom‑right widget)	main	dsh plugin --profile web add dsh-whale-widget (npm) or … add github:MeteorNOX/DeepSeek-Balance-Whale-Widget
DSH Desktop (Electron) client	main	Let the desktop client install it itself: type “把 dsh‑whale‑widget 装上” in a DSH session, or use the built‑in plugin manager.
Codex desktop app (different code path)	For‑Codex	Unzip to %USERPROFILE%\plugins\api-balance‑whale and follow the branch‑specific docs.

Only one of the two product lines may be used at a time – they are completely independent.

Configuration files (stored under $DSH_HOME)

File	Purpose
.dshw‑size.json	UI size, snap‑points, audio group selection, peak‑price style
.dshw‑usage.json	Ledger of balance observations, per‑turn cost, alert thresholds, audio settings
.dshw‑bubble.json	Custom bubble sequences and module library
.dshw‑api.json	List of extra providers you added, with endpoint URLs, JSON paths, and optional per‑token pricing
.dshw‑usage‑archive.json	Old ledger data (90 days for turn‑by‑turn, 365 days for daily aggregates)
.dshw‑codex.json	Cache of local Codex session logs for the Codex‑mode branch

When you might use it

• You run many DeepSeek calls and want a quick visual cue of how much money you are spending.
• You need a budget guard that warns you before the balance runs out.
• You like the playful “whale” UI and want to customise the bubble messages (e.g., random motivational quotes, GIFs, or a daily‑budget reminder).
• You work with multiple LLM providers and want a single widget that can show each provider’s remaining quota.

---

Bottom line: this repo is a fully‑featured, installable DSH plugin that turns the DeepSeek client into a small accounting dashboard with a cute, highly customisable whale widget.