dsh-balance-widget

DeepSeek API 余额悬浮窗 —— 为 DeepSeek Harness (dsh) 的 Web 界面添加一个右下角常驻悬浮窗，实时显示 DeepSeek API 账户剩余余额。

A floating balance widget for the dsh (DeepSeek Harness) web UI — shows your DeepSeek API account balance in real time, loaded by default on every launch.

特性 / Features

• 📍 右下角悬浮窗：注册在 dsh Web 的 shell.overlay 框架层，随 dsh 每次启动自动加载（常驻插件，非会话临时扩展）
• 🔄 实时刷新：每 30 秒自动轮询一次 DeepSeek 官方余额接口；↻ 按钮手动立即刷新
• 🖱️ 按住拖动：按住卡片任意位置可自由移动，点击折叠/展开，位置与折叠状态会话内记忆
• 🎨 主题自适应：全部使用 dsh 主题令牌（亮/暗主题自动适配），与界面风格相融
• 💳 多币种：CNY / USD / EUR 符号自适应，展示总额、赠送额度与充值额度
• 🔐 密钥安全：API 密钥只存在于宿主进程（经 subprocess 调 curl 代理 GET /user/balance），不出现在浏览器与日志中

安装 / Install

目标 dsh 机器上（已装 node，dsh 自带），无需构建：

unzip dsh-balance-widget-plugin.zip && cd dsh-balance-widget-plugin
node install.mjs                 # 多 profile 时：node install.mjs --profile <profile名称>
# 重启 dsh

安装脚本幂等、可重复执行，只做三件事：

1. 复制两个预构建包到 <profile>/plugins/；
2. 在 $DSH_HOME/profiles/node_modules/@deepseek-ai 建立链接（与 dsh 的 profiles 模块回退机制一致）；
3. 向 <profile>/cordis.patch.yml 追加两行插件挂载。

也可以把本仓库的 packages/ 内容合入自己的 dsh 源码树后按常规流程构建（tsc -b + tsdown）。

配置 / Configuration

余额经 DEEPSEEK_API_KEY 凭据读取，三种来源任选其一：

• dsh Web 的 Models 设置页（推荐，自动写入凭据管理）
• 环境变量 DEEPSEEK_API_KEY
• llm-deepseek 设置段的 apiKeyEnv 引用

可选：llm-deepseek.baseURL 或环境变量 DEEPSEEK_BASE_URL 可覆盖接口地址（默认为 https://api.deepseek.com）。

验证 / Verify

重启 dsh 后：

1. 右下角出现余额卡片；
2. 浏览器访问 <你的 dsh 地址>/balance-widget/balance，返回 {"ok":true,...,"totalBalance":...} 即成功；
3. 未配置密钥时返回 {"ok":false,"code":"no-key",...}，卡片显示红色错误提示。

卸载 / Uninstall

node install.mjs --remove   # 重启 dsh 后生效

工作原理 / How it works

层	包	职责
Host	dsh-balance-widget	cordis 插件，注册 GET /balance-widget/balance 路由；解析凭据 → subprocess 调 curl → 解析并归一化 DeepSeek 余额
Client	dsh-client-ui-balance-widget	浏览器 bundle（dsh.client 声明），在 shell.overlay 注册悬浮卡片，轮询路由并渲染

两个包均为独立 npm 包形态（package.json + lib/ + 类型声明），遵循 dsh 的标准双面插件结构。

License

MIT