MBE Desktop 与 MBE 后台 API 对齐检查报告

概述

本文档对比了 MBE Desktop 前端调用的 API 与 MBE 后台（mises-behavior-engine）定义的 API，检查两者是否对齐。

检查结果总结

✅ 基本对齐 - 主要 API 端点都已对齐，但存在一些细节差异需要注意。

详细对比

1. 知识库列表

前端调用 (knowledgeService.ts):

GET /admin/knowledge/

后端定义 (knowledge.py):

@router.get("/")
async def list_knowledge_bases():

响应格式:

后端返回: { "knowledge_bases": [...], "total": N }
前端处理: data?.knowledge_bases || data || []

✅ 对齐状态: ✅ 已对齐

2. 创建知识库

前端调用:

POST /admin/knowledge/create
Body: CreateKBRequest {
  name: string
  description?: string
  chunk_size?: number
  chunk_overlap?: number
  enable_embedding?: boolean
  developer_id?: string
  domain?: string
  kb_type?: string
}

后端定义:

@router.post("/create")
async def create_knowledge_base(request: CreateKBRequest):

请求模型对比:

✅ name - 对齐
✅ description - 对齐
✅ chunk_size - 对齐
✅ chunk_overlap - 对齐
✅ enable_embedding - 对齐
✅ developer_id - 对齐
✅ domain - 对齐
✅ kb_type - 对齐

✅ 对齐状态: ✅ 已对齐

3. 获取知识库详情

前端调用:

GET /admin/knowledge/{kb_id}

后端定义:

@router.get("/{kb_id}")
async def get_knowledge_base(kb_id: str):

✅ 对齐状态: ✅ 已对齐

4. 更新知识库

前端调用:

PUT /admin/knowledge/{kb_id}
Body: {
  name?: string
  description?: string
  chunk_size?: number
  chunk_overlap?: number
  enable_embedding?: boolean
}

后端定义:

@router.put("/{kb_id}")
async def update_knowledge_base(kb_id: str, request: UpdateKBRequest):

✅ 对齐状态: ✅ 已对齐

5. 删除知识库

前端调用:

DELETE /admin/knowledge/{kb_id}

后端定义:

@router.delete("/{kb_id}")
async def delete_knowledge_base(kb_id: str):

✅ 对齐状态: ✅ 已对齐

6. 上传文件

前端调用:

POST /admin/knowledge/upload/{kb_id}
Content-Type: multipart/form-data
FormData: {
  file: File
  chunk_size?: number
  chunk_overlap?: number
}

后端定义:

@router.post("/upload/{kb_id}")
async def upload_file(
    kb_id: str,
    file: UploadFile = File(...),
    chunk_size: Optional[int] = Form(None),
    chunk_overlap: Optional[int] = Form(None),
):

✅ 对齐状态: ✅ 已对齐

7. 批量上传文件

前端调用:

POST /admin/knowledge/upload-batch/{kb_id}
Content-Type: multipart/form-data
FormData: {
  files: File[]
}

后端定义:

@router.post("/upload-batch/{kb_id}")
async def upload_files_batch(
    kb_id: str,
    files: List[UploadFile] = File(...),
):

✅ 对齐状态: ✅ 已对齐

8. 导入 URL 内容

前端调用:

POST /admin/knowledge/import-url/{kb_id}
Body: {
  url: string
}

后端定义:

@router.post("/import-url/{kb_id}")
async def import_url_content(
    kb_id: str,
    request: ImportURLRequest,
):

✅ 对齐状态: ✅ 已对齐

9. 获取推荐书籍

前端调用:

GET /admin/knowledge/{kb_id}/recommended-books

后端定义:

@router.get("/{kb_id}/recommended-books")
async def get_recommended_books(kb_id: str):

✅ 对齐状态: ✅ 已对齐

10. 搜索推荐书籍

前端调用:

POST /admin/knowledge/{kb_id}/search-books

后端定义:

@router.post("/{kb_id}/search-books")
async def search_books_for_kb(kb_id: str):

✅ 对齐状态: ✅ 已对齐

数据模型对比

KnowledgeBase 接口

前端定义 (knowledgeService.ts):

