From f2ad48c3a578ababa81607b7f7e614ea05e1147d Mon Sep 17 00:00:00 2001 From: Minidoracat Date: Sat, 14 Jun 2025 20:10:27 +0800 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20=E6=9E=B6=E6=A7=8B=E6=96=87?= =?UTF-8?q?=E6=AA=94=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture/README.md | 41 +++- docs/architecture/api-reference.md | 297 +++++++++++++++++++++++-- docs/architecture/component-details.md | 205 ++++++++++++++++- docs/architecture/deployment-guide.md | 248 ++++++++++++++++++++- docs/architecture/interaction-flows.md | 129 +++++++++-- docs/architecture/system-overview.md | 143 +++++++++++- 6 files changed, 1002 insertions(+), 61 deletions(-) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index a30be71..975ef54 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -26,13 +26,16 @@ MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新 - **智能資源管理**: 自動清理和會話生命週期管理 - **提示詞管理系統**: 常用提示詞的 CRUD 操作和快速選擇 - **自動提交功能**: 倒數計時器和自動回饋提交機制 -- **會話管理功能**: 會話歷史追蹤和統計分析 +- **會話管理功能**: 會話歷史追蹤和統計分析（v2.4.3 重構增強） +- **音效通知系統**: 智能音效提醒和自訂音效管理（v2.4.3 新增） +- **智能記憶功能**: 輸入框高度記憶和一鍵複製（v2.4.3 新增） - **多語言支援**: 繁體中文、簡體中文、英文動態切換 #### 技術棧 - **後端**: Python 3.11+, FastAPI, FastMCP -- **前端**: HTML5, JavaScript ES6+, WebSocket +- **前端**: HTML5, JavaScript ES6+, WebSocket, Web Audio API（v2.4.3） - **通信**: WebSocket, HTTP REST API +- **存儲**: localStorage（會話歷史、音效文件、設定記憶） - **部署**: uvicorn, 跨平台支援 ### 🎯 快速導航 @@ -50,12 +53,38 @@ MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新 - 交互流程圖 - 會話生命週期圖 - 部署拓撲圖 +- **音效通知系統架構圖**（v2.4.3 新增） +- **會話管理重構流程圖**（v2.4.3 新增） +- **智能記憶功能架構圖**（v2.4.3 新增） + +### 🆕 v2.4.3 版本亮點 + +#### 🔊 音效通知系統 +- **內建音效**: 經典提示音、通知鈴聲、輕柔鐘聲 +- **自訂音效**: 支援 MP3、WAV、OGG 格式上傳 +- **智能播放**: 會話更新時自動播放通知音效 +- **音量控制**: 0-100% 可調節音量 +- **瀏覽器相容**: 處理自動播放政策限制 + +#### 📋 會話管理重構 +- **頁籤化設計**: 從側邊欄遷移到獨立頁籤，解決瀏覽器相容性問題 +- **本地歷史存儲**: 支援 72 小時可配置保存期限 +- **隱私控制**: 三級用戶訊息記錄設定（完整/基本/停用） +- **數據管理**: 匯出和清理功能 +- **詳情查看**: 專門的會話詳情彈窗 + +#### 🧠 智能記憶功能 +- **輸入框高度記憶**: 自動保存和恢復輸入框高度 +- **一鍵複製**: 專案路徑和會話ID點擊複製 +- **設定持久化**: 用戶偏好自動保存 +- **國際化支援**: 複製提示支援多語言 --- -**版本**: 2.4.0 -**最後更新**: 2025年6月 +**版本**: 2.4.3 +**最後更新**: 2025年6月14日 **維護者**: Minidoracat **架構類型**: Web-Only 四層架構 -**新功能**: 提示詞管理、自動提交、會話管理、語系切換優化 -**文檔狀態**: ✅ 已完成全面更新，包含所有新功能的詳細說明 +**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製 +**歷史功能**: 提示詞管理、自動提交、會話管理、語系切換優化 +**文檔狀態**: ✅ 已完成 v2.4.3 全面更新，包含所有新功能的詳細說明和架構分析 diff --git a/docs/architecture/api-reference.md b/docs/architecture/api-reference.md index db3d7c9..2920140 100644 --- a/docs/architecture/api-reference.md +++ b/docs/architecture/api-reference.md @@ -270,22 +270,81 @@ ws://localhost:{port}/ws - `settings.timeout`: 自動提交倒數時間（秒） - `settings.promptId`: 自動提交使用的提示詞 ID -#### session_management +#### session_management（v2.4.3 重構增強） 會話管理操作。 ```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|export_history|view_details", + "sessionId": "550e8400-e29b-41d4-a716-446655440000", + "options": { + "retentionHours": 72, + "privacyLevel": "full", + "includeUserMessages": true + } } } ``` **字段說明**: -- `action`: 管理動作（get_history=獲取歷史, get_stats=獲取統計, clear_history=清除歷史） +- `action`: 管理動作（get_history=獲取歷史, get_stats=獲取統計, clear_history=清除歷史, export_history=匯出歷史, view_details=查看詳情） - `sessionId`: 會話 ID（可選） +- `options.retentionHours`: 歷史保存時間（小時） +- `options.privacyLevel`: 隱私等級（full=完整, basic=基本, disabled=停用） +- `options.includeUserMessages`: 是否包含用戶訊息記錄 + +#### audio_management（v2.4.3 新增） +音效管理操作。 + +```json +{ + "type": "audio_management", + "data": { + "action": "update_settings|test_audio|upload_custom|delete_custom", + "settings": { + "enabled": true, + "volume": 75, + "selectedAudioId": "notification-ding" + }, + "customAudio": { + "id": "custom_1_1703123456789", + "name": "自訂提示音", + "data": "data:audio/mp3;base64,//uQx...", + "mimeType": "audio/mp3" + } + } +} +``` + +**字段說明**: +- `action`: 操作類型（update_settings=更新設定, test_audio=測試播放, upload_custom=上傳自訂音效, delete_custom=刪除自訂音效） +- `settings.enabled`: 是否啟用音效通知 +- `settings.volume`: 音量（0-100） +- `settings.selectedAudioId`: 選中的音效 ID +- `customAudio`: 自訂音效數據 + +#### height_management（v2.4.3 新增） +輸入框高度管理。 + +```json +{ + "type": "height_management", + "data": { + "action": "save_height|load_height", + "elementId": "combinedFeedbackText", + "height": 200, + "settingKey": "combinedFeedbackTextHeight" + } +} +``` + +**字段說明**: +- `action`: 操作類型（save_height=保存高度, load_height=載入高度） +- `elementId`: 元素 ID +- `height`: 高度值（像素） +- `settingKey`: 設定鍵名 ### 📥 服務器 → 客戶端訊息 @@ -366,7 +425,7 @@ WebSocket 連接建立確認。 - `promptId`: 當前自動提交提示詞 ID - `promptName`: 當前自動提交提示詞名稱 -#### session_history +#### session_history（v2.4.3 增強） 會話歷史數據。 ```json @@ -379,18 +438,99 @@ WebSocket 連接建立確認。 "summary": "代碼審查完成", "status": "completed", "created_at": "2024-12-13T10:30:00Z", - "feedback_length": 150 + "completed_at": "2024-12-13T10:35:00Z", + "feedback_length": 150, + "user_messages": [ + { + "timestamp": "2024-12-13T10:32:00Z", + "content": "代碼看起來不錯", + "type": "text", + "submission_method": "manual" + } + ], + "project_directory": "./my-project" } ], "stats": { "total": 10, "completed": 8, - "average_feedback_length": 120 + "average_feedback_length": 120, + "today_count": 3, + "average_duration": 300 + }, + "retention_info": { + "retention_hours": 72, + "oldest_session": "2024-12-11T10:30:00Z", + "cleanup_count": 2 } } } ``` +#### audio_notification（v2.4.3 新增） +音效通知觸發。 + +```json +{ + "type": "audio_notification", + "data": { + "trigger": "session_updated", + "audioId": "notification-ding", + "volume": 75, + "timestamp": "2024-12-13T10:30:00Z" + } +} +``` + +**字段說明**: +- `trigger`: 觸發事件（session_updated=會話更新, feedback_received=回饋接收） +- `audioId`: 播放的音效 ID +- `volume`: 播放音量 +- `timestamp`: 觸發時間 + +#### audio_settings_update（v2.4.3 新增） +音效設定更新通知。 + +```json +{ + "type": "audio_settings_update", + "data": { + "settings": { + "enabled": true, + "volume": 75, + "selectedAudioId": "soft-chime" + }, + "availableAudios": [ + { + "id": "default-beep", + "name": "經典提示音", + "isDefault": true + }, + { + "id": "custom_1", + "name": "自訂音效1", + "isDefault": false + } + ] + } +} +``` + +#### height_settings_update（v2.4.3 新增） +高度設定更新通知。 + +```json +{ + "type": "height_settings_update", + "data": { + "elementId": "combinedFeedbackText", + "height": 200, + "saved": true, + "timestamp": "2024-12-13T10:30:00Z" + } +} +``` + #### error 錯誤訊息。 @@ -505,7 +645,7 @@ def getPromptsSortedByUsage(self) -> List[dict] 獲取按使用頻率排序的提示詞列表，自動提交提示詞優先顯示。 -### SessionManager API +### SessionManager API（v2.4.3 重構增強） #### getCurrentSession() ```python @@ -516,17 +656,108 @@ def getCurrentSession(self) -> dict #### getSessionHistory() ```python -def getSessionHistory(self) -> List[dict] +def getSessionHistory(self, retentionHours: int = 72) -> List[dict] ``` -獲取會話歷史記錄。 +獲取會話歷史記錄，支援保存期限過濾。 #### getSessionStats() ```python def getSessionStats(self) -> dict ``` -獲取會話統計信息。 +獲取會話統計信息，包含今日統計和平均時長。 + +#### exportSessionHistory() +```python +def exportSessionHistory(self, format: str = "json") -> str +``` + +匯出會話歷史數據。 + +**參數**: +- `format`: 匯出格式（json, csv） + +#### cleanupExpiredSessions() +```python +def cleanupExpiredSessions(self, retentionHours: int = 72) -> int +``` + +清理過期會話記錄。 + +**返回值**: 清理的會話數量 + +### AudioManager API（v2.4.3 新增） + +#### playNotification() +```python +def playNotification(self) -> None +``` + +播放通知音效。 + +#### updateSettings() +```python +def updateSettings(self, enabled: bool, volume: int, selectedAudioId: str) -> None +``` + +更新音效設定。 + +#### addCustomAudio() +```python +def addCustomAudio(self, name: str, audioData: str, mimeType: str) -> dict +``` + +新增自訂音效。 + +**參數**: +- `name`: 音效名稱 +- `audioData`: Base64 編碼的音效數據 +- `mimeType`: MIME 類型（audio/mp3, audio/wav, audio/ogg） + +#### deleteCustomAudio() +```python +def deleteCustomAudio(self, audioId: str) -> bool +``` + +刪除自訂音效。 + +#### getAllAudios() +```python +def getAllAudios(self) -> List[dict] +``` + +獲取所有可用音效（內建 + 自訂）。 + +### TextareaHeightManager API（v2.4.3 新增） + +#### registerTextarea() +```python +def registerTextarea(self, elementId: str, settingKey: str) -> bool +``` + +註冊 textarea 元素進行高度管理。 + +#### saveHeight() +```python +def saveHeight(self, elementId: str, height: int) -> None +``` + +保存 textarea 高度到設定。 + +#### loadHeight() +```python +def loadHeight(self, elementId: str) -> int +``` + +從設定載入 textarea 高度。 + +#### unregisterTextarea() +```python +def unregisterTextarea(self, elementId: str) -> None +``` + +取消註冊 textarea 元素。 ### AutoSubmitManager API @@ -595,6 +826,32 @@ class AutoSubmitStatus: COMPLETED = "completed" # 已完成提交 ``` +### 音效通知狀態（v2.4.3 新增） +```python +class AudioNotificationStatus: + DISABLED = "disabled" # 已停用 + ENABLED = "enabled" # 已啟用 + PLAYING = "playing" # 播放中 + ERROR = "error" # 播放錯誤 +``` + +### 會話歷史狀態（v2.4.3 新增） +```python +class SessionHistoryStatus: + ACTIVE = "active" # 活躍會話 + COMPLETED = "completed" # 已完成會話 + EXPIRED = "expired" # 已過期會話 + ARCHIVED = "archived" # 已歸檔會話 +``` + +### 隱私等級（v2.4.3 新增） +```python +class PrivacyLevel: + FULL = "full" # 完整記錄 + BASIC = "basic" # 基本記錄 + DISABLED = "disabled" # 停用記錄 +``` + ## 🔒 安全考慮 ### 輸入驗證 @@ -605,6 +862,15 @@ class AutoSubmitStatus: - 提示詞名稱長度限制：最大 100 字符 - 提示詞內容長度限制：最大 5,000 字符 - 提示詞數量限制：最多 50 個 +- **音效文件限制（v2.4.3 新增）**： + - 支援格式：MP3, WAV, OGG + - 單個文件最大：2MB + - 自訂音效數量：最多 20 個 + - 音效名稱長度：最大 50 字符 +- **會話歷史限制（v2.4.3 新增）**： + - 預設保存期限：72 小時 + - 最大保存期限：168 小時（7天） + - 單個會話最大用戶訊息數：100 條 ### 資源保護 - WebSocket 連接數限制：每會話最多 5 個連接 @@ -633,9 +899,10 @@ app.add_middleware( --- -**版本**: 2.4.0 -**最後更新**: 2025年6月 +**版本**: 2.4.3 +**最後更新**: 2025年6月14日 **維護者**: Minidoracat **API 版本**: v1 -**協議支援**: MCP 2.0+, WebSocket, HTTP/1.1 -**新功能**: 自動提交、提示詞管理、會話管理、語系切換優化 +**協議支援**: MCP 2.0+, WebSocket, HTTP/1.1, Web Audio API +**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製 +**歷史功能**: 自動提交、提示詞管理、會話管理、語系切換優化 diff --git a/docs/architecture/component-details.md b/docs/architecture/component-details.md index de61065..49a8fcc 100644 --- a/docs/architecture/component-details.md +++ b/docs/architecture/component-details.md @@ -588,26 +588,106 @@ graph TB - **PromptSettingsUI**: 設定頁籤中的提示詞管理界面 - **PromptInputButtons**: 回饋輸入區的快速選擇按鈕 -#### 會話管理模組群組 (session/) +#### 會話管理模組群組 (session/) - v2.4.3 重構增強 **模組結構**： ```mermaid graph TB - subgraph "會話管理模組" + subgraph "會話管理模組（v2.4.3 重構）" SM[session-manager.js
會話控制器
狀態管理] - SDM[session-data-manager.js
數據管理器
歷史記錄] - SU[session-utils.js
工具函數
狀態判斷] + SDM[session-data-manager.js
數據管理器
本地存儲增強] + SUR[session-ui-renderer.js
UI 渲染器
頁籤化設計] + SDM_MODAL[session-details-modal.js
詳情彈窗
會話詳細資訊] end SM -->|數據操作| SDM - SM -->|工具函數| SU + SM -->|UI 渲染| SUR + SM -->|詳情顯示| SDM_MODAL SDM -->|狀態回調| SM + SUR -->|用戶操作| SM + SDM_MODAL -->|查看操作| SM ``` +**v2.4.3 重構亮點**： +- **從側邊欄遷移到頁籤**: 解決瀏覽器相容性問題 +- **本地歷史存儲**: 支援 72 小時可配置保存期限 +- **隱私控制**: 三級用戶訊息記錄設定（完整/基本/停用） +- **數據管理**: 匯出和清理功能 +- **UI 重新設計**: 專門的渲染器和詳情彈窗 + **核心功能**： - **SessionManager**: 當前會話的狀態管理和控制 -- **SessionDataManager**: 會話歷史記錄和統計數據管理 -- **SessionUtils**: 會話狀態判斷和工具函數 +- **SessionDataManager**: 會話歷史記錄、統計數據和本地存儲管理 +- **SessionUIRenderer**: 專門的 UI 渲染器，負責會話列表和狀態顯示 +- **SessionDetailsModal**: 會話詳情彈窗，提供完整的會話資訊查看 + +#### 音效通知模組群組 (audio/) - v2.4.3 新增 + +**模組結構**： +```mermaid +graph TB + subgraph "音效通知系統（v2.4.3 新增）" + AM[audio-manager.js
音效管理器
播放控制] + ASU[audio-settings-ui.js
設定界面
音效配置] + DA[DefaultAudios
內建音效
Base64 編碼] + CA[CustomAudios
自訂音效
用戶上傳] + 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
高度管理器] + RO[ResizeObserver
尺寸監控] + DEBOUNCE[防抖機制
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即可複製 +- **複製反饋**: 視覺提示複製成功狀態 +- **國際化支援**: 複製提示支援多語言 #### 自動提交功能整合 @@ -883,6 +963,110 @@ class ImageHandler { - **性能優化**: 延遲載入和資源快取 - **無障礙支援**: 鍵盤導航和螢幕閱讀器支援 +### 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 - 錯誤處理框架 @@ -1181,8 +1365,9 @@ tests/ --- -**版本**: 2.3.0 -**最後更新**: 2024年12月 +**版本**: 2.4.3 +**最後更新**: 2025年6月14日 **維護者**: Minidoracat **架構類型**: Web-Only 四層架構 -**技術棧**: Python 3.11+, FastAPI, FastMCP, WebSocket +**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能 +**技術棧**: Python 3.11+, FastAPI, FastMCP, WebSocket, Web Audio API diff --git a/docs/architecture/deployment-guide.md b/docs/architecture/deployment-guide.md index 54e5098..75dcdb1 100644 --- a/docs/architecture/deployment-guide.md +++ b/docs/architecture/deployment-guide.md @@ -46,12 +46,14 @@ graph TB - **內存**: 512MB 可用內存 - **磁盤**: 100MB 可用空間 - **網路**: 可訪問的網路連接 +- **瀏覽器**: 支援 Web Audio API 的現代瀏覽器（v2.4.3 音效功能） #### 推薦配置 - **Python**: 3.12+ - **內存**: 1GB+ 可用內存 -- **磁盤**: 500MB+ 可用空間 +- **磁盤**: 500MB+ 可用空間（包含音效文件存儲） - **CPU**: 2 核心或更多 +- **瀏覽器**: Chrome 90+, Firefox 88+, Safari 14+（完整功能支援） ### 安裝方式 @@ -61,7 +63,7 @@ graph TB uvx mcp-feedback-enhanced@latest web # 指定版本 -uvx mcp-feedback-enhanced@2.3.0 web +uvx mcp-feedback-enhanced@2.4.3 web ``` #### 2. 使用 pip @@ -223,6 +225,8 @@ mcp-feedback-enhanced web [OPTIONS] | `--debug` | `bool` | `False` | 啟用調試模式 | | `--no-browser` | `bool` | `False` | 不自動開啟瀏覽器 | | `--timeout` | `int` | `600` | 預設會話超時時間（秒） | +| `--audio-enabled` | `bool` | `True` | 啟用音效通知（v2.4.3 新增） | +| `--session-retention` | `int` | `72` | 會話歷史保存時間（小時，v2.4.3 新增） | ### 環境變數 @@ -232,6 +236,8 @@ export MCP_FEEDBACK_HOST=0.0.0.0 export MCP_FEEDBACK_PORT=9000 export MCP_FEEDBACK_DEBUG=true export MCP_FEEDBACK_TIMEOUT=1200 +export MCP_FEEDBACK_AUDIO_ENABLED=true +export MCP_FEEDBACK_SESSION_RETENTION=72 ``` ### 配置文件 @@ -250,6 +256,101 @@ export MCP_FEEDBACK_TIMEOUT=1200 "ui": { "default_language": "zh-TW", "theme": "light" + }, + "audio": { + "enabled": true, + "default_volume": 75, + "max_custom_audios": 20, + "max_file_size_mb": 2 + }, + "session_history": { + "retention_hours": 72, + "max_retention_hours": 168, + "privacy_level": "full", + "auto_cleanup": true + } +} +``` + +## 🆕 v2.4.3 版本部署考慮 + +### 音效通知系統部署 + +#### 瀏覽器相容性檢查 +```javascript +// 檢查 Web Audio API 支援 +function checkAudioSupport() { + if (typeof Audio === 'undefined') { + console.warn('Web Audio API 不支援，音效功能將被停用'); + return false; + } + return true; +} +``` + +#### 音效文件存儲配置 +```json +{ + "audio_storage": { + "type": "localStorage", + "max_size_mb": 10, + "compression": true, + "fallback_enabled": true + } +} +``` + +#### 自動播放政策處理 +```bash +# 部署時需要考慮瀏覽器自動播放限制 +# Chrome: 需要用戶交互後才能播放音效 +# Firefox: 預設允許音效播放 +# Safari: 需要用戶手勢觸發 +``` + +### 會話管理重構部署 + +#### localStorage 容量規劃 +```javascript +// 估算存儲需求 +const estimatedStorage = { + sessions_per_day: 50, + average_session_size_kb: 5, + retention_days: 3, + total_size_mb: (50 * 5 * 3) / 1024 // 約 0.73 MB +}; +``` + +#### 隱私設定配置 +```json +{ + "privacy_defaults": { + "user_message_recording": "full", + "retention_hours": 72, + "auto_cleanup": true, + "export_enabled": true + } +} +``` + +### 智能記憶功能部署 + +#### ResizeObserver 支援檢查 +```javascript +// 檢查 ResizeObserver 支援 +if (typeof ResizeObserver === 'undefined') { + console.warn('ResizeObserver 不支援，高度記憶功能將使用 fallback'); + // 使用 window.resize 事件作為 fallback +} +``` + +#### 設定存儲優化 +```json +{ + "memory_settings": { + "debounce_delay_ms": 500, + "max_stored_heights": 10, + "cleanup_interval_hours": 24 } } ``` @@ -266,9 +367,19 @@ curl http://localhost:8000/health # 響應示例 { "status": "healthy", - "version": "2.3.0", + "version": "2.4.3", "uptime": "2h 30m 15s", - "active_sessions": 1 + "active_sessions": 1, + "features": { + "audio_notifications": true, + "session_history": true, + "smart_memory": true + }, + "storage": { + "session_history_count": 25, + "custom_audio_count": 3, + "localStorage_usage_mb": 1.2 + } } ``` @@ -309,7 +420,41 @@ MAX_WEBSOCKET_CONNECTIONS = 50 #### 常見問題 -1. **埠被佔用** +**v2.4.3 新增問題**： + +1. **音效無法播放** +```bash +# 檢查瀏覽器自動播放政策 +# 解決方案：用戶需要先與頁面交互 +console.log('請點擊頁面任意位置以啟用音效功能'); + +# 檢查音效文件格式 +# 支援格式：MP3, WAV, OGG +# 最大文件大小：2MB +``` + +2. **會話歷史丟失** +```bash +# 檢查 localStorage 容量 +# 解決方案：清理過期數據或增加保存期限 +localStorage.getItem('sessionHistory'); + +# 檢查隱私設定 +# 確認用戶訊息記錄等級設定正確 +``` + +3. **輸入框高度不記憶** +```bash +# 檢查 ResizeObserver 支援 +if (typeof ResizeObserver === 'undefined') { + console.warn('瀏覽器不支援 ResizeObserver'); +} + +# 檢查設定存儲 +localStorage.getItem('combinedFeedbackTextHeight'); +``` + +4. **埠被佔用** ```bash # 檢查埠使用情況 netstat -tulpn | grep 8000 @@ -391,6 +536,13 @@ sudo firewall-cmd --reload - 平均回應時間 - 錯誤率 +### v2.4.3 新增指標 +- 音效播放成功率 +- 會話歷史存儲使用量 +- 自訂音效上傳數量 +- 輸入框高度調整頻率 +- localStorage 使用量 + ### 監控工具集成 ```python # Prometheus 指標 @@ -399,8 +551,92 @@ 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') + +# v2.4.3 新增指標 +audio_plays = Counter('mcp_audio_plays_total', 'Total audio notifications played') +audio_errors = Counter('mcp_audio_errors_total', 'Total audio playback errors') +session_history_size = Gauge('mcp_session_history_size_bytes', 'Session history storage size') +custom_audio_count = Gauge('mcp_custom_audio_count', 'Number of custom audio files') +height_adjustments = Counter('mcp_height_adjustments_total', 'Total textarea height adjustments') ``` --- -**完成**: 架構文檔體系已建立完成，包含完整的技術文檔和部署指南。 +## 🔄 版本升級指南 + +### 從 v2.4.2 升級到 v2.4.3 + +#### 1. 備份現有數據 +```bash +# 備份用戶設定 +cp ~/.mcp-feedback/settings.json ~/.mcp-feedback/settings.json.backup + +# 備份提示詞數據 +cp ~/.mcp-feedback/prompts.json ~/.mcp-feedback/prompts.json.backup +``` + +#### 2. 升級軟體 +```bash +# 使用 uvx 升級 +uvx mcp-feedback-enhanced@2.4.3 web + +# 或使用 pip 升級 +pip install --upgrade mcp-feedback-enhanced==2.4.3 +``` + +#### 3. 驗證新功能 +```bash +# 檢查音效功能 +curl http://localhost:8000/health | jq '.features.audio_notifications' + +# 檢查會話歷史功能 +curl http://localhost:8000/health | jq '.features.session_history' + +# 檢查智能記憶功能 +curl http://localhost:8000/health | jq '.features.smart_memory' +``` + +#### 4. 配置遷移 +```json +// 新增的配置項目會自動使用預設值 +{ + "audio": { + "enabled": true, + "volume": 75, + "selectedAudioId": "default-beep" + }, + "sessionHistory": { + "retentionHours": 72, + "privacyLevel": "full" + }, + "smartMemory": { + "heightMemoryEnabled": true + } +} +``` + +### 回滾指南 + +如果需要回滾到 v2.4.2： + +```bash +# 停止服務 +pkill -f mcp-feedback-enhanced + +# 安裝舊版本 +pip install mcp-feedback-enhanced==2.4.2 + +# 恢復備份設定 +cp ~/.mcp-feedback/settings.json.backup ~/.mcp-feedback/settings.json + +# 重新啟動服務 +mcp-feedback-enhanced web +``` + +--- + +**版本**: 2.4.3 +**最後更新**: 2025年6月14日 +**維護者**: Minidoracat +**新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製 +**完成**: 架構文檔體系已更新完成，包含 v2.4.3 版本的完整技術文檔和部署指南。 diff --git a/docs/architecture/interaction-flows.md b/docs/architecture/interaction-flows.md index a2d96f8..e050947 100644 --- a/docs/architecture/interaction-flows.md +++ b/docs/architecture/interaction-flows.md @@ -553,7 +553,7 @@ sequenceDiagram Modal->>UI: 填入提示詞內容 ``` -### 會話管理流程 +### 會話管理流程（v2.4.3 重構增強） ```mermaid sequenceDiagram @@ -561,52 +561,148 @@ sequenceDiagram participant Server as MCP 服務器 participant SM as SessionManager participant SDM as SessionDataManager + participant SUR as SessionUIRenderer participant UI as 前端界面 - Note over AI,UI: 📊 會話生命週期管理 + Note over AI,UI: 📊 會話生命週期管理（v2.4.3 重構） AI->>Server: interactive_feedback() Server->>SM: createSession() SM->>SDM: addCurrentSession() - SDM->>UI: 更新會話顯示 + SDM->>SUR: renderCurrentSession() + SUR->>UI: 更新會話顯示（頁籤化設計） Note over AI,UI: 📝 用戶回饋處理 UI->>Server: submit_feedback Server->>SM: processFeedback() SM->>SDM: updateSessionStatus() - SDM->>SDM: 記錄回饋數據 + SDM->>SDM: 記錄回饋數據（本地存儲） SM->>AI: 返回回饋結果 - Note over AI,UI: 📚 會話歷史管理 + Note over AI,UI: 📚 會話歷史管理（v2.4.3 增強） SM->>SDM: addSessionToHistory() SDM->>SDM: 檢查完成狀態 alt 會話已完成 - SDM->>SDM: 加入歷史記錄 + SDM->>SDM: 加入歷史記錄（localStorage） SDM->>SDM: updateStats() - SDM->>UI: 觸發 onHistoryChange + SDM->>SUR: renderSessionHistory() + SUR->>UI: 觸發 onHistoryChange else 會話未完成 SDM->>SDM: 跳過歷史記錄 end - Note over AI,UI: 🔍 歷史查詢 + Note over AI,UI: 🔍 歷史查詢與管理 UI->>SDM: getSessionHistory() - SDM-->>UI: 返回歷史列表 + SDM-->>UI: 返回歷史列表（72小時內） UI->>SDM: getSessionStats() SDM-->>UI: 返回統計數據 + UI->>SDM: exportSessionHistory() + SDM-->>UI: 返回匯出數據 + UI->>SDM: cleanupExpiredSessions() + SDM->>SDM: 清理過期會話 +``` + +### 音效通知系統流程（v2.4.3 新增） + +```mermaid +sequenceDiagram + participant WS as WebSocket + participant AM as AudioManager + participant ASU as AudioSettingsUI + participant AUDIO as Web Audio API + participant User as 用戶 + + Note over WS,User: 🔊 音效通知觸發流程 + WS->>AM: session_updated 事件 + AM->>AM: checkNotificationEnabled() + alt 音效通知已啟用 + AM->>AM: getSelectedAudio() + AM->>AUDIO: 創建 Audio 物件 + AM->>AUDIO: 設定音量和來源 + AUDIO->>User: 播放通知音效 + AM->>AM: logPlaybackSuccess() + else 音效通知已停用 + AM->>AM: logSkippedNotification() + end + + Note over WS,User: 🎵 音效設定管理 + User->>ASU: 開啟音效設定 + ASU->>AM: getAudioSettings() + AM-->>ASU: 返回當前設定 + ASU->>User: 顯示設定界面 + + User->>ASU: 調整音量 + ASU->>AM: updateVolume(volume) + AM->>AM: saveSettings() + + User->>ASU: 選擇音效 + ASU->>AM: selectAudio(audioId) + AM->>AM: saveSettings() + + User->>ASU: 測試播放 + ASU->>AM: testPlayAudio(audioId) + AM->>AUDIO: 播放測試音效 + AUDIO->>User: 播放音效 + + Note over WS,User: 📁 自訂音效管理 + User->>ASU: 上傳自訂音效 + ASU->>ASU: validateAudioFile() + ASU->>AM: addCustomAudio(file) + AM->>AM: convertToBase64() + AM->>AM: saveToLocalStorage() + ASU->>User: 顯示上傳成功 +``` + +### 智能記憶功能流程（v2.4.3 新增） + +```mermaid +sequenceDiagram + participant User as 用戶 + participant TEXTAREA as 輸入框 + participant THM as TextareaHeightManager + participant RO as ResizeObserver + participant SM as SettingsManager + + Note over User,SM: 📏 輸入框高度記憶 + User->>TEXTAREA: 調整輸入框高度 + TEXTAREA->>RO: 觸發尺寸變化事件 + RO->>THM: handleResize(element) + THM->>THM: debounce(500ms) + THM->>SM: saveHeight(elementId, height) + SM->>SM: 保存到 localStorage + + Note over User,SM: 🔄 高度恢復 + User->>User: 重新載入頁面 + THM->>SM: loadHeight(elementId) + SM-->>THM: 返回保存的高度 + THM->>TEXTAREA: 應用保存的高度 + TEXTAREA->>User: 顯示恢復的高度 + + Note over User,SM: 📋 一鍵複製功能 + User->>User: 點擊專案路徑 + User->>User: 觸發複製事件 + User->>User: 複製到剪貼簿 + User->>User: 顯示複製成功提示 + + User->>User: 點擊會話ID + User->>User: 觸發複製事件 + User->>User: 複製到剪貼簿 + User->>User: 顯示複製成功提示（多語言） ``` ## 📊 狀態同步機制 -### WebSocket 訊息類型 +### WebSocket 訊息類型（v2.4.3 擴展） ```mermaid graph LR subgraph "服務器 → 客戶端" CE[connection_established
連接建立] - SU[session_updated
會話更新] + SU[session_updated
會話更新
🔊 觸發音效通知] FR[feedback_received
回饋確認] ST[status_update
狀態更新] ASS[auto_submit_status
自動提交狀態] - SH[session_history
會話歷史] + SH[session_history
會話歷史
📚 v2.4.3 增強] + AN[audio_notification
音效通知
🔊 v2.4.3 新增] end subgraph "客戶端 → 服務器" @@ -615,7 +711,9 @@ graph LR LS[language_switch
語言切換] PM[prompt_management
提示詞管理] ASC[auto_submit_control
自動提交控制] - SM[session_management
會話管理] + SM[session_management
會話管理
📋 v2.4.3 重構] + AM[audio_management
音效管理
🎵 v2.4.3 新增] + HM[height_management
高度管理
📏 v2.4.3 新增] end ``` @@ -742,8 +840,9 @@ async def wait_for_feedback(self, timeout: int = 600): --- -**版本**: 2.3.0 -**最後更新**: 2024年12月 +**版本**: 2.4.3 +**最後更新**: 2025年6月14日 **維護者**: Minidoracat **架構類型**: Web-Only 四層架構 **核心特性**: 持久化會話、智能環境適配、無縫狀態切換 +**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能 diff --git a/docs/architecture/system-overview.md b/docs/architecture/system-overview.md index 969626a..5500e41 100644 --- a/docs/architecture/system-overview.md +++ b/docs/architecture/system-overview.md @@ -25,6 +25,9 @@ MCP Feedback Enhanced 採用**單一活躍會話 + 持久化 Web UI**的創新 - HTML5 + CSS3 (現代化 UI) - JavaScript ES6+ (模組化架構) - WebSocket API (雙向通信) +- Web Audio API (音效通知系統) +- localStorage API (本地數據存儲) +- ResizeObserver API (元素尺寸監控) - 響應式設計 (多設備支援) **開發工具**： @@ -66,8 +69,10 @@ graph TB JS[JavaScript 模組
app.js + 功能模組] CSS[樣式系統
響應式設計] PROMPT[提示詞管理
PromptManager + UI 組件] - SESSION_MGR[會話管理
SessionManager + 歷史追蹤] + SESSION_MGR[會話管理
SessionManager + 歷史追蹤
v2.4.3 重構增強] AUTO_SUBMIT[自動提交
AutoSubmitManager + 倒數計時] + AUDIO_MGR[音效通知系統
AudioManager + 自訂音效
v2.4.3 新增] + MEMORY_MGR[智能記憶功能
高度管理 + 一鍵複製
v2.4.3 新增] end subgraph "工具層" @@ -105,9 +110,13 @@ graph TB JS --> PROMPT JS --> SESSION_MGR JS --> AUTO_SUBMIT + JS --> AUDIO_MGR + JS --> MEMORY_MGR PROMPT --> WS SESSION_MGR --> WS AUTO_SUBMIT --> WS + AUDIO_MGR --> WS + MEMORY_MGR --> WS I18N --> ROUTES DEBUG --> SERVER @@ -166,8 +175,10 @@ graph TB - 實時 WebSocket 通信 - 豐富的用戶交互功能 - **提示詞管理系統**：常用提示詞的 CRUD 操作和快速選擇 -- **會話管理功能**：會話歷史追蹤和統計分析 +- **會話管理功能**：會話歷史追蹤和統計分析（v2.4.3 重構增強） - **自動提交機制**：倒數計時器和自動回饋提交 +- **音效通知系統**：智能音效提醒和自訂音效管理（v2.4.3 新增） +- **智能記憶功能**：輸入框高度記憶和一鍵複製（v2.4.3 新增） ### 3. 單一活躍會話模式 ```mermaid @@ -300,10 +311,17 @@ auto-refresh-manager → app - prompt-modal.js (編輯彈窗) - prompt-settings-ui.js (設定界面) - prompt-input-buttons.js (快速選擇按鈕) -- **會話管理模組群組**： +- **會話管理模組群組（v2.4.3 重構增強）**： - session-manager.js (會話控制器) - - session-data-manager.js (數據管理器) - - session-utils.js (工具函數) + - session-data-manager.js (數據管理器，新增本地存儲) + - session-ui-renderer.js (UI 渲染器，頁籤化設計) + - session-details-modal.js (詳情彈窗) +- **音效通知模組群組（v2.4.3 新增）**： + - audio-manager.js (音效管理器) + - audio-settings-ui.js (音效設定界面) +- **智能記憶功能（v2.4.3 新增）**： + - textarea-height-manager.js (輸入框高度管理) + - 一鍵複製功能整合在各 UI 組件中 - **自動提交功能**： - 整合在 app.js 中的 AutoSubmitManager - 與提示詞管理和設定管理的深度整合 @@ -364,21 +382,127 @@ auto-refresh-manager → app - **併發控制**: 安全的多執行緒操作 - **數據驗證**: 嚴格的輸入驗證和清理 +## 🆕 v2.4.3 版本新功能架構 + +### 1. 音效通知系統架構 + +**系統組成**： +```mermaid +graph TB + subgraph "音效通知系統" + AM[AudioManager
音效管理器] + ASU[AudioSettingsUI
設定界面] + DA[DefaultAudios
內建音效] + CA[CustomAudios
自訂音效] + end + + subgraph "Web Audio API" + AUDIO[Audio 物件] + BASE64[Base64 音效數據] + end + + subgraph "設定存儲" + LS[localStorage] + SM[SettingsManager] + end + + AM --> ASU + AM --> DA + AM --> CA + AM --> AUDIO + AUDIO --> BASE64 + ASU --> SM + SM --> LS + + WS[WebSocket] -->|會話更新事件| AM + AM -->|播放通知| AUDIO +``` + +**核心特性**： +- **內建音效**: 經典提示音、通知鈴聲、輕柔鐘聲 +- **自訂音效**: 支援 MP3、WAV、OGG 格式上傳 +- **音量控制**: 0-100% 可調節音量 +- **測試播放**: 即時測試音效效果 +- **設定持久化**: 音效偏好自動保存 + +### 2. 會話管理重構架構 + +**從側邊欄到頁籤的遷移**： +```mermaid +graph LR + subgraph "v2.4.2 設計" + SIDEBAR[左側邊欄
會話管理] + COMPAT[瀏覽器相容性問題
小視窗按鈕無法點擊] + end + + subgraph "v2.4.3 重構" + TAB[獨立頁籤
會話管理] + ENHANCED[增強功能
本地存儲 + 隱私控制] + end + + SIDEBAR -->|重構| TAB + COMPAT -->|解決| ENHANCED +``` + +**新增功能模組**： +- **session-ui-renderer.js**: 專門的 UI 渲染器 +- **session-details-modal.js**: 會話詳情彈窗 +- **本地歷史存儲**: 支援 72 小時可配置保存期限 +- **隱私控制**: 三級用戶訊息記錄設定 +- **數據管理**: 匯出和清理功能 + +### 3. 智能記憶功能架構 + +**輸入框高度管理**： +```mermaid +graph TB + subgraph "高度管理系統" + THM[TextareaHeightManager
高度管理器] + RO[ResizeObserver
尺寸監控] + DEBOUNCE[防抖機制
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即可複製 +- **複製反饋**: 視覺提示複製成功 +- **國際化支援**: 複製提示支援多語言 + ## 🔄 核心工作流程 -### AI 助手調用流程 +### AI 助手調用流程（v2.4.3 增強） ```mermaid sequenceDiagram participant AI as AI 助手 participant MCP as MCP 服務 participant WM as WebUIManager participant UI as Web UI + participant AUDIO as 音效管理器 participant User as 用戶 AI->>MCP: interactive_feedback() MCP->>WM: 創建/更新會話 WM->>UI: 啟動 Web 服務 WM->>User: 智能開啟瀏覽器 + + Note over UI,AUDIO: v2.4.3 新增音效通知 + UI->>AUDIO: 會話更新事件 + AUDIO->>User: 播放通知音效 + User->>UI: 提交回饋 UI->>WM: WebSocket 傳送 WM->>MCP: 回饋完成 @@ -462,8 +586,9 @@ graph LR --- -**版本**: 2.4.0 -**最後更新**: 2025年6月 +**版本**: 2.4.3 +**最後更新**: 2025年6月14日 **維護者**: Minidoracat **架構類型**: Web-Only 四層架構 -**新功能**: 提示詞管理、自動提交、會話管理、語系切換優化 +**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製 +**歷史功能**: 提示詞管理、自動提交、會話管理、語系切換優化