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