component-details.md•41.7 kB
# 組件詳細說明
## 🏗️ 四層架構組件
MCP Feedback Enhanced 採用清晰的四層架構設計，每層負責特定的功能領域。本文檔詳細說明各層組件的實現細節、職責分工和交互機制。
### 架構設計原則
- **單一職責**: 每個組件專注於特定功能領域
- **低耦合**: 層間通過明確的接口通信
- **高內聚**: 相關功能集中在同一層內
- **可擴展**: 支援新功能的無縫集成
- **可測試**: 每層都可獨立進行單元測試
### 詳細組件關係圖
```mermaid
graph TB
subgraph "第一層：MCP 服務層"
SERVER[server.py<br/>MCP 服務器<br/>FastMCP 實現]
TOOL[interactive_feedback<br/>核心工具<br/>參數驗證]
I18N[i18n.py<br/>國際化支援<br/>多語言管理]
DEBUG[debug.py<br/>統一調試<br/>日誌輸出]
end
subgraph "第二層：Web UI 管理層"
MANAGER[WebUIManager<br/>單例管理器<br/>會話控制]
SESSION[WebFeedbackSession<br/>會話模型<br/>狀態管理]
MODELS[models/<br/>數據模型<br/>類型定義]
end
subgraph "第三層：Web 服務層"
MAIN[main.py<br/>FastAPI 應用<br/>HTTP 服務]
ROUTES[routes/main_routes.py<br/>路由處理<br/>API 端點]
WS[WebSocket<br/>實時通信<br/>雙向數據流]
end
subgraph "第四層：前端交互層"
HTML[templates/<br/>HTML 模板<br/>Jinja2 渲染]
JS[static/js/<br/>JavaScript 模組<br/>ES6+ 架構]
CSS[static/css/<br/>樣式系統<br/>響應式設計]
LOCALES[locales/<br/>翻譯文件<br/>JSON 格式]
PROMPT_MODULES[prompt/<br/>提示詞管理模組<br/>CRUD 操作]
SESSION_MODULES[session/<br/>會話管理模組<br/>歷史追蹤]
end
subgraph "工具層 - 核心工具"
ERROR[utils/error_handler.py<br/>錯誤處理<br/>統一異常管理]
MEMORY[utils/memory_monitor.py<br/>記憶體監控<br/>資源追蹤]
RESOURCE[utils/resource_manager.py<br/>資源管理<br/>生命週期控制]
end
subgraph "工具層 - Web 工具"
BROWSER[utils/browser.py<br/>瀏覽器控制<br/>智能開啟]
PORT[utils/port_manager.py<br/>埠管理<br/>動態分配]
COMPRESS[utils/compression_*.py<br/>壓縮工具<br/>數據優化]
CLEANUP[utils/session_cleanup_manager.py<br/>清理管理<br/>自動回收]
end
%% 主要數據流
SERVER -->|MCP 調用| TOOL
TOOL -->|創建會話| MANAGER
MANAGER -->|管理| SESSION
MANAGER -->|啟動服務| MAIN
MAIN -->|路由分發| ROUTES
ROUTES -->|渲染頁面| HTML
HTML -->|載入腳本| JS
JS -->|WebSocket| WS
WS -->|回傳數據| SESSION
%% 新功能模組
JS -->|載入模組| PROMPT_MODULES
JS -->|載入模組| SESSION_MODULES
PROMPT_MODULES -->|提示詞管理| WS
SESSION_MODULES -->|會話追蹤| WS
%% 支援服務
I18N -->|翻譯服務| ROUTES
I18N -->|語言包| LOCALES
DEBUG -->|日誌記錄| SERVER
MODELS -->|數據結構| SESSION
%% 工具層支援
ERROR -->|錯誤處理| MANAGER
MEMORY -->|監控| MANAGER
RESOURCE -->|資源管理| SESSION
BROWSER -->|開啟瀏覽器| MANAGER
PORT -->|埠分配| MAIN
COMPRESS -->|數據壓縮| ROUTES
CLEANUP -->|清理會話| SESSION
%% 樣式定義
classDef layer1 fill:#e3f2fd
classDef layer2 fill:#f3e5f5
classDef layer3 fill:#e8f5e8
classDef layer4 fill:#fff3e0
classDef tools fill:#fafafa
class SERVER,TOOL,I18N,DEBUG layer1
class MANAGER,SESSION,MODELS layer2
class MAIN,ROUTES,WS layer3
class HTML,JS,CSS,LOCALES,PROMPT_MODULES,SESSION_MODULES layer4
class ERROR,MEMORY,RESOURCE,BROWSER,PORT,COMPRESS,CLEANUP tools
```
## 🔧 第一層：MCP 服務層
### server.py - MCP 服務器核心
**架構實現**：
```python
# 基於 FastMCP 的服務器實現
mcp = FastMCP("mcp-feedback-enhanced")
@mcp.tool()
async def interactive_feedback(
project_directory: Annotated[str, Field(description="專案目錄路徑")] = ".",
summary: Annotated[str, Field(description="AI 工作完成的摘要說明")] = "我已完成了您請求的任務。",
timeout: Annotated[int, Field(description="等待用戶回饋的超時時間（秒）")] = 600,
) -> list:
"""
收集用戶的互動回饋，支援文字和圖片
"""
# 1. 參數驗證和環境檢測
# 2. 啟動 Web UI 管理器
# 3. 創建或更新會話
# 4. 等待用戶回饋
# 5. 處理和返回結果
```
**主要職責**：
- **MCP 協議實現**: 基於 FastMCP 框架的標準實現
- **工具註冊**: 註冊 `interactive_feedback` 和 `get_system_info` 工具
- **環境檢測**: 自動識別 Local/SSH Remote/WSL 環境
- **生命週期管理**: 控制 Web UI 的啟動、運行和清理
- **接口層**: 作為 AI 助手與系統的主要通信接口
**核心特性**：
- 支援 MCP 2.0+ 協議標準
- 異步處理提升性能
- 完整的錯誤處理和日誌記錄
- 參數類型驗證和文檔生成
### interactive_feedback 工具
**工具執行流程**：
```mermaid
flowchart TD
START[AI 助手調用] --> VALIDATE[參數驗證]
VALIDATE --> ENV[環境檢測]
ENV --> MANAGER[獲取 WebUIManager]
MANAGER --> SESSION[創建/更新會話]
SESSION --> LAUNCH[啟動 Web 服務]
LAUNCH --> BROWSER[智能開啟瀏覽器]
BROWSER --> WAIT[等待用戶回饋]
WAIT --> TIMEOUT{超時檢查}
TIMEOUT -->|未超時| FEEDBACK[接收回饋]
TIMEOUT -->|超時| CLEANUP[清理資源]
FEEDBACK --> PROCESS[處理回饋數據]
PROCESS --> SAVE[保存回饋記錄]
SAVE --> RETURN[返回結果給 AI]
CLEANUP --> ERROR[返回超時錯誤]
ERROR --> RETURN
style START fill:#e3f2fd
style RETURN fill:#e8f5e8
style ERROR fill:#ffebee
```
**參數說明**：
- `project_directory`: 專案目錄路徑，用於命令執行上下文
- `summary`: AI 工作摘要，顯示給用戶確認
- `timeout`: 等待超時時間，預設 600 秒（10 分鐘）
**返回格式**：
```python
# 成功返回
[
TextContent(type="text", text="用戶回饋內容"),
MCPImage(data="base64_encoded_image", mimeType="image/png") # 可選
]
# 錯誤返回
[TextContent(type="text", text="錯誤描述")]
```
### i18n.py - 國際化支援
**多語言架構**：
```python
class I18nManager:
def __init__(self):
self._supported_languages = ["zh-TW", "en", "zh-CN"]
self._fallback_language = "en"
self._locales_dir = Path(__file__).parent / "web" / "locales"
def t(self, key: str, **kwargs) -> str:
"""翻譯函數，支援巢狀鍵值和參數替換"""
```
**核心功能**：
- **三語支援**: 繁體中文、簡體中文、英文
- **智能檢測**: 基於系統語言自動選擇
- **動態切換**: 運行時語言切換無需重啟
- **巢狀翻譯**: 支援 `buttons.submit` 格式的鍵值
- **參數替換**: 支援 `{name}` 格式的動態內容
- **回退機制**: 翻譯缺失時自動使用英文
**翻譯文件結構**：
```json
{
"app": {
"title": "MCP Feedback Enhanced",
"subtitle": "AI 輔助開發回饋收集器"
},
"buttons": {
"submit": "提交回饋",
"cancel": "取消"
}
}
```
### debug.py - 統一調試系統
**調試功能**：
- **條件輸出**: 只在 `MCP_DEBUG=true` 時輸出
- **分類日誌**: 不同模組使用不同前綴
- **安全輸出**: 輸出到 stderr 避免干擾 MCP 通信
- **編碼處理**: 自動處理中文字符編碼問題
**使用方式**：
```python
from .debug import server_debug_log as debug_log
debug_log("伺服器啟動完成") # [SERVER] 伺服器啟動完成
```
## 🎛️ 第二層：Web UI 管理層
### WebUIManager - 核心管理器
**單例模式實現**：
```python
class WebUIManager:
_instance: Optional['WebUIManager'] = None
_lock = threading.Lock()
def __new__(cls, *args, **kwargs):
if cls._instance is None:
with cls._lock:
if cls._instance is None:
cls._instance = super().__new__(cls)
return cls._instance
def __init__(self, host: str = "127.0.0.1", port: int = 0):
self.current_session: Optional[WebFeedbackSession] = None
self.global_active_tabs: Dict[str, dict] = {}
self.app: Optional[FastAPI] = None
self.server_thread: Optional[threading.Thread] = None
self.port_manager = PortManager()
```
**核心職責**：
- **會話管理**: 單一活躍會話的創建、更新、清理
- **服務器控制**: FastAPI 應用的啟動、停止、重啟
- **瀏覽器控制**: 智能開啟瀏覽器，避免重複視窗
- **資源管理**: 自動清理過期資源和錯誤處理
- **狀態同步**: 維護全局狀態和標籤頁追蹤
**關鍵方法**：
```python
async def create_session(self, project_dir: str, summary: str) -> str:
"""創建新會話或更新現有會話"""
async def smart_open_browser(self, url: str) -> bool:
"""智能開啟瀏覽器，檢測活躍標籤頁"""
def cleanup_session(self, reason: CleanupReason = CleanupReason.MANUAL):
"""清理會話資源"""
def get_server_url(self) -> str:
"""獲取服務器 URL"""
```
**智能瀏覽器開啟機制**：
```mermaid
flowchart TD
START[開啟瀏覽器請求] --> CHECK[檢查活躍標籤頁]
CHECK --> ACTIVE{有活躍標籤?}
ACTIVE -->|是| NOTIFY[發送會話更新通知]
ACTIVE -->|否| DETECT[檢測運行環境]
DETECT --> LOCAL{本地環境?}
LOCAL -->|是| DIRECT[直接開啟瀏覽器]
LOCAL -->|否| SSH{SSH Remote?}
SSH -->|是| TUNNEL[建立 SSH 隧道]
SSH -->|否| WSL[WSL 環境處理]
DIRECT --> SUCCESS[開啟成功]
TUNNEL --> SUCCESS
WSL --> SUCCESS
NOTIFY --> SUCCESS
SUCCESS --> TRACK[追蹤標籤頁狀態]
```
### WebFeedbackSession - 會話模型
**會話狀態機**：
```mermaid
stateDiagram-v2
[*] --> WAITING: 會話創建
WAITING --> FEEDBACK_PROCESSING: 用戶提交回饋
FEEDBACK_PROCESSING --> FEEDBACK_SUBMITTED: 處理完成
FEEDBACK_SUBMITTED --> WAITING: AI 再次調用
FEEDBACK_SUBMITTED --> CLEANUP: 會話結束
CLEANUP --> [*]: 資源釋放
WAITING --> TIMEOUT: 超時檢測
TIMEOUT --> CLEANUP: 清理資源
note right of WAITING
- 顯示 AI 摘要
- 等待用戶輸入
- 支援文字/圖片/命令
end note
note right of FEEDBACK_PROCESSING
- 驗證回饋數據
- 圖片壓縮處理
- 命令執行結果
end note
note right of FEEDBACK_SUBMITTED
- 回饋已保存
- 等待 AI 處理
- 準備下次調用
end note
```
**會話數據結構**：
```python
@dataclass
class WebFeedbackSession:
session_id: str
project_directory: str
summary: str
status: SessionStatus
created_at: datetime
timeout: int
feedback_future: Optional[asyncio.Future] = None
# 回饋數據
interactive_feedback: str = ""
command_logs: str = ""
images: List[Dict[str, Any]] = field(default_factory=list)
async def wait_for_feedback(self, timeout: int) -> Dict[str, Any]:
"""等待用戶回饋，支援超時處理"""
def update_session(self, project_dir: str, summary: str, timeout: int):
"""更新會話內容，支援 AI 多次調用"""
```
**狀態枚舉**：
```python
class SessionStatus(Enum):
WAITING = "waiting" # 等待用戶回饋
FEEDBACK_PROCESSING = "processing" # 處理回饋中
FEEDBACK_SUBMITTED = "submitted" # 回饋已提交
TIMEOUT = "timeout" # 會話超時
ERROR = "error" # 發生錯誤
```
### models/ - 數據模型層
**FeedbackResult 模型**：
```python
@dataclass
class FeedbackResult:
interactive_feedback: str = ""
command_logs: str = ""
images: List[Dict[str, Any]] = field(default_factory=list)
session_id: str = ""
timestamp: datetime = field(default_factory=datetime.now)
def to_mcp_response(self) -> List[Union[TextContent, MCPImage]]:
"""轉換為 MCP 協議格式"""
```
**CleanupReason 枚舉**：
```python
class CleanupReason(Enum):
TIMEOUT = "timeout" # 超時清理
MANUAL = "manual" # 手動清理
ERROR = "error" # 錯誤清理
SHUTDOWN = "shutdown" # 系統關閉
```
**WebSocket 消息模型**：
```python
@dataclass
class WebSocketMessage:
type: str # 消息類型
data: Dict[str, Any] # 消息數據
session_id: Optional[str] = None
timestamp: datetime = field(default_factory=datetime.now)
```
## 🌐 第三層：Web 服務層
### main.py - FastAPI 應用
**應用架構**：
```python
def create_app(manager: 'WebUIManager') -> FastAPI:
"""創建 FastAPI 應用實例"""
app = FastAPI(
title="MCP Feedback Enhanced",
description="AI 輔助開發回饋收集系統",
version="2.3.0"
)
# 設置中間件
setup_middleware(app)
# 設置路由
setup_routes(manager)
# 設置 WebSocket
setup_websocket(app, manager)
return app
```
**中間件配置**：
```python
def setup_middleware(app: FastAPI):
# CORS 設定 - 允許本地開發
app.add_middleware(
CORSMiddleware,
allow_origins=["http://127.0.0.1:*", "http://localhost:*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# 靜態文件服務
app.mount("/static", StaticFiles(directory="static"), name="static")
# 錯誤處理中間件
@app.exception_handler(Exception)
async def global_exception_handler(request, exc):
return JSONResponse(
status_code=500,
content={"detail": f"內部服務器錯誤: {str(exc)}"}
)
```
**核心功能**：
- **HTTP 路由處理**: RESTful API 端點
- **WebSocket 連接管理**: 實時雙向通信
- **靜態資源服務**: CSS、JS、圖片等資源
- **模板渲染**: Jinja2 模板引擎
- **錯誤處理**: 統一的異常處理機制
- **安全配置**: CORS 和安全標頭設定
### routes/main_routes.py - 路由處理
**路由架構圖**：
```mermaid
graph TB
subgraph "HTTP 路由"
ROOT[GET /<br/>主頁重定向]
FEEDBACK[GET /feedback<br/>回饋頁面]
API_SESSION[GET /api/session<br/>會話資訊]
API_SETTINGS[GET/POST /api/settings<br/>設定管理]
API_I18N[GET /api/i18n<br/>翻譯資源]
STATIC[/static/*<br/>靜態資源]
end
subgraph "WebSocket 路由"
WS[/ws<br/>WebSocket 連接]
MSG_HANDLER[訊息處理器]
BROADCAST[廣播機制]
end
subgraph "API 端點"
SUBMIT[POST /api/submit-feedback<br/>提交回饋]
COMMAND[POST /api/execute-command<br/>執行命令]
UPLOAD[POST /api/upload-image<br/>圖片上傳]
STATUS[GET /api/status<br/>系統狀態]
end
ROOT --> FEEDBACK
FEEDBACK --> API_SESSION
WS --> MSG_HANDLER
MSG_HANDLER --> BROADCAST
SUBMIT --> MSG_HANDLER
COMMAND --> MSG_HANDLER
UPLOAD --> MSG_HANDLER
```
**主要路由端點**：
**頁面路由**：
```python
@app.get("/")
async def root():
"""主頁重定向到回饋頁面"""
return RedirectResponse(url="/feedback")
@app.get("/feedback")
async def feedback_page(request: Request):
"""回饋收集頁面"""
return templates.TemplateResponse("feedback.html", {
"request": request,
"project_directory": session.project_directory,
"layout_mode": load_user_layout_settings()
})
```
**API 路由**：
```python
@app.get("/api/session")
async def get_session():
"""獲取當前會話資訊"""
@app.post("/api/submit-feedback")
async def submit_feedback(feedback_data: dict):
"""提交用戶回饋"""
@app.post("/api/execute-command")
async def execute_command(command_data: dict):
"""執行用戶命令"""
@app.post("/api/upload-image")
async def upload_image(file: UploadFile):
"""處理圖片上傳"""
```
**WebSocket 訊息類型**：
- `connection_established`: 連接建立確認
- `session_updated`: 會話內容更新
- `submit_feedback`: 提交回饋數據
- `feedback_received`: 回饋接收確認
- `status_update`: 系統狀態更新
- `error_occurred`: 錯誤通知
- `command_result`: 命令執行結果
- `image_uploaded`: 圖片上傳完成
**WebSocket 連接管理**：
```python
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
await websocket.accept()
try:
while True:
data = await websocket.receive_json()
await handle_websocket_message(websocket, data)
except WebSocketDisconnect:
await handle_disconnect(websocket)
```
## 🎨 第四層：前端交互層
### 新功能模組架構
#### 提示詞管理模組群組 (prompt/)
**模組結構**：
```mermaid
graph TB
subgraph "提示詞管理模組"
PM[prompt-manager.js<br/>核心管理器<br/>CRUD 操作]
PMO[prompt-modal.js<br/>彈窗組件<br/>編輯界面]
PSU[prompt-settings-ui.js<br/>設定頁面<br/>列表管理]
PIB[prompt-input-buttons.js<br/>輸入按鈕<br/>快速選擇]
end
PM -->|提供數據| PMO
PM -->|提供數據| PSU
PM -->|提供數據| PIB
PMO -->|編輯操作| PM
PSU -->|管理操作| PM
PIB -->|使用操作| PM
```
**核心功能**：
- **PromptManager**: 提示詞的增刪改查、排序、自動提交標記
- **PromptModal**: 新增/編輯提示詞的彈窗界面
- **PromptSettingsUI**: 設定頁籤中的提示詞管理界面
- **PromptInputButtons**: 回饋輸入區的快速選擇按鈕
#### 會話管理模組群組 (session/) - v2.4.3 重構增強
**模組結構**：
```mermaid
graph TB
subgraph "會話管理模組（v2.4.3 重構）"
SM[session-manager.js<br/>會話控制器<br/>狀態管理]
SDM[session-data-manager.js<br/>數據管理器<br/>本地存儲增強]
SUR[session-ui-renderer.js<br/>UI 渲染器<br/>頁籤化設計]
SDM_MODAL[session-details-modal.js<br/>詳情彈窗<br/>會話詳細資訊]
end
SM -->|數據操作| SDM
SM -->|UI 渲染| SUR
SM -->|詳情顯示| SDM_MODAL
SDM -->|狀態回調| SM
SUR -->|用戶操作| SM
SDM_MODAL -->|查看操作| SM
```
**v2.4.3 重構亮點**：
- **從側邊欄遷移到頁籤**: 解決瀏覽器相容性問題
- **本地歷史存儲**: 支援 72 小時可配置保存期限
- **隱私控制**: 三級用戶訊息記錄設定（完整/基本/停用）
- **數據管理**: 匯出和清理功能
- **UI 重新設計**: 專門的渲染器和詳情彈窗
**核心功能**：
- **SessionManager**: 當前會話的狀態管理和控制
- **SessionDataManager**: 會話歷史記錄、統計數據和本地存儲管理
- **SessionUIRenderer**: 專門的 UI 渲染器，負責會話列表和狀態顯示
- **SessionDetailsModal**: 會話詳情彈窗，提供完整的會話資訊查看
#### 音效通知模組群組 (audio/) - v2.4.3 新增
**模組結構**：
```mermaid
graph TB
subgraph "音效通知系統（v2.4.3 新增）"
AM[audio-manager.js<br/>音效管理器<br/>播放控制]
ASU[audio-settings-ui.js<br/>設定界面<br/>音效配置]
DA[DefaultAudios<br/>內建音效<br/>Base64 編碼]
CA[CustomAudios<br/>自訂音效<br/>用戶上傳]
end
subgraph "Web Audio API"
AUDIO[Audio 物件]
BASE64[Base64 音效數據]
end
AM -->|管理界面| ASU
AM -->|內建音效| DA
AM -->|自訂音效| CA
AM -->|播放控制| AUDIO
AUDIO -->|數據來源| BASE64
ASU -->|設定保存| SettingsManager
```
**核心功能**：
- **AudioManager**: 音效播放控制、音量管理、音效選擇
- **AudioSettingsUI**: 音效設定界面、上傳管理、測試播放
- **內建音效**: 經典提示音、通知鈴聲、輕柔鐘聲
- **自訂音效**: 支援 MP3、WAV、OGG 格式上傳和管理
**技術特性**：
- **Web Audio API**: 使用原生 Audio 物件進行播放
- **Base64 存儲**: 音效文件以 Base64 格式存儲在 localStorage
- **音量控制**: 0-100% 可調節音量
- **瀏覽器相容性**: 處理自動播放政策限制
#### 智能記憶功能 - v2.4.3 新增
**輸入框高度管理**：
```mermaid
graph TB
subgraph "高度管理系統"
THM[TextareaHeightManager<br/>高度管理器]
RO[ResizeObserver<br/>尺寸監控]
DEBOUNCE[防抖機制<br/>500ms 延遲]
end
subgraph "存儲機制"
SETTINGS[SettingsManager]
HEIGHT_KEY[combinedFeedbackTextHeight]
end
TEXTAREA[combinedFeedbackText] --> RO
RO --> THM
THM --> DEBOUNCE
DEBOUNCE --> SETTINGS
SETTINGS --> HEIGHT_KEY
THM -->|恢復高度| TEXTAREA
```
**一鍵複製功能**：
- **專案路徑複製**: 點擊路徑文字即可複製到剪貼簿
- **會話ID複製**: 點擊會話ID即可複製
- **複製反饋**: 視覺提示複製成功狀態
- **國際化支援**: 複製提示支援多語言
#### 自動提交功能整合
**整合架構**：
```mermaid
graph LR
subgraph "自動提交功能"
ASM[AutoSubmitManager<br/>倒數計時器<br/>狀態控制]
PM[PromptManager<br/>提示詞選擇<br/>自動標記]
SM[SettingsManager<br/>設定存儲<br/>配置管理]
end
ASM -->|選擇提示詞| PM
ASM -->|保存設定| SM
PM -->|提供提示詞| ASM
SM -->|載入設定| ASM
```
### templates/ - HTML 模板系統
**模板結構**：
```html
<!-- feedback.html - 主回饋頁面 -->
<!DOCTYPE html>
<html lang="{{ current_language }}" id="html-root">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ title }}</title>
<link rel="stylesheet" href="/static/css/styles.css">
</head>
<body class="layout-{{ layout_mode }}">
<div class="container">
<!-- 頁面頭部 -->
<header class="header">
<div class="header-content">
<h1 class="title" data-i18n="app.title">MCP Feedback Enhanced</h1>
<div class="project-info">
<span data-i18n="app.projectDirectory">專案目錄</span>: {{ project_directory }}
</div>
</div>
</header>
<!-- 主要內容區域 -->
<main class="main-content">
<!-- 標籤頁導航 -->
<div class="tab-container">
<div class="tab-buttons">
<button class="tab-button active" data-tab="combined" data-i18n="tabs.combined">📝 工作區</button>
<button class="tab-button" data-tab="settings" data-i18n="tabs.settings">⚙️ 設定</button>
<button class="tab-button" data-tab="about" data-i18n="tabs.about">ℹ️ 關於</button>
</div>
</div>
<!-- 標籤頁內容 -->
<div class="tab-content active" id="combined-tab">
<!-- AI 摘要區域 -->
<section class="ai-summary-section">
<h2 data-i18n="tabs.summary">📋 AI 摘要</h2>
<div id="ai-summary" class="ai-summary-content"></div>
</section>
<!-- 回饋表單區域 -->
<section class="feedback-section">
<h2 data-i18n="tabs.feedback">💬 回饋</h2>
<form id="feedback-form">
<textarea id="feedback-text" placeholder="請輸入您的回饋..."></textarea>
<div class="form-actions">
<button type="submit" data-i18n="buttons.submit">提交回饋</button>
</div>
</form>
</section>
<!-- 圖片上傳區域 -->
<section class="image-upload-section">
<h2 data-i18n="images.title">🖼️ 圖片上傳</h2>
<div id="image-upload-area" class="upload-area">
<input type="file" id="image-input" multiple accept="image/*">
<div class="upload-prompt" data-i18n="images.dragDrop">拖拽圖片到此處或點擊選擇</div>
</div>
<div id="image-preview" class="image-preview"></div>
</section>
<!-- 命令執行區域 -->
<section class="command-section">
<h2 data-i18n="tabs.commands">⚡ 命令</h2>
<div class="command-input-group">
<input type="text" id="command-input" placeholder="輸入要執行的命令...">
<button id="execute-command" data-i18n="commands.execute">執行</button>
</div>
<div id="command-output" class="command-output"></div>
</section>
</div>
</main>
<!-- 狀態指示器 -->
<footer class="footer">
<div class="status-indicators">
<div id="connection-status" class="connection-indicator">
<span data-i18n="status.connecting">連接中...</span>
</div>
<div id="session-status" class="session-indicator">
<span data-i18n="status.waiting">等待中...</span>
</div>
</div>
</footer>
</div>
<!-- JavaScript 模組載入 -->
<script src="/static/js/i18n.js"></script>
<script src="/static/js/modules/utils.js"></script>
<script src="/static/js/modules/tab-manager.js"></script>
<script src="/static/js/modules/websocket-manager.js"></script>
<script src="/static/js/modules/image-handler.js"></script>
<script src="/static/js/modules/settings-manager.js"></script>
<script src="/static/js/modules/ui-manager.js"></script>
<script src="/static/js/modules/auto-refresh-manager.js"></script>
<script src="/static/js/app.js"></script>
</body>
</html>
```
**模板特性**：
- **Jinja2 模板引擎**: 支援變數替換和條件渲染
- **響應式設計**: 適配桌面和移動設備
- **國際化支援**: `data-i18n` 屬性自動翻譯
- **模組化載入**: JavaScript 模組按需載入
- **無障礙設計**: 支援鍵盤導航和螢幕閱讀器
### static/js/ - JavaScript 模組系統
**模組化架構**：
```mermaid
graph TD
subgraph "核心模組"
UTILS[utils.js<br/>工具函數]
I18N[i18n.js<br/>國際化]
end
subgraph "功能模組"
TAB[tab-manager.js<br/>標籤頁管理]
WS[websocket-manager.js<br/>WebSocket 通信]
IMG[image-handler.js<br/>圖片處理]
SETTINGS[settings-manager.js<br/>設定管理]
UI[ui-manager.js<br/>UI 控制]
REFRESH[auto-refresh-manager.js<br/>自動刷新]
end
subgraph "主應用"
APP[app.js<br/>主應用程式]
end
UTILS --> TAB
UTILS --> WS
UTILS --> IMG
I18N --> UI
TAB --> APP
WS --> APP
IMG --> APP
SETTINGS --> APP
UI --> APP
REFRESH --> APP
```
**主要模組說明**：
**app.js - 主應用程式**：
```javascript
class FeedbackApp {
constructor(sessionId) {
this.sessionId = sessionId;
this.currentSessionId = null;
// 模組管理器
this.tabManager = null;
this.webSocketManager = null;
this.imageHandler = null;
this.settingsManager = null;
this.uiManager = null;
this.autoRefreshManager = null;
this.isInitialized = false;
}
async init() {
// 等待國際化系統
await this.waitForI18n();
// 初始化管理器
await this.initializeManagers();
// 設置事件監聽器
await this.setupEventListeners();
// 設置清理處理器
await this.setupCleanupHandlers();
this.isInitialized = true;
}
}
```
**websocket-manager.js - WebSocket 通信**：
```javascript
class WebSocketManager {
constructor(app) {
this.app = app;
this.websocket = null;
this.reconnectAttempts = 0;
this.maxReconnectAttempts = 5;
this.reconnectDelay = 1000;
}
async connect() {
const protocol = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
const wsUrl = `${protocol}//${window.location.host}/ws`;
this.websocket = new WebSocket(wsUrl);
this.setupEventHandlers();
}
async sendMessage(type, data) {
if (this.websocket?.readyState === WebSocket.OPEN) {
this.websocket.send(JSON.stringify({ type, data }));
}
}
}
```
**image-handler.js - 圖片處理**：
```javascript
class ImageHandler {
constructor(app) {
this.app = app;
this.maxFileSize = 1024 * 1024; // 1MB
this.supportedFormats = ['image/png', 'image/jpeg', 'image/gif', 'image/webp'];
}
async handleImageUpload(files) {
for (const file of files) {
if (this.validateImage(file)) {
const compressedImage = await this.compressImage(file);
await this.uploadImage(compressedImage);
}
}
}
async compressImage(file) {
// 圖片壓縮邏輯
return new Promise((resolve) => {
const canvas = document.createElement('canvas');
const ctx = canvas.getContext('2d');
const img = new Image();
img.onload = () => {
// 壓縮處理
resolve(canvas.toBlob());
};
img.src = URL.createObjectURL(file);
});
}
}
```
**前端特性總結**：
- **模組化設計**: 清晰的職責分離和依賴管理
- **響應式 UI**: 適配不同螢幕尺寸和設備
- **實時通信**: WebSocket 雙向數據同步
- **圖片處理**: 自動壓縮和格式轉換
- **國際化**: 動態語言切換和本地化
- **錯誤處理**: 優雅的錯誤恢復機制
- **性能優化**: 延遲載入和資源快取
- **無障礙支援**: 鍵盤導航和螢幕閱讀器支援
### static/css/ - 樣式系統（v2.4.3 擴展）
**樣式文件結構**：
```
static/css/
├── styles.css # 主樣式文件
├── prompt-management.css # 提示詞管理樣式
├── session-management.css # 會話管理樣式
└── audio-management.css # 音效管理樣式（v2.4.3 新增）
```
**v2.4.3 新增樣式特性**：
**audio-management.css - 音效管理樣式**：
```css
/* 音效管理區塊樣式 */
.audio-management-section {
background: var(--bg-tertiary);
border: 1px solid var(--border-color);
border-radius: 12px;
padding: 20px;
margin-bottom: 20px;
transition: all 0.3s ease;
}
/* 音效設定控制項 */
.audio-setting-item {
display: flex;
justify-content: space-between;
align-items: center;
margin-bottom: 16px;
padding: 12px 0;
border-bottom: 1px solid var(--border-color);
}
/* 音量控制滑桿 */
.audio-volume-slider {
width: 120px;
height: 6px;
background: var(--bg-secondary);
border-radius: 3px;
outline: none;
}
/* 自訂音效列表 */
.audio-custom-item {
display: flex;
justify-content: space-between;
align-items: center;
padding: 12px;
background: var(--bg-primary);
border: 1px solid var(--border-color);
border-radius: 8px;
margin-bottom: 8px;
}
```
**session-management.css - 會話管理樣式增強**：
```css
/* v2.4.3 頁籤化設計 */
.session-tab-content {
padding: 20px;
background: var(--bg-primary);
border-radius: 8px;
margin-top: 16px;
}
/* 會話卡片樣式 */
.session-card {
background: var(--bg-secondary);
border: 1px solid var(--border-color);
border-radius: 8px;
padding: 16px;
margin-bottom: 12px;
transition: all 0.3s ease;
}
.session-card:hover {
border-color: var(--accent-color);
box-shadow: 0 2px 8px rgba(0, 122, 204, 0.1);
}
/* 一鍵複製按鈕樣式 */
.copy-button {
background: transparent;
border: none;
color: var(--accent-color);
cursor: pointer;
padding: 2px 6px;
border-radius: 4px;
transition: background-color 0.2s ease;
}
.copy-button:hover {
background: var(--bg-tertiary);
}
```
**響應式設計增強**：
- **移動設備優化**: 音效控制項在小螢幕下垂直排列
- **觸控友好**: 按鈕和滑桿適配觸控操作
- **視覺反饋**: 懸停和點擊狀態的視覺提示
- **深色主題**: 完整的深色主題支援
## 🛠️ 工具層組件
### utils/error_handler.py - 錯誤處理框架
**統一錯誤處理**：
```python
class ErrorHandler:
@staticmethod
def handle_error(error_type: ErrorType, error: Exception, context: str = "") -> dict:
"""統一錯誤處理入口"""
error_info = {
"type": error_type.value,
"message": str(error),
"context": context,
"timestamp": datetime.now().isoformat(),
"suggestions": ErrorHandler._get_suggestions(error_type)
}
# 記錄錯誤日誌
debug_log(f"錯誤處理: {error_info}")
return error_info
class ErrorType(Enum):
NETWORK_ERROR = "network_error"
VALIDATION_ERROR = "validation_error"
TIMEOUT_ERROR = "timeout_error"
SYSTEM_ERROR = "system_error"
USER_ERROR = "user_error"
```
### utils/memory_monitor.py - 記憶體監控
**資源監控**：
```python
class MemoryMonitor:
def __init__(self):
self.process = psutil.Process()
self.baseline_memory = self.get_memory_usage()
def get_memory_usage(self) -> dict:
"""獲取當前記憶體使用情況"""
memory_info = self.process.memory_info()
return {
"rss": memory_info.rss, # 實際記憶體使用
"vms": memory_info.vms, # 虛擬記憶體使用
"percent": self.process.memory_percent(),
"available": psutil.virtual_memory().available
}
def check_memory_threshold(self, threshold_mb: int = 100) -> bool:
"""檢查記憶體使用是否超過閾值"""
current_memory = self.get_memory_usage()
memory_mb = current_memory["rss"] / 1024 / 1024
return memory_mb > threshold_mb
```
### utils/resource_manager.py - 資源管理
**生命週期管理**：
```python
class ResourceManager:
def __init__(self):
self.temp_files: List[Path] = []
self.active_processes: List[subprocess.Popen] = []
self.cleanup_callbacks: List[Callable] = []
def register_temp_file(self, file_path: Path):
"""註冊臨時文件以便清理"""
self.temp_files.append(file_path)
def register_process(self, process: subprocess.Popen):
"""註冊進程以便清理"""
self.active_processes.append(process)
def cleanup_all(self):
"""清理所有註冊的資源"""
# 清理臨時文件
for file_path in self.temp_files:
try:
if file_path.exists():
file_path.unlink()
except Exception as e:
debug_log(f"清理臨時文件失敗: {e}")
# 終止進程
for process in self.active_processes:
try:
process.terminate()
process.wait(timeout=5)
except Exception as e:
debug_log(f"終止進程失敗: {e}")
```
### utils/browser.py - 瀏覽器控制
**智能瀏覽器開啟**：
```python
class BrowserOpener:
@staticmethod
def open_browser(url: str) -> bool:
"""智能開啟瀏覽器，支援多種環境"""
try:
# 檢測運行環境
environment = detect_environment()
if environment == "local":
return BrowserOpener._open_local(url)
elif environment == "ssh":
return BrowserOpener._open_ssh(url)
elif environment == "wsl":
return BrowserOpener._open_wsl(url)
else:
return BrowserOpener._open_fallback(url)
except Exception as e:
debug_log(f"開啟瀏覽器失敗: {e}")
return False
@staticmethod
def _open_local(url: str) -> bool:
"""本地環境開啟瀏覽器"""
webbrowser.open(url)
return True
@staticmethod
def _open_ssh(url: str) -> bool:
"""SSH 環境處理"""
# 提供 SSH 隧道建立指引
print(f"請在本地終端執行: ssh -L 8765:127.0.0.1:8765 user@host")
print(f"然後在本地瀏覽器開啟: {url}")
return True
@staticmethod
def _open_wsl(url: str) -> bool:
"""WSL 環境處理"""
try:
subprocess.run(["cmd.exe", "/c", "start", url], check=True)
return True
except Exception:
return BrowserOpener._open_fallback(url)
```
### utils/port_manager.py - 埠管理
**動態埠分配**：
```python
class PortManager:
def __init__(self, start_port: int = 8765, end_port: int = 8865):
self.start_port = start_port
self.end_port = end_port
self.allocated_ports: Set[int] = set()
def find_available_port(self) -> int:
"""尋找可用埠"""
for port in range(self.start_port, self.end_port + 1):
if self.is_port_available(port):
self.allocated_ports.add(port)
return port
raise RuntimeError("無可用埠")
def is_port_available(self, port: int) -> bool:
"""檢查埠是否可用"""
try:
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.bind(('127.0.0.1', port))
return True
except OSError:
return False
def release_port(self, port: int):
"""釋放埠"""
self.allocated_ports.discard(port)
```
### utils/session_cleanup_manager.py - 會話清理
**自動清理機制**：
```mermaid
graph TD
START[啟動清理管理器] --> TIMER[設置定時器]
TIMER --> CHECK[檢查會話狀態]
CHECK --> ACTIVE{會話活躍?}
ACTIVE -->|是| TIMEOUT{超時檢查}
ACTIVE -->|否| SKIP[跳過清理]
TIMEOUT -->|超時| CLEANUP[執行清理]
TIMEOUT -->|未超時| WAIT[等待下次檢查]
CLEANUP --> WEBSOCKET[關閉 WebSocket]
WEBSOCKET --> RESOURCES[清理資源]
RESOURCES --> MEMORY[釋放記憶體]
MEMORY --> NOTIFY[通知清理完成]
NOTIFY --> WAIT
SKIP --> WAIT
WAIT --> TIMER
style CLEANUP fill:#ffcdd2
style NOTIFY fill:#c8e6c9
```
**清理策略**：
- **定時檢查**: 每 30 秒檢查一次會話狀態
- **超時清理**: 會話超時自動觸發清理
- **資源回收**: WebSocket 連接、進程、記憶體
- **優雅關閉**: 確保資源正確釋放
- **錯誤恢復**: 清理失敗時的備用方案
### utils/compression_*.py - 壓縮工具
**數據壓縮優化**：
- **圖片壓縮**: 自動壓縮上傳圖片至 1MB 以下
- **JSON 壓縮**: 大型 JSON 數據的 gzip 壓縮
- **傳輸優化**: WebSocket 消息的選擇性壓縮
- **快取機制**: 壓縮結果快取避免重複處理
## 🧪 測試架構
### 測試組織結構
```
tests/
├── unit/ # 單元測試
│ ├── test_error_handler.py
│ ├── test_memory_monitor.py
│ ├── test_port_manager.py
│ └── test_web_ui.py
├── integration/ # 集成測試
│ ├── test_mcp_workflow.py
│ ├── test_web_integration.py
│ └── test_i18n_integration.py
├── helpers/ # 測試輔助工具
│ ├── mcp_client.py
│ └── test_utils.py
├── fixtures/ # 測試數據
│ └── test_data.py
└── conftest.py # pytest 配置
```
### 測試策略
**單元測試**：
- 每個工具模組的獨立測試
- 數據模型的驗證測試
- 錯誤處理機制測試
- 國際化功能測試
**集成測試**：
- MCP 工具完整工作流程
- Web UI 與後端交互
- WebSocket 通信測試
- 多語言切換測試
**性能測試**：
- 記憶體使用監控
- 會話處理性能
- 並發連接測試
- 資源清理效率
## 🔧 開發工具鏈
### 代碼品質工具
**Ruff (Linting + Formatting)**：
- 代碼風格檢查和自動修復
- 安全漏洞檢測
- 導入排序和優化
- 複雜度控制
**mypy (類型檢查)**：
- 靜態類型檢查
- 漸進式類型註解
- 第三方庫類型支援
- 錯誤預防
**pre-commit (提交檢查)**：
- 提交前自動檢查
- 代碼格式化
- 測試執行
- 文檔更新
### 依賴管理
**uv (現代 Python 包管理)**：
- 快速依賴解析
- 鎖定文件管理
- 開發環境隔離
- 跨平台支援
---
## 📚 相關文檔
- **[系統架構總覽](./system-overview.md)** - 了解整體架構設計理念
- **[交互流程文檔](./interaction-flows.md)** - 詳細的用戶交互和系統流程
- **[API 參考文檔](./api-reference.md)** - 完整的 API 端點和參數說明
- **[部署指南](./deployment-guide.md)** - 環境配置和部署最佳實踐
---
**版本**: 2.4.3
**最後更新**: 2025年6月14日
**維護者**: Minidoracat
**架構類型**: Web-Only 四層架構
**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能
**技術棧**: Python 3.11+, FastAPI, FastMCP, WebSocket, Web Audio API