# 組件詳細說明
## 🏗️ 四層架構組件
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