mirror of
https://github.com/Minidoracat/mcp-feedback-enhanced.git
synced 2025-07-27 10:42:25 +08:00
13 KiB
13 KiB
系統架構總覽
🏗️ 整體架構設計
MCP Feedback Enhanced 採用單一活躍會話 + 持久化 Web UI的創新架構設計,實現 AI 助手與用戶之間的高效、無縫交互體驗。
核心設計理念
- Web-Only 架構:完全基於 Web 技術,已移除所有 Electron 桌面應用功能
- 四層架構設計:清晰的層次分離,便於維護和擴展
- 智能環境檢測:自動識別本地、SSH Remote、WSL 環境並優化配置
- 單一活躍會話:替代傳統多會話管理,提升性能和用戶體驗
- 模組化設計:每層職責明確,支援獨立開發和測試
技術棧概覽
後端技術:
- Python 3.11+ (核心語言)
- FastMCP 2.0+ (MCP 協議實現)
- FastAPI 0.115+ (Web 框架)
- uvicorn 0.30+ (ASGI 服務器)
- WebSocket (實時通信)
前端技術:
- HTML5 + CSS3 (現代化 UI)
- JavaScript ES6+ (模組化架構)
- WebSocket API (雙向通信)
- 響應式設計 (多設備支援)
開發工具:
- pytest + pytest-asyncio (測試框架)
- Ruff + mypy (代碼品質)
- pre-commit (提交檢查)
- uv (依賴管理)
系統整體架構圖
graph TB
subgraph "AI 助手環境"
AI[AI 助手<br/>Cursor/Claude/Windsurf/Augment]
end
subgraph "MCP Feedback Enhanced - 四層架構"
subgraph "第一層:MCP 服務層"
SERVER[server.py<br/>MCP 服務器]
TOOL[interactive_feedback<br/>核心工具]
I18N[i18n.py<br/>國際化支援]
DEBUG[debug.py<br/>統一調試]
end
subgraph "第二層:Web UI 管理層"
MANAGER[WebUIManager<br/>單例管理器]
SESSION[WebFeedbackSession<br/>會話模型]
MODELS[數據模型<br/>FeedbackResult/SessionStatus]
end
subgraph "第三層:Web 服務層"
FASTAPI[FastAPI 應用<br/>main.py]
ROUTES[路由處理<br/>main_routes.py]
WS[WebSocket 通信<br/>實時雙向通信]
end
subgraph "第四層:前端交互層"
HTML[HTML 模板<br/>feedback.html/index.html]
JS[JavaScript 模組<br/>app.js + 功能模組]
CSS[樣式系統<br/>響應式設計]
PROMPT[提示詞管理<br/>PromptManager + UI 組件]
SESSION_MGR[會話管理<br/>SessionManager + 歷史追蹤]
AUTO_SUBMIT[自動提交<br/>AutoSubmitManager + 倒數計時]
end
subgraph "工具層"
UTILS[工具模組<br/>error_handler/memory_monitor]
BROWSER[瀏覽器控制<br/>智能開啟]
NETWORK[網路工具<br/>埠管理]
CLEANUP[資源管理<br/>會話清理]
end
end
subgraph "用戶環境"
BROWSER_UI[Web 瀏覽器]
USER[用戶互動<br/>文字/圖片/命令]
end
subgraph "運行環境"
LOCAL[本地環境]
SSH[SSH Remote]
WSL[WSL 環境]
end
AI -->|MCP 協議| SERVER
SERVER --> TOOL
TOOL --> MANAGER
MANAGER --> SESSION
MANAGER --> FASTAPI
FASTAPI --> ROUTES
ROUTES --> HTML
HTML --> JS
JS --> WS
WS -->|HTTP/WebSocket| BROWSER_UI
BROWSER_UI --> USER
%% 新功能模組連接
JS --> PROMPT
JS --> SESSION_MGR
JS --> AUTO_SUBMIT
PROMPT --> WS
SESSION_MGR --> WS
AUTO_SUBMIT --> WS
I18N --> ROUTES
DEBUG --> SERVER
UTILS --> MANAGER
BROWSER --> FASTAPI
NETWORK --> FASTAPI
CLEANUP --> SESSION
LOCAL -.->|環境檢測| MANAGER
SSH -.->|環境檢測| MANAGER
WSL -.->|環境檢測| MANAGER
USER -->|回饋提交| WS
MODELS --> SESSION
🎯 核心設計理念
1. Web-Only 架構優勢
完全移除桌面應用依賴:
- 無需安裝 Electron 或其他桌面應用框架
- 減少系統資源佔用和安全風險
- 支援所有具備現代瀏覽器的環境
- 簡化部署和維護流程
跨平台統一體驗:
- Windows、macOS、Linux 完全一致的用戶介面
- SSH Remote 和 WSL 環境無縫支援
- 響應式設計適應不同螢幕尺寸
- 無需平台特定的配置或調整
2. 四層架構設計
第一層 - MCP 服務層:
- 實現 MCP 協議標準
- 提供
interactive_feedback
核心工具 - 統一的國際化和調試支援
- 錯誤處理和日誌記錄
第二層 - Web UI 管理層:
- 單例模式的 WebUIManager
- 會話生命週期管理
- 數據模型和狀態管理
- 瀏覽器智能控制
第三層 - Web 服務層:
- FastAPI 高性能 Web 框架
- RESTful API 和 WebSocket 支援
- 路由處理和中間件
- 靜態資源服務
第四層 - 前端交互層:
- 模組化 JavaScript 架構
- 響應式 HTML/CSS 設計
- 實時 WebSocket 通信
- 豐富的用戶交互功能
- 提示詞管理系統:常用提示詞的 CRUD 操作和快速選擇
- 會話管理功能:會話歷史追蹤和統計分析
- 自動提交機制:倒數計時器和自動回饋提交
3. 單一活躍會話模式
stateDiagram-v2
[*] --> NoSession: 系統啟動
NoSession --> ActiveSession: AI 首次調用
ActiveSession --> SessionUpdated: AI 再次調用
SessionUpdated --> ActiveSession: 會話切換完成
ActiveSession --> Cleanup: 超時或手動清理
Cleanup --> NoSession: 資源釋放
note right of ActiveSession
只維護一個活躍會話
提升性能和用戶體驗
end note
4. 持久化 Web UI 架構
智能會話管理:
- 瀏覽器標籤頁保持: 避免重複開啟瀏覽器視窗
- WebSocket 連接復用: 減少連接建立開銷和延遲
- 狀態無縫切換: 從 SUBMITTED → WAITING 自動轉換
- 內容局部更新: 只更新必要的 UI 元素,保持用戶操作狀態
會話持久性:
- 支援 AI 助手多次循環調用
- 會話狀態在調用間保持
- 自動超時清理機制
- 記憶體使用優化
5. 國際化與本地化
多語言支援:
- 繁體中文、簡體中文、英文
- 系統語言自動檢測
- 用戶偏好設定保存
- 動態語言切換
本地化特性:
- 文化適應的日期時間格式
- 本地化的錯誤訊息
- 地區特定的 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. 智能環境檢測與適配
環境自動識別:
- 本地開發環境檢測
- SSH Remote 環境識別
- WSL 子系統檢測
- 容器化環境支援
瀏覽器智能開啟:
- 活躍標籤頁檢測: 避免重複開啟瀏覽器視窗
- 跨平台支援: Windows, macOS, Linux 自動適配
- 環境感知: SSH/WSL 環境特殊處理
- 錯誤恢復: 開啟失敗時的備用方案
3. 高性能實時通信
WebSocket 雙向通信:
- 前後端狀態實時同步
- 低延遲消息傳遞
- 自動重連機制
- 心跳檢測保持連接
狀態管理優化:
- 會話更新通知: 立即推送會話變更
- 增量更新: 只傳輸變更的數據
- 狀態快照: 支援狀態回滾和恢復
- 錯誤處理: 連接斷線自動重連
4. 模組化前端架構
JavaScript 模組系統:
// 模組化載入順序
utils → tab-manager → websocket-manager →
image-handler → settings-manager → ui-manager →
auto-refresh-manager → app
功能模組分離:
- 標籤頁管理 (tab-manager.js)
- WebSocket 通信 (websocket-manager.js)
- 圖片處理 (image-handler.js)
- 設定管理 (settings-manager.js)
- UI 控制 (ui-manager.js)
- 自動刷新 (auto-refresh-manager.js)
- 提示詞管理模組群組:
- prompt-manager.js (核心管理器)
- prompt-modal.js (編輯彈窗)
- prompt-settings-ui.js (設定界面)
- prompt-input-buttons.js (快速選擇按鈕)
- 會話管理模組群組:
- session-manager.js (會話控制器)
- session-data-manager.js (數據管理器)
- session-utils.js (工具函數)
- 自動提交功能:
- 整合在 app.js 中的 AutoSubmitManager
- 與提示詞管理和設定管理的深度整合
📊 性能特性與優化
資源使用優化
記憶體管理:
- 單一會話模式: 相比傳統多會話減少 60% 記憶體使用
- 智能垃圾回收: 自動清理過期會話和臨時資源
- 記憶體監控: 實時監控記憶體使用情況
- 資源池化: 重用常用對象減少分配開銷
網路性能:
- 連接復用: WebSocket 連接保持,減少建立開銷
- 數據壓縮: 自動壓縮大型數據傳輸
- 批量操作: 合併多個小請求減少網路往返
- 快取策略: 靜態資源和翻譯文件快取
啟動性能:
- 延遲載入: 按需載入 JavaScript 模組
- 預載入優化: 關鍵資源優先載入
- 並行初始化: 多個組件並行啟動
- 快速響應: 首屏渲染時間 < 500ms
用戶體驗提升
交互響應性:
- 零等待切換: 會話更新無需重新載入頁面
- 即時反饋: 用戶操作立即響應
- 平滑動畫: CSS3 動畫提升視覺體驗
- 鍵盤快捷鍵: 提升操作效率
連續工作流程:
- 連續交互: 支援 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
🔍 安全性考量
數據安全
輸入驗證:
- 嚴格的參數類型檢查
- SQL 注入防護
- XSS 攻擊防護
- 文件上傳安全檢查
網路安全:
- 本地綁定 (127.0.0.1) 減少攻擊面
- WebSocket 連接驗證
- CORS 政策控制
- 安全標頭設定
資源保護:
- 文件系統訪問限制
- 記憶體使用限制
- 執行時間限制
- 臨時文件安全清理
🚀 部署與維護
環境需求
最低系統需求:
- Python 3.11 或更高版本
- 512MB 可用記憶體
- 現代瀏覽器 (Chrome 90+, Firefox 88+, Safari 14+)
- 網路連接 (本地環境可離線運行)
推薦配置:
- Python 3.12
- 1GB 可用記憶體
- SSD 儲存
- 穩定的網路連接
維護特性
自動化維護:
- 自動日誌輪轉
- 定期資源清理
- 健康狀態檢查
- 性能指標收集
監控與診斷:
- 詳細的調試日誌
- 性能指標追蹤
- 錯誤統計分析
- 系統資源監控
📚 相關文檔
版本: 2.4.0 最後更新: 2025年6月 維護者: Minidoracat 架構類型: Web-Only 四層架構 新功能: 提示詞管理、自動提交、會話管理、語系切換優化