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 組添加新檢測器，無需修改核心管道。