whale-purse

Readme

# whale-purse 🐋

一只住在 [DeepSeek Harness（DSH）](https://github.com/deepseek-ai/deepseek-harness) 网页里的**鲸鱼娘桌宠**，帮你盯着 DeepSeek 账户的 **余额**、**官方「今日已消费」**、**当前会话用量/花费** 与 **近 7 天历史趋势**。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![topic: dsh-plugin](https://img.shields.io/badge/topic-dsh--plugin-1f6feb)](https://github.com/topics/dsh-plugin)

![preview](assets/preview.png)

## 特性

- 🐋 **鲸鱼娘桌宠**：透明立绘悬浮在页面上，随波轻微摇摆，脚底带投影；点击 squash 弹跳回应
- 🖱️ **可拖拽**：拖动换位（`localStorage` 记忆，刷新/重开保持），点击打开用量面板
- 🔔 **任务完成提醒**：后台会话跑完时鲸鱼娘弹跳 + 头顶冒泡「任务完成啦」，点气泡直达完成会话
- 🏃 **状态动作**：有任务运行时鲸鱼娘忙碌抖动 + 「忙…」标签
- 💰 **余额监视**：DeepSeek 官方 `Get User Balance` 接口，30s 轮询 + 并发去重
- 📆 **官方今日已消费**：调用 `platform.deepseek.com` 用量接口，显示与官方 usage 页面一致的「今日已消费」（需平台 token）
- 🧮 **会话用量**：读 `sessionProjections` 的 `tokenUsage` 投影，按官方价格折算花费（输入/缓存读/缓存写/输出分桶）；已落盘消息按各自发生时的峰谷档计价，进行中增量按当前档计价
- 📊 **历史趋势（双 Tab 面板）**：「当前」Tab 看余额 + 今日已消费 + 实时花费；「历史」Tab 看近 7 天花费柱状图 + 本会话每条提问的花费明细
- ⚡ **峰谷定价**：北京 9:00-12:00 / 14:00-18:00 高峰价自动切换；官方定价页每 6h 自动抓取
- 🌗 **主题适配**：面板颜色与柱状图深浅随 DSH 浅色/深色主题切换（`--dsw-alias-*` token）
- 🖥️ **多屏适配**：外接大屏/笔记本切换时自动把桌宠夹回视口内

## 数据来源

| 数据 | 来源 | 需要的凭证 |
| --- | --- | --- |
| 余额（总/赠送/充值） | 官方 `GET https://api.deepseek.com/user/balance` | `DEEPSEEK_API_KEY` |
| 今日已消费（官方） | `platform.deepseek.com/api/v0/usage/cost` | `DEEPSEEK_PLATFORM_TOKEN` |
| 会话用量/花费 | 本机 `sessionProjections` + 官方价格 | 无（本地记账） |
| 近 7 天花费 | 本机会话日志回放 + 官方价格 | 无 |

> 「今日已消费」需要平台会话 token：登录 https://platform.deepseek.com 后，在 DevTools Console 执行 `JSON.parse(localStorage.getItem('userToken')).value`，把得到的值写入凭证 `DEEPSEEK_PLATFORM_TOKEN`（`~/.dsh/.credentials.yaml` 或启动环境）。未配置时该项显示「需配置平台 token」，其余功能不受影响。

## 安装

需要 [Node.js](https://nodejs.org) 与 `pnpm`，并已安装 `dsh`（`npm i -g @deepseek-ai/dsh`）。

### 方式一：一条命令（推荐）

```sh
dsh plugin --profile web add github:liuherong808-dev/dsh-whale-purse
```

该包声明了 `dsh.bundle`，`dsh plugin` 会自动把它加进 profile 的 bundle 层。然后重启 `dsh web` 并刷新页面。

### 方式二：手动安装

1. 把本仓库软链/复制进 web profile 依赖：

   ```sh
   ln -s "$(pwd)" ~/.dsh/profiles/web/node_modules/whale-purse
   ```

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

   ```yaml
   - insert:
       - id: whale-purse
         name: 'whale-purse'
         config:
           model: pro
           refreshIntervalSeconds: 30
   ```

3. 重启 `dsh web` 并刷新浏览器。

## 配置

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| `model` | `pro` | 计价模型：`pro` / `flash` |
| `refreshIntervalSeconds` | `30` | 余额轮询间隔（秒） |
| `apiKeyEnv` | `DEEPSEEK_API_KEY` | API key 的凭据引用名 |
| `baseUrl` | `https://api.deepseek.com` | 余额接口 base URL |
| `pricingRefreshHours` | `6` | 官方定价页抓取间隔（小时） |
| `enabled` | `true` | 是否启用余额查询 |

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

## 项目结构

```
whale-purse/
├── lib/
│   ├── index.js        # host 端：余额 + 今日消费 + 会话用量 + HTTP 路由
│   └── client.js       # 浏览器端：鲸鱼娘桌宠 + 双 Tab 面板（立绘 base64 内联）
├── assets/             # 鲸鱼娘立绘源图与预览
├── cordis.patch.yml    # dsh.bundle 补丁层
├── package.json
└── LICENSE
```

## 致谢与衍生说明

本项目是 [Suiwan/whale-purse](https://github.com/Suiwan/whale-purse)（MIT，© 2026 Zijian Li）的衍生版本，在此基础上新增了**官方「今日已消费」**（平台用量接口）能力。

鲸鱼娘立绘素材来自 [1190fasheqi/dafeiyu-pet](https://github.com/1190fasheqi/dafeiyu-pet)（「鲸鱼娘·大肥鱼」）。

## License

[MIT](LICENSE)