deepseek-balance-banner

Readme

# DeepSeek Balance Banner · DSH 余额横幅

> 为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)(DSH)Web 界面提供的**顶部余额横幅**：在页面顶部右侧(主题切换按钮左侧)同时显示你的 DeepSeek 账户 **USD 与 CNY 余额**,一目了然。

![顶部余额横幅](docs/banner.png)

*双币种胶囊：¥ 人民币(负数高亮)+ $ USD · 悬停显示提示 · 点击手动刷新 · 每 60 秒自动刷新*

---

## 功能

- 💵 **双币种同时显示**：调用 `GET /user/balance` 解析全部 `balance_infos`,USD 与 CNY 各一个胶囊
- 📍 **位置精确**：固定在页面顶部右侧,主题切换(白昼/夜间)按钮的**左侧**,不遮挡任何控件
- 🩸 **扣血动画**：检测到余额**扣款**时,从余额胶囊旁弹出**红色游戏化扣血飘字**(`-¥0.03`),上浮放大渐隐,金额越大越醒目
- 💚 **充值动画**：检测到**充值/入账**时,弹出**绿色正向飘字**(`+¥0.05`),向上弹出渐隐
- 🕐 **峰谷时段识别**：实时显示当前处于**高峰**(北京时间周一~周五 9:00–12:00、14:00–18:00,标准价)还是**低谷**(半价);**周六/周日全天自动显示为低谷价**(DeepSeek 官方 2026-08-23 生效规则),徽章附当前北京时间
- 🧮 **会话累计**：悬停横幅显示本次页面会话的扣款总额与充值总额
- 🎨 **主题自适应**：使用 DSH 主题变量(`--dsw-*`),深色/浅色皮肤均协调
- ⚠️ **负余额高亮**：余额 < 0 时显示警告色,一眼看到欠费
- 🔄 **自动 + 手动刷新**：每 60 秒自动刷新;点击任意胶囊立即刷新(宿主侧 25 秒 TTL 缓存,避免打爆接口)
- 🔐 **密钥零暴露**：插件不含密钥;API Key 由 DSH 凭据服务在宿主侧解析,浏览器只访问本机路由
- 🎬 **演示模式**：URL 加 `?dsb-demo=1` 自动循环播放扣血/充值动画(开发/预览用)

## 前置条件

| 要求 | 说明 |
|---|---|
| DeepSeek Harness | `dsh >= 0.1.0-rc.6`(推荐 `0.1.1-rc.2+`) |
| API Key | 已在 DSH 凭据中配置 `DEEPSEEK_API_KEY`(用于 `GET https://api.deepseek.com/user/balance`) |
| Web Profile 目录 | `$DSH_HOME/profiles/web/`(Windows 默认 `%USERPROFILE%\.dsh\profiles\web\`) |

## 安装

### 方式 A(推荐)∶一条命令安装

本插件是标准的 **DSH bundle 包**(`package.json` 声明 `dsh.bundle.patch`):

```bash
# 从 npm 安装
dsh plugin --profile web add deepseek-balance-banner

# 或从 GitHub 直装(不需要 npm 账号)
dsh plugin --profile web add github:iskshadow195563/DeepSeek_Harness_Balance_Banner#v1.0.0
```

> - `--profile` 必填,换成你实际使用的 profile 名(`web` 为默认 Web 界面 profile);
> - 安装完成即加入 Profile 的 bundle 层,**重启 `dsh web`** 后生效(与官方皮肤插件同机制);
> - 本仓库带 `dsh-plugin` topic,可被 [YELEBAI/dsh-plugin-marketplace](https://github.com/YELEBAI/dsh-plugin-marketplace) 等社区市场自动扫描收录。

### 方式 B:手动安装(Windows / macOS / Linux 通用)

1. **下载** `deepseek-balance-banner.mjs`(本仓库根目录,或 Release 附件),放入 Web profile 目录：

   ```bash
   # macOS / Linux
   cp deepseek-balance-banner.mjs "${DSH_HOME:-$HOME/.dsh}/profiles/web/"
   # Windows PowerShell
   Copy-Item deepseek-balance-banner.mjs "$env:USERPROFILE\.dsh\profiles\web\"
   ```

2. **合并补丁**：编辑同目录 `cordis.patch.yml`,追加：

   ```yaml
   - insert:
       - id: deepseek-balance-banner
         name: ./deepseek-balance-banner.mjs?v=1
   ```

   已有其他 insert 条目时,把 `- id: deepseek-balance-banner` 两行追加进列表;`?v=1` 用于破 ESM 缓存,升级时 +1。

3. **保存即热生效**;若 5 秒内未生效,重启 `dsh web`。
4. **F5 刷新页面** — 顶部右侧、「白昼/夜间」按钮左边出现双币种余额胶囊。

## 使用

| 操作 | 说明 |
|---|---|
| 查看余额 | 顶部右侧胶囊:¥ 人民币 / $ USD(负值高亮警告色) |
| 手动刷新 | 点击任意胶囊;也可等 60 秒自动刷新 |
| 余额来源 | 官方 `GET /user/balance`,与 DSH 右下角鲸鱼挂件同源 |

## 卸载

```bash
dsh plugin --profile web remove deepseek-balance-banner
```

文件型安装则:删除 `deepseek-balance-banner.mjs` + 移除 `cordis.patch.yml` 中的 insert 两行,刷新页面。

## 工作原理

```
浏览器页面 ──(同源 fetch)──> 本机 dsh web(/dsb-balance.json)
                                    │ ctx.credentials 解析 DEEPSEEK_API_KEY(不落页面)
                                    ▼
                     https://api.deepseek.com/user/balance  (balance_infos: USD + CNY)
```

- 宿主插件注入页面脚本 `panel.js`,并把余额端点挂在本机 `dsh web`;
- 宿主侧 25 秒 TTL 缓存,页面 60 秒轮询,请求量可控;
- API Key 永不进入浏览器。

## 发布 Release(v1.x)

```bash
git tag v1.1.0 && git push origin v1.1.0
gh release create v1.1.0 --title "v1.1.0" --notes "变更: ..." ./deepseek-balance-banner.mjs
```

或 GitHub 网页:Releases → Draft a new release → 选择 tag → 上传 `.mjs` 附件 → Publish。
每次发布记得把安装补丁里的 `?v=` 数字 +1(破浏览器 ESM 缓存)。

## 常见问题(FAQ)

| 问题 | 解决 |
|---|---|
| 顶部没出现胶囊 | 确认补丁已合并、`dsh web` 已重载,并 **F5**;同一插件不要与包形态重复安装 |
| 显示 `—`/加载中 | 检查 `DEEPSEEK_API_KEY` 是否已在 DSH 凭据中配置 |
| 只显示一个币种 | 你的账号可能只返回一种币种;DSH 官方适配器也会使用同源数据 |

## 安全设计

- 插件不含任何密钥;密钥仅由 DSH 凭据服务在宿主进程内解析;
- 页面只与本机 `dsh web` 同源通信,不跨域、不落 Key;
- 只读接口,无任何写操作。

## License

MIT License — see [LICENSE](LICENSE).

---

<p align="center">
  与 DeepSeek 官方 <a href="https://api-docs.deepseek.com/">API</a> 兼容 · 社区独立开发,与 DeepSeek 官方无隶属关系
</p>