AI Agent 除錯：你的儀表板知道成本，卻不知道原因

AI 代理（agent）的除錯，始於你的可觀測性儀表板無能為力之處。當 AI 編碼代理弄壞了某個東西、而那次執行已經結束時，儀表板只能告訴你該次執行花了多少成本（token、美元、延遲），但對於你真正關心的唯一問題，它卻隻字不提：為什麼代理會改動那個檔案？能回答這個問題的產物，是一段你可以開啟、閱讀、甚至重播的記錄追蹤（trace），因為它把那次執行交還到你手中，而不是從外部對它加以描述。

從代理開始執行實際工作的那一刻起，這就不再是罕見事件。代理會掃過整個儲存庫、編輯數個檔案、執行檢查，然後回報成功，而這一切都在你相隔幾分鐘輸入的兩次提示之間發生。如果其中某個編輯是錯的，你之後才會發現：在終端機關閉之後、在回捲緩衝區消失之後、在那個本可自我解釋的程序退出之後。接下來會發生什麼，完全取決於你保留了什麼。如果答案是成本儀表板，你即將進行考古；如果答案是錄影，你即將進行閱讀。

你無法重現的失敗

事情的樣貌是這樣的。你回到儲存庫，發現一個你從未要求任何人動過的檔案被改寫了、刪除了，或是被清空了——而那正是所有其他東西都依賴的函式。你問代理程式發生了什麼事；工作階段已經關閉，即使記錄檔倖存下來，代理程式對自己執行過程的敘述也只是重建，而非錄影。所以你做了最自然的事：再跑一次，結果得到不同的執行結果。不同的工具呼叫、不同的編輯、甚至可能完全沒有失敗，因為原本的軌跡取決於取樣、取決於儲存庫的狀態、取決於時機。你需要檢查的那次執行，已經不存在了。

這比不可重現更糟：它不可重現，卻被標記為成功。當代理（agent）以 0 退出時，整個執行（run）也會以 0 退出——即使執行內部的某個檢查是以 1 退出。因此，即使執行中的驗證步驟失敗，管線依然可能是綠燈；而你自然會信賴的那個退出碼，其實什麼也沒告訴你。

無論路由機制為這次執行選取了哪個模型（GLM 5.3 Flash 或其他任何模型）都無關緊要：一旦流程結束，推理過程也隨之消失。證據只存在於執行仍在進行之際：提示詞、工具呼叫、輸出、差異。如果沒有記錄下來，「它為什麼改了那個檔案」就沒有答案，只能靠推測。

這就是將AI 編碼代理與它們之前出現過的所有工具區分開來的失敗模式：損害與解釋發生在同一個地方，而那個地方會關閉。

「儀表板衡量了什麼，又略過了什麼？」

一次糟糕的運行之後，本能反應是打開可觀測性儀表板，而儀表板確實能出色地完成它的工作。它的工作是流量：每日 token 數、每個模型的成本、延遲、錯誤率。對於容量規劃和計費來說，這正是合適的工具；如果你在生產中運行 agent，就應該讓它保持開啟。

但你的問題不是總體性的。它是單一且因果性的：為什麼這次執行改變了這個檔案？聚合恰恰跳過了能回答這個問題所需的粒度。跨多次執行平均時，你在乎的那次執行成了雜訊；而在那次執行內部，你在乎的那次工具呼叫又成了雜訊。

儀表板從外部描述一次運行：它發生了、它的規模、它的代價。它無法將運行本身交到你手中，而「為什麼」並非描述的屬性，而是序列的屬性。

• 此次執行花費多少？— 成本儀表板可回答 vs 記錄的追蹤可回答

• 代理程式為何變更該檔案？ — 成本儀表板 無答案 vs 記錄的軌跡 依序顯示的編輯及其差異

• 在綠色執行中，哪一項檢查失敗？ — 成本儀表板「無回應」對比「已記錄的追蹤」 該檢查及其結束代碼

• 我能否再次重現完全相同的失敗？ — 成本儀表板：否；記錄的追蹤：是，離線且免費。

能回答這個問題的層級位於更底層：已記錄的請求日誌，於執行當下捕捉，依序包含每個發送的提示、每個發出的工具呼叫，以及每個回傳的回應。不是執行過程的摘要，而是執行過程本身。

將一次運行當作時間軸來解讀

有了錄影，除錯就不再是考古，而是閱讀。沒有錄影時，你做的就是考古：git reflog、stash 條目、shell 歷史，以及你自己對當天稍早提出過什麼要求的記憶。有了錄影，你做的就是閱讀：打開時間軸，然後捲動。

