ruflo 成本健康门禁（cost-health）完全指南：四路并行预算检查与 CI 集成

ruflo 成本健康门禁（cost-health）完全指南：四路并行预算检查与 CI 集成

【免费下载链接】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

ruflo-cost-tracker 插件的cost-health技能是操作上最实用的复合型 CI 门禁：它把 budget（预算）、burn（燃烧速率）、anomaly（异常会话）、projection（预算耗尽预测）四个独立告警阶梯并行运行，只做一次 shell-out 就返回一个合并的健康状态与max(exit_codes)。本文以 cost-health 技能文档 为主体，结合 health.mjs 及其四个子检查脚本的源码实现，完整讲解其算法、参数、退出码语义、CI 接入方式与阈值定制技巧。读完你将能在一个 CI 步骤内同时覆盖"是否超支、燃烧是否加速、是否存在异常会话、何时耗尽预算"四类告警，并理解每个告警背后的统计原理与边界情况。

为什么需要 cost-health：四个问题，一次门禁

cost-tracker 的四条 CI 门禁技能各自回答一个不同的问题，单看任何一条都不足以构成完整的成本健康视图：

cost-health把它们组合起来：并行运行全部四条检查，返回max(exit_codes)，每个检查打印一行摘要。这样四条告警阶梯只触发一次门禁，避免了分别接四条 CI gate 时重复的 npx + memory-list 开销。在 health.mjs 的头部注释中，作者把这四条腿分别标注为 reactive（budget-check）、trend（burn）、point（anomaly）、predictive（projection），合在一起才构成完整的开销健康图景。

从源码结构看，README.md 中把cost-health描述为"Composite CI gate — runs budget+burn+anomaly+projection in parallel, returns max(exit)"，而各子检查的完整独立用法仍可通过cost <check>单独调用——健康门禁失败后，输出末尾会提示_Run \cost ` for the full detail of any failing leg._` 以便逐腿深入排查。

核心算法：Promise.all 并行与合成退出码

cost-health的实现集中在 scripts/health.mjs，算法流程如下：

1. 并行派生四个子检查脚本——health.mjs 通过Promise.all聚合child_process.spawn的异步结果，每个子进程内部再各自完成一次 npx CLI shell-out；
2. 每个子检查以--format json输出，由runScript用正则/\{[\s\S]*\}/从 stdout 提取 JSON 主体并解析，同时捕获退出码（见 health.mjs）；
3. projection本身没有内建退出码——由调用方根据daysUntilReached[100%] < --alert-days-to-exhaust合成（见 health.mjs）：
   • 从 projection 的 JSON 中取出budget.exhaustion数组中thresholdPct === 100的条目；
   • 若daysUntilReached小于阈值则置exitCode = 1，否则为 0；
   • 未配置预算或没有数据时按"OK"处理（exit 0）；
4. 最终退出码取max(subcheck exits)——health.mjs 与 health.mjs 中process.exit(maxExit)保证任何一个子检查失败都导致整个门禁失败；
5. 按每个检查打印一行摘要，外加✓ HEALTHY/⚠ UNHEALTHY总徽章。

值得注意的实现细节：runScript通过jsonViaEnv参数处理两种 JSON 输出机制——大多数脚本接受--format json参数，而budget.mjs使用位置子命令 +BUDGET_QUIET=1环境变量来输出 JSON（见 health.mjs）。此外，若子进程 spawn 本身失败（如脚本文件缺失），会得到退出码 127 并附带错误信息（见 health.mjs）。

命令参数与阈值定制

参数一览

参数解析逻辑见 health.mjs：默认值在解析前初始化，--skip会 split 逗号并 trim 后放入Set，后续组装子检查任务时逐个判断跳过（见 health.mjs）。

阈值定制示例

# 季度复盘——更严格的阈值 cost health --alert-acceleration 50 --alert-outliers 1 --alert-days-to-exhaust 30 # 生产漂移门禁——只在剧变时触发 cost health --alert-acceleration 200 --alert-outliers 3 --alert-days-to-exhaust 7 # 冒烟测试期间跳过较慢的 burn 检查 cost health --skip burn

CI 集成：一个步骤覆盖四条告警阶梯

- name: Cost health gate run: cost health --alert-acceleration 100 --alert-outliers 1

在引入该技能之前，需要分别接四条门禁，每条都要重复承担 npx + memory-list 的开销；现在只需一次 shell-out，且四个子检查的 npx 调用在内部并行执行。

环境变量

cost-health还支持三个环境变量，供 CI 场景精细化控制：

