Skip to main content

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

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

注意

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

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

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

注意

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

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

注意

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

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

注意

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

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

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

通过存储库自定义说明,可以为 Copilot 提供特定于存储库的指导和首选项。

目前以下项支持仓库自定义指令:

  • VS Code 中的 Copilot Chat****
  • Copilot 编码智能体
  • Visual Studio、JetBrains IDE、Xcode 中和 GitHub 网站上的 Copilot Chat(仅限 copilot-instructions.md 文件)****
  • Copilot 代码评审(仅限 copilot-instructions.md 文件)

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

  • 必须有自定义指令文件(请参阅以下指令)。
  • 必须在 JetBrains IDE 中安装 Copilot 扩展的最新版本。
  • 必须在 Xcode 中安装 Copilot 扩展的最新版本。

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

JetBrains IDE 支持存储在存储库中的单个 .github/copilot-instructions.md 自定义说明文件。

可使用 Copilot 设置页在存储库中创建自定义说明文件,也可以手动创建该文件。

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

使用设置页

  1. 在 JetBrains IDE 中,单击“文件”**** 菜单 (Windows) 或菜单栏中的应用程序名称 (macOS),然后单击“设置”****。1. 在“语言和框架”下,单击 GitHub Copilot 。
  2. 在“Copilot Instructions”下,单击“Workspace”或“Global”,选择自定义说明是应用于当前工作区还是适用于所有工作区********。

手动创建工作区自定义说明文件

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

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

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

保存后,这些说明将应用于在启用 Copilot 的 JetBrains IDE 中打开的当前工作区。

手动创建全局自定义说明文件

要在 JetBrains IDE 中的所有工作区中应用相同的说明,可以在本地计算机上创建全局自定义说明文件。

  1. 打开文件资源管理器或终端。

  2. 导航到操作系统的相应位置:

    • macOS:/Users/YOUR-USERNAME/.config/github-copilot/intellij/
    • WindowsC:\Users\YOUR-USERNAME\AppData\Local\github-copilot\intellij\
  3. 在此目录中创建名为 global-copilot-instructions.md 的文件。

  4. 使用 Markdown 格式以自然语言添加自定义说明。

保存后,这些说明将全局应用于你在启用 Copilot 的 JetBrains IDE 中打开的所有工作区。

Xcode 支持存储在存储库中的单个 .github/copilot-instructions.md 自定义说明文件。

可通过 Copilot 设置页在存储库中创建自定义说明文件。

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

  1. 打开 GitHub Copilot for Xcode 应用程序。
  2. 在应用程序窗口顶部的“Settings”下,单击“Advanced”********。
  3. 在“Custom Instructions”的右侧,单击“Current Workspace”或“Global”,选择自定义说明是应用于当前工作区还是适用于所有工作区********。

VS Code 支持以下任一项:

  • 存储在存储库中的单个 .github/copilot-instructions.md 自定义说明文件
  • 存储在存储库中 .github/instructions 内的一个或多个 .instructions.md 文件。 每个文件都可以指定 applyTo 前辅文,以定义其说明适用的文件或目录。

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

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

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

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

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

使用一个或多个 .instructions.md 文件

  1. 如果尚无 .github/instructions 目录,则创建该目录。

  2. 创建一个或多个 .instructions.md 文件,向(这些)文件添加自然语言说明。

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

  3. 通过使用 glob 语法将 applyTo 前辅文添加到 Markdown 文件,指定说明适用的文件或目录。

    ---
    applyTo: "app/models/**/*.rb"
    ---
    
    Add custom instructions here
    

    若要将说明应用于所有文件,请使用 ** 模式。

Visual Studio 支持存储在存储库中的单个 .github/copilot-instructions.md 自定义说明文件。

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

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

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

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

GitHub 网站上的 Copilot Chat 和 Copilot 代码评审 支持存储在存储库中的单个 .github/copilot-instructions.md 自定义说明文件********。

此外,Copilot 编码智能体 支持存储在存储库中 .github/instructions 内的一个或多个 .instructions.md 文件****。 每个文件都可以指定 applyTo 前辅文,以定义其说明适用的文件或目录。

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

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

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

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

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

使用一个或多个 .instructions.md 文件

  1. 如果尚无 .github/instructions 目录,则创建该目录。

  2. 创建一个或多个 .instructions.md 文件,向(这些)文件添加自然语言说明。

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

  3. 通过使用 glob 语法将 applyTo 前辅文添加到 Markdown 文件,指定说明适用的文件或目录。

    ---
    applyTo: "app/models/**/*.rb"
    ---
    
    Add custom instructions here
    

    若要将说明应用于所有文件,请使用 ** 模式。

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

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

添加到自定义说明文件的说明应是简短的自包含语句,这些语句为 Copilot 提供相关信息,以帮助它在此存储库中工作。 由于这些说明随每个聊天消息一起发送,因此它们应广泛适用于你将在存储库上下文中发出的大多数请求。

用于说明文件的确切结构因项目和需求而异,但以下准则提供了一个很好的起点:

  • 提供正在处理的项目的概述,包括其用途、目标和任何相关的背景信息。
  • 包括存储库的文件夹结构,包括与项目相关的任何重要目录或文件。
  • 指定应遵循的编码标准和约定,例如命名约定、格式规则和最佳做法。
  • 包括项目中使用的任何特定工具、库或框架,以及任何相关的版本号或配置。

