AI Genius — 第 5 季第 2 集¶

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

课程说明¶

Agent 在聊天窗口中的表现令人印象深刻，但真正的价值体现在将其嵌入团队已经在使用的应用程序中。本课程基于 GitHub Copilot SDK 构建零售交易分析助手：使用 .NET 10 API 通过 SSE 流式传输模型响应，由 Blazor 前端实时呈现，并配备治理基础设施（自定义 Agent、挂钩、审计跟踪和代码扫描），从而能够安全交付。

课程幻灯片¶

请参阅 docs/ —“三个星期一”的叙事内容位于 Slide1.png – Slide3.png。

🧠 学习成果¶

完成本课程后，你将能够：

• 将 GitHub Copilot SDK 运行时嵌入 ASP.NET Core 应用程序
• 通过服务器发送事件（SSE），逐词元将模型响应流式传输到浏览器
• 在运行时发现可用模型，而不是硬编码可能过时的列表
• 将企业治理能力（自定义 Agent、挂钩、审计日志和代码扫描）应用于 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 Agent 直接访问 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 家门店，此外还包括：

🤖 自定义 Agent¶

📋 演示材料¶

完整文档位于 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 以 ❤️ 构建