hfdsdfgr/dsh-balance-bar

dsh-balance-bar

一个 DeepSeek Harness Web 插件，以固定在 GUI 右边缘的竖直进度条形式显示你的模型提供商账户余额，用颜色分区告诉你还剩多少可用额度——超出健康阈值的部分则显示为持续流动的动画波浪。

┌──┐
│≈≈│   ← 余额 > 50：浅蓝紫色波浪，持续流动
│≈≈│
│▓▓│
│▓▓│   ← 30 – 50：绿色
│▓▓│
│▓▓│   ← 10 – 30：黄色
└──┘   ←  50 | 绿色固定在 50 刻度处，超出的每一元都绘制为一层动画浅蓝紫色波浪 |

将鼠标悬停在竖条（或胶囊标签）上会弹出一张卡片，显示精确金额、刻度位置、充值/赠送拆分以及读数的新鲜度。点击可立即刷新。尚无读数时，胶囊标签显示 读取中…；如果提供商调用失败，它会保留最后一次有效数值，并在卡片中报告错误，而不是变成空白。

中文速览

一个 DeepSeek Harness Web 插件：在界面最右侧贴边显示一根竖直的账户余额进度条。

- 红色：余额  cordis.patch.yml 附带一个机器特定的绝对路径。 加载器行通过绝对文件 URL 指定 Host
半部分，因此请编辑该行（或让 install.mjs 写入它），使其指向你克隆此仓库的位置。
这里刻意没有 pnpm add 步骤，也没有需要创建的 node_modules 条目。

要求：一个 DSH Web profile，以及配置为凭据 DEEPSEEK_API_KEY 的 DeepSeek API key
（与 Harness 已使用的同一个 key）。

配置

每个键都是可选的；此处显示的是默认值，它们位于 cordis.patch.yml 中。

| 键 | 默认值 | 含义 |
|---|---|---|
| credentialRef | DEEPSEEK_API_KEY | 保存提供方 key 的凭据引用 |
| endpoint | https://api.deepseek.com/user/balance | 余额端点（任何 DeepSeek 兼容的端点均可） |
| cacheTtlMs | 60000 | 一次读取在重新获取前可被提供多久 |
| pollIntervalMs | 300000 | 后台刷新频率 |
| timeoutMs | 10000 | 每次请求的超时时间 |

架构

两个半部分，一个插件，彼此之间没有重叠。
text
Host half (src/index.ts)
ctx.credentials.resolve(credentialRef)      → the API key, Host-side only
GET https://api.deepseek.com/user/balance   → provider truth
├─ GET /dsh-balance/snapshot                → same-origin JSON the page polls
└─ globalThis.__DSH_BALANCE__               → index-injection row for first paint

Browser half (src/client.js)
window.__ModuleLoader__.load({ id, factory })   → the whole transport contract
require('react')                                → the shell's platform seed
ctx.slots.inject('shell.overlay')               → the fixed bar + hover card

为什么使用 HTTP 路由而不是 @Remote？ Remote 方法由 Typert 构建流水线根据 Host 装饰生成。
一个位于 Harness 构建之外的插件必须描述自己的线上协议，因此此插件通过一个精确命名的路由发布在
ctx.webServer 上。它刻意不位于 /api 之下：那个载体属于 Connection 插件，它会进行认证，
并会拒绝每一个它不拥有的路由。跨线传输的是一个仅用于显示的读数，而随附的 Web 组合仅绑定到
loopback。

为什么是 shell.overlay？ 它是布局包的根作用域列表槽——唯一一个
插件可以在不占用列的情况下把东西放到 shell 边缘。ctx.slots.inject
会等待声明，在重新声明后重新运行，并在此插件卸载时移除贡献。

测试

四项检查，纯 Node，无测试框架：
sh
node scripts/client-spec.mjs      # 色带、缩放、波形几何、载荷投影
node scripts/client-smoke.mjs     # 通过打桩的 window.__ModuleLoader__ 加载 bundle
node scripts/theme-tokens.mjs     # 每个 var(--dsw-) 引用都能在真实主题中解析
node scripts/balance-smoke.mjs    # 挂载 Host 半边并驱动实时 provider
node scripts/verify-deployed.mjs  # 对运行中的 GUI 进行只读探测

client-spec 在产品规则的边界处将其固定下来——10 是黄色，30 是绿色，50 仍然是绿色，
任何高于此值都会开启波形——并证明波形路径闭合其相位，因此动画循环时没有可见的跳跃。

theme-tokens 的存在是因为不存在的 CSS 自定义属性会静默失败：声明被丢弃，硬编码的
回退值反而被绘制出来，看起来像是设计选择而不是 bug。此插件的悬停卡片曾经就是这样发布的——
四个引用（--dsw-alias-bg-elevated、--dsw-alias-text-primary、--dsw-alias-text-secondary、
--dsw-alias-border-subtle）从未被 ui-theme 定义，因此卡片渲染成一种褪色的硬编码灰色，
看起来像是永久半透明。该检查会提取 bundle 实际安装的样式表，将每个 --dsw- 引用与
ui-theme 在 DSH 检出中声明的名称进行比较，并断言数值 chip 是水平的。

verify-deployed 生成浏览器会话 cookie，从所服务的 index 中读取 window.__DSH_BOOT__，
并下载浏览器实际会使用的 bundle 路由：这就是“文件是正确的”与“GUI 正在运行它们”之间的区别。

调整外观

阈值、缩放、波形颜色和刷新节奏是 src/client.js 顶部的命名常量：

| 常量 | 默认值 | 含义 |
|---|---|---|
| SCALE_LIMIT | 50 | 填充达到顶点的元数 |
| RED_LIMIT | 10 | 红色带的上界（不含） |
| YELLOW_LIMIT | 30 | 黄色带的上界（不含） |
| REFRESH_MS | 60000 | 浏览器轮询间隔 |
| PALETTE | 红 / 黄 / 绿渐变 | 填充颜色 |
| WAVE_CREST, WAVE_BODY | #cddcff, #8fb0ff | 浅蓝紫色波形 |

布局位于同一文件中的 STYLES 块：垂直条在 right: 12px 处宽 16 px，水平数值 chip 固定在其
左侧 right: 34px 处，两者在悬停时都会略微加宽/移动。颜色来自主题的语义 token
（--dsw-alias-label-、--dsw-alias-bg-layer-1、--dsw-elevation-），因此插件会跟随
浅色和深色模式；色带颜色是字面量，因为它们是产品规则而不是主题的。

许可证

MIT — 见 LICENSE。