Copilot 最佳使用方式与深度配置指南

二、高级配置：打造强大的智能体

为了让 Copilot 发挥最大作用，需定义人工智能：理解项目规范、拥有合适工具并使用适合任务的模型。VS Code 提供了多种方法定制人工智能。

2.1 自定义指令：让 Copilot 懂你的项目

自定义指令允许定义通用指导方针和规则，自动影响 AI 生成代码的方式。无需在每个聊天提示中手动添加上下文，只需在 Markdown 文件中指定。

2.1.1 三种指令文件类型对比

2.1.2 创建指令文件的方法

在聊天视图中，选择配置聊天（齿轮图标）> 聊天指令，然后选择新建指令文件。

选择创建说明文件的位置：

• 工作区：在工作区的 .github/instructions 文件夹中创建。
• 用户配置文件：在当前配置文件文件夹中创建。

2.1.3 为工作区生成自定义指令 AGENTS.md

用自定义指令快速设置工作区的方法是在聊天输入框中输入 /init 斜线命令，Agent 会自动分析项目结构和编码模式，生成全面工作区说明 AGENTS.md。

2.1.4 编写有效指令的技巧

• 保持指令简短且完整。每条指令应是一个单一、简单的陈述。
• 包含规则背后的推理。
• 通过具体的代码示例展示推荐的模式和应避免的模式。
• 专注于不明显的规则。
• 对于特定任务或语言的指令，请每个主题使用多个 *.instructions.md 文件。

2.2 智能体技能（Agent Skills）：复用能力的利器

Copilot 可以配置 Agent Skills，用于教授专业能力和工作流程。

2.2.1 主要功能

2.2.2 智能体与自定义指令核心差异

2.2.3 创建智能体技能

类型：

• 项目级技能：.github/skills/
• 全局配置：~/.copilot/skills/

创建方法：

1. 在工作区中创建一个 .github/skills 目录。
2. 为你的技能创建一个子目录。
3. 在技能目录中创建一个 SKILL.md 文件。

SKILL.md 结构示例：

--- name: webapp-testing description: Guide for testing web applications using Playwright. Use this when asked to create or run browser-based tests. --- # 使用 Playwright 进行 Web 应用程序测试 本技能助力您运用 Playwright 为 Web 应用程序创建并运行基于浏览器的测试。 ## 何时使用本技能 当您需要以下操作时，使用本技能： - 为 Web 应用程序创建新的 Playwright 测试 - 调试失败的浏览器测试 - 为新项目搭建测试基础设施 ## 创建测试 1. 查看 [测试模板](./test-template.js)，了解标准测试结构 2. 确定要测试的用户流程 3. 在 `tests/` 目录中创建一个新的测试文件 4. 使用 Playwright 的定位器查找元素（优先选用基于角色的选择器） 5. 添加断言以验证预期行为 

元数据字段说明：

2.2.4 使用技能

技能可作为聊天中的斜杠命令使用。在聊天输入框中输入 /，即可查看可用技能和提示的列表。

2.2.5 添加外部技能

从 GitHub 仓库寻找可用技能，例如 Claude Code 官方技能库。

2.3 自定义智能体（Custom Agents）

通过 .agent.md 文件，你可以配置 AI 采用不同的角色身份，专注于特定的开发任务。

2.3.1 创建自定义智能体

自定义智能体通过 .agent.md Markdown 文件定义，使用 YAML 前置元数据配置元信息。

存放位置：

• 工作区级：.github/agents/ —— 仅当前工作区可用
• 用户配置：用户配置文件夹 —— 跨工作区共享

文件结构示例：

--- name: code-reviewer description: Specialized agent for thorough code reviews focusing on security, performance, and maintainability tools: - readFile - runTests model: gpt-4o user-invokable: true --- # 代码审查专家 你是一个经验丰富的代码审查专家，专注于以下维度： ## 审查维度 1. **安全性**：检查潜在的 SQL 注入、XSS、敏感信息泄露等安全风险 2. **性能**：识别 N+1 查询、内存泄漏、不必要的计算等性能瓶颈 3. **可维护性**：评估代码可读性、函数复杂度、命名规范等 4. **测试覆盖**：检查是否包含充分的单元测试和集成测试 ## 输出格式 请按以下结构输出审查结果： - **严重问题**（阻塞合并）：... - **建议优化**（可选）：... - **亮点**：... #tool:readFile #tool:runTests 

