跳至內容

額外內容 — 自訂代理程式與程式碼檢閱

📎 額外實作課程 — 不屬於 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 frontmatter 的 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 — 選擇性指定特定模型

此處隨附四個代理程式：

代理程式 用途
dotnet-reviewer C# 最佳做法、安全性、效能
security-scanner 弱點與法規遵循問題
pr-summary 根據差異產生 PR 描述
accessibility-auditor UI 程式碼的 WCAG 法規遵循

步驟 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 — 對照解答檢查發現

良好的檢閱應該找出全部四項問題。解答如下：

# 問題 位置 重要性
1 N+1 查詢 GetTransactionsWithSegmentsAsync 會載入所有交易，再針對每一列呼叫 PredictSegmentAsync — 每列多一次往返。10 筆種子資料尚可接受，1,000 萬筆資料時則會造成嚴重問題。
2 缺少 null 檢查 GetTransactionAsync 未防範識別碼不存在的情況便直接傳回，因此呼叫端可能對 null 進行取值。
3 未驗證輸入 AddTransactionAsync 接受未驗證的輸入 — 負數金額、空白客戶識別碼與不合理的數值都會被持久保存。
4 硬式編碼的臨界值 PredictSegmentAsync 某個神奇數字決定客群區隔歸屬。變更商務規則時必須重新部署。

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.