ruflo-cost-tracker 成本燃烧率观测：用cost-burn追踪生产环境的日烧钱速率与漂移告警
【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo
导读
在 AI Agent 生产环境中，预算超支往往不是"突然发生"的，而是燃烧速率（burn rate）悄悄加速的结果——某个热循环（hot loop）可能让单日 LLM 开销飙到正常值的 10 倍，而传统预算检查要等到接近阈值才会报警。本文基于 ruflo 项目 ruflo-cost-tracker 插件的cost-burn技能（SKILL.md）及其实现脚本 burn.mjs，系统讲解如何把生产环境会话花费按时间窗口分桶、计算窗口间增量，并通过可配置的加速度阈值让 CI 构建在烧钱速率失控时直接失败。读完本文，你将掌握cost-burn的完整命令行参数、底层算法与边界行为，并能在自己的流水线中落地"预算无关的速率告警"。
cost-burn 在成本观测栈中的定位
ruflo-cost-tracker 将成本观测拆成了四个互补的视角，cost-burn是其中的第四块拼图，回答的是"趋势"问题：
| 要回答的问题 | 技能 | 视角 |
|---|---|---|
| "我们是否已经越过了阈值？"（反应式） | cost-budget-check | 存量检查 |
| "我们什么时候会越过阈值？"（预测式） | cost-projection | 前瞻预测 |
| "我们本可以花得更少吗？"（对比式） | cost-counterfactual | 反事实对比 |
| "日烧钱速率是否在加速？"（趋势） | cost-burn← 本文主题 | 速率趋势 |
cost-burn与同为趋势类的cost-trend有本质区别：cost-trend读取 docs/benchmarks/runs/*.json 下的基准运行数据，回答"基准测试指标（胜率、延迟）是否漂移"；而cost-burn读取cost-tracking命名空间下的会话记录，回答"生产环境花费是否在加速"。两者数据源不同、问题不同，互相补充。
前置条件：会话花费数据从哪来
cost-burn分析的数据源是cost-tracking命名空间中的session-*记录。这些记录由同插件的cost track命令（track.mjs）生产：它扫描~/.claude/projects/<编码后的工作目录>/下最近修改的会话 jsonl，逐行解析 assistant 消息的 usage 字段，按模型定价换算成 USD，聚合出包含total_cost_usd、capturedAt、endedAt、startedAt、byModel、byTier的结构化记录，再通过memory store --namespace cost-tracking --key session-<sessionId>持久化。
插件还在会话结束（Stop 钩子）时通过 hooks/hooks.json 自动触发捕获，无需手动调用。也就是说：只要插件在正常使用，
cost-burn就永远有真实数据可分析。
成本换算的定价表由 _prices.mjs 统一维护（每 1M tokens，USD）：
| 模型层级 | Input | Output | Cache Write | Cache Read |
|---|---|---|---|---|
| Haiku | $0.25 | $1.25 | $0.30 | $0.03 |
| Sonnet | $3.00 | $15.00 | $3.75 | $0.30 |
| Opus | $15.00 | $75.00 | $18.75 | $1.50 |
命令行参数与算法
参数一览
cost-burn的命令行形态为：
cost burn [--bucket 1d] [--lookback 14d] [--alert-on-acceleration-pct 50] [--format table|json]| 参数 | 默认值 | 说明 |
|---|---|---|
--bucket | 1d | 分桶窗口时长，支持N h\|d\|w\|m（小时/天/周/月），如1d、1w、6h |
--lookback | 14d | 回看窗口总时长，同样支持N h\|d\|w\|m，默认覆盖最近 14 天 |
--alert-on-acceleration-pct | 未设置 | 加速度告警阈值（百分比）。设置后，当最新桶相对历史均值的增幅超过该值时进程以退出码 1 结束 |
--format | table | 输出格式：table（Markdown 表格）或json（结构化 JSON，供 CI 与脚本消费） |
也可以直接用 Node 调用实现脚本，例如node plugins/ruflo-cost-tracker/scripts/burn.mjs --bucket 1w --lookback 90d（每周分桶、回看一个季度）。此外还支持两个环境变量：
BURN_NAMESPACE：覆盖数据源命名空间，默认cost-tracking；BURN_QUIET=1：等价于--format json，用于静默脚本化调用。
算法步骤
从 burn.mjs 的实现看，算法共五步：
- 读取会话记录：通过共享加载器 _sessions.mjs 的
loadSessions(NS)拉取cost-tracking命名空间下所有session-*键并解析 JSON； - 按窗口分桶：在
--lookback时间窗内（从当前时刻Date.now()往回数），把每条会话按时间戳落进--bucket时长的桶。桶序号从新到旧计数：index 0 是"最近一个 bucket"（now-bucketMs到now），index 1 是再往前一个，依此类推；桶数量为ceil(lookbackMs / bucketMs)； - 聚合每个桶：每个桶输出
{n: 会话数, spendUsd: Σ total_cost_usd}，即桶内会话条数与总花费； - 计算增量：
delta = 最新桶.spendUsd - mean(所有非空历史桶.spendUsd)。注意历史均值只统计非空桶（n > 0），既避免除以零，也防止稀疏历史把大量空窗口算进均值拉低基线； - 告警判定：若设置了
--alert-on-acceleration-pct N，当deltaPct > N时触发告警并以退出码 1 结束。其中deltaPct = delta / priorMean × 100。
每条会话的时间戳解析优先级为capturedAt→endedAt→startedAt（见 _sessions.mjs），保证记录字段不完整时依然能落桶。
冒烟示例解读
技能文档给出的冒烟场景是"5 天，每天 $0.10，今天 $0.50"，即 400% 加速度：
| Latest bucket spend | $0.500000 (1 sessions) | | Prior bucket mean | $0.100000 (4 non-empty buckets) | | **Delta (latest vs prior mean)** | **+$0.400000 (400.00%)** | # | Window | Sessions | Spend 0 | 2026-06-15 14:16 → 2026-06-16 14:16 | 1 | $0.500000 1 | 2026-06-14 14:16 → 2026-06-15 14:16 | 0 | $0.000000 2 | 2026-06-13 14:16 → 2026-06-14 14:16 | 1 | $0.100000 3 | 2026-06-12 14:16 → 2026-06-13 14:16 | 1 | $0.100000 ...表格按"最新在前"排列，index 0 是最近窗口；空桶（如 index 1）显示$0.000000且不计入历史均值。输出中的六个小数位精度来自源码中对金额的toFixed(6)/Math.round(x * 1e6) / 1e6归一化处理（burn.mjs）。
漂移告警退出码：让构建在烧钱加速时失败
cost-burn的核心价值在于把趋势信号变成可编程的退出码。文档中的两个对照示例：
$ cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 50 ⚠ ALERT: latest bucket $0.500000 is 400.0% above prior mean $0.100000 (threshold +50%) exit 1 $ cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 500 ✓ latest bucket within +500% of prior mean (actual delta: 400.0%) — OK exit 0语义是：阈值设 50% 表示"最新一天比历史日均值贵 50% 以上就视为失控"；设 500% 表示"贵 5 倍以内都能接受"。判定条件在源码中是deltaPct > ARGS.alertPct（严格大于，等于阈值不触发）。同时，--alert-on-acceleration-pct必须为正数（> 0），否则以退出码 2 报配置错误。
CI 集成示例
把退出码接入流水线非常简单——直接利用 shell 的短路语义：
# 当天花费相对周均值加速超过 100% 就失败构建，并呼叫值班 cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 100 || alert-oncall与预算告警的本质差异
文档特别强调："告警独立于预算——即使在总花费远低于预算时，它也会在速率加速上触发。"这正是它比cost-budget-check更早发现问题的原因：
- 预算告警是存量视角：总花费达到预算的 50/75/90/100% 才逐级报警（见 README.md 的告警阶梯）；
- 燃烧率告警是流量视角：哪怕当前总花费只占预算的一小部分，只要单日烧钱速度在飙升（例如"上线了一个烧钱是平时 10 倍的热循环"），
cost-burn会抢在预算报警之前就响起来。
边界情况与冷启动保护
文档列出了三类边界行为，源码中均有对应实现（burn.mjs）：
- 无历史基线（冷启动）：若回看窗口内不存在任何非空的历史桶，告警被跳过并输出原因字符串（
skipped (no prior non-empty buckets to compare — need ≥1)），进程正常以退出码 0 结束——避免在数据稀疏的启动阶段对运维产生误报骚扰； - 历史全为 $0、最新桶有花费：此时
priorMean === 0，deltaPct在数学上为Infinity，JSON 输出中记为null，表格中标记为new；同样不触发告警（没有基线可对比，无法判定"加速"）； --bucket大于--lookback：配置自相矛盾（例如--bucket 30d --lookback 7d），立即以退出码 2报硬错误burn: --bucket (...) cannot exceed --lookback (...)，而不是静默产出无意义结果。同理，--bucket或--lookback的时长格式非法（非N(h|d|w|m)）也以退出码 2 拒绝。
JSON 输出：供脚本与 CI 消费的结构化契约
--format json是cost-burn面向程序化消费的接口。其顶层结构（burn.mjs）包含：
| 字段 | 含义 |
|---|---|
namespace/config | 数据源命名空间与本次调用的参数快照（bucket、lookback、alertOnAccelerationPct） |
bucketsConsidered/sessionsInLookback | 桶总数与回看窗口内的会话总数 |
latest | 最新桶：windowStart/windowEnd（ISO 时间戳）、sessions、spendUsd |
priorMean | 历史均值：参与统计的非空桶数量bucketsConsidered与meanSpendUsd |
delta | deltaUsd与deltaPct（不可计算时为null） |
series | 逐桶数组：每个桶的bucketIndex、窗口起止、sessions、spendUsd |
alert | 告警对象：triggered、reason、thresholdPct；未设置阈值时为null |
generatedAt | 生成时间 |
下游可以这样消费：
# 最新桶相对历史均值加速超过 100% 时，构建失败 cost burn --bucket 1d --lookback 7d --alert-on-acceleration-pct 100 --format json \ | jq -e '.alert.triggered == true'质量保障：冒烟测试中的契约
插件把"burn 技能存在且实现正确"固化进了结构化的冒烟测试 smoke.sh，其中 step 39d 逐一断言：burn.mjs可执行、语法合法、通过受审的_sessions.mjs共享加载器做安全的外部调用、包含bucket/lookback/alert-on-acceleration-pct三个参数、实现priorMean/priorNonEmpty逻辑、具备process.exit(1)（失败关闭）与process.exit(2)（配置错误）两条退出路径；技能文档本身也必须引用burn.mjs、包含 drift / acceleration / burn-rate 概念关键词与alert-on-acceleration-pct参数说明。验证方式：
bash plugins/ruflo-cost-tracker/scripts/smoke.sh预期输出44 passed, 0 failed。这也提醒使用者：cost-burn不是一次性脚本，而是被 CI 契约锁定的插件能力，改动其行为会直接被冒烟测试拦截。
小结
cost-burn用"分桶 → 窗口间增量 → 加速度告警"三步，把生产环境的烧钱趋势变成可观测、可告警、可进 CI 的信号。它和预算检查互补：预算回答"还剩多少"，燃烧率回答"正在以什么速度烧、是否在失控"。对于运行多 Agent 工作流的团队，建议在预算阶梯之外至少配一条--alert-on-acceleration-pct的燃烧率门禁——它专治"预算没超但速率已经失控"这类最危险的中期故障。
延伸阅读
- cost-burn 技能定义 — 本文依据的原始文档
- burn.mjs 实现 — 算法与退出码的完整源码
- _sessions.mjs 共享加载器 — 会话读取与时长解析的统一入口
- track.mjs 数据生产端 —
session-*记录从 jsonl 到命名空间的写入流程 - ruflo-cost-tracker README — 全部 23 个子命令与定价/预算/联邦集成总览
- cost-trend 技能 — 与
cost-burn互补的基准漂移分析 - 冒烟测试 — 对 burn 技能契约的自动化断言
【免费下载链接】ruflo🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
