AI Agent 工具使用记录

这篇文章主要是记录 AI 工具配置中的一些小经验。

VSCode 与 Copilot

概述

目前 Copilot 已经可以免费使用，这部分内容会参考 Vscode 的 copilot 使用文档（以及翻译版）进行介绍。

Copilot 目前支持以下功能：

内联建议：补全单行或函数实现，以幽灵文本显示。可按 Tab 补全。当需要部分接受建议时使用 Ctrl+Right 接受建议的下一词/下一行。此外内联建议还支持预测下一步的更改。
自主编码：代理自主规划和执行复杂的开发任务，协调多种工具的多步工作流。MCP 或扩展工具可以增强自主编码的能力
自然语言聊天：在聊天界面中用自然语言与代码库互动，如进行提问、请求解释，或指定代码变更。使用 Ctrl+I 进行内联聊天（可在终端中触发）， Ctrl+Alt+I 在聊天界面中进行聊天。
智能操作：集成在编辑器中的增强功能，如自动编写提交消息、实现 TODO 注释、代码评审等

Copilot 可以根据工作区配置使用定制化的工作流程：

自定义指令
切换语言模型
自定义代理
MCP 服务器和工具增强

简单配置 Copilot

使用不同账号或者启停 AI 功能

VSCode 可为不同工作区使用不同的 Copilot 账号（帐户->管理扩展帐户首选项），也可以针对不同工作区启停 AI 功能（chat.disableAIFeatures）。

创建自定义指令

在项目根目录下创建 .github 文件夹，并在该文件夹下创建 copilot-instructions.md 文件。该文件中的内容应用于项目中的所有聊天交互。

创建自定义代理

在命令面板运行 Chat: New Custom Agent 命令，可在项目目录中创建一个新的自定义代理。一般在 .github/agents 下

聊天

模型与代理

Copilot 聊天可以选择不同的模型与代理。VSCode 提供了四个内置代理：代理、计划、询问和编辑。对于更专业的工作流程，还可以创建自定义代理。

定制化工作流 为了更定制化工作流程，在聊天过程中，可使用自定义指令、提示文件、自定义代理和 MCP 服务器。

上下文

聊天过程使用适当的上下文以获取最佳效果：

使用 # 提及添加上下文：引用特定文件 (#file)、代码库 (#codebase) 或终端输出 (#terminalSelection)。在聊天输入字段中键入 # 以查看所有可用的上下文项。
使用 / 命令：键入 / 以访问常用命令，如 /new 或 /explain，或创建自定义指令。
键入 # 后面跟一个工具名称，使用工具以扩展聊天功能。例如，#fetch 用于检索 Web 内容，#githubRepo 用于搜索 GitHub 存储库。
通过 @ 后接聊天参与者名称，VSCode 包含多个内置聊天参与者，如 @vscode、@terminal 或 @workspace。它们经过优化，可以回答有关其各自领域的问题。

此外 Copilot 还支持视觉图片和浏览器元素的上下文。

将聊天会话保存为可重用提示文件

在聊天输入框中键入 /savePrompt 并按 Enter。该命令会创建一个 .prompt.md 文件，将您当前的聊天对话概括为可重用提示。提示文件会在适当的地方包含占位符。

工具

使用工具 聊天中可使用的工具包含：内置工具、MCP 工具和扩展工具。

在聊天视图中选项 Agent 模式时，可以点击工具图标配置可用工具。

在提示文件、自定义指令中，可以用 # 使用指定的工具。

部分工具涉及敏感操作会需要审批，可通过配置文件设置是否自动通过审批

创建工具集

在“聊天”视图 > “工具集” > “创建新的工具集文件”中选择“配置聊天，随后可使用 # 进行引用。

代理

代理是实现 AI 驱动的自主编码以及执行超出简单代码建议和聊天交互的多步任务的关键，它可以端到端地处理完整的编码任务。VSCode 中的代理分为本地代理、后台代理、云端代理和第三方代理。

