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 小时均速线性外推，不预测使用模式变化