interface KnowledgeBase {
  id: string
  name: string
  description: string
  status: 'pending' | 'processing' | 'ready' | 'error'
  error_message?: string
  source_file?: string
  file_type?: string
  language?: string
  chunk_count?: number
  char_count?: number
  page_count?: number
  created_at: string
  updated_at: string
  config?: {
    chunk_size: number
    chunk_overlap: number
    enable_embedding: boolean
  }
  suggested_expert?: {
    name: string
    description: string
    keywords: string[]
    greeting: string
  }
  quality_score?: number
  quality_level?: string
  expert_used?: string
  processing_confidence?: number
  processing_time?: number
  moe?: {
    expert_used: string
    processing_confidence: number
    processing_time: number
    use_moe: boolean
  }
  authority_score?: number
  authority_level?: string
  authority_details?: {
    recommended_books?: Array<{...}>
    completeness?: {...}
  }
}

后端返回 (从 knowledge_manager.py 的 KnowledgeBase 模型):

✅ 基本字段对齐
✅ MOE 信息对齐
✅ 权威性评估信息对齐

⚠️ 注意: 后端可能返回更多字段，前端使用可选字段处理，兼容性良好。

潜在问题

1. 响应格式不一致

问题: 某些 API 的响应格式可能不完全一致

示例:

列表 API: 后端返回 { "knowledge_bases": [...], "total": N }
前端处理: data?.knowledge_bases || data || [] ✅ 已兼容

建议: 前端已做兼容处理，无需修改。

2. 错误处理

前端: 使用统一的错误处理系统 (useErrorHandler) 后端: 使用 FastAPI 的标准 HTTP 异常

✅ 对齐状态: ✅ 已对齐（前端已适配）

3. 认证方式

前端:

headers: token ? { Authorization: `Bearer ${token}` } : {}

后端:

# 使用依赖注入检查认证
# 从 Request 中获取 Authorization header

✅ 对齐状态: ✅ 已对齐

未使用的后端 API

以下后端 API 在前端尚未使用（可能是未来功能）：

POST /admin/knowledge/{kb_id}/reprocess - 重新处理知识库
POST /admin/knowledge/{kb_id}/ai-name - AI 生成名称
POST /admin/knowledge/import-chunks/{kb_id} - 导入分块
POST /admin/knowledge/{kb_id}/rebuild-vectors - 重建向量
GET /admin/knowledge/{kb_id}/vector-quality - 向量质量检查
POST /admin/knowledge/search - 搜索知识库内容
GET /admin/knowledge/search/context - 搜索上下文
POST /admin/knowledge/{kb_id}/test-quality - 测试质量
POST /admin/knowledge/expert/validate - 验证专家
POST /admin/knowledge/expert/auto-optimize - 自动优化专家
GET /admin/knowledge/expert/list - 专家列表
POST /admin/knowledge/expert/publish - 发布专家
DELETE /admin/knowledge/expert/{expert_id} - 删除专家
POST /admin/knowledge/expert/{expert_id}/re-optimize - 重新优化专家
POST /admin/knowledge/expert/test-match - 测试匹配
GET /admin/knowledge/audit/stats - 审计统计
GET /admin/knowledge/audit/logs - 审计日志
GET /admin/knowledge/wizard/domains - 向导：领域列表
GET /admin/knowledge/wizard/architecture/{domain} - 向导：架构
GET /admin/knowledge/wizard/checklist/{domain} - 向导：检查清单
POST /admin/knowledge/wizard/gap-analysis - 向导：差距分析
POST /admin/knowledge/wizard/ai-design - 向导：AI 设计

说明: 这些 API 可能是：

管理后台专用功能
未来计划的功能
高级功能（当前前端不需要）

总结

✅ 已对齐的功能

✅ 知识库 CRUD（创建、读取、更新、删除）
✅ 文件上传（单文件和批量）
✅ URL 导入
✅ 推荐书籍功能
✅ 数据模型兼容

⚠️ 需要注意的点

响应格式: 前端已做兼容处理，无需担心
错误处理: 前端统一错误处理系统已适配后端
认证: Bearer Token 方式已对齐

📋 建议

当前状态: ✅ 核心功能已完全对齐，可以正常使用
未来扩展: 如需使用后端的高级功能（如专家管理、向导等），需要在前端添加对应调用
文档: 建议维护 API 文档，确保前后端同步更新

结论

MBE Desktop 与 MBE 后台的核心 API 已对齐 ✅

所有核心功能（知识库管理、文件上传、URL 导入）都已对齐
数据模型兼容性良好
错误处理和认证方式已适配
前端代码具有良好的容错性

无需立即修改，可以正常使用。