tugu-dsh-balance-widget

Readme

# 💰 dsh-balance-widget

**DeepSeek Harness（DSH）余额插件** —— 侧边栏左下角入口，点击弹出居中大卡片：**实时余额 · 充值按钮 · Token 消耗 · 7/30 天消费趋势**。

![特性](https://img.shields.io/badge/platform-DeepSeek%20Harness-8d7ce4.svg)

## ✨ 功能

| 模块 | 能力 |
| --- | --- |
| **左下角入口** | 入口按钮**与「设置」按钮同一水平行**（自动实测设置按钮位置后锚定，不依赖官方 hash class）；宽栏「💰 余额」、折叠栏圆形图标 |
| **点击弹出大卡片** | **点击入口**后像「设置」面板一样在**屏幕中心弹出大卡片**（点击遮罩 / ✕ / ESC 关闭），交互稳定可靠；入口在面板打开时保持可见、可随时切换 |
| **实时余额** | 自动读取 DSH 已配置的 `DEEPSEEK_API_KEY`，查询 DeepSeek 官方 `GET /user/balance`：总余额 + 赠送 / 充值细分 + 可用状态；面板打开期间每 60 秒自动刷新，可手动刷新 |
| **充值按钮** | 一键直达 DeepSeek 官方充值页 `platform.deepseek.com/top_up`（新窗口） |
| **今日消耗** | 调用次数、Token 合计、输入 / 缓存命中 / 输出明细、**今日消耗金额**（回放会话日志 + 官方价格表计价，覆盖重启前历史） |
| **按模型分组** | 今日消耗**按模型分组**展示（模型 / 调用次数 / 金额）——后续新增其他模型自动出现，无需改插件 |
| **消费趋势图** | 面板内**默认显示近 7 天 / 近 30 天**每日消耗柱状图（hover 查看每日金额与 Token 明细、区间合计） |
| **当前会话 Token** | 全量回放会话持久化日志（含安装插件前的历史），实时补充进行中消息 |
| **今日约消费** | 余额差值估算（当天期初余额 − 当前余额），标注「约」避免与官方数据混淆 |
| **安全** | API Key 不出本机：浏览器只访问本地路由，Key 由宿主侧按请求解析 |

## 📥 安装

### 前置条件

- DeepSeek Harness（DSH Desktop 或 `dsh web`，0.1.7+）
- 已配置 `DEEPSEEK_API_KEY`（设置 → 模型 页面，或 `.credentials.yaml`）
- 同事机器上无需任何 Node / pnpm 环境（一键脚本自动处理）

### 方式一：一键脚本（推荐）

解压 `dsh-balance-widget-v0.2.0.zip` 后：

- **macOS / Linux**：终端进入解压目录，运行
  ```bash
  ./install.sh
  ```
- **Windows**：双击 `install.bat`

脚本会自动探测 DSH profile 目录、复制插件、注册 bundle，完成后**完全退出并重启 DSH Desktop** 即可。

### 方式二：手动安装

1. 找到 DSH web profile 目录：
   - macOS：`~/Library/Application Support/dsh-desktop/harness/profiles/web`
   - Windows：`%APPDATA%\dsh-desktop\harness\profiles\web`
   - 使用 `dsh` CLI：`~/.dsh/profiles/web`（或 `$DSH_HOME/profiles/web`）
2. 把 `dsh-balance-widget` 文件夹复制到该目录的 `node_modules/` 下
3. 编辑该目录下 `package.json`，在 `dsh.profile.bundles` 数组中追加 `"dsh-balance-widget"`
   ```json
   "dsh": {
     "profile": {
       "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-balance-widget"]
     }
   }
   ```
4. 完全退出并重启 DSH Desktop

> 有 `dsh` CLI + pnpm 的环境等价于：`dsh plugin --profile web add <插件目录路径>`

## ✅ 验证

重启后：侧边栏左下角（设置按钮旁）出现「💰 余额」入口 → 点击弹出居中大卡片。宿主路由可直接验证：

```bash
curl http://127.0.0.1:<端口>/api/dsh-balance
```

## 🗑 卸载

1. 删除 `<profile>/node_modules/dsh-balance-widget`
2. 从 `<profile>/package.json` 的 `dsh.profile.bundles` 移除 `"dsh-balance-widget"`
3. 重启 DSH Desktop

## 🏗 架构

```
Host（Node.js 进程，lib/index.js）
├─ GET /api/dsh-balance               余额（api.deepseek.com/user/balance）+ 今日约消费（余额差值）
├─ GET /api/dsh-balance/session-stats 当前会话 Token（日志回放 + 实时兜底）
├─ GET /api/dsh-balance/today         今日消耗（Token + 金额 + 按模型分组，回放计价）
├─ GET /api/dsh-balance/usage?days=N  近 N 天每日消耗序列（柱状图数据，60s 缓存）
├─ POST /api/dsh-balance/log          客户端错误上报（写入宿主日志，便于排查）
└─ session/event 监听                 实时累计会话级与今日 Token 台账（回放兜底）

Client（浏览器，lib/client.js）
├─ 入口：sidebar.footer.action 槽位，与设置按钮同行（JS 实测锚定）
├─ 面板：居中大卡片（遮罩 / ✕ / ESC 关闭），余额 60s / 会话 5s / 今日 30s 轮询
├─ 图表：7/30 天柱状图（纯 div，无图表依赖）
├─ 错误边界：渲染异常显示错误文本，入口不消失；错误自动上报宿主日志
└─ 样式：仅 --dsw-* 主题变量，自动适配浅色 / 深色主题
```

计价引擎 `lib/pricing.js` 移植自 [dsh-web-billing](https://github.com/bpc-oss/dsh-web-billing)（MIT），含官方价格表与峰谷定价。

## ⚖️ 许可

MIT