# 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)
- 所有关键操作有审计日志