From e6bf5f74ec6b6164324c104863c1fd3ec91e37c7 Mon Sep 17 00:00:00 2001 From: Minidoracat Date: Fri, 13 Jun 2025 17:03:59 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20=E6=9B=B4=E6=96=B0=E6=9E=B6?= =?UTF-8?q?=E6=A7=8B=E6=96=87=E6=AA=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture/README.md | 11 +- docs/architecture/api-reference.md | 287 ++++++++++++++++++++++++- docs/architecture/component-details.md | 76 ++++++- docs/architecture/interaction-flows.md | 147 ++++++++++++- docs/architecture/system-overview.md | 31 ++- 5 files changed, 543 insertions(+), 9 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 9486a56..a30be71 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -24,6 +24,10 @@ MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新 - **持久化 Web UI**: 支援多次循環調用，無需重複開啟瀏覽器 - **實時雙向通信**: WebSocket 實現前後端狀態同步 - **智能資源管理**: 自動清理和會話生命週期管理 +- **提示詞管理系統**: 常用提示詞的 CRUD 操作和快速選擇 +- **自動提交功能**: 倒數計時器和自動回饋提交機制 +- **會話管理功能**: 會話歷史追蹤和統計分析 +- **多語言支援**: 繁體中文、簡體中文、英文動態切換 #### 技術棧 - **後端**: Python 3.11+, FastAPI, FastMCP @@ -49,8 +53,9 @@ MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新 --- -**版本**: 2.3.0 -**最後更新**: 2024年12月 +**版本**: 2.4.0 +**最後更新**: 2025年6月 **維護者**: Minidoracat **架構類型**: Web-Only 四層架構 -**文檔狀態**: ✅ 已完成全面更新，完全移除 Electron 相關內容 +**新功能**: 提示詞管理、自動提交、會話管理、語系切換優化 +**文檔狀態**: ✅ 已完成全面更新，包含所有新功能的詳細說明 diff --git a/docs/architecture/api-reference.md b/docs/architecture/api-reference.md index e41ea81..db3d7c9 100644 --- a/docs/architecture/api-reference.md +++ b/docs/architecture/api-reference.md @@ -92,6 +92,68 @@ except EnvironmentError as e: **響應**: `200 OK` 或 `404 Not Found` +#### GET /api/translations +獲取多語言翻譯資源。 + +**響應**: `200 OK` +```json +{ + "zh-TW": { + "app": { + "title": "MCP Feedback Enhanced" + } + }, + "en": { + "app": { + "title": "MCP Feedback Enhanced" + } + }, + "zh-CN": { + "app": { + "title": "MCP Feedback Enhanced" + } + } +} +``` + +#### GET /api/session-status +獲取當前會話狀態。 + +**響應**: `200 OK` +```json +{ + "has_session": true, + "status": "active", + "session_info": { + "project_directory": "./my-project", + "summary": "代碼審查完成", + "feedback_completed": false + } +} +``` + +#### GET /api/current-session +獲取當前會話詳細信息。 + +**響應**: `200 OK` +```json +{ + "session_id": "550e8400-e29b-41d4-a716-446655440000", + "project_directory": "./my-project", + "summary": "代碼審查完成", + "feedback_completed": false, + "command_logs": "", + "images_count": 0 +} +``` + +**錯誤響應**: `404 Not Found` +```json +{ + "error": "沒有活躍會話" +} +``` + ### WebSocket API #### 連接端點 @@ -160,6 +222,71 @@ ws://localhost:{port}/ws } ``` +#### prompt_management +提示詞管理操作。 + +```json +{ + "type": "prompt_management", + "data": { + "action": "add|update|delete|use", + "prompt": { + "id": "prompt_1_1703123456789", + "name": "代碼審查提示", + "content": "請檢查這段代碼的邏輯正確性和性能優化建議。", + "isAutoSubmit": false + } + } +} +``` + +**字段說明**: +- `action`: 操作類型（add=新增, update=更新, delete=刪除, use=使用） +- `prompt.id`: 提示詞唯一標識符 +- `prompt.name`: 提示詞名稱 +- `prompt.content`: 提示詞內容 +- `prompt.isAutoSubmit`: 是否為自動提交提示詞 + +#### auto_submit_control +自動提交功能控制。 + +```json +{ + "type": "auto_submit_control", + "data": { + "action": "start|stop|update_settings", + "settings": { + "enabled": true, + "timeout": 30, + "promptId": "prompt_1_1703123456789" + } + } +} +``` + +**字段說明**: +- `action`: 控制動作（start=啟動, stop=停止, update_settings=更新設定） +- `settings.enabled`: 是否啟用自動提交 +- `settings.timeout`: 自動提交倒數時間（秒） +- `settings.promptId`: 自動提交使用的提示詞 ID + +#### session_management +會話管理操作。 + +```json +{ + "type": "session_management", + "data": { + "action": "get_history|get_stats|clear_history", + "sessionId": "550e8400-e29b-41d4-a716-446655440000" + } +} +``` + +**字段說明**: +- `action`: 管理動作（get_history=獲取歷史, get_stats=獲取統計, clear_history=清除歷史） +- `sessionId`: 會話 ID（可選） + ### 📥 服務器 → 客戶端訊息 #### connection_established @@ -218,6 +345,52 @@ WebSocket 連接建立確認。 } ``` +#### auto_submit_status +自動提交狀態更新。 + +```json +{ + "type": "auto_submit_status", + "data": { + "enabled": true, + "countdown": 25, + "promptId": "prompt_1_1703123456789", + "promptName": "代碼審查提示" + } +} +``` + +**字段說明**: +- `enabled`: 自動提交是否啟用 +- `countdown`: 剩餘倒數時間（秒） +- `promptId`: 當前自動提交提示詞 ID +- `promptName`: 當前自動提交提示詞名稱 + +#### session_history +會話歷史數據。 + +```json +{ + "type": "session_history", + "data": { + "sessions": [ + { + "session_id": "session-1", + "summary": "代碼審查完成", + "status": "completed", + "created_at": "2024-12-13T10:30:00Z", + "feedback_length": 150 + } + ], + "stats": { + "total": 10, + "completed": 8, + "average_feedback_length": 120 + } + } +} +``` + #### error 錯誤訊息。 @@ -289,6 +462,95 @@ def add_websocket(self, websocket: WebSocket) -> None 添加 WebSocket 連接到會話。 +### PromptManager API + +#### addPrompt() +```python +def addPrompt(self, name: str, content: str) -> dict +``` + +新增提示詞到管理器。 + +**參數**: +- `name`: 提示詞名稱（必須唯一） +- `content`: 提示詞內容 + +**返回值**: 新建的提示詞對象 + +#### updatePrompt() +```python +def updatePrompt(self, id: str, name: str, content: str) -> dict +``` + +更新現有提示詞。 + +#### deletePrompt() +```python +def deletePrompt(self, id: str) -> bool +``` + +刪除指定提示詞。 + +#### usePrompt() +```python +def usePrompt(self, id: str) -> dict +``` + +使用提示詞（更新最近使用記錄）。 + +#### getPromptsSortedByUsage() +```python +def getPromptsSortedByUsage(self) -> List[dict] +``` + +獲取按使用頻率排序的提示詞列表，自動提交提示詞優先顯示。 + +### SessionManager API + +#### getCurrentSession() +```python +def getCurrentSession(self) -> dict +``` + +獲取當前活躍會話信息。 + +#### getSessionHistory() +```python +def getSessionHistory(self) -> List[dict] +``` + +獲取會話歷史記錄。 + +#### getSessionStats() +```python +def getSessionStats(self) -> dict +``` + +獲取會話統計信息。 + +### AutoSubmitManager API + +#### start() +```python +def start(self, timeoutSeconds: int, promptId: str) -> None +``` + +啟動自動提交倒數計時器。 + +#### stop() +```python +def stop(self) -> None +``` + +停止自動提交倒數計時器。 + +#### updateSettings() +```python +def updateSettings(self, enabled: bool, timeout: int, promptId: str) -> None +``` + +更新自動提交設定。 + ## 📊 狀態碼和錯誤碼 ### HTTP 狀態碼 @@ -316,6 +578,23 @@ class SessionStatus: ERROR = "ERROR" ``` +### 提示詞狀態 +```python +class PromptStatus: + ACTIVE = "active" # 活躍提示詞 + AUTO_SUBMIT = "auto_submit" # 自動提交提示詞 + ARCHIVED = "archived" # 已歸檔提示詞 +``` + +### 自動提交狀態 +```python +class AutoSubmitStatus: + DISABLED = "disabled" # 已停用 + ENABLED = "enabled" # 已啟用 + COUNTDOWN = "countdown" # 倒數計時中 + COMPLETED = "completed" # 已完成提交 +``` + ## 🔒 安全考慮 ### 輸入驗證 @@ -323,6 +602,9 @@ class SessionStatus: - 圖片大小限制：單張最大 5MB - 圖片數量限制：最多 10 張 - 支援的圖片格式：PNG, JPEG, GIF, WebP +- 提示詞名稱長度限制：最大 100 字符 +- 提示詞內容長度限制：最大 5,000 字符 +- 提示詞數量限制：最多 50 個 ### 資源保護 - WebSocket 連接數限制：每會話最多 5 個連接 @@ -351,8 +633,9 @@ app.add_middleware( --- -**版本**: 2.3.0 -**最後更新**: 2024年12月 +**版本**: 2.4.0 +**最後更新**: 2025年6月 **維護者**: Minidoracat **API 版本**: v1 **協議支援**: MCP 2.0+, WebSocket, HTTP/1.1 +**新功能**: 自動提交、提示詞管理、會話管理、語系切換優化 diff --git a/docs/architecture/component-details.md b/docs/architecture/component-details.md index 03471e9..de61065 100644 --- a/docs/architecture/component-details.md +++ b/docs/architecture/component-details.md @@ -40,6 +40,8 @@ graph TB JS[static/js/
JavaScript 模組
ES6+ 架構] CSS[static/css/
樣式系統
響應式設計] LOCALES[locales/
翻譯文件
JSON 格式] + PROMPT_MODULES[prompt/
提示詞管理模組
CRUD 操作] + SESSION_MODULES[session/
會話管理模組
歷史追蹤] end subgraph "工具層 - 核心工具" @@ -66,6 +68,12 @@ graph TB JS -->|WebSocket| WS WS -->|回傳數據| SESSION + %% 新功能模組 + JS -->|載入模組| PROMPT_MODULES + JS -->|載入模組| SESSION_MODULES + PROMPT_MODULES -->|提示詞管理| WS + SESSION_MODULES -->|會話追蹤| WS + %% 支援服務 I18N -->|翻譯服務| ROUTES I18N -->|語言包| LOCALES @@ -91,7 +99,7 @@ graph TB class SERVER,TOOL,I18N,DEBUG layer1 class MANAGER,SESSION,MODELS layer2 class MAIN,ROUTES,WS layer3 - class HTML,JS,CSS,LOCALES layer4 + class HTML,JS,CSS,LOCALES,PROMPT_MODULES,SESSION_MODULES layer4 class ERROR,MEMORY,RESOURCE,BROWSER,PORT,COMPRESS,CLEANUP tools ``` @@ -552,6 +560,72 @@ async def websocket_endpoint(websocket: WebSocket): ## 🎨 第四層：前端交互層 +### 新功能模組架構 + +#### 提示詞管理模組群組 (prompt/) + +**模組結構**： +```mermaid +graph TB + subgraph "提示詞管理模組" + PM[prompt-manager.js
核心管理器
CRUD 操作] + PMO[prompt-modal.js
彈窗組件
編輯界面] + PSU[prompt-settings-ui.js
設定頁面
列表管理] + PIB[prompt-input-buttons.js
輸入按鈕
快速選擇] + end + + PM -->|提供數據| PMO + PM -->|提供數據| PSU + PM -->|提供數據| PIB + PMO -->|編輯操作| PM + PSU -->|管理操作| PM + PIB -->|使用操作| PM +``` + +**核心功能**： +- **PromptManager**: 提示詞的增刪改查、排序、自動提交標記 +- **PromptModal**: 新增/編輯提示詞的彈窗界面 +- **PromptSettingsUI**: 設定頁籤中的提示詞管理界面 +- **PromptInputButtons**: 回饋輸入區的快速選擇按鈕 + +#### 會話管理模組群組 (session/) + +**模組結構**： +```mermaid +graph TB + subgraph "會話管理模組" + SM[session-manager.js
會話控制器
狀態管理] + SDM[session-data-manager.js
數據管理器
歷史記錄] + SU[session-utils.js
工具函數
狀態判斷] + end + + SM -->|數據操作| SDM + SM -->|工具函數| SU + SDM -->|狀態回調| SM +``` + +**核心功能**： +- **SessionManager**: 當前會話的狀態管理和控制 +- **SessionDataManager**: 會話歷史記錄和統計數據管理 +- **SessionUtils**: 會話狀態判斷和工具函數 + +#### 自動提交功能整合 + +**整合架構**： +```mermaid +graph LR + subgraph "自動提交功能" + ASM[AutoSubmitManager
倒數計時器
狀態控制] + PM[PromptManager
提示詞選擇
自動標記] + SM[SettingsManager
設定存儲
配置管理] + end + + ASM -->|選擇提示詞| PM + ASM -->|保存設定| SM + PM -->|提供提示詞| ASM + SM -->|載入設定| ASM +``` + ### templates/ - HTML 模板系統 **模板結構**： diff --git a/docs/architecture/interaction-flows.md b/docs/architecture/interaction-flows.md index f0459a8..a2d96f8 100644 --- a/docs/architecture/interaction-flows.md +++ b/docs/architecture/interaction-flows.md @@ -473,6 +473,127 @@ function handleSessionUpdated(data) { } ``` +## 🚀 新功能交互流程 + +### 自動提交功能流程 + +```mermaid +sequenceDiagram + participant User as 用戶 + participant UI as 前端界面 + participant ASM as AutoSubmitManager + participant PM as PromptManager + participant WS as WebSocket + + Note over User,WS: 🔧 設定自動提交 + User->>UI: 開啟設定頁籤 + UI->>PM: 獲取提示詞列表 + PM-->>UI: 返回提示詞（自動提交優先） + User->>UI: 選擇提示詞並設定倒數時間 + UI->>ASM: updateSettings(enabled, timeout, promptId) + ASM->>WS: 保存設定到服務器 + + Note over User,WS: ⏰ 自動提交執行 + WS->>UI: session_updated（AI 新調用） + UI->>ASM: checkAutoSubmitConditions() + ASM->>ASM: 檢查設定和狀態 + alt 條件滿足 + ASM->>ASM: start(timeout, promptId) + ASM->>UI: 顯示倒數計時器 + loop 每秒更新 + ASM->>UI: updateCountdownDisplay(remaining) + end + ASM->>PM: getPromptById(promptId) + PM-->>ASM: 返回提示詞內容 + ASM->>UI: 填入提示詞到輸入框 + ASM->>WS: submit_feedback（自動提交） + else 條件不滿足 + ASM->>UI: 隱藏倒數計時器 + end +``` + +### 提示詞管理流程 + +```mermaid +sequenceDiagram + participant User as 用戶 + participant UI as 設定界面 + participant PM as PromptManager + participant Modal as PromptModal + participant Storage as LocalStorage + + Note over User,Storage: 📝 新增提示詞 + User->>UI: 點擊「新增提示詞」 + UI->>Modal: showAddModal() + Modal->>User: 顯示編輯表單 + User->>Modal: 輸入名稱和內容 + Modal->>PM: addPrompt(name, content) + PM->>PM: 驗證數據和唯一性 + PM->>Storage: 保存到 localStorage + PM->>UI: 觸發 onPromptsChange 回調 + UI->>UI: refreshPromptList() + + Note over User,Storage: ✏️ 編輯提示詞 + User->>UI: 點擊編輯按鈕 + UI->>Modal: showEditModal(prompt) + Modal->>User: 顯示預填表單 + User->>Modal: 修改內容 + Modal->>PM: updatePrompt(id, name, content) + PM->>Storage: 更新 localStorage + PM->>UI: 觸發回調更新界面 + + Note over User,Storage: 🎯 使用提示詞 + User->>UI: 在輸入區點擊提示詞按鈕 + UI->>PM: getPromptsSortedByUsage() + PM-->>UI: 返回排序後列表 + UI->>Modal: showSelectModal(prompts) + User->>Modal: 選擇提示詞 + Modal->>PM: usePrompt(id) + PM->>Storage: 更新使用記錄 + Modal->>UI: 填入提示詞內容 +``` + +### 會話管理流程 + +```mermaid +sequenceDiagram + participant AI as AI 助手 + participant Server as MCP 服務器 + participant SM as SessionManager + participant SDM as SessionDataManager + participant UI as 前端界面 + + Note over AI,UI: 📊 會話生命週期管理 + AI->>Server: interactive_feedback() + Server->>SM: createSession() + SM->>SDM: addCurrentSession() + SDM->>UI: 更新會話顯示 + + Note over AI,UI: 📝 用戶回饋處理 + UI->>Server: submit_feedback + Server->>SM: processFeedback() + SM->>SDM: updateSessionStatus() + SDM->>SDM: 記錄回饋數據 + SM->>AI: 返回回饋結果 + + Note over AI,UI: 📚 會話歷史管理 + SM->>SDM: addSessionToHistory() + SDM->>SDM: 檢查完成狀態 + alt 會話已完成 + SDM->>SDM: 加入歷史記錄 + SDM->>SDM: updateStats() + SDM->>UI: 觸發 onHistoryChange + else 會話未完成 + SDM->>SDM: 跳過歷史記錄 + end + + Note over AI,UI: 🔍 歷史查詢 + UI->>SDM: getSessionHistory() + SDM-->>UI: 返回歷史列表 + UI->>SDM: getSessionStats() + SDM-->>UI: 返回統計數據 +``` + ## 📊 狀態同步機制 ### WebSocket 訊息類型 @@ -484,12 +605,17 @@ graph LR SU[session_updated
會話更新] FR[feedback_received
回饋確認] ST[status_update
狀態更新] + ASS[auto_submit_status
自動提交狀態] + SH[session_history
會話歷史] end subgraph "客戶端 → 服務器" SF[submit_feedback
提交回饋] HB[heartbeat
心跳檢測] LS[language_switch
語言切換] + PM[prompt_management
提示詞管理] + ASC[auto_submit_control
自動提交控制] + SM[session_management
會話管理] end ``` @@ -498,15 +624,34 @@ graph LR ```mermaid stateDiagram-v2 [*] --> WAITING: 會話創建/更新 - WAITING --> FEEDBACK_PROCESSING: 用戶提交回饋 + WAITING --> AUTO_SUBMIT_READY: 自動提交條件滿足 + AUTO_SUBMIT_READY --> AUTO_SUBMIT_COUNTDOWN: 啟動倒數計時 + AUTO_SUBMIT_COUNTDOWN --> FEEDBACK_PROCESSING: 自動提交執行 + WAITING --> FEEDBACK_PROCESSING: 用戶手動提交回饋 FEEDBACK_PROCESSING --> FEEDBACK_SUBMITTED: 處理完成 FEEDBACK_SUBMITTED --> WAITING: 新會話更新 FEEDBACK_SUBMITTED --> [*]: 會話結束 + AUTO_SUBMIT_COUNTDOWN --> WAITING: 用戶取消自動提交 WAITING --> ERROR: 連接錯誤 FEEDBACK_PROCESSING --> ERROR: 處理錯誤 + AUTO_SUBMIT_COUNTDOWN --> ERROR: 自動提交錯誤 ERROR --> WAITING: 錯誤恢復 ERROR --> [*]: 致命錯誤 + + note right of AUTO_SUBMIT_READY + 檢查自動提交設定： + - 功能已啟用 + - 已選擇提示詞 + - 當前狀態為等待回饋 + end note + + note right of AUTO_SUBMIT_COUNTDOWN + 倒數計時狀態： + - 顯示剩餘時間 + - 允許用戶取消 + - 時間到自動提交 + end note ``` ## 🛡️ 錯誤處理和恢復 diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index 44b5d5a..969626a 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -65,6 +65,9 @@ graph TB HTML[HTML 模板
feedback.html/index.html] JS[JavaScript 模組
app.js + 功能模組] CSS[樣式系統
響應式設計] + PROMPT[提示詞管理
PromptManager + UI 組件] + SESSION_MGR[會話管理
SessionManager + 歷史追蹤] + AUTO_SUBMIT[自動提交
AutoSubmitManager + 倒數計時] end subgraph "工具層" @@ -98,6 +101,14 @@ graph TB WS -->|HTTP/WebSocket| BROWSER_UI BROWSER_UI --> USER + %% 新功能模組連接 + JS --> PROMPT + JS --> SESSION_MGR + JS --> AUTO_SUBMIT + PROMPT --> WS + SESSION_MGR --> WS + AUTO_SUBMIT --> WS + I18N --> ROUTES DEBUG --> SERVER UTILS --> MANAGER @@ -154,6 +165,9 @@ graph TB - 響應式 HTML/CSS 設計 - 實時 WebSocket 通信 - 豐富的用戶交互功能 +- **提示詞管理系統**：常用提示詞的 CRUD 操作和快速選擇 +- **會話管理功能**：會話歷史追蹤和統計分析 +- **自動提交機制**：倒數計時器和自動回饋提交 ### 3. 單一活躍會話模式 ```mermaid @@ -281,6 +295,18 @@ auto-refresh-manager → app - 設定管理 (settings-manager.js) - UI 控制 (ui-manager.js) - 自動刷新 (auto-refresh-manager.js) +- **提示詞管理模組群組**： + - prompt-manager.js (核心管理器) + - prompt-modal.js (編輯彈窗) + - prompt-settings-ui.js (設定界面) + - prompt-input-buttons.js (快速選擇按鈕) +- **會話管理模組群組**： + - session-manager.js (會話控制器) + - session-data-manager.js (數據管理器) + - session-utils.js (工具函數) +- **自動提交功能**： + - 整合在 app.js 中的 AutoSubmitManager + - 與提示詞管理和設定管理的深度整合 ## 📊 性能特性與優化 @@ -436,7 +462,8 @@ graph LR --- -**版本**: 2.3.0 -**最後更新**: 2024年12月 +**版本**: 2.4.0 +**最後更新**: 2025年6月 **維護者**: Minidoracat **架構類型**: Web-Only 四層架構 +**新功能**: 提示詞管理、自動提交、會話管理、語系切換優化