为 GitHub Copilot 添加存储库自定义说明

在存储库中创建一个文件，该文件为 Copilot 在该存储库中的工作提供额外的上下文。

本文内容

注意

此功能目前为 公共预览版，可能会更改。

Visual Studio、VS Code 和 GitHub 网站上的 Copilot Chat 目前支持存储库自定义指令。 它们也支持 Copilot 编码智能体。

本文的此版本适用于在 GitHub 上使用存储库自定义说明。 单击上面的选项卡，获取有关在其他环境中使用自定义说明的信息。

有关可用于自定义 GitHub Copilot Chat 响应的方法的概述，请参阅“About customizing GitHub Copilot Chat responses”。 有关自定义 Copilot 编码智能体 的信息，请参阅 Customizing the development environment for Copilot coding agent。

关于 Copilot 的存储库自定义说明

GitHub Copilot 可基于你团队的工作方式、你使用的工具或项目的具体情况（如果提供足够的相关信息来满足此前提）提供量身定制的聊天响应。 无需重复将此详细信息添加到聊天问题中，而是可以在存储库中创建一个自动添加此信息的文件。 聊天中不会显示这些附加信息，但这些信息可供 Copilot 使用以便其能够生成更优质的响应。

向 Copilot 分配问题或请求其创建拉取请求时，它也会使用自定义说明文件。 此文件中包含的说明可帮助 Copilot 以匹配团队的工作实践且符合项目编码标准的方式来处理文件。 请参阅“About Copilot coding agent”。

示例

This example of a .github/copilot-instructions.md file contains three instructions for Copilot.

We use Bazel for managing our Java dependencies, not Maven, so when talking about Java packages, always give me instructions and code samples that use Bazel.

We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions.

Our team uses Jira for tracking items of work.

注意

Visual Studio、VS Code 和 GitHub 网站上的 Copilot Chat 目前支持存储库自定义指令。

本文的此版本适用于在 VS Code 中使用存储库自定义说明。 单击上面的选项卡，获取有关在其他环境中使用自定义说明的说明。

有关可用于自定义 GitHub Copilot Chat 响应的方法的概述，请参阅“About customizing GitHub Copilot Chat responses”。

关于 GitHub Copilot Chat

的存储库自定义指令和提示文件

GitHub Copilot 可基于你团队的工作方式、你使用的工具或项目的具体情况（如果提供足够的相关信息来满足此前提）提供量身定制的聊天响应。 无需重复将此详细信息添加到聊天问题中，而是可以在仓库中创建一个自动添加此信息的文件。

可使用两种类型的文件，在 VS Code 中提供 GitHub Copilot Chat 的上下文和指令：

  • 仓库自定义指令****，使你可通过单个文件指定适用于整个仓库的指令和偏好设置，这些设置适用于在该仓库上下文中进行的任何对话。
  • 提示文件（公共预览版）****，使你可以将常用的提示指令和相关上下文保存在 Markdown 文件 (*.prompt.md) 中，以便在聊天提示中重复使用。 提示文件仅在 VS Code 中可用。

虽然自定义说明有助于将代码库范围的上下文添加到每个 AI 工作流，但提示文件则使你能够向特定聊天交互添加说明。

仓库自定义指令示例

This example of a .github/copilot-instructions.md file contains three instructions for Copilot.

We use Bazel for managing our Java dependencies, not Maven, so when talking about Java packages, always give me instructions and code samples that use Bazel.

We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions.

Our team uses Jira for tracking items of work.

提示文件示例

以下示例演示了如何使用提示文件。

  • New React form.prompt.md - 包含有关使用 React 生成窗体的可重用任务的说明。

    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

  • API security review.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
…

注意

此功能目前为 公共预览版，可能会更改。

Visual Studio、VS Code 和 GitHub 网站上的 Copilot Chat 目前支持存储库自定义指令。

本文的此版本适用于在 Visual Studio 中使用存储库自定义说明。 单击上面的选项卡，获取有关在其他环境中使用自定义说明的说明。