2.3.2 智能体配置参数详解

2.3.3 工作流交接（Handoffs）

工作流交接是自定义智能体的高级特性，允许你创建引导式顺序工作流，在不同智能体之间传递任务。

配置示例：

---name: planning-agent description: Creates detailed implementation plans before coding tools:- readFile - search handoffs:-label:"Execute this plan"agent: implementation-agent prompt:"Implement the following plan..."send:true---

典型的工作流设计： [需求分析智能体] ↓ handoff: "开始设计方案" [架构设计智能体] ↓ handoff: "开始编码实现" [开发实现智能体] ↓ handoff: "开始代码审查" [代码审查智能体] ↓ handoff: "合并并部署" [部署发布智能体]

2.3.4 创建第一个自定义智能体

假设我们需要一个专门负责 API 接口开发的智能体：

步骤 1：创建智能体文件 在 .github/agents/api-developer.agent.md 创建文件：

--- name: api-developer description: Specialized agent for API development with NestJS. Use this when creating RESTful APIs, defining DTOs, or implementing controllers and services. tools: - readFile - editFile - createFile - runTerminalCommand model: gpt-4o user-invokable: true --- # API 开发专家 你是一个专注于 NestJS 后端开发的专家，擅长设计 RESTful API、数据验证和业务逻辑实现。 ## 开发规范 ### 1. DTO 设计原则 - 使用 `class-validator` 进行属性验证 - 必填字段使用 `@IsNotEmpty()` 或 `@IsDefined()` - 可选字段使用 `@IsOptional()` - 枚举类型使用 `@IsEnum()` - 使用 `ApiProperty` 添加 Swagger 文档 ### 2. Controller 设计原则 - 使用 RESTful 命名规范 - 统一响应格式：`{ code: number, data: T, message: string }` - 使用装饰器进行权限控制 (`@Roles`, `@Permissions`) - 使用 `@ApiTags` 分组接口文档 ### 3. Service 设计原则 - 业务逻辑封装在 Service 层 - 使用 Repository 模式进行数据库操作 - 异常处理使用自定义异常类 - 日志记录使用 Winston 或 NestJS 内置 Logger ## 文件组织 src/modules/{module-name}/ ├── dto/ │ ├── create-{entity}.dto.ts │ ├── update-{entity}.dto.ts │ └── {operation}-{entity}.dto.ts ├── entities/ │ └── {entity}.entity.ts ├── {entity}.controller.ts ├── {entity}.service.ts └── {entity}.module.ts ## 代码示例 ### 创建 DTO ```typescript import { IsNotEmpty, IsString, IsOptional, IsEnum, IsNumber } from 'class-validator'; import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger'; export class CreateUserDto { @ApiProperty({ description: '用户名' }) @IsNotEmpty({ message: '用户名不能为空' }) @IsString() username: string; @ApiProperty({ description: '邮箱' }) @IsNotEmpty({ message: '邮箱不能为空' }) @IsEmail() email: string; @ApiPropertyOptional({ description: '年龄' }) @IsOptional() @IsNumber() age?: number; } ``` ### 创建 Controller ```typescript import { Controller, Get, Post, Body, Param, Query } from '@nestjs/common'; import { ApiTags, ApiOperation, ApiResponse } from '@nestjs/swagger'; import { UserService } from './user.service'; import { CreateUserDto } from './dto/create-user.dto'; @ApiTags('用户管理') @Controller('users') export class UserController { constructor(private readonly userService: UserService) {} @Post() @ApiOperation({ summary: '创建用户' }) @ApiResponse({ status: 201, description: '创建成功' }) create(@Body() createUserDto: CreateUserDto) { return this.userService.create(createUserDto); } @Get() @ApiOperation({ summary: '查询用户列表' }) findAll(@Query() query: QueryUserDto) { return this.userService.findAll(query); } } ``` ## 工具使用 #tool:readFile #tool:editFile #tool:createFile #tool:runTerminalCommand

