在 VS Code 中使用代理模式

藉助 Visual Studio Code 中的聊天代理模式，您可以使用自然語言指定一個高階任務，然後讓 AI 自主推理請求，規劃所需工作，並將更改應用到您的程式碼庫。代理模式結合了程式碼編輯和工具呼叫來完成您指定的任務。在處理請求時，它會監控編輯和工具的結果，並迭代解決出現的任何問題。

先決條件

• 安裝最新版本的 Visual Studio Code
• 訪問 Copilot。Copilot 免費計劃並獲得每月補全和聊天互動的限制。

為什麼要使用代理模式？

代理模式針對以下場景進行了最佳化

• 基於高階需求或定義不明確的實現細節的編碼任務
• 在專案中的多個檔案中進行自主編輯
• 處理需要程式碼編輯以及工具和終端命令呼叫的複雜任務

代理模式自主確定相關上下文和任務以完成給定請求。它還可以多次迭代以解決中間問題，例如語法錯誤或測試失敗。

您可以將代理模式用於的一些任務示例

• 重構程式碼庫的某些部分，例如“重構應用程式以使用 Redis 快取”。
• 規劃和實現新功能，例如“使用 OAuth 認證嚮應用程式新增登入表單”。
• 將程式碼庫遷移到新框架，例如“將應用程式從 React 遷移到 Vue.js”。
• 為複雜任務生成實現計劃，例如“使用 Swift 前端和 Node.js 後端建立餐食計劃 Web 應用程式”。
• 定義一個高階需求，例如“新增社交媒體分享功能”。

代理模式與 Copilot 編碼代理

VS Code 提供兩種自主編碼體驗。代理模式直接在編輯器中提供互動式開發，而 Copilot 編碼代理則在 GitHub 上獨立工作，在後臺實現功能。

本文件描述了代理模式。您可以在其文件中瞭解更多關於 Copilot 編碼代理的資訊。

在 VS Code 中啟用代理模式

要在 VS Code 中啟用代理模式，請啟用 chat.agent.enabled 設定。

集中管理代理模式

要透過裝置管理在組織內集中啟用或停用代理模式，請查閱企業文件中的集中管理 VS Code 設定。

您可以集中管理與代理模式相關的以下設定

• chat.agent.enabled：啟用或停用代理模式

• chat.extensionTools.enabled：啟用或停用使用第三方擴充套件貢獻的工具

• chat.tools.autoApprove：啟用或停用代理模式工具的自動批准

使用代理模式

在代理模式下，AI 自主操作並確定您提示的相關上下文。

請按照以下步驟開始

1. 開啟“聊天”檢視 (⌃⌘I (Windows, Linux Ctrl+Alt+I))，並從聊天模式選擇器中選擇代理。

   

   直接在 VS Code Stable 或 Insiders 中開啟代理模式。

2. 在聊天輸入欄位中輸入您進行編輯的提示，然後選擇傳送 () 提交。

   您可以指定一個高階需求，而無需指定要處理的檔案。在代理模式下，AI 自主確定要編輯的相關上下文和檔案。

   嘗試一些示例提示以開始使用

   • 使用 React 和 Node.js 建立一個餐食計劃 Web 應用程式
   • 新增社交媒體分享功能
   • 將當前認證替換為 OAuth

3. 代理模式可能會呼叫多個工具來完成不同的任務。您可以選擇工具圖示以配置哪些工具可用於響應您的請求。

   

   提示

   您還可以透過鍵入#後跟工具名稱直接在提示中引用工具。您可以在所有聊天模式（詢問、編輯和代理模式）中執行此操作。

4. 批准工具呼叫和終端命令。

   在執行終端命令、fetch工具或非內建工具之前，VS Code 會請求確認以繼續。這是因為工具可能會在您的本地計算機上執行並執行修改檔案或資料的操作。

   使用允許按鈕下拉選項自動允許當前會話、工作區或所有未來呼叫使用特定工具。瞭解如何管理工具批准並批准所有工具呼叫。

   

   如果您的專案在tasks.json中配置了任務，代理模式會嘗試執行適當的任務。例如，如果您定義了構建任務，代理模式將在執行應用程式之前執行構建任務。使用 github.copilot.chat.agent.runTasks 設定啟用或停用執行工作區任務。

