在 VS Code 中试试

自定义 VS Code 中的聊天回复

如果提供正确的上下文,Copilot 可以提供符合你的编码实践和项目要求的回复。通过自定义指令,你可以定义和自动应用代码生成或代码审查等任务的指南和规则。Prompt 文件允许你在 Markdown 文件中编写完整的聊天提示,然后你可以在聊天中引用或与他人共享这些提示。在本文中,你将了解如何使用自定义指令和 Prompt 文件来自定义 Visual Studio Code 中的聊天回复。

指令文件

自定义指令允许你描述通用指南或规则,以获得符合你特定编码实践和技术栈的回复。自定义指令不是在每个聊天查询中手动包含此上下文,而是自动将此信息包含在每个聊天请求中。

VS Code 支持多种类型的自定义指令,针对不同的场景:代码生成、测试生成、代码审查、提交消息生成以及拉取请求标题和描述生成指令。

你可以通过两种方式定义自定义指令

  1. 指令文件:在 Markdown 文件中为你的工作区或 VS Code 配置文件指定代码生成指令。
  2. 设置:在 VS Code 用户或工作区设置中指定指令。

使用指令文件

指令文件允许你在 Markdown 文件中指定自定义指令。你可以使用这些文件定义你的编码实践、首选技术和项目要求。

指令文件有两种类型

  • .github/copilot-instructions.md:一个指令文件,其中包含工作区的所有指令。这些指令会自动包含在每个聊天请求中。

  • .instructions.md 文件:一个或多个包含特定任务自定义指令的 prompt 文件。你可以将单个 prompt 文件附加到聊天请求,或者将其配置为自动包含在特定文件或文件夹中。

如果你同时指定这两种指令文件,它们都会包含在聊天请求中。指令不应用特定的顺序或优先级。确保在文件中避免冲突的指令。

注意

指令文件仅用于代码生成,不用于 代码补全

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

你可以将自定义指令存储在工作区或仓库中的 .github/copilot-instructions.md 文件中,并使用 Markdown 描述你的编码实践、首选技术和项目要求。这些指令仅适用于文件所在的工作区。

VS Code 会自动将 .github/copilot-instructions.md 文件中的指令包含在每个聊天请求中,并将其应用于代码生成。

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

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

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

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

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

注意

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

使用 .instructions.md 文件

你还可以创建一个或多个 .instructions.md 文件来存储特定任务的自定义指令。例如,你可以为不同的编程语言、框架或项目类型创建指令文件。

VS Code 支持两种范围的指令文件

  • 工作区指令文件:仅在工作区内可用,存储在工作区的 .github/instructions 文件夹中。
  • 用户指令文件:可在多个工作区中使用,存储在当前的 VS Code 配置文件中。

指令文件是带有 .instructions.md 文件后缀的 Markdown 文件。指令文件包含两个部分

  • (可选)带元数据的头部(Front Matter 语法)

    属性 描述
    applyTo 指定指令自动应用于哪些文件的 glob 模式。若要始终包含自定义指令,请使用 ** 模式。

    例如,以下指令文件始终应用

    ---
    applyTo: "**"
    ---
    Add a comment at the end of the file: 'Contains AI-generated edits.'
    
  • 包含指令内容的 Body

    使用 Markdown 格式以自然语言指定自定义指令。你可以使用标题、列表和代码块来构建指令。

    你可以使用 Markdown 链接引用其他指令文件。使用相对路径引用这些文件,并确保路径相对于指令文件位置正确。

创建指令文件

  1. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 新建指令文件命令。

  2. 选择应创建指令文件的位置。

    用户指令文件存储在当前配置文件文件夹中。你可以使用设置同步在多个设备上同步用户指令文件。确保在设置同步: 配置命令中配置提示和指令设置。

    工作区指令文件默认存储在工作区的 .github/instructions 文件夹中。使用 chat.instructionsFilesLocations 设置为工作区添加更多指令文件夹。

  3. 输入指令文件的名称。

  4. 使用 Markdown 格式编写自定义指令。

    在工作区指令文件中,可以将其他工作区文件引用为 Markdown 链接([index](../index.ts)),或在指令文件中引用为 #index.ts

若要在聊天提示中使用指令文件,你可以选择

  • 在聊天视图中,选择添加上下文 > 指令,然后从快速选择中选择指令文件。
  • 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 附加指令命令,然后从快速选择中选择指令文件。
  • 在指令文件头中配置 applyTo 属性,以自动将指令应用于特定文件或文件夹。

