偵錯 Agent 的工作

當 Agent 出現非預期的行為、呼叫了錯誤的工具、產生了奇怪的回應，或是忽略了自訂設定檔時，您會希望了解原因。VS Code 與 GitHub Copilot Chat 是開源的，這種透明度延伸到了執行時期的運作過程。本指南將介紹 Agent 除錯紀錄面板 (Agent Debug Log panel)、Chat 除錯檢視 (Chat Debug view)，以及如何使用兩者來診斷 Agent 的行為。

Agent 除錯紀錄面板

Agent 除錯紀錄面板是主要的診斷工具。您可以從 Chat 檢視上方的溢位選單中選擇顯示 Agent 除錯紀錄 (Show Agent Debug Logs) 來開啟，或在指令選擇區 (Command Palette) 執行 開發人員：開啟 Agent 除錯面板 (Developer: Open Agent Debug Panel)。

此面板會以編輯器分頁的形式開啟。頂部的階層連結 (breadcrumb) 會顯示您目前正在檢查的對話工作階段。

紀錄檢視

「紀錄」(Logs) 檢視會顯示工作階段期間發生的每個事件的時間序列清單。每一列包含：

• 時間戳記。
• 事件名稱。
• 詳細資料欄中的摘要。

在每次請求開始時，您會看到一組自訂事件：

• 載入指令 (Load Instructions) - 找到並套用了哪些指令檔案
• 載入 Agent (Load Agents) - 載入了哪些 Agent 設定
• 載入 Hooks (Load Hooks) - 找到了哪些 Hook 定義
• 載入技能 (Load Skills) - 找到了哪些技能並進行了載入

這些資訊會精確顯示 Agent 在開始運作前載入了什麼。在此之後，隨著工作階段的進行，您將會看到工具呼叫與 LLM 請求。

使用頂部的切換開關，可以在「清單檢視」(List View，平鋪的時間順序) 與「樹狀檢視」(Tree View，依子 Agent 分組) 之間切換。使用篩選列來縮小特定事件類型的範圍——例如，如果您只想查看工具呼叫。

展開事件詳細資料

選擇紀錄檢視中的任何一行，即可在右側開啟詳細資料面板。

根據事件類型，面板會顯示：

• 載入技能 (Load Skills) - 已搜尋的路徑完整清單 (依順序) 以及找到並載入了哪些技能
• 工具呼叫 (Tool call) - 精確的輸入負載 (payload) 與回傳的輸出
• LLM 請求 (LLM Request) - 發送給模型的完整系統提示詞 (system prompt)

這是診斷價值最高的部分。如果自訂設定未生效，載入詳情會顯示搜尋過的確切路徑，以及是否找到了您的檔案。

摘要檢視

選取階層連結中的工作階段名稱，即可導覽至「摘要」(Summary) 檢視。它會顯示該工作階段的統計彙總。

• 模型輪次 (Model turns)。
• 工具呼叫。
• 總 Token 使用量。
• 錯誤。
• 事件總數。

您可以從摘要檢視開啟「Agent 流程圖」。

Agent 流程圖

流程圖將事件順序視覺化為可導覽的圖表。這對於理解子 Agent 如何被呼叫以及工作如何被結構化非常有幫助。

Chat 除錯檢視

如果說 Agent 除錯紀錄面板顯示的是事件順序，那麼 Chat 除錯檢視顯示的就是每個 LLM 請求與回應的原始內容。

從 Chat 檢視的溢位選單中選擇顯示 Chat 除錯檢視 (Show Chat Debug View) 來開啟它。

側邊欄會列出工作階段期間發出的每一項 AI 請求，並依 Agent 分組。選取一項請求來檢查：

• 完整的系統提示詞。
• 使用者的提示詞。
• 所有已附加的上下文。
• 完整的工具呼叫負載。

這些是傳送給模型以及從模型回傳的確切資料。這對於回答以下問題很有用：當 Agent 撰寫該函式時，是否擁有正確的檔案內容？系統提示詞的構成是否如我預期？

#debugEventsSnapshot 與 /troubleshoot

一旦您正在查看某個工作階段的除錯面板，您可以直接將這些事件的快照附加到對話訊息中。

#debugEventsSnapshot

在對話輸入框中輸入 #debugEventsSnapshot，即可將目前除錯事件的快照作為上下文附加進去。

範例

#debugEventsSnapshot how many tokens did this session use?

#debugEventsSnapshot which customization files were loaded?

#debugEventsSnapshot why did it call that tool twice?

Agent 會讀取該快照並根據實際發生的情況進行回答——不是基於一般知識，而是基於您工作階段中的實際事件資料。

您也可以點擊 Agent 除錯面板右上角的星號圖示，自動將快照附加到對話編輯器中。

/troubleshoot

/troubleshoot 是一個專門用於深入紀錄分析的斜線指令。

範例

/troubleshoot list all paths you tried to load customizations from

/troubleshoot the agent made an unexpected file edit in the last response, why?

檢查重點

Token 使用量

如果回應開始變得模糊或重複，請先檢查摘要檢視。上下文視窗過滿是導致輸出品質下降的常見原因。

工具呼叫順序

查看紀錄檢視以確認 Agent 是否遵循了合理的順序，例如在編輯檔案前先讀取它，或在變更後執行測試。

自訂設定檔探索

如果自訂指令、技能或提示詞檔案似乎未生效，請檢查載入事件，查看搜尋過的每一條路徑。

錯誤

失敗的工具呼叫、模型逾時以及遺失的依賴項會直接顯示在紀錄檢視中。

關於紀錄持久性的重要說明

紀錄資料不會跨 VS Code 工作階段進行持久化。Agent 除錯紀錄面板與 Chat 除錯檢視僅顯示目前 VS Code 工作階段的資料，且 Chat 除錯檢視僅擷取在作用中視窗期間發出的 LLM 請求。請在您實際工作時使用這些工具——一旦您重新啟動 VS Code，這些資料將無法再存取。

接下來要做什麼

Agent 除錯紀錄面板與 Chat 除錯檢視讓您能完整洞察 Agent 的運作：紀錄檢視用於時間軸、摘要用於數據、流程圖用於結構，而 Chat 除錯檢視則用於原始負載。當您需要用通俗語言詢問關於工作階段的問題時，#debugEventsSnapshot 與 /troubleshoot 就能讓您精確達成目標。

這就是完整的基礎：工具鏈、模型、上下文、工具、提示詞、工作階段與除錯層。在最後一章指南中，您將會把所有內容整合起來，並從零開始建構一個真正的應用程式。

深入了解

• 偵錯聊天互動