四个子检查的底层原理

budget：反应式预算检查

budget子检查对应 scripts/budget.mjs 的check子命令：读取cost-tracking:budget-config中的预算上限，对session-*记录的total_cost_usd求和，计算利用率后输出四级告警阶梯——50% INFO 🟡 / 75% WARNING 🟠 / 90% CRITICAL 🔴 / 100% HARD_STOP 🛑（见 budget.mjs）。

配置存储结构（cost-tracking:budget-config）如下：

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

告警阶梯（由 REFERENCE.md 文档化、被该技能强制执行）：

HARD_STOP 路径的关键实现：budget.mjs check在利用率 ≥100% 时process.exit(1)（见 budget.mjs），并且该退出必须在BUDGET_QUIET=1和普通输出两个分支都执行——这是曾导致复合门禁失效的 iter-75 缺陷修复点。可以把关键 agent 的 spawn 包进budget.mjs check && spawn …来 fail-closed。若未配置预算，返回{ error: 'no budget configured', totalSpend, recordCount }，健康门禁中显示为"unknown — no budget configured"。

burn：燃烧速率趋势

burn对应 scripts/burn.mjs：把cost-tracking中的 session 记录按--bucket时长（默认1d）分桶，统计--lookback（默认14d）窗口，每个桶得到{n, spendUsd}；随后计算delta = latest.spendUsd - mean(prior non-empty buckets)（见 burn.mjs），当--alert-on-acceleration-pct N设置且deltaPct > N时退出码 1（见 burn.mjs）。

关键特性：

