From 67c3270aade5630419fbf24136d082bfb4872764 Mon Sep 17 00:00:00 2001 From: qyyfw Date: Sat, 27 Jun 2026 10:21:15 +0000 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=96=B9=E6=A1=88=E4=BA=8C=E8=AF=A6?= =?UTF-8?q?=E7=BB=86=E5=AE=9E=E6=96=BD=E8=AE=A1=E5=88=92=20-=205=20Phase?= =?UTF-8?q?=2020=E5=91=A8=E5=AE=8C=E6=95=B4=E6=8B=86=E8=A7=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- 方案二-详细实施计划.md | 967 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 967 insertions(+) create mode 100644 方案二-详细实施计划.md diff --git a/方案二-详细实施计划.md b/方案二-详细实施计划.md new file mode 100644 index 0000000..f9ad72a --- /dev/null +++ b/方案二-详细实施计划.md @@ -0,0 +1,967 @@ +# 方案二：稳扎稳打 — 详细实施计划 + +> **定位**: 核心服务全部自研，基础设施用开源，架构完全自主可控 +> **周期**: 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) + +```markdown +# 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 平台交叉验证共识* \ No newline at end of file