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

642 lines
13 KiB
Markdown
Raw 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
#### 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（可選）
📝 新增專案架構文檔
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`: 當前自動提交提示詞名稱
#### 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
}
}
}
```
📝 新增專案架構文檔
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]
```
獲取按使用頻率排序的提示詞列表，自動提交提示詞優先顯示。
### 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
```
更新自動提交設定。
📝 新增專案架構文檔
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-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-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-13 17:03:59 +08:00
**版本**: 2.4.0
**最後更新**: 2025年6月
📝 更新架構文檔
2025-06-12 22:45:23 +08:00
**維護者**: Minidoracat
**API 版本**: v1
**協議支援**: MCP 2.0+, WebSocket, HTTP/1.1
📝 更新架構文檔
2025-06-13 17:03:59 +08:00
**新功能**: 自動提交、提示詞管理、會話管理、語系切換優化
Reference in New Issue Copy Permalink