🚀 在 VS Code 中

VS Code 中 GitHub Copilot 的自定义指令

您可以通过向 Copilot 提供有关团队的工作流程、工具或项目细节的上下文详细信息来增强 Copilot 的聊天响应。 您无需在每个聊天查询中手动包含此上下文,而是可以创建一个自定义指令文件,该文件会自动将此信息与每个聊天请求合并。

Copilot 将这些指令应用于聊天视图、快速聊天或内联聊天中的聊天提示。 这些指令不会显示在聊天中,但会由 VS Code 传递给 Copilot。

您可以为特定目的指定自定义指令

  • 代码生成指令 - 提供特定于生成代码的上下文。 例如,您可以指定私有变量应始终以强调符作为前缀,或者单例应以某种特定方式实现。 您可以在设置中或工作区中的 Markdown 文件中指定代码生成指令。

  • 测试生成指令 - 提供特定于生成测试的上下文。 例如,您可以指定所有生成的测试都应使用特定的测试框架。 您可以在设置中或工作区中的 Markdown 文件中指定测试生成指令。

  • 代码审查指令 - 提供特定于审查当前编辑器选择内容的上下文。 例如,您可以指定审查者应在代码中查找特定类型的错误。 您可以在设置中或工作区中的 Markdown 文件中指定审查选择指令。

  • 提交消息生成指令 - 提供特定于生成提交消息的上下文。 您可以在设置中或工作区中的 Markdown 文件中指定提交消息生成指令。

  • 拉取请求标题和描述生成指令 - 提供特定于生成拉取请求标题和描述的上下文。 您可以在设置中或工作区中的 Markdown 文件中指定拉取请求标题和描述生成指令。

自定义指令由自然语言指令组成,并且应是简短、独立的语句,用于添加上下文或相关信息以补充聊天问题。

定义代码生成自定义指令

Copilot 可以帮助您生成代码,例如作为重构、生成单元测试或实现功能的一部分。 您可能希望在项目中使用特定的库,或者希望 Copilot 生成的代码遵循特定的编码风格。

注意

Copilot 不会将代码生成指令应用于代码补全

使用设置

您可以使用 github.copilot.chat.codeGeneration.instructions 设置来配置自定义代码生成指令。 您可以在用户或工作区级别定义自定义指令,并且还可以指定特定于语言的指令。 获取有关特定于语言的设置的更多信息。

以下代码片段显示了如何在 settings.json 文件中定义一组指令。 要直接在设置中定义指令,请配置 text 属性。 要引用外部文件,请配置 file 属性。

  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Always add a comment: 'Generated by Copilot'."
    },
    {
      "text": "In TypeScript always use underscore for private field names."
    },
    {
      "file": "code-style.md" // import instructions from file `code-style.md`
    }
  ],

code-style.md 文件的内容示例

Always use React functional components.

Always add comments.

使用 .github/copilot-instructions.md 文件

您还可以将自定义指令存储在工作区或存储库中的 .github/copilot-instructions.md 文件中,并让 VS Code 自动拾取此文件。

如果您在 .github/copilot-instructions.md 文件和设置中都定义了自定义指令,则 Copilot 会尝试合并来自这两个来源的指令。

注意

Visual Studio 中的 GitHub Copilot 也会检测 .github/copilot-instructions.md 文件。 如果您有一个在 VS Code 和 Visual Studio 中都使用的工作区,则可以使用同一文件为这两个编辑器定义自定义指令。

  1. github.copilot.chat.codeGeneration.useInstructionFiles 设置为 true,以指示 VS Code 中的 Copilot 使用自定义指令文件。

  2. 在工作区的根目录中创建 .github/copilot-instructions.md 文件。 如果需要,请先创建 .github 目录。

    提示

    在 VS Code 的资源管理器视图中,您可以通过键入完整路径作为文件名来一步创建文件夹和文件。

  3. 将自然语言指令添加到文件中。 您可以使用 Markdown 格式。

    指令之间的空格将被忽略,因此指令可以写成一个段落,每行一条指令,或者用空行分隔以提高可读性。