5. （可選）在執行工具之前驗證和編輯工具輸入引數。

   選擇工具名稱旁邊的箭頭以檢視其詳細資訊和輸入引數。您可以在執行工具之前編輯輸入引數。

   

6. VS Code 會檢測程式碼編輯和終端命令中的問題，並會迭代解決它們。

   啟用 github.copilot.chat.agent.autoFix 設定以自動診斷和修復生成的程式碼更改中的問題。此設定預設啟用。

   例如，代理模式可能會由於程式碼編輯而執行單元測試。如果測試失敗，它會使用測試結果來解決問題。

   代理模式會多次迭代以解決問題。 chat.agent.maxRequests 設定控制代理模式在詢問您是否可以繼續之前可以發出的最大請求數。

7. 在處理您的聊天請求時，請注意建議的程式碼編輯會直接出現在編輯器中。

   您可以在“聊天”檢視中檢視更改檔案的列表。編輯器疊加控制元件使您能夠在建議的編輯之間導航。

   注意

   AI 生成的程式碼編輯僅限於當前工作區中的檔案。

8. 檢視建議的編輯並接受或放棄建議的編輯。

9. 繼續迭代程式碼更改以完善編輯或實現其他功能。

代理模式工具

代理模式在處理使用者請求時使用工具來完成專門任務。此類任務的示例包括列出目錄中的檔案、編輯工作區中的檔案、執行終端命令、獲取終端輸出等。

代理模式可以使用以下工具

• 內建工具
• MCP 工具
• 擴充套件貢獻的工具

內建工具只能讀取和編輯當前工作區中的檔案。

您可以檢視和管理可用於響應請求的工具。選擇“聊天”檢視中的工具圖示以檢視和選擇代理模式中可用的工具。

根據工具的結果，代理可能會呼叫其他工具來完成整個請求。例如，如果程式碼編輯導致檔案中的語法錯誤，代理可能會探索另一種方法並建議不同的程式碼更改。

定義工具集

工具集是您可以在聊天中使用的工具集合。您可以像使用單個工具一樣使用工具集。例如，在代理模式下使用工具選擇器選擇工具集，或透過鍵入#後跟工具集名稱直接在提示中引用工具集。

工具集使您能夠將相關工具分組在一起，從而更容易在聊天提示、提示檔案或自定義聊天模式中使用它們。當您安裝了許多來自 MCP 伺服器或擴充套件的工具時，這可能特別有用。

要建立工具集，請在“聊天”檢視中選擇配置聊天按鈕，選擇工具集，然後選擇新建工具集檔案。或者，您可以使用命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 中的聊天：配置工具集命令。

工具集檔案是一個.jsonc檔案，它儲存在您的使用者配置檔案中，幷包含一個代理模式工具列表。工具集具有以下結構

• <tool set name>：工具集的名稱，它顯示在工具選擇器中以及在提示中引用工具集時。
• tools：工具集中包含的工具名稱列表。工具可以是內建工具、MCP 工具或擴充套件貢獻的工具。
• description：工具集的簡要描述。此描述與工具集名稱一起顯示在工具選擇器中。
• icon：工具集的圖示，值可在產品圖示參考中找到。

以下程式碼片段顯示了一個工具集檔案的示例，該檔案定義了一個名為reader的工具集

{
  "reader": {
    "tools": [
      "changes",
      "codebase",
      "fetch",
      "findTestFiles",
      "githubRepo",
      "problems",
      "usages"
    ],
    "description": "description",
    "icon": "tag"
  }
}

管理工具批准

在代理模式執行工具或終端命令之前，它會請求確認是否執行。這是因為它們可能會執行修改檔案或資料或執行破壞性操作的操作。

在“聊天”檢視中，當發生工具或終端命令呼叫時，使用允許按鈕下拉選項自動確認當前會話、工作區或所有未來呼叫使用特定工具。

您可以使用命令面板中的聊天：重置工具確認命令來重置工具確認。

自動批准所有工具和命令

當您啟用chat.tools.global.autoApprove設定時，您可以停用所有工作區中所有工具和終端命令的手動批准。

