384 lines
16 KiB
Plaintext
384 lines
16 KiB
Plaintext
# AI PaaS 平台项目规格说明书（专为 Qoder 设计）
|
||
|
||
**文档版本：** 1.0
|
||
**适用工具：** Qoder (Quest Mode / Agent Mode)
|
||
**目标：** 指导 Qoder 生成代码、设计架构、管理任务，完成 AI PaaS 平台开发
|
||
**策略：** 核心自研 + 外围开源
|
||
|
||
---
|
||
|
||
## 1. 项目概述 (Project Overview)
|
||
|
||
**项目名称：** AI PaaS Platform (AIPaaS)
|
||
**目标：** 构建一个面向个人用户的 AI 能力服务平台，支持 Agent 创建、MCP 接入、Skills 市场、IM Bot 机器人、CLI 工具及 AI 产品交易。
|
||
**核心差异化：** 能力注册中心、LLM 智能路由、统一计费系统、可视化 Agent 编排。
|
||
**开发模式：** 混合模式（核心逻辑自研，基础设施开源）。
|
||
|
||
---
|
||
|
||
## 2. 开发策略 (Development Strategy)
|
||
|
||
### 2.1 自研 vs 开源决策表
|
||
|
||
| 模块 | 策略 | 说明 | Qoder 行动指令 |
|
||
|------|------|------|----------------|
|
||
| **用户认证** | 70% 开源 + 30% 自研 | 使用 Keycloak，自研租户隔离适配器 | `Configure Keycloak, Build Tenant Adapter` |
|
||
| **API Gateway** | 80% 开源 + 20% 自研 | 使用 Kong，自研能力路由与计费插件 | `Setup Kong, Create Custom Plugins` |
|
||
| **数据库** | 100% 开源 | PostgreSQL + Redis + Milvus | `Initialize DB Schema, Configure Milvus` |
|
||
| **能力注册中心** | 100% 自研 | 核心模块，管理 Agent/MCP/Skill 元数据 | `Build Capability Registry Service` |
|
||
| **LLM Provider Router** | 100% 自研 | 核心模块，多模型路由、故障转移、计费 | `Build LLM Router Service` |
|
||
| **计费系统** | 100% 自研 | 订阅 + 按量混合计费，对接支付网关 | `Build Billing Service` |
|
||
| **Agent 编排引擎** | 100% 自研 | 可视化工作流，类似 LangFlow | `Build Frontend Editor + Backend Executor` |
|
||
| **Skills 市场** | 100% 自研 | 发布、审核、交易、分成逻辑 | `Build Skill Marketplace API` |
|
||
| **IM Bot 网关** | 100% 自研 | 多平台适配（微信/QQ/钉钉）+ 统一路由 | `Build IM Gateway with Adapters` |
|
||
| **知识库 (RAG)** | 开源 + 自研 | Milvus 向量库 + 自研检索逻辑 | `Setup Milvus, Build RAG Service` |
|
||
| **基础设施** | 100% 开源 | Docker, K8s, Nginx, Kafka, Prometheus | `Generate Docker Compose, K8s Helm Charts` |
|
||
|
||
### 2.2 Qoder 工作流建议
|
||
|
||
1. **阶段一 (架构设计)：** 使用 **Qoder Quest Mode**。输入本规格书，生成项目骨架、目录结构、配置文件。
|
||
2. **阶段二 (核心开发)：** 使用 **Qoder Agent Mode**。逐模块开发（如先开发认证，再开发注册中心）。
|
||
3. **阶段三 (知识沉淀)：** 使用 **Qoder Repo Wiki**。自动生成架构图、API 文档、依赖关系图，并定期更新。
|
||
4. **阶段四 (测试验证)：** 使用 **Qoder Code Review** 和 **Test Generation**。确保代码质量。
|
||
|
||
---
|
||
|
||
## 3. 技术栈 (Tech Stack)
|
||
|
||
### 3.1 后端服务
|
||
* **核心服务：** Go (1.21+) (高性能，适合网关、Router、注册中心)
|
||
* **业务服务：** Python (3.10+) (FastAPI) (适合 Agent 编排、Skills 市场、数据处理)
|
||
* **API Gateway：** Kong (3.x) (Lua 插件，高性能)
|
||
* **消息队列：** Kafka (高吞吐用量日志) + Redis Stream (轻量任务)
|
||
* **任务队列：** Celery (Python) (异步审核、结算)
|
||
|
||
### 3.2 前端与工具
|
||
* **Dashboard：** React 18 + TypeScript + Ant Design 5
|
||
* **CLI：** Python (Click 库)
|
||
* **开发工具：** Qoder (IDE 插件 / CLI)
|
||
|
||
### 3.3 基础设施
|
||
* **数据库：** PostgreSQL 15 (业务数据), Redis 7 (缓存/限流), Milvus 2.4 (向量)
|
||
* **认证：** Keycloak 24 (OAuth2.0/OIDC)
|
||
* **容器：** Docker + Kubernetes (K8s)
|
||
* **存储：** MinIO (S3 兼容，对象存储)
|
||
* **监控：** Prometheus + Grafana + ELK Stack
|
||
* **CI/CD：** GitHub Actions
|
||
|
||
---
|
||
|
||
## 4. 系统架构 (System Architecture)
|
||
|
||
### 4.1 逻辑架构图 (文本描述)
|
||
```
|
||
[Web Dashboard] [Mobile App] [CLI]
|
||
│
|
||
▼
|
||
[API Gateway (Kong)] ←── [Custom Plugins (Auth, RateLimit, UsageCheck)]
|
||
│
|
||
├─ [Auth Service (Keycloak + Tenant Adapter)]
|
||
├─ [LLM Router (Self-Research)] ←── [LLM Providers (DeepSeek, Qwen, etc.)]
|
||
├─ [Capability Registry (Self-Research)] ←── [Agent/MCP/Skill Services]
|
||
├─ [Billing Service (Self-Research)] ←── [Payment Gateways (Alipay, Stripe)]
|
||
├─ [Usage Tracker (Redis + Kafka)]
|
||
└─ [Admin Console (React)]
|
||
```
|
||
|
||
### 4.2 多租户隔离策略
|
||
* **数据库：** Shared-schema 模式，所有表增加 `tenant_id` 字段。
|
||
* **ORM：** 自动注入 `tenant_id` 过滤器（MyBatis Plus / GORM）。
|
||
* **认证：** Keycloak Realm 隔离（每个租户独立 Realm）或 单 Realm + 租户标签（推荐单 Realm 降低复杂度，通过 API 层过滤）。
|
||
* **资源：** 独立 Redis Key 命名空间 (`tenant:{id}:usage`)。
|
||
|
||
---
|
||
|
||
## 5. 模块规格说明书 (Module Specifications)
|
||
|
||
### 5.1 用户认证与授权 (Auth Service)
|
||
|
||
**功能：**
|
||
1. OAuth2.0 登录 (微信、QQ、Google)
|
||
2. JWT Token 生成 (HS256)
|
||
3. API Key 管理系统 (按 tenant 隔离)
|
||
4. RBAC 权限 (Admin, User, Developer)
|
||
|
||
**Qoder 指令：**
|
||
* `Configure Keycloak with OAuth2.0 providers (WeChat, QQ).`
|
||
* `Build a Go-based Tenant Adapter for Keycloak to manage tenant isolation.`
|
||
* `Implement JWT middleware for API Gateway validation.`
|
||
* `Create API Key generation endpoint (POST /api/keys) with revoke support.`
|
||
|
||
### 5.2 API Gateway (Kong)
|
||
|
||
**功能：**
|
||
1. JWT 认证插件
|
||
2. API Key 认证插件
|
||
3. 限流插件 (基于 tenant 的 QPS 限制)
|
||
4. 熔断插件
|
||
5. 自定义插件：能力路由 (Capability Router)、用量检查 (Usage Check)
|
||
|
||
**Qoder 指令：**
|
||
* `Generate Kong configuration file (kong.yml) with services for LLM Router and Capability Registry.`
|
||
* `Create a custom Kong plugin in Go for Usage Check (query Redis before routing).`
|
||
* `Create a custom Kong plugin for Capability Routing (route based on capability_id header).`
|
||
|
||
### 5.3 能力注册中心 (Capability Registry) - **核心自研**
|
||
|
||
**功能：**
|
||
1. 能力注册 (POST /v1/capabilities/register)
|
||
2. 能力查询 (GET /v1/capabilities?tag=travel)
|
||
3. 元数据存储 (PostgreSQL)
|
||
4. 缓存 (Redis, 5 分钟 TTL)
|
||
5. 健康检查 (定期心跳)
|
||
6. 版本管理 (语义化版本 v1.0.0)
|
||
|
||
**数据模型 (PostgreSQL)：**
|
||
```sql
|
||
CREATE TABLE capabilities (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
capability_id VARCHAR(100) UNIQUE NOT NULL, -- Agent ID / Skill ID
|
||
name VARCHAR(255) NOT NULL,
|
||
type VARCHAR(50) NOT NULL, -- 'agent', 'mcp', 'skill', 'bot'
|
||
version VARCHAR(20) NOT NULL,
|
||
description TEXT,
|
||
tags JSONB,
|
||
api_endpoint VARCHAR(500),
|
||
protocol VARCHAR(20) DEFAULT 'rest',
|
||
dependencies JSONB,
|
||
status VARCHAR(20) DEFAULT 'active',
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW(),
|
||
INDEX idx_tenant_type (tenant_id, type),
|
||
INDEX idx_capability_id (capability_id)
|
||
);
|
||
```
|
||
|
||
**Qoder 指令：**
|
||
* `Generate Go service for Capability Registry with CRUD API.`
|
||
* `Implement Redis caching layer for capability metadata.`
|
||
* `Create API endpoints: POST /v1/capabilities/register, GET /v1/capabilities, DELETE /v1/capabilities/{id}.`
|
||
* `Implement semantic versioning validation for registration.`
|
||
|
||
### 5.4 LLM Provider Router - **核心自研**
|
||
|
||
**功能：**
|
||
1. 多模型适配器 (DeepSeek, Qwen, Doubao, Baidu, Yuanbao, Zhipu, Ollama)
|
||
2. OpenAI 兼容接口 (POST /v1/chat/completions)
|
||
3. 路由策略 (成本优先、性能优先、智能路由)
|
||
4. 故障转移 (自动切换备用模型)
|
||
5. 用量追踪 (记录输入/输出 Token)
|
||
|
||
**Qoder 指令：**
|
||
* `Define LLM Provider Interface in Go (ChatCompletion, Stream, HealthCheck).`
|
||
* `Implement Adapters for DeepSeek, Qwen, Ollama (follow OpenAI format conversion).`
|
||
* `Build Router Service with Strategy Pattern for model selection.`
|
||
* `Implement Circuit Breaker for failover using Redis.`
|
||
* `Add Usage Tracking hook before calling model adapter (record to Kafka).`
|
||
|
||
### 5.5 计费系统 (Billing System) - **核心自研**
|
||
|
||
**功能：**
|
||
1. 订阅管理 (Free, Pro, Business, Enterprise)
|
||
2. Token 配额管理 (月配额、剩余量)
|
||
3. 混合计费 (订阅 + 超出部分按量)
|
||
4. 支付集成 (支付宝、微信支付、Stripe)
|
||
5. 账单生成 (月度)
|
||
|
||
**数据模型 (PostgreSQL)：**
|
||
```sql
|
||
CREATE TABLE subscriptions (
|
||
id UUID PRIMARY KEY,
|
||
user_id UUID NOT NULL,
|
||
tenant_id UUID NOT NULL,
|
||
plan_type VARCHAR(20) NOT NULL, -- 'free', 'pro', 'business'
|
||
tokens_quota INT,
|
||
start_date DATE,
|
||
end_date DATE,
|
||
status VARCHAR(20) -- 'active', 'expired', 'cancelled'
|
||
);
|
||
|
||
CREATE TABLE usage_records (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
capability_id VARCHAR(100),
|
||
model_id VARCHAR(50),
|
||
input_tokens INT,
|
||
output_tokens INT,
|
||
cost DECIMAL(10, 4),
|
||
timestamp TIMESTAMP
|
||
);
|
||
```
|
||
|
||
**Qoder 指令：**
|
||
* `Generate Billing Service with subscription management API.`
|
||
* `Implement Usage Tracker middleware (check quota before allowing API call).`
|
||
* `Create Stripe/Alipay webhook handlers for payment confirmation.`
|
||
* `Build monthly billing report generator (run via Celery task).`
|
||
|
||
### 5.6 Agent 编排引擎 (Agent Engine)
|
||
|
||
**功能：**
|
||
1. 可视化工作流编辑器 (React)
|
||
2. 工作流定义 (JSON/YAML)
|
||
3. 执行引擎 (支持异步、重试、断点)
|
||
4. 节点类型：LLM 调用、条件分支、循环、工具调用
|
||
|
||
**Qoder 指令：**
|
||
* `Create React frontend component for Workflow Editor (drag-and-drop).`
|
||
* `Define JSON schema for Workflow Definition (nodes, edges).`
|
||
* `Build Go backend executor for workflow definition (parse JSON, execute nodes).`
|
||
* `Implement state persistence for long-running workflows (store in PostgreSQL).`
|
||
|
||
### 5.7 Skills 市场 (Skills Market)
|
||
|
||
**功能：**
|
||
1. Skill 发布 (代码包 + 元数据)
|
||
2. 安全扫描 (静态分析)
|
||
3. 审核流程 (自动 + 人工)
|
||
4. 交易 (购买、分成)
|
||
5. 版本管理 (v1.0, v1.1)
|
||
|
||
**Qoder 指令：**
|
||
* `Build Skill Upload Service with code validation (static analysis).`
|
||
* `Implement Skill Marketplace API (Publish, Buy, Rate).`
|
||
* `Create Admin Dashboard for Skill Review (Approve/Reject).`
|
||
* `Implement Revenue Sharing logic (Platform 30%, Developer 70%).`
|
||
|
||
### 5.8 IM Bot 网关 (IM Bot Gateway)
|
||
|
||
**功能：**
|
||
1. 平台适配器 (WeChat, QQ, DingTalk)
|
||
2. 统一消息格式 (内部标准化)
|
||
3. 会话管理 (跨平台状态)
|
||
4. 消息路由 (到对应 Agent)
|
||
|
||
**Qoder 指令：**
|
||
* `Create Adapter Interface for IM Platforms (WeChatAdapter, QQAdapter).`
|
||
* `Implement Message Router to translate platform format to internal format.`
|
||
* `Build Session Manager for user conversation state (Redis).`
|
||
* `Integrate with LLM Router for AI response generation.`
|
||
|
||
---
|
||
|
||
## 6. API 规格 (API Specifications)
|
||
|
||
### 6.1 通用头 (Common Headers)
|
||
```
|
||
Authorization: Bearer <JWT-Token>
|
||
X-Tenant-ID: <tenant_id>
|
||
X-User-ID: <user_id>
|
||
Content-Type: application/json
|
||
```
|
||
|
||
### 6.2 关键端点
|
||
|
||
| 方法 | 路径 | 描述 | 模块 |
|
||
|------|------|------|------|
|
||
| `POST` | `/v1/auth/login` | 用户登录 (OAuth2.0) | Auth |
|
||
| `POST` | `/v1/auth/keys` | 生成 API Key | Auth |
|
||
| `POST` | `/v1/capabilities/register` | 注册能力 (Agent/MCP) | Registry |
|
||
| `GET` | `/v1/capabilities/{id}` | 查询能力详情 | Registry |
|
||
| `POST` | `/v1/chat/completions` | LLM 统一入口 (Router) | LLM Router |
|
||
| `GET` | `/v1/usage/stats` | 用量统计 | Usage Tracker |
|
||
| `POST` | `/v1/agents` | 创建 Agent (工作流) | Agent Engine |
|
||
| `GET` | `/v1/skills` | 浏览 Skill | Skills Market |
|
||
| `POST` | `/v1/skills/{id}/purchase` | 购买 Skill | Billing |
|
||
| `POST` | `/v1/im/connect` | IM 机器人连接 | IM Bot |
|
||
|
||
---
|
||
|
||
## 7. 开发路线图 (Development Roadmap)
|
||
|
||
### 阶段 1：基础架构与核心中间件 (Week 1-4)
|
||
* [ ] 项目初始化 (目录结构、CI/CD 配置)
|
||
* [ ] 部署基础设施 (Docker Compose: Keycloak, Kong, PostgreSQL, Redis, Milvus)
|
||
* [ ] 实现用户认证系统 (Keycloak + Tenant Adapter)
|
||
* [ ] 实现 API Gateway (Kong + Auth Plugins)
|
||
* [ ] 实现能力注册中心 (CRUD + Redis Cache)
|
||
|
||
### 阶段 2：核心 AI 能力与计费 (Week 5-8)
|
||
* [ ] 实现 LLM Provider Router (多模型适配 + 路由策略)
|
||
* [ ] 实现用量追踪系统 (Redis + Kafka)
|
||
* [ ] 实现计费系统 (订阅 + 配额检查 + 支付集成)
|
||
* [ ] 实现 Agent 编排引擎 (前端编辑器 + 后端执行器)
|
||
|
||
### 阶段 3：市场与集成 (Week 9-12)
|
||
* [ ] 实现 Skills 市场 (发布 + 审核 + 交易)
|
||
* [ ] 实现 IM Bot 网关 (微信/QQ/钉钉适配)
|
||
* [ ] 实现知识库 (RAG + Milvus 集成)
|
||
* [ ] 实现 Dashboard (React + 数据展示)
|
||
|
||
### 阶段 4：测试与优化 (Week 13-14)
|
||
* [ ] 全链路测试 (端到端流程)
|
||
* [ ] 性能优化 (限流、缓存、数据库索引)
|
||
* [ ] 安全审计 (渗透测试、代码审查)
|
||
* [ ] 文档编写 (Repo Wiki, API 文档)
|
||
|
||
---
|
||
|
||
## 8. Qoder 交互指南 (How to Use with Qoder)
|
||
|
||
### 8.1 初始提问 (Initial Prompt)
|
||
**请将以下指令直接发送给 Qoder：**
|
||
|
||
> "你是 AI PaaS 平台的架构师。请根据我提供的《AI PaaS 平台项目规格说明书》，使用 Qoder 的 Quest Mode 完成以下任务：
|
||
> 1. 生成项目目录结构。
|
||
> 2. 生成 Docker Compose 文件，包含 Keycloak, Kong, PostgreSQL, Redis, Milvus。
|
||
> 3. 生成 PostgreSQL 数据库 schema (users, capabilities, subscriptions, usage_records)。
|
||
> 4. 生成 Go 项目骨架 (capability-registry, llm-router, billing)。
|
||
> 5. 使用 Repo Wiki 保存生成的架构图和依赖关系。
|
||
> 项目核心策略是：核心逻辑自研，基础设施开源。请优先生成基础设施配置和核心中间件骨架。"
|
||
|
||
### 8.2 模块开发指令 (Module Specific Prompt)
|
||
**当完成基础架构后，逐模块开发时，使用以下格式：**
|
||
|
||
> "请开发 [模块名称] 模块。
|
||
> 需求描述：[复制规格书中的功能描述]。
|
||
> 技术栈：[如 Go + PostgreSQL + Redis]。
|
||
> 关键接口：[列出关键 API 端点]。
|
||
> 数据模型：[要求生成 SQL Schema]。
|
||
> 注意事项：[如租户隔离、配额检查、错误处理]。
|
||
请生成完整的代码文件，并编写单元测试。"
|
||
|
||
### 8.3 代码审查与优化 (Code Review)
|
||
> "请审查 [文件路径] 的代码。
|
||
> 检查点：[如安全性、性能、租户隔离、错误处理、代码规范]。
|
||
> 建议：[列出具体问题]。
|
||
> 请提供重构建议并生成优化后的代码。"
|
||
|
||
### 8.4 Repo Wiki 使用
|
||
> "请分析当前项目结构，生成 Repo Wiki 文档。
|
||
> 内容包括：系统架构图、模块依赖关系图、API 端点列表、数据模型说明。
|
||
> 确保 Wiki 与代码保持同步，每次重大修改后更新 Wiki。"
|
||
|
||
---
|
||
|
||
## 9. 可行性验证 (Feasibility Check)
|
||
|
||
本方案基于以下前提，确保 Qoder 可执行：
|
||
1. **代码生成能力：** Qoder 能够生成 Go/Python/React 代码片段及完整文件。
|
||
2. **配置生成能力：** Qoder 能够编写 Docker Compose、K8s Helm Chart、Kong 配置。
|
||
3. **数据库操作：** Qoder 能够编写 SQL Schema 及 ORM 模型。
|
||
4. **测试生成：** Qoder 能够编写单元测试 (GoTest / PyTest / Jest)。
|
||
5. **迭代开发：** Qoder 支持多轮对话，可逐步完善代码 (如先写接口，再写实现)。
|
||
|
||
**风险控制：**
|
||
* 对于复杂的前端工作流编辑器 (React)，Qoder 可能生成基础框架，需人工细化交互逻辑。
|
||
* 对于第三方平台接入 (微信/QQ)，需 Qoder 调用官方 API 文档生成适配器代码。
|
||
* 对于支付网关，需 Qoder 生成 webhook 处理逻辑，密钥由用户配置。
|
||
|
||
---
|
||
|
||
## 10. 附录：初始任务清单 (First Step Checklist)
|
||
|
||
在将此文档投喂给 Qoder 前，请确保用户已准备：
|
||
- [ ] 注册 Qoder 账号并配置 API Key (如果需要云端模式)
|
||
- [ ] 准备好本地开发环境 (Docker, Git, Code Editor)
|
||
- [ ] 准备好第三方平台 API Key (微信、QQ、Stripe 等，可在后期配置)
|
||
- [ ] 准备好模型 API Key (DeepSeek、Qwen 等)
|
||
|
||
**Qoder 启动命令示例 (如果使用 CLI)：**
|
||
```bash
|
||
qoder project create --spec "AI PaaS Platform Specification" --mode quest
|
||
``` |