dsh-balance-display

Readme

# dsh-balance-display

DeepSeek API 余额显示插件 —— 在 DSH Web GUI 的**左侧栏底部**实时显示 API Key 剩余额度，支持低余额预警、余额消耗趋势、一键充值。

**密钥全程只在主机端**：主机端通过 dsh 凭据服务读取 key 并查询 `api.deepseek.com/user/balance`，浏览器端只从本机回环路由拉取脱敏后的余额 JSON，密钥绝不进入浏览器。

## 功能

- **左下角余额胶囊**：显示 `余额 ¥92.12`，点击刷新，悬浮显示充值/赠送拆分
- **低余额预警**：低于阈值（默认 ¥5，可调）圆点变红 + 悬浮警告 + 可选浏览器通知（跨过阈值只提醒一次）
- **小额精度自适应**：余额 < ¥1 时显示 4 位小数（`¥0.5842`），清楚还剩几分钱
- **余额趋势**：localStorage 记录历史点，设置页 sparkline 趋势图 + 今日/近 7 天消耗统计
- **充值直达**：胶囊与设置页均可一键打开 `platform.deepseek.com/usage`
- **错误退避重试**：连续失败时刷新间隔自动递增（1min → 5min → 30min）
- **页面隐藏暂停轮询**：切走标签页暂停刷新，回来立即刷新
- **跟随主题**：浅色 / 深色 / 跟随系统，与 DSH 外观设置一致
- **中英文界面**：跟随 dsh 语言设置实时切换
- **Agent 协作**：在系统提示中声明插件，智能体可在余额过低时提醒用户充值

## 安装

已发布到 npm：

```sh
dsh plugin --profile web add dsh-balance-display
```

本地开发模式：

```sh
dsh plugin --profile web add link:/path/to/dsh-balance-display
```

装完**重启 dsh web**（宿主端改动需重启；纯客户端改动硬刷新浏览器即可）。侧边栏底部出现余额胶囊，设置页出现「余额显示」tab。

## 安全设计

| 风险 | 对策 |
|---|---|
| Key 泄漏到浏览器 | Key 只在主机端 resolve 后用于余额请求的 `Authorization` 头；客户端只 fetch 本机路由；路由响应 schema 无 key 字段 |
| Key 泄漏到日志/错误 | 不写日志含 key 值；所有外发错误文本经 `redact()` 脱敏（`sk-*` / `Bearer *` → `[redacted]`），客户端二次脱敏兜底 |
| 客户端 bundle 携带 key | 客户端是纯静态渲染代码，不含任何凭据；安装后 grep 断言零匹配 |
| 路由被滥用 | 仅 GET（余额）与 GET/POST（announce 配置）；dsh web 默认仅绑定 127.0.0.1；不加 CORS 头 |
| 上游数据 XSS | React 文本转义渲染，无 `innerHTML` |
| 上游卡死 | 请求 10s 超时；缓存 TTL 有界；并发请求共享一次上游调用 |

## 配置

设置页「余额显示」tab：

| 项 | 说明 |
|---|---|
| 侧边栏显示余额角标 | 开关胶囊显示 |
| 自动刷新间隔（分钟） | 默认 10 |
| 低余额预警阈值（¥） | 默认 5 |
| 余额不足时浏览器通知 | 需授权通知权限 |
| Agent 协作 | 在系统提示中声明插件（实时同步到主机端） |

余额历史与偏好存于浏览器 localStorage（`dsh.balanceDisplay.*`），主机端不感知、不存储。

## 兼容性

兼容**桌面打包版**（内嵌 dsh rc.5）与**官网 npm 版 `dsh web`**（rc.6）：两者共用同一套 profile 插件协议（bundle 挂载、`/plugins/<id>/client.js` 服务、webServer 路由、credentials 服务）。插件零 `@deepseek-ai` 运行时依赖，所有接入点特性检测，一份代码两种形态通用。

## 开发

```
dsh-balance-display/
├── package.json          # dsh.bundle.patch + dsh.client 清单
├── cordis.patch.yml      # 插件挂载行
└── lib/
    ├── index.js          # 主机端：余额路由 / config 路由 / 脱敏 / 缓存
    └── client.js         # 浏览器端：左下角胶囊 / 设置页 / i18n / 趋势图
```

测试（主机端 stub + 客户端 SSR 冒烟，无需启动 dsh）：

```sh
node /tmp/test-balance-host.mjs      # 主机端：脱敏/缓存/并发去重/凭据失效/config 路由
node /tmp/test-balance-client3.mjs   # 客户端：精度/退避/消耗/历史/阈值
```

发布新版本：

```sh
npm version patch   # 或 minor / major
npm publish         # 需输 2FA 动态码
```

## License

MIT