AI Genius — 第 5 季第 2 集¶

🔥 Agent HQ：使用 GitHub Copilot SDK 建置零售分析助手¶

課程說明¶

代理程式在聊天視窗中的表現令人印象深刻，但真正的價值體現在將其嵌入團隊已經在使用的應用程式中。本課程基於 GitHub Copilot SDK 建置零售交易分析助手：使用 .NET 10 API 透過 SSE 串流傳輸模型回應，由 Blazor 前端即時呈現，並配備治理基礎架構（自訂代理程式、掛鉤、稽核追蹤和程式碼掃描），從而能夠安全交付。

課程投影片¶

請參閱 docs/ —「三個星期一」的敘事收錄於 Slide1.png – Slide3.png。

🧠 學習成果¶

完成本課程後，你將能夠：

• 將 GitHub Copilot SDK 執行階段嵌入 ASP.NET Core 應用程式
• 透過伺服器傳送事件（SSE），逐一權杖將模型回應串流傳輸到瀏覽器
• 在執行階段發現可用模型，而不是硬編碼可能過時的清單
• 將企業治理能力（自訂代理程式、掛鉤、稽核記錄和程式碼掃描）應用於 AI 輔助開發

💬 使用 Copilot 持續學習¶

嘗試使用以下提示詞與 GitHub Copilot 互動，探索本課程涵蓋的主題。在 VS Code 中開啟 Copilot Chat（Windows/Linux 使用 Ctrl+Alt+I，Mac 使用 Cmd+Shift+I），貼上提示詞，看看能學到什麼。還可以嘗試連線 Microsoft Learn MCP Server，取得最新的官方文件。

可以從這些提示詞開始，也可以自行撰寫提示詞！

• 我可以使用 GitHub Copilot SDK 建置什麼？
• 如何在 ASP.NET Core 中透過伺服器傳送事件串流傳輸 Copilot SDK 回應？
• 如何列出已登入 Copilot 帳號可用的模型？
• 如何為 Copilot SDK 設定身分驗證？
• 什麼是 Copilot 掛鉤？如何使用它們強制實施安全閘門？

📚 資源與後續行動¶

🌟 Microsoft Learn MCP Server¶

Microsoft Learn MCP Server 可讓 AI 代理程式直接存取 Microsoft 官方文件，為本課程涵蓋的產品和服務提供有可靠依據且保持最新的解答。

VS Code — 此儲存庫已包含 .vscode/mcp.json，因此開啟該資料夾時，伺服器即已完成設定。

GitHub Copilot CLI — 執行以下命令，將 Learn MCP Server 安裝為外掛：

/plugin install microsoftdocs/mcp

如需瞭解更多資訊、檢視其他用戶端或提交問題，請造訪 Learn MCP Server 儲存庫。

✨ 此示範展示的功能¶

🛠️ 技術堆疊¶

同一應用程式提供兩種實作，請選擇你偏好的語言。兩條學習路線講授相同的 SDK 概念，並公開完全一致的 HTTP 介面規格。

🚀 快速開始¶

先決條件¶

• GitHub Copilot CLI — 已使用擁有 Copilot 存取權限的帳號登入
• .NET 學習路線： .NET 10 SDK
• Python 學習路線： Python 3.11+ 和 uv

執行專案 — .NET¶

dotnet restore src/AgentOrchestrator/AgentHQDemo.slnx
dotnet build   src/AgentOrchestrator/AgentHQDemo.slnx

# Terminal 1 — API (SQLite DB auto-created and seeded on first run)
dotnet run --project src/AgentOrchestrator/AgentHQDemo.Api --urls "http://localhost:5050"

# Terminal 2 — Blazor UI
dotnet run --project src/AgentOrchestrator/AgentHQDemo.Web --urls "http://localhost:5051"

然後開啟 http://localhost:5051。API 在連接埠 5050 執行。

執行專案 — Python¶

cd src/AgentOrchestrator-python
uv sync

# One server for both the API and the UI
uv run uvicorn app.main:app --port 5070

然後開啟 http://localhost:5070。

兩套技術堆疊刻意使用不同的連接埠，因此可以同時執行。

GitHub Codespaces¶

1. 按一下 Code → 在 main 分支上建立 codespace
2. 等待環境設定完成（約 2 分鐘）
3. 執行你所選學習路線對應的命令

Copilot CLI 二進位檔案¶

Copilot SDK 會在建置期間從 registry.npmjs.org 下載相符的 CLI 二進位檔案。如果該套件登錄站不可存取（例如使用企業代理或電腦離線），建置將失敗並顯示 MSB3923。 Directory.Build.props 會在偵測到全域安裝的 Copilot CLI 時重複使用它，從而避開此問題：

npm install -g @github/copilot

如有需要，可覆蓋或停用此偵測：

dotnet build -p:CopilotCliBinaryPath=/path/to/copilot   # use a specific binary
dotnet build -p:CopilotUseLocalCli=false                # always download

📡 API 端點¶

呼叫範例¶

# Stream a chat response
curl -N -X POST http://localhost:5050/api/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Which segment has the lowest retention?", "model": "claude-haiku-4.5"}'

