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:<your-name>/balance-dock

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

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

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

# 克隆仓库
git clone https://github.com/<your-name>/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') 可解析:

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

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

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

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

验证 / Verify

重启后:

• GET http://127.0.0.1:<port>/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

./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 <key>' })                  │
└──────────────────────────────────────────────────────────────────┘

• 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

---

🧩 目录结构 / 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)。

---

📄 License

[MIT](./LICENSE)