本地代理：直接您的机器上的 VS Code 中运行。可以通过聊天与本地代理进行交互，以即时获得对提示的响应。本地代理在工作区上运行，并可以访问 VS Code 中提供的所有工具和模型。
后台代理：类似 Copilot CLI 的后台代理是基于 CLI 的代理，它们在您的本地机器上以非交互方式运行。后台代理可以使用 Git 工作树以隔离模式工作，以防止代码更改干扰您当前的工作区。
云端代理：云端代理在远程基础设施上运行，以执行 AI 驱动的编码任务。类似 Copilot 编码代理的云端代理与 GitHub 存储库和拉取请求集成，以实现团队协作和代码审阅。
第三方代理：由其他提供商（例如 OpenAI Codex）开发的后台代理

MCP

VSCode 支持添加 MCP 服务器，用户可以通过多种方式在 VS Code 中添加 MCP 服务器：

直接从 Web 安装：在您的网站上使用特殊的 MCP 安装 URL（vscode
/install）。
工作区配置：在工作区的 .vscode/mcp.json 文件中指定服务器配置。
全局配置：在用户配置文件中全局定义服务器。
自动发现：VSCode 可以从 Claude Desktop 等其他工具发现服务器。
扩展：VS Code 扩展可以通过编程方式注册 MCP 服务器。
命令行：使用 --add-mcp VSCode 命令行选项从命令行安装 MCP 服务器。

自定义

自定义指令

在 Markdown 文件中为诸如生成代码、执行代码审查或生成提交消息等任务定义通用指南或规则。

单个 .github/copilot-instructions.md 文件
- 自动应用于工作区中的所有聊天请求
- 存储在工作区中

VSCode 可以分析工作区并生成一个匹配的 .github/copilot-instructions.md 文件，其中包含符合项目编码实践和项目结构的自定义指令。

一个或多个 .instructions.md 文件
- 使用 glob 模式，根据文件类型或位置有条件地应用指令
- 存储在工作区或用户配置文件中
通过在指令文件头中使用 applyTo frontmatter 属性，您可以指定一个 glob 模式来定义指令应自动应用于哪些文件。
一个或多个 AGENTS.md 文件
- 如果您在工作区中使用多个 AI 代理，这将非常有用
- 自动应用于工作区中的所有聊天请求或特定子文件夹（实验性）
- 存储在工作区根目录或子文件夹中（实验性）

如果在工作区中使用多个 AI 代理，可以在工作区根目录的 AGENTS.md Markdown 文件中为所有代理定义自定义指令。VSCode 会自动将此文件中的指令应用于此工作区内的所有聊天请求。

提示文件

在 Markdown 文件中为常用且可重复的开发任务定义可重用的提示。提示文件是独立的提示，可以直接在聊天中运行它们。

提示文件是 Markdown 文件，使用 .prompt.md 扩展名，包含可选的头部和正文。在 YAML frontmatter 头部中配置以下字段:

字段	描述
description	对提示的简短描述。
name	提示的名称，在聊天中键入/后使用。如果未指定，则使用文件名。
argument-hint	在聊天输入字段中显示的可选提示文本，用于指导用户如何与提示进行交互。
agent	用于运行提示的代理：ask、edit、agent，或自定义代理的名称。默认情况下，使用当前代理。如果指定了工具且当前代理为 ask 或 edit，则默认代理为 agent。
model	运行提示时使用的语言模型。如果未指定，则使用模型选择器中当前选定的模型。
tools	可用于此提示的工具或工具集名称列表。可以包括内置工具、工具集、MCP工具或扩展程序提供的工具。要包含MCP服务器的所有工具，请使用 `<server name>/*` 格式。

在正文中可以编写需要发送给模型的具体提示文本。可以使用 Markdown 相对路径链接引用其他工作区文件。在正文文本中引用代理工具，请使用 #tool:<tool-name> 语法。

在提示文件中，您可以使用 ${variableName} 语法引用变量。

工作区变量：${workspaceFolder}、${workspaceFolderBasename}
选择变量：${selection}、${selectedText}
文件上下文变量：${file}、${fileBasename}、${fileDirname}、${fileBasenameNoExtension}
输入变量：${input:variableName}、${input:variableName:placeholder}（从聊天输入字段将值传递到提示）

示例如下：

md
---
agent: 'agent'
model: GPT-4o
tools: ['githubRepo', 'search/codebase']
description: 'Generate a new React form component'
---
Your goal is to generate a new React form component based on the templates in #tool:githubRepo contoso/react-templates.

Ask for the form name and fields if not provided.

