jieguanya/tugu-dsh-balance-widget

💰 dsh-balance-widget

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

特性

✨ 功能

| 模块 | 能力 |
| --- | --- |
| 左下角入口 | 入口按钮与「设置」按钮同一水平行（自动实测设置按钮位置后锚定，不依赖官方 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：终端进入解压目录，运行
./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"
"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

✅ 验证

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

curl http://127.0.0.1:/api/dsh-balance

🗑 卸载

1. 删除 /node_modules/dsh-balance-widget
2. 从 /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（MIT），含官方价格表与峰谷定价。

⚖️ 许可

MIT