lijunyu726/dsh-header-balance

dsh-header-balance

DSH Web GUI 的 DeepSeek 余额芯片：在会话页头部显示账户余额，点击跳转充值，悬停可见赠送 / 充值拆分。

API Key 与网络请求全部在宿主侧完成，key 永不进入浏览器代码。

余额芯片演示：会话页头部显示余额，点击跳转到充值页

功能

| 能力 | 说明 |
|---|---|
| 余额显示 | 会话页头部芯片，只显总余额，视觉密度与你熟悉的「会话日志」按钮一致 |
| 点击充值 | 点整块芯片打开 platform.deepseek.com/top_up；Electron 外壳会交给系统浏览器 |
| 手动刷新 | 芯片内的 ↻ 按钮（已阻止冒泡，不会误触充值跳转） |
| 自动刷新 | 挂载时、每 60 秒、窗口重新获得焦点时 |
| 悬停详情 | 账户余额 + 赠送 / 充值拆分（赠金为 0 时自动省略该行）+ 充值入口 |
| 窄屏适配 | 手机端省略「余额」二字，只留金额 |
| 不可用告警 | is_available 为 false 时给出明确提示，而非静默显示 ¥0.00 |
| 失败可读 | 未配置 Key / Key 失效 / 余额不足 / 限流 / 超时 / 断网 / 响应异常，各有对应文案 |

安装

dsh plugin --profile web add dsh-header-balance

重启 DSH 后，会话页头部就会出现余额芯片。

dsh plugin add 会读取本包 package.json 里的 dsh.bundle.patch，自动把插件插进配置树，不需要手工编辑 cordis.patch.yml。下面是它替你做的事，仅供排查时参考：

- insert:
- id: dsh-header-balance
name: 'dsh-header-balance'

也可以用 npm 直接装（例如自建 profile 或离线分发），但要自己补上面那条 insert：

npm install dsh-header-balance

插件读取的凭据与官方 llm-deepseek 适配器同一个引用（默认 DEEPSEEK_API_KEY），因此只要模型能用，余额就能查到，无需单独配置。

架构要点（为什么有宿主侧代码）

「余额」和纯前端的挂件不同，它必须走宿主侧：

浏览器（lib/client.js）                 宿主（lib/index.js）
connection.rpc.call('/api',             读 settings['llm-deepseek']
'accountBalance/balance', {} )   →    经 credentials.resolve() 取 API Key
↓                                   GET api.deepseek.com/user/balance
只拿到归一化后的数字  ←──────────────      解析线上 snake_case 字符串为数字

三条硬约束，都写在 ARCHITECTURE.md 里并有行号依据：

1. 客户端不得使用 ctx.remote.accountBalance。 remote. 命名空间只为官方那 15 个 strict 贡献挂载；社区插件用了会永久 pending，并把宿主启动一起拖垮。必须走原始载体 connection.rpc.call。
2. 宿主 inject 必须为空。 它是启动闸门，声明了却拿不到的服务会让整个 App 起不来。settings / credentials 一律软 ctx.get() 读取，取不到就回退。
3. Remote 方法签名不可随意改。 网关的 SRC 发现会从 Function.prototype.toString() 解析参数名，因此不能用解构、默认值、剩余参数或重名参数。

线上端点：accountBalance/balance，载荷 { args: {} }。

开发

node scripts/link-host-deps.mjs   # 把宿主侧 peer 依赖软链到本仓库（仅开发用）
npm run build:bundle              # 由 lib/balance.js 重新生成 bundle 的内联段
npm run check                     # 语法预检 + 校验内联段与源文件一致
npm test                          # 36 项测试
npm run verify                    # 以上全部

lib/client.js 里的展示逻辑不是手写的，而是由 scripts/inline-balance.mjs 从 lib/balance.js 构建期内联。原因是 DSH 的 bundle 解析器只认平台 seed 字面量与已注册的包 id，require 自身子路径必定失败；而逻辑又不能直接手写在 bundle 里，否则无法在 Node 下单测。

三层测试

- test/balance.test.js（12 项）—— 展示格式化与文案。纯函数，无依赖。
- test/host-service.test.js（19 项）—— 宿主半边。真的 import @deepseek-ai/dsh-typert-protocol 并断言 remoteMethods() 能读到 Remote 标记，因此 SRC 发现那条路是真验过的，不是打桩。覆盖成功路径、七类失败、凭据优先级与回退、以及「API Key 绝不进入返回值」。
- test/client-contract.test.js（5 项）—— bundle 契约。在 node:vm 里真正执行 lib/client.js，其 require 模拟只放行平台 seed 字面量，比真实宿主更严格。

宿主侧测试需要 scripts/link-host-deps.mjs 建好软链；缺少已安装的 DSH 时这些用例会自动跳过并在报告里标注，纯逻辑测试不受影响。

已知边界

- 只在 DSH 0.1.5 的槽位契约上验证过（conversation.session.header.utilities，kind: list）。
- 赠送 / 充值拆分只在悬停说明里，芯片本体只显总额——这是刻意的，避免头部控件变宽。
- 不做余额历史、不做用量统计、不做告警阈值。
- 金额不参与任何计算，只做展示格式化；结算发生在服务端。
- 依赖宿主侧的 settings 与 credentials 服务；两者任一缺失时会回退到进程环境变量，都取不到则提示未配置。

许可

MIT