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