步骤 2：使用智能体 创建完成后，你可以在 Copilot 聊天中直接调用这个智能体：

1. 通过斜杠命令：输入 /api-developer 然后描述你的需求。
2. 自动触发：当你在聊天中提到 API 相关任务时，Copilot 会根据描述自动加载该智能体。
3. 手动指定：使用 @ 符号选择智能体。

2.3.5 智能体的最佳实践

1. 角色边界清晰：每个智能体应该专注于一个明确的领域或任务。
2. 工具权限最小化：根据智能体的职责严格限制其可用工具。
3. 指令具体可执行：智能体的指令部分应该包含具体的、可操作的规范。
4. 工作流合理拆分：利用工作流交接（Handoffs）将任务分解为清晰的阶段。
5. 持续迭代优化：根据实际使用效果持续优化智能体配置。

2.4 钩子（Hooks）：自动化工作流的瑞士军刀

Hooks 允许你在智能体会话的关键生命周期节点执行自定义 shell 命令。

2.4.1 生命周期事件类型

2.4.2 钩子配置方式

Hooks 通过 JSON 文件配置，Copilot 会在以下位置搜索配置：

配置文件格式：

{"hooks":{"SessionStart":[{"type":"command","command":"node","args":["./scripts/get-project-info.js"],"cwd":"${workspaceFolder}","env":{"NODE_ENV":"development"},"timeout":30000}],"PreToolUse":[{"type":"command","command":"python","args":["security-check.py"],"windows":{"command":"python.exe"},"linux":{"command":"/usr/bin/python3"}}]}}

配置字段说明：

2.4.3 钩子输入输出协议

Hooks 通过标准输入（stdin）接收 JSON 格式的输入，通过标准输出（stdout）返回 JSON 格式的输出。

输入格式示例（PreToolUse）：

{"timestamp":"2024-01-15T09:30:00Z","cwd":"/home/user/project","sessionId":"sess_abc123","hookEventName":"PreToolUse","toolName":"editFile","toolInput":{"path":"src/config/database.ts","content":"..."}}

输出格式示例（PreToolUse 拦截危险操作）：

{"continue":false,"stopReason":"Potential destructive operation detected","systemMessage":"⚠️ 检测到可能危险的操作：正在尝试修改数据库配置文件。请确认此操作是经过授权的。","hookSpecificOutput":{"permissionDecision":"deny","updatedInput":null,"additionalContext":"This operation was blocked by security policy"}}

退出码含义：

2.4.4 典型使用场景

场景 1：拦截危险命令 使用 PreToolUse 钩子阻止破坏性操作。

场景 2：自动格式化代码 使用 PostToolUse 在文件修改后自动运行 Prettier。

场景 3：审计日志记录 使用 PreToolUse 和 PostToolUse 组合记录所有工具调用。

场景 4：注入会话上下文 使用 SessionStart 在会话开始时提供项目元数据。

2.4.5 安全与排错

安全注意事项：

1. 权限控制：Hooks 以 VS Code 相同的权限执行 shell 命令。
2. 最小权限原则：限制钩子脚本的权限范围。
3. 输入验证：验证所有输入参数。
4. 密钥管理：切勿在钩子脚本中硬编码敏感信息。

故障排查： 查看诊断信息：在 Chat 视图中右键 → Diagnostics（诊断），在 Output 面板中选择 GitHub Copilot Chat Hooks 查看钩子输出。

2.5 模型上下文协议（MCP）：连接外部世界的桥梁

MCP（Model Context Protocol）是一个开放标准，旨在为 AI 模型与外部世界提供统一的连接协议。

2.5.1 MCP 能做什么？

在 VS Code 中，MCP 服务器可以提供以下四种能力：

2.5.2 配置 MCP 服务器

