dsh-balance-vision

Readme

# dsh-balance-vision

DeepSeek 余额实时显示插件(**含视觉模型支持**): 在 dsh Web UI 输入框**下方、命中率/输入输出 token 统计条所在的同一行**, 实时显示:

- **账户余额与充足度状态指示灯**(如 `🟢 余额 ¥97.69`, 红/黄/绿三色直观反映余额充裕状况，**点击状态圆点可直接手动强刷查询最新余额**)
- **本次对话的估算消耗**(如 `本会话约 ¥3.92`, 按模型、按 DeepSeek 官方单价估算)
- **`?` 定价参考图标**: 悬停以 `?` 为中心优雅浮现 **DeepSeek V4 系列专属定价微卡片**（支持 `deepseek-v4-flash` / `deepseek-v4-flash-vision-exp` / `deepseek-v4-pro`），点击直达官方定价页 <https://api-docs.deepseek.com/zh-cn/quick_start/pricing/>

悬停读数可查看**左右双栏毛玻璃卡片**：
- **左栏【📊 账户余额】**：实时大字总额、充足度 Badge、充值与赠送金额构成、5分钟自动刷新时间戳点击指示灯强刷指引以及偏好设置快速入口。
- **右栏【⚡ 本会话消耗】**：当前会话预估总花费、按模型细分明细（如 `• deepseek-v4-flash-vision-exp: ¥3.92`）、换行小字体展示输入/输出与缓存命中统计。
- **时间感知引擎**：内置 DeepSeek 官方谷峰计费自动切换机制（见下方「官方谷峰规则」），全自动无缝同步。

## 🆕 视觉模型支持

本插件内置 **`deepseek-v4-flash-vision-exp`**（DeepSeek 2026-08-23 上线的多模态视觉理解实验模型）官方定价：

- 官方明确视觉模型**计费价格与 `deepseek-v4-flash` 完全一致**（CNY 峰时 0.1/3/9，谷时 0.05/1.5/4.5；USD 峰时 0.014/0.44/1.32，谷时 0.007/0.22/0.66）；
- 使用该模型进行会话时，本插件会自动按 Flash 价格精确估算消耗，无需手工配置；
- 设置面板「模型单价」页签与 `?` 定价卡片中均会展示该模型。

### 官方谷峰规则（2026-08 生效）

