0 Fork 0

Files

T

qyyfw 67c3270aad feat: 方案二详细实施计划 - 5 Phase 20周完整拆解

2026-06-27 10:21:15 +00:00

27 KiB

Raw Permalink Blame History

方案二：稳扎稳打 — 详细实施计划

定位: 核心服务全部自研，基础设施用开源，架构完全自主可控周期: 20 周（5 个 Phase，每 Phase 4 周） 开发工具: MiMo Code（Quest Mode + Agent Mode + AGENTS.md） 技术栈: Go(核心) + Python(AI) + TypeScript(前端) + PostgreSQL + Redis + Kafka + Milvus

总览：5 Phase 里程碑

Week  1-4   Phase 1: 基座搭建（Auth + DB + Gateway + 项目骨架）
Week  5-8   Phase 2: 核心引擎（LLM Router + Billing + Metering）
Week  9-12  Phase 3: 能力治理（Registry + Skills + Dashboard）
Week 13-16  Phase 4: 生态扩展（IM Bot + MCP + Agent + ACP）
Week 17-20  Phase 5: 集成上线（测试 + 部署 + 监控 + 运营）

         Phase 1        Phase 2        Phase 3        Phase 4        Phase 5
    ┌──────────────┬──────────────┬──────────────┬──────────────┬──────────────┐
    │ 域基础设施    │ 核心引擎      │ 能力治理      │ 生态扩展      │ 集成上线      │
    │              │              │              │              │              │
    │ ✅ 项目骨架   │ ✅ LLM Router │ ✅ Registry  │ ✅ IM Bot GW │ ✅ 全链路测试 │
    │ ✅ Keycloak  │ ✅ Billing    │ ✅ Skills 市场│ ✅ MCP Hub   │ ✅ K8s 部署   │
    │ ✅ APISIX    │ ✅ Metering   │ ✅ Dashboard │ ✅ LangFlow  │ ✅ 监控告警   │
    │ ✅ DB Schema │ ✅ OpenAPI GW │ ✅ Admin     │ ✅ ACP 协议  │ ✅ 文档上线   │
    └──────────────┴──────────────┴──────────────┴──────────────┴──────────────┘
         ▲               ▲               ▲               ▲               ▼
         └───────────────┴───────────────┴───────────────┴───── 可运行交付 ─┘

Phase 1：基座搭建（Week 1-4）

目标: 项目可运行，基础设施就绪，Auth + Gateway + DB 全部跑通 结束标志: docker-compose up 启动所有服务，可注册用户、登录、通过网关调用 API

1.1 项目骨架初始化（Day 1-2）

MiMo Code Quest Prompt:

初始化 AI PaaS 平台项目骨架。

项目名: ai-paas-platform
Monorepo 结构 (pnpm workspace):
- packages/web (React + TypeScript + Ant Design Pro)
- packages/admin (React + TypeScript + Ant Design Pro)
- services/gateway (Go)
- services/auth (Go)
- services/billing (Go)
- services/metering (Go)
- services/registry (Go)
- services/llm-router (Go)
- services/skills (Go)
- services/im-gateway (Go)
- infra/keycloak (Docker)
- infra/postgresql (Docker + migrations)
- infra/redis (Docker)
- infra/kafka (Docker)
- infra/milvus (Docker)
- infra/apisix (Docker)
- deploy/docker-compose.yml

生成:
1. 根目录 Makefile, docker-compose.yml, .env.example
2. 各 Go 服务的基础 main.go + health endpoint
3. 各 React 应用的基础 vite 配置
4. PostgreSQL migration 初始脚本 (001_init.sql)
5. .mimocode/AGENTS.md 配置文件

交付物:

Monorepo 目录结构
docker-compose.yml 一键启动所有基础设施
各服务 health endpoint 可访问
AGENTS.md 配置完成

1.2 数据库 Schema 设计（Day 3-5）

MiMo Code Quest Prompt:

设计 AI PaaS 平台的 PostgreSQL 数据库 Schema。