在 VS Code 中，MCP 服务器通过 mcp.json 文件配置，支持两种配置位置：

配置文件结构：

{"servers":{"github":{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer ${env:GITHUB_TOKEN}"}},"playwright":{"type":"command","command":"npx","args":["-y","@microsoft/mcp-server-playwright"],"env":{"PLAYWRIGHT_BROWSERS_PATH":"0"}},"sqlite":{"type":"command","command":"uvx","args":["mcp-server-sqlite","--db-path","./data/app.db"]},"fetch":{"type":"http","url":"https://api.example.com/mcp/fetch","timeout":30000}}}

传输类型：

2.5.3 使用 MCP 服务器

配置完成后，MCP 服务器提供的工具会自动出现在 Copilot 的工具列表中。

工具调用： 当你在聊天中描述需要执行的操作时，Copilot 会自动选择合适的 MCP 工具。

Prompt 调用： MCP 服务器提供的预配置提示可以通过 /<server>.<prompt> 语法调用。

在智能体中使用： 你也可以在 .agent.md 文件中显式声明使用 MCP 工具。

2.5.4 MCP 与 Hooks 的协同

MCP 和 Hooks 虽然解决的问题不同，但可以形成强大的协同效应。

协同示例：数据操作的安全审查

1. [Copilot] 识别需要操作数据库
2. [MCP] 调用 mcp-sqlite/delete 工具
3. [Hooks - PreToolUse] 触发安全审查钩子
4. [Hooks] 返回 "ask" 决策，Copilot 询问用户确认
5. [User] 确认执行
6. [MCP] 执行实际的删除操作
7. [Hooks - PostToolUse] 记录审计日志

2.5.5 常用 MCP 服务器推荐

社区已经有很多现成的 MCP 服务器可以直接使用：

更多 MCP 服务器可以在 MCP 官方文档 和 社区服务器列表 中找到。

2.5.6 安全与最佳实践

安全注意事项：

1. 信任审查：VS Code 会在首次启动 MCP 服务器前提示信任确认。
2. 代码执行风险：本地 MCP 服务器可以执行任意代码，只使用可信来源的服务器。
3. 最小权限原则：为 MCP 服务器配置最小必要的权限。
4. 密钥管理：不要在 mcp.json 中硬编码敏感信息。

最佳实践：

1. 按需启用：不要一次性启用过多 MCP 服务器。
2. 命名规范：为 MCP 服务器使用清晰的命名。
3. 环境隔离：区分开发、测试、生产环境的 MCP 配置。
4. 定期审计：定期检查 MCP 服务器的使用情况。

重置信任状态：如需重新审查已信任的 MCP 服务器，使用命令 MCP: Reset Trust。

三、实战场景：Copilot 能帮你做什么？

3.1 端到端功能开发

用自然语言描述一项功能，智能体就会搭建项目架构、在多个文件中实现逻辑，并运行测试以验证结果。

3.2 调试并修复失败的测试

将智能体指向失败的测试，它会读取错误信息，在你的代码库中追踪根本原因，应用修复方案，并重新运行测试以确认。

3.3 重构或迁移代码库

让智能体规划一次迁移，例如从一个框架迁移到另一个框架，它会在文件间应用协调的更改，同时通过构建进行验证。

3.4 通过拉取请求进行协作

将任务委派给云智能体，它会创建分支、实施更改并打开拉取请求供团队审核。

四、总结：从"能用"到"好用"的关键配置

要让 Copilot 真正成为你的"专属项目管家"，关键在以下几点：

1. 基础能力用好：熟练掌握 Tab 补全、行内对话（Ctrl+I）、智能操作等日常功能。
2. 指令文件配好：根据项目规模选择合适的配置策略。
3. 技能体系建好：将重复性的工作流抽象为 Agent Skills。
4. 持续迭代优化：定期回顾指令文件的效果。

其实无论是 Claude Code、Cursor 还是 Copilot，工具只是手段，提升开发效率和代码质量才是目的。选择最适合你团队工作流的工具，搭配合理的配置，才能真正发挥 AI 辅助开发的威力。