MCP/mcp-feedback-enhanced
1
0
Fork 0
mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-07-27 10:42:25 +08:00
Code Issues Packages Projects Releases Wiki Activity
mcp-feedback-enhanced/docs/architecture/api-reference.md

909 lines
20 KiB
Markdown
Raw Permalink Normal View History

📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
# API 參考文檔
📝 更新架構文檔
2025-06-12 22:45:23 +08:00
本文檔提供 MCP Feedback Enhanced 的完整 API 參考，包括 MCP 工具、Web API、WebSocket 通信協議和內部 API 接口。
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
## 📡 MCP 工具 API
📝 更新架構文檔
2025-06-12 22:45:23 +08:00
MCP Feedback Enhanced 基於 FastMCP 框架實現，提供標準的 MCP 協議支援。
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
### interactive_feedback
AI 助手與用戶進行交互式回饋的核心 MCP 工具。
#### 函數簽名
```python
async def interactive_feedback(
project_directory: str,
summary: str,
timeout: int = 600
) -> dict
```
#### 參數說明
| 參數 | 類型 | 必需 | 預設值 | 描述 |
|------|------|------|--------|------|
| `project_directory` | `str` | ✅ | - | 專案目錄路徑，用於上下文顯示 |
| `summary` | `str` | ✅ | - | AI 助手的工作摘要，向用戶說明當前狀態 |
| `timeout` | `int` | ❌ | `600` | 等待用戶回饋的超時時間（秒） |
#### 返回值
```python
{
"command_logs": "", # 命令執行日誌（保留字段）
"interactive_feedback": str, # 用戶回饋內容
"images": List[str] # 用戶上傳的圖片（Base64 編碼）
}
```
#### 使用示例
```python
# 基本調用
result = await interactive_feedback(
project_directory="./my-web-app",
summary="我已完成登入功能的實現，包括表單驗證和錯誤處理。請檢查代碼品質。"
)
# 自定義超時
result = await interactive_feedback(
project_directory="./complex-project",
summary="重構完成，請詳細測試所有功能模組。",
timeout=1200 # 20分鐘
)
```
#### 錯誤處理
```python
try:
result = await interactive_feedback(...)
except TimeoutError:
print("用戶回饋超時")
except ValidationError as e:
print(f"參數驗證錯誤: {e}")
except EnvironmentError as e:
print(f"環境檢測錯誤: {e}")
```
## 🌐 Web API
### HTTP 端點
#### GET /
主頁重定向到回饋頁面。
**響應**: `302 Redirect` → `/feedback`
#### GET /feedback
回饋頁面主入口。
**響應**: `200 OK`
```html
<!DOCTYPE html>
<html>
<!-- 回饋頁面 HTML 內容 -->
</html>
```
#### GET /static/{path}
靜態資源服務（CSS、JS、圖片等）。
**參數**:
- `path`: 靜態資源路徑
**響應**: `200 OK` 或 `404 Not Found`
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
#### 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": "沒有活躍會話"
}
```
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
### WebSocket API
#### 連接端點
```
ws://localhost:{port}/ws
```
#### 訊息格式
所有 WebSocket 訊息都使用 JSON 格式：
```json
{
"type": "message_type",
"data": { /* 訊息數據 */ },
"timestamp": "2024-12-XX 10:30:00"
}
```
### 📤 客戶端 → 服務器訊息
#### submit_feedback
提交用戶回饋。
```json
{
"type": "submit_feedback",
"data": {
"feedback": "這個功能很好，但建議增加輸入驗證。",
"images": [
"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA..."
],
"settings": {
"language": "zh-TW",
"compress_images": true
}
}
}
```
**字段說明**:
- `feedback`: 用戶回饋文字內容
- `images`: 圖片數組（Base64 編碼）
- `settings.language`: 界面語言
- `settings.compress_images`: 是否壓縮圖片
#### heartbeat
心跳檢測訊息。
```json
{
"type": "heartbeat",
"data": {
"timestamp": 1703123456789
}
}
```
#### language_switch
切換界面語言。
```json
{
"type": "language_switch",
"data": {
"language": "en"
}
}
```
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
#### 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
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
#### session_management（v2.4.3 重構增強）
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
會話管理操作。
```json
{
"type": "session_management",
"data": {
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
"action": "get_history|get_stats|clear_history|export_history|view_details",
"sessionId": "550e8400-e29b-41d4-a716-446655440000",
"options": {
"retentionHours": 72,
"privacyLevel": "full",
"includeUserMessages": true
}
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
}
}
```
**字段說明**:
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
- `action`: 管理動作（get_history=獲取歷史, get_stats=獲取統計, clear_history=清除歷史, export_history=匯出歷史, view_details=查看詳情）
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
- `sessionId`: 會話 ID（可選）
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
- `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`: 設定鍵名
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
### 📥 服務器 → 客戶端訊息
#### connection_established
WebSocket 連接建立確認。
```json
{
"type": "connection_established",
"data": {
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"server_time": "2024-12-XX 10:30:00"
}
}
```
#### session_updated
會話更新通知（AI 再次調用時）。
```json
{
"type": "session_updated",
"data": {
"session_id": "new-session-id",
"summary": "根據您的建議，我已修改了錯誤處理邏輯。",
"project_directory": "./my-project",
"timestamp": "2024-12-XX 10:35:00"
}
}
```
#### feedback_received
回饋接收確認。
```json
{
"type": "feedback_received",
"data": {
"session_id": "session-id",
"status": "success",
"message": "回饋已成功接收"
}
}
```
#### status_update
狀態更新通知。
```json
{
"type": "status_update",
"data": {
"status": "FEEDBACK_PROCESSING",
"message": "正在處理您的回饋...",
"progress": 50
}
}
```
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
#### auto_submit_status
自動提交狀態更新。
```json
{
"type": "auto_submit_status",
"data": {
"enabled": true,
"countdown": 25,
"promptId": "prompt_1_1703123456789",
"promptName": "代碼審查提示"
}
}
```
**字段說明**:
- `enabled`: 自動提交是否啟用
- `countdown`: 剩餘倒數時間（秒）
- `promptId`: 當前自動提交提示詞 ID
- `promptName`: 當前自動提交提示詞名稱
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
#### session_history（v2.4.3 增強）
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
會話歷史數據。
```json
{
"type": "session_history",
"data": {
"sessions": [
{
"session_id": "session-1",
"summary": "代碼審查完成",
"status": "completed",
"created_at": "2024-12-13T10:30:00Z",
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
"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"
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
}
],
"stats": {
"total": 10,
"completed": 8,
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
"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
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
}
}
}
```
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
#### 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"
}
}
```
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
#### error
錯誤訊息。
```json
{
"type": "error",
"data": {
"error_code": "VALIDATION_ERROR",
"message": "回饋內容不能為空",
"details": {
"field": "feedback",
"value": ""
}
}
}
```
## 🔧 內部 API
### WebUIManager API
#### create_session()
```python
async def create_session(
self,
summary: str,
project_directory: str
) -> WebFeedbackSession
```
創建新的回饋會話。
#### smart_open_browser()
```python
async def smart_open_browser(self, url: str) -> bool
```
智能開啟瀏覽器，避免重複開啟。
**返回值**:
- `True`: 檢測到活躍標籤頁，未開啟新視窗
- `False`: 開啟了新瀏覽器視窗
### WebFeedbackSession API
#### submit_feedback()
```python
async def submit_feedback(
self,
feedback: str,
images: List[str],
settings: dict
) -> None
```
提交用戶回饋到會話。
#### wait_for_feedback()
```python
async def wait_for_feedback(self, timeout: int = 600) -> dict
```
等待用戶回饋完成。
#### add_websocket()
```python
def add_websocket(self, websocket: WebSocket) -> None
```
添加 WebSocket 連接到會話。
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
### 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]
```
獲取按使用頻率排序的提示詞列表，自動提交提示詞優先顯示。
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
### SessionManager API（v2.4.3 重構增強）
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
#### getCurrentSession()
```python
def getCurrentSession(self) -> dict
```
獲取當前活躍會話信息。
#### getSessionHistory()
```python
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
def getSessionHistory(self, retentionHours: int = 72) -> List[dict]
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
```
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
獲取會話歷史記錄，支援保存期限過濾。
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
#### getSessionStats()
```python
def getSessionStats(self) -> dict
```
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
獲取會話統計信息，包含今日統計和平均時長。
#### 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 元素。
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
### 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
```
更新自動提交設定。
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
## 📊 狀態碼和錯誤碼
### HTTP 狀態碼
- `200 OK`: 請求成功
- `302 Found`: 重定向
- `404 Not Found`: 資源不存在
- `500 Internal Server Error`: 服務器內部錯誤
### WebSocket 錯誤碼
```python
class ErrorCodes:
VALIDATION_ERROR = "VALIDATION_ERROR"
SESSION_NOT_FOUND = "SESSION_NOT_FOUND"
TIMEOUT_ERROR = "TIMEOUT_ERROR"
PROCESSING_ERROR = "PROCESSING_ERROR"
CONNECTION_ERROR = "CONNECTION_ERROR"
```
### 會話狀態
```python
class SessionStatus:
WAITING = "FEEDBACK_WAITING"
PROCESSING = "FEEDBACK_PROCESSING"
SUBMITTED = "FEEDBACK_SUBMITTED"
ERROR = "ERROR"
```
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
### 提示詞狀態
```python
class PromptStatus:
ACTIVE = "active" # 活躍提示詞
AUTO_SUBMIT = "auto_submit" # 自動提交提示詞
ARCHIVED = "archived" # 已歸檔提示詞
```
### 自動提交狀態
```python
class AutoSubmitStatus:
DISABLED = "disabled" # 已停用
ENABLED = "enabled" # 已啟用
COUNTDOWN = "countdown" # 倒數計時中
COMPLETED = "completed" # 已完成提交
```
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
### 音效通知狀態（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" # 停用記錄
```
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
## 🔒 安全考慮
### 輸入驗證
- 回饋內容長度限制：最大 10,000 字符
- 圖片大小限制：單張最大 5MB
- 圖片數量限制：最多 10 張
- 支援的圖片格式：PNG, JPEG, GIF, WebP
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
- 提示詞名稱長度限制：最大 100 字符
- 提示詞內容長度限制：最大 5,000 字符
- 提示詞數量限制：最多 50 個
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
- **音效文件限制（v2.4.3 新增）**：
- 支援格式：MP3, WAV, OGG
- 單個文件最大：2MB
- 自訂音效數量：最多 20 個
- 音效名稱長度：最大 50 字符
- **會話歷史限制（v2.4.3 新增）**：
- 預設保存期限：72 小時
- 最大保存期限：168 小時（7天）
- 單個會話最大用戶訊息數：100 條
📝 新增專案架構文檔
2025-06-10 09:01:53 +08:00
### 資源保護
- WebSocket 連接數限制：每會話最多 5 個連接
- 會話超時自動清理
- 內存使用監控和限制
### 跨域設置
```python
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # 開發環境，生產環境應限制
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
---
📝 更新架構文檔
2025-06-12 22:45:23 +08:00
## 📚 相關文檔
- **[系統架構總覽](./system-overview.md)** - 了解整體架構設計理念和技術棧
- **[組件詳細說明](./component-details.md)** - 深入了解各層組件的具體實現
- **[交互流程文檔](./interaction-flows.md)** - 詳細的用戶交互和系統流程
- **[部署指南](./deployment-guide.md)** - 環境配置和部署最佳實踐
---
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
**版本**: 2.4.3
**最後更新**: 2025年6月14日
📝 更新架構文檔
2025-06-12 22:45:23 +08:00
**維護者**: Minidoracat
**API 版本**: v1
📝 架構文檔更新
2025-06-14 20:10:27 +08:00
**協議支援**: MCP 2.0+, WebSocket, HTTP/1.1, Web Audio API
**v2.4.3 新功能**: 音效通知系統、會話管理重構、智能記憶功能、一鍵複製
**歷史功能**: 自動提交、提示詞管理、會話管理、語系切換優化
Reference in New Issue Copy Permalink