diff --git a/docs/architecture/README.md b/docs/architecture/README.md new file mode 100644 index 0000000..ff4f881 --- /dev/null +++ b/docs/architecture/README.md @@ -0,0 +1,54 @@ +# MCP Feedback Enhanced 架構文檔 + +## 📋 文檔索引 + +本目錄包含 MCP Feedback Enhanced 專案的完整架構文檔,提供深入的技術分析和設計說明。 + +### 📚 文檔結構 + +| 文檔 | 描述 | 適用對象 | +|------|------|----------| +| [系統架構總覽](./system-overview.md) | 整體架構設計、核心概念和技術亮點 | 架構師、技術負責人 | +| [組件詳細說明](./component-details.md) | 各層級組件的詳細功能和實現 | 開發人員、維護人員 | +| [交互流程文檔](./interaction-flows.md) | AI 助手與 MCP 服務的完整交互流程 | 集成開發人員 | +| [API 參考文檔](./api-reference.md) | MCP 工具接口和 WebSocket API 規範 | API 使用者、前端開發 | +| [部署指南](./deployment-guide.md) | 環境配置、部署選項和故障排除 | 運維人員、系統管理員 | + +### 🏗️ 架構概覽 + +MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新架構,實現了 AI 助手與用戶之間的無縫交互體驗。 + +#### 核心特性 +- **智能環境檢測**: 自動識別 Local/SSH Remote/WSL 環境 +- **單一活躍會話**: 替代傳統多會話管理,提升性能和用戶體驗 +- **持久化 Web UI**: 支援多次循環調用,無需重複開啟瀏覽器 +- **實時雙向通信**: WebSocket 實現前後端狀態同步 +- **智能資源管理**: 自動清理和會話生命週期管理 + +#### 技術棧 +- **後端**: Python 3.11+, FastAPI, FastMCP +- **前端**: HTML5, JavaScript ES6+, WebSocket +- **通信**: WebSocket, HTTP REST API +- **部署**: uvicorn, 跨平台支援 + +### 🎯 快速導航 + +- **新手入門**: 從 [系統架構總覽](./system-overview.md) 開始 +- **深入理解**: 閱讀 [組件詳細說明](./component-details.md) +- **集成開發**: 參考 [交互流程文檔](./interaction-flows.md) 和 [API 參考文檔](./api-reference.md) +- **部署運維**: 查看 [部署指南](./deployment-guide.md) + +### 📊 架構圖表 + +所有文檔都包含豐富的 Mermaid 圖表,包括: +- 系統整體架構圖 +- 組件關係圖 +- 交互流程圖 +- 會話生命週期圖 +- 部署拓撲圖 + +--- + +**版本**: 2.3.0 +**最後更新**: 2024年12月 +**維護者**: Minidoracat diff --git a/docs/architecture/api-reference.md b/docs/architecture/api-reference.md new file mode 100644 index 0000000..aa8430e --- /dev/null +++ b/docs/architecture/api-reference.md @@ -0,0 +1,341 @@ +# API 參考文檔 + +## 📡 MCP 工具 API + +### interactive_feedback + +AI 助手與用戶進行交互式回饋的核心 MCP 工具。 + +#### 函數簽名 +```python +async def interactive_feedback( + project_directory: str, + summary: str, + timeout: int = 600 +) -> dict +``` + +#### 參數說明 + +| 參數 | 類型 | 必需 | 預設值 | 描述 | +|------|------|------|--------|------| +| `project_directory` | `str` | ✅ | - | 專案目錄路徑,用於上下文顯示 | +| `summary` | `str` | ✅ | - | AI 助手的工作摘要,向用戶說明當前狀態 | +| `timeout` | `int` | ❌ | `600` | 等待用戶回饋的超時時間(秒) | + +#### 返回值 +```python +{ + "command_logs": "", # 命令執行日誌(保留字段) + "interactive_feedback": str, # 用戶回饋內容 + "images": List[str] # 用戶上傳的圖片(Base64 編碼) +} +``` + +#### 使用示例 +```python +# 基本調用 +result = await interactive_feedback( + project_directory="./my-web-app", + summary="我已完成登入功能的實現,包括表單驗證和錯誤處理。請檢查代碼品質。" +) + +# 自定義超時 +result = await interactive_feedback( + project_directory="./complex-project", + summary="重構完成,請詳細測試所有功能模組。", + timeout=1200 # 20分鐘 +) +``` + +#### 錯誤處理 +```python +try: + result = await interactive_feedback(...) +except TimeoutError: + print("用戶回饋超時") +except ValidationError as e: + print(f"參數驗證錯誤: {e}") +except EnvironmentError as e: + print(f"環境檢測錯誤: {e}") +``` + +## 🌐 Web API + +### HTTP 端點 + +#### GET / +主頁重定向到回饋頁面。 + +**響應**: `302 Redirect` → `/feedback` + +#### GET /feedback +回饋頁面主入口。 + +**響應**: `200 OK` +```html + + + + +``` + +#### GET /static/{path} +靜態資源服務(CSS、JS、圖片等)。 + +**參數**: +- `path`: 靜態資源路徑 + +**響應**: `200 OK` 或 `404 Not Found` + +### WebSocket API + +#### 連接端點 +``` +ws://localhost:{port}/ws +``` + +#### 訊息格式 +所有 WebSocket 訊息都使用 JSON 格式: +```json +{ + "type": "message_type", + "data": { /* 訊息數據 */ }, + "timestamp": "2024-12-XX 10:30:00" +} +``` + +### 📤 客戶端 → 服務器訊息 + +#### submit_feedback +提交用戶回饋。 + +```json +{ + "type": "submit_feedback", + "data": { + "feedback": "這個功能很好,但建議增加輸入驗證。", + "images": [ + "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..." + ], + "settings": { + "language": "zh-TW", + "compress_images": true + } + } +} +``` + +**字段說明**: +- `feedback`: 用戶回饋文字內容 +- `images`: 圖片數組(Base64 編碼) +- `settings.language`: 界面語言 +- `settings.compress_images`: 是否壓縮圖片 + +#### heartbeat +心跳檢測訊息。 + +```json +{ + "type": "heartbeat", + "data": { + "timestamp": 1703123456789 + } +} +``` + +#### language_switch +切換界面語言。 + +```json +{ + "type": "language_switch", + "data": { + "language": "en" + } +} +``` + +### 📥 服務器 → 客戶端訊息 + +#### connection_established +WebSocket 連接建立確認。 + +```json +{ + "type": "connection_established", + "data": { + "session_id": "550e8400-e29b-41d4-a716-446655440000", + "server_time": "2024-12-XX 10:30:00" + } +} +``` + +#### session_updated +會話更新通知(AI 再次調用時)。 + +```json +{ + "type": "session_updated", + "data": { + "session_id": "new-session-id", + "summary": "根據您的建議,我已修改了錯誤處理邏輯。", + "project_directory": "./my-project", + "timestamp": "2024-12-XX 10:35:00" + } +} +``` + +#### feedback_received +回饋接收確認。 + +```json +{ + "type": "feedback_received", + "data": { + "session_id": "session-id", + "status": "success", + "message": "回饋已成功接收" + } +} +``` + +#### status_update +狀態更新通知。 + +```json +{ + "type": "status_update", + "data": { + "status": "FEEDBACK_PROCESSING", + "message": "正在處理您的回饋...", + "progress": 50 + } +} +``` + +#### error +錯誤訊息。 + +```json +{ + "type": "error", + "data": { + "error_code": "VALIDATION_ERROR", + "message": "回饋內容不能為空", + "details": { + "field": "feedback", + "value": "" + } + } +} +``` + +## 🔧 內部 API + +### WebUIManager API + +#### create_session() +```python +async def create_session( + self, + summary: str, + project_directory: str +) -> WebFeedbackSession +``` + +創建新的回饋會話。 + +#### smart_open_browser() +```python +async def smart_open_browser(self, url: str) -> bool +``` + +智能開啟瀏覽器,避免重複開啟。 + +**返回值**: +- `True`: 檢測到活躍標籤頁,未開啟新視窗 +- `False`: 開啟了新瀏覽器視窗 + +### WebFeedbackSession API + +#### submit_feedback() +```python +async def submit_feedback( + self, + feedback: str, + images: List[str], + settings: dict +) -> None +``` + +提交用戶回饋到會話。 + +#### wait_for_feedback() +```python +async def wait_for_feedback(self, timeout: int = 600) -> dict +``` + +等待用戶回饋完成。 + +#### add_websocket() +```python +def add_websocket(self, websocket: WebSocket) -> None +``` + +添加 WebSocket 連接到會話。 + +## 📊 狀態碼和錯誤碼 + +### HTTP 狀態碼 +- `200 OK`: 請求成功 +- `302 Found`: 重定向 +- `404 Not Found`: 資源不存在 +- `500 Internal Server Error`: 服務器內部錯誤 + +### WebSocket 錯誤碼 +```python +class ErrorCodes: + VALIDATION_ERROR = "VALIDATION_ERROR" + SESSION_NOT_FOUND = "SESSION_NOT_FOUND" + TIMEOUT_ERROR = "TIMEOUT_ERROR" + PROCESSING_ERROR = "PROCESSING_ERROR" + CONNECTION_ERROR = "CONNECTION_ERROR" +``` + +### 會話狀態 +```python +class SessionStatus: + WAITING = "FEEDBACK_WAITING" + PROCESSING = "FEEDBACK_PROCESSING" + SUBMITTED = "FEEDBACK_SUBMITTED" + ERROR = "ERROR" +``` + +## 🔒 安全考慮 + +### 輸入驗證 +- 回饋內容長度限制:最大 10,000 字符 +- 圖片大小限制:單張最大 5MB +- 圖片數量限制:最多 10 張 +- 支援的圖片格式:PNG, JPEG, GIF, WebP + +### 資源保護 +- WebSocket 連接數限制:每會話最多 5 個連接 +- 會話超時自動清理 +- 內存使用監控和限制 + +### 跨域設置 +```python +app.add_middleware( + CORSMiddleware, + allow_origins=["*"], # 開發環境,生產環境應限制 + allow_credentials=True, + allow_methods=["*"], + allow_headers=["*"], +) +``` + +--- + +**下一步**: 查看 [部署指南](./deployment-guide.md) 了解部署配置和運維指南 diff --git a/docs/architecture/component-details.md b/docs/architecture/component-details.md new file mode 100644 index 0000000..94e10f8 --- /dev/null +++ b/docs/architecture/component-details.md @@ -0,0 +1,285 @@ +# 組件詳細說明 + +## 🏗️ 四層架構組件 + +MCP Feedback Enhanced 採用清晰的四層架構設計,每層負責特定的功能領域。 + +### 組件關係圖 + +```mermaid +graph TB + subgraph "第一層:MCP 服務層" + SERVER[server.py
MCP 服務器] + TOOL[interactive_feedback
核心工具] + I18N[i18n.py
國際化支援] + end + + subgraph "第二層:Web UI 管理層" + MANAGER[WebUIManager
單例管理器] + SESSION[WebFeedbackSession
會話模型] + RESULT[FeedbackResult
結果模型] + end + + subgraph "第三層:Web 服務層" + MAIN[main.py
FastAPI 應用] + ROUTES[main_routes.py
路由處理] + WS[WebSocket
實時通信] + end + + subgraph "第四層:前端交互層" + HTML[feedback.html
主頁面] + JS[app.js
交互邏輯] + CSS[樣式文件] + end + + subgraph "工具層" + BROWSER[browser.py
瀏覽器控制] + NETWORK[network.py
網路工具] + PORT[port_manager.py
埠管理] + CLEANUP[session_cleanup_manager.py
清理管理] + COMPRESS[compression_*.py
壓縮工具] + end + + SERVER --> MANAGER + TOOL --> SESSION + MANAGER --> MAIN + SESSION --> ROUTES + ROUTES --> HTML + HTML --> JS + + BROWSER --> MANAGER + NETWORK --> MAIN + PORT --> MAIN + CLEANUP --> SESSION + COMPRESS --> ROUTES +``` + +## 🔧 第一層:MCP 服務層 + +### server.py - MCP 服務器核心 +```python +# 核心功能架構 +class MCPServer: + def __init__(self): + self.app = FastMCP("mcp-feedback-enhanced") + self.setup_tools() + + @self.app.tool() + async def interactive_feedback( + project_directory: str, + summary: str, + timeout: int = 600 + ) -> dict: + # 環境檢測與驗證 + # Web UI 啟動 + # 會話管理 + # 回饋等待與處理 +``` + +**主要職責**: +- MCP 協議實現和工具註冊 +- 環境檢測 (Local/SSH/WSL) +- Web UI 生命週期管理 +- 與 AI 助手的接口層 + +### interactive_feedback 工具 +```mermaid +flowchart TD + START[工具調用] --> VALIDATE[參數驗證] + VALIDATE --> ENV[環境檢測] + ENV --> LAUNCH[啟動 Web UI] + LAUNCH --> SESSION[創建/更新會話] + SESSION --> WAIT[等待用戶回饋] + WAIT --> TIMEOUT{超時檢查} + TIMEOUT -->|未超時| FEEDBACK[接收回饋] + TIMEOUT -->|超時| ERROR[超時錯誤] + FEEDBACK --> RETURN[返回結果] + ERROR --> RETURN +``` + +### i18n.py - 國際化支援 +- **多語言支援**: 繁體中文、簡體中文、英文 +- **動態語言切換**: 基於用戶偏好自動選擇 +- **模組化翻譯**: 分離的語言包管理 + +## 🎛️ 第二層:Web UI 管理層 + +### WebUIManager - 核心管理器 +```python +class WebUIManager: + def __init__(self): + self.current_session: Optional[WebFeedbackSession] = None + self.global_active_tabs: Dict[str, dict] = {} + self.app: Optional[FastAPI] = None + self.server_process: Optional[subprocess.Popen] = None +``` + +**關鍵特性**: +- **單例模式**: 確保全局唯一實例 +- **會話生命週期**: 創建、更新、清理會話 +- **智能瀏覽器開啟**: 避免重複開啟視窗 +- **資源管理**: 自動清理和錯誤處理 + +### WebFeedbackSession - 會話模型 +```mermaid +stateDiagram-v2 + [*] --> WAITING: 會話創建 + WAITING --> FEEDBACK_PROCESSING: 用戶提交 + FEEDBACK_PROCESSING --> FEEDBACK_SUBMITTED: 處理完成 + FEEDBACK_SUBMITTED --> WAITING: 新會話更新 + FEEDBACK_SUBMITTED --> [*]: 會話結束 + + note right of WAITING + 等待用戶輸入 + 顯示 AI 摘要 + end note + + note right of FEEDBACK_PROCESSING + 處理回饋數據 + 圖片壓縮等 + end note +``` + +**狀態管理**: +- `WAITING`: 等待用戶回饋 +- `FEEDBACK_PROCESSING`: 處理回饋中 +- `FEEDBACK_SUBMITTED`: 回饋已提交 + +## 🌐 第三層:Web 服務層 + +### main.py - FastAPI 應用 +```python +class FastAPIApp: + def __init__(self): + self.app = FastAPI() + self.setup_middleware() + self.setup_routes() + self.setup_websocket() + + def setup_middleware(self): + # CORS 設定 + # 靜態文件服務 + # 錯誤處理中間件 +``` + +**核心功能**: +- HTTP 路由處理 +- WebSocket 連接管理 +- 靜態資源服務 +- 中間件配置 + +### main_routes.py - 路由處理 +```mermaid +graph LR + subgraph "HTTP 路由" + GET[GET /] + FEEDBACK[GET /feedback] + STATIC[靜態資源] + end + + subgraph "WebSocket 路由" + WS[/ws] + MSG[訊息處理] + BROADCAST[廣播機制] + end + + GET --> FEEDBACK + FEEDBACK --> STATIC + WS --> MSG + MSG --> BROADCAST +``` + +**WebSocket 訊息類型**: +- `connection_established`: 連接建立 +- `session_updated`: 會話更新 +- `submit_feedback`: 提交回饋 +- `feedback_received`: 回饋確認 +- `status_update`: 狀態更新 + +## 🎨 第四層:前端交互層 + +### feedback.html - 主頁面 +```html + +
+
+
+
+
+
+
+ +
+``` + +### app.js - 交互邏輯 +```javascript +class FeedbackApp { + constructor() { + this.websocket = null; + this.currentSession = null; + this.feedbackState = 'WAITING'; + } + + // WebSocket 管理 + initWebSocket() { /* ... */ } + handleWebSocketMessage(data) { /* ... */ } + + // 用戶交互 + submitFeedback() { /* ... */ } + handleImageUpload() { /* ... */ } + + // UI 更新 + updateSessionDisplay() { /* ... */ } + updateFeedbackState() { /* ... */ } +} +``` + +**前端特性**: +- **響應式設計**: 適配不同螢幕尺寸 +- **實時狀態同步**: WebSocket 雙向通信 +- **圖片上傳**: 拖拽上傳和自動壓縮 +- **多語言支援**: 動態語言切換 + +## 🛠️ 工具層組件 + +### browser.py - 瀏覽器控制 +```python +class BrowserManager: + @staticmethod + def open_browser(url: str, environment: str): + if environment == "local": + webbrowser.open(url) + elif environment == "ssh": + # SSH 隧道處理 + elif environment == "wsl": + # WSL 特殊處理 +``` + +### port_manager.py - 埠管理 +- **動態埠分配**: 自動尋找可用埠 +- **埠衝突檢測**: 避免埠佔用問題 +- **埠範圍配置**: 可配置的埠範圍 + +### session_cleanup_manager.py - 清理管理 +```mermaid +graph TD + TIMER[定時器啟動] --> CHECK[檢查會話狀態] + CHECK --> TIMEOUT{會話超時?} + TIMEOUT -->|是| CLEANUP[執行清理] + TIMEOUT -->|否| WAIT[等待下次檢查] + CLEANUP --> WEBSOCKET[關閉 WebSocket] + WEBSOCKET --> PROCESS[終止進程] + PROCESS --> MEMORY[釋放內存] + MEMORY --> WAIT + WAIT --> CHECK +``` + +**清理策略**: +- **超時清理**: 會話超時自動清理 +- **資源回收**: WebSocket、進程、內存 +- **優雅關閉**: 確保資源正確釋放 + +--- + +**下一步**: 查看 [交互流程文檔](./interaction-flows.md) 了解完整的交互機制 diff --git a/docs/architecture/deployment-guide.md b/docs/architecture/deployment-guide.md new file mode 100644 index 0000000..ba4e11b --- /dev/null +++ b/docs/architecture/deployment-guide.md @@ -0,0 +1,406 @@ +# 部署指南 + +## 🚀 部署架構概覽 + +MCP Feedback Enhanced 支援多種部署環境,具備智能環境檢測和自適應配置能力。 + +### 部署拓撲圖 + +```mermaid +graph TB + subgraph "本地開發環境" + LOCAL[本地機器] + LOCAL_BROWSER[本地瀏覽器] + LOCAL --> LOCAL_BROWSER + end + + subgraph "SSH 遠程環境" + REMOTE[遠程服務器] + SSH_TUNNEL[SSH 隧道] + LOCAL_CLIENT[本地客戶端] + REMOTE --> SSH_TUNNEL + SSH_TUNNEL --> LOCAL_CLIENT + end + + subgraph "WSL 環境" + WSL[WSL 子系統] + WIN_BROWSER[Windows 瀏覽器] + WSL --> WIN_BROWSER + end + + subgraph "容器化部署" + DOCKER[Docker 容器] + PORT_MAP[埠映射] + HOST[宿主機] + DOCKER --> PORT_MAP + PORT_MAP --> HOST + end +``` + +## 🛠️ 安裝和配置 + +### 系統要求 + +#### 最低要求 +- **Python**: 3.11 或更高版本 +- **內存**: 512MB 可用內存 +- **磁盤**: 100MB 可用空間 +- **網路**: 可訪問的網路連接 + +#### 推薦配置 +- **Python**: 3.12+ +- **內存**: 1GB+ 可用內存 +- **磁盤**: 500MB+ 可用空間 +- **CPU**: 2 核心或更多 + +### 安裝方式 + +#### 1. 使用 uvx(推薦) +```bash +# 直接運行 +uvx mcp-feedback-enhanced@latest web + +# 指定版本 +uvx mcp-feedback-enhanced@2.3.0 web +``` + +#### 2. 使用 pip +```bash +# 安裝 +pip install mcp-feedback-enhanced + +# 運行 +mcp-feedback-enhanced web +``` + +#### 3. 從源碼安裝 +```bash +# 克隆倉庫 +git clone https://github.com/Minidoracat/mcp-feedback-enhanced.git +cd mcp-feedback-enhanced + +# 使用 uv 安裝 +uv sync + +# 運行 +uv run python -m mcp_feedback_enhanced web +``` + +## 🌍 環境配置 + +### 環境檢測機制 + +```mermaid +flowchart TD + START[啟動檢測] --> SSH{SSH 環境?} + SSH -->|是| SSH_CONFIG[SSH 配置] + SSH -->|否| WSL{WSL 環境?} + WSL -->|是| WSL_CONFIG[WSL 配置] + WSL -->|否| LOCAL_CONFIG[本地配置] + + SSH_CONFIG --> TUNNEL[建立 SSH 隧道] + WSL_CONFIG --> WSL_BROWSER[WSL 瀏覽器開啟] + LOCAL_CONFIG --> LOCAL_BROWSER[本地瀏覽器開啟] + + TUNNEL --> SUCCESS[部署成功] + WSL_BROWSER --> SUCCESS + LOCAL_BROWSER --> SUCCESS +``` + +### 1. 本地環境部署 + +**特點**: +- 直接在本地機器運行 +- 自動開啟本地瀏覽器 +- 最簡單的部署方式 + +**配置**: +```bash +# 運行命令 +mcp-feedback-enhanced web + +# 自動檢測並開啟瀏覽器 +# 默認地址: http://localhost:8000 +``` + +### 2. SSH 遠程環境部署 + +**特點**: +- 在遠程服務器運行服務 +- 自動建立 SSH 隧道 +- 本地瀏覽器訪問遠程服務 + +**配置步驟**: + +1. **在遠程服務器安裝**: +```bash +# SSH 連接到遠程服務器 +ssh user@remote-server + +# 安裝服務 +pip install mcp-feedback-enhanced +``` + +2. **運行服務**: +```bash +# 在遠程服務器運行 +mcp-feedback-enhanced web --host 0.0.0.0 --port 8000 +``` + +3. **建立 SSH 隧道**(自動或手動): +```bash +# 手動建立隧道(如果自動檢測失敗) +ssh -L 8000:localhost:8000 user@remote-server +``` + +### 3. WSL 環境部署 + +**特點**: +- 在 WSL 子系統中運行 +- 自動開啟 Windows 瀏覽器 +- 跨系統無縫集成 + +**配置**: +```bash +# 在 WSL 中運行 +mcp-feedback-enhanced web + +# 自動檢測 WSL 環境並開啟 Windows 瀏覽器 +``` + +### 4. 容器化部署 + +#### Docker 部署 +```dockerfile +# Dockerfile +FROM python:3.12-slim + +WORKDIR /app +COPY . . + +RUN pip install mcp-feedback-enhanced + +EXPOSE 8000 + +CMD ["mcp-feedback-enhanced", "web", "--host", "0.0.0.0", "--port", "8000"] +``` + +```bash +# 構建和運行 +docker build -t mcp-feedback-enhanced . +docker run -p 8000:8000 mcp-feedback-enhanced +``` + +#### Docker Compose +```yaml +# docker-compose.yml +version: '3.8' + +services: + mcp-feedback: + build: . + ports: + - "8000:8000" + environment: + - ENVIRONMENT=docker + volumes: + - ./projects:/app/projects + restart: unless-stopped +``` + +## ⚙️ 配置選項 + +### 命令行參數 + +```bash +mcp-feedback-enhanced web [OPTIONS] +``` + +| 參數 | 類型 | 預設值 | 描述 | +|------|------|--------|------| +| `--host` | `str` | `localhost` | 綁定的主機地址 | +| `--port` | `int` | `8000` | 服務埠號 | +| `--debug` | `bool` | `False` | 啟用調試模式 | +| `--no-browser` | `bool` | `False` | 不自動開啟瀏覽器 | +| `--timeout` | `int` | `600` | 預設會話超時時間(秒) | + +### 環境變數 + +```bash +# 設置環境變數 +export MCP_FEEDBACK_HOST=0.0.0.0 +export MCP_FEEDBACK_PORT=9000 +export MCP_FEEDBACK_DEBUG=true +export MCP_FEEDBACK_TIMEOUT=1200 +``` + +### 配置文件 +```json +// config.json +{ + "server": { + "host": "localhost", + "port": 8000, + "debug": false + }, + "session": { + "timeout": 600, + "max_connections": 5 + }, + "ui": { + "default_language": "zh-TW", + "theme": "light" + } +} +``` + +## 🔧 運維管理 + +### 服務監控 + +#### 健康檢查端點 +```bash +# 檢查服務狀態 +curl http://localhost:8000/health + +# 響應示例 +{ + "status": "healthy", + "version": "2.3.0", + "uptime": "2h 30m 15s", + "active_sessions": 1 +} +``` + +#### 日誌監控 +```python +# 日誌配置 +import logging + +logging.basicConfig( + level=logging.INFO, + format='%(asctime)s - %(name)s - %(levelname)s - %(message)s', + handlers=[ + logging.FileHandler('mcp-feedback.log'), + logging.StreamHandler() + ] +) +``` + +### 性能調優 + +#### 內存優化 +```python +# 會話清理配置 +SESSION_CLEANUP_INTERVAL = 300 # 5分鐘 +SESSION_TIMEOUT = 600 # 10分鐘 +MAX_CONCURRENT_SESSIONS = 10 +``` + +#### 網路優化 +```python +# WebSocket 配置 +WEBSOCKET_PING_INTERVAL = 30 +WEBSOCKET_PING_TIMEOUT = 10 +MAX_WEBSOCKET_CONNECTIONS = 50 +``` + +### 故障排除 + +#### 常見問題 + +1. **埠被佔用** +```bash +# 檢查埠使用情況 +netstat -tulpn | grep 8000 + +# 解決方案:使用不同埠 +mcp-feedback-enhanced web --port 8001 +``` + +2. **瀏覽器無法開啟** +```bash +# 手動開啟瀏覽器 +mcp-feedback-enhanced web --no-browser +# 然後手動訪問 http://localhost:8000 +``` + +3. **SSH 隧道失敗** +```bash +# 手動建立隧道 +ssh -L 8000:localhost:8000 user@remote-server + +# 或使用不同埠 +ssh -L 8001:localhost:8000 user@remote-server +``` + +#### 調試模式 +```bash +# 啟用詳細日誌 +mcp-feedback-enhanced web --debug + +# 查看詳細錯誤信息 +export PYTHONPATH=. +python -m mcp_feedback_enhanced.debug +``` + +### 安全配置 + +#### 生產環境安全 +```python +# 限制 CORS +app.add_middleware( + CORSMiddleware, + allow_origins=["https://yourdomain.com"], + allow_credentials=True, + allow_methods=["GET", "POST"], + allow_headers=["*"], +) + +# 添加安全標頭 +@app.middleware("http") +async def add_security_headers(request, call_next): + response = await call_next(request) + response.headers["X-Content-Type-Options"] = "nosniff" + response.headers["X-Frame-Options"] = "DENY" + response.headers["X-XSS-Protection"] = "1; mode=block" + return response +``` + +#### 防火牆配置 +```bash +# Ubuntu/Debian +sudo ufw allow 8000/tcp + +# CentOS/RHEL +sudo firewall-cmd --permanent --add-port=8000/tcp +sudo firewall-cmd --reload +``` + +## 📊 監控和指標 + +### 系統指標 +- CPU 使用率 +- 內存使用量 +- 網路連接數 +- 活躍會話數 + +### 業務指標 +- 會話創建率 +- 回饋提交率 +- 平均回應時間 +- 錯誤率 + +### 監控工具集成 +```python +# Prometheus 指標 +from prometheus_client import Counter, Histogram, Gauge + +session_counter = Counter('mcp_sessions_total', 'Total sessions created') +response_time = Histogram('mcp_response_time_seconds', 'Response time') +active_sessions = Gauge('mcp_active_sessions', 'Active sessions') +``` + +--- + +**完成**: 架構文檔體系已建立完成,包含完整的技術文檔和部署指南。 diff --git a/docs/architecture/interaction-flows.md b/docs/architecture/interaction-flows.md new file mode 100644 index 0000000..da9c8c3 --- /dev/null +++ b/docs/architecture/interaction-flows.md @@ -0,0 +1,307 @@ +# 交互流程文檔 + +## 🔄 AI 助手與 MCP 服務完整交互流程 + +本文檔詳細描述 AI 助手調用 MCP Feedback Enhanced 服務的完整流程,包括首次調用和多次循環調用的機制。 + +## 📋 流程概覽 + +### 整體交互時序圖 + +```mermaid +sequenceDiagram + participant AI as AI 助手 + participant MCP as MCP 服務 + participant WM as WebUIManager + participant WS as WebSocket + participant UI as Web UI + participant User as 用戶 + + Note over AI,User: 第一次調用流程 + AI->>MCP: interactive_feedback(summary, timeout) + MCP->>WM: launch_web_feedback_ui() + WM->>WM: 創建新會話 + WM->>WS: 啟動 Web 服務器 + WM->>User: 智能開啟瀏覽器 + User->>UI: 訪問回饋頁面 + UI->>WS: 建立 WebSocket 連接 + WS->>UI: connection_established + + Note over AI,User: 用戶回饋流程 + User->>UI: 填寫回饋內容 + UI->>WS: submit_feedback + WS->>WM: 處理回饋數據 + WM->>MCP: 設置回饋完成 + MCP->>AI: 返回回饋結果 + + Note over AI,User: 第二次調用流程 + AI->>MCP: interactive_feedback(new_summary, timeout) + MCP->>WM: 更新現有會話 + WM->>WS: session_updated 通知 + WS->>UI: 會話更新訊息 + UI->>UI: 局部更新內容 + User->>UI: 提交新回饋 + UI->>WS: submit_feedback + WS->>WM: 處理新回饋 + WM->>MCP: 設置回饋完成 + MCP->>AI: 返回新回饋結果 +``` + +## 🚀 第一次調用詳細流程 + +### 1. AI 助手發起調用 + +```python +# AI 助手調用示例 +result = await interactive_feedback( + project_directory="./my-project", + summary="我已完成了功能 X 的實現,請檢查代碼品質和邏輯正確性", + timeout=600 +) +``` + +### 2. MCP 服務處理流程 + +```mermaid +flowchart TD + START[AI 調用 interactive_feedback] --> VALIDATE[參數驗證] + VALIDATE --> ENV[環境檢測] + ENV --> LAUNCH[調用 launch_web_feedback_ui] + LAUNCH --> SESSION[創建新會話] + SESSION --> SERVER[啟動 Web 服務器] + SERVER --> BROWSER[智能開啟瀏覽器] + BROWSER --> WAIT[等待用戶回饋] + WAIT --> TIMEOUT{檢查超時} + TIMEOUT -->|未超時| FEEDBACK[接收回饋] + TIMEOUT -->|超時| ERROR[返回超時錯誤] + FEEDBACK --> RETURN[返回結果給 AI] + ERROR --> RETURN +``` + +**關鍵步驟說明**: + +#### 2.1 環境檢測 +```python +def detect_environment(): + if os.environ.get('SSH_CLIENT') or os.environ.get('SSH_TTY'): + return "ssh" + elif 'microsoft' in platform.uname().release.lower(): + return "wsl" + else: + return "local" +``` + +#### 2.2 會話創建 +```python +async def create_session(self, summary: str, project_dir: str): + # 保存舊會話的 WebSocket 連接 + old_websockets = [] + if self.current_session: + old_websockets = list(self.current_session.websockets) + + # 創建新會話 + session_id = str(uuid.uuid4()) + self.current_session = WebFeedbackSession( + session_id=session_id, + summary=summary, + project_directory=project_dir + ) + + # 繼承 WebSocket 連接 + for ws in old_websockets: + self.current_session.add_websocket(ws) + + # 標記需要發送會話更新 + self._pending_session_update = True +``` + +### 3. Web UI 連接建立 + +```mermaid +sequenceDiagram + participant Browser as 瀏覽器 + participant UI as Web UI + participant WS as WebSocket + participant Session as 會話管理 + + Browser->>UI: 訪問 /feedback + UI->>WS: 建立 WebSocket 連接 + WS->>Session: 註冊連接 + Session->>WS: connection_established + WS->>UI: 發送連接確認 + + alt 有待處理的會話更新 + Session->>WS: session_updated + WS->>UI: 會話更新訊息 + UI->>UI: 更新頁面內容 + end +``` + +## 🔄 多次循環調用機制 + +### 持久化會話架構 + +MCP Feedback Enhanced 的核心創新在於**持久化會話架構**,支援 AI 助手進行多次循環調用而無需重新建立連接。 + +```mermaid +stateDiagram-v2 + [*] --> FirstCall: AI 首次調用 + FirstCall --> SessionActive: 會話建立 + SessionActive --> UserFeedback: 等待用戶回饋 + UserFeedback --> FeedbackSubmitted: 回饋提交 + FeedbackSubmitted --> AIProcessing: AI 處理回饋 + AIProcessing --> SecondCall: AI 再次調用 + SecondCall --> SessionUpdated: 會話更新 + SessionUpdated --> UserFeedback: 等待新回饋 + + note right of SessionActive + Web 服務器持續運行 + 瀏覽器標籤頁保持開啟 + WebSocket 連接維持 + end note + + note right of SessionUpdated + 無需重新開啟瀏覽器 + 局部更新頁面內容 + 狀態無縫切換 + end note +``` + +### 第二次調用流程 + +#### 1. AI 助手再次調用 +```python +# AI 根據用戶回饋進行調整後再次調用 +result = await interactive_feedback( + project_directory="./my-project", + summary="根據您的建議,我已修改了錯誤處理邏輯,請再次確認", + timeout=600 +) +``` + +#### 2. 智能會話切換 +```mermaid +flowchart TD + CALL[AI 再次調用] --> CHECK[檢查現有會話] + CHECK --> ACTIVE{有活躍會話?} + ACTIVE -->|是| UPDATE[更新會話內容] + ACTIVE -->|否| CREATE[創建新會話] + UPDATE --> PRESERVE[保存 WebSocket 連接] + CREATE --> PRESERVE + PRESERVE --> NOTIFY[發送會話更新通知] + NOTIFY --> FRONTEND[前端接收更新] + FRONTEND --> REFRESH[局部刷新內容] +``` + +#### 3. 前端無縫更新 +```javascript +// 處理會話更新訊息 +function handleSessionUpdated(data) { + // 顯示會話更新通知 + showNotification('會話已更新', 'info'); + + // 重置回饋狀態 + feedbackState = 'FEEDBACK_WAITING'; + + // 局部更新 AI 摘要 + updateAISummary(data.summary); + + // 清空回饋表單 + clearFeedbackForm(); + + // 更新會話 ID + currentSessionId = data.session_id; + + // 保持 WebSocket 連接不變 + // 無需重新建立連接 +} +``` + +## 📊 狀態同步機制 + +### WebSocket 訊息類型 + +```mermaid +graph LR + subgraph "服務器 → 客戶端" + CE[connection_established
連接建立] + SU[session_updated
會話更新] + FR[feedback_received
回饋確認] + ST[status_update
狀態更新] + end + + subgraph "客戶端 → 服務器" + SF[submit_feedback
提交回饋] + HB[heartbeat
心跳檢測] + LS[language_switch
語言切換] + end +``` + +### 狀態轉換圖 + +```mermaid +stateDiagram-v2 + [*] --> WAITING: 會話創建/更新 + WAITING --> FEEDBACK_PROCESSING: 用戶提交回饋 + FEEDBACK_PROCESSING --> FEEDBACK_SUBMITTED: 處理完成 + FEEDBACK_SUBMITTED --> WAITING: 新會話更新 + FEEDBACK_SUBMITTED --> [*]: 會話結束 + + WAITING --> ERROR: 連接錯誤 + FEEDBACK_PROCESSING --> ERROR: 處理錯誤 + ERROR --> WAITING: 錯誤恢復 + ERROR --> [*]: 致命錯誤 +``` + +## 🛡️ 錯誤處理和恢復 + +### 連接斷線處理 +```javascript +// WebSocket 重連機制 +function handleWebSocketClose() { + console.log('WebSocket 連接已關閉,嘗試重連...'); + + setTimeout(() => { + initWebSocket(); + }, 3000); // 3秒後重連 +} + +// 心跳檢測 +setInterval(() => { + if (websocket && websocket.readyState === WebSocket.OPEN) { + websocket.send(JSON.stringify({ + type: 'heartbeat', + timestamp: Date.now() + })); + } +}, 30000); // 每30秒發送心跳 +``` + +### 超時處理 +```python +async def wait_for_feedback(self, timeout: int = 600): + try: + await asyncio.wait_for( + self.feedback_completed.wait(), + timeout=timeout + ) + return self.get_feedback_result() + except asyncio.TimeoutError: + raise TimeoutError(f"等待用戶回饋超時 ({timeout}秒)") +``` + +## 🎯 性能優化 + +### 連接復用 +- **WebSocket 連接保持**: 避免重複建立連接 +- **會話狀態繼承**: 新會話繼承舊會話的連接 +- **智能瀏覽器開啟**: 檢測活躍標籤頁,避免重複開啟 + +### 資源管理 +- **自動清理機制**: 超時會話自動清理 +- **內存優化**: 單一活躍會話模式 +- **進程管理**: 優雅的進程啟動和關閉 + +--- + +**下一步**: 查看 [API 參考文檔](./api-reference.md) 了解詳細的 API 規範 diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md new file mode 100644 index 0000000..5f08d67 --- /dev/null +++ b/docs/architecture/system-overview.md @@ -0,0 +1,178 @@ +# 系統架構總覽 + +## 🏗️ 整體架構設計 + +MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新架構設計,實現 AI 助手與用戶之間的高效、無縫交互體驗。 + +### 系統整體架構圖 + +```mermaid +graph TB + subgraph "AI 助手環境" + AI[AI 助手
Claude/GPT等] + end + + subgraph "MCP Feedback Enhanced" + subgraph "MCP 服務層" + MCP[MCP Server
server.py] + TOOL[interactive_feedback
工具] + end + + subgraph "Web UI 管理層" + WM[WebUIManager
單例模式] + SESSION[WebFeedbackSession
會話管理] + end + + subgraph "Web 服務層" + API[FastAPI
HTTP/WebSocket] + ROUTES[路由處理
main_routes.py] + end + + subgraph "前端交互層" + UI[Web UI
HTML/JS] + WS[WebSocket
實時通信] + 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. 單一活躍會話模式 +```mermaid +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. 智能環境檢測 +```mermaid +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. 創新的會話管理 +```python +# 傳統多會話設計 (已棄用) +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 助手調用流程 +```mermaid +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: 返回結果 +``` + +### 多次循環調用 +```mermaid +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 +``` + +--- + +**下一步**: 查看 [組件詳細說明](./component-details.md) 了解各組件的具體實現