Requirements for the form:
* Use form design system components: [design-system/Form.md](../docs/design-system/Form.md)
* Use `react-hook-form` for form state management:
* Always define TypeScript types for your form data
* Prefer *uncontrolled* components using register
* Use `defaultValues` to prevent unnecessary rerenders
* Use `yup` for validation:
* Create reusable validation schemas in separate files
* Use TypeScript types to ensure type safety
* Customize UX-friendly validation rules

可在聊天中通过 / 使用提示文件。

自定义代理

为特定角色或任务创建专家助手的方式，例如数据库管理员、前端开发或规划。在自定义代理 Markdown 文件中，可以描述其范围和功能、它可以访问的工具以及首选语言模型。

自定义代理定义在 .agent.md Markdown 文件中，可以存储在工作区供他人使用，也可以存储在用户配置文件中，以便在不同工作区中重复使用它们。

交接

交接功能使用户可以创建引导式顺序工作流，以建议的下一步操作在代理之间进行切换。聊天响应完成后，会出现交接按钮，允许用户将相关上下文和预填的提示传递到下一个代理。

代理文件结构

自定义代理文件是 Markdown 文件，使用 .agent.md 扩展名。此外，VSCode 会将工作区 .github/agents 文件夹中的任何 .md 文件识别为自定义代理。

在 YAML frontmatter 头部中可配置以下字段:

字段	描述
description	自定义代理的简短描述，显示为聊天输入字段中的占位符文本。
name	自定义代理的名称。如果未指定，则使用文件名。
argument-hint	显示在聊天输入字段中以指导用户如何与自定义代理交互的可选提示文本。
tools	可用于此自定义代理的工具或工具集名称列表。可以包括内置工具、工具集、MC P工具或扩展提供的工具。要包含 MCP 服务器的所有工具，请使用 `<server name>/*` 格式。了解有关聊天中的工具的更多信息。
model	运行提示时使用的AI模型。如果未指定，则使用模型选择器中当前选择的模型。
infer	可选的布尔标志，用于启用将自定义代理用作子代理（默认值为true）。
target	自定义代理的目标环境或上下文（vscode 或 github-copilot）。
mcp-servers	可选的模型上下文协议（MCP）服务器配置 json 列表，用于与 GitHub Copilot 中的自定义代理一起使用（目标：github-copilot）。
handoffs	可选的建议下一步操作或提示列表，用于在自定义代理之间进行切换。交接按钮在聊天响应完成后显示为交互式建议。
handoffs.label	显示在交接按钮上的显示文本。
handoffs.agent	要切换到的目标代理标识符。
handoffs.prompt	要发送到目标代理的提示文本。
handoffs.send	可选的布尔标志，用于自动提交提示（默认值为 false）。

示例：

md
---
description: Generate an implementation plan for new features or refactoring existing code.
name: Planner
tools: ['fetch', 'githubRepo', 'search', 'usages']
model: Claude Sonnet 4
handoffs:
  - label: Implement Plan
    agent: agent
    prompt: Implement the plan outlined above.
    send: false
---
# Planning instructions
You are in planning mode. Your task is to generate an implementation plan for a new feature or for refactoring existing code.
Don't make any code edits, just generate a plan.

The plan consists of a Markdown document that describes the implementation plan, including the following sections:

* Overview: A brief description of the feature or refactoring task.
* Requirements: A list of requirements for the feature or refactoring task.
* Implementation Steps: A detailed list of steps to implement the feature or refactoring task.
* Testing: A list of tests that need to be implemented to verify the feature or refactoring task.

语言模型

从为特定任务优化的不同 AI 模型中进行选。可以在模型之间切换，以获得最佳的代码生成、推理或视觉处理等专业任务的性能。携带自己的 API 密钥以访问更多模型或更好地控制模型托管。

MCP 和工具

通过模型上下文协议 (MCP) 连接外部服务和专业工具。这可以将聊天功能扩展到代码之外，以与数据库、API 和其他开发工具进行交互。

Claude 技能（实验性）

如果已在项目或用户配置文件中定义了 Claude 技能，则可以重用它们来定制在 VSCode 中的聊天交互。当启用 read 工具时，语言模型可以按需加载这些技能。

配置 Codex CLI

参考

VSCode 文档
- Vscode 的 copilot 使用文档
- Vscode 的 copilot 中文版使用文档
配置 Codex CLI