在设置中指定自定义指令

你还可以在用户或工作区设置中配置自定义指令。针对不同的场景有特定的设置。指令会自动应用于特定任务。

下表列出了每种自定义指令类型的设置。

指令类型 设置名称
代码生成 github.copilot.chat.codeGeneration.instructions
测试生成 github.copilot.chat.testGeneration.instructions
代码审查 github.copilot.chat.reviewSelection.instructions
提交消息生成 github.copilot.chat.commitMessageGeneration.instructions
拉取请求标题和描述生成 github.copilot.chat.pullRequestDescriptionGeneration.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": "general.instructions.md" // import instructions from file `general.instructions.md`
    },
    {
      "file": "db.instructions.md" // import instructions from file `db.instructions.md`
    }
  ],

自定义指令示例

以下示例展示了代码生成的自定义指令

  • 在适用于所有代码的 .github/instructions/general-coding.instructions.md 文件中定义通用编码指南

    ---
    applyTo: "**"
    ---
    # Project general coding standards
    
    ## Naming Conventions
    - Use PascalCase for component names, interfaces, and type aliases
    - Use camelCase for variables, functions, and methods
    - Prefix private class members with underscore (_)
    - Use ALL_CAPS for constants
    
    ## Error Handling
    - Use try/catch blocks for async operations
    - Implement proper error boundaries in React components
    - Always log errors with contextual information
    
  • 在适用于 TypeScript 和 React 代码的 .github/instructions/typescript-react.instructions.md 文件中定义 TypeScript 和 React 编码指南,通用编码指南会被继承

    ---
    applyTo: "**/*.ts,**/*.tsx"
    ---
    # Project coding standards for TypeScript and React
    
    Apply the [general coding guidelines](./general-coding.intructions.md) to all code.
    
    ## TypeScript Guidelines
    - Use TypeScript for all new code
    - Follow functional programming principles where possible
    - Use interfaces for data structures and type definitions
    - Prefer immutable data (const, readonly)
    - Use optional chaining (?.) and nullish coalescing (??) operators
    
    ## React Guidelines
    - Use functional components with hooks
    - Follow the React hooks rules (no conditional hooks)
    - Use React.FC type for components with children
    - Keep components small and focused
    - Use CSS modules for component styling
    

定义自定义指令的提示

  • 保持指令简短且自包含。每条指令应是一个简单、独立的陈述。如果需要提供多条信息,请使用多条指令。

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

  • 将指令拆分成多个文件。这种方法对于按主题或任务类型组织指令非常有用。

  • 将指令存储在指令文件中,可以方便地与团队或跨项目共享自定义指令。你还可以对文件进行版本控制,以便跟踪随时间推移的更改。

  • 使用指令文件头中的 applyTo 属性,自动将指令应用于特定文件或文件夹。

  • 在你的 prompt 文件中引用自定义指令,以保持你的 prompt 清晰和专注,并避免为不同任务重复指令。

Prompt 文件(实验性)

Prompt 文件允许你在 Markdown 文件中编写完整的提示,然后你可以在聊天中引用这些提示。与补充现有提示的自定义指令不同,prompt 文件是可以存储在工作区中并与他人共享的独立提示。使用 prompt 文件,你可以为常见任务创建可重用模板,在代码库中存储领域专业知识,并规范团队的 AI 交互。

VS Code 支持两种范围的 prompt 文件

  • 工作区 prompt 文件:仅在工作区内可用,存储在工作区的 .github/prompts 文件夹中。
  • 用户 prompt 文件:可在多个工作区中使用,存储在当前的 VS Code 配置文件中。

常见用例包括

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

Prompt 文件结构

Prompt 文件是带有 .prompt.md 文件后缀的 Markdown 文件。

Prompt 文件包含两个部分

  • (可选)带元数据的头部(Front Matter 语法)

    属性 描述
    mode 运行 prompt 时使用的聊天模式:askeditagent(默认)。
    tools 在 agent 模式下可以使用的工具列表。工具名称数组,例如 terminalLastCommandgithubRepo。在聊天输入字段中输入 # 时会显示工具名称。
    如果给定的工具不可用,则在运行 prompt 时会忽略它。
    description prompt 的简短描述。
  • 包含 prompt 内容的 Body

    Prompt 文件模仿了在聊天中编写 prompt 的格式。这允许混合自然语言指令、附加上下文,甚至链接到其他 prompt 文件作为依赖项。你可以使用 Markdown 格式来组织 prompt 内容,包括标题、列表和代码块。