時間軸會依照事件發生的順序，把整個執行過程攤開來：開啟一切的提示、每次工具呼叫、每次附 diff 的檔案編輯、每次檢查、每組退出碼。檔案系統快照是每一「輪」拍攝一次，而不是每一次工具呼叫都拍——這樣足以在對話的每個步驟掌握儲存庫狀態，又不會被每次呼叫的雜訊淹沒。讓這成為除錯而非瀏覽的，是相鄰性：編輯與攔下它的檢查彼此相鄰、依序陳列，中間沒有任何需要臆測的縫隙。「為什麼」多半正是相鄰性所賦予的。

一個具體的例子，可從一段記錄下來的修復中直接讀出：14 個事件，包括以 +1 -3 呈現的檔案變更，以及一個結束代碼為 1 的失敗檢查。編輯動作與隨後因它而失敗的檢查，在記錄中前後相鄰。這就是從片段重建執行歷程與直接閱讀執行歷程之間的完整差異。最受此差異影響的正是終端編碼代理：他們的工作區是一個在任務完成的那一刻便會關閉的終端；時間軸就是留存下來的捲動緩衝區。

記錄或推斷：追蹤所知道的，與它得出的結論

時間軸告訴你事件的先後順序。因果圖告訴你什麼導致了什麼，而這兩者之間的差距，正是信任必須被建立的地方。

該圖表連接事件：這次編輯，然後是這次失敗的檢查。其中一些邊是記錄的事實：產生 diff 的工具呼叫就在追蹤記錄中。其他邊則是推斷出來的：該圖表得出結論，認為檢查失敗是由於那次 diff 造成的。orca graph 會將每一條邊標記為記錄的或推斷的，並在兩種情況下都標明它所使用的規則，因此你永遠知道你看的是執行時實際發生的事，還是工具對執行結果推斷出的結論。

這種區別是切實執行的，而非僅供期許：推斷出的邊永遠不會被寫回追蹤紀錄中。追蹤紀錄依然是實際發生之事的忠實記錄；推斷只是疊加其上的一層視圖，你可以檢視、質疑它，甚至不同意它。當涉及的代理不只一個時，這點格外重要。當一個重構代理和一個撰寫測試的代理改動相同的檔案時，「是哪個代理造成了這個變更？」正是多代理歸因所要回答的問題。如果這樣一條邊悄悄把自己從推斷升格為事實，你最後就會在除錯一個故事，而不是一次執行。

您可以免費重製，次數隨您喜歡

閱讀可以解釋，重播可以證明。一旦你有了假設（檢查失敗是因為這項編輯移除了 reset 呼叫），你就會想再次執行，親眼看著它發生。重新執行即時代理程式，會為你帶來一條新的軌跡與一張新的帳單。

重放運行記錄能讓你得到完全相同的那次執行：重放會在封鎖網路的狀態下執行，所以不消耗 token、也沒有變異。每次都是相同的事件，而且完全離線。正是這個特性，把智能體除錯從賭博變成了工程：失敗已成為確定性的，而確定性的失敗就能被修復。

這套工具也並非黑箱。OrcaReplay 以 Apache-2.0 開放原始碼授權釋出，追蹤格式則採用 CC BY 4.0，因此任何人都能重新實作：你的錄製內容不會被專有格式綁架，我們自己的也不例外。而它經過實際測試，並非僅供展示：在 Node 20 與 Node 22 上通過 1393 項測試。你可以先親自閱讀原始碼、檢查格式、執行測試套件，再決定是否要讓它處理你團隊的測試執行。

重點

儀表板是一張帳單。記錄下來的軌跡才是那次執行。如果你除錯 AI 代理的計畫止步於成本儀表板，那你有的不是除錯計畫，而是一套計費系統。儀表板永遠能告訴你一次執行花了多少錢，卻永遠無法告訴你代理為什麼刪掉了你的檔案，因為「為什麼」存在於序列之中，而序列唯有在你保留它的時候才存在。

整個方法共有四個步驟：

• 記錄每次執行。

• 閱讀時間軸。

• 檢查圖的邊。

• 免費重玩那些令你感到害怕的內容，次數不限。

來源說明：本文中的每項數據皆為廠商回報，出自我們自己的產品，以及 OrcaReplay 儲存庫與其文件：一次執行的退出碼行為；記錄了 14 個事件的修復，含其 +1 -3 差異與退出碼 1 的檢查；orca 圖中邊的標記；每回合一次的快照頻率；封鎖網路時的離線重播；以及在 Node 20 與 Node 22 上執行的 1393 項測試套件。本文未引用任何第三方測量結果。1393 項測試套件是唯一您可以自行驗證的宣稱：複製該儲存庫並執行即可。所有項目皆已於 2026-09-04 進行最後核對。