balance-dock

Readme

# balance-dock

> DeepSeek 账户余额 · DeepSeek Harness (dsh) 常驻 Web 插件
> A persistent DeepSeek balance readout plugin for [DeepSeek Harness](https://github.com/deepseek-ai/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](https://github.com/deepseek-ai/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 层栈:

```bash
# 从 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

```powershell
# 克隆仓库
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

```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 <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

| 项 | 说明 |
| --- | --- |
| `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`)。

---

## 📄 License

[MIT](./LICENSE)