额外内容 — 自定义代理与代码审查¶

📎 额外实验 — 不属于 Copilot SDK。 此内容涵盖 .agent.md 文件、一个 Copilot CLI 功能，而不是 Copilot SDK。它确实很有用，但属于选修，且与编号的 SDK 技术路线彼此独立。如果您是为了 SDK 而来，请从 实验 01 开始。

目标： 使用仓库中的自定义代理找出四个刻意保留的代码异味，并了解代理、指令和技能如何协同落实团队的代码审查标准。

时间： 约 20 分钟

先决条件： 实验 02 完成。您需要已登录的 GitHub Copilot CLI，或具有 Copilot Chat 的 VS Code。

⚠️ 请先阅读本节¶

您即将找到的问题是 刻意保留。它们的存在，是为了让审查确实有话可说。 请勿修正它们 — 实验 05 与审查指示文件都假设它们仍然存在。

您在此处的任务是 检测并描述，而不是修复。

步骤 1 — 查看已签入的内容¶

ls .github/agents/
cat .github/agents/dotnet-reviewer.agent.md

每个代理都是包含 YAML 前置字段的 Markdown 文件：

---
name: dotnet-reviewer
description: Senior .NET code reviewer specializing in C# best practices, security, and performance
tools: ['agent', 'read', 'search']
model: claude-sonnet-4.6
---

• name — 调用代理时使用的名称
• description — 告诉 Copilot 何时使用此代理
• tools — 允许使用的能力；这些代理只具备只读工具，因此没有 edit 或 bash
• model — 可选的指定模型

此处随附四个代理程序：

步骤 2 — 了解共享内容¶

代理不会各自孤立运行。有两个配置文件会应用于整个仓库：

head -40 .github/copilot-instructions.md
head -30 .github/copilot-review-instructions.md

• copilot-instructions.md — 每个代理程序都会遵循的编程标准（文件范围命名空间、非同步惯例、 Result<T> 而不是异常，依此类推)
• copilot-review-instructions.md — 审查专用内容：SDK 命名空间变更、SSE 清空缓冲区需求，以及刻意保留之代码异味的明确列表，避免审查者将它们误报为新错误

这种分层正是重点：标准存放在版本控制中，因此每位审查者 — 无论是人员还是代理程序 — 都会应用相同标准。

步骤 3 — 使用代理检查服务¶

针对包含大多数问题的文件运行 .NET 审查代理：

copilot --agent dotnet-reviewer -p "Review src/AgentOrchestrator/AgentHQDemo.Api/Services/RetailAnalyticsService.cs for performance and correctness issues. List each with severity and a suggested fix, but do not modify any files." --allow-all-tools

在 VS Code Copilot Chat 中，对等做法是：

@dotnet-reviewer review RetailAnalyticsService.cs for performance and correctness issues

步骤 4 — 对照答案检查发现¶

良好的审查应该找出全部四个问题。答案如下：

N+1 问题直接在代码中清晰可见 — 甚至已特别标注注释：

foreach (var txn in transactions)
{
    // N+1: querying segments for every single transaction
    var segment = await PredictSegmentAsync(txn.CustomerId);
    ...
}

💡 代理找到了几项？代理具有一定的非确定性，一次运行只找出四项中的三项并不罕见。这也说明：代理可以加快审查速度，但不能取代人工审查。

步骤 5 — 接着使用安全扫描器¶

不同代理会采用不同视角。安全扫描器应重点关注问题 3：

copilot --agent security-scanner -p "Scan src/AgentOrchestrator/AgentHQDemo.Api/Controllers/TransactionsController.cs and the service it calls for input validation and injection risks. Report findings only, make no edits." --allow-all-tools

比较两份输出。.NET 审查工具注重效率；安全扫描器注重信任边界。同一份代码，不同的优先级 — 这正是它们应该成为两个独立代理而不是一个通用代理的原因。

步骤 6 — 审核 UI 的无障碍功能¶

copilot --agent accessibility-auditor -p "Audit src/AgentOrchestrator/AgentHQDemo.Web/Components/ChatInput.razor and Header.razor for WCAG issues. Report only." --allow-all-tools

检查标签关联、键盘操作能力和流式消息区域的焦点管理。

步骤 7 — 生成 PR 摘要¶

存在未提交的更改时，pr-summary 会起草说明：

copilot --agent pr-summary -p "Summarise the current git diff as a pull request description." --allow-all-tools

✅ 检查点¶

• [x] 您能说明 .agent.md frontmatter 字段
• [x] 您已找到四个刻意保留的问题 — 并将它们保留在原处
• [x] 您已看到两个代理程序对相同代码得出不同结论
• [x] 您已了解指示文件如何为每个代理程序提供共享标准

💡 加分练习¶

编写第五个代理程序。创建 .github/agents/test-writer.agent.md ，并搭配 description ，用来说明应在何时触发，以及 tools: ['read', 'search']。请它针对以下项目提出（但不要编写）测试： PredictSegmentAsync.

相关内容¶

• 下一步： 额外内容 — 治理钩子
• 深入解析：自定义代理
• 深入解析：技能
• 演示：零售分析