第三节：用AI让重复任务一键完成——prompts.md 文件详解

一、什么是 Prompt 文件？

你已经学会了用 Agent 定义 AI 的"专业身份"（第一节），用 Instructions 为 AI 设定"全局行为准则"（第二节）。但在日常开发中，还有一些频繁执行的标准化任务，比如：

• "请审查这段代码的安全性"
• "为这个函数生成单元测试"
• "写一个符合 Conventional Commits 规范的提交信息"

这些任务流程固定、要求明确，每次都要重新输入一长串提示词，既低效又容易遗漏关键要求。

Prompt 文件正是为了解决这个问题 ------它把常用的任务提示词保存为可复用的模板，你可以通过 / 命令一键调用，Copilot 会自动加载模板内容（包括变量占位符、工具权限等），让你以最少的输入完成重复性工作。

💡 官方定义 ：Prompt 文件是存储在仓库中的可重用提示模板，用于标准化特定任务的 AI 交互。你可以在 Copilot Chat 中通过 / 菜单选择，或直接输入 /文件名 来调用。

二、Prompt 在配置体系中的定位

为了更好地理解 Prompt 的作用，我们重新审视整个 Copilot 定制化体系：

定制功能	文件类型与位置	触发方式	核心用途	类比
自定义指令	.github/copilot-instructions.md	自动（每次对话都加载）	全局背景规则（编码规范、架构原则）	公司的《员工手册》
自定义代理	.github/agents/*.agent.md	手动选择 （下拉菜单或 @agent-name）	拥有专属角色、工具权限的专家	特种兵编制
提示文件	.github/prompts/*.prompt.md	手动调用 （/prompt-name）	标准化、可交互的重复任务模板	作战指令卡
代理技能	.github/skills/<skill-name>/SKILL.md	自动/手动	封装脚本和资源的复杂任务模块	战术工具包

Prompt 是最轻量、最直接的复用方式 ：它不改变 AI 的身份（Agent 改变身份），不改变全局规则（Instructions 改变背景），只是把一段精心设计的提示词保存下来，并支持变量交互------让你每次调用时可以临时填入不同的参数。

三、.prompt.md 文件结构与 Frontmatter 详解

*.prompt.md 文件与 agent.md、instructions.md 一样，由 YAML Frontmatter 和 Markdown 内容 两部分组成。下面是支持的 Frontmatter 字段。

3.1 name（可选，推荐配置）

属性	说明
类型	string
用途	在 Copilot Chat 的 / 菜单中显示的名称
默认值	文件名（不含 .prompt.md）

示例：

name: "代码审查（安全版）"

3.2 description（可选，强烈推荐）

属性	说明
类型	string
用途	简要描述该 Prompt 的作用，帮助你在菜单中区分不同 Prompt
长度建议	10-200 字符

示例：

description: "根据 OWASP Top 10 审查代码中的安全漏洞"

3.3 agent（可选）

属性	说明
类型	string
用途	指定调用此 Prompt 时使用哪个 Agent（如 @security-agent）
默认值	当前活跃的 Agent

示例：

agent: "security-agent"

为什么要指定 Agent？

如果你的 Prompt 需要特殊的工具权限或角色背景（例如安全审查需要只读权限，不能修改文件），可以绑定一个已经配置好的 Agent。这样调用 Prompt 时，Copilot 会自动切换到该 Agent 模式。

3.4 model（可选）

属性	说明
类型	string
用途	指定调用此 Prompt 时使用的 AI 模型
可选值	gpt-4o、gpt-4-turbo、gpt-3.5-turbo 等（取决于你的订阅）
默认值	用户当前选择的模型

示例：

model: "gpt-4o"

3.5 tools（可选）

属性	说明
类型	string 或 string\[\]
用途	为此 Prompt 临时启用的工具列表（覆盖当前 Agent 的工具设置）
默认值	不启用额外工具（继承 Agent 的配置）

示例：

tools: ["read", "grep", "search"]

⚠️ 注意 ：如果当前 Agent 不支持工具（例如 ask 模式），指定 tools 后 Copilot 会自动将模式升级为 agent。

3.6 argument-hint（可选）

属性	说明
类型	string
用途	当你调用 Prompt 时，在输入框中显示的占位提示文字
默认值	无

示例：

argument-hint: "<请粘贴要审查的代码或输入文件路径>"

这个字段可以提升用户体验，让团队成员知道该 Prompt 期望什么输入。

四、核心机制：使用 ${input:变量名} 实现交互

Prompt 文件与普通提示词最大的区别在于支持变量占位符 。通过 ${input:变量名} 语法，你可以在模板中定义需要用户临时填写的参数。

4.1 基本语法

${input:<变量名>:<可选默认值/占位文本>}

• 变量名：必填，用于在模板中引用用户输入的值
• 默认值/占位文本：可选，显示在输入框中作为提示或默认内容

4.2 实际示例

假设你要创建一个"生成 React 组件"的 Prompt：

---
name: "创建 React 组件"
description: "生成一个带有 TypeScript 类型定义的 React 函数组件"
---

请创建一个名为 `${input:组件名:例如 UserCard}` 的 React 函数组件。

**Props 定义**：
```typescript
interface ${input:组件名}Props {
  ${input:Props类型:例如 user: User; onClick?: () => void}
}

组件要求：

• 使用 React 18+ 的函数组件

• 包含 JSDoc 注释

• 使用 Tailwind CSS 进行样式布局

  当你调用 /创建 React 组件 时，Copilot 会依次弹出三个输入框：

  1. "请输入组件名" (默认显示 例如 UserCard)
  2. "请输入 Props 类型" (默认显示 例如 user: User; onClick?: () => void)

  你填写后，AI 就会基于这些参数生成最终代码。

  4.3 变量作用域

  变量在单个 Prompt 文件的 Markdown 内容中全局有效。你可以在多处使用同一个变量名，用户只需输入一次，所有引用位置都会被替换。

  五、编写高质量 Prompt 的实战技巧

  Frontmatter 定义了交互方式，但 Prompt 的核心价值在于 Markdown 内容。以下是提升效果的三条核心技巧。

  5.1 明确角色与约束

  在内容开头，为 AI 设定清晰的角色和必须遵守的约束：

  ## 角色
  你是一位资深后端工程师，专注于 **Node.js + TypeScript** 项目。
  
  ## 约束
  - 严格遵循项目的 `.github/copilot-instructions.md` 中的编码规范
  - 不要使用 `any` 类型
  - 必须处理所有异步操作的错误
  - 输出只包含代码和必要注释，不要添加额外解释

5.2 提供输入格式和示例

如果 Prompt 需要处理用户提供的代码片段或数据，明确告知 AI 期望的输入格式，并给出正反例：

## 输入格式
用户会提供一个函数或一段代码块。请基于它生成单元测试。

## 好的示例
输入：
```typescript
function add(a: number, b: number): number {
  return a + b;
}

输出应包含：

• 正常情况测试

• 边界情况（如负数、零）

• 类型错误测试

  5.3 结构化输出要求

  明确要求 AI 按固定格式输出，便于阅读和复制：

  ## 输出格式
  请按以下结构输出：
  
  ### 1. 问题列表
  - [严重] 问题描述 + 行号
  - [一般] 问题描述
  
  ### 2. 修复建议
  对每个问题给出修改后的代码片段
  
  ### 3. 总体评价
  - 优点：
  - 改进空间：

六、完整实战示例：security-review.prompt.md

下面是一个可以直接使用的安全审查 Prompt，结合了所有知识点：

---
name: "安全审查"
description: "基于 OWASP Top 10 检查代码中的安全漏洞"
agent: "security-agent"
tools: ["read", "search", "grep"]
argument-hint: "<请粘贴代码或输入文件路径>"
model: "gpt-4o"
---

## 🎯 角色
你是一位应用安全专家，精通 OWASP Top 10 漏洞和常见攻击模式。

## 📥 输入
用户会提供一段代码（或文件名）。你需要分析这段代码。

## ✅ 审查清单
请检查以下项目：
1. **注入漏洞**：SQL 注入、命令注入、NoSQL 注入
2. **认证与授权**：是否有硬编码凭证、未检查权限的 API
3. **敏感数据暴露**：是否记录了密码/token、未加密传输
4. **XSS**：用户输入是否被安全转义
5. **不安全反序列化**：是否使用了 `eval()`、`new Function()` 等

## 📤 输出格式（严格按此格式）

### 🔴 严重漏洞（Critical）
- 漏洞描述 + 具体代码行
- 攻击场景（攻击者如何利用）
- 修复方案（代码示例）

### 🟡 高危问题（High）
（同上结构）

### 🔵 最佳实践偏离（Info）
- 建议改进的地方（无安全风险但影响健壮性）

### ✅ 结论
- 是否建议合并：是 / 否（并说明理由）

## ⚠️ 约束
- 不要输出任何修改后的完整文件，只输出审查报告
- 如果不确定是否存在漏洞，标记为"需要人工确认"并说明原因
- 所有修复示例必须使用参数化查询或安全 API，禁止使用字符串拼接

七、部署与使用

7.1 存放位置

在仓库根目录下创建 .github/prompts/ 文件夹，将所有 *.prompt.md 文件放入其中：

your-repo/
├── .github/
│   ├── agents/
│   │   └── security-agent.agent.md
│   ├── instructions/
│   │   └── backend.instructions.md
│   ├── prompts/
│   │   ├── security-review.prompt.md
│   │   ├── generate-test.prompt.md
│   │   └── write-commit-message.prompt.md
│   └── copilot-instructions.md
└── src/

7.2 调用方法

• 斜杠命令 ：在 Copilot Chat 输入框中输入 /security-review（文件名，不含扩展名），然后按回车。如果 Prompt 定义了 argument-hint，光标会自动定位到参数输入位置。
• 菜单选择 ：输入 /，从弹出的列表中选择"安全审查"。
• 带参数调用 ：可以直接输入 /security-review 待审查的代码片段，参数会作为 ${input} 变量的默认值。

7.3 共享

将 .github/prompts/ 目录提交到 Git 仓库后，所有克隆该仓库的团队成员都可以使用这些 Prompt。这非常适合团队标准化代码审查流程、测试模板等。

八、Prompts vs. Agents vs. Instructions 对比总结

维度	Instructions	Agents	Prompts
作用	提供全局背景规则	定义专业身份和权限	标准化具体任务流程
触发方式	自动（每次对话）	手动选择（下拉菜单或 @）	手动调用（/ 命令）
是否支持变量交互	否	否（但可通过对话传递）	是 （${input} 语法）
典型用途	编码规范、架构原则	多步骤复杂任务（如重构、迁移）	单一重复任务（如审查、生成测试）
文件位置	.github/copilot-instructions.md	.github/agents/*.agent.md	.github/prompts/*.prompt.md

使用建议：

• 全局规则用 Instructions
• 需要特定工具权限或持久化角色的用 Agent
• 标准化、可交互的重复性任务用 Prompts

三者可以组合使用：一个 Prompt 可以指定使用某个 Agent（通过 agent 字段），该 Agent 又继承了 Instructions 的全局规则。

九、参考资料

• GitHub Docs: Using prompt files with Copilot Chat
• GitHub Blog: Customizing GitHub Copilot with prompts and slash commands
• GitHub Docs: About custom agents
• GitHub Docs: Custom instructions for GitHub Copilot

---

以上是重新整理后的第三节，格式与前两节完全一致（包含二级标题、三级标题、表格、代码块、对比总结、参考资料）。现在可以向用户交付了。