你可以使用 Markdown 链接引用其他 prompt 文件或指令文件。使用相对路径引用这些文件,并确保路径相对于 prompt 文件位置正确。

在 prompt 文件中,你可以使用 ${variableName} 语法引用变量。你可以引用以下变量

  • 工作区变量 - ${workspaceFolder}, ${workspaceFolderBasename}
  • 选中变量 - ${selection}, ${selectedText}
  • 文件上下文变量 - ${file}, ${fileBasename}, ${fileDirname}, ${fileBasenameNoExtension}
  • 输入变量 - ${input:variableName}, ${input:variableName:placeholder}(从聊天输入字段将值传递给 prompt)

Prompt 文件示例

  • 用于生成 React 表单的可重用任务的 Prompt

    ---
    mode: 'agent'
    tools: ['githubRepo', 'codebase']
    description: 'Generate a new React form component'
    ---
    Your goal is to generate a new React form component based on the templates in #githubRepo contoso/react-templates.
    
    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
    
  • 用于执行 REST API 安全审查的 Prompt

    ---
    mode: 'edit'
    description: 'Perform a REST API security review'
    ---
    Perform a REST API security 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
    
提示

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

创建工作区 prompt 文件

工作区 prompt 文件存储在你的工作区中,并且仅在该工作区中可用。

默认情况下,prompt 文件位于工作区的 .github/prompts 目录中。你可以使用 chat.promptFilesLocations 设置指定额外的 prompt 文件位置。

创建工作区 prompt 文件

  1. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 新建 Prompt 文件命令。

  2. 选择应创建 prompt 文件的位置。

    默认情况下,只有 .github/prompts 文件夹可用。使用 chat.promptFilesLocations 设置为工作区添加更多 prompt 文件夹。

  3. 输入 prompt 文件的名称。

    或者,你也可以直接在工作区的 prompts 文件夹中创建 .prompt.md 文件。

  4. 使用 Markdown 格式编写聊天提示。

    在 prompt 文件中,可以将其他工作区文件引用为 Markdown 链接([index](../index.ts)),或在 prompt 文件中引用为 #index.ts

    你还可以引用其他 .prompt.md 文件来创建 prompt 层次结构。你也可以以相同的方式引用指令文件

创建用户 prompt 文件

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

创建用户 prompt 文件

  1. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 选择聊天: 新建 Prompt 文件命令。

  2. 选择用户数据文件夹作为 prompt 文件的位置。

    如果你使用多个VS Code 配置文件,prompt 文件将创建在当前配置文件的用户数据文件夹中。

  3. 输入 prompt 文件的名称。

  4. 使用 Markdown 格式编写聊天提示。

    你还可以引用其他用户 prompt 文件或用户指令文件。

在设备之间同步用户 prompt 文件

VS Code 可以使用设置同步在多个设备上同步你的用户 prompt 文件。

若要同步你的用户 prompt 文件,请为 prompt 文件和指令文件启用设置同步

  1. 确保已启用设置同步

  2. 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行设置同步: 配置命令。

  3. 从要同步的设置列表中选择提示和指令

在聊天中使用 prompt 文件

你有多种选项可以运行 prompt 文件

  • 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 运行 Prompt 命令,然后从快速选择中选择一个 prompt 文件。

  • 在聊天视图中,在聊天输入字段中输入 / 后跟 prompt 文件名。

    此选项允许你在聊天输入字段中传递附加信息。例如,/create-react-form/create-react-form: formName=MyForm

  • 在编辑器中打开 prompt 文件,然后按编辑器标题区域的播放按钮。你可以选择在当前聊天会话中运行 prompt,或打开新的聊天会话。

    此选项对于快速测试和迭代你的 prompt 文件非常有用。

设置

自定义指令设置

Prompt 文件(实验性)设置

  • chat.promptFiles (实验性):启用可重用 prompt 文件和指令文件。

  • chat.promptFilesLocations (实验性):prompt 文件所在的文件夹列表。相对路径将从工作区的根文件夹解析。支持文件路径的 glob 模式。

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