crazysmallbamboo/whale-widget-standalone

鲸鱼娘余额挂件（独立版）🐋

一只住在屏幕右下角的鲸鱼娘，帮你盯着 DeepSeek 账户的余额与消费。

不依赖 DeepSeek Harness（DSH），可单独运行。沿用原挂件 MeteorNOX/DeepSeek-Balance-Whale-Widget 的鲸鱼娘图片素材、峰谷价格表与记账逻辑。

功能

无边框、置顶、可拖动的悬浮窗，实时显示：

| 项目 | 说明 |
|---|---|
| Token 价格 | 当前时段的峰价 / 谷价（deepseek-v4-pro） |
| 今日消费 | 余额差值记账，跨天自动归档（保留 30 天） |
| 剩余额度 | DeepSeek 账户余额 |
| 本轮消耗 | 本次打开挂件以来的余额下降 |
| 上一轮对话 | 最近一次 DSH 对话的 token 消耗金额 |

交互：

- 60 秒自动刷新，点击鲸鱼娘手动刷新
- 拖动挂件内部任意位置可移动
- 拖动边框可自由缩放：上 / 下 / 左 / 右 / 四个角共八个方向都能抓，等比缩放（图片和字号一起变），
范围 0.4×～3×；鼠标移到边框上时边框会高亮、指针变成缩放箭头，告诉你这里能拖
- 点 ✕ 或按 Esc 关闭
- 右键菜单：
- 大小：小 / 默认 / 大 三档快捷缩放（拖边框拖出满意尺寸后，也可以用它快速回到常用档位）
- 更换图片：选择任意 PNG/JPG/GIF 图片替换鲸鱼娘
- 恢复默认图片：换回自带鲸鱼娘素材
- 设置 API Key：手动填入 DeepSeek API Key（无需 DSH）
- 立即刷新 / 回到右下角 / 关闭

大小、图片、API Key 以及窗口位置都会自动保存到 %APPDATA%\whale-widget\config.json，下次打开沿用；拖出来的尺寸也会原样恢复。

窗口位置存不下来时（或换了显示器后窗口跑到看不见的地方），右键 → 回到右下角 即可复位。
拉取失败时界面会保留上一次的数字并调暗表示已过期，不会因为一次网络抖动就把余额清空。

个人配置存放在用户目录，不在本项目文件夹内：这样即使你把项目提交 / 上传到 Git，API Key 也不会被一起带出去。首次运行会自动迁移旧版留在项目目录里的 config.json。

环境要求

- Windows
- Python 3.8+（含 tkinter，Anaconda / 官方 Python 均可）
- Pillow（PIL，用于缩放图片）

安装 Pillow：

pip install pillow

使用

1. 双击 鲸鱼余额挂件.bat 启动（也可直接运行 pythonw whale_widget.pyw）
- 启动器用 %~dp0 定位同目录下的脚本，不写死任何绝对路径，整个文件夹可以随意移动 / 改名
- 依次尝试 pythonw → pyw → python，都没找到时给出安装提示
2. 配置 API Key（二选一）：
- 右键 → 设置 API Key，手动填入（推荐，无需 DSH）
- 或使用 ~/.dsh/.credentials.yaml 里的 DEEPSEEK_API_KEY（如果装了 DSH）
3. 右键可调整大小、更换图片

完全不依赖 DSH：图片素材已内置，API Key 可手动配置。想开机自启，把 .bat 快捷方式放进「启动」文件夹即可。

下载方式：请用 git clone 或网页 Code → Download ZIP。这两条路径拿到的启动器都是 CRLF 行尾（仓库已用 .gitattributes 把 .bat 钉死为不做任何行尾转换）。

⚠️ 不要在 GitHub 文件页上右键单独保存或直接下载 .bat：raw 视图会把行尾转成 LF，而 cmd.exe 解析 LF 行尾的批处理会直接失败（连 set 语句都会从中间断开）。若你已经被这样坑到，直接运行 pythonw whale_widget.pyw 效果完全一样，或重新用 ZIP 下载。

