Skip to main content

GST.Rpa.SignalR — 即時通訊

適用對象：GST 內部開發人員 前置知識：C#/.NET 8/SignalR 基礎 閱讀時間：10 分鐘 最後更新：2026-04-04 版本：0.1.0

開發狀態

本模組目前為骨架階段，僅包含 DI 註冊介面。以下標註「Planned」的章節描述規劃中的架構設計。

1. 模組職責​

GST.Rpa.SignalR 負責 RPA 引擎的即時通訊層，透過 WebSocket（SignalR）將引擎狀態、螢幕截圖、日誌等資訊即時推送至前端控制台。

主要職責：

功能說明
引擎狀態推送即時傳送 RPA 引擎的執行狀態變化（啟動、暫停、錯誤等）
螢幕截圖串流將 Agent 端的螢幕畫面即時傳送至 Web 控制台
日誌串流即時推送執行日誌，供遠端監控使用
雙向指令通道接收前端的控制指令（啟動、停止、暫停流程等）

2. NuGet 引用與相依​

<Project Sdk="Microsoft.NET.Sdk">

  <ItemGroup>
    <ProjectReference Include="..\GST.Rpa.Core\GST.Rpa.Core.csproj" />
  </ItemGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Extensions.DependencyInjection" />
  </ItemGroup>

</Project>
相依項目類型用途
GST.Rpa.CoreProjectReference引擎核心型別（狀態、事件定義）
Microsoft.Extensions.DependencyInjectionNuGetDI 容器抽象層

Target Framework：net8.0-windows（繼承自 Directory.Build.props）

3. 現有介面​

目前模組僅包含一個靜態擴充方法，用於 DI 註冊預留：

using Microsoft.Extensions.DependencyInjection;

namespace GST.Rpa.SignalR;

public static class ServiceCollectionExtensions
{
    public static IServiceCollection AddRpaSignalR(this IServiceCollection services)
    {
        // TODO (GST-351): Register SignalR hub and real-time services
        return services;
    }
}

使用方式（於 Host 啟動時呼叫）：

services.AddRpaSignalR();

目前此方法為空殼，待 GST-351 實作後將在此註冊 Hub、序列化設定及相關服務。

4. 規劃架構​

4.1 RpaHub 通訊協議​

Planned

RPA SignalR Hub 將定義以下通道：

Server → Client（推送）

通道名稱承載資料說明
EngineStateChangedEngineState引擎狀態變更通知
ScreenshotFramebyte[]螢幕截圖影格
LogEntryLogRecord即時日誌條目
StepCompletedStepResult流程步驟完成通知

Client → Server（指令）

通道名稱承載資料說明
StartFlowFlowStartRequest啟動指定流程
StopFlowstring (flowId)停止執行中的流程
PauseFlowstring (flowId)暫停流程
ResumeFlowstring (flowId)恢復暫停的流程

Hub 預計繼承自 Hub<IRpaClient>，以強型別定義 Client 端方法合約。

4.2 MessagePack 二進位序列化​

Planned

為提升即時通訊效能，計畫採用 MessagePack 取代預設的 JSON 序列化：

  • 套件：Microsoft.AspNetCore.SignalR.Protocols.MessagePack
  • 優勢：二進位格式，體積約為 JSON 的 50-70%，序列化/反序列化速度提升 2-4 倍
  • 適用場景：高頻率的螢幕截圖串流與狀態更新

預計註冊方式：

services.AddSignalR()
    .AddMessagePackProtocol();

4.3 螢幕截圖串流設計​

Planned

螢幕截圖串流將包含以下最佳化機制：

機制說明
差異偵測（Delta Detection）僅傳送與前一幀不同的區域，減少頻寬消耗
FPS 控制可設定推送頻率（預設 2-5 FPS），避免網路壅塞
JPEG 壓縮截圖以 JPEG 格式壓縮傳送，品質可調
按需啟用僅在前端開啟截圖檢視時才開始串流

預計透過 IAsyncEnumerable<T> 搭配 SignalR Streaming 實作：

public async IAsyncEnumerable<ScreenshotFrame> StreamScreenshots(
    string agentId,
    int fps = 2,
    int quality = 75,
    [EnumeratorCancellation] CancellationToken cancellationToken = default)
{
    // Delta detection + FPS throttle + JPEG compression
}

4.4 多客戶端連線管理​

Planned

支援多個 Web 控制台同時連線至同一 Agent 的場景：

  • Group 管理：以 agentId 為 Group，將訂閱同一 Agent 的客戶端歸為同組
  • 連線追蹤：維護 ConnectionId → AgentId 對應表，處理斷線重連
  • 背壓控制：當客戶端消費速度低於推送速度時，自動降低推送頻率
  • 認證整合：搭配 JWT Bearer Token 驗證連線身份
public override async Task OnConnectedAsync()
{
    var agentId = Context.GetHttpContext()?.Request.Query["agentId"];
    await Groups.AddToGroupAsync(Context.ConnectionId, agentId);
}

4.5 通訊拓撲​

Planned

規劃中的整體通訊拓撲：RpaHub 居中，Worker Agent 推送狀態 / 截圖 / Log，Web Console 訂閱對應 Group，Admin 訂閱所有 Group：

拓撲三大流向：

  • Worker → Hub（推送）：Worker 為事件來源，主動 SendAsync 引擎狀態、截圖、日誌等通道
  • Hub → Web Console（廣播）：以 Clients.Group(agentId) 把該 Agent 的更新分發給訂閱者；Group 內可同時有多個 Console（同一 Agent 多人觀察）
  • Web Console → Hub → Worker（控制）：使用者透過 Console 發出 StartFlow / PauseFlow 等指令，Hub 路由到對應 Group 的 Worker

Admin Console 不依附特定 Group，可訂閱 Clients.All 取得全域監控視角。

5. 版本紀錄​

版本日期說明
0.1.02026-04-04骨架初版 — 僅含 DI 註冊介面（AddRpaSignalR）