MBE 文档中心

MBE 开发者业务全流程文档

📋 概述

本文档详细描述了 MBE（米塞斯行为引擎）开发者从注册到使用完整功能的业务流程。

流程总览：

注册 → 认证 → 管理专家 → 查看指标 → 检测问题 → 获取建议 → 应用优化 → 审计日志

🚀 完整流程

阶段 0: 服务检查

目的： 确保 MBE 服务正常运行

操作：

# 检查服务健康状态
curl http://localhost:8000/health

Web UI：

  • 访问：http://localhost:8000/
  • API 文档：http://localhost:8000/docs

阶段 1: 注册开发者账户

目的： 创建开发者账户并获取 API Key

API 调用：

POST /api/developer/register
Content-Type: application/json

{
  "username": "mydev",
  "email": "dev@example.com",
  "tier": "free"  # free / pro / enterprise
}

响应示例：

{
  "success": true,
  "developer": {
    "id": "dev_abc123",
    "username": "mydev",
    "email": "dev@example.com",
    "tier": "free",
    "api_key": "mbe_xxxxxxxxxxxx",  // ⚠️ 只显示一次！
    "quota": {
      "max_experts": 3,
      "max_requests_per_day": 100,
      "max_storage_mb": 100
    }
  },
  "important": "请妥善保存您的 API Key，它不会再次显示！"
}

重要提示：

  • ✅ API Key 只显示一次，请立即保存
  • ✅ 默认等级为 free
  • ✅ 注册后自动获得配额限制

服务等级对比：

功能 Free Pro Enterprise
专家数量 3 20 无限
API 调用/天 100 10,000 无限
存储空间 100 MB 1 GB 10 GB
自动应用建议 ❌ ✅ ✅
审计日志查询 3天 3天 30天

阶段 2: API Key 认证

目的： 验证 API Key 并获取账户信息

API 调用：

GET /api/developer/me
X-Developer-Key: mbe_xxxxxxxxxxxx

或使用 Bearer Token：

GET /api/developer/me
Authorization: Bearer mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "developer": {
    "id": "dev_abc123",
    "username": "mydev",
    "email": "dev@example.com",
    "tier": "free",
    "status": "active",
    "created_at": "2026-01-28T10:00:00",
    "last_login": "2026-01-28T10:05:00"
  },
  "quota": {
    "max_experts": 3,
    "used_experts": 0,
    "max_requests_per_day": 100,
    "remaining_requests": 100
  }
}

认证方式：

  1. X-Developer-Key 请求头（推荐）
  2. Authorization: Bearer {api_key}
  3. 兼容模式： 路径参数 developer_id（仅演示账户）

阶段 3: 获取专家列表

目的： 查看开发者拥有的所有专家

API 调用：

GET /api/developer/{developer_id}/experts
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "developer_id": "dev_abc123",
  "experts": [
    {
      "expert_id": "dynamic_expert_001",
      "name": "Expert 001",
      "type": "dynamic",
      "status": "active"
    }
  ],
  "total": 1,
  "quota": {
    "max_experts": 3,
    "used": 1
  }
}

Web UI：

  • 开发者仪表盘：http://localhost:8000/developer/feedback

阶段 4: 注册专家所有权

目的： 将专家绑定到开发者账户

API 调用：

POST /api/developer/{developer_id}/experts/{expert_id}/register?is_public=false
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "message": "专家 dynamic_expert_001 已绑定到您的账户",
  "ownership": {
    "expert_id": "dynamic_expert_001",
    "developer_id": "dev_abc123",
    "created_at": "2026-01-28T10:10:00",
    "is_public": false,
    "shared_with": []
  }
}

注意事项：

  • ⚠️ 不能超过专家配额限制
  • ⚠️ 专家创建后需要注册所有权才能管理
  • ✅ 可以设置专家为公开（is_public=true）

阶段 5: 获取专家表现指标

目的： 查看专家的使用量、性能、质量等指标

API 调用：

GET /api/developer/{developer_id}/experts/{expert_id}/metrics?start_date=2026-01-21&end_date=2026-01-28
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "expert_id": "dynamic_expert_001",
  "metrics": {
    "expert_id": "dynamic_expert_001",
    "period": {
      "start": "2026-01-21T00:00:00",
      "end": "2026-01-28T00:00:00"
    },
    "usage": {
      "total_conversations": 156,
      "unique_users": 45,
      "total_messages": 892
    },
    "performance": {
      "avg_response_time": 3.2,
      "p95_response_time": 5.8,
      "max_response_time": 12.3
    },
    "quality": {
      "switch_rate": 0.08,
      "retry_rate": 0.05,
      "satisfaction_score": 4.2
    },
    "knowledge": {
      "hit_rate": 0.85,
      "avg_relevance_score": 0.78
    }
  },
  "rate_limit": {
    "remaining": 99,
    "limit": 100
  }
}

