mcp-feedback-enhanced/docs/architecture/system-overview.md

系統架構總覽

🏗️ 整體架構設計

MCP Feedback Enhanced 採用單一活躍會話 + 持久化 Web UI的創新架構設計，實現 AI 助手與用戶之間的高效、無縫交互體驗。

系統整體架構圖

graph TB
    subgraph "AI 助手環境"
        AI[AI 助手<br/>Claude/GPT等]
    end
    
    subgraph "MCP Feedback Enhanced"
        subgraph "MCP 服務層"
            MCP[MCP Server<br/>server.py]
            TOOL[interactive_feedback<br/>工具]
        end
        
        subgraph "Web UI 管理層"
            WM[WebUIManager<br/>單例模式]
            SESSION[WebFeedbackSession<br/>會話管理]
        end
        
        subgraph "Web 服務層"
            API[FastAPI<br/>HTTP/WebSocket]
            ROUTES[路由處理<br/>main_routes.py]
        end
        
        subgraph "前端交互層"
            UI[Web UI<br/>HTML/JS]
            WS[WebSocket<br/>實時通信]
        end
        
        subgraph "工具層"
            ENV[環境檢測]
            BROWSER[智能瀏覽器開啟]
            RESOURCE[資源管理]
        end
    end
    
    subgraph "用戶環境"
        USER[用戶瀏覽器]
        FILES[專案文件]
    end
    
    AI -->|調用 MCP 工具| MCP
    MCP --> TOOL
    TOOL --> WM
    WM --> SESSION
    WM --> API
    API --> ROUTES
    ROUTES --> UI
    UI --> WS
    WS --> USER
    
    ENV --> MCP
    BROWSER --> USER
    RESOURCE --> SESSION
    
    USER -->|回饋提交| WS
    FILES -->|專案內容| TOOL

🎯 核心設計理念

1. 單一活躍會話模式

stateDiagram-v2
    [*] --> NoSession: 系統啟動
    NoSession --> ActiveSession: AI 首次調用
    ActiveSession --> SessionUpdated: AI 再次調用
    SessionUpdated --> ActiveSession: 會話切換完成
    ActiveSession --> Cleanup: 超時或手動清理
    Cleanup --> NoSession: 資源釋放
    
    note right of ActiveSession
        只維護一個活躍會話
        提升性能和用戶體驗
    end note

2. 持久化 Web UI 架構

• 瀏覽器標籤頁保持: 避免重複開啟瀏覽器
• WebSocket 連接復用: 減少連接建立開銷
• 狀態無縫切換: 從 SUBMITTED → WAITING
• 內容局部更新: 只更新必要的 UI 元素

3. 智能環境檢測

flowchart TD
    START[啟動檢測] --> LOCAL{本地環境?}
    LOCAL -->|是| DIRECT[直接開啟瀏覽器]
    LOCAL -->|否| REMOTE{SSH 遠程?}
    REMOTE -->|是| TUNNEL[建立 SSH 隧道]
    REMOTE -->|否| WSL{WSL 環境?}
    WSL -->|是| WSLOPEN[WSL 瀏覽器開啟]
    WSL -->|否| FALLBACK[回退模式]
    
    DIRECT --> SUCCESS[成功啟動]
    TUNNEL --> SUCCESS
    WSLOPEN --> SUCCESS
    FALLBACK --> SUCCESS

🔧 技術亮點

1. 創新的會話管理

# 傳統多會話設計 (已棄用)
self.sessions: Dict[str, WebFeedbackSession] = {}

# 創新單一活躍會話設計
self.current_session: Optional[WebFeedbackSession] = None
self.global_active_tabs: Dict[str, dict] = {}  # 全局標籤頁狀態

2. 智能瀏覽器開啟機制

• 活躍標籤頁檢測: 避免重複開啟瀏覽器視窗
• 跨平台支援: Windows, macOS, Linux 自動適配
• 環境感知: SSH/WSL 環境特殊處理

3. 實時狀態同步

• WebSocket 雙向通信: 前後端狀態實時同步
• 會話更新通知: 立即推送會話變更
• 錯誤處理機制: 連接斷線自動重連

📊 性能特性

資源使用優化

• 內存佔用: 單一會話模式減少 60% 內存使用
• 連接復用: WebSocket 連接保持，減少建立開銷
• 智能清理: 自動資源回收和會話超時處理

用戶體驗提升

• 零等待切換: 會話更新無需重新載入頁面
• 連續交互: 支援 AI 助手多次循環調用
• 視覺反饋: 實時狀態指示和進度顯示

🔄 核心工作流程

AI 助手調用流程

sequenceDiagram
    participant AI as AI 助手
    participant MCP as MCP 服務
    participant WM as WebUIManager
    participant UI as Web UI
    participant User as 用戶
    
    AI->>MCP: interactive_feedback()
    MCP->>WM: 創建/更新會話
    WM->>UI: 啟動 Web 服務
    WM->>User: 智能開啟瀏覽器
    User->>UI: 提交回饋
    UI->>WM: WebSocket 傳送
    WM->>MCP: 回饋完成
    MCP->>AI: 返回結果

多次循環調用

graph LR
    A[AI 首次調用] --> B[用戶回饋]
    B --> C[AI 處理回饋]
    C --> D[AI 再次調用]
    D --> E[會話無縫更新]
    E --> F[用戶再次回饋]
    F --> G[持續循環...]
    
    style D fill:#e1f5fe
    style E fill:#e8f5e8

---

下一步: 查看 組件詳細說明 了解各組件的具體實現