如果你自己编辑这个 .bat，也请务必保持 CRLF 行尾——tests.py 里有对应的自检会拦住。

工作原理

余额

调用 https://api.deepseek.com/user/balance，用 DEEPSEEK_API_KEY 拉取账户余额（优先选 CNY 币种）。

Token 峰谷价格

沿用原挂件的价格表（CNY / 百万 token，每项为「谷价 / 峰价」）：

| 模型 | 命中缓存 | 未命中缓存 | 输出 |
|---|---|---|---|
| deepseek-v4-pro | 0.15 / 0.30 | 4.5 / 9.0 | 13.5 / 27.0 |

峰谷判定：工作日 9:00–12:00、14:00–18:00（北京时间）为峰价，其余及周末全天为谷价。

界面上的「Token价格」一栏显示的是当前时段的输出价（谷价 ¥13.50/M 或峰价 ¥27.00/M）；
上面三列价格同时用于折算「上一轮对话」的花费。whale_widget.pyw 里只内置了
deepseek-v4-pro 这一档（常量 PRO_PRICE）。

今日消费（小鲸鱼记账）

每次观测余额后，用余额下降的差值累计当天消费；跨天自动归档，币种切换不记差值。

账本位置：

| 情况 | 账本文件 | 说明 |
|---|---|---|
| 手动填写的 API Key | ~/.dsh/.dshw-usage-.json | 按账户隔离，换 Key 不会把两个账户的余额差算成消费 |
| 来自 DSH 凭据 / 未配置 | ~/.dsh/.dshw-usage.json | 与原 DSH 挂件共享同一账本 |

- ~/.dsh 不存在或不可写时，自动改用脚本同目录存放，并自动创建所需文件夹（无需 DSH 也能记账）
- 账本写入失败时状态栏会显示 账本写入失败，不会静默丢数据

上一轮对话消耗
读取 DSH 会话投影缓存 ~/.dsh/storages/session_projcache/sessions/*.json 中最近一次会话的 tokenUsage.last.buckets（未命中输入 / 命中缓存 / 输出 token），按当前峰谷价折算金额。无 DSH 会话数据时显示 --。

自检 / 测试

仓库自带四个可移植的自检脚本（不含任何硬编码路径，克隆到任意目录都能跑）：

python tests.py                 # 42 项逻辑自检（价格表、峰谷判定、账本、币种选择、路径隔离、启动器）
python test_fresh_user.py       # 14 项「全新用户」模拟：拷到临时目录、清空环境，验证无 DSH 也能记账
python test_gui_regressions.py  # 90 项 GUI 交互回归（位置、拖边框缩放、换图、大图、失败保留数据）
python test_gui_nokey.py        # 无 Key 时启动 GUI，确认不崩溃并给出「未找到 API Key」提示

全部脚本都直接调用 whale_widget.pyw 里的真实函数（不是复制的副本），路径相对脚本自身解析，
并把 DSH_HOME / 配置 / 账本 / 凭据重定向到临时目录，不会污染你本机的配置与真实账本。

其中一组断言专治实测踩过的坑，改坏了会被立刻拦住：

- 启动器必须是 CRLF 行尾、且不含任何盘符绝对路径
- 改「大小」后窗口位置必须不变；拉取失败必须保留上次数字而不是清成 --
- 换图 / 恢复默认图片必须真的重建画面（渲染缓存的 key 要同时包含图片来源）
- 拖动边框后对边必须钉住不动、字号要同步、✕ 关闭按钮不能被缩放区吃掉
- 选了非图片文件不能写进配置；配置里的图片失效时要自动退回自带素材
- 大图必须先降采样再缓存（否则拖动边框会卡成幻灯片）

借物 / 致谢

- 鲸鱼娘图片素材（assets/DSniang1.png 等）
- 峰谷价格表与「小鲸鱼记账」逻辑

以上均来自 MeteorNOX/DeepSeek-Balance-Whale-Widget（MIT License，Copyright (c) 2026 MeteorNOX）。

许可

MIT