# AI PaaS 商业平台开发需求与设计说明书

## 1. 项目背景与目标

本项目旨在构建一套面向个人开发者及中小企业的 **AI PaaS 商业平台**，提供从 Agent 创建、技能交易到多端接入的全链路 AI 能力服务。

**核心目标：**

1. **能力服务化**：将 Agent、MCP、Skills 等 AI 能力封装为标准 API，支持一键部署与调用。
2. **商业闭环**：实现“订阅 + 按量”混合计费，支持多租户隔离与自动化账单。
3. **生态开放**：提供 Skills 市场与 IMBot 接入，构建开发者与用户的双边市场。
4. **工程化落地**：基于 **Qoder** 开发工具，采用“核心自研 + 开源集成”策略，确保 16 周内完成 MVP 上线。

---

## 2. 整体架构概述

平台采用 **微服务 + 云原生** 架构，严格遵循“核心业务自研，基础设施开源”的原则。

### 2.1 架构分层

| 层级 | 核心组件 | 实施策略 | 关键说明 |
| ------ |------ |------ |------ |
| **接入层** | Web 门户 / CLI / IMBot | **自研** | 统一用户入口，多端适配（微信/钉钉/钉钉） |
| **业务层** | Agent 工作台 / Skills 市场 / 计费中心 | **自研** | 平台核心商业逻辑，涉及资金与权限，必须自研 |
| **中间件层** | API Gateway / LLM Router / 注册中心 | **自研 + 封装** | 流量治理与模型路由需自研策略，底层复用 Kong/Nginx |
| **能力层** | Agent Runtime / RAG / MCP Server | **开源集成** | 复用 LangFlow、Milvus、vLLM 等成熟开源方案 |
| **基础设施** | K8s / 数据库 / 消息队列 | **开源/云原生** | PostgreSQL, Redis, Kafka, Prometheus |

### 2.2 自研与开源边界

- **必须自研（护城河）：**
    - **混合计费引擎**：支持 Token 消耗、API 调用次数、订阅套餐的实时扣费与熔断。
    - **多租户治理**：基于 `tenant_id` 的数据隔离、资源配额（Quota）控制、RBAC 权限模型。
    - **LLM 智能路由**：基于成本、延迟、模型能力的动态路由策略及故障自动转移。
- **禁止自研（复用开源）：**
    - **向量检索**：使用 **Milvus** 或 **ChromaDB**，不自行实现向量索引。
    - **模型推理**：使用 **vLLM** 或 **SGLang** 作为推理后端，不自行实现 Attention 算子。
    - **工作流引擎**：使用 **Temporal** 或 **LangFlow** 处理 Agent 编排，不自行实现状态机。

---

## 3. 核心模块详细设计

### 3.1 平台底座

- **认证授权**：OAuth 2.0 + JWT。支持 GitHub/微信第三方登录。
- **多租户架构**：
    - 数据库：PostgreSQL，采用 `Schema` 隔离或 `Row-Level Security` (RLS)。
    - 资源隔离：K8s Namespace 隔离或 Cgroup 资源限制。
- **Dashboard**：
    - 用户侧：API Key 管理、用量图表、账单详情、Agent 部署状态。
    - 管理侧：用户审核、全局监控、内容安全审计、系统配置。

### 3.2 订阅计费系统

- **计费模型**：
    - **Subscription**：月付/年付，包含基础 Token 额度（如 100万 Tokens/月）。
    - **Pay-as-you-go**：超出额度后，按 `Price per 1k Tokens` 或 `Price per Request` 计费。
- **支付集成**：
    - 国内：支付宝/微信（通过 Ping++ 或 Stripe 中国）。
    - 国际：Stripe。
- **实时性**：
    - 使用 Redis 缓存当前用量，Kafka 异步消费日志进行持久化与账单生成。
    - **熔断机制**：当 `Used > Quota + Buffer` 时，API Gateway 立即拦截请求。

### 3.3 标准化中间件（核心）

- **能力注册中心**：
    - 所有 AI 能力（Agent/Skill/MCP）注册为 `Capability` 对象。
    - 元数据：`{id, name, version, type, endpoint, pricing_model, schema}`。
    - 存储：MongoDB（灵活 Schema）或 PostgreSQL (JSONB)。
- **API Gateway**：
    - 基于 **Kong** 或 **APISIX** 二次开发。
    - 插件：`jwt-auth`, `rate-limiting`, `ai-billing`, `protocol-transform`。
- **LLM Provider Router**：
    - **统一接口**：`POST /v1/chat/completions` (OpenAI 兼容)。
    - **路由策略**：
    - **Fallback**：主模型超时/5xx -> 自动切换备用模型 -> 记录错误日志。

### 3.4 AI 能力层

