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）；未挂载时进程内存累计

安装

# 方式一：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()         ← 计量

• src/index.ts：插件入口（拦截 + 工具注册）
• src/prices.ts：价格表 + 峰谷逻辑 + 费用计算（纯函数，独立可测）
• src/budget.ts：预算状态与持久化（storage KV / 内存降级）

测试

pnpm test   # vitest，8 个用例覆盖计量/deny/warn/峰谷/时区

限制

• 价格为静态配置，不实时同步官方调价
• 内存降级模式下重启后累计清零
• 费用为估算值（基于 provider usage），与账单可能存在差异