Wattage：给 AI Agent 装上 token 电表，在 CI 中拦截成本回退

Wattage 是一款面向 AI Agent 的 token 消耗剖析与成本回归门禁工具，作者将其定位为「Agent 的 Kill-A-Watt 电表」。它读取符合 OpenTelemetry GenAI 语义约定的追踪导出文件，对每一次模型调用按 vendored 定价快照折算成美元，并跑过一组内置检测器给出修复建议；当一次改动让 Agent 变得更贵时，可以直接在 CI 中失败构建。

安装与快速上手

工具通过 uvx 即可运行，无需配置文件或 API key，可完全离线使用：

• uvx wattage report trace.json：读取一份 OTLP JSON 追踪并输出终端报告。
• uv run wattage report examples/sample_trace.json --html report.html：生成可分享的 HTML 火焰图。
• 仓库自带示例追踪，克隆后 uv sync 即可立即查看一份 Token Efficiency 评级 A（100）、总成本 $0.0602 的样例报告。

报告中会给出 input、output、cache_read、cache_creation、reasoning 五类 token 的细分，以及每条 finding 的美元代价、修复建议和质量风险等级（none / low / review）。

八类浪费检测器

Wattage 在统一数据模型（sessions → tasks → loops → iterations → calls）之上提供 8 个检测器：

• prefix_churn：稳定的前缀被重复发送而未走缓存。
• cache_gap：缓存被部分命中，后续读取未能充分利用。
• verbosity：单步输出远超实际所需。
• redundant_tool_calls：同一工具调用被重复触发（支持模糊匹配）。
• nonconvergence：Agent 在循环中抖动、振荡或空转。
• retrieval_thrash：反复检索但从未拿到相关结果。
• model_mismatch：昂贵模型承担了廉价模型可完成的工作。
• reasoning_o verspend：简单步骤消耗了大量 reasoning token。

其中 nonconvergence 是项目重点强调的「convergence engine」：相比 SHA-256 精确匹配基线在 10 条人工标注合成循环上的 F1 为 0.25，Wattage 的分类器取得 1.00 的精确率与召回率，作者称这是因为它能识别「时间戳每次都换」「两种策略间振荡」「看似不同实则原地踏步」等结构性模式。

在真实追踪上的收益

在一条 3 轮演示追踪上，prefix_churn 的修复模拟显示：仅为稳定前缀开启 prompt caching，单次调用成本即从 $0.000199 降至 $0.000110，下降 44.7%。作者强调绝对金额小，但机制在生产规模上等价。

CI 成本回归门禁

wattage ci 可以作为 PR 检查运行：维护一个基线 JSON 文件，配置失败阈值即可在 PR 中阻断改动。示例 GitHub Actions 工作流支持 score_below、cost_delta_pct_above、any_critical 三类条件，并通过 SARIF 上报到 GitHub Security 标签页，同时输出 JUnit XML 兼容其它 CI 系统。基线只在「实际通过门禁」的运行上更新，噪声抑制是结构性的而非统计性的。

Wattage 拒绝伪造数字：未被定价的模型会把对应调用成本记为 0 并让 wattage ci 以退出码 4 失败，而非猜测；质量信号未测量时显示为 unmeasured，不假定为合格。整体上，它把 Agent 的 token 成本从「黑盒账单」变成「CI 上可被门禁的可观测指标」。