指标说明：

  • 使用量： 对话数、用户数、消息数
  • 性能： 平均/P95/最大响应时间
  • 质量： 切换率、重试率、满意度
  • 知识库： 命中率、相关性得分

阶段 6: 检测专家问题

目的： 自动检测专家运行中的潜在问题

API 调用：

GET /api/developer/{developer_id}/experts/{expert_id}/issues
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "expert_id": "dynamic_expert_001",
  "issues": [
    {
      "id": "issue_001",
      "type": "slow_response",
      "severity": "HIGH",
      "description": "平均响应时间过长(8.5秒),影响用户体验",
      "detected_at": "2026-01-28T10:15:00",
      "affected_files": ["src/core/engine.py", "src/llm/base.py"]
    },
    {
      "id": "issue_002",
      "type": "high_switch_rate",
      "severity": "MEDIUM",
      "description": "专家切换率较高(25%),用户对初始专家匹配不满意",
      "detected_at": "2026-01-28T10:16:00",
      "affected_files": ["src/knowledge/expert_router.py"]
    }
  ],
  "total": 2
}

问题类型：

  • slow_response - 响应时间过长
  • high_switch_rate - 专家切换率过高
  • low_knowledge_hit_rate - 知识库命中率低
  • low_relevance_score - 检索相关性低
  • knowledge_gap - 知识缺口

阶段 7: 获取优化建议

目的： 获取针对检测到问题的优化建议

API 调用：

GET /api/developer/{developer_id}/experts/{expert_id}/suggestions
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "expert_id": "dynamic_expert_001",
  "suggestions": [
    {
      "id": "sug_001",
      "type": "optimize_index",
      "priority": "HIGH",
      "title": "优化向量索引配置",
      "description": "建议调整索引参数以提升检索速度",
      "auto_applicable": true,
      "estimated_improvement": "响应时间减少15%",
      "affected_files": ["src/core/engine.py"]
    },
    {
      "id": "sug_002",
      "type": "add_content",
      "priority": "MEDIUM",
      "title": "补充知识库内容",
      "description": "建议添加更多相关文档以提升命中率",
      "auto_applicable": false,
      "estimated_improvement": "命中率提升10%"
    }
  ],
  "total": 2,
  "auto_applicable": 1
}

建议类型：

  • optimize_index - 优化索引（可自动应用）
  • update_config - 更新配置（可自动应用）
  • add_content - 添加内容（需手动）
  • update_content - 更新内容（需手动）
  • retrain - 重新训练（需手动）

权限说明：

  • ✅ Free 用户： 只能查看建议，需手动实施
  • ✅ Pro/Enterprise 用户： 可以自动应用建议

阶段 8: 应用优化建议

目的： 自动应用可执行的优化建议（Pro/Enterprise 功能）

API 调用：

POST /api/developer/{developer_id}/experts/{expert_id}/apply-suggestions
X-Developer-Key: mbe_xxxxxxxxxxxx
Content-Type: application/json

{
  "suggestion_ids": ["sug_001", "sug_002"]
}

响应示例：

{
  "success": true,
  "expert_id": "dynamic_expert_001",
  "applied": 1,
  "failed": 0,
  "results": [
    {
      "suggestion_id": "sug_001",
      "status": "applied",
      "message": "建议已应用: 优化向量索引配置"
    }
  ]
}

注意事项：

  • ⚠️ 只有 auto_applicable=true 的建议可以自动应用
  • ⚠️ Free 用户无法使用此功能
  • ✅ 应用后会自动记录到审计日志

阶段 9: 查看开发者仪表盘

目的： 查看所有专家的汇总信息和概览

API 调用：

GET /api/developer/{developer_id}/dashboard
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "developer_id": "dev_abc123",
  "developer_tier": "pro",
  "overview": {
    "total_experts": 5,
    "total_issues": 3,
    "total_suggestions": 8,
    "experts_needing_attention": 2
  },
  "experts": [
    {
      "expert_id": "dynamic_expert_001",
      "health_score": {
        "score": 85,
        "status": "healthy",
        "color": "green"
      },
      "issues_count": 1,
      "suggestions_count": 2
    }
  ],
  "quota": {
    "max_experts": 20,
    "used_experts": 5,
    "max_requests_per_day": 10000
  }
}

