qyyfw
d9a8a0e93c
- 03-数据库设计.md: ER图 + 12张表定义 + Redis数据结构 + Migration策略 - 04-API接口规范.md: OpenAPI 3.0 约定 + 全部接口定义 (Auth/APIKey/LLM/Billing/Registry/Skills/IM/Admin) - 05-AGENTS-MiMoCode配置.md: MiMo Code 核心配置文件，包含项目结构/技术栈/开发规范/模块说明 至此 docs/ 目录包含完整的6份基础设计文档，可作为 MiMo Code 的上下文输入
187 lines
6.5 KiB
Markdown
187 lines
6.5 KiB
Markdown
# AI PaaS Platform — AGENTS.md（MiMo Code 核心配置）
|
||
|
||
> 此文件放在项目根目录 `.mimocode/AGENTS.md`，MiMo Code 每次启动时自动加载。
|
||
> 这是 MiMo Code 理解整个项目的唯一上下文来源——写得越精确，生成的代码质量越高。
|
||
|
||
---
|
||
|
||
# AI PaaS 商业平台
|
||
|
||
## 项目概述
|
||
面向个人开发者的 AI 能力服务平台。提供 Agent、MCP、Skills、IM Bot、LLM 调用等 AI 能力，支持按 Token 计费和订阅制收费。
|
||
|
||
## 架构模式
|
||
微服务架构 + 事件驱动。核心业务自研，基础设施开源。
|
||
|
||
## 技术栈
|
||
- **后端核心**: Go 1.22+ (所有核心服务)
|
||
- **AI 服务**: Python 3.11+ (LangFlow, MCP Hub 集成)
|
||
- **前端**: React 18 + TypeScript 5+ + Ant Design Pro 6 + ECharts
|
||
- **数据库**: PostgreSQL 16 (RLS 多租户隔离)
|
||
- **缓存**: Redis 7 (Lua 原子计费)
|
||
- **消息队列**: Kafka 3.x (用量上报)
|
||
- **向量库**: Milvus 2.x (RAG)
|
||
- **认证**: Keycloak 25+ (JWT + API Key)
|
||
- **网关**: Apache APISIX 3.15+ (API Gateway)
|
||
- **Agent**: LangFlow (工作流编排)
|
||
- **MCP**: mcp-hub (MCP 服务管理)
|
||
- **监控**: Prometheus + Grafana
|
||
|
||
## 项目结构
|
||
```
|
||
ai-paas-platform/
|
||
├── .mimocode/
|
||
│ └── AGENTS.md ← 本文件
|
||
├── docs/ ← 设计文档
|
||
│ ├── 01-PRD-产品需求文档.md
|
||
│ ├── 02-系统架构设计.md
|
||
│ ├── 03-数据库设计.md
|
||
│ └── 04-API接口规范.md
|
||
├── packages/ ← 前端应用
|
||
│ ├── web/ ← 用户 Dashboard (React)
|
||
│ └── admin/ ← 管理后台 (React)
|
||
├── services/ ← 后端服务 (Go)
|
||
│ ├── auth/ ← 认证服务 (:8081)
|
||
│ ├── registry/ ← 能力注册中心 (:8082)
|
||
│ ├── openapi-gateway/ ← OpenAI 兼容网关 (:8083)
|
||
│ ├── billing/ ← 计费引擎 (:8084)
|
||
│ ├── skills/ ← Skills 市场 (:8085)
|
||
│ ├── admin/ ← 管理后台 API (:8086)
|
||
│ ├── im-gateway/ ← IM Bot 网关 (:8087)
|
||
│ ├── metering/ ← 用量追踪 (:8090)
|
||
│ └── llm-router/ ← LLM 智能路由 (:8091)
|
||
├── infra/ ← 基础设施配置
|
||
│ ├── keycloak/
|
||
│ ├── postgresql/
|
||
│ ├── redis/
|
||
│ ├── kafka/
|
||
│ ├── milvus/
|
||
│ └── apisix/
|
||
├── deploy/ ← 部署配置
|
||
│ ├── docker-compose.yml
|
||
│ └── k8s/
|
||
└── migrations/ ← 数据库 Migration
|
||
├── 001_init.sql
|
||
└── ...
|
||
```
|
||
|
||
## 开发规范
|
||
|
||
### Go 服务
|
||
- 遵循 Effective Go + gofmt + golangci-lint
|
||
- 每个服务独立 main.go，可独立编译运行
|
||
- 服务间通信: 同步用 HTTP/gRPC，异步用 Kafka
|
||
- 错误处理: 统一错误码，返回 `{code, message, data}` 格式
|
||
- 配置管理: 环境变量 + YAML 配置文件
|
||
- 日志: 结构化 JSON 日志 (slog)
|
||
|
||
### TypeScript 前端
|
||
- 遵循 eslint + prettier
|
||
- 组件: React 函数组件 + Hooks
|
||
- 状态管理: React Query (服务端) + Zustand (客户端)
|
||
- 路由: React Router v6
|
||
- 样式: Ant Design Pro 内置 + CSS Modules
|
||
|
||
### Python AI 服务
|
||
- 遵循 ruff + black
|
||
- 类型注解: 必须
|
||
- 异步: asyncio
|
||
|
||
### 数据库
|
||
- 所有表启用 RLS，策略基于 tenant_id
|
||
- 所有金额使用整数 (毫 Credit)，避免浮点
|
||
- Migration 文件名: `{序号}_{描述}.sql`
|
||
- 不可变表: credit_transactions, token_usage (无 UPDATE/DELETE)
|
||
|
||
### Git
|
||
- 分支: main (生产), develop (开发), feature/* (功能)
|
||
- 提交: Conventional Commits (feat/fix/docs/chore/test)
|
||
- PR: 必须通过 CI + Code Review
|
||
|
||
### 测试
|
||
- Go: testing + testify, 覆盖率 > 80%
|
||
- TypeScript: vitest + playwright
|
||
- 单元测试: 每个服务的核心逻辑
|
||
- 集成测试: 服务间调用链
|
||
|
||
## 核心模块说明
|
||
|
||
### auth-service (:8081)
|
||
- Keycloak 适配器
|
||
- JWT 验证中间件
|
||
- API Key 验证 (SHA-256 哈希查 DB)
|
||
- 租户上下文提取 (JWT claim → tenant_id)
|
||
- RBAC: owner > admin > developer > user
|
||
|
||
### llm-router (:8091)
|
||
- 多平台 LLM 对接 (OpenAI 兼容格式)
|
||
- 7 个平台: DeepSeek, 千问, 豆包, 智谱, 元宝, 百度, Ollama
|
||
- 智能路由: 用户选择 / 成本优先 / 延迟优先
|
||
- 故障转移: 主模型不可用自动切换
|
||
- 流式响应: SSE 透传
|
||
- API Key 加密存储 (AES-256-GCM)
|
||
|
||
### billing (:8084)
|
||
- Credit 模型: 1 Credit = 1000 tokens
|
||
- 模型系数: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5
|
||
- Redis Lua 原子操作: 先扣后服 + 幂等 + 可审计
|
||
- 订阅套餐: Free/Pro/Team/Enterprise
|
||
- 每日对账: Redis ↔ PostgreSQL 一致性检查
|
||
|
||
### registry (:8082)
|
||
- 能力 CRUD (REST + gRPC 双协议)
|
||
- 能力类型: agent/mcp/skill/llm/custom
|
||
- 版本管理: SemVer
|
||
- 状态: draft → pending_review → active → deprecated
|
||
- 服务发现: 按类型/标签/状态查询
|
||
|
||
### metering (:8090)
|
||
- Kafka Consumer: 消费 usage.events
|
||
- PostgreSQL 持久化: token_usage 表 (按月分区)
|
||
- 预聚合: 每小时刷新 usage_summaries
|
||
- 用量查询: 按日/周/月/模型/能力统计
|
||
|
||
### skills (:8085)
|
||
- 技能发布/审核/交易
|
||
- 计费模式: per_call/per_token/subscription/free
|
||
- 分成: 平台 25% / 开发者 75%
|
||
- 全文搜索: PostgreSQL GIN 索引
|
||
|
||
### im-gateway (:8087)
|
||
- 多平台适配器: 微信(LangBot) / QQ(OneBot) / 钉钉
|
||
- 会话管理: Redis Hash, 24h 过期
|
||
- 上下文窗口: 最近 20 条消息
|
||
- 指令系统: /help /model /clear /balance
|
||
|
||
### openapi-gateway (:8083)
|
||
- OpenAI 兼容 API: POST /v1/chat/completions
|
||
- 请求拦截链: Auth → Balance → LLM → Billing → Response
|
||
- 流式 SSE 支持
|
||
- 用量异步上报 Kafka
|
||
|
||
## 计费原则（最重要）
|
||
1. **先扣后服**: 先扣减余额，再允许调用
|
||
2. **幂等**: 通过 idempotency_key 防重复扣费
|
||
3. **原子**: Redis Lua 脚本保证原子性
|
||
4. **可审计**: 每笔变动有 trace_id + 原因
|
||
5. **实时可见**: Dashboard 余额秒级更新
|
||
|
||
## LLM 对接
|
||
- 统一 OpenAI 兼容格式: POST /v1/chat/completions
|
||
- 百度需适配层 (非标准 API)
|
||
- 其他平台直接兼容
|
||
- 流式: SSE (text/event-stream)
|
||
|
||
## 部署
|
||
- 开发: docker-compose.yml (一键启动)
|
||
- 生产: Kubernetes + Helm Charts
|
||
- 监控: Prometheus + Grafana
|
||
- 日志: 结构化 JSON → Loki
|
||
|
||
## 重要约束
|
||
- 所有 API 必须有 OpenAPI 3.0 规范
|
||
- 所有数据库变更必须有 Migration
|
||
- 所有金额使用整数 (毫 Credit)
|
||
- 所有敏感数据加密 (AES-256)
|
||
- 所有关键操作有审计日志
|