@dsh-external/dsh-deepseek-balance

Readme

# dsh-deepseek-balance · DeepSeek 账户余额实时显示

DSH Web GUI 的余额小部件，**两处显示**，每 30 秒自动刷新（也可手动刷新）：

- **会话标题栏右侧**：主界面 banner 位置的余额徽章（`余额 ¥1.36`）
- **设置 → 插件 → 账户余额**：完整详情页（总余额 / 赠送余额 / 充值余额 / 可用状态）

两处共享同一份轮询数据，任意一处挂载即开始刷新，切换页面后数据同步更新。

API Key 全程留在 host 进程内：插件通过 DSH 的凭据通道（`ctx.credentials`）解析 `DEEPSEEK_API_KEY`，在 host 侧请求官方余额接口（`GET https://api.deepseek.com/user/balance`），浏览器只拿到余额结果，永远接触不到 Key。

## 安装

```sh
# 从 GitHub 安装（发布后）
dsh plugin --profile web add https://github.com/MatsMQ/dsh-deepseek-balance

# 或本地路径安装
dsh plugin --profile web add <本包路径>
```

依赖：host 侧需要 `webServer` 与 `credentials` 服务（web profile 自带），浏览器侧需要 react（shell 自带）。

## 使用

1. 确保凭据已配置（`$DSH_HOME/.credentials.yaml` 或环境变量）：`DEEPSEEK_API_KEY: sk-...`，与模型设置中使用的 Key 一致。
2. 重启 DSH Web 服务（插件在启动时装载）。
3. 进入会话后可在**标题栏右侧**看到余额徽章，悬停显示完整明细与更新时间；完整页在 **设置 → 插件 → 账户余额**。

## 配置（cordis.patch.yml 的 entry config）

| 字段 | 默认值 | 说明 |
|---|---|---|
| `credentialRef` | `DEEPSEEK_API_KEY` | 使用的凭据引用名 |
| `upstreamUrl` | `https://api.deepseek.com/user/balance` | 余额查询端点 |
| `timeoutMs` | `10000` | 上游请求超时（毫秒） |

## 路由

- `GET /dsh-balance`（exact）— 余额 JSON，`Cache-Control: no-store`。
- 浏览器请求做同源围栏（校验 `Sec-Fetch-Site`），防止 DNS-rebinding 类跨站读取；无该头部的本地工具（curl、node）不受影响。
- 返回码：`no-credential` / `unauthorized` / `upstream` / `network`，以及成功时的 `{ ok: true, data, fetchedAt }`。

## 安全边界

- Key 不出 host 进程；路由只返回余额数据。
- 默认 Web 部署只监听 `127.0.0.1`；若把 webServer 绑到 `0.0.0.0`，该路由也会暴露到局域网（余额信息，非密钥）。
- 本插件不修改任何配置或凭据文件。