dsh-balance-guard · 余额哨兵

DeepSeek Harness 插件:在 Web 界面会话头部右上角实时显示 DeepSeek API 账户余额,余额不足自动变橙提醒(标题标记 + 系统通知)。

• Host 端注册同源端点 GET /api/dsh-plugin-balance,服务端读取与 llm-deepseek 相同的凭证(默认 credential ref DEEPSEEK_API_KEY,即 $DSH_HOME/.credentials.yaml 或环境变量),调用 https://api.deepseek.com/user/balance(15 秒缓存、单飞)。
• Client 端把余额胶囊渲染到 conversation.session.header.utilities — 会话头部右上角(状态圆点 + 金额)
• 客户端默认每 30 秒轮询一次;点击胶囊立即刷新;页面重新可见时也会刷新。 悬停显示总额 / 赠送 / 充值明细与更新时间。
• 低余额自动提醒:余额 ≤ 阈值(默认 ¥5)时,胶囊变橙并显示 ⚠,页面标题加 「⚠ 余额不足」前缀,并弹一条浏览器系统通知(每个低余额事件只提醒一次,充值 恢复到阈值以上后再次跌破会重新提醒)。第一次点击胶囊会请求系统通知授权。

配置

插件行配置(profile cordis.patch.yml,或通过 llm 同款设置节):

- insert:
    - id: plugin-balance
      name: dsh-balance-guard
      config:
        apiKeyEnv: DEEPSEEK_API_KEY   # credential ref
        baseURL: https://api.deepseek.com  # 可用 $DEEPSEEK_BASE_URL 覆盖
        pollIntervalMs: 30000         # 客户端轮询间隔
        cacheMs: 15000                # 服务端缓存
        timeoutMs: 10000              # 上游请求超时
        lowBalanceThreshold: 5        # 低余额提醒阈值
        lowBalanceCurrency: CNY       # 阈值比较的币种

也支持在 $DSH_HOME/settings.yaml 里以 plugin-balance: 节覆盖 pollIntervalMs / cacheMs / timeoutMs / lowBalanceThreshold / lowBalanceCurrency。

安装

dsh plugin --profile web add dsh-balance-guard
# 或本地目录:
dsh plugin --profile web add file:/path/to/dsh-balance-guard

运行中的 web 进程会热加载 patch 变更(host 插件即时生效),刷新页面即可看到胶囊。

端点响应

{
  "ok": true,
  "value": {
    "isAvailable": true,
    "balanceInfos": [
      { "currency": "CNY", "totalBalance": "110.00",
        "grantedBalance": "10.00", "toppedUpBalance": "100.00" }
    ],
    "lowBalance": {
      "active": false,
      "currency": "CNY",
      "threshold": 5,
      "amount": "110.00"
    },
    "updatedAt": 1755012345678
  },
  "pollIntervalMs": 30000
}

错误时 ok: false + error.code:no-api-key | invalid-api-key | api-error | transport-error | bad-response。