# AI PaaS 商业平台 — 产品需求文档（PRD）

> 版本: 1.0 | 日期: 2026-06-27
> 产品名: **AIPaaS**（AI能力服务平台）
> 目标用户: 个人开发者 / AI 爱好者 / 小型团队

---

## 1. 产品定位

**一句话描述**: 让任何开发者都能像用水电一样使用 AI 能力——注册即用，按量付费。

**核心价值**:
- **统一入口**: Agent、MCP、Skills、IM Bot、LLM 调用，一个平台全搞定
- **按需付费**: 不买服务器，不养团队，按 Token 用量付费
- **能力交易**: 开发者发布 AI 技能，用户购买使用，平台促成交易
- **多平台接入**: 一个 API Key 调用 DeepSeek/千问/豆包/百度/元宝/智谱

---

## 2. 用户角色

| 角色 | 说明 | 典型操作 |
|------|------|---------|
| **平台管理员** | 平台运营者 | 审核能力、管理用户、配置系统、查看收入 |
| **租户（开发者）** | 注册开发者，创建和发布 AI 能力 | 创建 Agent、发布 Skill、管理 API Key、查看用量 |
| **终端用户** | 使用 AI 能力的最终用户 | 调用 API、购买 Skill、通过 IM Bot 对话 |

---

## 3. 功能模块

### 3.1 用户认证与多租户（Auth）

#### 3.1.1 注册/登录

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 邮箱注册 | 邮箱 + 密码注册，发送验证邮件 | P0 |
| GitHub OAuth | 第三方登录 | P1 |
| 微信扫码登录 | 第三方登录 | P2 |
| 登录 | 邮箱 + 密码，返回 JWT | P0 |
| Token 刷新 | Access Token 过期后用 Refresh Token 续期 | P0 |
| 忘记密码 | 邮箱重置密码 | P0 |

#### 3.1.2 多租户

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 租户隔离 | 每个用户/团队是独立租户，数据严格隔离 | P0 |
| 角色体系 | owner / admin / developer / user 四级角色 | P0 |
| 团队管理 | 邀请成员、分配角色（Phase 2） | P1 |

#### 3.1.3 API Key 管理

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 创建 Key | 用户创建 API Key，用于程序化调用 | P0 |
| 删除 Key | 可随时删除，立即失效 | P0 |
| Key 列表 | 查看所有 Key 的创建时间、最后使用时间 | P0 |
| 用途标识 | 给每个 Key 标记用途（如"我的应用"） | P1 |

---

### 3.2 LLM 智能路由（LLM Router）

#### 3.2.1 多平台对接

| 平台 | 协议 | 模型列表 | 优先级 |
|------|------|---------|--------|
| DeepSeek | OpenAI 兼容 | deepseek-chat, deepseek-reasoner | P0 |
| 千问（阿里云） | OpenAI 兼容 | qwen-turbo, qwen-plus, qwen-max | P0 |
| 豆包（字节） | OpenAI 兼容 | doubao-pro, doubao-lite | P0 |
| 智谱 GLM | OpenAI 兼容 | glm-4, glm-4-flash | P0 |
| 元宝（腾讯） | OpenAI 兼容 | yuanbao-pro, yuanbao-lite | P1 |
| 百度文心 | 自定义（需适配层） | ernie-4.0, ernie-3.5 | P1 |
| 本地 Ollama | OpenAI 兼容 | 用户自定义 | P1 |

#### 3.2.2 智能路由

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 用户选择 | 用户指定使用哪个平台/模型 | P0 |
| 成本优先 | 自动选择当前最便宜的模型 | P1 |
| 延迟优先 | 自动选择响应最快的模型 | P1 |
| 故障转移 | 主模型不可用时自动切换备用模型 | P0 |
| 负载均衡 | 同一模型多个 API Key 时轮询 | P2 |

#### 3.2.3 调用方式

