# DeepSeek-Balance-Whale-Widget

> DSH Web 界面右下角的小鲸鱼余额挂件：实时显示 DeepSeek API 余额、今日已用（差额记账或按峰谷定价），可拖拽吸附与个性化。

## Metadata

- Author: [@MeteorNOX](https://github.com/MeteorNOX)
- Repo: <https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget.git>
- GitHub: [MeteorNOX/DeepSeek-Balance-Whale-Widget](https://github.com/MeteorNOX/DeepSeek-Balance-Whale-Widget)
- Stars: 208
- Language: JavaScript
- Topics: `cordis`, `deepseek`, `deepseek-harness`, `developer-tools`, `dsh`, `dsh-plugin`, `dsh-plugins`, `floating-widget`, `plugin`
- Forks: 8
- Open Issues: 0
- Last push: 2026-08-20T13:45:23.000Z
- Added: 2026-08-20T00:00:00.000Z

## Install

```bash
dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget
```

## Wiki

## 一句话定位
这是一个常驻 DSH Web 界面右下角的小鲸鱼余额挂件，每隔 60 秒自动拉取 DeepSeek API 余额并显示当日消费金额。它通过余额差值自动记账，或读取平台令牌按峰谷定价实时换算，让你在不打开 DeepSeek 后台的情况下随时掌握账户消耗。

## 核心能力
- 自动显示 DeepSeek API 账户余额，60 秒刷新一次，点击鲸鱼可立即手动刷新；余额数字带滚动动画
- 通过余额差值自动累计今日消费，跨天自动归零并保留 30 天历史，无需平台令牌
- 可选「实时·令牌」模式：读取平台会话令牌后，按峰谷定价（9–12 / 14–18 高峰，价高 6 倍）实时换算当日消费
- 鼠标拖拽可移动位置，松手后自动吸附到屏幕四边中点（左/右/上/下）；吸附到左边时整体水平镜像翻转，文字同步反向
- 点击鲸鱼显示当前时段（高峰/空闲）与今日已用；点击气泡切换 6 组加权随机台词（含卖萌 / 吐槽 / 峰谷提示），5 秒后自动收起
- 汉堡菜单调节大小（0.6–2.5 倍）、音效（小黄鸭 / 音效1）、音量、用量模式；可选按压 / 松手音效

## 技术实现
- **语言**: JavaScript（ESM）
- **关键依赖**: 仅使用 Node 内置模块（`node:fs`、`node:path`、`node:os`、`node:url`）与全局 `fetch`、`AbortSignal.timeout`，无第三方 npm 包
- **架构模式**: 标准 DSH bundle 插件，通过 `dsh.bundle.patch`（`cordis.patch.yml`）声明插入 Web profile；宿主侧注册 6 条 webServer 路由 + `tapIndex` 注入客户端脚本到 `index.html`
- **入口文件**: `lib/index.js`（同时包含宿主侧 Node 逻辑与内嵌的浏览器端 `WIDGET_JS` 字符串）

## 适用场景
DeepSeek API 重度用户希望在打开 DSH Web 时一眼看到当前余额与当天消费，避免反复登录 DeepSeek 控制台。普通用户用默认的「小鲸鱼记账」模式就能掌握大致花费；愿意配置平台令牌的用户可切到「实时·令牌」模式拿到精确的峰谷分摊费用。适合长跑任务、Agent 长时间运行、多会话并发时作为消费监控仪表。

## 前置依赖与兼容性

| 依赖 | 最低版本 | 说明 |
|---|---|---|
| DSH | 未声明 | 标准 DSH bundle 插件，需 Web profile 加载；`cordis.patch.yml` 中以 `dsh-whale-widget` 为挂载点 |
| Node.js | ≥ 18 | 源码使用了原生 `fetch`、`AbortSignal.timeout`、`node:fs` 等内置 API；DSH 实际运行通常 ≥ 22 |
| 平台 | 跨平台 | 仅读写 JSON / PNG / MP3 文件，无原生模块；源代码中保留了几条 Windows 开发机硬编码路径（`D:/TestBox/deepseek/...`）作为旧版降级兜底 |
| 原生模块 | 无 | 不依赖任何原生 Node 扩展 |
| 凭据 | — | `DEEPSEEK_API_KEY`（必填）用于拉取余额；`DEEPSEEK_PLATFORM_TOKEN`（可选）用于「实时·令牌」模式 |

## 安装方式

```bash
dsh plugin --profile web add github:MeteorNOX/DeepSeek-Balance-Whale-Widget
```

## 配置项

挂件本身的偏好通过 Web 界面右上角汉堡菜单调节并自动持久化到 `~/.dshw-size.json`，无需手写配置文件：

| 配置 | 类型 | 说明 | 默认值 |
|---|---|---|---|
| 挂件大小 | 数字滑块（0.6–2.5） | 鲸鱼图标的整体缩放比例，记忆到本地 | 1.5 |
| 音效开关 | 开关 | 按压 / 松手时是否播放音效 | 开启 |
| 音效类型 | 枚举（小黄鸭 / 音效1） | 选择哪一套音效文件 | 小黄鸭 |
| 音量 | 数字滑块（0–1） | 音效播放音量 | 0.9 |
| 用量模式 | 枚举（小鲸鱼记账 / 实时·令牌） | 「今日已用」的计算方式 | 小鲸鱼记账 |

凭据通过 DSH 凭据服务（`ctx.credentials.resolve`）注入，插件不落盘：

| 凭据 | 是否必填 | 用途 |
|---|---|---|
| `DEEPSEEK_API_KEY` | 必填 | DeepSeek 官方 API Key，用于拉取余额 |
| `DEEPSEEK_PLATFORM_TOKEN` | 可选 | DeepSeek 平台会话令牌，仅「实时·令牌」模式需要 |

## 常见问题

**Q: 需要先配置什么才能看到余额？**

A: 必须先在 DSH 凭据服务中配置 `DEEPSEEK_API_KEY`（DeepSeek 官方 API Key），否则余额区域会显示「未配置 DEEPSEEK_API_KEY」。

**Q: 「今日已用」默认显示的是什么模式？**

A: 默认是「小鲸鱼记账」模式，不需要任何平台令牌——挂件每次观测到余额下降就把差值累加到当天用量，跨天自动归零并归档。如果想要更精确的数字，可在汉堡菜单切到「实时·令牌」模式并填入 `DEEPSEEK_PLATFORM_TOKEN`。

**Q: 拖动后挂件跑到屏幕中间怎么办？**

A: 把鲸鱼拖到屏幕左 / 右 / 上 / 下四边任一中点附近，松手后会自动吸附到对应边；中间区域则停留在你松手的位置。吸附到左边时整体水平翻转，文字也同步反向。

**Q: 没声音怎么办？**

A: 检查 `assets/Ya1.mp3`、`Ya2.mp3`、`D1.mp3`、`D2.mp3` 是否随包发布。音频文件缺失时插件会静默降级为无声音（不会报错）。

**Q: 本地改了源码不生效？**

A: ESM 模块有缓存，改完源码后需要重启 `dsh web`。如果用的是已发布的 npm 版本，改完需要 `npm publish` 升版本再 `dsh plugin --profile web update dsh-whale-widget`。

**Q: 余额会保留多久的历史？**

A: 「小鲸鱼记账」模式下，`.dshw-usage.json` 最多保留最近 30 天的每日消费历史，超出后自动清理最早的记录。

**Q: 网络抖动时挂件会报错吗？**

A: 不会。余额接口对网络错误和 5xx 做了 1 次重试，瞬时抖动时会沿用最近一次成功获取的余额，并把响应标记为 `stale=true`，前端继续显示旧值而不是报错。

**Q: 这个插件会保存我的 API Key 吗？**

A: 不会。Key 始终只从 DSH 凭据服务（`ctx.credentials.resolve`）读取，插件内部既不缓存也不落盘；账本文件 `.dshw-usage.json` 只存余额差值与日期，不含任何敏感凭据。

## 上手难度
入门 — 安装即用，唯一必填项 `DEEPSEEK_API_KEY` 在 DSH 凭据里点几下就能配好；进阶玩法（实时令牌、峰谷定价）按需开启。

## 已知问题与限制
- 源代码里硬编码了 Windows 开发机路径 `D:/TestBox/deepseek/...` 作为图片 / 音效 / 账本文件的降级兜底（`lib/index.js:17-22`、`lib/index.js:44-50`），对非 Windows 用户无影响但会出现在 fallback 候选列表里
- 「实时·令牌」模式依赖 DeepSeek 平台会话令牌，需要从浏览器 DevTools 的用量请求 `Authorization` 头手工复制（README.md:110-111），DeepSeek 没有公开该令牌的官方获取流程
- 鲸鱼本体图片为固定 cut-out PNG（`assets/DSniang1.png`），气泡由代码 SVG 绘制；如需换图需保证透明背景 cut-out，否则需要同步调整几何参数（README.md:136）
- 价格表（`PRICING`）以源码常量形式硬编码（`lib/index.js:67-74`），DeepSeek 调整定价后需要修改源码并发布新版本
- 「小鲸鱼记账」模式仅在「余额下降」时累加差值，同一天内账户充值或退款导致的余额上升不会被记录为负值（`lib/index.js:1167-1191` 的差值逻辑），这意味着如果充值与消费在同一天交错，最终的当日用量可能与实际消费有出入

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [DeepSeek-Balance-Whale-Widget](https://deepseek-plugin.org/plugins/MeteorNOX/DeepSeek-Balance-Whale-Widget)
Wiki generated by AI (model: `MiniMax-M3`)