📝 新增專案架構文檔

2025-07-27 10:42:25 +08:00 · 2025-06-10 09:01:53 +08:00 · 2025-06-10 09:01:53 +08:00 · 3ed676cf29
commit 3ed676cf29
parent 47088ad1a9
6 changed files with 1571 additions and 0 deletions
--- a/docs/architecture/README.md
+++ 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
--- a/docs/architecture/api-reference.md
+++ 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
 <!DOCTYPE html>
 <html>
 <!-- 回饋頁面 HTML 內容 -->
 </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) 了解部署配置和運維指南
--- a/docs/architecture/component-details.md
+++ b/docs/architecture/component-details.md
@ -0,0 +1,285 @@
 # 組件詳細說明
 ## 🏗️ 四層架構組件
 MCP Feedback Enhanced 採用清晰的四層架構設計，每層負責特定的功能領域。
 ### 組件關係圖
 ```mermaid
 graph TB
    subgraph "第一層：MCP 服務層"
        SERVER[server.py<br/>MCP 服務器]
        TOOL[interactive_feedback<br/>核心工具]
        I18N[i18n.py<br/>國際化支援]
    end
    subgraph "第二層：Web UI 管理層"
        MANAGER[WebUIManager<br/>單例管理器]
        SESSION[WebFeedbackSession<br/>會話模型]
        RESULT[FeedbackResult<br/>結果模型]
    end
    subgraph "第三層：Web 服務層"
        MAIN[main.py<br/>FastAPI 應用]
        ROUTES[main_routes.py<br/>路由處理]
        WS[WebSocket<br/>實時通信]
    end
    subgraph "第四層：前端交互層"
        HTML[feedback.html<br/>主頁面]
        JS[app.js<br/>交互邏輯]
        CSS[樣式文件]
    end
    subgraph "工具層"
        BROWSER[browser.py<br/>瀏覽器控制]
        NETWORK[network.py<br/>網路工具]
        PORT[port_manager.py<br/>埠管理]
        CLEANUP[session_cleanup_manager.py<br/>清理管理]
        COMPRESS[compression_*.py<br/>壓縮工具]
    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
 <!-- 核心結構 -->
 <div id="app">
    <header><!-- 標題和狀態 --></header>
    <main>
        <section id="ai-summary"><!-- AI 摘要顯示 --></section>
        <section id="feedback-form"><!-- 回饋表單 --></section>
        <section id="image-upload"><!-- 圖片上傳 --></section>
    </main>
    <footer><!-- 狀態指示器 --></footer>
 </div>
 ```
 ### 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) 了解完整的交互機制
--- a/docs/architecture/deployment-guide.md
+++ 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')
 ```
 ---
 **完成**: 架構文檔體系已建立完成，包含完整的技術文檔和部署指南。
--- a/docs/architecture/interaction-flows.md
+++ 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<br/>連接建立]
        SU[session_updated<br/>會話更新]
        FR[feedback_received<br/>回饋確認]
        ST[status_update<br/>狀態更新]
    end
    subgraph "客戶端 → 服務器"
        SF[submit_feedback<br/>提交回饋]
        HB[heartbeat<br/>心跳檢測]
        LS[language_switch<br/>語言切換]
    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 規範
--- a/docs/architecture/system-overview.md
+++ b/docs/architecture/system-overview.md
@ -0,0 +1,178 @@
 # 系統架構總覽
 ## 🏗️ 整體架構設計
 MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新架構設計，實現 AI 助手與用戶之間的高效、無縫交互體驗。
 ### 系統整體架構圖
 ```mermaid
 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. 單一活躍會話模式
 ```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) 了解各組件的具體實現