```
POST /v1/chat/completions    ← OpenAI 兼容格式，用户直接用
GET  /v1/models              ← 可用模型列表
POST /v1/embeddings          ← 向量嵌入（Phase 2）
```

---

### 3.3 计费系统（Billing）

#### 3.3.1 Credit 模型

| 概念 | 说明 |
|------|------|
| **Credit** | 内部统一计费单位，1 Credit = 1000 tokens |
| **模型系数** | 不同模型消耗不同: deepseek-chat=1.0, deepseek-reasoner=2.0, doubao-pro=1.5 |
| **余额** | 租户 Credit 余额，先扣后服 |
| **充值** | 支持手动充值（支付宝/微信支付） |
| **订阅** | 每月固定 Credit 额度，超出按量计费 |

#### 3.3.2 订阅套餐

| 套餐 | 月费 | 包含 Credits | 超出价格 | QPS 限制 |
|------|------|-------------|---------|---------|
| **Free** | ¥0 | 100 | 不允许超出 | 2 |
| **Pro** | ¥99 | 50,000 | ¥0.01/Credit | 20 |
| **Team** | ¥499 | 300,000 | ¥0.008/Credit | 100 |
| **Enterprise** | 定制 | 定制 | 定制 | 定制 |

#### 3.3.3 计费流程

```
用户调用 API
    ↓
1. API Key 验证 → 提取 tenant_id
    ↓
2. 余额检查 → 余额不足返回 402
    ↓
3. 预扣费（预留最大可能消耗）
    ↓
4. 调用 LLM Router → 获取实际消耗
    ↓
5. 结算（实际消耗 vs 预扣，多退少补）
    ↓
6. 记录流水（不可变审计日志）
    ↓
7. 返回结果 + 用量信息
```

#### 3.3.4 核心原则

| 原则 | 说明 |
|------|------|
| **先扣后服** | 先扣减余额，再允许调用，绝不允许"调用成功但余额为负" |
| **幂等** | 同一请求多次重试，绝不重复扣费 |
| **原子** | Redis Lua 脚本保证扣费操作原子性 |
| **可审计** | 每笔 Credit 变动都有 trace_id + 原因 |
| **实时可见** | Dashboard 上余额和用量秒级更新 |

---

### 3.4 能力注册中心（Capability Registry）

#### 3.4.1 能力类型

| 类型 | 说明 | 示例 |
|------|------|------|
| **agent** | AI 智能体 | 客服机器人、代码助手、翻译器 |
| **mcp** | MCP 协议服务 | 文件操作、数据库查询、API 调用 |
| **skill** | 可交易技能 | 文案生成、图片分析、数据分析 |
| **llm** | LLM 提供商 | DeepSeek、千问、豆包 |
| **custom** | 自定义 OpenAPI 应用 | 用户自己的 API 服务 |

#### 3.4.2 能力生命周期

```
draft (草稿) → pending_review (待审核) → active (活跃) → deprecated (弃用)
                                        ↘ rejected (拒绝)
```

#### 3.4.3 能力元数据

```yaml
name: "智能客服 Agent"
type: agent
version: "1.2.0"
description: "基于 GPT-4 的智能客服，支持多轮对话和知识库检索"
tags: [客服, 多轮对话, 知识库]
endpoint: "https://my-agent.example.com/api"
protocol: rest
pricing:
  model: per_token
  rate: 2  # 每 1000 tokens 消耗 2 Credits
dependencies:
  - capability_id: "milvus-rag"
    version: ">=1.0.0"
status: active
```

---

### 3.5 Skills 市场

#### 3.5.1 核心功能

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 发布技能 | 开发者上传技能，填写描述、定价、示例 | P0 |
| 浏览市场 | 按分类、标签、评分、热度浏览 | P0 |
| 搜索技能 | 全文搜索 + 分类过滤 | P0 |
| 购买技能 | 用 Credit 购买，立即可用 | P0 |
| 已购管理 | 查看已购技能列表 | P0 |
| 技能评分 | 用户评分和评论 | P1 |
| 技能试用 | 免费试用 N 次 | P1 |

