mcpField
C
cost-diff

cost-diff

github.com/ruvnet测试与质量80.0k248 次安装今天更新
代码仓库

关于 cost-diff

cost-diff 是用于比较两份成本摘要快照的回归检测技能，可在 PR 流程中检查支出变化。它按层级和模型列出变动，并支持总额、百分比及令牌类别阈值告警。

主要功能

  1. 01比较基线与当前快照
  2. 02按层级和模型计算差异
  3. 03按绝对差额排序结果
  4. 04支持总额与百分比告警
  5. 05检查令牌类别增长阈值

适用场景

  1. 01在 PR 检查中检测成本回归
  2. 02比较 main 与分支的成本快照
  3. 03发现缓存写入等令牌类别增长
  4. 04使用百分比和金额阈值设置门禁

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/ruvnet/ruflo --skill cost-diff

安装后在 Claude Code 中输入/cost-diff确认已加载。

详细介绍

PR 级成本回归检测。cost-counterfactual 会与假设基线（始终使用 haiku/sonnet/opus）进行比较，cost-burn 会将最新时间段与之前的均值进行比较，而 cost-diff 会比较两个特定的已知良好快照。

问题技能
“如果始终使用 X，我们会花多少钱？”cost-counterfactual
“每日消耗是否比之前的均值增长得更快？”cost-burn
“这个 PR 是否比 main 增加了支出？”cost-diff ← 就是这个

算法

实现：scripts/diff.mjs。使用 cost summary --format json 提供的稳定 JSON 契约。

  1. 加载 --baseline 和 --current JSON 快照。
  2. 合理性检查：两者都必须包含 total_cost_usd 和 sessionCount（cost-summary 结构）。
  3. 按键计算差值：byTier（haiku/sonnet/opus）和 byModel（每个模型）。
  4. 根据基线／当前值是否为零，为每个条目标记 added／removed／changed。
  5. 按 |delta| 降序排列表格，让变化最大的条目位于顶部。
  6. --alert-on-pct N：当 total_pct > N 时以状态码 1 退出。
  7. --alert-on-usd N：当 total_delta_usd > N 时以状态码 1 退出。 两者可以同时设置；先触发的条件优先。

PR 门禁工作流

# Capture baseline (e.g. on main, via the cost-tracker-smoke CI workflow)
cost summary --format json > baseline.json

# On the PR branch, capture current state
cost summary --format json > current.json

# Compare; fail the PR if total spend grew >10% OR >$5
cost diff --baseline baseline.json --current current.json \
          --alert-on-pct 10 --alert-on-usd 5.00

同时使用这两个标志可以捕捉以下情况：

  • 仅百分比触发：绝对变化较小，但变化幅度显著 （例如从 $0.10 翻倍到 $0.20，达到 +100%，但只增加了 +$0.10）。
  • 仅 USD 触发：绝对变化较大，但百分比较小 （例如从 $100 增长到 $110，仅增长 +10%，但增加了 +$10）。

任一信号都可以独立导致 PR 检查失败——两者是 OR 关系。

--alert-on-class-pct（迭代 86）

上面的两个 USD 级阈值会漏掉一种回归：当某一种 token 类型增长过快，而总支出仅小幅增长时。例如，某个 PR 引入了冗长的上下文缓存模式，总支出只增长了 10%（低于 --alert-on-pct 50），但 cache_write token 增长了 900%。迭代 82 的驱动因素被 USD 信号掩盖了。

当 cache_write token 从基线到当前增长超过 50% 时，--alert-on-class-pct cache_write:50 会以状态码 1 退出。可在一个标志中检查多个类别（以逗号分隔）：

cost diff --baseline baseline.json --current current.json \
          --alert-on-class-pct cache_write:50,output:25

第一个超出阈值的类别优先。有效类别：input | output | cache_write | cache_read。

推荐的 PR 门禁三项组合：

cost diff --baseline ... --current ... \
          --alert-on-pct 25 \
          --alert-on-usd 5.00 \
          --alert-on-class-pct cache_write:100

三个相互正交的信号——pct（总量增长）、usd（绝对增幅较大）、class-pct（构成发生变化）。每个信号都能捕捉其他信号遗漏的情况；OR 关系的 AND 语义意味着任一信号触发都会导致 PR 检查失败。

冒烟测试记录（合成的基线与当前快照）

| Total spend       | $1.000000 | $1.500000 | +$0.500000 | 50.00% |
| Sessions          | 10        | 13        | +3         | 30.00% |

## By tier
| opus   | $0      | $0.60   | +$0.600000 | new      | added   |
| sonnet | $0.70   | $0.50   | -$0.200000 | -28.57%  | changed |
| haiku  | $0.30   | $0.40   | +$0.100000 | 33.33%   | changed |

注意，表格按绝对差值而非字母顺序排序——变化最大的条目（新添加的 opus）会排在最前面。操作人员从上往下查看，就能首先看到“影响最大的事项”。

退出码

退出码含义
0未触发警报，或未设置阈值
1超出 --alert-on-pct 或 --alert-on-usd 阈值
2配置错误（文件缺失、JSON 无效、快照格式错误）

状态列

状态含义
added此 tier／model 在基线中为 $0，在当前快照中大于 $0
removed此 tier／model 在基线中大于 $0，在当前快照中为 $0
changed基线和当前快照都大于 $0；差值即为两者之差

baseline === 0 && current === 0 的条目会被删除（无需报告）。

与 cost-summary 的配合

cost-diff 是由 cost-summary 奠定的契约的后半部分：即 cost summary --format json 提供的稳定 JSON 结构。两部分都已冻结——可以向 summary 添加字段，但不能重命名或删除字段。

如果你在其他地方使用快照（仪表板、警报），同样的结构也适用——cost-diff 只是其中一个使用方。

评论

支持 Markdown