Balance Panel — DSH 的可扩展余额/用量面板

前言¶

在使用 DeepSeek Harness (DSH) 进行智能体开发时，如果同时接入多个模型后端，切换 provider 后查看余额或用量通常需要跳转页面或打开新标签。Balance Panel 旨在解决这个问题。这是一个可扩展的余额/用量面板，以浮动卡片的形式固定在 DSH Web UI 的右侧边缘。它根据当前会话使用的后端自动选择显示内容，同一时刻只显示一张面板。

核心功能¶

浮动与自动隐藏：面板常驻右侧边缘。当当前会话的模型命中某个已接入的后端时，面板显示；切换到未接入的 provider 时自动隐藏。
多后端支持：内置三种后端逻辑，适配不同的计费模式：
- OpenCode Go：适配订阅配额，支持进度条和重置倒计时。
- Zhipu：适配按量计费的现金余额。
- DeepSeek：适配按量计费的现金余额。
可扩展架构：通过修改配置文件中的 BACKENDS 数组，可以添加新的供应商支持，无需修改客户端代码。

安装与启用¶

    bash install.sh

该脚本会执行 `npm pack` 并通过 `dsh plugin add` 安装到默认的 web profile。

启用面板：
- 打开 DSH Web UI。
- 进入 设置 -> 余额面板。
- 开启开关。
- 设置刷新间隔（可选：15/30/60/120s）。
升级方式：
- 先移除旧版本包（例如通过 pnpm --dir ~/.dsh/profiles/web remove @deepseek-ai/dsh-opencode-go-usage）。
- 运行 bash install.sh。
- 更新 dsh.profile.bundles 中的旧包名为 @deepseek-ai/dsh-balance-panel。
- 重启 DSH。

后端语义与展示¶

不同后端的数据展示逻辑不同：

OpenCode Go：显示订阅配额。包含三行数据：剩余百分比、重置倒计时、进度条。颜色阈值：剩余 ≤30% 为橙色，≤10% 为红色。
Zhipu / DeepSeek：显示按量计费现金余额。包含纯金额行：可用余额（加粗）、累计充值、累计消费。赠送和冻结仅在非零时出现。不显示进度条和重置倒计时。

扩展新供应商¶

在 lib/index.js 的 BACKENDS 数组中添加后端对象。主要逻辑包括：

匹配路由：实现 matchesProvider(id, node) 方法，在设置 providers 字典中认领路由。
数据解析：实现 resolvePanel(ctx, providerId, node) 方法，拉取上游数据并归一化为面板结构。
返回结构：返回包含 panel 对象的对象。panel.rows 定义行数据（支持 bar 进度条，仅配额语义使用）；panel.chip 定义折叠徽章；panel.foot 定义底部注脚。

安全与缓存¶

服务端解析：API Key 仅在 DSH 服务端进程内解析，绝不发送到浏览器或写入日志。
独立缓存：不同后端有独立的缓存策略（OpenCode Go 为 15s，其他为 5min）。失败时不缓存，下次轮询重试。
路由防护：包含同源和 loopback 保护，跨站读取请求返回 403。

适用场景与注意¶

此插件适合需要在 Web UI 实时监控多个 API 后端余额和用量的开发者。安装前请确保已阅读源码，并检查许可证（MIT）是否满足需求。