zypchloe-del/dsh-balance-pill

dsh-balance-pill

🌐 English

给 DeepSeek Harness (DSH) 的 DeepSeek 余额悬浮胶囊：右下角可拖拽、可折叠的毛玻璃小窗口，实时显示官方 API 账户余额，且未单独配置 Key 时自动复用 Harness 的 DEEPSEEK_API_KEY，开箱即用。

license

📸 截图

| 胶囊态（默认，不挡对话区） | 展开态 |
| --- | --- |
| pill | card |

为什么需要它

DSH 用起来总想顺手看一眼 DeepSeek 余额，切到官网太麻烦。这个插件把余额做成一个常驻的右下角小胶囊，瞄一眼就知道还有多少钱，点一下看明细，拖一下摆到顺手的位置。

功能

- 实时余额：查询官方 API GET /user/balance，显示总额、可用状态、充值 / 赠送明细（CNY 显示 ¥，USD 显示 $）。
- 自动复用 Key：优先用插件内保存的 Key；未配置时只读回退复用 Harness 的 DEEPSEEK_API_KEY（绝不写入 / 清除它）。
- 独立凭证：插件内填的 Key 存独立引用 DSH_BALANCE_PILL_KEY，与 Harness 自己的模型 Key 互不影响。
- 折叠胶囊：默认折叠成右下角小胶囊（状态圆点 + 余额），点击展开，不遮挡对话区。
- 拖拽摆放：胶囊和卡片都能拖到任意位置，位置跨展开 / 折叠保持。
- 自动刷新：每 5 分钟自动查询，也可手动刷新。
- 毛玻璃外观：16px 背景模糊 + 半透明，明暗主题随系统 prefers-color-scheme 自适应。
- 国际化：文案跟随 DSH 的语言设置自动切换中 / 英文（未匹配语言回退中文）。
- 跨平台：Host 用 resolveExecutable("curl") 解析本机 curl（不写死 curl.exe）。
- 安全：所有 HTTP 路由仅接受 loopback（127.0.0.1 / ::1）请求。

快速开始

方式一：从 GitHub 直接安装（无需 npm，开箱即用）

dsh plugin --profile web add github:zypchloe-del/dsh-balance-pill

方式二：从 npm 安装（发布后）

dsh plugin --profile web add dsh-balance-pill

安装后刷新页面，右下角就会出现小胶囊：

- 如果 DSH 已接入 DeepSeek（DEEPSEEK_API_KEY 已配置）→ 直接显示余额；
- 否则点胶囊展开 → 点 ⚙ → 填入 API Key → 保存。

：桌面版 desktop，Web 版 web，不带 --profile 操作默认 profile。

配置 API Key

| 方式 | 说明 |
| --- | --- |
| 自动复用（推荐） | DSH 已配置 DEEPSEEK_API_KEY（环境变量或凭据文件）时自动探测，无需填写 |
| 浮窗内填写 | 展开 → ⚙ → 填 Key → 保存，写入 ~/.dsh/.credentials.yaml 的 DSH_BALANCE_PILL_KEY |

插件内保存的 Key 优先级高于 Harness 的 Key；「清除」只清插件自己的 Key，不动 Harness 的 Key。

卸载

dsh plugin --profile web remove dsh-balance-pill

结构

dsh-balance-pill/
├── lib/
│   ├── index.js    # Host：/api/dsh-balance-pill/* 路由（余额查询、Key 状态/保存/清除）
│   └── client.js   # Client：胶囊 + 卡片 UI、拖拽、折叠、自动刷新、i18n、毛玻璃
├── cordis.patch.yml  # bundle patch（entry id: dsh-balance-pill）
├── package.json
├── README.md / README.en.md
└── LICENSE

实现说明

- Host（lib/index.js）：零顶层导入 ESM，通过 webServer 注册 loopback-only 路由，用 subprocess 调本机 curl 请求官方接口，用 credentials 做 Key 解析（自有引用 → 回退 Harness 引用）。
- Client（lib/client.js）：window.__ModuleLoader__.load 挂载，直接挂 document.body 低层级容器（z-index 2）而非 shell.overlay，以兼容不同宿主模式的浮层层级；文案经 locale 服务注册 / 绑定，跟随 DSH 语言。
- 官方余额接口响应（/user/balance）：
{ "is_available": true, "balance_infos": [{ "currency": "CNY", "total_balance": "110.00", "granted_balance": "10.00", "topped_up_balance": "100.00" }] }

FAQ

Q：会不会泄露我的 Key？
不会。Key 只存本机 ~/.dsh/.credentials.yaml，余额查询请求只发往 DeepSeek 官方接口；HTTP 路由只接受本机 loopback。

Q：和 Harness 自带的 Key 冲突吗？
不会。插件优先用自己独立的 DSH_BALANCE_PILL_KEY，空时才只读复用 Harness 的 Key，且绝不写回 / 清除后者。

Q：怎么固定位置？
拖到想要的位置后松手，位置在本次会话内保持（展开 / 折叠不丢失）。

相关插件

- dsh-wallpaper —— 给 DSH 网页版换壁纸：上传自定义壁纸、调透明度、铺满整个界面背景。

License

MIT