AI agent token 成本監控

資料怎麼進來

• MCP 健檢：在 AI 工具加上 Budgethelm、按一次授權，對 agent 說「用 Budgethelm 幫我健檢」。agent 會在你的電腦跑一行指令，讀 Claude Code／Codex 的本機紀錄，只上傳時間、工具、模型、token 數和停下紀錄；對話內容、檔案與 API key 不會離開你的電腦。
• 匯入金鑰回報：在專案建立 aops_ 開頭的匯入金鑰，agent 每次呼叫後送到 POST /api/ingest/usage，一次最多 500 筆。同一個 external_id 重送不會重算。金鑰只在建立時顯示一次，資料庫只存雜湊。
• CSV 匯入：在瀏覽器解析並預覽，錯誤附行號，一次最多 5,000 列。可以帶選填的 cache_read_tokens，用來判斷提示快取有沒有用上。
• 示範資料：一鍵建立 14 天、3 個虛構 agent 的資料，畫面標「示範資料（虛構）」，可一鍵清除。

看得到什麼

• 總覽最上方：本週花費（含比上週）、最燒錢的 agent、每月可省。
• 專案頁：近 14 天呼叫數、token、已知成本、錯誤率、平均延遲，每日圖，各 agent、各模型拆分，最近 20 筆呼叫。
• 成本分析頁：可選日期區間，依你填的模型費率估算成本。
• 月預算：本月成本對預算，超過只提醒，不擋 agent。
• 異常偵測：每天的呼叫次數、成本或錯誤率跟前 7 天比，突然暴增就在畫面上標出來（目前不寄通知）。

成本怎麼算

agent 回報了 cost_usd 就照實加總，記為「已知成本」；沒回報就記為成本未知，不自己猜。需要估算的畫面（成本分析、省錢）會用你填的模型費率，沒填時省錢頁改用內建官方價目，並標示為估算。日期一律以 UTC 切日。

在 AI 工具裡查

用 MCP 接上 Budgethelm 之後，可以在 Claude Code、Cursor、Codex 裡直接呼叫 get_project_summary、get_cost_breakdown 查專案摘要和成本拆分。權限分開授權，可以只開放部分專案。

常見問題

沒有回報 cost_usd 會怎樣？

那筆呼叫記為「成本未知」。成本分析頁會用你填的模型費率估算；省錢頁在你沒填費率時，模型在內建價目表上就用官方價補估，並標「含官方價目估算」。

預算超支會擋下 agent 嗎？

不會。月預算只在畫面上提醒，不會阻擋 agent 的呼叫。

日期用哪個時區？

一律以 UTC 切日。