架構¶

本頁是 AI Genius S5E2 Agent HQ 示範的系統參考，概述 .NET 10 Blazor WebAssembly 前端、ASP.NET Core Web API、GitHub Copilot SDK 整合，以及免設定的 SQLite 分析資料存放區。

想直接探索嗎？

此系統地圖以互動式圖表呈現相同的架構，您可以搜尋節點、追蹤路由，並播放三種引導式檢視。

元件檢視¶

此示範會以兩個本機處理程序執行：Blazor WebAssembly 使用者介面使用連接埠 5051，API 使用連接埠 5050。API 中的 Program.cs 會將 CopilotChatService 註冊為單一執行個體，並將 RetailAnalyticsService 註冊為以 RetailDbContext 為後端的範圍服務。

graph LR
    Browser["Browser"]

    subgraph Web["AgentHQDemo.Web — Blazor WebAssembly :5051"]
        Blazor["Chat UI"]
        WebChat["ChatService"]
        Storage["StorageService<br/>localStorage"]
    end

    subgraph Api["AgentHQDemo.Api — ASP.NET Core Web API :5050"]
        ChatController["ChatController<br/>/api/chat"]
        TxController["TransactionsController<br/>/api/transactions"]
        SegController["SegmentsController<br/>/api/segments"]
        CopilotService["CopilotChatService<br/>singleton"]
        Analytics["RetailAnalyticsService<br/>scoped"]
        DbContext["RetailDbContext"]
    end

    subgraph Copilot["GitHub Copilot SDK"]
        Client["CopilotClient"]
        Session["Copilot session"]
        Models["Claude / GPT / Gemini models"]
    end

    subgraph Mcp["AgentHQDemo.McpServer — stdio subprocess"]
        RetailTools["RetailTools<br/>5 read-only tools"]
    end

    SQLite[("SQLite<br/>retail.db")]

    Browser --> Blazor
    Blazor --> WebChat
    Blazor --> Storage
    WebChat -->|"SSE and REST"| ChatController
    WebChat -->|"REST"| TxController
    WebChat -->|"REST"| SegController
    ChatController --> CopilotService
    CopilotService --> Client
    Client --> Session
    Session --> Models
    Session -->|"MCP over stdio"| RetailTools
    RetailTools -->|"Mode=ReadOnly"| SQLite
    TxController --> Analytics
    SegController --> Analytics
    Analytics --> DbContext
    DbContext --> SQLite

請注意，存取 retail.db 有兩條不同的路徑。REST 控制器會直接透過 RetailDbContext 進行讀寫；模型則只能透過 MCP 伺服器存取同一個資料庫，且連線會以 Mode=ReadOnly 模式開啟，並僅能使用該伺服器發佈的五項領域工具。MCP 是供模型使用，而不是供應用程式與自己的資料庫通訊。

SSE 對話流程¶

AgentHQDemo.Web.Services.ChatService.StreamChatAsync 會使用 HttpCompletionOption.ResponseHeadersRead 將要求張貼至 /api/chat/stream。API 會設定 text/event-stream、清出每個資料區塊，並以 data: [DONE] 結束串流。

sequenceDiagram
    participant Browser as Browser
    participant UI as Blazor Home.razor
    participant WebChat as Web ChatService
    participant Controller as ChatController.StreamChat
    participant Service as CopilotChatService.ChatStreamAsync
    participant Client as CopilotClient session
    participant Channel as Channel of string

    Browser->>UI: Submit prompt
    UI->>WebChat: StreamChatAsync(prompt, model)
    WebChat->>Controller: POST /api/chat/stream
    Controller->>Service: ChatStreamAsync(prompt, model)
    Service->>Client: CreateSessionAsync(SessionConfig)
    Service->>Client: session.On (SessionEvent) subscription
    Service->>Client: SendAsync(MessageOptions)
    Client-->>Service: AssistantMessageDeltaEvent
    Service-->>Channel: TryWrite(delta content)
    Channel-->>Controller: ReadAllAsync chunk
    Controller-->>WebChat: data: {"content":"..."}
    WebChat-->>UI: yield chunk
    UI-->>Browser: Batched render at about 20fps
    Client-->>Service: SessionIdleEvent
    Controller-->>WebChat: data: [DONE]

資料模型¶

RetailDbContext 會公開 Transactions 與 Segments 集合。客群預測會由 RetailAnalyticsService 以記錄形式傳回，而不會儲存在 SQLite 中。

classDiagram
    class Transaction {
        int Id
        string CustomerId
        decimal Amount
        string ProductCategory
        string StoreId
        DateTime Timestamp
        bool IsFlagged
    }

    class CustomerSegment {
        int Id
        string Name
        string Description
        int CustomerCount
        decimal AvgMonthlySpend
        decimal RetentionRate
    }

    class SegmentPrediction {
        string CustomerId
        string PredictedSegment
        double Confidence
        string[] TopFeatures
    }

    Transaction ..> SegmentPrediction : analysed for
    CustomerSegment ..> SegmentPrediction : predicted name

儲存庫配置¶

實作位於 src/AgentOrchestrator/ 之下，並分為 API、使用者介面與測試專案。

src/AgentOrchestrator/
├── AgentHQDemo.Api/
│   ├── Controllers/
│   ├── Data/
│   ├── Models/
│   ├── Services/
│   └── Program.cs
├── AgentHQDemo.Web/
│   ├── Components/
│   ├── Layout/
│   ├── Pages/
│   ├── Services/
│   └── Program.cs
├── tests/
│   └── AgentHQDemo.Tests/
└── AgentHQDemo.slnx

主要設計決策¶

單一執行個體 Copilot 用戶端： AgentHQDemo.Api.Services.CopilotChatService 會註冊為單一執行個體，並保有一個長時間存續的 CopilotClient。EnsureStartedAsync 會在連線中斷後重新建立用戶端。
串流用 Channel 橋接：Copilot SDK 回呼會將助理增量寫入無界限的 Channel<string>。API 會將 Channel 讀取為 IAsyncEnumerable<string>，並將每個項目轉換為 SSE 框架。
執行階段模型探索： CopilotChatService.ListModelsAsync 會在執行階段呼叫 Copilot SDK。 ChatController.GetModels 會在無法連線至 CLI 或 CLI 未傳回任何模型時，改用靜態目錄。
以 SQLite 提供免設定分析： Program.cs 會使用 UseSqlite("Data Source=retail.db")、呼叫 EnsureCreatedAsync，並在啟動時植入零售範例資料。

架構¶