定义测试生成自定义指令

您可以使用 Copilot 为您的代码生成测试,例如通过在聊天视图中使用 @workspace /tests 提示。 您可以定义自定义指令,以帮助 Copilot 生成特定于您的项目和开发工作流程的测试。

要配置自定义测试生成指令,请使用 github.copilot.chat.testGeneration.instructions 设置。 您可以在用户或工作区级别定义自定义指令。

以下代码片段显示了如何在 settings.json 文件中定义一组指令。 要直接在设置中定义指令,请配置 text 属性。 要引用外部文件,请配置 file 属性。

  "github.copilot.chat.testGeneration.instructions": [
    {
      "text": "Always use vitest for testing React components."
    },
    {
      "text": "Use Jest for testing JavaScript code."
    },
    {
      "file": "code-style.md" // import instructions from file `code-style.md`
    }
  ],

code-style.md 文件的内容示例

Always add code comments.

Always use React functional components.

定义代码审查自定义指令

您可以使用 Copilot 审查编辑器中选择的代码。 您可以定义自定义指令,以帮助 Copilot 考虑与您的项目和开发工作流程相关的特定代码审查标准。

要配置自定义代码审查指令,请使用 github.copilot.chat.reviewSelection.instructions 设置。 您可以在用户或工作区级别定义自定义指令。

定义提交消息生成自定义指令

在源代码管理视图中,您可以使用 Copilot 为待处理的代码更改生成提交消息。 您可以定义自定义指令,以帮助 Copilot 生成考虑到特定于您的项目和开发工作流程的特定格式和结构的提交消息。

要配置自定义提交消息生成指令,请使用 github.copilot.chat.commitMessageGeneration.instructions 设置。 您可以在用户或工作区级别定义自定义指令。

定义拉取请求标题和描述生成自定义指令

当您安装了 GitHub Pull Requests 扩展时,您可以使用 Copilot 为拉取请求生成标题和描述。 您可以定义自定义指令,以帮助 Copilot 生成考虑到特定于您的项目和开发工作流程的特定格式和结构的标题和描述。

要配置自定义拉取请求标题和描述生成指令,请使用 github.copilot.chat.pullRequestDescriptionGeneration.instructions 设置。 您可以在用户或工作区级别定义自定义指令。

定义自定义指令的技巧

  • 保持指令简短且独立。 每个指令都应是一个简单的独立语句。 如果您需要提供多条信息,请使用多个指令。

  • 不要在指令中引用外部资源,例如特定的编码标准。

  • 通过将指令存储在外部文件中,可以轻松地与团队或跨项目共享自定义指令。 您还可以对文件进行版本控制,以跟踪随时间的变化。

可重用提示文件(实验性)