# List transactions (10 seed records)
curl http://localhost:5050/api/transactions

# Predict customer segment
curl http://localhost:5050/api/segments/predict/C003
# → {"customerId":"C003","predictedSegment":"High Value","confidence":0.89,...}

🎯 可用模型¶

模型選擇器在執行階段透過 GET /api/chat/models 填入；該端點會詢問 Copilot CLI，確定已已登入帳號實際可用的模型。具體清單因帳號而異，並會隨時間變化；範例包括 claude-haiku-4.5（預設）、auto、claude-sonnet-*、claude-opus-*、 gpt-5.* 和 gemini-*。

如果 API 無法存取 Copilot CLI，API 和使用者介面都會回復到一個精簡的靜態清單，以確保示範仍能正常呈現。

🏗️ 架構¶

graph TB
    subgraph "Frontend — Port 5051"
        UI[Blazor WebAssembly<br/>Batched Rendering]
    end

    subgraph "Backend — Port 5050"
        API[ASP.NET Core API]
        Chat[ChatController<br/>SSE Streaming]
        Txn[TransactionsController]
        Seg[SegmentsController]
        SDK[Copilot SDK<br/>Connection Recovery]
        SVC[RetailAnalyticsService]
        DB[(SQLite<br/>Auto-seeded)]
    end

    UI -->|SSE Stream| Chat
    UI -->|REST| Txn
    UI -->|REST| Seg
    Chat --> SDK
    Txn --> SVC
    Seg --> SVC
    SVC --> DB
    SDK --> Models[Claude / GPT / Gemini]

📂 專案結構¶

.
├── .devcontainer/              # Codespaces configuration
├── .github/
│   ├── agents/                 # Custom Copilot agents
│   ├── hooks/                  # Governance + audit hooks
│   ├── prompts/                # Reusable prompts
│   ├── skills/                 # Copilot skills
│   ├── workflows/              # CI, CodeQL, setup
│   ├── copilot-instructions.md # Coding standards for all agents
│   └── copilot-review-instructions.md
├── .vscode/mcp.json            # MS Learn MCP server
├── docs/                       # Labs, walkthroughs, and reference material
├── img/                        # Session branding
├── src/
│   ├── AgentOrchestrator/          # .NET implementation
│   │   ├── AgentHQDemo.Api/        # Web API — chat, transactions, segments
│   │   ├── AgentHQDemo.McpServer/  # Read-only MCP server over retail.db
│   │   ├── AgentHQDemo.Web/        # Blazor WebAssembly UI
│   │   ├── samples/SdkLabs/        # Runnable lab samples
│   │   ├── tests/                  # xUnit tests (26)
│   │   └── AgentHQDemo.slnx        # Solution
│   └── AgentOrchestrator-python/   # Python implementation
│       ├── app/                    # FastAPI — routers, services, models, UI
│       ├── mcp_server/             # Read-only MCP server over retail.db
│       ├── sdk_labs/               # Runnable lab samples
│       ├── tests/                  # pytest tests (30)
│       └── pyproject.toml          # uv project
├── AGENTS.md                   # Guidelines for AI agents
└── Directory.Build.props       # Copilot CLI resolution

🗄️ 種子資料¶

首次啟動時會自動建立 SQLite 資料庫，其中包含 10 條交易，涵蓋 5 位客戶（C001–C005）、4 個類別和 4 家門市，此外還包括：

🤖 自訂代理程式¶

📋 示範教材¶

完整文件位於 docs/，並按學習路線分組：

請選擇 一條 學習路線，而不是兩條都做；它們講授相同的內容。

不屬於任一語言學習路線的內容均位於 專題：

🔐 安全說明¶

此示範 有意 包含存在缺陷的程式碼模式，以便在程式碼檢閱和靜態分析示範期間現場發現這些問題：

兩種實作都包含相同的四項缺陷，因此同一份解答適用於任一學習路線。

相比之下，聊天功能的資料庫存取 並不是 上述缺陷之一。兩條學習路線都透過只讀 MCP 伺服器向模型公開 retail.db（AgentHQDemo.McpServer / mcp_server/），此伺服器使用 Mode=ReadOnly 開啟 SQLite，並發布五個特定領域工具，而不是通用查詢工具。REST API 仍保留直接 ORM 存取權限；MCP 面向模型，並非用於應用程式存取自己的資料庫。

解決這些問題之前，請勿用於生產環境。 請參閱 SECURITY.md。

CodeQL 說明： 儲存庫為私人儲存庫時會跳過分析，因為程式碼掃描需要 GitHub Advanced Security。如果儲存庫轉為公開，分析會自動執行；也可以設定儲存庫變數 ENABLE_CODEQL=true。

🤝 參與貢獻¶

請參閱 AGENTS.md 瞭解儲存庫指南， CODE_OF_CONDUCT.md 瞭解社群規範，以及 SUPPORT.md 瞭解如何取得幫助。

📄 授權條款¶

• 程式碼 — MIT 授權條款
• 文件與內容 — CC BY 4.0

使用 GitHub Copilot SDK 以 ❤️ 建置