dsh-balance-guard：DeepSeek 账户余额实时监控与预警插件

前言¶

在使用 DeepSeek Harness（DSH）开发智能体时，API 账户余额是持续消耗的资源。手动查看余额通常需要登录网页控制台，中断开发流程。dsh-balance-guard 插件解决了这一问题，它通过 Host 端代理和 Client 端渲染，将余额状态直接嵌入到 Web 界面的会话头部右上角。

插件简介¶

本插件由 bunipai 维护，采用 MIT 许可证。它通过读取与 llm-deepseek 相同的凭证（默认 DEEPSEEK_API_KEY），调用 DeepSeek 官方接口获取余额信息，并实时展示在界面中。

核心功能¶

• 界面集成：在 Web 界面会话头部右上角显示余额胶囊。
• 自动刷新：客户端默认每 30 秒轮询一次；点击胶囊立即刷新；页面重新可见时也会刷新。
• 详细信息：悬停显示总额、赠送、充值明细与更新时间。
• 低余额预警：余额 ≤ 阈值（默认 ¥5）时，胶囊变橙并显示 ⚠，页面标题加「⚠ 余额不足」前缀，并弹窗系统通知。
• 通知规则：低余额事件只提醒一次，充值恢复到阈值以上后再次跌破会重新提醒。
• 首次授权：第一次点击胶囊会请求系统通知授权。

安装与启用¶

使用官方安装命令：

dsh plugin --profile web add dsh-balance-guard

安装后，运行中的 web 进程会热加载 patch 变更，刷新页面即可看到余额胶囊。

配置¶

在 profile cordis.patch.yml 中添加插件行配置，支持自定义参数：

- insert:
    - id: plugin-balance
      name: dsh-balance-guard
      config:
        apiKeyEnv: DEEPSEEK_API_KEY
        baseURL: https://api.deepseek.com
        pollIntervalMs: 30000
        cacheMs: 15000
        timeoutMs: 10000
        lowBalanceThreshold: 5
        lowBalanceCurrency: CNY

也可以在 $DSH_HOME/settings.yaml 中以 plugin-balance: 节覆盖部分配置项（如 pollIntervalMs、lowBalanceThreshold 等）。

注意事项¶

• 插件以当前 dsh 进程权限运行，需确保服务端能读取到正确的凭证。
• 错误码包括：no-api-key、invalid-api-key、api-error、transport-error、bad-response。