Web UI：

  • 仪表盘：http://localhost:8000/developer/feedback

阶段 10: 查看审计日志

目的： 查看开发者的操作历史记录

API 调用：

GET /api/developer/{developer_id}/audit-log?days=7&action=view_metrics
X-Developer-Key: mbe_xxxxxxxxxxxx

响应示例：

{
  "success": true,
  "developer_id": "dev_abc123",
  "period": {
    "start": "2026-01-21",
    "end": "2026-01-28"
  },
  "total": 15,
  "logs": [
    {
      "timestamp": "2026-01-28T10:20:00",
      "developer_id": "dev_abc123",
      "action": "view_metrics",
      "resource_id": "dynamic_expert_001",
      "details": {},
      "ip_address": "192.168.1.100",
      "success": true
    }
  ]
}

查询参数：

  • days - 查询最近多少天（Free/Pro: 最多3天，Enterprise: 最多30天）
  • action - 按操作类型筛选（可选）

记录的操作：

  • view_metrics - 查看指标
  • view_issues - 查看问题
  • view_suggestions - 查看建议
  • apply_suggestion - 应用建议
  • register_expert - 注册专家
  • list_experts - 列出专家

🎯 演示模式

目的： 无需注册即可体验功能

访问方式：

GET /api/developer/demo_developer/dashboard

特点：

  • ✅ 无需 API Key
  • ✅ 可查看所有演示专家
  • ✅ 功能受限（只读）

Web UI：

  • 演示仪表盘：http://localhost:8000/developer/feedback?developer_id=demo_developer

📊 完整流程测试

运行测试脚本：

python scripts/test_developer_workflow.py

测试覆盖：

  1. ✅ 服务健康检查
  2. ✅ 注册开发者账户
  3. ✅ API Key 认证
  4. ✅ 获取专家列表
  5. ✅ 注册专家所有权
  6. ✅ 获取专家指标
  7. ✅ 检测专家问题
  8. ✅ 获取优化建议
  9. ✅ 查看仪表盘
  10. ✅ 查看审计日志
  11. ✅ 演示模式

🔐 权限和安全

认证要求

所有 API 端点（除演示模式外）都需要认证：

X-Developer-Key: mbe_xxxxxxxxxxxx

权限控制

  • ✅ 开发者只能访问自己的专家
  • ✅ 公开专家可以被所有开发者查看
  • ✅ 专家所有权由创建者控制
  • ✅ 所有操作记录到审计日志

速率限制

等级 每日请求限制
Free 100
Pro 10,000
Enterprise 无限

超过限制返回 429 Too Many Requests

🌐 Web UI 访问地址

功能 地址
开发者反馈仪表盘 http://localhost:8000/developer/feedback
任务审批界面 http://localhost:8000/admin/tasks
任务生命周期 http://localhost:8000/admin/lifecycle
API 文档 http://localhost:8000/docs

📝 最佳实践

  1. API Key 管理

    • ✅ 立即保存 API Key（只显示一次）
    • ✅ 不要在代码中硬编码
    • ✅ 使用环境变量存储
    • ✅ 定期轮换（如泄露）

  2. 专家管理

    • ✅ 及时注册专家所有权
    • ✅ 定期查看专家指标
    • ✅ 关注问题检测结果
    • ✅ 及时应用优化建议

  3. 监控和优化

    • ✅ 每日查看仪表盘
    • ✅ 关注健康评分
    • ✅ 优先处理 HIGH 优先级问题
    • ✅ 利用自动应用功能（Pro+）

  4. 审计和合规

    • ✅ 定期查看审计日志
    • ✅ 了解操作历史
    • ✅ 追踪问题处理过程

🐛 常见问题

Q: API Key 丢失怎么办？

A: 目前不支持找回，需要重新注册账户。

Q: 如何升级账户等级？

A: 联系管理员或通过支付系统升级。

Q: 为什么看不到专家指标？

A: 检查：

  1. API Key 是否正确
  2. 专家是否已注册所有权
  3. 是否有足够的 API 调用配额

Q: 如何申请更多配额？

A: 升级到 Pro 或 Enterprise 等级。

📚 相关文档

最后更新： 2026-01-28