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) 了解各組件的具體實現