dsh-balance-local

Readme

# dsh-balance-local

A **DeepSeek API balance** plugin for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh):
shows your remaining DeepSeek API balance in the **Settings page** and as an ambient readout below the
conversation composer, auto-refreshing every 60 seconds.

**Security first**: the API key is resolved from the dsh credential store **on the Host side only** and never
reaches the browser. The browser just polls a same-origin, loopback-only route that returns an aggregated,
sanitized balance payload.

---

为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（dsh）打造的**余额查询插件**：
在设置页显示「DeepSeek 余额」面板（总余额 / 充值 / 赠送），并在会话输入框下方显示余额徽章，每 60 秒自动刷新。

**安全设计**：API key 只在服务端（Host 进程）从 dsh 凭据库读取，**永不进入浏览器**；浏览器只轮询一个
同源、仅限本机访问的路由，拿到的是脱敏后的余额数据。

## Features / 功能

- ⚙️ 设置页「DeepSeek 余额」面板：总余额 / 充值余额 / 赠送余额，手动刷新按钮
- 📌 会话输入框下方余额徽章（绿点=有余额 / 橙点=无余额 / 灰点=加载中或错误）
- ⏱ 每 60 秒自动刷新（Host 侧另有 30s 缓存）
- 🔒 key 不出服务端、路由仅本机回环可访问、错误分类返回（不透传上游响应体）

## Install / 安装

The plugin is a cordis bundle. It is **not** published to npm — install it from this repo.

```sh
git clone https://github.com/chenpengye/dsh-balance-local.git
cd dsh-balance-local
pnpm install && pnpm build      # produces lib/index.js + lib/client.js
```

Then register it into your dsh profile (e.g. `web`):

```sh
cd ~/.dsh/profiles/web
pnpm add /absolute/path/to/dsh-balance-local -w
```

Add the patch entry to `~/.dsh/profiles/web/cordis.patch.yml`:

```yaml
- insert:
    - id: dsh-balance-local
      name: dsh-balance-local
```

Restart `dsh web` (or trigger the HMR watcher) and hard-refresh the browser page (`Cmd+Shift+R`).

> 中文：克隆本仓库 → `pnpm install && pnpm build` → 在 `~/.dsh/profiles/<name>` 下
> `pnpm add <路径> -w` → 在 `cordis.patch.yml` 里加上面的 insert 条目 → 重启 `dsh web`
> 或触发 HMR 热加载 → 硬刷新页面即可在设置页和输入框下方看到余额。

## Usage / 使用

- The API key comes from the dsh credential store (`DEEPSEEK_API_KEY`), the same one saved in
  Settings → Models. No extra configuration needed.
- API key 复用 dsh 凭据库中的 `DEEPSEEK_API_KEY`（设置 → 模型 里保存的那个），无需额外配置。

## Configuration / 配置项

Host-side config (defaults shown), overridable in the profile config:

| Key | Default | Description |
| --- | --- | --- |
| `apiKeyRef` | `DEEPSEEK_API_KEY` | credential reference resolved on the Host |
| `baseUrl` | `https://api.deepseek.com` | upstream; HTTPS only (loopback HTTP allowed for tests) |
| `timeoutMs` | `10000` | upstream request timeout |
| `cacheMs` | `30000` | Host-side response cache |
| `allowRemote` | `false` | when false, non-loopback requests are rejected with 403 |

## Security / 安全

- Credentials never leave the Host process; the browser sees only the aggregated balance.
- The route rejects non-loopback requests (`allowRemote: false` by default).
- Errors are classified (`INVALID_API_KEY`, `RATE_LIMITED`, `UPSTREAM_TIMEOUT`, …) — no upstream body passthrough.
- Responses are `no-store` + `nosniff`.

> 💡 Also available: [dsh-balance-whale](https://github.com/chenpengye/dsh-balance-whale) — a floating
> whale-girl widget version of the same plugin. 同款鲸鱼娘悬浮框版本。

## License

MIT — see [LICENSE](LICENSE).