核心表:
1. tenants (租户) - id, name, plan, credit_balance, status, created_at
2. users (用户) - id, tenant_id, email, name, role, api_key_hash, status
3. capabilities (能力) - id, tenant_id, name, type, version, endpoint, protocol, status, pricing_config
4. capability_versions (能力版本) - id, capability_id, version, endpoint, changelog, status
5. credit_transactions (Credit 流水) - id, tenant_id, type, amount, balance_after, trace_id, idempotency_key
6. token_usage (Token 用量) - id, tenant_id, capability_id, model, prompt_tokens, completion_tokens, cost_credits, trace_id (按月分区)
7. subscriptions (订阅) - id, tenant_id, plan, credits_included, credits_used, period_start, period_end, status
8. skills (技能) - id, tenant_id, name, description, pricing_model, price_credits, status
9. skill_purchases (技能购买) - id, user_id, skill_id, amount_credits
10. im_sessions (IM 会话) - id, tenant_id, platform, user_identifier, bot_id, status

要求:
- 所有表启用 RLS (Row Level Security)，策略基于 tenant_id
- 所有表有 created_at/updated_at
- token_usage 按月分区
- 外键关系完整
- 索引覆盖高频查询

交付物:

001_init.sql 完整建表脚本
RLS 策略配置
种子数据脚本 (开发环境)

1.3 Keycloak 认证服务（Day 6-10）

MiMo Code Quest Prompt:

部署 Keycloak 并实现多租户认证适配器。

1. Docker 部署 Keycloak 25.x
2. 配置 Realm: ai-paas
3. 配置 Clients:
   - web-app (PKCE, React 前端)
   - admin-app (PKCE, 管理后台)
   - api-service (Client Credentials, 服务间调用)
4. 实现 Go 适配器 (services/auth):
   - JWT 验证中间件
   - API Key 验证 (查 DB)
   - 租户上下文提取 (从 JWT claim 提取 tenant_id)
   - RBAC 角色: owner, admin, developer, user
5. 实现用户注册/登录 API:
   - POST /api/v1/auth/register (邮箱+密码)
   - POST /api/v1/auth/login (返回 JWT)
   - POST /api/v1/auth/refresh
   - GET  /api/v1/auth/me (当前用户信息)
6. APISIX 集成: jwt-auth 插件配置

交付物:

Keycloak Docker 配置
Go auth 中间件 (JWT + API Key)
Auth API (注册/登录/刷新)
APISIX jwt-auth 插件配置
RBAC 角色体系

1.4 Apache APISIX 网关（Day 11-14）

MiMo Code Quest Prompt:

部署 Apache APISIX 3.15+ 并配置核心插件。

1. Docker 部署 APISIX + etcd
2. 配置以下插件:
   - jwt-auth: JWT 令牌验证
   - key-auth: API Key 验证
   - limit-count: 按租户限流 (1000/min)
   - limit-req: 请求限速
   - api-breaker: 熔断保护
   - proxy-rewrite: 动态路由
   - prometheus: 指标采集
   - cors: 跨域配置
