在 VS Code 中使用代理模式

借助 Visual Studio Code 中的聊天代理模式，你可以使用自然语言指定高级任务，并让 AI 自主地分析请求、规划所需工作，并将更改应用到你的代码库。代理模式结合使用代码编辑和工具调用来完成你指定的任务。在处理你的请求时，它会监控编辑和工具的结果，并进行迭代以解决出现的任何问题。

先决条件

• 安装最新版本的 Visual Studio Code
• 访问 Copilot。Copilot 免费计划并获得每月补全和聊天交互的限制。

为何使用代理模式？

代理模式针对在项目中的多个文件之间进行自主编辑进行了优化。对于不仅需要代码编辑，还需要调用工具和终端命令的复杂任务，它尤其有用。你可以使用代理模式来

• 重构代码库的部分内容，例如“将应用重构为使用 Redis 缓存”。
• 规划和实现新功能，例如“使用 OAuth 认证为应用添加登录表单”。
• 将你的代码库迁移到新框架，例如“将应用从 React 迁移到 Vue.js”。
• 为复杂任务生成实施计划，例如“使用 Swift 前端和 Node.js 后端创建一个膳食规划 Web 应用”。
• 定义一个高级需求，例如“添加社交媒体分享功能”。

当你的编码任务定义得不太明确，且可能需要运行终端命令和工具时，代理模式特别有用。代理模式会自主确定相关的上下文和任务来完成请求。它还可以多次迭代以解决中间问题，例如语法错误或测试失败。

代理模式 vs 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)) 并从聊天模式选择器中选择代理 (Agent)。

   

   在 VS Code 稳定版或 Insiders 版中直接打开代理模式。

2. 在聊天输入框中输入你的编辑提示，然后选择发送 () 提交。

   你可以指定一个高级需求，而不必指定要处理哪些文件。在代理模式下，AI 会自主确定相关的上下文和要编辑的文件。

   尝试使用以下一些示例提示开始

   • 使用 React 和 Node.js 创建一个膳食规划 Web 应用
   • 添加社交媒体分享功能
   • 将当前身份验证替换为 OAuth

3. 代理模式可能会调用多个工具来完成不同的任务。或者，选择工具图标来配置哪些工具可用于响应你的请求。

   

   提示

   你也可以在提示中通过键入 # 后跟工具名称来直接引用一个工具。你可以在所有聊天模式（提问、编辑和代理模式）中执行此操作。

4. 确认工具调用和终端命令。

   在运行终端命令或非内置工具之前，Copilot 会请求确认才能继续。这是因为工具可能会在你的本地计算机上运行并执行修改文件或数据的操作。

   使用继续按钮下拉选项，可以为当前会话、工作区或所有未来调用自动确认特定工具。了解如何管理工具批准和批准所有工具调用。

   

   如果你的项目在 tasks.json 中配置了任务，代理模式会尝试运行相应的任务。例如，如果你定义了一个构建任务，代理模式将在运行应用程序之前运行该构建任务。使用 github.copilot.chat.agent.runTasks 设置来启用或禁用运行工作区任务。

5. 或者，在运行工具之前验证和编辑工具的输入参数。

   选择工具名称旁边的 V 形图标以查看其详细信息和输入参数。你可以在运行工具前编辑输入参数。

   

6. VS Code 会检测代码编辑和终端命令中的问题，并会迭代解决它们。

   启用 github.copilot.chat.agent.autoFix 设置，以自动诊断和修复生成的代码更改中的问题。此设置默认启用。

   例如，代理模式可能会因代码编辑而运行单元测试。如果测试失败，它会使用测试结果来解决问题。

   代理模式会多次迭代以解决问题。 chat.agent.maxRequests 设置控制代理模式在询问你是否可以继续之前可以发出的最大请求数。

7. 在处理你的聊天请求时，你会注意到建议的代码编辑直接出现在编辑器中。

   你可以在聊天视图中查看已更改文件的列表。编辑器浮层控件使你能够在建议的编辑之间导航。

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.autoApprove 设置。这将自动批准所有工具和命令调用，当语言模型希望运行工具时，VS Code 不会请求确认。

