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

在仓库中创建一个文件，自动向询问 Copilot Chat 的问题中添加信息。

本文内容

Note

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

Repository custom instructions are currently supported for Copilot Chat in Visual Studio, VS Code and on the GitHub website.

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

有关可用于自定义 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 that will be added to all chat questions.

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.

Note

Repository custom instructions are currently supported for Copilot Chat in Visual Studio, VS Code and on the GitHub website.

本文的此版本适用于在 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 that will be added to all chat questions.

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
…

Note

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

Repository custom instructions are currently supported for Copilot Chat in Visual Studio, VS Code and on the GitHub website.

本文的此版本适用于在 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 that will be added to all chat questions.

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”文件。

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

Note

  • It is possible for multiple types of custom instructions to apply to a conversation. Personal instructions take the highest priority, followed by repository instructions, with organization instructions prioritized last. However, all sets of relevant instructions are still combined and provided to Copilot Chat.
  • Whenever possible, you should avoid providing conflicting sets of instructions. If you are concerned about response quality, you can also choose to temporarily disable repository instructions. See 为 GitHub Copilot 添加存储库自定义说明.

保存文件后，.github/copilot-instructions.md 文件中的说明便可即刻供 Copilot Chat 使用。 系统会自动将完整说明集附加到在 Copilot Chat 视图或内联聊天中提交的请求中。

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

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

保存文件后，.github/copilot-instructions.md 文件中的说明便可即刻供 Copilot Chat 使用。 系统会自动将完整说明集附加到在 Copilot Chat 视图或内联聊天中提交的请求中。

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

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

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

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

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

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

    Note

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

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

  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 文件中的自定义说明并将其添加到请求中”****。

启用并使用提示文件

Note

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

通过提示文件，你可以使用额外的上下文生成和共享可重用的提示说明。 提示文件是存储在工作区中的 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 的自定义说明”。