3. 初始路由配置:
   - /api/v1/auth/* → auth-service:8081
   - /api/v1/capabilities/* → registry-service:8082
   - /api/v1/llm/* → llm-router:8083
   - /api/v1/billing/* → billing-service:8084
   - /api/v1/skills/* → skills-service:8085
   - /api/v1/admin/* → admin-service:8086
4. 实现动态路由更新机制 (通过 etcd 监听)

交付物:

APISIX Docker 配置
插件配置文件
初始路由表
动态路由更新机制

Phase 2：核心引擎（Week 5-8）

目标: LLM Router + 计费引擎 + 用量追踪全部跑通，可以调用 LLM 并计费 结束标志: 用户通过 API Key 调用 LLM，自动扣费，用量可查

2.1 LLM Provider Router（Day 15-20）

MiMo Code Quest Prompt:

实现 LLM Provider Router 服务 (Go)。

功能:
1. 多平台 LLM 对接 (OpenAI 兼容格式):
   - DeepSeek: https://api.deepseek.com/v1
   - 千问: https://dashscope.aliyuncs.com/compatible-mode/v1
   - 豆包: https://ark.cn-beijing.volces.com/api/v3
   - 百度: 适配层封装为 OpenAI 格式
   - 元宝: https://api.yuanbao.tencent.com/v1
   - 智谱: https://open.bigmodel.cn/api/paas/v4
   - 本地 Ollama: http://localhost:11434/v1

2. 智能路由:
   - 按用户选择路由
   - 按成本自动选择最便宜模型
   - 按延迟自动选择最快模型
   - 故障转移: 主模型不可用时自动切换

3. API:
   - POST /v1/chat/completions (OpenAI 兼容)
   - GET  /api/v1/models (可用模型列表)
   - GET  /api/v1/providers (提供商状态)

4. 数据模型:
   - providers: id, name, base_url, api_key_encrypted, models_json, status, priority
   - model_routing_rules: model, provider_id, priority, is_default

5. 配置:
   - YAML 配置文件 + DB 动态更新
   - API Key 加密存储 (AES-256)
   - 连接池管理
   - 超时配置 (默认 30s)

交付物:

llm-router Go 服务
7 个平台适配器
智能路由逻辑
故障转移机制
OpenAI 兼容 API

2.2 Token 计费引擎（Day 21-27）

MiMo Code Quest Prompt:

实现 Token 计费引擎 (Go + Redis Lua)。

核心设计原则:
- 先扣后服: 先扣减余额，再允许调用
- 幂等: 通过 idempotency_key 防重复扣费
- 原子: Redis Lua 脚本保证原子性
- 可审计: 每笔变动有 trace_id

Credit 模型:
- 1 Credit = 1000 tokens (默认)
- 不同模型有系数: deepseek-chat=1.0, deepseek-reasoner=2.0, gpt-4o=10.0

Redis Lua 脚本 (metering.lua):
1. 幂等检查 (billing:idempotency:{tenant}:{key})
2. 余额检查 (billing:balance:{tenant})
3. 扣减余额 (DECRBY)
4. 记录幂等结果 (SET + 24h TTL)
5. 更新今日统计 (billing:daily:{tenant}:{date})

Go 服务 (services/billing):
- POST /api/v1/billing/meter (实时计量，调用 Lua)
- POST /api/v1/billing/topup (充值)
- GET  /api/v1/billing/balance (查询余额)
- GET  /api/v1/billing/transactions (流水查询)
- POST /api/v1/billing/subscribe (订阅管理)
- GET  /api/v1/billing/subscription (订阅状态)

订阅套餐:
- Free: ¥0/月, 100 Credits, 2 QPS
- Pro: ¥99/月, 50000 Credits, ¥0.01/Credit 超出, 20 QPS
- Team: ¥499/月, 300000 Credits, ¥0.008/Credit 超出, 100 QPS

Redis Key 设计:
- billing:balance:{tenant_id} → String (毫 Credit)
- billing:idempotency:{tenant_id}:{key} → Hash
- billing:daily:{tenant_id}:{YYYY-MM-DD} → Hash
- billing:subscription:{tenant_id} → Hash

交付物:

metering.lua 脚本
billing-service Go 服务
计费 API (6 个接口)
订阅套餐配置
单元测试 (Lua + Go)

2.3 用量追踪 Kafka → PostgreSQL（Day 28-32）

MiMo Code Quest Prompt:

实现用量追踪服务 (Go)。

架构:
LLM Router → Kafka Topic (usage.events) → Metering Consumer → PostgreSQL

Kafka Topic:
- topic: usage.events
- partition_key: tenant_id
- retention: 7d

Consumer (services/metering):
1. 消费 usage.events
2. 写入 token_usage 表 (按月分区)
3. 更新 tenant_balances 表 (从 Redis 同步)
4. 异常处理: 消费失败重试 3 次后进入死信队列

API:
- GET /api/v1/usage/summary?period=daily&date=2026-06-27 (用量汇总)
- GET /api/v1/usage/detail?start=...&end=... (用量明细)
- GET /api/v1/usage/by-model (按模型统计)
- GET /api/v1/usage/by-capability (按能力统计)

PostgreSQL 表:
- token_usage (按月分区，不可变)
- tenant_balances (实时同步)
- usage_summaries (预聚合，每小时刷新)

交付物:

Kafka producer (在 LLM Router 中)
metering-service Go 服务
Consumer 逻辑
用量查询 API
预聚合定时任务

2.4 OpenAPI 网关（Day 33-35）

MiMo Code Quest Prompt:

实现平台 OpenAPI 网关 (Go)。

功能:
1. 对外暴露统一 OpenAI 兼容 API:
   - POST /v1/chat/completions
   - GET  /v1/models
   - POST /v1/embeddings
2. 内部路由到 LLM Router
3. 请求拦截链:
   - API Key 验证 → 租户上下文 → 余额检查 → 调用 LLM Router → 计费扣减 → 返回结果
4. 流式响应支持 (SSE)
5. 用量上报 (异步发 Kafka)

API:
- POST /v1/chat/completions (OpenAI 兼容，对外入口)
- POST /v1/capabilities/{id}/invoke (能力调用)
- GET  /v1/capabilities (能力列表)

交付物:

openapi-gateway Go 服务
OpenAI 兼容 API
流式 SSE 支持
请求拦截链

Phase 3：能力治理（Week 9-12）

目标: 能力注册中心 + Skills 市场 + 用户 Dashboard + 管理后台 结束标志: 用户可在 Dashboard 管理能力、购买技能、查看用量

3.1 Capability Registry（Day 36-42）

MiMo Code Quest Prompt:

实现能力注册中心 (Go + gRPC/REST)。

功能:
1. 能力 CRUD:
   - POST   /api/v1/capabilities (注册)
   - DELETE /api/v1/capabilities/{id} (注销)
   - GET    /api/v1/capabilities (列表，支持 type/status/tags 过滤)
   - GET    /api/v1/capabilities/{id} (详情)
   - PUT    /api/v1/capabilities/{id} (更新)
   - POST   /api/v1/capabilities/{id}/versions (发布新版本)

2. 能力类型:
   - agent: AI 智能体
   - mcp: MCP 服务
   - skill: 技能
   - llm: LLM 提供商
   - custom: 自定义 OpenAPI 应用

3. 元数据:
   - name, type, version, description, tags
   - endpoint (调用地址)
   - protocol (rest/grpc/websocket)
   - pricing_config (计费配置)
   - dependencies (依赖的其他能力)
   - status: active / deprecated / beta

4. 服务发现:
   - 按类型查询
   - 按标签查询
   - 按状态过滤

5. gRPC 接口 (服务间调用):
   - RegisterCapability
   - DeregisterCapability
   - GetCapability
   - ListCapabilities
   - HealthCheck

交付物:

registry-service Go 服务
REST API (6 个接口)
gRPC 接口 (5 个方法)
能力发现/查询
版本管理

3.2 Skills 市场（Day 43-47）

MiMo Code Quest Prompt:

实现 Skills 市场服务 (Go)。

功能:
1. 技能管理:
   - POST   /api/v1/skills (发布技能)
   - GET    /api/v1/skills (市场列表，支持搜索/分类/排序)
   - GET    /api/v1/skills/{id} (技能详情)
   - PUT    /api/v1/skills/{id} (更新)
   - DELETE /api/v1/skills/{id} (下架)

2. 技能购买:
   - POST /api/v1/skills/{id}/purchase (购买，扣 Credit)
   - GET  /api/v1/skills/purchased (已购列表)
   - 扣费通过 Billing Engine API

3. 计费模式:
   - per_call: 每次调用扣费
   - per_token: 按 Token 扣费
   - subscription: 订阅制
   - free: 免费

4. 分成:
   - 平台抽成 25%
   - 开发者分成 75%
   - 预留 skill_earnings 表

5. 搜索:
   - PostgreSQL 全文搜索 (中文分词: zhparser)
   - 按分类、标签、评分排序

交付物:

skills-service Go 服务
技能 CRUD API
购买流程 (调用 Billing)
全文搜索
分成逻辑 (预留)

3.3 用户 Dashboard（Day 48-54）

MiMo Code Quest Prompt:

实现用户 Dashboard (React + TypeScript + Ant Design Pro)。

页面:
1. 首页概览:
   - Credit 余额 + 充值按钮
   - 今日/本月用量图表 (ECharts)
   - 快捷操作 (创建能力、浏览市场)

2. API Key 管理:
   - 创建/删除 API Key
   - Key 使用统计

3. 用量详情:
   - 按日/周/月图表
   - 按模型/能力分类统计
   - 导出 CSV

4. 账单中心:
   - Credit 流水记录
   - 订阅管理 (升级/降级/取消)
   - 充值历史

5. 我的能力:
   - 已创建的能力列表
   - 已购买的技能

6. 设置:
   - 个人信息
   - 通知偏好

技术:
- React 18 + TypeScript + Ant Design Pro 6
- ECharts 图表
- React Query 数据管理
- React Router 路由

交付物:

web React 应用
6 个页面
API 对接
响应式设计

3.4 管理后台（Day 55-58）

MiMo Code Quest Prompt:

实现管理后台 (React + TypeScript + Ant Design Pro)。

页面:
1. 仪表盘:
   - 总用户数、总租户数、总 API 调用量
   - 收入统计
   - 系统状态

2. 用户管理:
   - 用户列表 (搜索/过滤/分页)
   - 用户详情
   - 封禁/解封

3. 租户管理:
   - 租户列表
   - 租户详情 (订阅/用量/余额)
   - 调整余额

4. 能力审核:
   - 待审核能力列表
   - 审核通过/拒绝

5. 系统配置:
   - LLM 提供商配置
   - 订阅套餐配置
   - 全局限流配置

6. 监控:
   - API 调用趋势
   - 错误率
   - 响应时间

交付物:

admin React 应用
6 个管理页面
RBAC 权限控制

Phase 4：生态扩展（Week 13-16）

目标: IM Bot + MCP + Agent + ACP 全部接入 结束标志: 用户可通过微信/QQ 与 AI 对话，可使用 MCP 工具，可创建 Agent

4.1 IM Bot 网关（Day 59-65）

MiMo Code Quest Prompt:

实现 IM Bot 网关 (Go)。

功能:
1. 多平台适配器:
   - 微信 (通过 LangBot/OpenClaw 协议)
   - QQ (通过 go-cqhttp 协议)
   - 钉钉 (通过钉钉开放平台 API)

2. 统一路由:
   - 消息接收 → 平台识别 → 上下文注入 → 调用 LLM Router → 回复
   - 会话管理 (Redis 存储上下文)

3. API:
   - POST /api/v1/im/callback/{platform} (平台回调)
   - GET  /api/v1/im/sessions (会话列表)
   - GET  /api/v1/im/sessions/{id}/messages (消息历史)

4. 配置:
   - 每个平台独立配置 (token, secret, etc.)
   - 每个租户独立的 bot 实例

5. 消息格式:
   - 文本/图片/文件
   - Markdown 渲染
   - 按钮交互

交付物:

im-gateway Go 服务
微信适配器 (集成 LangBot)
QQ 适配器
钉钉适配器
会话管理

4.2 MCP Hub 集成（Day 66-68）

MiMo Code Quest Prompt:

集成 mcp-hub 开源服务。

1. Docker 部署 mcp-hub
2. 与 Capability Registry 联动:
   - MCP Server 注册时自动在 Registry 创建 capability 记录
   - Registry 中 MCP 类型能力自动同步到 mcp-hub
3. API 代理:
   - /api/v1/mcp/servers → mcp-hub API
   - /api/v1/mcp/tools → mcp-hub 工具列表
   - /api/v1/mcp/call → mcp-hub 工具调用 (经过计费)
4. 计费集成:
   - MCP 工具调用经过 Billing Engine 扣费

交付物:

mcp-hub Docker 配置
Registry 联动逻辑
MCP API 代理
计费集成

4.3 LangFlow Agent 集成（Day 69-73）

MiMo Code Quest Prompt:

集成 LangFlow 开源服务。

1. Docker 部署 LangFlow
2. 与 Capability Registry 联动:
   - LangFlow Flow 发布时自动在 Registry 创建 capability 记录
   - 支持 Flow 版本管理
3. API 代理:
   - /api/v1/agent/flows → LangFlow Flow 列表
   - /api/v1/agent/flows/{id}/run → 运行 Flow (经过计费)
   - /api/v1/agent/flows/{id}/chat → 流式对话 (SSE)
4. 计费集成:
   - Agent 调用经过 Billing Engine 扣费
5. 用户界面:
   - Dashboard 中嵌入 LangFlow 编辑器 (iframe)
   - Flow 管理页面

交付物:

LangFlow Docker 配置
Registry 联动逻辑
Agent API 代理
计费集成

4.4 ACP 协议基础（Day 74-77）

MiMo Code Quest Prompt:

实现 ACP (Agent Communication Protocol) 基础。

1. 协议定义:
   - Agent 间消息格式 (JSON)
   - 消息类型: request, response, notification, error
   - 路由: 基于 agent_id 寻址

2. 消息总线:
   - 基于 Kafka 的 Agent 消息队列
   - topic: agent.messages.{agent_id}
   - 支持同步/异步通信

3. API:
   - POST /api/v1/acp/send (发送消息)
   - GET  /api/v1/acp/messages (接收消息)
   - GET  /api/v1/acp/agents (已注册 Agent 列表)

4. 安全:
   - Agent 间通信需要认证
   - 消息签名验证

交付物:

ACP 协议定义
消息总线实现
ACP API
安全机制

Phase 5：集成上线（Week 17-20）

目标: 全链路测试 + 生产部署 + 监控 + 文档 结束标志: 平台可在生产环境运行，有完整文档

5.1 全链路测试（Day 78-83）

MiMo Code Quest Prompt:

编写 AI PaaS 平台的全链路测试。

1. 单元测试:
   - 各 Go 服务核心逻辑
   - Redis Lua 脚本测试
   - TypeScript 前端组件测试

2. 集成测试:
   - Auth → LLM Router → Billing 完整流程
   - Capability 注册 → 调用 → 计费流程
   - Skills 购买 → 使用 → 分成流程

3. E2E 测试:
   - 用户注册 → 登录 → 创建 API Key → 调用 LLM → 查看用量
   - 管理员登录 → 审核能力 → 查看统计

4. 压力测试:
   - LLM Router 并发 (100 QPS)
   - Billing Engine 并发 (1000 TPS)
   - API Gateway 压力 (500 RPS)

5. 测试工具:
   - Go: testing + testify
   - TypeScript: vitest + playwright
   - 压力: k6

交付物:

单元测试覆盖率 > 80%
集成测试套件
E2E 测试脚本
压力测试报告

5.2 生产部署（Day 84-88）

MiMo Code Quest Prompt:

准备 AI PaaS 平台的生产部署配置。

1. Docker Compose (单机部署):
   - 所有服务容器化
   - 环境变量配置
   - 健康检查
   - 自动重启

2. Kubernetes (集群部署):
   - Helm Chart 编写
   - Deployment + Service + Ingress
   - ConfigMap + Secret
   - HPA 自动扩缩容
   - PDB (Pod Disruption Budget)

3. 数据库:
   - PostgreSQL 备份策略 (pg_dump 每日)
   - Redis 持久化配置
   - Kafka 备份

4. 域名 + SSL:
   - Nginx Ingress 配置
   - Let's Encrypt 自动证书

5. 环境区分:
   - dev: docker-compose
   - staging: k8s namespace
   - production: k8s namespace

交付物:

docker-compose.prod.yml
Helm Chart
部署脚本
环境配置模板

5.3 监控告警（Day 89-91）

MiMo Code Quest Prompt:

配置 AI PaaS 平台的监控告警系统。

1. Prometheus:
   - 各服务 metrics 端点
   - 自定义指标:
     - llm_router_request_total (by provider, model, status)
     - billing_credit_deduction_total (by tenant)
     - api_gateway_request_duration_seconds
   - 采集配置

2. Grafana:
   - Dashboard 配置:
     - 平台总览 (请求数/错误率/延迟)
     - LLM Router (各提供商状态/延迟)
     - Billing (收入/扣费趋势)
     - 用户活跃度
   - 告警规则

3. 告警:
   - 错误率 > 5% → 告警
   - 延迟 P99 > 5s → 告警
   - 余额 < 阈值 → 通知用户
   - 服务不可用 → 立即告警

4. 日志:
   - 结构化日志 (JSON)
   - 日志级别: debug/info/warn/error
   - 集中收集 (Loki 或 ELK)

交付物:

Prometheus 配置
Grafana Dashboard JSON
告警规则
日志配置

5.4 文档上线（Day 92-95）

MiMo Code Quest Prompt:

编写 AI PaaS 平台的完整文档。

1. API 文档:
   - OpenAPI 3.0 规范 (api-spec.yaml)
   - 每个接口的详细说明
   - 请求/响应示例
   - 错误码列表

2. 开发者文档:
   - 快速开始指南
   - 认证说明 (JWT + API Key)
   - SDK 使用示例 (Python/Go/TypeScript)
   - MCP Server 接入指南
   - Agent 发布指南

3. 运维文档:
   - 部署指南
   - 配置说明
   - 故障排查
   - 备份恢复

4. 架构文档:
   - 系统架构图
   - 数据流图
   - 数据库 ER 图
   - 部署架构图

5. 用户文档:
   - 注册/登录指南
   - API Key 使用指南
   - 用量查看指南
   - 订阅管理指南

交付物:

API 文档 (OpenAPI 3.0)
开发者文档站
运维文档
架构文档
用户文档

MiMo Code 核心配置 (.mimocode/AGENTS.md)

# AI PaaS Platform

## 架构
- Go 后端服务 (API Gateway, LLM Router, Billing, Registry, Metering, Skills, IM Gateway)
- Python AI 服务 (LangFlow, MCP Hub)
- TypeScript 前端 (React + Ant Design Pro: web + admin)
- Infrastructure: PostgreSQL + Redis + Kafka + Milvus + Keycloak + APISIX

## 技术栈
- Go 1.22+ (高服务: 网关, 路由, 计费, 注册中心)
- Python 3.11+ (AI 服务: LangFlow, MCP)
- TypeScript 5+ (前端: React 18, Ant Design Pro 6, ECharts)
- PostgreSQL 16 (主数据库, RLS 多租户隔离)
- Redis 7 (缓存 + Lua 原子计费)
- Kafka 3.x (事件总线: 用量上报)
- Milvus 2.x (向量数据库: RAG)
- Keycloak 25+ (认证授权)
- Apache APISIX 3.15+ (API Gateway)
- Docker + K8s (部署)
- Prometheus + Grafana (监控)

## 开发规范
- Go: gofmt + golangci-lint, 遵循 Effective Go
- Python: ruff + black
- TypeScript: eslint + prettier
- 所有 API 必须有 OpenAPI 3.0 规范
- 所有数据库变更必须有 Migration 脚本 (版本号递增)
- Git: Conventional Commits (feat/fix/docs/chore)
- 测试: 单元测试覆盖率 > 80%

## 核心模块
- services/auth: Keycloak 适配器 + JWT/API Key 验证
- services/gateway: APISIX 自研插件
- services/llm-router: 多平台 LLM 智能路由 + 故障转移
- services/billing: Token 计费引擎 (Redis Lua 原子操作)
- services/metering: 用量追踪 (Kafka → PostgreSQL)
- services/registry: 能力注册中心 (gRPC + REST)
- services/skills: Skills 市场
- services/im-gateway: IM Bot 多平台网关

## 数据库
- 所有表启用 RLS，策略基于 tenant_id
- token_usage 按月分区
- credit_transactions 不可变 (追加写)
- 所有金额使用整数 (毫 Credit)，避免浮点

## 计费原则
- 先扣后服: 先扣减余额，再允许调用
- 幂等: 通过 idempotency_key 防重复扣费
- 原子: Redis Lua 脚本保证原子性
- 可审计: 每笔变动有 trace_id + 原因

## LLM 对接
- 统一 OpenAI 兼容格式: POST /v1/chat/completions
- 百度需要适配层 (非标准 API)
- 其他平台直接兼容
- API Key 加密存储 (AES-256)

风险与对策

风险	等级	影响	对策
开发周期长	高	20 周投入大	分 Phase 交付，每 Phase 结束有可运行成果
技术复杂度高	中	多服务协调	MiMo Code 辅助生成骨架，降低编码量
单人开发	中	人力瓶颈	严格控制范围，Phase 内任务优先级排序
APISIX 学习曲线	低	网关配置复杂	文档完善，社区活跃，插件机制成熟
Kafka 运维	中	消息积压	监控 Consumer Lag，自动扩缩容
数据一致性	中	计费准确性	Redis Lua 原子操作 + 每日对账
LLM 平台 API 变动	低	适配器失效	抽象 Provider 接口，变动时只改适配器

每日开发节奏建议

09:00-09:15  每日站会 (自检: 昨日完成/今日计划/阻塞)
09:15-12:00  MiMo Code 核心开发 (Quest Mode / Agent Mode)
12:00-13:30  午休
13:30-15:00  MiMo Code 继续开发
15:00-15:30  Code Review + 测试
15:30-17:00  MiMo Code 补充测试 + 文档
17:00-17:30  Git 提交 + 推送 + 更新进度

Phase 完成检查清单

每个 Phase 结束时，必须通过以下检查：

Phase 1 检查

docker-compose up 所有服务正常启动
Keycloak 可注册/登录用户
APISIX 可转发请求到后端服务
数据库 Schema 已创建，RLS 策略生效
各服务 health endpoint 返回 200

Phase 2 检查

可通过 API Key 调用 LLM (至少 3 个平台)
调用后自动扣费，余额正确
用量数据写入 PostgreSQL
流式响应 (SSE) 正常工作
故障转移测试通过 (关闭主模型，自动切换)

Phase 3 检查

可注册新能力 (Agent/MCP/Skill)
可在市场购买技能
Dashboard 显示正确的余额和用量
管理后台可管理用户和租户
搜索功能正常

Phase 4 检查

IM Bot 可收发消息 (至少 1 个平台)
MCP 工具可调用并计费
LangFlow Flow 可运行并计费
ACP 消息可发送和接收

Phase 5 检查

单元测试覆盖率 > 80%
全链路 E2E 测试通过
压力测试报告 (目标: 500 RPS)
Docker Compose 生产配置可用
Grafana Dashboard 正常显示
API 文档完整 (OpenAPI 3.0)
开发者文档可访问

文档版本: 1.0 | 更新日期: 2026-06-27 | 基于 5 平台交叉验证共识

27 KiB Raw Permalink Blame History Unescape Escape

方案二：稳扎稳打 — 详细实施计划

总览：5 Phase 里程碑

Phase 1：基座搭建（Week 1-4）

1.1 项目骨架初始化（Day 1-2）

1.2 数据库 Schema 设计（Day 3-5）

1.3 Keycloak 认证服务（Day 6-10）

1.4 Apache APISIX 网关（Day 11-14）

Phase 2：核心引擎（Week 5-8）

2.1 LLM Provider Router（Day 15-20）

2.2 Token 计费引擎（Day 21-27）

2.3 用量追踪 Kafka → PostgreSQL（Day 28-32）

2.4 OpenAPI 网关（Day 33-35）

Phase 3：能力治理（Week 9-12）

3.1 Capability Registry（Day 36-42）

3.2 Skills 市场（Day 43-47）

3.3 用户 Dashboard（Day 48-54）

3.4 管理后台（Day 55-58）

Phase 4：生态扩展（Week 13-16）

4.1 IM Bot 网关（Day 59-65）

4.2 MCP Hub 集成（Day 66-68）

4.3 LangFlow Agent 集成（Day 69-73）

4.4 ACP 协议基础（Day 74-77）

Phase 5：集成上线（Week 17-20）

5.1 全链路测试（Day 78-83）

5.2 生产部署（Day 84-88）

5.3 监控告警（Day 89-91）

5.4 文档上线（Day 92-95）

MiMo Code 核心配置 (.mimocode/AGENTS.md)

风险与对策

每日开发节奏建议

Phase 完成检查清单

Phase 1 检查

Phase 2 检查

Phase 3 检查

Phase 4 检查

Phase 5 检查

27 KiB

Raw Permalink Blame History