#### 3.5.2 计费模式

| 模式 | 说明 | 分成 |
|------|------|------|
| per_call | 每次调用扣费 | 平台 25% / 开发者 75% |
| per_token | 按 Token 扣费 | 平台 25% / 开发者 75% |
| subscription | 订阅制（月/年） | 平台 25% / 开发者 75% |
| free | 免费 | 无 |

#### 3.5.3 技能详情页内容

```
名称 / 作者 / 版本 / 价格
简介 / 详细描述
功能列表 / 使用示例
API 文档 / 调用示例
评分 / 评论 / 使用次数
```

---

### 3.6 IM Bot 网关

#### 3.6.1 支持平台

| 平台 | 协议 | 优先级 | 说明 |
|------|------|--------|------|
| 微信 | LangBot / OpenClaw | P0 | 个人微信，扫码登录 |
| QQ | OneBot v11 | P1 | go-cqhttp |
| 钉钉 | 钉钉开放平台 | P1 | 企业机器人 |
| 飞书 | 飞书开放平台 | P2 | 企业机器人 |
| Telegram | Bot API | P2 | 个人机器人 |

#### 3.6.2 核心功能

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 多轮对话 | 维护会话上下文（Redis，24h 过期） | P0 |
| 模型选择 | 用户可切换不同 LLM 模型 | P0 |
| 指令系统 | /help /model /clear /balance 等快捷指令 | P0 |
| 消息格式 | 文本 / Markdown / 图片 | P0 |
| 按钮交互 | 平台支持时提供按钮选择 | P1 |
| 文件处理 | 接收和发送文件（图片、文档） | P2 |

#### 3.6.3 会话管理

```
每个用户 + 每个平台 = 独立会话
会话存储: Redis Hash
上下文窗口: 最近 20 条消息
过期时间: 24 小时无活动自动清除
```

---

### 3.7 用户 Dashboard

#### 3.7.1 页面结构

```
Dashboard
├── 首页概览
│   ├── Credit 余额卡片
│   ├── 今日/本月用量趋势图
│   ├── 快捷操作按钮
│   └── 最近调用记录
├── API Key 管理
│   ├── Key 列表（创建时间/最后使用/状态）
│   ├── 创建新 Key
│   └── 删除 Key
├── 用量详情
│   ├── 按日/周/月图表
│   ├── 按模型分类统计
│   ├── 按能力分类统计
│   └── 导出 CSV
├── 账单中心
│   ├── Credit 流水记录
│   ├── 订阅管理（升级/降级/取消）
│   └── 充值历史
├── 我的能力
│   ├── 已创建的能力列表
│   ├── 创建新能力
│   └── 能力统计（调用量/收入）
├── 市场
│   ├── 浏览技能
│   ├── 搜索技能
│   └── 已购技能
└── 设置
    ├── 个人信息
    ├── 修改密码
    └── 通知偏好
```

#### 3.7.2 首页概览卡片

```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Credit 余额   │ │ 今日调用次数  │ │ 今日消耗      │ │ 当前套餐      │
│ 12,580       │ │ 342 次       │ │ 1,280 Credits│ │ Pro          │
│ [充值] [升级] │ │ ↑12% vs 昨日 │ │ ↓5% vs 昨日  │ │ 到期: 07-27  │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
```

---

### 3.8 管理后台

#### 3.8.1 页面结构