作為一項增強的邊界措施，您可能選擇僅在連線到遠端環境時設定chat.tools.global.autoApprove。您需要將其設定為遠端設定，而不是使用者級別設定。請注意，作為本地機器一部分（如開發容器）或可以訪問您的憑據的遠端環境仍會帶來不同程度的風險。

自動批准終端命令

在代理模式執行終端命令之前，它會請求確認是否執行。如果您希望對哪些終端命令自動批准進行更精細的控制，請使用 chat.tools.terminal.autoApprove 設定。

此設定允許您在單個配置中指定允許和拒絕的命令

• 將命令設定為true以自動批准，無需確認
• 將命令設定為false以始終需要明確批准
• 將命令設定為null以取消該命令的預設行為
• 透過將模式用/字元括起來使用正則表示式

例如

{
  // Allow the `mkdir` command, regardless of arguments
  "mkdir": true,
  // Allow `test/scripts.sh`, since this contains a `/` it will also allow `\`
  // and an optional `./` or `.\` prefix
  "test/scripts.sh": true,
  // Allow `git status` and all commands starting with `git show`
  "/^git (status|show\\b.*)$/": true,

  // Block the `del` command, regardless of arguments
  "del": false,
  // Block any command containing the text "dangerous"
  "/dangerous/": false,

  // Unset the default `rm` rule to allow other rules to auto approve `rm`
  // commands
  "rm": null,
}

預設情況下，命令和正則表示式會針對完整命令列中的每個子命令進行評估，因此foo && bar需要foo和bar都匹配一個true條目，並且不得匹配false條目才能自動批准。

對於高階場景，您可以使用物件語法來控制模式是匹配單個子命令還是匹配完整命令列

{
  // Broad rule to block any _command line_ that contains the text ".ps1"
  "/\\.ps1\\b/i": { "approve": false, "matchCommandLine": true }
}

matchCommandLine屬性決定匹配行為

• false（預設）：匹配子命令和內聯命令。例如，對於foo && bar，foo和bar都必須匹配。
• true：匹配完整命令列。例如，foo && bar被視為單個字串。

要自動批准終端命令，子命令和命令列都不得被明確拒絕，並且所有子命令或完整命令列都需要被批准。

接受或放棄編輯

VS Code 在“聊天”檢視中列出了已編輯的檔案列表。帶有待處理編輯的檔案在“資源管理器”檢視和編輯器選項卡中也有視覺指示器（方框中的點）。

使用編輯器疊加控制元件，您可以透過使用 上 和 下 控制元件在建議的編輯之間導航。使用保留或撤消按鈕接受或拒絕給定檔案的編輯。

如果您在“原始碼管理”檢視中暫存更改，則任何待處理的編輯都會自動接受。另一方面，如果您放棄更改，任何待處理的編輯也會被放棄。

當您關閉 VS Code 時，待處理編輯的狀態會被記住並在您重新開啟 VS Code 時恢復。

要在一小段延遲後自動接受所有建議的編輯，請配置 chat.editing.autoAccept 設定。將滑鼠懸停在編輯器疊加控制元件上，可以取消自動接受倒計時。如果您自動接受所有編輯，建議仍在原始碼管理中提交之前檢視更改。

管理檔案編輯批准

您可以使用 chat.tools.edits.autoApprove 設定來管理 AI 無需明確使用者批准即可編輯哪些檔案。此設定可以幫助避免對包含敏感資訊（如工作區配置設定或環境設定）的檔案進行意外編輯。

chat.tools.edits.autoApprove 設定接受 glob 模式-布林值對，指示哪些檔案自動批准進行編輯。例如

"chat.tools.edits.autoApprove": {
  "**/*": true,
  "**/.vscode/*.json": false,
  "**/.env": false
}

編輯上一個聊天請求

您可以在活動的聊天會話中編輯以前的聊天請求。如果您想完善提示或糾正錯誤，這會很有用。編輯聊天請求相當於撤消請求，然後使用編輯後的提示提交新請求。瞭解更多關於編輯以前的聊天請求的資訊。

使用檢查點恢復編輯

聊天檢查點提供了一種將工作區狀態恢復到先前時間點的方法，當聊天互動導致多個檔案發生更改時尤其有用。

