内容
<p align="center">
<img src="assets/banner.png" alt="基于 GitHub Copilot 的智能代理 AI 工作坊" width="400" />
</p>
# 基于 GitHub Copilot 的智能代理 AI 工作坊
[](LICENSE)
一个全天的自定进度的实验室，教你使用 VS Code 中的 GitHub Copilot 构建、配置和编排智能代理 AI 工作流。
一个单一的 **任务管理 ASP.NET Core Web API** 在 10 个模块中不断演进，你逐步在上面叠加每一个 Copilot 智能代理的基元。
---
## 先决条件
| 工具 | 版本 | 检查 |
|---|---|---|
| VS Code | 最新稳定版 | `code --version` |
| GitHub Copilot Business | 有效订阅 | 在 github.com/settings/copilot 检查 |
| .NET SDK | 9.x | `dotnet --version` |
| Node.js | 20+ | `node --version` |
| Git | 任意 | `git --version` |
---
## 快速开始
```bash
# 1. 在 VS Code 中打开
code <源代码文件夹在此>\copilot-agentic-workshop
# 2. 启动 TaskManager API
dotnet run --project src/TaskManager/TaskManager.Api
# 3. 打开代理自定义编辑器
# Ctrl+Alt+I → 齿轮图标 (⚙️) → "打开自定义"
# 4. 开始实验室 00
# 打开 labs/00-foundation/README.md
```
---
## 工作坊结构
```
11 个模块 × 平均 40 分钟 = 总共约 7 小时
第一阶段 — 基础 (30 分钟)
实验室 00 — 设置和生态系统概述
第二阶段 — 行为层 (2.5 小时)
实验室 01 — 指令：始终在线的上下文
实验室 02 — 提示文件：按需模板
实验室 03 — 自定义代理：专业化角色
实验室 04 — 技能：多步骤 + 捆绑资产
第三阶段 — 集成层 (2.5 小时)
实验室 05 — MCP：使用现有服务器
实验室 06 — MCP：构建您自己的 C# 服务器
实验室 07 — 工具：内置 + 限制
第四阶段 — 自动化层 (1.5 小时)
实验室 08 — 钩子：生命周期自动化
实验室 09 — 子代理和编排
第五阶段 — 顶点 (1 小时)
实验室 10 — 完整的开发人员工作流：任务标记功能
```
---
## 模块索引
| # | 实验室 | 关键文件 | 时长 |
|---|---|---|---|
| 00 | [基础](labs/00-foundation/README.md) | `src/TaskManager/`，代理自定义编辑器 | 30 分钟 |
| 01 | [指令](labs/01-instructions/README.md) | `.github/copilot-instructions.md`，`.github/instructions/*.instructions.md` | 45 分钟 |
| 02 | [提示](labs/02-prompts/README.md) | `.github/prompts/*.prompt.md` | 30 分钟 |
| 03 | [自定义代理](labs/03-custom-agents/README.md) | `.github/agents/*.agent.md` | 45 分钟 |
| 04 | [技能](labs/04-skills/README.md) | `.github/skills/scaffold-feature/` | 30 分钟 |
| 05 | [MCP：使用](labs/05-mcp-consume/README.md) | `.vscode/mcp.json`，Playwright + GitHub MCP | 45 分钟 |
| 06 | [MCP：构建](labs/06-mcp-build/README.md) | `mcp/TaskManager.Mcp/` | 60 分钟 |
| 07 | [工具](labs/07-tools/README.md) | 代理 `tools:` 前置信息 | 30 分钟 |
| 08 | [钩子](labs/08-hooks/README.md) | `.github/hooks/workshop-hooks.json` | 45 分钟 |
| 09 | [子代理](labs/09-sub-agents/README.md) | `feature-implementer.agent.md` 编排 | 45 分钟 |
| 10 | [顶点](labs/10-capstone/README.md) | 以上所有 — 任务标记功能 | 60 分钟 |
---
## 仓库布局
```
copilot-agentic-workshop/
│
├── .github/ ← 所有 Copilot 自定义项
│ ├── copilot-instructions.md ← 全局始终在线规则（C#，干净的架构，测试）
│ ├── instructions/
│ │ ├── api.instructions.md ← 适用于 *Endpoints.cs, *Controller.cs
│ │ └── tests.instructions.md ← 适用于 *.Tests/**
│ ├── prompts/
│ │ ├── new-endpoint.prompt.md ← /new-endpoint — 搭建新的 API 端点
│ │ └── pr-review.prompt.md ← /pr-review — 系统化的 PR 审查检查清单
│ ├── agents/
│ │ ├── code-reviewer.agent.md ← 只读安全性 + 架构审查者
│ │ ├── test-writer.agent.md ← 编写 xUnit + FluentAssertions + NSubstitute 测试
│ │ └── feature-implementer.agent.md ← 编排器：代码 → 审查 → 测试
│ ├── skills/
│ │ └── scaffold-feature/
│ │ ├── SKILL.md ← /scaffold-feature — 从模板生成所有层
│ │ └── templates/ ← 7 个 .cs.template 文件用于搭建技能
│ └── hooks/
│ └── workshop-hooks.json ← 审计日志 + 守卫 + 自动格式化钩子
│
├── .vscode/
│ └── mcp.json ← Playwright + GitHub + 自定义 TaskManager MCP 服务器
│
├── src/TaskManager/ ← ASP.NET Core Web API（不断演进的项目）
│ ├── TaskManager.Domain/ ← 实体，接口（无外部依赖）
│ ├── TaskManager.Application/ ← DTOs，服务（依赖于 Domain）
│ ├── TaskManager.Api/ ← 端点，DI，内存存储库（依赖于 Application）
│ └── TaskManager.Tests/ ← xUnit 测试（依赖于 Application + Domain）
│
├── mcp/TaskManager.Mcp/ ← 自定义 C# MCP 服务器（模块 06）
│ ├── Tools/TaskTools.cs ← list_tasks, get_task, create_task MCP 工具
│ ├── Services/TaskApiClient.cs ← 类型化 HTTP 客户端 → TaskManager REST API
│ └── Models/TaskDto.cs ← DTO 镜像 API 响应
│
├── labs/ ← 逐步实验室说明
│ ├── 00-foundation/README.md
│ ├── 01-instructions/README.md
│ ├── ...
│ └── 10-capstone/README.md
│
├── docs/
│ ├── 00-ecosystem-map.md ← 可视化概念图 + 关系图
│ └── cheatsheet.md ← 所有 YAML 模式在一页上
│
├── streams/
│ └── engineering-manager/ ← 未来：EM 流（提案，估计，审查）
│
└── NuGet.Config ← 包括 nuget.org 作为备用包源
```
---
## Copilot 基元 — 快速参考
| 基元 | 文件模式 | 位置 | 调用者 |
|---|---|---|---|
| 全局指令 | `copilot-instructions.md` | `.github/` | 自动应用于每个请求 |
| 文件指令 | `*.instructions.md` | `.github/instructions/` | 自动通过 `applyTo` 通配符 |
| 提示文件 | `*.prompt.md` | `.github/prompts/` | 聊天中 `/name` |
| 自定义代理 | `*.agent.md` | `.github/agents/` | 聊天面板中的代理选择器 |
| 技能 | `SKILL.md` | `.github/skills/<name>/` | 聊天中 `/name` |
| 钩子 | `*.json` | `.github/hooks/` | 生命周期事件中自动 |
| MCP 配置 | `mcp.json` | `.vscode/` | 需要工具时自动 |
---
## 运行测试
```bash
dotnet test src/TaskManager/TaskManager.slnx
```
---
## 涵盖的概念
- **代理模式** — 自主多步骤任务执行 vs. 聊天模式
- **指令** — 始终在线的上下文（全局 + 文件作用域 `applyTo`）
- **提示文件** — 参数化按需工作流（`/slash-commands`）
- **自定义代理** — 具有工具限制和模型覆盖的专业化角色
- **技能** — 多步骤工作流与捆绑模板资产
- **MCP（模型上下文协议）** — 使用（Playwright，GitHub）和构建（C#）服务器
- **工具** — 内置工具，MCP 工具，工具别名，最小权限原则
- **钩子** — `preToolUse` / `postToolUse` / `sessionStart` / `agentStop` / `subagentStart/Stop`
- **子代理** — 父 → 任务工具 → 子代理 → 结果（上下文隔离 + 委托）
---
## 故障排除
**NuGet 还原失败**
根目录下的 `NuGet.Config` 添加了 nuget.org 作为备用源。
如果内部 Artifactory 源超时，包将从 nuget.org 拉取。
**MCP 服务器无法启动**
1. 检查 Node.js 是否已安装：`node --version`
2. 打开 VS Code 的输出面板 → 选择 "MCP" 下拉菜单
3. 从命令面板重新运行 `MCP: List Servers`
**代理模式不可用**
确保 GitHub Copilot 代理模式在 VS Code 设置中启用：
`"github.copilot.chat.agent.enabled": true`
**钩子未触发**
在 VS Code 中启用：`"github.copilot.chat.agent.hooksEnabled": true`
查看代理调试日志：聊天面板 → `...` → "显示代理调试日志"
