DeepSeek Balance Whale Widget: a DSH plugin that watches your API balance from the corner of the screen
DeepSeek Harness（DSH）一只住在 DSH 界面右下角的小鲸鱼娘，帮你盯着DeepSeek账户余额。QQ弹弹，支持拖拽吸附、左吸附翻转、数字滚动动画，随界面自动启用，建议直接喊来你的dsh安装
At a glance
- What is it?
- A floating whale in the DeepSeek Harness web UI polls your DeepSeek balance every 60 seconds and estimates today's spend by diffing consecutive readings. The accounting mode needs no session token; the precise mode does, and it expires.
- Who is it for?
- Adopt it if you run the DSH web profile on Windows and want the balance visible without leaving the interface; the default accounting mode needs only DEEPSEEK_API_KEY and writes to $DSH_HOME/.dshw-usage.json. Do not adopt it if you need exact daily spend while DSH is closed, or if you cannot accept a platform session token that breaks on re-login.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The balance you only notice after it is gone
DeepSeek API spend is invisible until you open the platform website and look. The widget puts that number in the bottom right corner of the DSH web interface as a whale cut-out with a speech bubble, and refreshes it on a 60 second timer, plus on click. The README frames the audience narrowly: people already running DeepSeek Harness with the web profile, on Windows, who want the balance in peripheral vision rather than in a browser tab. It is not a general dashboard and it does not work outside DSH. The project is published under MIT and the default branch is main.
Two accounting modes, and only one of them is honest about gaps
The usage figure is where the design gets interesting. The default mode, which the README calls the whale's own bookkeeping, never calls a usage endpoint. It records the balance each time it polls, and when the balance drops it adds the difference to the current day's total in a local ledger at $DSH_HOME/.dshw-usage.json. Days roll over automatically and the ledger keeps 30 days. If the observed currency changes, the widget resets its baseline instead of recording a difference, which prevents a multi-currency account from corrupting the total. The README states the consequence directly: spend that happens while DSH is closed is missed. The second mode, labelled real-time token, calls the DeepSeek platform usage endpoint and converts token buckets into money using a peak and off-peak price table. That mode needs DEEPSEEK_PLATFORM_TOKEN, which is a platform web session token, not an sk- API key, and the README warns it may need to be re-copied after you log in again.
Peak pricing is hardcoded in lib/index.js
The pricing table lives in a PRICING constant at the top of lib/index.js, and the README tells you to edit it yourself when DeepSeek changes prices. Peak hours are defined as 09:00 to 12:00 and 14:00 to 18:00 on weekdays, everything else off-peak, with weekends priced as off-peak from 2026-08-23. That date is in the future relative to most readers, so treat the weekend rule as a scheduled change described in the README rather than something you can confirm from the running code. The important part is structural: the conversion from tokens to money happens locally against a constant, not against a number the API returns. If the constant drifts from DeepSeek's published rates, the widget will report a wrong amount with full confidence. There is a menu option labelled peak and off-peak hint text with three variants, including one the README calls Liang Wen peak and off-peak, which is flavour rather than function.
Per-turn cost comes from local session events, not the network
Separately from the daily total, the widget listens to local DSH session events and after a turn completes it shows a bubble with that turn's cost, computed from the model's reported usage against the same pricing table. The README notes this path needs no credentials at all. Two menu settings control it: a checkbox for whether to show the cost after each turn, and an auto-close time in seconds where 0 means the bubble stays until dismissed. While the cost bubble is on screen, ordinary balance-change bubbles are suppressed, which avoids two bubbles fighting for the same corner. One caveat the README gives: a turn has to end properly, meaning a turn/end event, before anything is settled, so an interrupted turn produces no figure.
Installing it, and the link:. mistake that silently does nothing
The recommended path installs straight from GitHub without cloning: dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget. The local path is dsh plugin --profile web add link:. run from the repository root, because the repository root is itself the plugin package. The README calls out a specific failure: writing link:.\dsh-whale-widget, because no such subdirectory exists, installs the code as an ordinary dependency rather than a plugin, and the widget simply never appears after a restart. Removing it is dsh plugin --profile web remove dsh-whale-widget. The README also documents a proxy escape hatch using http_proxy, https_proxy and all_proxy environment variables before the add command, and mentions that pnpm may block build scripts, in which case you add the package key under allowBuilds in C:\Users\<username>\.dsh\profiles\web\pnpm-workspace.yaml. Verification is three checks: dsh --profile web --dump-config should list dsh-whale-widget, and the routes /dsh-whale/balance.json and /dsh-whale/widget.js should return 200. There are also /dsh-whale/image.png, /dsh-whale/size.json (GET reads, PUT writes) and /dsh-whale/last-turn.json.
A draggable widget that exposes its own state over HTTP
The widget snaps to the four edges, and to quarter positions along them, with corners combining two edges. When it snaps left, the whole thing mirrors horizontally and the text flips with it. Size is a slider from 0.6 to 2.5 times, and the README says the text position and font size scale with the image. Sound effects are optional mp3s in the assets directory and degrade to silence when the files are missing, which is the right default for a package that ships audio. The HTTP surface is worth flagging for anyone installing this on a shared machine: size and last-turn state are readable and, for size, writable over localhost without authentication. That is consistent with a local developer tool, but it is a real property of the design and the README does not discuss access control.
Where the whale is the wrong tool
If your spend is driven by CI jobs, batch scripts or scheduled calls rather than interactive DSH sessions, the default accounting mode will undercount, because it only sees balance drops that occur while the widget is polling. The token mode is more accurate but depends on a credential that the README describes as valid only while you are logged into the platform website, so it is not a set-and-forget integration. Anyone wanting a stable, machine-readable spend feed should be calling the DeepSeek platform usage API directly from their own monitoring rather than reading a JSON file the widget maintains. The widget is also Windows-oriented in its documentation, with PowerShell commands and a .dsh\profiles\web path; nothing in the supplied material describes a Linux or macOS install, so I cannot say whether one works. And the whole thing is scoped to DSH's web profile, so it is useless to you if you use the DeepSeek API from your own application without DSH.
Maintenance cost and what to check before you rely on it
The maintenance burden concentrates in two places. The PRICING constant in lib/index.js has to be edited by hand when DeepSeek changes rates, and the DEEPSEEK_PLATFORM_TOKEN has to be re-copied after each platform re-login. Version history in the repository shows a rapid sequence of releases in a short window, including v0.2.9, v0.2.10 and a separately tagged v1.0.0+win build called DS Desktop Whale, which suggests the packaging is still moving. The licence is MIT, which permits commercial use and modification; the README's instruction to edit the pricing constant is a normal exercise of that permission. This is a description of the licence text, not legal advice. Before depending on the daily figure for anything, watch the ledger at $DSH_HOME/.dshw-usage.json across a day with a known spend and compare it against the platform page. If the two diverge, the gap is almost certainly spend that happened while DSH was closed, and the token mode is the answer.
Editorial conclusion
Adopt it if you run the DSH web profile on Windows and want the balance visible without leaving the interface; the default accounting mode needs only DEEPSEEK_API_KEY and writes to $DSH_HOME/.dshw-usage.json. Do not adopt it if you need exact daily spend while DSH is closed, or if you cannot accept a platform session token that breaks on re-login. Before trusting the numbers, verify that dsh --profile web --dump-config lists dsh-whale-widget under bundles and that curl http://127.0.0.1:3080/dsh-whale/balance.json returns 200 JSON with a totalBalance field.
Community notes