當啟用檢查點時，VS Code 會在聊天互動的關鍵點自動建立檔案的快照，這樣如果聊天請求所做的更改不符合您的預期，或者您想嘗試不同的方法，您可以返回到一個已知的良好狀態。

要啟用檢查點，請配置 chat.checkpoints.enabled 設定。

瞭解更多關於使用聊天中的檢查點。

使用待辦事項列表跟蹤進度（實驗性）

為了更好地瞭解代理正在處理的各個任務，您可以在代理模式下啟用實驗性待辦事項列表功能。此功能可幫助您跟蹤代理正在完成的任務的進度。這也有助於代理保持專注於總體目標。當代理完成任務時，它會更新待辦事項列表以反映工作的當前狀態。

使用 chat.todoListTool.enabled 設定啟用待辦事項列表功能。

使用指令來獲取符合您編碼風格的 AI 編輯

要獲取符合您編碼風格、首選框架和其他偏好的 AI 生成程式碼編輯，您可以使用指令檔案。指令檔案使您能夠在 Markdown 檔案中描述您的編碼風格和偏好，AI 會使用這些檔案生成符合您要求的程式碼編輯。

您可以手動將指令檔案作為上下文附加到您的聊天提示中，也可以配置指令檔案以自動應用。

以下程式碼片段顯示了一個指令檔案的示例，該檔案描述了您的編碼風格和偏好

---
applyTo: "**"
---
# Project general coding standards

## Naming Conventions
- Use PascalCase for component names, interfaces, and type aliases
- Use camelCase for variables, functions, and methods
- Prefix private class members with underscore (_)
- Use ALL_CAPS for constants

## Error Handling
- Use try/catch blocks for async operations
- Implement proper error boundaries in React components
- Always log errors with contextual information

瞭解更多關於使用指令檔案的資訊。

設定

以下列表包含與代理模式相關的設定。您可以透過“設定”編輯器 (⌘, (Windows, Linux Ctrl+,)) 配置設定。

• chat.agent.enabled：啟用或停用代理模式（預設值：false，需要 VS Code 1.99 或更高版本）
• chat.agent.maxRequests：代理模式下聊天可以發出的最大請求數（預設值：Copilot Free 使用者為 5，其他使用者為 15）
• github.copilot.chat.agent.runTasks：使用代理模式時執行工作區任務（預設值：true）
• chat.mcp.discovery.enabled：啟用或停用發現其他工具中配置的 MCP 伺服器（預設值：true）
• github.copilot.chat.agent.autoFix：自動診斷和修復生成的程式碼更改中的問題（預設值：true）
• chat.tools.autoApprove （實驗性）：自動批准所有工具（預設值：false）

常見問題

為什麼我應該使用代理模式而不是編輯模式？

考慮以下標準在編輯模式和代理模式之間進行選擇

• 編輯範圍：代理模式自主確定相關上下文和要編輯的檔案。在編輯模式下，您需要自己指定上下文。
• 任務複雜度：代理模式更適合需要程式碼編輯以及工具和終端命令呼叫的複雜任務。
• 持續時間：代理模式涉及處理請求的多個步驟，因此獲取響應可能需要更長時間。例如，確定相關的上下文和要編輯的檔案，確定行動計劃等等。
• 自愈：代理模式評估生成的編輯結果，並可能多次迭代以解決中間問題。
• 請求配額：在代理模式下，根據任務的複雜性，一個提示可能會導致對後端發出許多請求。

我什麼時候應該使用 Copilot 編碼代理而不是代理模式？

對於可以獨立在後臺處理而無需立即使用者互動的明確定義的任務，請使用Copilot 編碼代理。當您希望參與開發過程並快速迭代更改時，請使用代理模式。

我收到錯誤訊息“每個請求不能超過 128 個工具。”

一個聊天請求一次最多可以啟用 128 個工具。如果您選擇了超過 128 個工具，請透過在“聊天”檢視中的工具選擇器中取消選擇一些工具來減少工具數量，或確保已啟用虛擬工具 (github.copilot.chat.virtualTools.threshold)。

相關資源

• 配置 MCP 伺服器以向代理模式新增工具
• 使用指令和提示自定義 AI
• 使用 Copilot 編碼代理在後臺實現任務