Wattage: 一个用于AI智能体的token消耗分析器和成本回归门

Wattage 是一个面向 AI 智能体的开源 token 消耗分析器和成本回归门。它能够读取 OpenTelemetry (OTLP) JSON 格式的追踪导出文件，无需配置、API 密钥，完全离线运行，为每一次调用定价并执行多种效率检测。

快速上手

使用 uvx wattage report trace.json 即可分析追踪文件。例如，针对仓库中自带的示例追踪文件，运行 uv run wattage report examples/sample_trace.json 会输出一个终端表格，显示总成本、token 细分和效率等级（如 A 级）。也可以使用 --html 参数生成独立的 HTML 火焰图。

核心功能：收敛引擎

Wattage 的突出特点是其收敛引擎，特别是非收敛检测器。它能够捕捉智能体在循环中无效震荡的模式，包括时间戳变化的重复尝试、两种策略间的振荡，以及每次调用技术上不同但未学到任何东西的“看似高效”的停滞。与 SHA-256 精确匹配基线相比，Wattage 在基准测试中实现了 1.00 的 F1 分数（精确率 1.00，召回率 1.00），而基线 F1 仅为 0.25。此外，Wattage 的前缀抖动修复模拟显示，通过启用稳定前缀的提示缓存，成本可降低 44.7%。

八大检测器

Wattage 在 wattage report 中运行八个检测器：前缀抖动（稳定上下文被重新发送而非缓存）、缓存间隙（尝试缓存但后续读取未充分利用）、冗长性（输出远超所需）、冗余工具调用（相同工具重复调用）、非收敛（循环无效）、检索抖动（重复检索无结果）、模型不匹配（用昂贵模型处理可由便宜模型完成的任务）、推理过度支出（简单步骤使用大量推理 token）。每种问题都有实际的美元成本，并附带具体修复建议，同时标注质量风险等级（无/低/审查）。

CI 集成

Wattage 提供 wattage ci 命令作为成本回归门。在 GitHub Actions 工作流中，可以配置在 PR 中运行，当智能体性能退化超过阈值时（如分数低于 80、成本增加超过 5%、存在严重问题），构建失败并发布 PR 注释，包含每个检测器的 delta 表。同时支持 SARIF 和 JUnit XML 输出，便于集成到其他 CI 系统。基线文件是一个小型 JSON 文件，仅在通过门的运行中更新，避免噪声污染。

徽章与贡献

使用 uv run wattage badge 可生成 README 徽章，可在 CI 中自动更新。Wattage 采用 Apache-2.0 许可证，贡献者可通过 Python entry-point 组添加新检测器，无需修改核心管道。