@sky_sun/dsh-balance

Readme

# 账户余额显示插件（@sky_sun/dsh-balance）

在 DeepSeek Harness Web UI 的**会话标题栏右侧**显示 DeepSeek 账户余额，**每 60 秒自动刷新**，点击可手动刷新。

## 功能

- 显示账户余额（充值余额 + 赠送余额，人民币）
- 60 秒轮询 + 点击手动刷新
- API key 只在 host 进程内解析，**绝不下发浏览器**（只回传余额数字）
- 路由只接受环回来源请求（防 DNS rebinding 读他人余额）
- 余额接口失败时优雅降级为"查询失败"，不崩界面

## 技术要点

- **双面插件**：host 半注册 `GET /api/balance` 路由（`ctx.webServer`），用 `ctx.credentials` 解析 `DEEPSEEK_API_KEY` 调 DeepSeek `/user/balance`；client 半在 `conversation.session.header.utilities` 插槽渲染余额组件
- **baseURL 复用 llm-deepseek 约定**：默认官方 `https://api.deepseek.com`，可用 `DEEPSEEK_BASE_URL` 环境变量覆盖

## 安装

```powershell
# 安装到你的 profile（本插件声明了 dsh.bundle.patch，安装后自动挂载）
dsh plugin --profile web add @sky_sun/dsh-balance

# 或者直接 npm install 到 profile 目录
cd $env:USERPROFILE\.dsh\profiles\web
npm install @sky_sun/dsh-balance
```

安装后重启 `dsh web`，标题栏右侧即可看到余额。

## 配置

| 字段 | 默认 | 说明 |
|---|---|---|
| `apiKeyEnv` | `DEEPSEEK_API_KEY` | 凭据引用（环境变量名），host 端解析 |
| `baseURL` | 官方 API | 端点 base，省略时用 `$DEEPSEEK_BASE_URL` 或官方地址 |

在 profile 的 `cordis.patch.yml` 里可覆盖：

```yaml
- id: ui-balance
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
    baseURL: https://api.deepseek.com
```

## 依赖

需要 DSH 的 host 提供：`@deepseek-ai/dsh-host-webserver`（web 服务器）、`@deepseek-ai/dsh-credentials`（凭据 seam）。web profile 均已内置。

## 已知限制

- 余额查询频率固定 60 秒 + 手动，不支持自定义间隔
- 只在 web profile 下工作（依赖浏览器插槽）