- **Agent 编排**：
    - 集成 **LangFlow** 或 **Dify** 作为可视化后端，前端自研管理界面。
    - 支持 Python/YAML 定义工作流，Docker 容器化执行。
- **MCP 支持**：
    - 实现 MCP Server 适配器，将内部 API 暴露为 MCP 资源/工具。
    - 支持 SSE/Stdio 传输协议。
- **Skills 市场**：
    - 发布流程：Git Repo -> 静态分析 -> 沙箱测试 -> 人工审核 -> 上架。
    - 交易：支持免费/付费/订阅，平台抽成 30%。
- **IMBot**：
    - 适配器模式：`WeChatAdapter`, `DingTalkAdapter`。
    - 消息队列：接收 Webhook -> Kafka -> Agent Runtime -> 回复。

---

## 4. 技术栈选型

| 领域 | 推荐技术 | 选型理由 |
| ------ |------ |------ |
| **后端框架** | **NestJS** (Node) 或 **FastAPI** (Python) | NestJS 适合网关/BFF，FastAPI 适合 AI 服务，生态丰富，Qoder 生成质量高 |
| **前端** | **Next.js** + **Shadcn/UI** | SSR 支持好，组件库美观，开发效率高 |
| **数据库** | **PostgreSQL** + **Redis** | PG 支持 JSONB 和 RLS，Redis 用于缓存/限流/队列 |
| **向量库** | **Milvus** 或 **ChromaDB** | 生产级向量检索，避免自研 |
| **消息队列** | **Kafka** 或 **RabbitMQ** | 解耦计费、日志、IM 消息处理 |
| **推理引擎** | **vLLM** | 高吞吐，PagedAttention，支持连续批处理 |
| **容器编排** | **Kubernetes** | 弹性伸缩，多租户隔离基础 |
| **监控** | **Prometheus** + **Grafana** | 行业标准，Qoder 可生成配置 |

---

## 5. 开发阶段规划

基于 Qoder 辅助开发，预计 **16 周** 完成 MVP：

| 阶段 | 周期 | 核心任务 | Qoder 重点指令 |
| ------ |------ |------ |------ |
| **P0: 骨架** | W1-2 | 项目初始化、DB Schema、Auth 模块、CI/CD | "生成 NestJS 多租户项目结构，包含 TypeORM 配置和 JWT 守卫" |
| **P1: 底座** | W3-6 | 用户中心、API Key 管理、基础 Dashboard | "实现 API Key 的 CRUD 接口，包含权限校验和数据库事务" |
| **P2: 中间件** | W7-10 | API Gateway、LLM Router、计费引擎 | "编写 LLM 路由插件，实现基于 Token 的实时扣费逻辑" |
| **P3: AI 能力** | W11-14 | Agent Runtime、Skills 市场、RAG 集成 | "集成 LangFlow，封装 Agent 执行接口，支持流式输出" |
| **P4: 交付** | W15-16 | 压力测试、安全审计、文档生成、部署 | "生成 K8s Helm Chart，编写 OpenAPI 文档，执行 JMeter 压测脚本" |

---

## 6. 给 Qoder 的具体指令建议

为确保 Qoder 生成的代码符合架构要求，请在 Prompt 中遵循以下规范：

### 6.1 代码规范

- **语言**：后端统一使用 TypeScript (NestJS) 或 Python (FastAPI)，禁止混用。
- **类型安全**：必须定义完整的 Interface/Type，禁止使用 `any`。
- **错误处理**：统一使用 `HttpException` 或自定义 `AppException`，禁止裸 `throw`。
- **日志**：使用 `Logger` 服务，关键操作（支付、权限变更）必须记录审计日志。

### 6.2 模块拆分指令

- **不要生成单体文件**：对于计费、路由等复杂模块，要求 Qoder 按 `Controller -> Service -> Repository -> Strategy` 分层。
- **配置外置**：所有密钥、URL、阈值必须从 `ConfigService` 读取，禁止硬编码。
- **接口先行**：先让 Qoder 生成 OpenAPI (Swagger) 定义，确认无误后再实现逻辑。

### 6.3 关键场景 Prompt 示例

**场景：实现 LLM 路由策略**
"请基于 Strategy 模式实现 LLM Provider Router。

**场景：实现计费扣费**
"实现一个基于 Redis + Lua 的原子扣费服务。

### 6.4 验收标准

- **测试覆盖率**：核心模块（计费、路由） > 80%。
- **文档**：每个模块必须有 `README.md` 和 Swagger 文档。
- **安全**：通过 `npm audit` / `pip-audit`，无高危漏洞。

---

**备注**：本文档为 Qoder 开发的上下文基准。在执行具体任务时，请始终引用本架构设计，避免偏离“核心自研、开源集成”的原则。对于未定义的边缘场景，优先选择 **PostgreSQL + Redis + Kafka** 组合，避免引入不必要的新技术栈。