dsh-plugin-account-balance

Readme

# dsh-plugin-account-balance

[English](#english) | 中文

一个 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 插件：在客户端侧边栏左下角显示当前 LLM 提供商的**账户余额**，紧挨着设置按钮右侧并排显示。

- 设置按钮宽度减半，余额显示框并排在右侧
- 余额每 5 分钟自动刷新，点击余额框可手动刷新
- API Key 只在 host 进程内使用，绝不进入浏览器上下文

## 效果

```
┌──────────────┐
│ ...          │
│              │
│ [运行控制]    │
│ [⚙ 设置][余额 ¥5.79] │   ← 左下角：减半的设置按钮 + 余额框并排
└──────────────┘
```

## 安装

插件是 npm 包，通过 profile 机制安装（`dsh plugin` 是 pnpm 的薄转发层）。

### 从 npm（推荐，无需构建授权）

```sh
dsh plugin --profile web add dsh-plugin-account-balance
```

### 从 GitHub

```sh
dsh plugin --profile web add github:flluhaoran/dsh-plugin-account-balance
```

> pnpm ≥10 首次安装 git 依赖会要求构建授权：把 pnpm 打印的包键加入该 profile 的
> `pnpm-workspace.yaml` 的 `allowBuilds`，然后重新执行 `add`。

### 从 tarball

```sh
pnpm pack            # 在插件仓库内打包
dsh plugin --profile web add ./dsh-plugin-account-balance-0.1.0.tgz
```

安装后重启（或刷新）客户端界面即可看到左下角的余额框。

> **桌面版说明**：桌面应用使用 `web` profile（`~/.dsh/profiles/web`）。若你的机器
> 没有 node/pnpm，可先用 Electron 内置的 Node 运行 dsh CLI：
>
> ```sh
> ELECTRON_RUN_AS_NODE=1 "/Applications/DeepSeek Harness.app/Contents/MacOS/DeepSeek Harness" \
>   "/Applications/DeepSeek Harness.app/Contents/Resources/host/node_modules/@deepseek-ai/dsh/lib/bin.js" \
>   plugin --profile web add dsh-plugin-account-balance
> ```
>
> （或用 Homebrew 安装 pnpm 后直接使用 `dsh plugin`。）

## 卸载

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

## 工作原理

插件是单包双面（bundle）：

- **host 半**（`lib/host.js`）：在 loopback webserver 注册精确路由
  `/account-balance`。处理时解析当前默认模型的提供商及其 settings profile 中的
  `apiKeyEnv` 引用，通过 `credentials` 服务解析密钥（密钥不出 host 进程），调用
  提供商余额接口并返回 JSON。
- **client 半**（`lib/client.js`）：以 `priority: -1` 影子注册 `sidebar.settings`
  槽（最低优先级先渲染，覆盖内置设置壳），复刻设置面板外壳的同时把触发按钮改为
  半宽，并在右侧并排渲染余额框；余额框通过同源 `fetch("/account-balance")` 获取
  数据，5 分钟自动刷新、点击手动刷新。所有既有设置分区（通用、模型、权限、主题等）
  通过同名子槽继续原样渲染。

### 支持的提供商

| 提供商 | 余额接口 |
|---|---|
| `deepseek-official` | `GET https://api.deepseek.com/user/balance` |

其他提供商当前返回 `supported: false`，界面显示「暂不支持」。欢迎 PR 补充。

## 开发

```sh
git clone https://github.com/flluhaoran/dsh-plugin-account-balance.git
cd dsh-plugin-account-balance
dsh plugin --profile web add .     # 从 checkout 安装，改动即时生效（客户端 HMR 热重载）
```

## License

MIT

---

## English

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) plugin that
shows the current LLM provider's **account balance** in the sidebar footer,
right beside a halved Settings button.

- Auto-refresh every 5 minutes; click the box to refresh immediately.
- The API key is only used inside the host process and never crosses into the
  browser context.

### Install

```sh
dsh plugin --profile web add dsh-plugin-account-balance        # npm
dsh plugin --profile web add github:flluhaoran/dsh-plugin-account-balance  # git
dsh plugin --profile web add ./dsh-plugin-account-balance-0.1.0.tgz        # tarball
```

### How it works

One package, two faces (a "bundle"): the host half registers an exact
`/account-balance` route on the loopback web server (resolves the current
provider's credential through the `credentials` service and queries its balance
API); the client half shadows the in-box `sidebar.settings` slot with
`priority: -1`, re-rendering the settings shell with a halved trigger and an
inline balance box that fetches `/account-balance` same-origin.

### Supported providers

| Provider | Balance endpoint |
|---|---|
| `deepseek-official` | `GET https://api.deepseek.com/user/balance` |

Other providers report `supported: false` ("暂不支持" / "Unsupported").