偵錯聊天互動

Visual Studio Code 提供了多種工具，協助您了解傳送提示詞（Prompt）給 AI 時實際發生的狀況。請使用這些工具來檢查代理程式如何探索提示詞檔案、呼叫工具、發出語言模型請求以及產生回應。

VS Code 提供兩個互補的除錯工具

• 代理除錯記錄面板 (Agent Debug Log panel)（預覽版）顯示聊天期間發生的所有事件的時間順序記錄，包括工具呼叫、LLM 請求、提示詞檔案探索以及錯誤。
• 聊天除錯檢視 (Chat Debug view) 顯示每個 LLM 請求和回應的原始詳細資料，包括完整的系統提示詞、使用者提示詞、上下文以及工具呼叫酬載（payloads）。

代理除錯記錄面板

代理除錯記錄面板是了解發送提示詞時發生狀況的主要工具。它會顯示聊天期間代理互動的時間順序記錄，在除錯 自訂代理 和編排的子代理工作流程時特別有用。

若要開啟代理除錯記錄面板

• 啟用下列設定

  • github.copilot.chat.agentDebugLog.fileLogging.enabled 在 VS Code 中開啟 在 VS Code Insiders 中開啟

• 在「聊天」檢視中選取省略號 (...) 選單，然後選擇 顯示代理除錯記錄 (Show Agent Debug Logs)。

• 從命令面板執行 開發人員：開啟代理除錯記錄 (Developer: Open Agent Debug Logs)。

您可以在代理除錯面板中切換四種檢視模式

• 記錄 (Logs)：工作階段期間事件的時間順序列表，具備篩選功能，可專注於特定事件類型。

• 代理流程圖 (Agent Flow Chart)：視覺化呈現工作階段期間代理與子代理之間互動的流程圖。

• 摘要 (Summary)：工作階段的匯總統計資料，例如工具呼叫總數、Token 使用量、錯誤數量以及總持續時間。

• 快取瀏覽器 (Cache Explorer)：連續模型請求的並排差異比較（diff），有助於診斷提示詞快取未命中的問題。

記錄檢視

記錄檢視會顯示聊天期間發生的事件時間順序列表。每個事件都包含時間戳記、事件類型和摘要資訊。您可以展開每個事件以檢視更多詳細資料，例如 LLM 請求的完整系統提示詞，或是工具呼叫的輸入與輸出。

您可以切換「平面列表」與「樹狀檢視」，後者將事件按子代理進行分組。使用篩選選項可專注於特定事件或事件類型。

當您開啟代理除錯面板時，記錄檢視為預設檢視。您也可以透過選取 檢視記錄 (View Logs)，從 摘要檢視 切換回記錄檢視。

摘要檢視

摘要檢視提供聊天工作階段的匯總統計資料，例如工具呼叫總數、Token 使用量、錯誤數量和總持續時間。

在摘要檢視中，您可以選取 檢視記錄 (View Logs)、代理流程圖 (Agent Flow Chart) 或 快取瀏覽器 (Cache Explorer) 來切換至對應的檢視模式。

若要開啟摘要檢視

1. 透過在聊天檢視中選取省略號 (...) 選單並選擇 顯示代理除錯記錄 (Show Agent Debug Logs) 來開啟代理除錯面板。

2. 在面板頂端的導覽列中選取工作階段說明。

代理流程圖檢視

代理流程圖檢視可將代理之間的事件順序和互動視覺化，讓您可以更輕鬆地理解複雜的編排邏輯。

您可以平移和縮放流程圖，並選取圖表中的任何節點以查看該事件的詳細資料。

若要開啟流程圖檢視，請從 摘要檢視 中選取 代理流程圖 (Agent Flow Chart)。

1. 透過在聊天檢視中選取省略號 (...) 選單並選擇 顯示代理除錯記錄 (Show Agent Debug Logs) 來開啟代理除錯面板。

2. 在面板頂端的導覽列中選取工作階段說明。

3. 從摘要檢視中選取 代理流程圖 (Agent Flow Chart)。

快取瀏覽器檢視

快取瀏覽器檢視可透過比較工作階段中連續的模型回合請求，協助您診斷提示詞快取未命中的問題。提示詞快取允許語言模型提供者重複使用符合先前請求的前綴，從而降低延遲和 Token 成本。當快取命中率較低時，快取瀏覽器能精確指出提示詞前綴在何處分歧。

此檢視包含兩個面板

• 工作階段中所有模型回合的列表，依使用者請求分組。每個回合顯示快取命中百分比、持續時間、模型名稱和時間戳記。選取一個回合即可與前一個回合進行比較。
• 主要內容區域顯示當前請求與先前請求之間的並排前綴差異。

主要內容區域包含下列資訊

• 快取效能：快取命中百分比以及相對於總數所重複使用的輸入 Token 數量。
• 提示詞簽章 (Prompt signature)：請求中每個元件（系統指令、工具定義和訊息）的視覺化摘要，並附帶顏色編碼的狀態指標。第一個分歧點標記了提示詞快取中斷的位置。
• 元件：系統指令、工具定義和個別訊息的可展開區段，會顯示兩個請求之間的文字級差異。

