dsh-balance-dock

Readme

# dsh-balance

在对话下方（消息区与输入框之间）显示 DeepSeek 账户余额的 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）web 插件。

Show the DeepSeek account balance below the conversation in the DSH web UI.

![dsh-plugin](https://img.shields.io/badge/dsh--plugin-v0.1.1-4d6bfe) ![license](https://img.shields.io/badge/license-MIT-green)

## 功能 Features

- 在 `conversation.input.dock` 槽位渲染紧凑余额条：`💰 CNY 19.63`
- 每 15 秒自动刷新（轮询 host 路由 `/dsh-balance/balance`）
- 悬停显示「赠送 / 充值」拆分
- 余额不可用时显示降级文案，不打扰对话
- 零依赖、无构建脚本；API key 只留在 host 侧，永不下发浏览器

## 安装 Install

前置：DSH 已安装且 `dsh web` 可正常运行；Node.js ≥ 20；pnpm ≥ 10（`dsh plugin` 需要）。

> npm 包名是 **`dsh-balance-dock`**（`dsh-balance` 已被同名插件占用）；GitHub 仓库名是 `dsh-balance`，两者装出来是同一个插件。

```sh
# 从 npm 安装（推荐）
dsh plugin --profile web add dsh-balance-dock

# 或从 GitHub 安装
dsh plugin --profile web add git+https://github.com/Shawnxxboxx/dsh-balance.git
# 固定到 tag：git+https://github.com/Shawnxxboxx/dsh-balance.git#v0.1.0
```

装完**重启 dsh web**（插件含 host 半，需要重启挂载），然后硬刷新浏览器（Cmd/Ctrl+Shift+R）即可在对话下方看到余额条。

> 安装过程会自动完成 bundle 挂载（`dsh.profile.bundles` 会加入 `dsh-balance-dock`），无需手动编辑任何配置文件。

> **pnpm 11 用户注意**：npm 发布不足 24 小时的新版本会被 pnpm 的 release-age 策略拦截（表现为装到旧版本）。遇到时把下面两行并入 profile 的 `pnpm-workspace.yaml` 后重装：
> ```yaml
> minimumReleaseAgeExclude:
>   - dsh-balance-dock
> ```

### 手动/离线安装

```sh
git clone https://github.com/Shawnxxboxx/dsh-balance.git
cd dsh-balance
dsh plugin --profile web add .        # 以本地路径安装
```

## 更新 Update

```sh
dsh plugin --profile web add dsh-balance-dock        # npm 渠道
dsh plugin --profile web add git+https://github.com/Shawnxxboxx/dsh-balance.git   # GitHub 渠道
```

client 改动热加载（刷新即生效）；host 改动需重启 `dsh web`。

## 卸载 Uninstall

```sh
dsh plugin --profile web remove dsh-balance-dock
```

## 常见问题 FAQ

- **设置里看不到？** 打开 设置 → 插件 → **插件列表**（不是「插件配置」），搜索 `dsh-balance-dock`（列表显示名为 `balance-dock`，前缀 `dsh-` 被剥掉）。「插件配置」页只列出声明了设置项的插件。
- **显示「余额不可用」？** 确认 `DEEPSEEK_API_KEY` 已配置（通过 web 的模型设置页写入，或在启动环境导出）；确认能访问 `https://api.deepseek.com/user/balance`。
- **刷新频率想改？** 编辑 `client/client.js` 里的 `POLL_MS`，client 改动刷新页面即生效。

## 架构 Architecture

- **Host 半**（`lib/index.js`）：通过 `credentials` 服务解析 `DEEPSEEK_API_KEY`，调用 `https://api.deepseek.com/user/balance`；只对环回地址 + 同源请求开放（`GET /dsh-balance/balance`），带 10s 超时与明确错误码。
- **Client 半**（`client/client.js`）：手写 `window.__ModuleLoader__.load` bundle，注册 `conversation.input.dock`（order 30），每 15s 轮询 host 路由渲染余额。

## License

MIT © Shawnxxboxx