作为一个增强的边界，你可以选择仅在连接到远程环境时设置 chat.tools.autoApprove。你需要将其设置为远程级别而非用户级别的设置。请注意，属于你本地计算机的远程环境（如开发容器）或可以访问你凭据的环境仍会带来不同程度的风险。

自动批准终端命令

在代理模式运行终端命令之前，它会请求确认才能运行。如果你想更精细地控制哪些终端命令被自动批准，请使用 chat.tools.terminal.autoApprove 设置。

此设置允许你在单个配置中指定允许和拒绝的命令：

• 将命令设置为 true 可自动批准它们而无需确认
• 将命令设置为 false 以始终要求明确批准
• 将命令设置为 null 以取消该命令的默认行为
• 通过将模式包装在 / 字符中来使用正则表达式

例如

{
  "mkdir": true,
  "echo": true,
  "/^git (status|show)\\b/": true,
  "rm": false,
  "del": false,
  "/dangerous/": false
}

默认情况下，命令和正则表达式会对完整命令行中的每个子命令进行评估，因此 foo && bar 需要 foo 和 bar 都匹配一个 true 条目，并且不能匹配一个 false 条目才能自动批准。这也适用于内联命令（例如，echo $(rm file)）。

对于高级场景，你可以使用对象语法来控制模式是匹配单个子命令还是整个命令行：

{
  // Broad rule to block any command line that contains ".ps1"
  "/\\.ps1\\b/i": { "approve": false, "matchCommandLine": true }
}

matchCommandLine 属性决定匹配行为

• false (默认): 匹配子命令和内联命令。例如，对于 foo && bar，foo 和 bar 都必须匹配。
• true: 匹配整个命令行。例如，foo && bar被视为单个字符串。

要使终端命令获得自动批准，子命令和命令行都不能被明确拒绝，并且所有子命令或整个命令行都需要被批准。

接受或放弃编辑

Copilot 会在聊天视图中的已更改文件列表中列出被编辑的文件。有待处理编辑的文件在资源管理器视图和编辑器选项卡中也会有指示符。

通过编辑器浮层控件，你可以使用向上 ()和向下 ()控件在建议的编辑之间导航。使用保留或撤销按钮来接受或拒绝给定文件的编辑。

使用编辑器或聊天视图中的保留或撤销控件来接受或拒绝单个或所有建议的编辑。

通过 chat.editing.autoAcceptDelay 设置，你可以配置一个延迟时间，之后建议的编辑将被自动接受。将鼠标悬停在编辑器浮层控件上可以取消自动接受的倒计时。

当你关闭 VS Code 时，待处理编辑的状态会被记住。当你重新打开 VS Code 时，待处理的编辑会被恢复，你仍然可以接受或放弃这些编辑。

编辑之前的聊天请求（实验性）

你可以在当前聊天会话中编辑之前的聊天请求。如果你想优化你的提示或更正错误，这会很有用。编辑聊天请求相当于撤销该请求，然后用编辑后的提示提交一个新请求。

当你编辑之前的聊天请求时，会执行以下步骤：

1. 被编辑的请求以及所有后续的请求和响应都将从对话历史中移除。
2. 这些请求所做的任何编辑都将被恢复到请求发出之前的状态。
3. 编辑后的请求将被添加到对话历史中，并提交给语言模型以获取新的响应。

你可以使用 chat.editRequests 设置来配置对先前聊天请求的编辑

• inline: 在聊天视图中选择请求，使其可以就地编辑。使用 Escape 退出编辑模式。
• hover: 将鼠标悬停在聊天请求上，然后选择编辑图标（铅笔）以使其可就地编辑。使用 Escape 退出编辑模式。
• input: 将鼠标悬停在聊天请求上，然后选择编辑图标（铅笔）以在聊天输入框中编辑该请求。
• none: 禁用在聊天视图中编辑聊天请求。

使用检查点恢复编辑（预览）

聊天检查点提供了一种将工作区状态恢复到先前时间点的方法，当聊天交互导致多个文件发生更改时，这尤其有用。

启用检查点后，VS Code 会在聊天交互的关键点自动创建文件快照，让你可以在聊天请求所做的更改不符合预期或想尝试不同方法时，返回到一个已知的良好状态。

要启用检查点，请配置 chat.checkpoints.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 免费用户为 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