余额常驻插件Cao-zhi-hao/balance-dock

balance-dock

DeepSeek 账户余额 · DeepSeek Harness (dsh) 常驻 Web 插件
A persistent DeepSeek balance readout plugin for DeepSeek Harness (dsh).

在 dsh 会话输入框下方的状态条区域显示你的 DeepSeek 账户余额,每 60 秒自动刷新,也可手动刷新。作为部署级常驻插件,每次打开页面、刷新页面都会自动加载——不会像动态插件那样刷新后消失。

Shows your DeepSeek account balance in the status band under the conversation composer. Auto-refreshes every 60 seconds with a manual refresh button. As a deployment-level persistent web plugin it loads automatically on every page open/refresh — it never disappears like a dynamic plugin does.

✨ 功能特性 / Features

- ✅ 常驻持久 — 刷新页面、重开页面、重启进程后依然存在,无需手动激活
Persistent — survives page refresh, re-open, and process restart without manual activation
- ✅ 安全取数 — API 密钥只存在于 Host 端(经 ctx.credentials 解析),浏览器只访问同源 /ds-balance 接口
Secure — the API key lives only on the Host side (resolved via ctx.credentials); the browser only fetches the same-origin /ds-balance endpoint
- ✅ 自动刷新 — 每 60 秒刷新,支持 ↻ 手动刷新
Auto-refresh — every 60 seconds, plus a ↻ manual refresh button
- ✅ 主题适配 — 使用 dsh 主题变量,自动适配明暗模式
Theme-aware — uses dsh theme tokens, adapts to light/dark mode
- ✅ 多币种 — 支持 CNY/USD/EUR 符号显示(其余按 ISO 代码前缀)
Multi-currency — CNY/USD/EUR symbols with ISO-code fallback

📦 安装 / Installation

前置要求 / Prerequisites

- 已安装并运行 DeepSeek Harness web profile
- 已配置 DEEPSEEK_API_KEY(通常位于 $DSH_HOME/.credentials.yaml,或 Web 设置页 Models 中配置)

方式一:dsh plugin 命令安装(推荐)/ Option 1: dsh plugin command (recommended)

本包是 bundle 插件(声明了 dsh.bundle.patch + dsh.client),可直接用 dsh 内置的插件管理命令安装,它会自动把插件注册进 profile 层栈:

从 npm registry 安装(发布后)
dsh plugin --profile web add balance-dock

或从 GitHub 直接安装
dsh plugin --profile web add github:/balance-dock

或本地仓库(在仓库父目录执行)
dsh plugin --profile web add ./balance-dock

安装脚本 scripts/install.ps1 同样可用,两种方式二选一。

方式二:安装脚本 / Option 2: Install script

克隆仓库
git clone https://github.com//balance-dock.git
cd balance-dock

安装到当前用户的 dsh profile(默认 profile: web)
./scripts/install.ps1

指定其他 profile
./scripts/install.ps1 -Profile tui

方式三:手动安装 / Option 3: Manual install

1. 将本仓库复制(或符号链接)到 profile 的模块解析路径,使 require('balance-dock') 可解析:

默认 DSH_HOME 为 ~/.dsh;复制到 profiles/node_modules 下
Copy-Item -Recurse . "C:\Users\\.dsh\profiles\node_modules\balance-dock"

2. 在 profile 的 cordis.patch.yml 中添加插件行(以 web profile 为例,文件位于 $DSH_HOME/profiles/web/cordis.patch.yml):

- insert:
- id: balance-dock
name: 'balance-dock'

3. 重启 dsh 进程(新增插件行必须重启才生效 — plugin-set changes take effect on restart)。

验证 / Verify

重启后:

- GET http://127.0.0.1:/ds-balance 应返回余额 JSON,例如:
json
{"ok":true,"status":200,"isAvailable":true,"infos":[{"currency":"CNY","totalBalance":"10.95","grantedBalance":"0.00","toppedUpBalance":"10.95"}]}
- 打开任意会话,输入框下方应显示 ● DeepSeek ¥10.95(充值 ¥10.95) 状态条。

