ai-paas-comparison/docs/05-AGENTS-MiMoCode配置.md

AI PaaS Platform — AGENTS.md (v2.0)

放置于 .mimocode/AGENTS.md，MiMo Code 每次启动自动加载。

---

AI PaaS 商业平台

一句话描述

让任何 AI 使用者都能像用水电一样使用 AI 能力，注册即用，按量付费。

用户模型

• 扁平化：只有用户，没有租户概念
• 权限分级：未认证 → 已实名 → 订阅用户
• 订阅用户：完成实名认证 + 支付月费，自动获得创建/发布 AI 能力权限
• 核心规则：欠费不影响已发布能力

技术栈

• AI 服务层: Python 3.11+ (FastAPI) — 所有自研业务服务
• LLM 网关: NEW API (Go, 开源) — 多模型统一管理
• SSO 认证: Casdoor (Go, 开源) — OAuth2/OIDC/社交登录
• API 网关: APISIX (Lua, 开源) — 路由/限流/鉴权
• 本地 LLM: Ollama (Go, 开源) — 本地模型推理
• Agent 编排: LangFlow (Python, 开源) — 可视化工作流
• 前端: React 18 + TypeScript + Ant Design Pro + ECharts
• 数据库: PostgreSQL 16
• 缓存: Redis 7 (Lua 原子计费)
• 消息队列: Kafka 3.x (用量上报)
• 实名认证: 阿里云实名认证 API

项目结构

ai-paas-platform/
├── .mimocode/
│   └── AGENTS.md                ← 本文件
├── docs/
│   ├── 01-PRD-产品需求文档.md
│   ├── 02-系统架构设计.md
│   ├── 03-数据库设计.md
│   └── 04-API接口规范.md
├── packages/
│   └── web/                      ← React Dashboard
├── services/
│   ├── gateway/                  ← FastAPI 核心网关 (:8080)
│   ├── billing/                  ← FastAPI 计费引擎 (:8081)
│   ├── registry/                 ← FastAPI 能力注册 (:8082)
│   ├── skills/                   ← FastAPI Skills 市场 (:8083)
│   ├── metering/                 ← FastAPI 用量追踪 (:8084)
│   └── admin/                    ← FastAPI 管理后台 (:8085)
├── infra/
│   ├── casdoor/                  ← Casdoor 配置
│   ├── new-api/                  ← NEW API 配置
│   ├── ollama/                   ← Ollama 配置
│   ├── apisix/                   ← APISIX 配置
│   ├── postgresql/               ← 数据库初始化
│   ├── redis/
│   └── kafka/
├── deploy/
│   ├── docker-compose.yml        ← 一键启动开发环境
│   └── k8s/
├── migrations/
└── pyproject.toml

开发规范

Python 服务 (FastAPI)

• 遵循 ruff + black 格式化
• 每个服务独立目录，可独立运行
• 服务间通信: 同步 HTTP，异步 Kafka
• 错误处理: 统一 {code, message, data} 格式
• 配置管理: 环境变量 + .env 文件
• 日志: structlog (结构化 JSON)
• 类型注解: 必须 (Pydantic v2)
• 测试: pytest + httpx, 覆盖率 > 80%

TypeScript 前端

• eslint + prettier
• React 函数组件 + Hooks
• 状态: React Query (服务端) + Zustand (客户端)
• 路由: React Router v6
• 样式: Ant Design Pro 内置

Git

• 分支: main, develop, feature/*
• 提交: Conventional Commits (feat/fix/docs/chore/test)
• PR: 必须通过 CI

核心服务说明

ai-paas-gateway (:8080)

• 所有业务请求入口
• JWT 验证 (对接 Casdoor)
• API Key 验证 (SHA-256 查 DB)
• 用户状态检查 (订阅/欠费)
• LLM 调用代理: gateway → NEW API → LLM
• 流式 SSE 透传
• 用量异步上报 (Kafka)

ai-paas-billing (:8081)

• Redis Lua 原子操作
• 先扣后服 + 幂等 + 可审计
• 订阅管理 (Free/Developer/Pro/Flagship)
• Token 包充值
• 欠费保护期 (7 天)
• 开发者分成结算

ai-paas-registry (:8082)

• 能力 CRUD
• 能力类型: agent/mcp/skill/llm/custom
• 版本管理: SemVer
• 状态: draft → pending_review → active → deprecated
• 欠费时已发布能力保持 active

ai-paas-skills (:8083)

• 技能市场浏览/搜索/购买
• 开发者发布技能
• 分成: 平台 25% / 开发者 75%
• 全文搜索 (PostgreSQL GIN)
• 评分系统

ai-paas-metering (:8084)

• Kafka Consumer
• PostgreSQL 持久化
• 按月分区表
• 预聚合统计

ai-paas-admin (:8085)

• 用户管理
• 能力审核
• 财务管理
• 系统监控

计费原则（最重要）

1. 先扣后服: 先扣减余额，再允许调用
2. 幂等: idempotency_key 防重复扣费
3. 原子: Redis Lua 保证原子性
4. 可审计: 每笔变动有 trace_id
5. 欠费保护: 已发布能力不被下架

LLM 对接

• 统一通过 NEW API 代理
• NEW API 配置各平台 API Key
• 格式: OpenAI 兼容 (POST /v1/chat/completions)
• 流式: SSE (text/event-stream)
• 百度需适配层 (NEW API 内置)

实名认证

• 阿里云实名认证 API
• 用户提交: 真实姓名 + 身份证号
• 验证通过: 标记 verified = true
• 信息加密存储 (AES-256)

重要约束

• 所有 API 必须有 OpenAPI 文档 (FastAPI 自动生成)
• 所有数据库变更必须有 Migration
• 所有金额使用整数 (分)
• 所有敏感数据加密
• 欠费不影响已发布能力