以下说明文件是这些做法的一个实践示例:

# Project Overview

This project is a web application that allows users to manage their tasks and to-do lists. It is built using React and Node.js, and uses MongoDB for data storage.

## Folder Structure

- `/src`: Contains the source code for the frontend.
- `/server`: Contains the source code for the Node.js backend.
- `/docs`: Contains documentation for the project, including API specifications and user guides.

## Libraries and Frameworks

- React and Tailwind CSS for the frontend.
- Node.js and Express for the backend.
- MongoDB for data storage.

## Coding Standards

- Use semicolons at the end of each statement.
- Use single quotes for strings.
- Use function based components in React.
- Use arrow functions for callbacks.

## UI guidelines

- A toggle is provided to switch between light and dark mode.
- Application should have a modern and clean design.

你还应考虑仓库的大小和复杂度。 以下类型的指令仅适用于只有少数参与者的小型存储库,但对于大型和多样化的存储库,这可能会导致问题****:

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

例如,以下指令可能无法获得预期结果****:

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.

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

保存文件后,文件中的说明便可供 Copilot Chat 使用。 系统会将完整指令集自动添加到你在该存储库上下文中提交到 Copilot 的请求中。 例如,系统会将它们添加到你提交到 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”文件。

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

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

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

可以选择是否要让 Copilot 使用基于仓库的自定义指令。

为 Copilot Chat 启用或禁用自定义指令

默认情况下,Copilot Chat 已启用自定义指令,但你可以随时禁用或重新启用它们。 这适用于你自己的 Copilot Chat 使用,不会影响其他用户。

  1. 在 GitHub.com 上,执行下列操作之一:

    • 转到使用自定义指令文件的存储库,打开辅助聊天面板。
    • 转到 Copilot Chat (github.com/copilot) 的沉浸式视图,并附加包含自定义指令文件的存储库。
  2. 单击“Chat”面板顶部或沉浸式页面右上角的 按钮。

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

    注意

    只会在包含自定义指令文件的存储库上下文中看到这些选项。

对于包含自定义指令文件的所有存储库,你的选择将一直保留,直到更改为止。

为 Copilot 代码评审 启用或禁用自定义指令

默认情况下,Copilot 代码评审 已启用自定义指令,但你可以在 GitHub.com 上的仓库设置中禁用或重新启用它们。 这适用于 Copilot 对此仓库中执行的所有代码评审使用自定义指令。

  1. 在 GitHub 上,导航到存储库的主页面。

  2. 在存储库名称下,单击 “设置”。 如果看不到“设置”选项卡,请选择“”下拉菜单,然后单击“设置”。

    存储库标头的屏幕截图,其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“Code & automation”部分,单击 Copilot,然后单击“Code review”********。

  4. 打开或关闭“Use custom instructions when reviewing pull requests”选项。

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

可以选择是否要让 Copilot 使用基于仓库的自定义指令。

为 Copilot Chat 启用或禁用自定义指令

默认情况下,Copilot Chat 已启用自定义指令,但你可以随时禁用或重新启用它们。 这适用于你自己的 Copilot Chat 使用,不会影响其他用户。

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

为 Copilot 代码评审 启用或禁用自定义指令

默认情况下,Copilot 代码评审 已启用自定义指令,但你可以在 GitHub.com 上的仓库设置中禁用或重新启用它们。 这适用于 Copilot 对此仓库中执行的所有代码评审使用自定义指令。

  1. 在 GitHub 上,导航到存储库的主页面。

  2. 在存储库名称下,单击 “设置”。 如果看不到“设置”选项卡,请选择“”下拉菜单,然后单击“设置”。

    存储库标头的屏幕截图,其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“Code & automation”部分,单击 Copilot,然后单击“Code review”********。

  4. 打开或关闭“Use custom instructions when reviewing pull requests”选项。

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

可以选择是否要让 Copilot 使用基于仓库的自定义指令。

为 Copilot Chat 启用或禁用自定义指令

默认情况下,Copilot Chat 已启用自定义指令,但你可以随时禁用或重新启用它们。 这适用于你自己的 Copilot Chat 使用,不会影响其他用户。

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

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

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

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

为 Copilot 代码评审 启用或禁用自定义指令

默认情况下,Copilot 代码评审 已启用自定义指令,但你可以在 GitHub.com 上的仓库设置中禁用或重新启用它们。 这适用于 Copilot 对此仓库中执行的所有代码评审使用自定义指令。

  1. 在 GitHub 上,导航到存储库的主页面。

  2. 在存储库名称下,单击 “设置”。 如果看不到“设置”选项卡,请选择“”下拉菜单,然后单击“设置”。

    存储库标头的屏幕截图,其中显示了选项卡。 “设置”选项卡以深橙色边框突出显示。

  3. 在边栏的“Code & automation”部分,单击 Copilot,然后单击“Code review”********。

  4. 打开或关闭“Use custom instructions when reviewing pull requests”选项。

启用并使用提示文件

注意

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

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