dsh-balance-guard · API 余额守卫

DeepSeek Harness 插件：在底部状态条（1 轮 · 1 步 | LLM 3.8s | … 那一行）实时显示你的 API 余额（人民币）；余额低于自定义阈值时暂停模型输出，并自动跳转充值页。

功能

• 🪙 状态条余额：每 5s 刷新显示 余额 ¥xx.xx（正常绿色 / 低于阈值红色 ⚠）
• 💸 本会话花费（自动计费）：本会话 -¥x.xx = API 余额减少量，每次刷新自动重算，无需手动设置价格；余额上升（充值）自动校正基线，不会把充值算成花费；token 明细在悬停提示里
• 🛑 暂停输出闸门：余额 < 阈值时拦截 llm/stream，所有新模型调用直接失败、不再产生 token；用户消息不会被吞（错误会显示在会话里，说明原因）
• 🔗 自动跳转充值页：余额从正常跌破阈值的瞬间自动 window.open 充值页（被弹窗拦截时也有醒目「去充值」按钮）
• ⚙ 设置弹窗：阈值（¥）、充值页 URL、手动 API Key、启用开关、重置本会话计费基线——保存后持久化到 $DSH_HOME/balance-guard.json
• ⏸ 临时解除：低余额期间点「临时解除」可继续输出（下次成功查到余额仍低会重新暂停）；点「我已充值」立即重查余额
• 🔑 Key 解析顺序：设置里手动填的 Key > credentials 服务（DEEPSEEK_API_KEY）> 环境变量
• 📑 通用设置页：阈值、充值页 URL、闸门开关与「重置本会话计费基线」也同步出现在 设置 → 通用 → 余额守卫 区块，无需在状态条上找 ⚙

自动计费原理（v2：全局账本 + 会话起点快照）

• 宿主维护一个全局账本 {基线余额, 上次余额, 累计花费}：每次观测到新余额只结算一次（余额下降 → 全局花费；上升 → 抬升全局基线，充值不计花费），持久化在 $DSH_HOME/balance-guard-usage.json（重启不丢）
• 每个会话首次出现时记录起点快照（当时的全局花费）；本会话花费 = 当前全局花费 − 起点值——只展示自己区间内的真实花费，多个会话并行轮询不会重复记账（v1 的 per-session 归属会把同一笔消耗记给每个会话，已废弃）
• 点「重置本会话计费」= 把起点快照移到当下（从此刻起的花费才计入本会话）
• 精度 = 余额接口精度（¥0.01）；v1 旧账本因重复记账不可信，升级后自动从当前余额重新起算

安装

# 热装配进 profile（本仓库已做）：
dev_install_package(dir="F:\Dstest\dsh-balance-guard", profile="web")
# 浏览器刷新页面后生效；重启后由 profile bundles 正常装配

配置（默认值）

项	默认	说明
threshold	10	余额阈值（¥），低于即暂停输出
rechargeUrl	https://platform.deepseek.com/top_up	充值页
baseUrl	https://api.deepseek.com	余额 API base（GET {base}/user/balance）
enabled	true	暂停闸门开关
pollSeconds	60	宿主侧余额轮询周期

运行时修改通过状态条里的 ⚙ 弹窗完成；patch 配置（cordis.patch.yml）在重启装配时生效，JSON 文件优先级更高。

安全说明

• 手动填写的 API Key 会以明文存入 $DSH_HOME/balance-guard.json（本机单用户工具；介意的话请留空走环境变量/凭据）
• /balance-guard/* HTTP 接口永不返回密钥
• 查询失败时保留上次"已确认低余额"判定（fail-closed）；从未确认过低余额时查询失败不暂停（fail-open）

目录结构

dsh-balance-guard/
├── package.json        # dsh.bundle.patch + dsh.client 声明（bundle 形态）
├── cordis.patch.yml    # 挂载声明：insert entry balance-guard
├── lib/
│   ├── index.js        # 宿主半侧：余额轮询 + llm/stream 闸门 + /balance-guard API
│   └── client.js       # 浏览器半侧：状态条单元格 + 设置弹窗（__ModuleLoader__）
└── README.md

更新日志

v1.1.0（2026-08-16）

• 记账 v2（修复重复记账）：余额差额结算从"按会话归属"改为全局账本单点结算；本会话花费 = 全局花费 − 会话起点快照。修复 v1 下多个会话并行轮询时同一笔消耗被每个会话各记一次、合计远超真实花费的问题（实测 9 个会话把 ¥17 真实消耗放大成 ¥153.31）
• 充值抬基线逻辑移至全局层；/usage-reset 改为重置会话起点快照
• 持久化格式升级为 {global, sessions}，v1 旧账本自动作废、从当前余额重新起算

v1.0（2026-08-16）

• 状态栏余额 + 低余额暂停闸门 + 自动跳转充值页
• 本会话花费（余额差额法）、/totals 聚合、诊断字段