1. **空闲时段价格为高峰时段价格的一半**。高峰时段为**北京时间周一至周五 09:00~12:00、14:00~18:00**；其余时间（含**周末全天**）均为空闲时段。插件内置时间感知引擎按此规则自动切换计价，无需人工干预。
2. **图片计费**：发送给 `deepseek-v4-flash-vision-exp` 的图片会**按其尺寸换算成 token，与文本 token 一并计费**——图片进入模型前自动缩放（总像素约相当于 800×800，小于 384×384 的会放大），**每张图片最多 384 tokens**（如 2000×2000 与 5000×5000 的图片换算结果相同）。详见官方[图像理解：Token 用量](https://api-docs.deepseek.com/zh-cn/guides/vision#token-usage)。

![示例预览图](./assets/preview.png)

## 架构

```
┌─────────────┐  按 refreshIntervalMs 轮询   ┌──────────────────┐
│ DeepSeek API│◀────────────────────────────│ 服务器插件(host)  │
│ /user/balance│                            │ · 余额缓存(带陈旧回退)│
│             │  ?force=1 手动强刷路由       │ · /query-balance 路由│
└─────────────┘                             │ · queryBalanceCost  │
                                            │   会话花费投影(含V4谷峰)│
                                            └────────┬───────────┘
                                                     │ 只读缓存 / 投影推送帧
                                            ┌────────▼───────────┐
                                            │ 浏览器插件(client)   │
                                            │ · 双栏悬停卡片      │
                                            │ · 点击指示灯手动强刷  │
                                            │ · 单例轮询器(页面隐藏 │
                                            │   时暂停)            │
                                            └────────────────────┘
```

- **性能**: 浏览器只读本地缓存(每 `clientPollIntervalMs` 一次极小 JSON), 不直接访问 DeepSeek;
  服务器按 `refreshIntervalMs` 拉取并缓存(失败保留上次成功值); 花费由投影折叠计算
  (与 dsh-token-meter 相同的 O(1) 状态机, 同引用事件零开销), 随既有 `session/projection`
  推送帧实时到达客户端, 无额外网络请求。
- **手动强刷**: 点击状态指示灯按钮可直接穿透缓存向 DeepSeek 官方发起实时查询，服务端内置 2000ms 冷却防刷保护。
- **密钥**: 复用 Harness 的 credentials 能力(`ctx.credentials`), 默认引用
  `DEEPSEEK_API_KEY`(即 `$DSH_HOME/.credentials.yaml` 或进程环境), 无需在配置里写密钥。
- **同行动态布局**: 组件全 Flex 居中对齐，与输入框底部统计条完美处于绝对水平中线。

## 安装

### 方式一：使用 DSH CLI 自动安装与配置（推荐）

DeepSeek Harness 自带的插件管理命令可以为您**一键完成下载安装和修改配置文件**：

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

执行完毕后，**重启 `dsh web` 即可生效。**

### 方式二：让 AI 助手帮您安装

如果您正在使用 Antigravity 等 AI 助手，直接复制以下提示词发给它：

> 请帮我在当前环境中安装 `dsh-balance-vision` 插件，将其配置写入到我的 `cordis.yml` 中并启用它。

### 方式三：本地源码安装

如果您下载了源码，可以通过以下命令进行本地链接安装：

```sh
dsh plugin --profile web add <本目录绝对路径>
```

---

## 升级

当插件发布新版本后，您可以通过以下命令升级到最新版本：

```sh
dsh plugin --profile web remove dsh-balance-vision
pnpm store prune
dsh plugin --profile web add dsh-balance-vision@latest
```

> **为什么需要 `pnpm store prune`？**
> pnpm 会在本地缓存已下载的包。如果不清除缓存，即使 NPM 上已经发布了新版本，
> `dsh plugin add` 仍然可能安装到旧版本。执行 `pnpm store prune` 可以清除过期缓存，
> 确保拉取到最新版本。

---

## 卸载

使用 DSH CLI 一键卸载并自动清理配置文件：

```sh
dsh plugin --profile web remove dsh-balance-vision
```

## ⚙️ 可视化设置面板说明

在 Web 界面输入框底部的统计条最右侧，点击 **⚙️ 齿轮图标**（或在悬停卡片底部点击 **⚙️ 打开偏好设置**），即可呼出可视化配置弹窗：

| 配置分组 | 包含设置项 | 说明 |
| :--- | :--- | :--- |
| **🎯 常规与阈值** | 计价货币、预警阈值、告急阈值、服务端查询间隔、前端读取缓存间隔 | 支持实时红黄绿三色阈值指示条预览；货币切换即时反映到会话消耗与余额展示。 |
| **🔑 API 凭证** | API Key、Base URL、请求超时时间、连通性测试 | 支持自定义 API Key（留空自动继承环境凭证）；提供 **⚡ 测试 API 连通性** 按钮，一键验证密钥有效性并反馈真实余额。 |
| **⚡ 模型单价** | 各模型（V4 Flash / V4 Flash Vision-Exp / V4 Pro / Chat / Reasoner）每 1M Token 的命中/未命中/输出单价 | 支持微调模型单价，提供“恢复官方推荐单价”按钮。 |
| **📋 YAML 导出** | 实时生成 `cordis.patch.yml` 配置代码块 | 随调参实时渲染 YAML 配置文本，支持一键复制到剪贴板，方便将当前参数持久化写入配置文件。 |

> **提示**：在设置弹窗中点击「**保存并生效**」，修改将立即应用到当前服务与页面，无需手动重启 `dsh web`！

## 配置模板

在 `$DSH_HOME/profiles/web/cordis.patch.yml`（或指定 profile 的 patch 文件）中覆盖配置。

### 模板 1：标准国内人民币账户（默认开箱即用 · 包含 DeepSeek V4 系列与视觉模型）

```yaml
- id: dsh-balance-vision
  config:
    apiKey: ''                    # 留空自动复用 DEEPSEEK_API_KEY
    apiKeyRef: DEEPSEEK_API_KEY
    baseUrl: https://api.deepseek.com
    warningThreshold: 10          # 余额 < 10 元显示黄色预警灯
    dangerThreshold: 5            # 余额 < 5 元显示红色告急灯
    refreshIntervalMs: 300000     # 服务器向 DeepSeek 拉取余额的查询间隔(单位: 毫秒 ms，300000ms = 5分钟)
    clientPollIntervalMs: 30000   # 浏览器从本地读取缓存的刷新间隔(单位: 毫秒 ms，30000ms = 30秒)
    timeoutMs: 8000               # 单次网络请求超时时间(单位: 毫秒 ms，8000ms = 8秒)
    currency: CNY
    prices:
      deepseek-v4-flash: { cacheHit: 0.1, cacheMiss: 3, output: 9 }
      deepseek-v4-flash-vision-exp: { cacheHit: 0.1, cacheMiss: 3, output: 9 }
      deepseek-v4-pro: { cacheHit: 0.3, cacheMiss: 9, output: 27 }
      deepseek-chat: { cacheHit: 0.1, cacheMiss: 1, output: 2 }
      deepseek-reasoner: { cacheHit: 1, cacheMiss: 4, output: 16 }
    defaultPrices: { cacheHit: 0.1, cacheMiss: 1, output: 2 }
```

### 模板 2：海外美元账户（USD 计价与小额阈值）

```yaml
- id: dsh-balance-vision
  config:
    apiKey: ''
    apiKeyRef: DEEPSEEK_API_KEY
    baseUrl: https://api.deepseek.com
    warningThreshold: 2.0         # 余额 < $2.0 显示黄色预警
    dangerThreshold: 0.5          # 余额 < $0.5 显示红色告急
    refreshIntervalMs: 300000     # 服务器拉取余额间隔(单位: 毫秒 ms，300000ms = 5分钟)
    clientPollIntervalMs: 30000   # 浏览器读取缓存间隔(单位: 毫秒 ms，30000ms = 30秒)
    timeoutMs: 8000               # 请求超时时间(单位: 毫秒 ms，8000ms = 8秒)
    currency: USD                 # 计价货币切换为美元
    prices:
      deepseek-v4-flash: { cacheHit: 0.014, cacheMiss: 0.44, output: 1.32 }
      deepseek-v4-flash-vision-exp: { cacheHit: 0.014, cacheMiss: 0.44, output: 1.32 }
      deepseek-v4-pro: { cacheHit: 0.044, cacheMiss: 1.32, output: 3.96 }
    defaultPrices: { cacheHit: 0.014, cacheMiss: 0.44, output: 1.32 }
```

### 模板 3：高频重度开发者（高缓冲安全档）

```yaml
- id: dsh-balance-vision
  config:
    warningThreshold: 50          # 余额 < 50 元预警(留足多次长任务会话缓冲)
    dangerThreshold: 10           # 余额 < 10 元告急
```

---

## 验证

```sh
npm test                         # 运行全部测试
node test/smoke-projection.mjs   # 投影折叠(替换语义/模型归属/计价/工作日峰谷)测试
node test/smoke-client.mjs       # 客户端 bundle 注册与渲染冒烟测试(零依赖)
```

手工验证:

```sh
curl http://127.0.0.1:3080/query-balance
# → {"ok":true,...,"isAvailable":true,"thresholds":{"warning":10,"danger":5},"balances":[{"currency":"CNY","total":99.74,...}]}
curl http://127.0.0.1:3080/plugins/dsh-balance-vision/client.js   # 客户端 bundle
```

## 开发说明

- 服务器插件: `src/index.js`(ESM, 零构建)。
- 客户端 bundle: `client/client.js`, 手写的惰性 CJS 工厂格式
  (`window.__ModuleLoader__.load({id, factory})`), 修改后**重启 dsh web** 生效
  (无 monorepo 构建链时不做 bundle 重哈希)。
- 项目自带 `node_modules`(schemastery/zod), 与 profile 内同名依赖互不冲突。
- 本地测试: `test/` 目录下提供零依赖单元与冒烟测试，发布 npm 时自动排除测试目录。

## 常见问题 (FAQ)

**Q: 插件怎么知道查询的是哪个用户的余额数据？**

A: 插件在向 DeepSeek 官方服务器发送查询请求时，会在请求头中携带您的 **API Key**（即 `sk-xxxx`）。因为每一个 API Key 在 DeepSeek 官方都是唯一绑定到您的账号上的，所以服务器通过识别这串凭证，就能精准返回您的账号真实余额。
此外，本插件利用了 DSH 原生的凭据管理系统（Credentials），它会自动复用您平时用于聊天的 `DEEPSEEK_API_KEY`，所以您甚至不需要在插件里重复配置密钥。

**Q: `deepseek-v4-flash-vision-exp` 视觉模型怎么计价？**

A: 根据 DeepSeek 官方定价页，视觉模型**计费价格与 `deepseek-v4-flash` 完全一致**；图片会**按其尺寸换算成 token，与文本 token 一并计费**（图片自动缩放至约 800×800 总像素，每张图片最多 384 tokens）。本插件已内置该模型的峰时/谷时、CNY/USD 官方单价，使用该模型时会话消耗自动按 Flash 价精确估算。

**Q: 官方谷峰规则具体是什么？插件会自动同步吗？**

A: **完全自动同步！** 官方规则（2026-08 生效）：**空闲时段价格为高峰时段价格的一半；高峰时段为北京时间周一至周五 09:00~12:00、14:00~18:00，其余时间（含周末全天）均为空闲时段**。插件内置时间感知计费引擎（`isPeakHourBJT`），按北京时间的**星期几与小时**自动判断峰/谷并切换计价，无需人工重启或修改任何配置。

**Q: 红黄绿状态指示灯的判断规则是什么？**

A:
* 🟢 **绿色（充足）**：余额 $\ge$ `warningThreshold`（默认 $\ge 10$ 元），账户额度充裕。
* 🟡 **黄色（偏低）**：`dangerThreshold` $\le$ 余额 $<$ `warningThreshold`（默认 $5 \sim 10$ 元），提示余量不多，建议适时充值。
* 🔴 **红色（告急）**：余额 $<$ `dangerThreshold`（默认 $< 5$ 元）或余额不可用/异常，警示当前任务可能中断。
各阈值均可在可视化设置面板或配置文件中自由调节。

---

## 📝 更新日志 (Changelog)

### v0.1.0 (2026-08-25)

- 🖼️ **新增 DeepSeek 视觉模型支持**：
  - 内置 `deepseek-v4-flash-vision-exp`（2026-08-23 官方上线的多模态视觉理解实验模型）官方定价；
  - 官方定价与 `deepseek-v4-flash` 一致，峰时/谷时、CNY/USD 全量内置；
  - `resolveModelPrice` 自动识别视觉模型并按 Flash 价格估算会话消耗（未单独配置时继承 flash 自定义价）；
  - `/query-balance` 与 `/query-balance/config` 响应定价表、设置面板「模型单价」页签、
    `?` 定价参考卡片均展示该模型；
- 📅 **官方工作日谷峰规则**：
  - 峰时仅限北京时间周一至周五 09:00~12:00、14:00~18:00，周末全天按谷时（半价）计价；
  - 新增 `isPeakHourBJT` 时间感知辅助函数并全量接入计价与序列化；
  - 客户端 `?` 定价卡片与日程提示同步更新；
- 派生自 [dsh-balance](https://github.com/TwotwoPiggy/dsh-balance) v0.2.2（继承其全部余额展示、
  可视化设置面板与测试体系）。

---

### 上游 v0.2.2 (2026-08-17, dsh-balance)

- 🔒 **配置与数据安全强化**：
  - 修复前端保存设置时对空 `apiKey` 的误清空缺陷；
  - 修复 `thresholds` 多币种初始化时的浅拷贝覆盖问题，实现逐币种深度合并（Deep Merge）；
  - 为 `readJsonBody` 增加 10 秒超时防护与超大请求体熔断机制。
- 💱 **实时币种自适应与定价完整性**：
  - 切换计价货币（CNY ↔ USD）后前端即时动态自适应折算会话消耗，无需刷新网页；
  - 完善谷时自定义模型定价下发与服务端回退的一致性。