余额速览 LiuCrane/dsh-easy-balance

dsh-easy-balance

一个 DeepSeek Harness Web UI 插件，给对话加上两条常驻信息：

1. 模型旁边的服务商 —— 输入框模型选择器左侧紧挨着一个小标签，显示当前选中的模型由哪个服务商提供（opencode-go、lm-studio、deepseek……）。鼠标悬停时显示完整的 provider · model 组合。标签跟随选择器渲染的那份持久选择，所以切换模型，标签也跟着切换。
2. 输入框下方的余额 —— 输入框停靠区里，圆形/上下文那一行的下方单独一行放一条常驻信息条，显示 DeepSeek 账户余额和 OpenCode Go 套餐用量，覆盖 5 小时滚动、每周、每月三个窗口。每个窗口是随插件一起发布的 composer-dock 语言里的一颗胶囊：一个 14px 进度环（几何形状和色调与上下文计量条一致，超过 70% 变琥珀色，超过 90% 变红色）、窗口名称、已用百分比；悬停显示重置时刻。有一个刷新控件可以强制重新读取；除此之外信息条每 5 分钟自动刷新一次。

布局约定：信息条占满整个停靠行（flex: 1 1 100%），并且是 order: 1，所以它渲染在随插件发布的统计胶囊和上下文计量条之后，停靠行把它折到单独一行。这一行与上方那一行之间留一点小间距（停靠行上的 row-gap: 2px），下方有自己的 margin-bottom: 8px。它内部从不换行：文本用省略号截断，同时进度环和数字保持清晰可读，所以侧边栏挤压输入框时，信息条不会长成两三行。每一段文字——包括 DeepSeek 金额——都用同一档三级标签色调；只有进度环超过 70%/90% 时才切换到警告或错误色调。

停靠行是信息条的盒树父级，但不是它的 DOM 父级：插槽条目渲染在插槽的 display: contents 锚点内部（）。因此样式表通过那个锚点定位这一行（div:has(> [data-slot="conversation.composer.dock"]):has([data-easy-balance])），组件还会在挂载后检查该行的计算 flex-wrap，当选择器够不到它时（引擎不支持 :has()，或者锚点变了），退回到设置该行的内联 flex-wrap，并在卸载时恢复之前的值。

安装

dsh plugin --profile <profile> add /absolute/path/to/dsh-easy-balance

或者通过 Plugin Manager（install_bundle）安装本地目录。bundle 补丁插入一行 Host（easy-balance）；这个包还声明了 dsh.client 那一半，所以浏览器 bundle 从 /plugins 提供。

工作原理

| 一半 | 文件 | 作用 |
| Host | index.js | 注册 GET /easy-balance/usage，读取两个服务商，成功读取后缓存 45 秒 |
| Client | client.js | 注册 conversation.input.right（服务商标签）和 conversation.composer.dock（余额信息条） |
两处上游读取都需要凭证，所以它们都在 Host 上完成，绝不会在浏览器里发生：

| 事实 | 端点 | 凭证引用 |
| DeepSeek 余额 | GET https://api.deepseek.com/user/balance | DEEPSEEK_API_KEY |
| OpenCode Go 用量 | GET https://opencode.ai/zen/go/v1/usage | OPENCODE_GO_API_KEY |

凭证通过 ctx.credentials 解析（填充 $DSH_HOME/.credentials.yaml 的也是这同一处接缝），所以轮换后的密钥无需重启就能用于下一次读取。该路由只应答连接层放行的请求，发送 cache-control: no-store，并且绝不在响应体里带上密钥。

GET /easy-balance/usage?refresh=1 会跳过缓存值；如果请求到达时已有一次读取在进行中，它会加入那次读取，而不是再启动一次。

只有当某个类别的服务商确实属于当前配置档时，才会报告该类别：组合必须为它暴露一条已注册的 llm 路由（余额对应任意 deepseek 路由，套餐用量对应 opencode-go）并且能解析出该服务商的凭证。两者缺一，Host 就直接返回 { "configured": false }，完全不调用上游，Client 对该类别也不渲染任何内容——没有余额，没有用量窗口，连错误占位符都没有；当没有任何类别被配置时，整条状态条会彻底消失。已配置的服务商如果读取失败，仍会报告错误，所以真实的故障依然可见。

响应结构

{
"fetchedAt": 1759330000000,
"deepseek": {
"configured": true,
"ok": true,
"available": true,
"balances": [
{ "currency": "CNY", "total": "68.04", "granted": "0.00", "toppedUp": "68.04" }
]
},
"opencodeGo": {
"configured": true,
"ok": true,
"windows": {
"rolling": { "status": "ok", "percent": 6, "resetsAt": "2026-10-01T16:30:03.186Z" },
"weekly": { "status": "ok", "percent": 6, "resetsAt": "2026-10-05T00:00:00.000Z" },
"monthly": { "status": "ok", "percent": 16, "resetsAt": "2026-10-20T08:07:46.000Z" }
}
}
}

| 结果 | 含义 |
| { "configured": false } | 服务商未配置（没有路由，或没有凭证）——Client 隐藏该类别 |
| { "configured": true, "ok": true, ... } | 当前值 |
| { "configured": true, "ok": false, "error": "" } | 已配置但读取失败：unauthorized、network、timeout、bad-json、http-<status> |

一个类别失败，绝不会把另一个类别也藏起来。

测试

node test/smoke.mjs 离线跑两半：它针对 React 桩件物化 Client 包（槽位 id、渲染文本、错误映射），用桩化的 fetch 驱动 Host 路由处理器，并断言凭证引用、缓存、?refresh=1 绕过、方法守卫和连接围栏。这是逻辑测试，不是视觉验证。

设计说明与限制

- 增量席位。 服务商 chip 使用 conversation.input.right，这是一个有序列表槽位，没有任何已发布的占用者，所以不会遮蔽任何东西。状态条
- 在自带的 stats 条目旁边使用 conversation.composer.dock，并通过定位该插槽自己的锚点来占用自己那一行（见上文）；不引用任何自带类名。
- 主题一致性。 这条横条把样式表作为 元素放在自己那一行里（随组件一起移除），只引用 --dsw-alias- token 和宿主的 --dsh-content-font- 属性，因此浅色与深色配色、宿主字体缩放都能生效。运行时不会导入任何 Harness Client 包。
- DeepSeek 分类需要 API-key 路线。 它用 DEEPSEEK_API_KEY 读取平台余额。只登录 DSH account*（deepseek-account 路线）不会显示余额，因为这个数字来自另一个服务。
- 没有固定金额上限。 OpenCode Go 端点只上报百分比，而套餐的月度上限因模型而异，所以横条显示百分比加重置时间，而不是推算出一个金额。
- 路由路径。 /easy-balance/usage 是这个插件唯一新增的路径。改名意味着要同时改两半里的 USAGE_PATH。
- 横条是每个会话的环境装饰；它的读取由 Host 缓存在进程范围内共享，所以打开很多会话不会让上游调用成倍增加。
- 在会话有已知的模型选择之前，服务商 chip 不渲染任何内容，这与模型选择器自身的回退行为一致。
- chip 显示目录里的服务商名称。llm-pi-ai 里没有 displayName 的路由会回退到它的路由 id（opencode-go），所以给那个服务商条目加上 displayName: OpenCode Go，chip 和模型菜单的分组标题都会更好看。