dsh-balance-float

English · 中文文档

DeepSeek 余额悬浮窗 —— 一个 DeepSeek Harness (DSH) 插件（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

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

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

安装 Install

要求：已安装 DeepSeek Harness（dsh CLI），并有一个 web profile。

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

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

配置 Configuration

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

# 必填：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），添加一行：

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 检出：

# 目录结构：<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