自定义 VS Code 中的聊天回复
如果提供正确的上下文,Copilot 可以提供符合你的编码实践和项目要求的回复。通过自定义指令,你可以定义和自动应用代码生成或代码审查等任务的指南和规则。Prompt 文件允许你在 Markdown 文件中编写完整的聊天提示,然后你可以在聊天中引用或与他人共享这些提示。在本文中,你将了解如何使用自定义指令和 Prompt 文件来自定义 Visual Studio Code 中的聊天回复。
指令文件
自定义指令允许你描述通用指南或规则,以获得符合你特定编码实践和技术栈的回复。自定义指令不是在每个聊天查询中手动包含此上下文,而是自动将此信息包含在每个聊天请求中。
VS Code 支持多种类型的自定义指令,针对不同的场景:代码生成、测试生成、代码审查、提交消息生成以及拉取请求标题和描述生成指令。
你可以通过两种方式定义自定义指令
- 指令文件:在 Markdown 文件中为你的工作区或 VS Code 配置文件指定代码生成指令。
- 设置:在 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
文件
-
将 github.copilot.chat.codeGeneration.useInstructionFiles 设置为
true
,以指示 VS Code 中的 Copilot 使用自定义指令文件。 -
在工作区根目录下创建
.github/copilot-instructions.md
文件。如果需要,请先创建.github
目录。 -
向文件中添加自然语言指令。你可以使用 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 链接引用其他指令文件。使用相对路径引用这些文件,并确保路径相对于指令文件位置正确。
创建指令文件
-
从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 新建指令文件命令。
-
选择应创建指令文件的位置。
用户指令文件存储在当前配置文件文件夹中。你可以使用设置同步在多个设备上同步用户指令文件。确保在设置同步: 配置命令中配置提示和指令设置。
工作区指令文件默认存储在工作区的
.github/instructions
文件夹中。使用 chat.instructionsFilesLocations 设置为工作区添加更多指令文件夹。 -
输入指令文件的名称。
-
使用 Markdown 格式编写自定义指令。
在工作区指令文件中,可以将其他工作区文件引用为 Markdown 链接(
[index](../index.ts)
),或在指令文件中引用为#index.ts
。
若要在聊天提示中使用指令文件,你可以选择
- 在聊天视图中,选择添加上下文 > 指令,然后从快速选择中选择指令文件。
- 从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 附加指令命令,然后从快速选择中选择指令文件。
- 在指令文件头中配置
applyTo
属性,以自动将指令应用于特定文件或文件夹。
在设置中指定自定义指令
你还可以在用户或工作区设置中配置自定义指令。针对不同的场景有特定的设置。指令会自动应用于特定任务。
下表列出了每种自定义指令类型的设置。
你可以在设置值中将自定义指令定义为文本,或引用工作区中的外部文件。
以下代码片段展示了如何在 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 时使用的聊天模式: ask
、edit
或agent
(默认)。tools
在 agent 模式下可以使用的工具列表。工具名称数组,例如 terminalLastCommand
或githubRepo
。在聊天输入字段中输入#
时会显示工具名称。
如果给定的工具不可用,则在运行 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 文件
-
从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 新建 Prompt 文件命令。
-
选择应创建 prompt 文件的位置。
默认情况下,只有
.github/prompts
文件夹可用。使用 chat.promptFilesLocations 设置为工作区添加更多 prompt 文件夹。 -
输入 prompt 文件的名称。
或者,你也可以直接在工作区的 prompts 文件夹中创建
.prompt.md
文件。 -
使用 Markdown 格式编写聊天提示。
在 prompt 文件中,可以将其他工作区文件引用为 Markdown 链接(
[index](../index.ts)
),或在 prompt 文件中引用为#index.ts
。你还可以引用其他
.prompt.md
文件来创建 prompt 层次结构。你也可以以相同的方式引用指令文件。
创建用户 prompt 文件
用户 prompt 文件存储在你的用户配置文件中。使用用户 prompt 文件,你可以在多个工作区中共享可重用提示。
创建用户 prompt 文件
-
从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 选择聊天: 新建 Prompt 文件命令。
-
选择用户数据文件夹作为 prompt 文件的位置。
如果你使用多个VS Code 配置文件,prompt 文件将创建在当前配置文件的用户数据文件夹中。
-
输入 prompt 文件的名称。
-
使用 Markdown 格式编写聊天提示。
你还可以引用其他用户 prompt 文件或用户指令文件。
在设备之间同步用户 prompt 文件
VS Code 可以使用设置同步在多个设备上同步你的用户 prompt 文件。
若要同步你的用户 prompt 文件,请为 prompt 文件和指令文件启用设置同步
-
确保已启用设置同步。
-
从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行设置同步: 配置命令。
-
从要同步的设置列表中选择提示和指令。
在聊天中使用 prompt 文件
你有多种选项可以运行 prompt 文件
-
从命令面板 (⇧⌘P (Windows, Linux Ctrl+Shift+P)) 运行聊天: 运行 Prompt 命令,然后从快速选择中选择一个 prompt 文件。
-
在聊天视图中,在聊天输入字段中输入
/
后跟 prompt 文件名。此选项允许你在聊天输入字段中传递附加信息。例如,
/create-react-form
或/create-react-form: formName=MyForm
。 -
在编辑器中打开 prompt 文件,然后按编辑器标题区域的播放按钮。你可以选择在当前聊天会话中运行 prompt,或打开新的聊天会话。
此选项对于快速测试和迭代你的 prompt 文件非常有用。
设置
自定义指令设置
-
chat.promptFiles (实验性):启用可重用 prompt 文件和指令文件。
-
github.copilot.chat.codeGeneration.useInstructionFiles:控制是否将来自
.github/copilot-instructions.md
的代码指令添加到 Copilot 请求中。 -
chat.instructionsFilesLocations (实验性):指令文件所在的文件夹列表。相对路径将从工作区的根文件夹解析。支持文件路径的 glob 模式。
设置值 描述 ["/path/to/folder"]
为特定路径启用指令文件。指定一个或多个指令文件所在的文件夹。相对路径将从工作区的根文件夹解析。
默认情况下,.github/copilot-instructions
已添加但处于禁用状态。 -
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 请求中的一组指令。
Prompt 文件(实验性)设置
-
chat.promptFiles (实验性):启用可重用 prompt 文件和指令文件。
-
chat.promptFilesLocations (实验性):prompt 文件所在的文件夹列表。相对路径将从工作区的根文件夹解析。支持文件路径的 glob 模式。
设置值 描述 ["/path/to/folder"]
为特定路径启用 prompt 文件。指定一个或多个 prompt 文件所在的文件夹。相对路径将从工作区的根文件夹解析。
默认情况下,.github/prompts
已添加但处于禁用状态。