前言¶
DeepSeek Harness（DSH）采用插件化架构，允许开发者通过扩展功能来定制工作流。在 Web profile 中，开发者需要实时监控 API Key 的账户消耗。传统的命令行输出方式不够直观，dsh-balance-view 插件通过在输入框上方挂载常驻面板，解决了这一问题。
插件定位¶
dsh-balance-view 是一个 DeepSeek Harness 插件，由维护者 luhaifeng666 开发，属于“联网工具”分类。它旨在解决开发者需要频繁查看账户余额的问题，通过常驻面板和实时更新机制，提供直观的余额展示。
核心功能¶
该插件主要提供以下能力：
- 余额查询：查询当前 DeepSeek API Key 对应账号的账户余额。
- 常驻面板：在输入框上方展示余额信息，不会遮挡对话内容。
- 实时更新：支持多种刷新触发机制，确保数据尽可能贴近实时：
- 挂载时：面板首次出现时查询一次。
- 回合结束：每轮对话结束后自动刷新。
- 定时轮询：面板可见期间每 5 分钟兜底刷新。
- 手动刷新：面板右侧提供 ⟳ 按钮供用户随时刷新。
- 命令支持：支持输入
/balance命令查看余额。
安装与启用¶
安装该插件需要通过 DSH 的命令行工具进行。请确保你已安装 DSH 并配置好 profile。
# 从 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
安装完成后，需要重启 dsh 进程使插件生效。你也可以替换 --profile 参数为其他 profile 名称（如 desktop）。
使用方法¶
安装并重启后，插件会自动在输入框上方加载面板。
- 查看余额：输入
/balance并回车，会在对话流中显示当前的余额信息。 - 手动刷新：点击面板右侧的 ⟳ 图标，图标旋转时表示正在刷新，刷新完成后显示最新余额。
- 关闭面板：点击面板右侧的 × 图标可手动关闭面板。
实现与设计¶
该插件在实现上分为 Host 侧和 Client 侧：
- Host 侧 (
index.js)：注册/balance命令，读取凭据服务中的DEEPSEEK_API_KEY，请求https://api.deepseek.com/user/balance接口，并将结果作为命令文本返回。Host 侧不写入会话日志，也不注册投影。 - Client 侧 (
client.js)：向conversation.input.dock槽位注入面板组件，余额数据存储在组件本地 state 中。自动刷新和手动刷新均通过ctx.remote.commands.execute(sessionId, "/balance")触发 Host 查询。
设计说明：为何不写入会话日志¶
原版插件曾尝试将余额变化写入会话日志（session.append("balance/change", ...)）。这会导致 DSH 默认启用的 session-persistence-jsonl 持久化层在恢复会话时报错，因为 balance/change 是自定义事件，不在已知事件表中。此外，高频的轮询和刷新会严重污染会话日志。
本插件改为“命令返回文本 + 面板本地 state”的模式：余额仅做一次性查询，不进会话日志。代价是自动刷新会以 /balance 命令节点的形式出现在对话流中，但这不会进入模型上下文，也不会影响 KV cache。
适用场景与注意事项¶
该插件适合所有使用 DeepSeek Harness 进行开发或对话的用户，特别是需要精确控制 API 消耗的场景。
注意事项：
* 插件以当前 dsh 进程的权限运行，请确保安装来源可信。
* 由于不写入会话日志，关闭面板后若不刷新，面板上的余额可能不会反映最新的扣费情况（需依赖回合结束或轮询机制）。
结语¶
dsh-balance-view 通过常驻面板和合理的刷新策略，为 DSH 用户提供了便捷的余额监控手段。若需查看更多详情或提交 Issue，请访问 GitHub 仓库。