```
Admin Console
├── 仪表盘
│   ├── 核心指标（用户数/API调用量/收入）
│   ├── 趋势图表
│   └── 系统状态
├── 用户管理
│   ├── 用户列表（搜索/过滤/分页）
│   ├── 用户详情
│   └── 封禁/解封
├── 租户管理
│   ├── 租户列表
│   ├── 租户详情（订阅/用量/余额）
│   └── 调整余额
├── 能力审核
│   ├── 待审核列表
│   ├── 审核详情
│   └── 通过/拒绝
├── 系统配置
│   ├── LLM 提供商配置
│   ├── 订阅套餐配置
│   └── 全局限流配置
└── 数据分析
    ├── API 调用趋势
    ├── 热门能力排行
    └── 收入报表
```

---

### 3.9 MCP Hub 集成

| 功能 | 说明 | 优先级 |
|------|------|--------|
| MCP Server 注册 | 开发者注册自己的 MCP Server | P0 |
| 工具列表 | 查看已注册 MCP Server 提供的工具 | P0 |
| 工具调用 | 通过平台调用 MCP 工具（经过计费） | P0 |
| Server 市场 | 浏览和使用社区 MCP Server | P1 |

---

### 3.10 Agent 编排（LangFlow 集成）

| 功能 | 说明 | 优先级 |
|------|------|--------|
| 可视化编辑器 | 嵌入 LangFlow 的 Flow 编辑器 | P1 |
| Flow 发布 | 将 Flow 发布为可调用的 Agent | P0 |
| Flow 运行 | API 调用运行 Flow（经过计费） | P0 |
| Flow 模板 | 预置常用 Flow 模板 | P2 |

---

### 3.11 ACP 协议（Phase 4）

| 功能 | 说明 | 优先级 |
|------|------|--------|
| Agent 发现 | 发现已注册的 Agent | P1 |
| Agent 通信 | Agent 间发送消息 | P1 |
| 工作流编排 | 多 Agent 协作完成复杂任务 | P2 |

---

## 4. 非功能需求

### 4.1 性能要求

| 指标 | 目标值 |
|------|--------|
| API 响应时间 (P95) | < 200ms（不含 LLM 调用） |
| LLM 调用响应时间 (P95) | < 5s（流式首 token < 1s） |
| 并发用户数 | 1000+ |
| API QPS | 500+ |
| 计费延迟 | < 100ms（Redis Lua） |

### 4.2 安全要求

| 要求 | 说明 |
|------|------|
| 数据加密 | 传输 HTTPS，存储敏感字段 AES-256 |
| 多租户隔离 | PostgreSQL RLS，数据严格隔离 |
| API Key 安全 | 哈希存储，仅展示一次 |
| 限流防刷 | 按租户/Key 限流，防止滥用 |
| 审计日志 | 所有关键操作可追溯 |

### 4.3 可用性要求

| 指标 | 目标值 |
|------|--------|
| 系统可用性 | 99.9% |
| 数据备份 | 每日自动备份 |
| 故障恢复 | RPO < 1h, RTO < 4h |

---

## 5. Phase 交付范围

### Phase 1（Week 1-4）: 基座
- ✅ 注册/登录/鉴权
- ✅ 多租户隔离
- ✅ 数据库 Schema
- ✅ API Gateway 基础路由
- ✅ 项目骨架可运行

### Phase 2（Week 5-8）: 核心引擎
- ✅ LLM Router（7 个平台对接）
- ✅ Token 计费引擎
- ✅ 用量追踪
- ✅ OpenAI 兼容 API
- ✅ 流式响应 SSE

### Phase 3（Week 9-12）: 能力治理
- ✅ Capability Registry
- ✅ Skills 市场
- ✅ 用户 Dashboard
- ✅ 管理后台

### Phase 4（Week 13-16）: 生态扩展
- ✅ IM Bot 网关（微信/QQ/钉钉）
- ✅ MCP Hub 集成
- ✅ LangFlow Agent 集成
- ✅ ACP 协议基础

### Phase 5（Week 17-20）: 集成上线
- ✅ 全链路测试
- ✅ 生产部署
- ✅ 监控告警
- ✅ 完整文档

---

*文档结束*