Suiwan/whale-purse

whale-purse 🐋

一只住在 DeepSeek Harness（DSH）里的鲸鱼娘桌宠，帮你盯着 DeepSeek 账户余额和当前会话的用量/花费。

把「DeepSeek 余额 + 会话 token 用量/预估花费」做成一只可拖拽的二次元鲸鱼娘，浮在 DSH Web GUI 上。点她弹出用量明细面板（当前 / 历史双 Tab），拖她换位置，位置自动记住；余额 30s、花费 3s 自动刷新。

preview

关于

一只可爱的鲸鱼桌宠，为 DeepSeek Harness 盯着你的 DeepSeek 余额和会话用量/花费。把她拖到任何地方，点击即可打开实时面板，查看实时花费、高峰/低谷定价、预算提醒和历史趋势。

特性

- 🐋 鲸鱼娘桌宠：透明立绘悬浮在页面上，随波轻微摇摆，脚底带投影
- 🖱️ 可拖拽：拖动换位（localStorage 记忆，刷新/重开保持），点击开面板
- 🔔 任务完成提醒：后台会话跑完时鲸鱼娘弹跳 + 头顶冒泡「任务完成啦」，点气泡直达完成会话
- 🏃 状态动作：有任务运行时鲸鱼娘忙碌抖动 + 「忙…」标签；点击她 squash 弹跳回应（纯 CSS，不动形象）
- 💰 余额监视：DeepSeek 官方 Get User Balance 接口，30s 轮询 + 并发去重；请求失败保留上次快照并提示过期
- ⚠️ 低余额/预算提醒：余额低于阈值或今日花费超过预算时，面板警告 + 鲸鱼娘红点；浏览器有通知权限时低余额发送 Notification
- ⚙️ 面板设置：点面板右上角齿轮即可改 model / 低余额阈值 / 今日预算，保存到本地 JSON，无需手改 YAML
- 🧮 会话用量：读 sessionProjections 的 tokenUsage 投影，按官方价格折算花费（输入未命中 / 缓存命中 / 输出三桶，分桶条形图按金额占比绘制、每桶标注 token 数、金额与金额占比，避免缓存命中 token 占大头却几乎不花钱的误导；DeepSeek 官方没有「缓存写入」计费类别，故不展示该桶）；model: auto 时按会话实际请求头识别 flash/pro，识别为非 DeepSeek 模型（如 GPT / Claude）的会话不估算花费；已落盘消息按各自发生时的峰谷档与模型计价，进行中增量按当前档计价；DSH「在新会话中新建分支」checkout 出的历史 seed 不会重复计费，只统计新建分支后的新增用量
- 📊 历史趋势（双 Tab 面板）：「当前」Tab 看余额与实时花费；「历史」Tab 看近 7 天花费柱状图（有 sessionPersistence 时自动合并已保存会话）+ 本会话每条提问的花费明细（多步循环自动合并成一行，问题前 10 字 + Tokens + 花费）
- ⚡ 峰谷定价：北京 9:00-12:00 / 14:00-18:00 高峰价自动切换；面板显示当前档位与距下次切换倒计时；官方定价页每 6h 自动抓取；2026-08-17 前发生的消息按生效前标准价计入历史
- 🌗 主题适配：面板颜色与柱状图深浅随 DSH 浅色/深色主题切换（--dsw-alias-* token）
- 🖥️ 多屏适配：外接大屏/笔记本切换时自动把桌宠夹回视口内，不会丢
- 🛡️ 友好错误：余额/定价请求超时显示「请求超时」而非英文 This operation was aborted
- 🧩 兼容 DSH-better-sidebar：适配其 Explorer 面板的浮层层级，桌宠拖进面板区域也不会被遮挡

安装

1. 把本仓库软链进你的 DSH web profile 依赖：

ln -s /path/to/whale-purse ~/.dsh/profiles/web/node_modules/whale-purse

2. 在 ~/.dsh/profiles/web/cordis.patch.yml 里加一条 insert：

- insert:
- id: whale-purse
name: 'whale-purse'
config:
model: auto           # auto | pro | flash
refreshIntervalSeconds: 30
lowBalanceThreshold: 20   # 余额低于 20 元时提醒（可不写，默认 10）
dailyBudget: 5            # 今日花费超过 5 元时提醒（可不写，默认不提醒）

3. 保存后刷新浏览器即可（Cmd+Shift+R）。

余额接口需要能解析到 DEEPSEEK_API_KEY（凭据缝 → 启动环境 → process.env，逐层回退）。

推荐在鲸鱼娘面板右上角点 ⚙ 设置 修改 model、低余额阈值、今日预算；保存后写入 ~/.dsh/whale-purse.settings.json，优先级高于下面 YAML 里的同名配置，无需重启。

配置

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| model | auto | 计价模型：auto（按会话实际请求头识别；非 DeepSeek 模型不估算花费）/ pro / flash |
| refreshIntervalSeconds | 30 | 余额轮询间隔（秒） |
| apiKeyEnv | DEEPSEEK_API_KEY | API key 的环境变量名 |
| baseUrl | https://api.deepseek.com | 余额接口 base URL |
| pricingRefreshHours | 6 | 官方定价页抓取间隔（小时） |
| lowBalanceThreshold | 10 | 余额低于该值（CNY）时触发低余额提示 |
| dailyBudget | 未设置 | 今日花费预算（CNY），超过后面板提示 |
| enabled | true | 是否启用余额查询 |

项目结构

whale-purse/
├── lib/
│   ├── index.js        # host 端：余额服务 + HTTP 路由（/api/whale-purse/balance、/api/whale-purse/balance/daily、/api/whale-purse/balance/messages、/api/whale-purse/settings）
│   └── client.js       # 浏览器端：鲸鱼娘桌宠 + 双 Tab 面板（WebP 立绘 base64 内联）
├── assets/
│   ├── whale-sprite.webp       # 内联立绘（280×373，透明，约 41KB）
│   ├── whale-sprite.png        # 鲸鱼娘立绘源 PNG（280×373，透明）
│   ├── whale-front-source.png  # 立绘源图
│   └── preview.png             # 预览图
└── scripts/
├── embed-asset.mjs         # 把 whale-sprite.webp/png 重新内联进 lib/client.js
├── screenshot.mjs          # Playwright 截图脚本
└── smoke-test.mjs          # 模型识别/计价逻辑冒烟测试（node scripts/smoke-test.mjs）

whale-sprite.webp 由 PNG 源图生成：cwebp -q 90 -alpha_q 100 -m 6 assets/whale-sprite.png -o assets/whale-sprite.webp。改完素材后运行 npm run embed 重新内联。

更新日志

2026-08-28

- 修复：DSH「在新会话中新建分支」后，新会话不再重复计算 checkout（seed）之前的花费，只统计分支后的新增用量
- 修复：非 DeepSeek 模型（GPT / Qwen / Claude 等）不再被误按 DeepSeek flash/pro 计费，auto 模式下显示「未估算花费」
- 优化：分桶条形图改为按金额占比绘制，并显示每桶金额占比；移除 DeepSeek 不存在的「缓存写入」展示桶
- 测试：新增 scripts/smoke-test.mjs 冒烟测试，覆盖模型识别、分支 seed 跳过与混合模型计价

素材来源与版权

- 鲸鱼娘立绘来自 dafeiyu-pet（MIT License），是 DeepSeek 鲸鱼形象的二创桌宠。
- 本项目为 DeepSeek / DSH 的非官方插件，与 DeepSeek 官方无关联。

License

MIT