dsh-balance-view

Readme

# dsh-balance-view

一个 [DeepSeek Harness（dsh）](https://github.com/deepseek-ai/deepseek-harness) 插件：查询当前 DeepSeek API Key 对应账号的**账户余额**，并在输入框上方以常驻面板展示，保持**实时更新**。

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

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

点 `×` 可手动关闭面板。

## 效果

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

## 安装

```sh
# 从 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