提示文件 (prompts) 使您能够构建和共享具有附加上下文的可重用提示指令。 提示文件是一个 Markdown 文件,它模仿在 Copilot 聊天中编写提示的现有格式(例如,Rewrite #file:x.ts)。 这允许混合自然语言指令、附加上下文,甚至链接到其他提示文件作为依赖项。

虽然自定义指令有助于为每个 AI 工作流程添加代码库范围的上下文,但提示文件使您可以为特定的聊天交互添加指令。

常见用例包括

  • 代码生成:为组件、测试或迁移创建可重用提示(例如,React 表单或 API 模拟)。
  • 领域专业知识:通过提示共享专业知识,例如安全实践或合规性检查。
  • 团队协作:使用对规范和文档的引用来记录模式和指南。
  • 入职:为复杂流程或特定于项目的模式创建分步指南。

提示文件示例

  • react-form.prompt.md - 记录用于生成表单的可重用任务

    Your goal is to generate a new React form component.
    
    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
    
  • security-api.prompt.md - 记录 REST API 的可重用安全实践,可用于对 REST API 进行安全审查

    Secure REST API review:
    * Ensure all endpoints are protected by authentication and authorization
    * Validate all user inputs and sanitize data
    * Implement rate limiting and throttling
    * Implement logging and monitoring for security events
    
    

用法

要启用提示文件,请配置 chat.promptFiles VS Code 设置。 默认情况下,提示文件位于工作区的 .github/prompts 目录中。 您还可以指定提示文件所在的附加文件夹

创建提示文件

  1. .github/prompts 目录的 chat.promptFiles 设置设置为 true

  2. 在工作区的 .github/prompts 目录中创建 .prompt.md 文件。

    或者,使用命令面板中的创建提示命令 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。

  3. 使用 Markdown 格式编写提示指令。

    在提示文件中,将其他工作区文件引用为 Markdown 链接 ([index](../index.ts)),或作为提示文件中的 #file:../index.ts 引用。

    您还可以引用其他 .prompt.md 文件来创建提示层次结构,其中包含可在多个提示文件中共享的可重用提示。

创建用户提示文件

用户提示文件存储在您的用户配置文件中。 使用用户提示文件,您可以在多个工作区之间共享可重用提示。

您可以像添加工作区提示文件一样,将用户提示文件添加到聊天提示中。

要创建用户提示文件

  1. 从命令面板中选择创建用户提示命令 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。

  2. 输入提示文件的名称。

  3. 使用 Markdown 格式编写提示指令。

用户提示文件现在可以使用设置同步在多个设备之间同步。 确保在您的设置同步配置中启用对提示文件的支持。 从命令面板中选择设置同步:配置,并确保选中提示

将提示文件附加到聊天请求

  1. 选择附加上下文 图标 (⌘/ (Windows, Linux Ctrl+/)),然后选择提示...

    或者,使用命令面板中的聊天:使用提示命令 (⇧⌘P (Windows, Linux Ctrl+Shift+P))。

  2. 从快速选择中选择一个提示文件以将其附加到您的聊天请求。

    您可以在 Copilot 聊天和 Copilot 编辑中使用提示文件。

  3. (可选)附加任务所需的其他上下文文件。

    对于可重用任务,请发送不带任何其他指令的提示。

    要进一步改进可重用提示,请包含其他指令以提供更多手头任务的上下文。

提示

使用 Markdown 链接引用其他上下文文件(如 API 规范或文档),以便为 Copilot 提供更完整的信息。

设置

自定义指令设置

  • github.copilot.chat.codeGeneration.useInstructionFiles:控制是否将来自 .github/copilot-instructions.md 的代码指令添加到 Copilot 请求中。
  • github.copilot.chat.codeGeneration.instructions (实验性):将添加到生成代码的 Copilot 请求中的一组指令。
  • github.copilot.chat.testGeneration.instructions (实验性):将添加到生成测试的 Copilot 请求中的一组指令。
  • github.copilot.chat.reviewSelection.instructions (预览):将添加到用于审查当前编辑器选择内容的 Copilot 请求中的一组指令。
  • github.copilot.chat.commitMessageGeneration.instructions (实验性):将添加到生成提交消息的 Copilot 请求中的一组指令。
  • github.copilot.chat.pullRequestDescriptionGeneration.instructions (实验性):将添加到生成拉取请求标题和描述的 Copilot 请求中的一组指令。

提示文件(实验性)设置

  • chat.promptFiles (实验性):启用可重用提示文件。

  • chat.promptFilesLocations (实验性):提示文件所在的文件夹列表。 您可以指定一个或多个提示文件所在的文件夹。 相对路径从工作区的根文件夹解析。 支持文件路径的 glob 模式。

    设置值 描述
    ["/path/to/folder"] 为特定路径启用提示文件。 指定一个或多个提示文件所在的文件夹。 相对路径从工作区的根文件夹解析。
    默认情况下,.github/prompts 已添加但已禁用。