@dsh-external/dsh-balance-float

Readme

# dsh-balance-float

> [English](./README.en.md) · 中文文档

DeepSeek 余额悬浮窗 —— 一个 [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness) 插件（bundle）：打开 Harness 即显示当前 DeepSeek API 余额的悬浮窗，可自由拖动与缩放；窗口放大后展示来自 platform.deepseek.com/usage 的官方用量信息（今日柱状图、逐日明细、模型分布）。

A floating DeepSeek balance & usage widget for DeepSeek Harness: shows your API balance as a draggable, resizable window; enlarge it to reveal official usage stats (today's bar chart, daily breakdown, model share) from platform.deepseek.com/usage.

## 功能 Features

- **悬浮窗**：打开 Harness 即出现，整窗拖动、右下角缩放、可收起为胶囊、60 秒自动刷新
- **余额**：显示总余额、赠送余额、充值余额，支持多币种符号（CNY/USD/…）
- **按窗口大小分级展示**：
  - 小尺寸 = 第一版完整界面（余额明细 + 底栏）
  - 拉大到 ≥ 400×300 = 追加**用量面板**
- **用量面板**（与 platform.deepseek.com/usage 同源数据）：
  - 今日金额 / 本月费用 / 今日 Tokens
  - **今日用量柱状图**（金额 + Tokens 双柱，按本月日均缩放，纯 CSS 实现）
  - 本月逐日明细表（输入 / 缓存命中 / 输出 / 费用）
  - 模型分布（费用占比）
  - "官网用量 ↗" 直达链接
- **双数据通道**：
  - 配置 `DEEPSEEK_PLATFORM_TOKEN` → 官方逐日真实数据（`state: official`）
  - 未配置 → 按"当日余额差值"估算今日消费（`state: estimate`，界面标注"估算"）
- 性能：外壳/内容拆分 + `memo` + rAF 帧节流，缩放流畅

## 截图 Screenshots

**基础悬浮窗** —— 余额明细（整窗拖动 / 右下角缩放 / 收起胶囊）：

![基础悬浮窗：余额明细](./assets/screenshot-basic.png)

**放大后（≥ 400×300）** —— 追加官方用量面板：今日用量柱状图、本月逐日明细表、模型分布：

![放大后的官方用量面板](./assets/screenshot-usage.png)

## 安装 Install

要求：已安装 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（`dsh` CLI），并有一个 web profile。

```sh
dsh plugin --profile web add github:lingruan28-boop/dsh-balance-float
```

重启 DSH 后，悬浮窗自动出现在页面右上角。

## 配置 Configuration

DSH 凭据文件（默认 `~/.dsh/.credentials.yaml`，与模型 API Key 同文件）：

```yaml
# 必填：DeepSeek API Key（余额查询）
DEEPSEEK_API_KEY: sk-...

# 可选：官方用量数据（platform.deepseek.com 登录会话的 userToken）
# 获取方式：浏览器登录 platform.deepseek.com → F12 → Application →
#   Local Storage → 复制 userToken 的值
# 不配置也能用：用量面板退化为余额差值估算
DEEPSEEK_PLATFORM_TOKEN: <userToken>
```

凭据文件有文件监听，改完即生效（无需重启）。

## 平台 Token 配置教程（可选，官方用量数据）

**`DEEPSEEK_PLATFORM_TOKEN` 是什么**：platform.deepseek.com 的**登录会话令牌**（浏览器 localStorage 里的 `userToken`，一段长字符串），**不是** API Key。官网用量后台（platform.deepseek.com/usage 页面同源接口）用它对账号会话鉴权；没有它，用量面板只能按余额差值估算今日消费。

### 第一步：登录平台网站

浏览器打开 <https://platform.deepseek.com> 并用你的账号登录。

### 第二步：打开开发者工具

按 `F12`（或 `Ctrl+Shift+I`，或右键页面 → 检查）。

### 第三步：找到 userToken

1. 开发者工具顶部切到 **Application（应用）** 面板
2. 左侧边栏展开 **Local Storage** → 点击 `https://platform.deepseek.com`
3. 右侧键值列表中找到名为 `userToken` 的键
4. 双击它的 **Value** 选中，复制整段值（以引号包裹的长字符串）

### 第四步：写入凭据文件

编辑 DSH 凭据文件（默认 `~/.dsh/.credentials.yaml`），添加一行：

```yaml
DEEPSEEK_PLATFORM_TOKEN: <粘贴的 userToken 值>
```

### 第五步：验证

- 无需重启：凭据文件有监听，改完即生效
- 拉大悬浮窗（≥ 400×300），用量面板应显示**官方真实数据**：今日柱状图、本月逐日明细表、模型分布
- 若面板提示"用量接口不可用"，通常是 token 过期：重新登录 platform.deepseek.com（会刷新会话）后再取一次新值更新即可

### 注意事项

- token 只在本机 Host 进程内读取，不会发送到浏览器或第三方
- 重新登录平台网站会使旧 token 失效，需要按上述步骤重新获取
- 不配置也不影响使用：用量面板退化为余额差值估算（界面标注"估算"）

## 使用 Usage

- 整窗拖动移动；右下角手柄缩放
- 标题栏 `↻` 手动刷新，`–` 收起为迷你胶囊（点击展开）
- 拉大到 ≥ 400×300 显示用量面板（含今日柱状图、逐日表、模型分布）
- 数据每 60 秒自动刷新

## 从源码构建 Build from source

构建复用 Harness 的 client-bundle 预设，需要一份本地 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 检出：

```sh
# 目录结构：<ds-balance-float 所在目录>/../deepseek-harness
pnpm install        # 在插件目录安装 tsdown / lightningcss 等依赖
pnpm run bundle     # 输出 lib/index.js（Host）+ lib/client.js（浏览器）
```

Harness 检出路劲不同时，编辑 `tsdown.config.ts` 中的 import 路径即可。

## 架构 Architecture

```
浏览器 (Client 半部)                         DSH Host 进程 (Host 半部)
┌─────────────────────────┐    fetch     ┌──────────────────────────────┐
│ shell.overlay 悬浮窗 UI  │ ───────────► │ GET /ds-balance (webServer)  │
│ 拖动/缩放/60s自动刷新     │  同源HTTP     │ → credentials 解析密钥        │
│ 尺寸分级 + 用量面板       │              │ → api.deepseek.com/          │
└─────────────────────────┘              │    user/balance              │
                                         │ → (可选) platform.deepseek.  │
                                         │    com/api/v0/usage/         │
                                         │    amount + cost             │
                                         │ → 无 token 时余额差值估算     │
                                         └──────────────────────────────┘
```

- Host 半部：`src/index.ts` — 注册 `/ds-balance` 路由，解析凭据、请求余额与用量接口，返回归一化 JSON；密钥永不出 Host
- Client 半部：`src/client/index.ts` — 注册 `shell.overlay` 槽位；外壳/内容拆分（memo）、rAF 帧节流、ResizeObserver 尺寸分级
- 样式：`src/client/balance.module.css`（CSS Modules，`--dsw-alias-*` 主题令牌，明暗主题自适应）

## License

[MIT](./LICENSE)