Back to Details

cost-budget-check

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Cost Budget Check

成本预算检查

Reads 
cost-tracking:budget-config
for the project's budget limit, sums 
total_cost_usd
across 
session-*
records produced by 
cost-track
, computes utilization, and emits the measured 4-tier alert ladder (50% INFO / 75% WARNING / 90% CRITICAL / 100% HARD_STOP).
Until P2 (this skill) landed, the README documented the alert ladder but no code checked it. Now this skill is the gate.
读取项目的
cost-tracking:budget-config
配置获取预算限额，汇总
cost-track
生成的
session-*
记录中的
total_cost_usd
总额，计算利用率，并触发实测的四级阶梯警报（50% INFO / 75% WARNING / 90% CRITICAL / 100% HARD_STOP）。
在P2（该skill）落地之前，README中仅记录了警报阶梯，但没有代码实现检查逻辑。现在这个skill是管控的核心。

When to use

使用场景

  • After every cost-track run, to surface the alert level.
  • Before spawning a swarm — if utilization ≥ 90%, escalate to 
    /cost-optimize
    first.
  • Cron-friendly via 
    /loop 30m
    for continuous monitoring.
  • 每次cost-track运行后，用于显示警报等级。
  • 在启动swarm之前——如果利用率≥90%，需先调用
    /cost-optimize
    进行优化。
  • 通过
    /loop 30m
    实现定时任务，支持持续监控。

Steps

操作步骤

  1. Run the check:
    bash
    node plugins/ruflo-cost-tracker/scripts/budget.mjs check
    Filter by period: 
    BUDGET_PERIOD=today
    (default 
    all
    ). Use 
    BUDGET_QUIET=1
    for machine-readable JSON.
  2. Inspect the markdown summary — budget, spent, remaining, utilization percentage, alert level (🟢 OK · 🟡 INFO · 🟠 WARNING · 🔴 CRITICAL · 🛑 HARD_STOP), and the recommended action.
  3. Set / inspect the budget:
    bash
    node plugins/ruflo-cost-tracker/scripts/budget.mjs set 50.00
node plugins/ruflo-cost-tracker/scripts/budget.mjs get
  4. HARD_STOP path — 
    budget.mjs check
    exits with code 
    1
    when utilization ≥ 100%. Wrap critical agent spawns in a 
    budget.mjs check && spawn …
    guard to fail closed.
  1. 执行检查：
    bash
    node plugins/ruflo-cost-tracker/scripts/budget.mjs check
    按时间段筛选：
    BUDGET_PERIOD=today
    （默认值为
    all
    ）。使用
    BUDGET_QUIET=1
    可输出机器可读的JSON格式。
  2. 查看Markdown摘要——包含预算金额、已支出金额、剩余金额、利用率百分比、警报等级（🟢 正常 · 🟡 INFO · 🟠 WARNING · 🔴 CRITICAL · 🛑 HARD_STOP），以及推荐操作。
  3. 设置/查看预算：
    bash
    node plugins/ruflo-cost-tracker/scripts/budget.mjs set 50.00
node plugins/ruflo-cost-tracker/scripts/budget.mjs get
  4. HARD_STOP流程——当利用率≥100%时，
    budget.mjs check
    将以退出码
    1
    终止。可将关键agent的启动逻辑包装为
    budget.mjs check && spawn …
    ，确保在超预算时停止执行。

Storage shape (
cost-tracking:budget-config
)

存储结构（
cost-tracking:budget-config
）

json
{
  "budget_usd": 50.00,
  "setAt": "2026-05-05T...",
  "thresholds": { "info": 0.50, "warning": 0.75, "critical": 0.90, "hard_stop": 1.00 }
}
json
{
  "budget_usd": 50.00,
  "setAt": "2026-05-05T...",
  "thresholds": { "info": 0.50, "warning": 0.75, "critical": 0.90, "hard_stop": 1.00 }
}

Alert ladder (from REFERENCE.md, now enforced)

警报阶梯（来自REFERENCE.md，现已强制执行）

ThresholdLevelAction
50%INFO 🟡log notification, no UX disruption
75%WARNING 🟠display warning, suggest 
/cost-optimize
90%CRITICAL 🔴urgent alert, recommend model downgrades
100%HARD_STOP 🛑halt non-essential spawns; exit code 1
阈值等级操作
50%INFO 🟡记录通知，不影响用户体验
75%WARNING 🟠显示警告，建议调用
/cost-optimize
90%CRITICAL 🔴紧急警报，推荐降级模型
100%HARD_STOP 🛑暂停非必要的agent启动；退出码1

Cross-references

交叉引用

  • cost-track
    (producer) — populates 
    cost-tracking:session-*
  • cost-report
    — same data source, narrative format
  • cost-optimize
    — recommended action when WARNING/CRITICAL
  • REFERENCE.md "Budget alert thresholds" — the documented ladder this enforces
  • cost-track
    （数据生成方）——填充
    cost-tracking:session-*
    数据
  • cost-report
    ——使用同一数据源，生成叙事格式报告
  • cost-optimize
    ——当触发WARNING/CRITICAL时的推荐操作
  • REFERENCE.md中的“预算警报阈值”——本工具强制执行的文档化阶梯规则