dsh-whale-widget: A Balance Bookkeeping Whale for DeepSeek Harness

What Does It Do?

The Whale Widget is a DSH plugin for DeepSeek Harness that keeps a small whale parked in the bottom-right corner of the DSH web interface, showing your DeepSeek API balance, today's spend, and the cost of each conversation turn. It removes the need to open a separate page to check balance and usage by folding bookkeeping, peak/off-peak pricing, usage history, and customizable speech bubbles into one clickable widget. This repository is an enhanced fork of the upstream whale widget based on upstream v0.4.2, maintained by TuWeiZhi under the MIT license, adding only idle auto-speak and a shuffled random-phrase bag.

Core Features

• Balance and spend tracking: balance refreshes every 60 seconds or on click, decreases accumulate as spend while top-ups and grants are recorded separately, with amounts kept to 8 decimal places.
• Per-turn cost bubbles: listens to local DSH session events, converts real model usage into money, and pops a cost bubble after each turn, with an on/off switch and configurable auto-close delay.
• Peak/off-peak pricing: distinguishes weekday peak hours from idle hours in Beijing time, treats weekends as off-peak from 2026-08-23, and offers countdown and multiple display styles.
• Bubble system: click sequences, modular layouts, side-by-side weighted bubbles, and fully customizable bubble content with a placeholder for the amount.
• Idle auto-speak and shuffle bag: the two additions over upstream, letting the whale speak on its own when idle and drawing random phrases without repeats within a round.
• Usage record window: today, last 7 days, and all-time totals, model share bars, expandable per-day details, and search by date or model name.

How to Use This Plugin?

Once enabled in DSH, the whale appears automatically in the bottom-right corner each time the web interface opens, and clicking it refreshes the balance manually. To edit bubble content, go to the menu, then Sound & Prompts, then Global Settings, expand the per-turn cost section, and choose to edit the prompt content; size, snapping, and sound are all adjusted from the main menu, and changes in the panel only apply after you save. Note that this fork and the upstream package are separate packages that conflict if installed side by side, so remove the upstream version first if you already have it; the desktop client reads a different profile than the web interface, so let DSH install it from within a desktop session.

How to Troubleshoot This Plugin?

If the balance stops updating, first check that an API key is configured in DSH credentials or that you are signed in to a DeepSeek account under Settings → Account & Balance; brief network hiccups fall back to the last known balance instead of erroring. When a balance increase is detected, the widget flags a pending balance adjustment that you can reconcile under the built-in DeepSeek bookkeeping settings. Top-edge snapping is off by default; to enable it, open the snapping and flipping settings from the menu, set the top value above zero, and confirm.