🗑️ 卸载 / Uninstall
powershell
./scripts/uninstall.ps1

或手动:删除 profiles/node_modules/balance-dock 目录,并从 cordis.patch.yml 移除对应 insert 块,然后重启 dsh。

🏗️ 工作原理 / How it works

┌──────────────────────────── Browser ────────────────────────────┐
│  conversation.composer.dock slot                                │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │ ● DeepSeek ¥10.95(充值 ¥10.95)   [↻]                    │   │
│  └──────────────────────────────────────────────────────────┘   │
│         │ fetch('/ds-balance') (同源,无密钥)                     │
└─────────┼───────────────────────────────────────────────────────┘
▼
┌─────────────────────────── Host (Node) ─────────────────────────┐
│  GET /ds-balance  (webServer route, 由 host 半部注册)             │
│    ├─ ctx.credentials.resolve('DEEPSEEK_API_KEY')  ← 密钥在此     │
│    └─ fetch('https://api.deepseek.com/user/balance',             │
│              { Authorization: 'Bearer ' })                  │
└──────────────────────────────────────────────────────────────────┘

- Host 半部 (lib/index.js):在 harness web 服务器上注册 GET /ds-balance 路由。通过 ctx.credentials 解析 DEEPSEEK_API_KEY,再用 Node 原生 fetch 调用 DeepSeek 余额 API,返回解析后的 JSON。密钥绝不出现在浏览器或命令行参数中。
- Client 半部 (lib/client.js):作为 dsh.client 声明包被 clientModules 扫描进 window.__DSH_BOOT__ 启动图,浏览器每次加载页面自动注入。组件挂载在 conversation.composer.dock 槽位,定时(60s)拉取 /ds-balance 并渲染。

为什么是常驻插件而不是动态插件?

动态插件(Cordis define/run)的 Client 半部注入在浏览器页面运行时内,刷新页面即失效,需手动重新激活。本插件通过 package.json 的 dsh.client 声明 + cordis.patch.yml 插件行,成为部署级 web 插件,随启动图常驻,刷新不再丢失。

⚙️ 配置 / Configuration

| 项 | 说明 |
| --- | --- |
| DEEPSEEK_API_KEY | DeepSeek API 密钥,经 ctx.credentials 解析(默认 ref 名)。存放在 $DSH_HOME/.credentials.yaml 或由设置页写入 |
| 刷新间隔 | 默认 60 秒,修改 lib/client.js 中 interval(load, 60000) 的毫秒数 |

🧩 目录结构 / Project structure

balance-dock/
├── package.json          # 包声明:dsh.bundle + dsh.client 标记 + exports
├── cordis.patch.yml      # bundle patch 层:dsh plugin add 后自动注册插件行
├── lib/
│   ├── index.js          # Host 半部:注册 /ds-balance 路由(取余额)
│   └── client.js         # Client 半部:composer dock 余额条 UI
├── scripts/
│   ├── install.ps1       # 安装到 dsh profile
│   └── uninstall.ps1     # 从 dsh profile 卸载
├── LICENSE
└── README.md

❓ 常见问题 / FAQ

Q: 刷新页面后余额条消失了?
A: 请确认使用的是本常驻插件(已加入 cordis.patch.yml),而非旧版动态插件。动态插件刷新即失是设计行为;常驻插件刷新后依然存在。

Q: 安装后余额接口返回 SPA 首页而非 JSON?
A: 说明 host 半部未注册路由。检查 cordis.patch.yml 插件行是否存在,并重启 dsh 进程(新增插件行需重启生效)。本插件通过 inject: ['webServer'] 保证路由在服务就绪后注册。

Q: 显示"余额不可用"?
A: 检查 $DSH_HOME/.credentials.yaml 中 DEEPSEEK_API_KEY 是否已配置,以及网络能否访问 api.deepseek.com。

Q: 在受限沙箱下 curl 报 TLS 错误?
A: 本插件刻意使用 Node 原生 fetch(OpenSSL)而非 curl(Windows schannel 在受限令牌下可能报 SEC_E_NO_CREDENTIALS)。

📄 许可证

MIT