有关可用于自定义 GitHub Copilot Chat 响应的方法的概述，请参阅“About customizing GitHub Copilot Chat responses”。

关于 GitHub Copilot Chat

的存储库自定义指令

GitHub Copilot 可基于你团队的工作方式、你使用的工具或项目的具体情况（如果提供足够的相关信息来满足此前提）提供量身定制的聊天响应。 无需重复将此详细信息添加到聊天问题中，而是可以在存储库中创建一个自动添加此信息的文件。 聊天中不会显示这些附加信息，但这些信息可供 Copilot 使用以便其能够生成更优质的响应。

示例

This example of a .github/copilot-instructions.md file contains three instructions for Copilot.

We use Bazel for managing our Java dependencies, not Maven, so when talking about Java packages, always give me instructions and code samples that use Bazel.

We always write JavaScript with double quotes and tabs for indentation, so when your responses include JavaScript code, please follow those conventions.

Our team uses Jira for tracking items of work.

仓库自定义指令的先决条件

  • 自定义说明文件（请参阅以下说明）。

创建存储库自定义说明文件

  1. 在存储库的根目录中，创建名为 .github/copilot-instructions.md 的文件。

    如果尚无 .github 目录，则创建该目录。

  2. 以 Markdown 格式在该文件中添加自然语言说明。

    系统会忽略说明信息间的空格，因此可将信息编写为一个段落，每个段落位于一行上，或用空白行分隔，以保持其可读性。

要查看你的指令实际效果，请前往 https://github.com/copilot，附加包含指令文件的仓库，然后开始一次对话。

你是否已成功将自定义指令文件添加到你的仓库中？

是 否

编写有效的存储库自定义说明

添加到 .github/copilot-instructions.md 文件的说明应为简短的自包含语句，这些语句包含可补充用户聊天问题的上下文或相关信息。

你还应考虑仓库的大小和复杂度。 以下类型的指令可能适用于仅有少数贡献者的小型仓库，但对于大型且多样化的仓库，可能会影响 Copilot 的其他区域：

  • 要求在提供的回答中引用外部资源
  • 有关按特定风格回答的说明
  • 要求始终以特定详细级别的信息来回答

例如，以下指令可能无法产生预期效果：

Always conform to the coding styles defined in styleguide.md in repo my-org/my-repo when generating code.

Use @terminal when answering questions about Git.

Answer all questions in the style of a friendly colleague, using informal language.

Answer all questions in less than 1000 characters, and words of no more than 12 characters.

使用中的存储库自定义说明

保存 .github/copilot-instructions.md 文件后，该文件中的指令便可供 Copilot Chat 使用。 完整的说明集将自动添加到与包含说明文件的存储库相关的聊天提示中。

在 Copilot Chat 的沉浸式视图 (github.com/copilot) 中，可以通过附加包含指令文件的存储库来发起使用存储库自定义指令的对话。

每当 Copilot Chat 使用存储库自定义指令时，指令文件都将被添加为所生成响应的引用。 要查看是否使用了仓库自定义指令，请展开“Chat”面板中聊天响应顶部的引用列表，检查是否列出了 .github/copilot-instructions.md 文件。

展开的“References”列表的屏幕截图，其中用深橙色边框突出显示了“copilot-instructions.md”文件。

可以单击引用信息来打开该文件。

注意

  • 可以向聊天应用多种类型的自定义指令。 个人指令具有最高优先级，存储库指令其次，组织指令的优先级最低。 但是，所有相关指令集仍将被合并并提供给 Copilot Chat。
  • 请尽可能避免提供冲突的指令集。 如果顾虑响应质量，也可以选择暂时禁用存储库说明。 请参阅“为 GitHub Copilot 添加存储库自定义说明”。

自定义说明在“聊天”视图或内联聊天中不可见，但可以通过查看“聊天”视图中的回复引用列表来验证 Copilot 是否正在使用这些说明。 如果将自定义说明添加到发送到模型的提示中，引用信息中会列出文件 .github/copilot-instructions.md。 可以单击引用信息来打开该文件。

