160 lines
5.0 KiB
Markdown
160 lines
5.0 KiB
Markdown
# 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
|
||
|
||
## 项目结构
|
||
```
|
||
QihuAI/
|
||
├── .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
|
||
- 所有金额使用整数 (分)
|
||
- 所有敏感数据加密
|
||
- **欠费不影响已发布能力**
|