花费熔断 summmmerz/dsh-spend-guard

dsh-spend-guard

DeepSeek Harness 的滚动窗口花费熔断（宿主侧插件）。

最近 10 分钟内的花费达到 ¥1 → 弹 Windows 通知提醒；达到 ¥2 → 结束当前这一轮（等同你按 GUI 的「停止」按钮）。

为什么需要它

- dsh 核心没有任何花费/步数上限开关。
- dsh-cost-meter 的「预算」是展示型的：只有 今日/本月/累计/自定义区间 四种周期，行为仅限于 ≥80% 预警、≥100% 超支时变色，不会暂停任务。
- 插件市场里也没有「滚动分钟窗口 + 金额 + 停当前轮」的组合（dsh-budget 是 会话/日/月 + USD 且 peer 范围写死 <0.2.0； dsh-balance-tracker 单位是元、动作是取消当前回合，但窗口是自然日，且依赖 dsh 0.2.0 已移除的 0.1.x 客户端包）。

它怎么算钱

不自己定价，而是轮询差分 dsh-cost-meter 的账本（<DSH_HOME>/storages/cost-meter/ledger.json）：

1. 每 pollMs（默认 10s）读一次账本；
2. 对当天聚合值 days[<日期>].cost 求相对上次轮询的增量；
3. 增量按采样时刻塞进环形窗口，窗口内求和即为「最近 N 分钟花了多少」；
4. 金额口径跟随账本：pricingCurrency（默认 USD）× 账本自己的 config.exchangeRate （默认 7.2）= 人民币元，与 dsh-cost-meter 界面上的数字同源。

⚠️ 为什么不用 per-session 明细（踩过的坑）

账本里 days[日期].sessions[] 是「每个会话当天的累计值」，且在重负载日会截断。
实测 2026-10-04 那次事故当天：该数组只保留 200 条、仅覆盖当天 42% 的花费 （33.95 / 81.17 元），缺口 47.2 元全是子代理消耗 —— 那天正是一次 workflow 工具扇出 383 个子代理烧掉的。

所以按条目差分会漏掉本插件最该拦住的那类事故。当天聚合值在任何负载下都是完整口径（含子代理），因此只信它。test/window.test.mjs 里有两条回归测试锁住这个行为（sessions 为空、以及条目被替换/截断时，窗口仍必须计数）。

代价：检测延迟最多约 pollMs + cost-meter 的落盘间隔（默认各 10s）。
对一个 10 分钟窗口的熔断来说不影响使用。

降级：账本读不到（未装 cost-meter、格式变动、权限问题）时不熔断，只每 5 分钟打一条警告日志 —— 算不出钱的守卫不应该把 harness 弄死。

它怎么停

agent.cancel({ kind: 'user' }, { keepInbox: true })

与 GUI「停止」按钮完全同一条路径（见 dsh-api-session-controller 的 stop 实现）：只结束当前回合，不销毁会话，已排队的输入保留。

默认会结束所有正在运行的 agent（含子代理）—— 熔断的目的是立刻止血，子代理同样在烧钱（2026-10-04 那次 47 元几乎全在子代理上）。用 cancelScope: root 可只结束主会话。

配置

默认值可通过 profile 的 cordis.patch.yml 覆盖：

- id: dsh-spend-guard
config:
windowMs: 600000 # 滚动窗口(ms)，默认 10 分钟 warnYuan: 1 # 窗口内达到该金额(元) → 提醒 stopYuan: 2 # 窗口内达到该金额(元) → 结束当前回合 pollMs: 10000 # 账本轮询间隔(ms) field: cost # cost(含订阅折算) | apiCost(纯 API 口径) exchangeRate: null # 汇率覆盖；null = 用账本的 config.exchangeRate warnCooldownMs: 60000 # 两条提醒之间的最小间隔(ms) stopCooldownMs: 60000 # 两次熔断之间的最小间隔(ms)；0 = 超限就一直熔断 cancelScope: all # all=结束所有在跑的 agent(含子代理) | root=只结束主会话 toast: true # 是否发 Windows 通知 debug: false # 每次轮询打印窗口金额 ledgerPath: "" # 账本路径；留空=自动定位

禁用整行：

- id: dsh-spend-guard
disabled: true

日志

[dsh-spend-guard] 已启用: 滚动 10 分钟, 提醒 ¥1.00 / 熔断 ¥2.00, 账本 <path> [dsh-spend-guard] 提醒: 最近 10 分钟已花 ¥1.44(停止阈值 ¥2.00)。
[dsh-spend-guard] 熔断: 最近 10 分钟已花 ¥2.16(阈值 ¥2.00)，已结束当前回合。(被结束的 agent 数: 1)

用 提醒: / 熔断: 两个标记即可 grep。

测试

node test/window.test.mjs

用合成账本驱动真实的 apply()，覆盖：首次轮询只建基线、按当天聚合增量而非累计、 1 元提醒 / 2 元熔断、sessions[] 为空或被截断时仍必须计数（回归）、跨日新日期不误熔断、聚合值回退不作负增量、cancelScope 语义、以及熔断必须走 cancel({kind:'user'}, {keepInbox:true})。

已知边界

- 依赖 dsh-cost-meter 在跑并持续落盘；它没启用时本插件静默不生效（只记日志）。
- 窗口精度受轮询间隔限制（默认 ~10-20s）。
- 只统计 dsh 自己计到的花费；在别处（其他终端/网页）产生的消费不在窗口内。
- 熔断会结束所有在跑的回合（默认，含子代理）；如果你同时跑多个无关会话且不希望被连带中断，设 cancelScope: root。