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.
- Language
- JavaScript
- Branch
- main
Install
$ dsh plugin --profile web add dsh-whale-widgetRun 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 globalfetch,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 +tapIndexto inject client script intoindex.html - Entry File:
lib/index.js(contains both host-side Node logic and embedded browser-sideWIDGET_JSstring)
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
| Dependency | Min Version | Description |
|---|---|---|
| DSH | Not declared | Standard DSH bundle plugin, requires Web profile loading; mounted as dsh-whale-widget in cordis.patch.yml |
| Node.js | ≥ 18 | Source uses native fetch, AbortSignal.timeout, node:fs and other built-in APIs; DSH actual runtime usually ≥ 22 |
| Platform | Cross-platform | Only 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 Modules | None | Does 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:
| Config | Type | Description | Default |
|---|---|---|---|
| Widget Size | Number slider (0.6–2.5) | Overall scale of whale icon, persisted locally | 1.5 |
| Sound Effect Toggle | Switch | Whether to play sound on press/release | Enabled |
| Sound Type | Enum (rubber duck / sound 1) | Which set of sound files to use | Rubber Duck |
| Volume | Number slider (0–1) | Sound playback volume | 0.9 |
| Usage Mode | Enum (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:
| Credential | Required | Purpose |
|---|---|---|
DEEPSEEK_API_KEY | Required | DeepSeek official API Key, used to fetch balance |
DEEPSEEK_PLATFORM_TOKEN | Optional | DeepSeek 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
Authorizationheader (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
DeepSeek Harness(DSH)Web 界面右下角的常驻余额挂件:小鲸鱼气泡图 + DeepSeek API 余额 + 今日已用,每次打开界面自动启用。本项目是标准 DSH 插件包,可通过 dsh plugin 安装/卸载。
特性
- 🐋 常驻自启:随 DSH Web 界面每次打开自动出现(标准 DSH bundle 插件)
- 💰 余额:60 秒自动刷新 + 点击鲸鱼手动刷新;余额变化时数字滚动动画;瞬时网络抖动自动沿用最近余额不报错
- 📊 今日已用:两种模式任选(见下),显示今日消耗金额
- 小鲸鱼记账(推荐,免令牌):不需要任何会话令牌,鲸鱼娘每次观测余额后用余额差值自动记账(
.dshw-usage.json,跨天自动归零归档) - 实时·令牌:填入平台会话令牌后直接调用平台用量接口,按峰谷定价(空闲 9:00–12:00 与 14:00–18:00 之外 / 高峰 9–12 与 14–18 点)实时换算今日已用
- 小鲸鱼记账(推荐,免令牌):不需要任何会话令牌,鲸鱼娘每次观测余额后用余额差值自动记账(
- 🖱️ 拖拽 + 四边四分之一吸附(左/右/上/下,角落可组合)
- 🔄 左吸附时整体水平镜像翻转(文字同步反向、带动画)
- 🧸 按压 Q 弹玩偶效果(按压时底部坐标不变)
- 🎚️ 汉堡菜单(悬停鲸鱼右上角出现):大小滑块(0.6–2.5 倍,尺寸记忆)、音效切换(小黄鸭 / 音效1)、音量调节、用量模式选择
- 🔊 音效:按压/松手音效(可选包内 mp3,缺失时静默降级)
- 💬 随机台词:点击气泡切换随机台词段(6 组加权随机,含峰谷提示/今日已用/卖萌吐槽),再点一次关闭;气泡总显示 5 秒自动收起
- 📐 随浏览器窗口自动缩放;文字位置/字号与图片联动
目录结构
dsh-whale-widget/
├── package.json # DSH bundle 插件元数据
├── README.md # 本文件
├── cordis.patch.yml # 插件挂载声明
├── lib/
│ └── index.js # 宿主侧插件本体
├── assets/
│ ├── DSniang1.png # 小鲸鱼本体(cut-out,气泡由代码绘制)
│ ├── Ya1.mp3 / Ya2.mp3 # 小黄鸭音效(可选)
│ └── D1.mp3 / D2.mp3 # 音效1(可选)
└── whale-widget-prompt.md # 完整规格/维护提示词
安装
方式 A:本地开发安装(当前项目)
在项目根目录(DeepSeek-Balance-Whale-Widget-main)执行:
dsh plugin --profile web add link:.\dsh-whale-widget
说明:
dsh plugin会把参数转发给 pnpm,并在成功后自动把dsh-whale-widget加入dsh.profile.bundles- 使用
link:会在 profile 的node_modules里链接到当前源码目录,方便继续改代码 - 安装完成后重启
dsh web,再 F5 刷新浏览器 - 如果之后移动了源码目录,必须重新到新的项目根目录执行一次:
因为dsh plugin --profile web add link:.\dsh-whale-widgetlink:记录的是源目录的绝对路径;移动后旧链接会失效。若提示已存在/冲突,可先dsh plugin --profile web remove dsh-whale-widget再重新 add。
方式 B:发布到 npm 后安装
如果你把这个包发布到 npm:
cd dsh-whale-widget
npm publish
然后任意机器上安装:
dsh plugin --profile web add dsh-whale-widget
卸载
dsh plugin --profile web remove dsh-whale-widget
从旧手动安装升级
如果你之前按旧方式手动安装过(复制 whale-balance.mjs + 改 cordis.patch.yml),先清理:
$web = "$env:USERPROFILE\.dsh\profiles\web"
Remove-Item "$web\whale-balance.mjs" -ErrorAction SilentlyContinue
Remove-Item "$web\whale-balance.cjs" -ErrorAction SilentlyContinue
Remove-Item "$web\DSniang1.png" -ErrorAction SilentlyContinue
Remove-Item "$web\DSniang02.png" -ErrorAction SilentlyContinue
然后编辑 $web\cordis.patch.yml,删除这段旧补丁:
- insert:
- id: whale-balance-widget
name: ./whale-balance.mjs?v=1
如果里面只有这段,直接改成:
[]
清理后再执行上面的安装命令。
凭据与用量模式
- 余额:需要
DEEPSEEK_API_KEY(在 DSH 凭据服务中配置),用于api.deepseek.com/user/balance - 实时·令牌模式:需要
DEEPSEEK_PLATFORM_TOKEN(平台会话令牌,从浏览器 DevTools 的用量请求Authorization头获取),用于platform.deepseek.com/api/v0/usage/by_api_key/amount - 小鲸鱼记账模式(默认):不需要平台令牌,鲸鱼娘用余额差值自动记账,跨天自动归档
验证
dsh --profile web --dump-config | Select-String -Pattern "whale"
curl http://127.0.0.1:3080/dsh-whale/image.png
curl http://127.0.0.1:3080/dsh-whale/balance.json
curl http://127.0.0.1:3080/dsh-whale/size.json
/dsh-whale/image.png→ 200image/png/dsh-whale/balance.json→ 200,含{"ok":true,"totalBalance":...,"currency":"CNY","todayUsage":...}/dsh-whale/size.json→ GET 返回{scale,sound,vol,soundSet,usageMode};PUT 写入- 浏览器 F5 后右下角出现挂件
常见问题
- 挂件不出现:确认
dsh plugin add成功;dsh --profile web --dump-config里能看到dsh-whale-widget;重启dsh web后 F5。 - 图片不显示:确认
assets/DSniang1.png在插件包内,且没有把旧文件放在 profile 里占用了同名路由。 - 余额报「未配置 DEEPSEEK_API_KEY」:去 DSH 配置凭据。
- 今日已用显示 --:记账模式下需要先跑一次余额观测(60 秒内自动完成);令牌模式需要配置
DEEPSEEK_PLATFORM_TOKEN。 - 没有声音:确认
assets/*.mp3在包内;若不想带音效文件,静默降级为无声音。 - 本地开发改了代码不生效:使用
link:安装时,修改源码后重启dsh web(ESM 模块缓存);如果用已发布版本,需要npm publish新版本后dsh plugin --profile web update dsh-whale-widget。 - 自定义图片:气泡由代码绘制(SVG),鲸鱼本体为 cut-out PNG,放在右下角 59.45%;换图需保证透明背景 cut-out,否则按
whale-widget-prompt.md调整几何参数。
开发与维护
完整规格、视觉参数、架构结论和生成提示词见 whale-widget-prompt.md。修改文字位置、颜色、动画、吸附逻辑、台词组或定价表时参考该文件。
Read the usage guide →
Install steps, key points, FAQ and compatibility for this plugin — auto-derived from indexed fields.
Listing badge
[](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.