余额面板 luhaifeng666/dsh-balance-plugin

dsh-balance-view

一个 DeepSeek Harness（dsh） 插件：查询当前 DeepSeek API Key 对应账号的账户余额，在输入框上方用常驻面板展示，并保持实时更新。

面板余额会在以下时机刷新：

- 面板出现时：会话中面板首次挂载就查询一次。
- 每轮对话结束后：一个对话回合（turn）结束时自动刷新——此时扣费已基本结算，余额最贴近真实。
- 定时轮询：面板可见期间每 5 分钟兜底刷新一次，避免长时间无对话时余额过期。
- 手动刷新：点面板右侧的 ⟳ 按钮随时手动刷新，刷新中图标会旋转。

点 × 可手动关闭面板。

效果

账户余额 CNY 34.53（赠送 0.00 / 充值 34.53） ⟳ ×

安装

从 npm 安装（推荐）
dsh plugin --profile web add dsh-balance-view

或从 GitHub 安装
dsh plugin --profile web add github:luhaifeng666/dsh-balance-plugin

或从本地目录安装
dsh plugin --profile web add ./dsh-balance

也可替换成你自己的 profile 名（如 desktop）。安装后重启 dsh 生效。

使用

- 输入 /balance 回车，会在对话流中显示当前余额（命令结果节点）。
- 输入框上方的常驻面板会自动查询并实时更新；也可点 ⟳ 手动刷新。

实现

- host 侧（index.js）：注册 /balance 命令，handler 读取凭据服务中的 DEEPSEEK_API_KEY，请求 https://api.deepseek.com/user/balance，把结果作为命令文本返回。不写会话日志、不注册投影。
- client 侧（client.js）：向 conversation.input.dock 槽位注入面板，余额由组件本地 state 持有。三种自动刷新（挂载 / 回合结束 / 轮询）与手动刷新都通过 ctx.remote.commands.execute(sessionId, "/balance") 触发 host 查询，再读取返回文本。

设计说明：为何不写会话日志

原版把余额经 session.append("balance/change", …) 写入会话日志并驱动投影。但 DSH 的持久化层（session-persistence-jsonl，所有 profile 默认启用）在恢复会话时，会拒绝日志里不在已知事件表中的类型——balance/change 是插件自定义事件、不在该表内，且 Session.append 无法标记 ignorable，会导致凡收到过余额刷新的会话重启后无法恢复。加上轮询 / 每轮刷新会高频写入，几乎每个会话都会被污染。

因此本插件改为「命令返回文本 + 面板本地 state」：余额只做一次性查询、不进会话日志，彻底规避该恢复风险。代价是自动刷新会以 /balance 命令节点的形式出现在对话流中（command/run / command/done 为 log-only 事件，不进模型上下文、不影响 KV cache）。

License

MIT