预算卫士 haoku123/dsh-budget-guard

dsh-budget-guard

DeepSeek Harness 插件：LLM 成本计量 + 预算执行（超预算硬拦截），支持 DeepSeek 峰谷定价。

与其他「只显示数字」的成本插件不同，本插件在 llm/stream 调用层执行预算：超出日/月/总预算时直接拦截模型调用，而不只是弹一个红条。

功能

- 用量计量：包装 llm/stream waterfall，观察 provider usage（input / output / cache），跨会话累计
- 费用计算：内置 DeepSeek 价格表，按模型计费（USD）
- 峰谷定价：感知 DeepSeek 峰谷时段（北京时间 9:00–12:00、14:00–18:00 为高峰，其余半价），按调用时刻计价
- 预算执行：
- deny（默认）：超预算硬拦截 agent-loop 调用，抛 BUDGET_EXCEEDED（LlmError），loop 走 request-error 流程
- warn：只记录不拦截
- 内部调用（compaction、标题生成等，无 sessionId）永不拦截，避免死锁
- budget_status 工具：模型/用户可查询当前用量与剩余预算
- 持久化：可选接入 storage 服务（json KV）；未挂载时进程内存累计
- 仪表盘：shell.overlay 角落常驻面板（5s 轮询），见下

仪表盘

面板把已经在记的数据变成可判断的信息，而不只是三个累计数字：

| 区块 | 内容 |
| 主视觉 | 今日消耗环形进度（占日预算百分比）+ 大号金额 + 剩余额度 |
| 24h 趋势 | 每小时花费柱状图，高峰时段着黄色，当前小时描边 |
| 其他周期 | 本月 / 总计进度条，80% 处有警戒刻度，无限额显示虚线轨道 |
| 洞察 | 消耗速率（$/h）、触限预测、缓存命中率与省下金额、当前时段单价与折扣 |

几个刻意的设计：

- 消耗速率只统计已走完的整小时。当前小时还在累积，算进去会让数字每次轮询都跳。
- 被拦截时不显示花费预测。deny 模式下调用已经发不出去了，今日预计 $12.81 描述的是不可能发生的开销；这时显示的是「明日 00:00（12.6 小时后）」这类恢复时间。总预算耗尽则明说需要调高上限——等到明天也不会自动恢复。
- 峰谷时段由 host 返回的两组单价比值推导，不由浏览器时钟计算。计价窗口是北京时间，用本地时钟判断会让 UTC+8 以外的用户看到错误时段。
- 任何非零消耗都保证有可见填充（下限 1.5%）。$0.03 / $5 是 0.6%，按真实比例渲染会得到 0 像素宽的条——面板退化成几行文字，看起来像坏了。百分比数字仍按真实值显示。
- 缓存节省是估算：按 list price 的 input/cachedInput 差价反推，而非逐次调用的实际计费，所以只保留两位小数。

安装

方式一：npm（推荐）
npm install dsh-budget-guard

方式二：dsh 插件命令
dsh plugin --profile web add "github:haoku123/dsh-budget-guard#main"

方式三：本地开发
git clone https://github.com/haoku123/dsh-budget-guard.git
cd dsh-budget-guard
npm install --legacy-peer-deps
npm run build
pnpm dsh web --patch ./cordis.patch.yml

配置

见 cordis.patch.yml 示例。默认价格基于 DeepSeek 官方公告（峰价，USD/1M tokens），可通过 prices.models 覆盖。

架构

llm/stream waterfall
├── store.check() → deny? → 抛 LlmError(BUDGET_EXCEEDED) ← 预算执行 └── meterStream() → 观察 usage chunk → store.record() ← 计量

GET /dsh-budget-api/status → { status, history, budget, prices, pricing }
│ └ list + effective 单价 └ 近 24 个小时桶（含空桶）

- src/index.ts：插件入口（拦截 + 工具注册 + status 路由）
- src/prices.ts：价格表 + 峰谷逻辑 + 费用计算（纯函数，独立可测）
- src/budget.ts：预算状态与持久化（storage KV / 内存降级）+ 小时桶趋势
- src/client.tsx：仪表盘组件

记账分四个 scope：d: 日、m: 月、t:total 总计、h: 小时。前三个永久累计；小时桶只为趋势图存在，保留 48 小时后裁剪——每天 24 条，不设上限会无限增长。deleteRecord 在 storage 后端是可选的，所以内存里一定裁剪，落盘行删不掉也无所谓：connect 加载时会用同一个窗口过滤，过期桶不会复活。

测试

npm test # vitest：host 17 用例（计量/deny/warn/峰谷/时区/小时桶/status 契约）
+ client 18 用例（渲染/趋势/洞察/拦截态/低占用可见性）

限制

- 价格为静态配置，不实时同步官方调价
- 内存降级模式下重启后累计清零（趋势图同样清零）
- 费用为估算值（基于 provider usage），与账单可能存在差异
- 触限预测按近 3 小时均速线性外推，不预测使用模式变化