dsh-balance-whale

Readme

# dsh-balance-whale 🐳

A floating **DeepSeek API balance** widget for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh).
A cute whale-girl (鲸鱼娘) icon floats at the bottom-right corner of the dsh web GUI, showing your remaining
DeepSeek API balance — click to expand details (total / topped-up / granted) with a manual refresh.

**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 API 剩余余额，点击展开详情（总余额 / 充值 / 赠送），支持手动刷新。

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

## Features / 功能

- 🐳 鲸鱼娘悬浮按钮（手绘 SVG，无外部资源），实时显示余额 + 状态点（绿=有余额 / 橙=无余额）
- 📋 点击展开卡片：可用状态、各币种总余额 / 充值 / 赠送明细、更新时间、刷新按钮
- ⏱ 每 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-whale.git
cd dsh-balance-whale
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-whale -w
```

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

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

Restart `dsh web` (or, if the HMR watcher is active, delete-and-recreate the patch file to hot-reload)
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`.

## License

MIT — see [LICENSE](LICENSE).