• 告警与预算无关——即使在预算范围内，只要速率加速就触发，能在"烧掉 10 倍正常量"的预算警报响起之前先抓住热点循环；
• 与cost-trend区分：cost-trend读docs/benchmarks/runs/*.json回答"基准是否漂移"，cost-burn读cost-tracking命名空间回答"生产开销是否加速"；
• 边界情况：无历史非空桶时跳过告警并给原因（exit 0，避免冷启动误报）；先前桶全为 $0 而最新桶 >0 时 delta 为Infinity/null，表格中标记为new且不告警；--bucket大于--lookback时直接报错退出码 2。

anomaly：基于 MAD 的逐会话离群点检测

anomaly对应 scripts/anomaly.mjs：先过滤--since窗口（默认全量），计算median(total_cost_usd)与MAD = median(|x - median|)，然后对每个会话算 Iglewicz-Hoaglin (1993) 修正 z 分数：

z = 0.6745 * (x - median) / MAD

|z| > --threshold（默认 3.5）的会话被标记为离群点；--alert-on-outliers N使离群数 ≥ N 时退出码 1。

为什么用 MAD 而不用均值+标准差？cost-anomaly 技能文档 给出了对比：一个 $50 的会话会同时把均值和标准差撑大，后续离群点反而藏进"新常态"区间；而中位数与 MAD 两者都最多忽略 50% 的数据，离群点本身无法移动它们，在小样本（n=10）上依然稳健。该文档还列出了四个边界情况：n < 3时提示"数据不足"并 exit 0；MAD = 0时输出解释而非除零崩溃；低方向（low）离群点通常是崩溃或丢弃的会话而非超支；MAD 极小时微小偏差也会产生巨大 z 分（$5 离群点在 MAD=$0.01 下 z=330 是正确行为而非 bug）。输出表格专门带Direction列（high/low），帮助运维正确解读。

projection：前向预算耗尽预测

projection对应 scripts/projection.mjs：从cost-tracking读取 session 记录，过滤到测量窗口（默认最近 7 天），计算每日燃烧率windowSpend / windowDays，线性外推到 7d/30d/90d/365d 四个默认水平线；若配置了预算，则额外计算"按当前速率达到 75% / 90% / 100% 消耗的天数"，对已越过的阈值打上ALREADY REACHED标记。其参数包括--window <Nh|Nd|Nw|Nm>（默认7d）、--horizons <csv>（默认7d,30d,90d,365d）、--format table|json，以及环境变量PROJECTION_NAMESPACE与PROJECTION_QUIET=1。

使用时机：金融/SRE 规划（把 JSON 交给预算仪表盘回答"本季度是否在正轨上"）；CI 门禁（cost-projection --format json | jq '.budget.exhaustion[2].daysUntilReached < 7'在 100% 耗尽不足一周时让构建失败）；负载迁移后的 sanity check。注意其线性外推基于平稳性假设——文档页脚提示在工作负载变化后应重新运行。

跳过子检查（--skip）

cost health --skip burn,projection # 只跑 budget + anomaly

适用场景：

• 子检查不适用（未设置预算 → 跳过 projection）；
• 子检查对快速反馈场景太慢（如冒烟测试）；
• 子检查已被独立 CI 门禁覆盖。

跳过后输出末尾会追加一行_Skipped: burn, projection_标注。

退出码语义：worst signal wins

max()意味着最坏信号胜出——退出码 2（配置错误）总是压过退出码 1（告警），这样你就能在错误配置的流水线伪装成健康状态之前及时发现它。每个子检查若 spawn 失败（如脚本缺失）也会被归一化为 127（见 health.mjs）。

冒烟实测：5 个健康会话 + 1 个离群点

技能文档中给出的冒烟实录直观展示了输出形态：

# Healthy Overall: ✓ HEALTHY (max exit code 0) | Check | Status | Detail | | budget | ✓ | unknown — no budget configured | | burn | ✓ | delta within ±100% | | anomaly | ✓ | 0 outliers — under threshold ≥1 | | projection | ✓ | no budget configured — skipping | # After adding $5 outlier (vs $0.10 baseline) Overall: ⚠ UNHEALTHY (max exit code 1) | burn | ⚠ | ALERT 5163.2% acceleration: latest bucket $5.00 is 5163.2% above prior mean $0.095 | | anomaly | ⚠ | ALERT 1 outlier (|z|>3.5) |

可以看到：budget与projection在未配置预算时按通过处理，而burn（5163.2% 加速）与anomaly（1 个离群点）共同把门禁推向 UNHEALTHY——这正是 max 语义的直观体现。对应子检查的 smoke 实录分别记录在 cost-budget-check/SKILL.md、cost-burn/SKILL.md、cost-anomaly/SKILL.md 与 cost-projection/SKILL.md 中。

集成测试：跨脚本契约如何被验证

复合门禁的风险在于"每个子检查单独通过、组合起来却错"——这正是历史上发生过的问题。test-health-integration.mjs 的头部注释记录了 iter-75 的经典测试金字塔缺口：BUDGET_QUIET=1模式曾静默吞掉 HARD_STOP 退出码，导致cost-health派生的 budget.mjs 在该模式下返回 exit 0。单文件的源码级 grep 冒烟无法验证跨脚本契约，因此该集成测试用合成 fixture 端到端跑通复合逻辑，断言每个子检查的信号都能正确传导到 cost-health 的退出码。运行方式：

node plugins/ruflo-cost-tracker/scripts/test-health-integration.mjs # TEST_HEALTH_KEEP_FIXTURE=1 保留 .swarm fixture 以便调试

退出码 0 表示全部断言通过，1 表示至少一个断言失败，2 表示 fixture 搭建错误（通常为 CI 中 CLI 不可用）。这也解释了 budget.mjs 中那句重要注释：HARD_STOP 退出必须在BUDGET_QUIET=1与普通输出两个分支都执行，否则复合门禁会在静默模式下失效。

与 cost-tracker 生态的配合

cost-health处于 README.md 技能矩阵中"复合 CI 门禁"的位置，上游数据由cost-track技能自动从 Claude Code jsonl 捕获进cost-tracking命名空间（session-*记录），cost-budget-check负责写budget-config。四腿之外还有互补技能：cost-counterfactual（对比基线回答"本可以花得更少吗"）、cost-diff（PR 级回归检测）、cost-session（单会话内逐消息钻取，配合 anomaly 定位 $16 大额消息）、cost-export（Prometheus textfile / webhook 外发观测）。命名空间遵循 ruflo-agentdb 的 kebab-case<plugin-stem>-<intent>约定，经memory_*工具族按命名空间路由。整个插件的回归契约是 scripts/smoke.sh，期望输出 "44 passed, 0 failed"。

小结

cost-health的设计哲学是"一次 shell-out，覆盖四条告警阶梯"：反应式的预算检查、趋势型的燃烧加速、点状的离群会话、预测性的耗尽倒计时，通过Promise.all并行派生、max(exit_codes)聚合、逐腿 JSON 摘要与 HARD_STOP/加速/离群/倒计时四级合成退出码，把成本治理真正落到 CI 门禁层面。理解其四个子检查的统计基础（四级阈值阶梯、MAD 修正 z 分数、窗口均值漂移、线性外推）与边界语义（未配预算按通过、冷启动跳过告警、配置错误压过告警），你就能按季度复盘、生产漂移、冒烟快检等不同场景定制阈值，让成本异常在变成账单惊吓之前先变成一行红色摘要。

【免费下载链接】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