MCP/mcp-feedback-enhanced
1
0
Fork 0
mirror of https://github.com/Minidoracat/mcp-feedback-enhanced.git synced 2025-08-10 11:42:26 +08:00
Code Issues Packages Projects Releases Wiki Activity
mcp-feedback-enhanced/docs/architecture/api-reference.md
Minidoracat e6bf5f74ec 📝 更新架構文檔
2025-06-13 17:03:59 +08:00

642 lines
13 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# API 參考文檔
本文檔提供 MCP Feedback Enhanced 的完整 API 參考，包括 MCP 工具、Web API、WebSocket 通信協議和內部 API 接口。
## 📡 MCP 工具 API
MCP Feedback Enhanced 基於 FastMCP 框架實現，提供標準的 MCP 協議支援。
### 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`
#### 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
#### 連接端點
```
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"
}
}
```
#### 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
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
}
}
```
#### 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
錯誤訊息。
```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 連接到會話。
### 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 狀態碼
- `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"
```
### 提示詞狀態
```python
class PromptStatus:
ACTIVE = "active" # 活躍提示詞
AUTO_SUBMIT = "auto_submit" # 自動提交提示詞
ARCHIVED = "archived" # 已歸檔提示詞
```
### 自動提交狀態
```python
class AutoSubmitStatus:
DISABLED = "disabled" # 已停用
ENABLED = "enabled" # 已啟用
COUNTDOWN = "countdown" # 倒數計時中
COMPLETED = "completed" # 已完成提交
```
## 🔒 安全考慮
### 輸入驗證
- 回饋內容長度限制：最大 10,000 字符
- 圖片大小限制：單張最大 5MB
- 圖片數量限制：最多 10 張
- 支援的圖片格式：PNG, JPEG, GIF, WebP
- 提示詞名稱長度限制：最大 100 字符
- 提示詞內容長度限制：最大 5,000 字符
- 提示詞數量限制：最多 50 個
### 資源保護
- WebSocket 連接數限制：每會話最多 5 個連接
- 會話超時自動清理
- 內存使用監控和限制
### 跨域設置
```python
app.add_middleware(
CORSMiddleware,
allow_origins=["*"], # 開發環境，生產環境應限制
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
```
---
## 📚 相關文檔
- **[系統架構總覽](./system-overview.md)** - 了解整體架構設計理念和技術棧
- **[組件詳細說明](./component-details.md)** - 深入了解各層組件的具體實現
- **[交互流程文檔](./interaction-flows.md)** - 詳細的用戶交互和系統流程
- **[部署指南](./deployment-guide.md)** - 環境配置和部署最佳實踐
---
**版本**: 2.4.0
**最後更新**: 2025年6月
**維護者**: Minidoracat
**API 版本**: v1
**協議支援**: MCP 2.0+, WebSocket, HTTP/1.1
**新功能**: 自動提交、提示詞管理、會話管理、語系切換優化
Reference in New Issue View Git Blame Copy Permalink