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。
