mirror of
https://github.com/Minidoracat/mcp-feedback-enhanced.git
synced 2025-07-27 02:22:26 +08:00
📝 架構文檔更新
This commit is contained in:
Minidoracat
parent
edee06b177
commit
f2ad48c3a5
@ -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 全面更新，包含所有新功能的詳細說明和架構分析
|
||||
|
||||
@ -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 新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製
|
||||
**歷史功能**: 自動提交、提示詞管理、會話管理、語系切換優化
|
||||
|
||||
@ -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<br/>會話控制器<br/>狀態管理]
|
||||
SDM[session-data-manager.js<br/>數據管理器<br/>歷史記錄]
|
||||
SU[session-utils.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 -->|工具函數| 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<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即可複製
|
||||
- **複製反饋**: 視覺提示複製成功狀態
|
||||
- **國際化支援**: 複製提示支援多語言
|
||||
|
||||
#### 自動提交功能整合
|
||||
|
||||
@ -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
|
||||
|
||||
@ -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 版本的完整技術文檔和部署指南。
|
||||
|
||||
@ -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<br/>連接建立]
|
||||
SU[session_updated<br/>會話更新]
|
||||
SU[session_updated<br/>會話更新<br/>🔊 觸發音效通知]
|
||||
FR[feedback_received<br/>回饋確認]
|
||||
ST[status_update<br/>狀態更新]
|
||||
ASS[auto_submit_status<br/>自動提交狀態]
|
||||
SH[session_history<br/>會話歷史]
|
||||
SH[session_history<br/>會話歷史<br/>📚 v2.4.3 增強]
|
||||
AN[audio_notification<br/>音效通知<br/>🔊 v2.4.3 新增]
|
||||
end
|
||||
|
||||
subgraph "客戶端 → 服務器"
|
||||
@ -615,7 +711,9 @@ graph LR
|
||||
LS[language_switch<br/>語言切換]
|
||||
PM[prompt_management<br/>提示詞管理]
|
||||
ASC[auto_submit_control<br/>自動提交控制]
|
||||
SM[session_management<br/>會話管理]
|
||||
SM[session_management<br/>會話管理<br/>📋 v2.4.3 重構]
|
||||
AM[audio_management<br/>音效管理<br/>🎵 v2.4.3 新增]
|
||||
HM[height_management<br/>高度管理<br/>📏 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 新功能**: 音效通知系統、會話管理重構、智能記憶功能
|
||||
|
||||
@ -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 模組<br/>app.js + 功能模組]
|
||||
CSS[樣式系統<br/>響應式設計]
|
||||
PROMPT[提示詞管理<br/>PromptManager + UI 組件]
|
||||
SESSION_MGR[會話管理<br/>SessionManager + 歷史追蹤]
|
||||
SESSION_MGR[會話管理<br/>SessionManager + 歷史追蹤<br/>v2.4.3 重構增強]
|
||||
AUTO_SUBMIT[自動提交<br/>AutoSubmitManager + 倒數計時]
|
||||
AUDIO_MGR[音效通知系統<br/>AudioManager + 自訂音效<br/>v2.4.3 新增]
|
||||
MEMORY_MGR[智能記憶功能<br/>高度管理 + 一鍵複製<br/>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<br/>音效管理器]
|
||||
ASU[AudioSettingsUI<br/>設定界面]
|
||||
DA[DefaultAudios<br/>內建音效]
|
||||
CA[CustomAudios<br/>自訂音效]
|
||||
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[左側邊欄<br/>會話管理]
|
||||
COMPAT[瀏覽器相容性問題<br/>小視窗按鈕無法點擊]
|
||||
end
|
||||
|
||||
subgraph "v2.4.3 重構"
|
||||
TAB[獨立頁籤<br/>會話管理]
|
||||
ENHANCED[增強功能<br/>本地存儲 + 隱私控制]
|
||||
end
|
||||
|
||||
SIDEBAR -->|重構| TAB
|
||||
COMPAT -->|解決| ENHANCED
|
||||
```
|
||||
|
||||
**新增功能模組**：
|
||||
- **session-ui-renderer.js**: 專門的 UI 渲染器
|
||||
- **session-details-modal.js**: 會話詳情彈窗
|
||||
- **本地歷史存儲**: 支援 72 小時可配置保存期限
|
||||
- **隱私控制**: 三級用戶訊息記錄設定
|
||||
- **數據管理**: 匯出和清理功能
|
||||
|
||||
### 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即可複製
|
||||
- **複製反饋**: 視覺提示複製成功
|
||||
- **國際化支援**: 複製提示支援多語言
|
||||
|
||||
## 🔄 核心工作流程
|
||||
|
||||
### 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 新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製
|
||||
**歷史功能**: 提示詞管理、自動提交、會話管理、語系切換優化
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user