若要開啟快取瀏覽器檢視

1. 透過在聊天檢視中選取省略號 (...) 選單並選擇 顯示代理除錯記錄 (Show Agent Debug Logs) 來開啟代理除錯面板。

2. 在頂端的導覽列中選取工作階段說明，前往摘要檢視。

3. 選取 快取瀏覽器 (Cache Explorer) 以開啟所選工作階段的快取瀏覽器檢視。

將除錯事件附加到聊天中

您可以將代理除錯事件的快照附加到聊天對話中，並針對當前工作階段詢問 AI 問題。這對於了解 Token 使用量、載入了哪些自訂項目、發生了哪些工具呼叫以及請求花費的時間非常有用。

若要將除錯事件附加到聊天中

1. 為您的聊天工作階段開啟 代理記錄檢視。

2. 選取代理除錯面板右上角的閃光圖示。這會開啟聊天檢視，並將除錯事件快照作為上下文附加進去。

或者，您也可以使用 /troubleshoot 斜線指令直接詢問聊天工作階段相關問題，而無需先開啟代理除錯面板。例如，輸入 /troubleshoot list all paths you tried to load customizations 或 /troubleshoot how many tokens did you use in #session。

匯出與匯入工作階段

您可以將除錯工作階段匯出為 Open Telemetry JSON (OTLP 格式) 檔案，以便與他人分享或離線分析。您也可以匯入先前匯出的檔案，在代理除錯面板中檢視。

若要匯出工作階段

1. 開啟代理除錯記錄面板並導覽至您想要匯出的工作階段。

2. 選取面板右上角工具列中的 匯出 (Export) 圖示（下載）。

3. 選擇儲存 JSON 檔案的位置。

如果未選取任何工作階段，VS Code 會顯示通知，提示沒有可供匯出的現用除錯工作階段。

若要匯入工作階段

1. 選取代理除錯記錄面板右上角工具列中的 匯入 (Import) 圖示（上傳）。

2. 選取一個先前匯出的 JSON 檔案。

匯入的工作階段會開啟在代理除錯記錄面板中，並顯示其概觀與指標，就像即時工作階段一樣。

聊天除錯檢視

聊天除錯檢視會顯示每個 AI 請求與回應的原始詳細資料。當您需要檢查發送給語言模型或從中接收到的確切系統提示詞、使用者提示詞、上下文或工具回應酬載時，請使用此工具。

開啟聊天除錯檢視

若要開啟聊天除錯檢視

• 在聊天檢視中選取溢位選單，然後選擇 顯示聊天除錯檢視 (Show Chat Debug View)。
• 從命令面板執行 開發人員：顯示聊天除錯檢視 (Developer: Show Chat Debug View) 指令。

讀取除錯輸出

聊天除錯檢視中的每次互動都包含可展開的區段

您可以展開每個區段以查看完整詳細資訊。當使用代理程式時，由於單一請求中可能會呼叫多個工具，此功能特別有用。

常見的疑難排解情境

AI 忽略您的工作區檔案

如果 AI 回應的是一般資訊，而非參考您的程式碼庫

1. 開啟代理記錄並檢查 探索 (Discovery) 事件，以驗證工作區檔案是否已建立索引。
2. 開啟聊天除錯檢視並檢查 上下文 (Context) 區段，驗證工作區檔案是否出現在上下文中。如果沒有，請確認 工作區索引 已啟用。
3. 嘗試加入明確的 # 提及項目（例如 #file 或 #codebase）以確保正確的檔案被包含在內。深入了解 管理上下文。

MCP 工具未被呼叫

如果 AI 未呼叫預期的工具

1. 開啟代理記錄並檢查 工具呼叫 (Tool calls) 篩選器，查看該工具是被呼叫還是被跳過。
2. 開啟聊天除錯檢視並檢查 系統提示詞 區段，驗證該工具是否列在可用工具中。
3. 如果缺少該工具，請確認 MCP 伺服器正在執行且已正確設定。
4. 嘗試在提示詞中明確使用 #tool-name 提及該工具。

AI 回應不完整或被中斷

如果回應看起來被截斷了

1. 檢查代理記錄中的 LLM 請求 (LLM requests) 事件，以檢視 Token 使用量。
2. 上下文視窗已滿可能會導致模型截斷其回應。啟動 新的聊天工作階段 以重設上下文。

提示詞檔案未被套用

如果自訂指令或提示詞檔案似乎沒有生效

1. 開啟代理記錄並檢查 探索 (Discovery) 事件，查看該檔案是被載入、跳過還是驗證失敗。
2. 驗證檔案路徑以及 applyTo 模式是否與當前上下文相符。
3. 查看 聊天自訂診斷 以取得錯誤詳情。

相關資源

• 聊天概覽
• 管理 AI 的情境
• 在 VS Code 中疑難排解 AI
• 在 VS Code 中使用 AI 的安全性考量