展开的“References”列表的屏幕截图，其中用深橙色边框突出显示了“copilot-instructions.md”文件。

自定义说明在“聊天”视图或内联聊天中不可见，但可以通过查看“聊天”视图中的回复引用列表来验证 Copilot 是否正在使用这些说明。 如果将自定义说明添加到发送到模型的提示中，引用信息中会列出文件 .github/copilot-instructions.md。 可以单击引用信息来打开该文件。

“References”弹出窗口的屏幕截图，其中用深橙色边框突出显示了“copilot-instructions.md”文件。

启用或禁用存储库自定义说明

可以选择是否要将自定义说明添加到聊天问题。

  1. 单击“Chat”面板顶部或沉浸式页面右上角的 按钮。

  2. 单击“Disable custom instructions”或“Enable custom instructions”。********

    注意

    在沉浸式模式下，只有当附加了包含自定义说明文件的仓库时，才会看到这些选项。

你的选择将一直保留，直到你更改它。

  1. 使用键盘快捷方式 Command+, (Mac)/Ctrl+, (Linux/Windows) 打开“设置编辑器”。
  2. 在搜索框中键入 instruction file。
  3. 选中或清除“代码生成: 使用说明文件”**** 下的复选框。

  1. 在 Visual Studio 菜单栏中的“工具”下，单击“选项” 。

    Visual Studio 菜单栏的屏幕截图。 “工具”菜单已展开，“选项”项以橙色边框突出显示。

  2. 在“Options”对话框的搜索框中键入 custom instructions，然后单击“Copilot”****。

  3. 选中或清除复选框“(预览)允许加载 .github/copilot-instructions.md 文件中的自定义说明并将其添加到请求中”****。

启用并使用提示文件

注意

提示文件为公共预览版，可能会更改。

通过提示文件，你可以使用额外的上下文生成和共享可重用的提示说明。 提示文件是存储在工作区中的 Markdown 文件，它模仿 Copilot Chat 中编写提示的现有格式（例如，Rewrite #file:x.ts）。 你在工作区中可以有多个提示文件，每个提示文件都定义一个用于不同目的的提示。

启用提示文件

若要启用提示文件，请配置工作区设置。

  1. 按 Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac) 打开命令面板。
  2. 键入“Open Workspace Settings (JSON)”，然后选择显示的选项。
  3. 在 settings.json 文件中，添加 "chat.promptFiles": true 以启用 .github/prompts 文件夹作为提示文件的位置。 如果此文件夹尚不存在，系统将创建它。

创建提示文件

  1. 按 Ctrl+Shift+P (Windows/Linux) / Command+Shift+P (Mac) 打开命令面板。

  2. 键入“prompt”并选择“Chat: Create Prompt”****。

  3. 输入提示文件的名称，不包括 .prompt.md 文件扩展名。 该名称可以包含字母数字字符和空格，且应描述文件将包含的提示信息的目的。

  4. 使用 Markdown 格式编写提示说明。

    可以使用 Markdown 链接（例如 [index](../../web/index.ts)）或使用 #file:../../web/index.ts 语法来引用工作区中的其他文件。 路径是相对于提示文件的。 通过引用其他文件，可以提供其他上下文，例如 API 规范或产品文档。

使用提示文件

  1. 在 Copilot Chat 视图底部，单击“Attach context”图标 ()****。

  2. 在下拉菜单中，单击“Prompt...”并选择要使用的提示文件****。

  3. （可选）附加其他文件（包括提示文件）以提供更多上下文。

  4. （可选）在聊天提示框中键入其他信息。

    是否需要执行此操作取决于所使用的提示的内容。

  5. 提交聊天提示。

有关提示文件的详细信息，请参阅 Visual Studio Code 文档中的“VS Code 中 GitHub Copilot 的自定义说明”。