# 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
```