dsh-balance-effort

dsh-balance-effort

DSH 插件：会话标题栏的账户余额徽标 + 输入框右侧的推理等级滑块。两者共用一个包，是因为它们当初解决的是同一次「让会话头部可用信息更完整」的需求，装起来也只要挂一行。

安装步骤见仓库根目录 README。

目录结构

dsh-balance-effort/
├─ package.json        # name / dsh.bundle.patch / dsh.client 三处声明，缺一不可
├─ cordis.patch.yml    # bundle 层：把本包作为一行 insert 进宿主组合
└─ lib/
   ├─ index.js         # Host 半：Node 侧路由，直连 DeepSeek 余额接口
   └─ client.js        # 浏览器半：__ModuleLoader__.load 注册的两个控件

Host 半

在组合的 webServer 上挂一条只读路由：

方法	路径	说明
GET	/dsh-balance/balance	返回余额快照
GET	/dsh-balance/balance?force=1	绕过 5 秒缓存

响应：

{
  "phase": "ok",              // ok | no-key | error
  "isAvailable": true,
  "currency": "CNY",
  "total": 18.69,
  "granted": 18.69,
  "toppedUp": 0,
  "fetchedAt": 1759... ,      // epoch ms
  "updatedLabel": "21:04:34", // 本机时钟 HH:mm:ss
  "source": "..."             // 凭据来源，可缺省
}

出错时是 { "phase": "error", "message": "..." }，没配 Key 是 { "phase": "no-key" } —— 浏览器半据此显示「未配置」而不是报错。

实现口径：

• Key 来自 ctx.credentials.resolve('DEEPSEEK_API_KEY')，只在 Host 进程里用，不出进程；
• 路由只接受 GET（其余 405 + Allow: GET）、不接受任何入参、cache-control: no-store；
• 5 秒内重复请求命中缓存，并发请求合并成一次；单次上游请求 20 秒 AbortSignal.timeout 硬超时；
• 上游永远请求 https://api.deepseek.com/user/balance，URL 不来自输入，没法当 SSRF 跳板；
• 多币种时优先挑 CNY 那一条。

浏览器半

控件	slot	id	order
余额徽标	conversation.session.header.utilities	deepseek-balance	10
推理等级滑块	conversation.input.right	reasoning-effort-slider	0

ctx.inject(['modelDirectories'], ...) 用来等 @deepseek-ai/dsh-client-ui-model-selection 先就绪 —— 本插件在启动序列里可能比它 apply 得更早，直接 ctx.get 一次会拿到 undefined 并把滑块永久钉死。

余额徽标行为

• 挂载即拉一次，之后每 60 秒刷新；点击 = 强制刷新；fetch 失败 5 秒后自动重试一次。
• data-state 驱动颜色：ok / low（< ¥10）/ error / loading（脉冲）。
• title 里是完整明细（总余额、赠金 / 充值、更新时间），触屏设备看不到，所以 aria-label 用同一份文本。
• 所有计时器都在 effect 清理里回收，组件卸载后不会继续打接口。

推理等级滑块行为

• 档位来自当前模型目录条目的 reasoning.efforts，当前值取会话选择的 reasoningEffort，缺省回落到 reasoning.defaultEffort。
• 交互：拖拽（pointer capture）、点轨道、←/→/↑/↓ 键；提交走 directory.select({ provider, model, reasoningEffort })。
• 面板是 position: fixed 锚在胶囊上方，滚动 / 改窗口尺寸直接关掉（锚点失效）。
• 重置按钮把当前模型的档位恢复成 defaultEffort。
• 拿不到档位时渲染灰胶囊并写明断点（无服务 / 无目录 / 加载中 / 无选择 / 未收录 / 无档位），不会 return null —— 静默消失是最难排查的失败形态。

已知限制

• 余额接口是 DeepSeek 官方 user/balance，只对 DeepSeek 平台 Key 有效；用别的 provider 时不显示余额（显示「未配置」或错误）。
• 低余额阈值 LOW_BALANCE = 10 写死在 lib/client.js 顶部，按币种数值比较，不区分 CNY/USD。
• 滑块只调整会话级 reasoningEffort，不改模型默认值。