在 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 编码代理在后台实现任务