1279 lines
67 KiB
Markdown
1279 lines
67 KiB
Markdown
# 🧠 AI Hub 智能平台 — 总体架构设计与实施方案
|
||
|
||
> **文档版本**：v1.0
|
||
> **目标读者**：架构师 / 开发工程师 / 技术决策者
|
||
> **开发工具**：Trea / WorkBuddy / Qoder（AI 辅助编码）
|
||
> **适用对象**：非技术背景创始人 / 产品经理
|
||
|
||
---
|
||
|
||
## 一、项目愿景与核心定位
|
||
|
||
### 1.1 一句话定义
|
||
|
||
> **AI Hub 是一个「AI 能力操作系统」**——它既是用户的智能助手底座，也是开发者的技能分发市场，更是 AI 应用的一站式托管与计费平台。
|
||
|
||
### 1.2 三大支柱目标
|
||
|
||
| 支柱 | 核心命题 | 关键能力 |
|
||
|------|---------|---------|
|
||
| **🧠 智能引擎** | 越用越懂你，越用越快 | 长文本记忆、语义检索、知识自进化、个性化 Agent |
|
||
| **🏪 能力集市（Hub）** | 技能可创作、可交易、可复用 | Skills/MCP/Agent/App 发布、审核、版本、计费 |
|
||
| **🔌 应用工厂** | 任何 AI 项目可一键接入平台底座 | 统一认证、统一计费、统一模型库、SSO、Token 计量 |
|
||
|
||
### 1.3 设计哲学
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ "Lego 式" 平台设计 │
|
||
│ │
|
||
│ 所有能力 = 标准化积木（Skill / MCP / Agent / App） │
|
||
│ 平台 = 积木的连接器 + 供电系统 + 商店 │
|
||
│ 用户 = 搭积木的人（无代码 / 低代码优先） │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 二、整体系统架构（High-Level Architecture）
|
||
|
||
### 2.1 架构全景图
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────────┐
|
||
│ │
|
||
│ ┌───────────────────────┐ │
|
||
│ │ 用户端（Web/移动端） │ │
|
||
│ │ Next.js 18 + TS │ │
|
||
│ └───────────┬───────────┘ │
|
||
│ │ HTTPS │
|
||
│ ▼ │
|
||
│ ┌────────────────────────────────┐ │
|
||
│ │ API Gateway（Kong/Envoy） │ ◄── 限流/鉴权/路由 │
|
||
│ └────────┬───────────────┬───────┘ │
|
||
│ │ │ │
|
||
│ ┌────────────────┼───────────────┼────────────────┐ │
|
||
│ ▼ ▼ ▼ ▼ │
|
||
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
|
||
│ │ 认证与用户服务 │ │ 智能引擎服务 │ │ Hub 集市服务 │ │ 应用托管服务 │ │
|
||
│ │ (Auth/MS) │ │ (Memory/LLM) │ │ (Marketplace)│ │ (AppFactory) │ │
|
||
│ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ └──────┬───────┘ │
|
||
│ │ │ │ │ │
|
||
│ ▼ ▼ ▼ ▼ │
|
||
│ ┌──────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 共享基础设施层（Shared Infrastructure） │ │
|
||
│ │ │ │
|
||
│ │ PostgreSQL 18+pgvector │ Redis 7+ │ ClickHouse │ S3 │ Message Queue │ │
|
||
│ │ Vector DB(Qdrant) │ Keycloak │ Stripe │ Docker/K8s │ │
|
||
│ └──────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 技术栈选型总表
|
||
|
||
| 层级 | 技术选型 | 选型理由 |
|
||
|------|---------|---------|
|
||
| **前端框架** | Next.js 18 (App Router) + TypeScript | 全栈一体、SSR 友好、生态成熟 |
|
||
| **UI 组件库** | Ant Design 5.x / shadcn/ui | 企业级组件丰富 / 可定制性强 |
|
||
| **状态管理** | Zustand + TanStack Query | 轻量、适合 AI 流式场景 |
|
||
| **后端框架** | NestJS (TS) + FastAPI (Python) 双栈 | TS 统一前端/后端；Python 负责 AI/ML |
|
||
| **API 协议** | REST + WebSocket + MCP (Model Context Protocol) | 兼容传统 + 实时流式 + Agent 标准协议 |
|
||
| **数据库** | PostgreSQL 18 + pgvector 扩展 | 关系数据 + 向量检索一体化 |
|
||
| **缓存/会话** | Redis 7 Cluster | 高性能缓存、会话、限流、消息队列 |
|
||
| **向量数据库** | Qdrant（主） + pgvector（轻量） | 生产级向量检索 + 多租户命名空间隔离 |
|
||
| **OLAP/分析** | ClickHouse | 日志分析、用量统计、计费报表（参考 Langfuse 架构） |
|
||
| **对象存储** | MinIO / S3 | 文件、模型、向量索引备份 |
|
||
| **消息队列** | RabbitMQ / NATS | 异步任务、Agent 编排、事件驱动 |
|
||
| **API 网关** | Kong / Envoy | 统一入口、限流、鉴权、路由 |
|
||
| **身份认证** | Keycloak (OIDC/OAuth2) | 企业级 SSO、多租户、RBAC |
|
||
| **容器编排** | Docker Compose（开发/小规模）→ Kubernetes（生产） | 渐进式演进 |
|
||
| **CI/CD** | GitHub Actions + ArgoCD (GitOps) | 自动化构建部署 |
|
||
| **可观测性** | OpenTelemetry + Prometheus + Grafana + Langfuse | 全链路追踪、Metrics、日志 |
|
||
| **支付/计费** | Stripe（海外）+ 微信/支付宝（国内） | 双轨支付 |
|
||
| **AI 模型网关** | LiteLLM Proxy | 统一接入 OpenAI/Claude/Gemini/本地模型 |
|
||
| **Agent 编排** | LangGraph（Python）+ Langflow（可视化画布） | 多 Agent 编排 + 可视化 |
|
||
| **MCP 运行时** | MCP Gateway（自研）+ Docker 沙箱 | MCP Server 托管执行 |
|
||
|
||
---
|
||
|
||
## 三、支柱一：智能引擎（越用越懂你）
|
||
|
||
### 3.1 核心问题拆解
|
||
|
||
| 问题 | 解决方案 | 技术组件 |
|
||
|------|---------|---------|
|
||
| 长文本存储 | 分层存储：热数据（Redis）+ 温数据（PostgreSQL）+ 冷数据（S3） | Redis + PG + S3 |
|
||
| 语义检索 | 多向量 + 混合检索（BM25 + 向量） + Rerank | Qdrant + pgvector + Cohere Rerank |
|
||
| 用户数据隔离 | 租户级命名空间 + Row-Level Security | Qdrant Collection per tenant + PG RLS |
|
||
| 自进化记忆 | 记忆生命周期管理（感知→巩固→遗忘） | 自研 Memory Engine |
|
||
| 个性化 Agent | 用户画像 + 行为模式学习 + 动态 Prompt 注入 | User Profile Service |
|
||
|
||
### 3.2 长文本存储与语义检索架构
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 用户上传/对话内容 │
|
||
└──────────────────────────┬───────────────────────────────────────┘
|
||
▼
|
||
┌─────────────────────────┐
|
||
│ 文档预处理 Pipeline │
|
||
│ ┌───────────────────┐ │
|
||
│ │ 格式解析(PDF/Word/ │ │
|
||
│ │ MD/HTML/音视频) │ │
|
||
│ └────────┬──────────┘ │
|
||
│ ┌────────▼──────────┐ │
|
||
│ │ 智能分块(10-15% │ │
|
||
│ │ 重叠+语义边界) │ │
|
||
│ └────────┬──────────┘ │
|
||
│ ┌────────▼──────────┐ │
|
||
│ │ 多模型Embedding │ │
|
||
│ │ (text-embedding-3 │ │
|
||
│ │ + bge-large等) │ │
|
||
│ └────────┬──────────┘ │
|
||
└───────────┼─────────────┘
|
||
▼
|
||
┌────────────────────────────────────┐
|
||
│ 分层存储引擎 │
|
||
├────────────────────────────────────┤
|
||
│ L1 热缓存 → Redis（最近会话） │
|
||
│ L2 向量索引 → Qdrant（租户隔离） │
|
||
│ L3 结构化 → PostgreSQL + pgvector │
|
||
│ L4 原始文件 → S3/MinIO │
|
||
└────────────────┬───────────────────┘
|
||
▼
|
||
┌───────────────────────┐
|
||
│ 混合检索引擎 │
|
||
│ • BM25 关键词检索 │
|
||
│ • 向量相似度检索 │
|
||
│ • 图谱关系检索 │
|
||
│ → RRF 融合排序 │
|
||
│ → Rerank 精排 │
|
||
└───────────────────────┘
|
||
```
|
||
|
||
### 3.3 自进化记忆系统（核心创新）
|
||
|
||
参考认知科学的 **ACT-R 架构** 与 **艾宾浩斯遗忘曲线**，设计四层记忆体系：
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 用户记忆系统（Memory Engine） │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐ │
|
||
│ │ 感知层 │───▶│ 提炼层 │───▶│ 关联层 │ │
|
||
│ │ (Perception)│ │ (Distill) │ │ (Association) │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ • 对话解析 │ │ • 关键信息 │ │ • 知识图谱构建 │ │
|
||
│ │ • 意图识别 │ │ 抽取 │ │ • 跨会话关联 │ │
|
||
│ │ • 情感分析 │ │ • 实体识别 │ │ • 用户偏好建模 │ │
|
||
│ │ • 多模态 │ │ • 摘要压缩 │ │ • 行为模式学习 │ │
|
||
│ └─────────────┘ └─────────────┘ └────────┬────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────┐ │
|
||
│ │ 巩固/遗忘层 │ │
|
||
│ │ (Consolidation) │ │
|
||
│ │ │ │
|
||
│ │ • 记忆激活度评分 │ │
|
||
│ │ • 艾宾浩斯衰减 │ │
|
||
│ │ • 冲突检测解决 │ │
|
||
│ │ • 定期反思重组 │ │
|
||
│ └─────────────────┘ │
|
||
│ │
|
||
├─────────────────────────────────────────────────────────────────┤
|
||
│ 记忆类型： │
|
||
│ • 情景记忆（Episodic） → 用户说过什么、做过什么 │
|
||
│ • 语义记忆（Semantic） → 用户的知识领域、专业背景 │
|
||
│ • 程序记忆（Procedural）→ 用户习惯的交互模式、偏好工作流 │
|
||
│ • 情感记忆（Emotional） → 用户对什么话题敏感、什么风格喜欢 │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**自进化机制详解：**
|
||
|
||
1. **每次对话后** → 自动提取关键事实写入用户知识图谱
|
||
2. **每 N 轮对话** → 触发 Reflection Agent，归纳用户偏好模式
|
||
3. **每周/月** → 运行 Memory Consolidation Job，压缩冗余、解决冲突、强化高频
|
||
4. **实时检索时** → 根据当前上下文动态加权记忆（时间衰减 + 相关度 + 使用频率）
|
||
5. **跨会话学习** → 用户纠正一次，永久生效（"我不喜欢太长的回复" → 全局生效）
|
||
|
||
### 3.4 用户数据隔离方案
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 多租户隔离策略（Defense in Depth） │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ Layer 1: 应用层 → tenant_id 作为所有查询的强制参数 │
|
||
│ （SDK 层强制注入，无法绕过） │
|
||
│ │
|
||
│ Layer 2: 数据库层 → PostgreSQL Row-Level Security (RLS) │
|
||
│ 每个表自动附加 tenant_id 过滤策略 │
|
||
│ │
|
||
│ Layer 3: 向量层 → Qdrant 每租户独立 Collection/Namespace │
|
||
│ 物理隔离，杜绝跨租户检索 │
|
||
│ │
|
||
│ Layer 4: 缓存层 → Redis Key 前缀 = tenant_id: │
|
||
│ 缓存击穿也不泄露其他租户数据 │
|
||
│ │
|
||
│ Layer 5: 文件层 → S3 Bucket/Prefix 按租户隔离 │
|
||
│ 预签名 URL 带租户校验 │
|
||
│ │
|
||
│ Layer 6: 网络层 → K8s NetworkPolicy 限制跨命名空间访问 │
|
||
│ 生产环境可选 gVisor 沙箱 │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 3.5 智能引擎 — 自进化闭环
|
||
|
||
```
|
||
用户提问
|
||
│
|
||
▼
|
||
┌──────────────┐ 检索 ┌──────────────────┐
|
||
│ Coordinator │──────────▶│ 混合检索引擎 │
|
||
│ Agent │ │ (向量+BM25+图谱) │
|
||
└──────┬───────┘ └────────┬─────────┘
|
||
│ │
|
||
│ 注入用户画像+记忆 │ 返回相关上下文
|
||
▼ ▼
|
||
┌─────────────────────────────────────────┐
|
||
│ LLM 推理（LiteLLM 路由） │
|
||
│ • 自动选择最优模型（成本/质量/速度） │
|
||
│ • 动态注入用户记忆 + 知识库 + Skills │
|
||
└────────────┬────────────────────────────┘
|
||
│
|
||
▼
|
||
生成回复 + 触发后台记忆更新
|
||
│
|
||
┌─────────┴─────────┐
|
||
▼ ▼
|
||
返回用户 Memory Engine 异步处理
|
||
• 提取新事实
|
||
• 更新用户画像
|
||
• 刷新知识图谱
|
||
• 调整偏好权重
|
||
```
|
||
|
||
---
|
||
|
||
## 四、支柱二：Hub 能力集市
|
||
|
||
### 4.1 集市架构全景
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────────┐
|
||
│ Hub 集市架构 │
|
||
├──────────────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 用户/开发者门户 │ │
|
||
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
|
||
│ │ │Skills商店│ │MCP市场 │ │Agent画布 │ │应用商店 │ │我的创作 │ │ │
|
||
│ │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ │
|
||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ Hub 核心服务层 │ │
|
||
│ ├────────────┬────────────┬────────────┬────────────┬───────────────┤ │
|
||
│ │ 发布引擎 │ 审核引擎 │ 版本管理 │ 交易引擎 │ 部署引擎 │ │
|
||
│ │ Publish │ Review │ Versioning │ Billing │ Deployment │ │
|
||
│ │ │ │ │ │ │ │
|
||
│ │ • 上传/导入│ • 自动扫描 │ • SemVer │ • 免费/付费│ • GitHub URL │ │
|
||
│ │ • 元数据 │ • 沙箱测试 │ • 灰度发布 │ • 订阅制 │ • AI自动构建 │ │
|
||
│ │ • 分类标签 │ • 人工审核 │ • 回滚 │ • 分成结算 │ • Docker部署 │ │
|
||
│ │ • 搜索推荐 │ • 安全检测 │ • Changelog│ • 发票 │ • 健康检查 │ │
|
||
│ └────────────┴────────────┴────────────┴────────────┴───────────────┘ │
|
||
│ │
|
||
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
||
│ │ 可交易资产类型 │ │
|
||
│ ├────────────────────────────────────────────────────────────────────┤ │
|
||
│ │ 📦 Skill → 单一能力单元（如"PDF解析""情感分析"） │ │
|
||
│ │ 🔌 MCP Server → 标准协议服务（可自托管/平台托管） │ │
|
||
│ │ 🤖 Agent → 单/多Agent工作流 │ │
|
||
│ │ 🎨 Agent画布 → 可视化编排的多Agent协作流程 │ │
|
||
│ │ 📱 独立应用 → 完整AI应用（如MuMuAINovel小说助手） │ │
|
||
│ └────────────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 4.2 各类资产详细设计
|
||
|
||
#### 4.2.1 Skills（技能）
|
||
|
||
```yaml
|
||
# Skill 标准定义格式 (skill.yaml)
|
||
name: pdf-advanced-parser
|
||
version: 1.2.0
|
||
description: "支持复杂排版PDF的智能解析，保留表格/公式/图片结构"
|
||
author: user_12345
|
||
category: document-processing
|
||
tags: [pdf, ocr, table-extraction]
|
||
pricing:
|
||
model: freemium # free | freemium | paid | subscription
|
||
free_quota: 100 # 每月免费次数
|
||
paid_price: 0.05 # 每次调用价格(USD)
|
||
|
||
inputs:
|
||
- name: file_url
|
||
type: string
|
||
required: true
|
||
- name: extract_images
|
||
type: boolean
|
||
default: false
|
||
|
||
outputs:
|
||
- name: parsed_content
|
||
type: object
|
||
- name: markdown
|
||
type: string
|
||
|
||
runtime:
|
||
language: python
|
||
framework: fastapi
|
||
requirements: requirements.txt
|
||
entrypoint: main.py
|
||
resources:
|
||
cpu: "500m"
|
||
memory: "1Gi"
|
||
gpu: optional
|
||
|
||
permissions:
|
||
- file.read
|
||
- network.outbound
|
||
|
||
metadata:
|
||
avg_latency_ms: 2300
|
||
success_rate: 0.987
|
||
total_calls: 15420
|
||
rating: 4.7
|
||
```
|
||
|
||
#### 4.2.2 MCP Server（Model Context Protocol 服务）
|
||
|
||
**两种部署模式：**
|
||
|
||
```
|
||
模式A：平台托管（Platform-Hosted）
|
||
─────────────────────────────────────
|
||
开发者提交 → GitHub URL → 平台自动：
|
||
1. git clone 仓库
|
||
2. 解析 Dockerfile / docker-compose
|
||
3. 构建 Docker 镜像
|
||
4. 部署到 K8s（按租户/按需求隔离）
|
||
5. 暴露 HTTPS + SSE 端点
|
||
6. 自动健康检查 + 弹性伸缩
|
||
|
||
模式B：自托管（Self-Hosted）
|
||
─────────────────────────────────────
|
||
开发者自己部署 MCP Server
|
||
在平台注册 endpoint URL + API Key
|
||
平台作为代理路由 + 计费计量
|
||
```
|
||
|
||
**MCP Server 自动部署流水线：**
|
||
|
||
```
|
||
GitHub URL 输入
|
||
│
|
||
▼
|
||
┌─────────────────┐
|
||
│ 1. 仓库克隆 & 分析 │
|
||
│ • 检测语言/框架 │
|
||
│ • 解析依赖 │
|
||
│ • 识别 MCP 配置 │
|
||
└────────┬────────┘
|
||
▼
|
||
┌─────────────────┐
|
||
│ 2. 安全扫描 │
|
||
│ • 依赖漏洞扫描 │
|
||
│ • 代码静态分析 │
|
||
│ • 恶意行为检测 │
|
||
│ • 权限声明验证 │
|
||
└────────┬────────┘
|
||
▼
|
||
┌─────────────────┐
|
||
│ 3. 沙箱测试 │
|
||
│ • 启动临时容器 │
|
||
│ • 运行 MCP 协议 │
|
||
│ │ 握手测试 │
|
||
│ • 验证工具列表 │
|
||
│ • 性能基准测试 │
|
||
└────────┬────────┘
|
||
▼
|
||
┌─────────────────┐
|
||
│ 4. 构建 & 部署 │
|
||
│ • Docker 镜像构建│
|
||
│ • 推送到平台Registry│
|
||
│ • K8s Deployment │
|
||
│ • 配置 Ingress │
|
||
│ • 生成 API Endpoint│
|
||
└────────┬────────┘
|
||
▼
|
||
┌─────────────────┐
|
||
│ 5. 上线 & 监控 │
|
||
│ • 流量接入 │
|
||
│ • 用量计量 │
|
||
│ • 异常告警 │
|
||
│ • 自动扩缩容 │
|
||
└─────────────────┘
|
||
```
|
||
|
||
#### 4.2.3 Agent / 多 Agent 画布
|
||
|
||
**参考开源项目选型：**
|
||
|
||
| 工具 | 优势 | 适配场景 |
|
||
|------|------|---------|
|
||
| **Langflow**（推荐） | 140K+ Stars、MIT 协议、可导出为 MCP Server、Python 生态 | Agent 画布核心引擎 |
|
||
| **Flowise** | TypeScript 栈、人机协作审批节点、上手最快 | 备选/补充 |
|
||
| **n8n** | 150K+ Stars、自动化工作流最强、400+ 集成 | 复杂业务流程编排 |
|
||
|
||
**Agent 画布功能设计：**
|
||
|
||
```
|
||
┌────────────────────────────────────────────────────────────────┐
|
||
│ Agent 画布编辑器 │
|
||
├────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ ┌─ 左侧组件面板 ─────┐ ┌─ 中央画布 ──────────────────────┐ │
|
||
│ │ │ │ │ │
|
||
│ │ 📦 Skills │ │ ┌────────┐ ┌────────┐ │ │
|
||
│ │ 🔌 MCP Tools │ │ │ 用户输入│───▶│Router │ │ │
|
||
│ │ 🤖 Agent 节点 │ │ └────────┘ └───┬────┘ │ │
|
||
│ │ 📝 Prompt 模板 │ │ │ │ │
|
||
│ │ 🔀 条件分支 │ │ ┌──────────┼──────────┐ │ │
|
||
│ │ 🔄 循环/迭代 │ │ ▼ ▼ ▼ │ │
|
||
│ │ 💾 记忆节点 │ │ ┌────────┐ ┌────────┐ ┌────────┐│
|
||
│ │ 🌐 API 调用 │ │ │Agent A │ │Agent B │ │Agent C ││
|
||
│ │ ⏰ 定时触发 │ │ │(研究) │ │(写作) │ │(审核) ││
|
||
│ │ 🛡️ 人工审批 │ │ └────┬───┘ └────┬───┘ └───┬────┘│
|
||
│ │ │ │ └──────────┼──────────┘ │ │
|
||
│ └─────────────────────┘ │ ▼ │ │
|
||
│ │ ┌────────┐ │ │
|
||
│ │ │ 输出 │ │ │
|
||
│ │ └────────┘ │ │
|
||
│ └──────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌─ 右侧属性面板 ──────────────────────────────────────────┐ │
|
||
│ │ 选中节点 → 配置模型/参数/Prompt/Skills/权限 │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 功能：实时调试 | 单步执行 | 变量追踪 | 日志查看 | 性能分析 │
|
||
│ │
|
||
└────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
#### 4.2.4 独立应用接入（以 MuMuAINovel 为例）
|
||
|
||
**接入流程：**
|
||
|
||
```
|
||
步骤1：开发者在平台注册应用
|
||
┌─────────────────────────────────────────┐
|
||
│ App Name: MuMuAINovel │
|
||
│ GitHub URL: https://github.com/... │
|
||
│ Category: Creative Writing │
|
||
│ Pricing: Freemium │
|
||
└─────────────────────────────────────────┘
|
||
|
||
步骤2：平台自动注入标准化模块
|
||
┌──────────────────────────────────────────────────────────┐
|
||
│ 原应用 + 平台 SDK = 标准化接入 │
|
||
│ │
|
||
│ 注入内容： │
|
||
│ • @platform/auth-sdk → 单点登录/用户认证 │
|
||
│ • @platform/billing-sdk → Token 计量/订阅/计费 │
|
||
│ • @platform/model-router → 统一大模型库（不限原模型） │
|
||
│ • @platform/observability→ 日志/追踪/监控 │
|
||
│ • @platform/memory-sdk → 接入平台记忆系统 │
|
||
│ • docker-compose.platform.yml → 平台标准部署模板 │
|
||
└──────────────────────────────────────────────────────────┘
|
||
|
||
步骤3：审核 → 发布 → 上架应用商店
|
||
|
||
步骤4：用户一键安装/订阅 → 统一计费
|
||
```
|
||
|
||
### 4.3 审核与安全体系
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 四层审核防线 │
|
||
├──────────────┬──────────────┬──────────────┬───────────────────┤
|
||
│ Layer 1 │ Layer 2 │ Layer 3 │ Layer 4 │
|
||
│ 自动扫描 │ 沙箱动态测试 │ 人工审核 │ 持续监控 │
|
||
│ │ │ │ │
|
||
│ • 依赖漏洞 │ • 运行时行为 │ • 功能验证 │ • 异常用量检测 │
|
||
│ • 代码静态分析│ • 网络请求监控│ • 内容合规 │ • 用户投诉响应 │
|
||
│ • 恶意代码 │ • 资源消耗 │ • 质量评估 │ • 自动下架机制 │
|
||
│ • 权限声明 │ • 输出审核 │ • 安全复核 │ • 版本更新审核 │
|
||
│ • 病毒扫描 │ • 压力测试 │ │ │
|
||
└──────────────┴──────────────┴──────────────┴───────────────────┘
|
||
```
|
||
|
||
### 4.4 交易与计费模型
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 交易 & 计费架构 │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 计费维度： │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ • Token 消耗（输入 + 输出，按模型分别计价） │ │
|
||
│ │ • Skill 调用次数（按次/包月/订阅） │ │
|
||
│ │ • MCP Server 使用时长（按小时/按调用） │ │
|
||
│ │ • Agent 执行步数（按步/包月） │ │
|
||
│ │ • 应用订阅费（月费/年费/终身） │ │
|
||
│ │ • 存储用量（知识库大小） │ │
|
||
│ │ • 带宽用量（文件上传下载） │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 分成模式： │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ 平台 30% + 开发者 70%（标准应用商店模式） │ │
|
||
│ │ 优质开发者可降至 20/80 │ │
|
||
│ │ 平台自有 Skills 不抽成 │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 支付集成： │
|
||
│ ┌──────────────────────────────────────────────────────────┐ │
|
||
│ │ Stripe（国际信用卡/订阅） │ │
|
||
│ │ 微信支付 + 支付宝（国内） │ │
|
||
│ │ 平台虚拟币（充值→消费，降低支付摩擦） │ │
|
||
│ └──────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 五、支柱三：平台底座与标准化
|
||
|
||
### 5.1 统一架构标准
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────────┐
|
||
│ 平台标准化体系 │
|
||
├──────────────┬──────────────┬──────────────┬───────────────────────┤
|
||
│ API 标准 │ 数据标准 │ 部署标准 │ 开发标准 │
|
||
│ │ │ │ │
|
||
│ • RESTful │ • 统一数据 │ • Docker │ • Monorepo (pnpm) │
|
||
│ • GraphQL │ Schema │ Compose │ • 代码规范 (ESLint) │
|
||
│ • WebSocket │ • 事件格式 │ • K8s Helm │ • 提交规范 (Conven) │
|
||
│ • MCP 协议 │ • 日志格式 │ Charts │ • CI/CD 模板 │
|
||
│ • OpenAPI 3 │ • 追踪格式 │ • GitOps │ • 测试标准 (Jest) │
|
||
│ • 版本管理 │ • 错误码体系 │ • IaC (Pulumi)│ • 文档规范 (JSDoc) │
|
||
│ • 限流标准 │ • 元数据规范 │ • 蓝绿部署 │ • 安全扫描 (SAST) │
|
||
└──────────────┴──────────────┴──────────────┴───────────────────────┘
|
||
```
|
||
|
||
### 5.2 统一 API 网关设计
|
||
|
||
```yaml
|
||
# 统一 API 响应格式
|
||
response:
|
||
success: boolean
|
||
code: string # 业务错误码
|
||
message: string # 人类可读消息
|
||
data: object # 业务数据
|
||
meta: # 元数据
|
||
request_id: uuid # 全链路追踪ID
|
||
latency_ms: number # 响应耗时
|
||
quota_remaining: number # 剩余配额
|
||
rate_limit:
|
||
limit: number
|
||
remaining: number
|
||
reset_at: datetime
|
||
pagination: # 分页信息
|
||
page: number
|
||
per_page: number
|
||
total: number
|
||
```
|
||
|
||
### 5.3 认证与单点登录（SSO）
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ 统一身份认证架构 │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 认证方式： │
|
||
│ • 邮箱/密码（bcrypt + JWT） │
|
||
│ • OAuth 2.0（Google/GitHub/微信） │
|
||
│ • SSO/SAML（企业版） │
|
||
│ • Passkey/WebAuthn（无密码登录） │
|
||
│ │
|
||
│ 权限模型（RBAC + ABAC）： │
|
||
│ ┌────────────────────────────────────────────────────────────┐ │
|
||
│ │ Role: Super Admin / Tenant Admin / Developer / User / Guest│ │
|
||
│ │ │ │
|
||
│ │ Policy: 基于属性（租户/项目/资源/时间/地点）的动态授权 │ │
|
||
│ │ │ │
|
||
│ │ Scope: 细粒度 API Key 权限（读写/只读/按资源/按操作） │ │
|
||
│ └────────────────────────────────────────────────────────────┘ │
|
||
│ │
|
||
│ 实现方案：Keycloak（开源 OIDC 提供商） │
|
||
│ • 支持多租户隔离 │
|
||
│ • 支持 SSO/SAML/OAuth2/OpenID │
|
||
│ • 支持社交登录 │
|
||
│ • 支持 MFA/Passkey │
|
||
│ • 支持企业 LDAP/AD 集成 │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 5.4 大模型统一路由层（LiteLLM Proxy）
|
||
|
||
```
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ LiteLLM Proxy 统一模型网关 │
|
||
├──────────────────────────────────────────────────────────────────┤
|
||
│ │
|
||
│ 应用层 │
|
||
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
|
||
│ │Chat App│ │Agent │ │Skill │ │MCP │ │
|
||
│ └───┬────┘ └───┬────┘ └───┬────┘ └───┬────┘ │
|
||
│ └────────────┴────────────┴────────────┘ │
|
||
│ │ │
|
||
│ ▼ │
|
||
│ ┌─────────────────────┐ │
|
||
│ │ LiteLLM Proxy │ │
|
||
│ │ │ │
|
||
│ │ • 统一 OpenAI 格式 │ │
|
||
│ │ • 智能路由/降级 │ │
|
||
│ │ • 重试/超时/限流 │ │
|
||
│ │ • Token 计量/计费 │ │
|
||
│ │ • 敏感信息过滤 │ │
|
||
│ │ • 请求/响应缓存 │ │
|
||
│ │ • A/B 测试 │ │
|
||
│ └──────────┬──────────┘ │
|
||
│ │ │
|
||
│ ┌────────┬───────┼───────┬────────┐ │
|
||
│ ▼ ▼ ▼ ▼ ▼ │
|
||
│ ┌──────┐┌──────┐┌──────┐┌──────┐┌──────┐ │
|
||
│ │OpenAI││Claude││Gemini││本地 ││其他 │ │
|
||
│ │GPT-4o││3.5 ││1.5Pro││vLLM ││API │ │
|
||
│ └──────┘└──────┘└──────┘└──────┘└──────┘ │
|
||
│ │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## 六、开源项目借用清单
|
||
|
||
### 6.1 可直接借用的开源项目
|
||
|
||
| 项目 | 用途 | 协议 | 集成方式 |
|
||
|------|------|------|---------|
|
||
| **Langflow** | Agent 可视化画布 + 可导出 MCP | MIT | 嵌入平台作为 Agent 编辑器 |
|
||
| **n8n** | 复杂工作流自动化编排 | fair-code | 集成作为高级流程引擎 |
|
||
| **LiteLLM** | 统一模型网关/路由/计费 | MIT | 平台核心模型路由层 |
|
||
| **Langfuse** | LLM 可观测性/追踪/Eval | MIT | 嵌入平台作为监控面板 |
|
||
| **Keycloak** | 身份认证/SSO/RBAC | Apache 2.0 | 平台统一身份服务 |
|
||
| **Qdrant** | 向量数据库（多租户） | Apache 2.0 | 平台语义检索引擎 |
|
||
| **LangGraph** | 多 Agent 编排框架 | MIT | Python 后端 Agent 编排核心 |
|
||
| **LobeChat** | 开源 AI 聊天前端（参考 UI） | MIT | UI/UX 设计参考 + 部分组件 |
|
||
| **Flowise** | 备选可视化 Agent 构建器 | MIT | 备选/补充 |
|
||
| **Helicone** | LLM 请求代理/缓存/限流 | MIT | 备选网关方案 |
|
||
| **Dify** | 参考整体产品设计/API 设计 | Apache 2.0 | 架构参考/API 设计参考 |
|
||
| **RAGFlow** | 文档解析/分块（深度文档理解） | Apache 2.0 | 集成作为高级文档预处理 |
|
||
|
||
### 6.2 架构参考项目
|
||
|
||
| 项目 | 参考点 |
|
||
|------|--------|
|
||
| **Suna (Kortix)** | Monorepo 组织、Agent 后端架构、Docker 全栈部署 |
|
||
| **LobeHub MCP Marketplace** | MCP 集市架构、Capability Registry 设计 |
|
||
| **mipyao-ai-app-monorepo** | Next.js + NestJS + LangChain.js 全栈 RAG 架构 |
|
||
| **MuMuAINovel**（用户提供的项目） | 独立 AI 应用的标准化改造参考 |
|
||
|
||
---
|
||
|
||
## 七、数据库 Schema 设计（核心表）
|
||
|
||
### 7.1 核心数据模型
|
||
|
||
```sql
|
||
-- ============ 用户与租户 ============
|
||
CREATE TABLE tenants (
|
||
id UUID PRIMARY KEY,
|
||
name VARCHAR(255) NOT NULL,
|
||
plan VARCHAR(50) DEFAULT 'free',
|
||
quota_tokens BIGINT DEFAULT 0,
|
||
used_tokens BIGINT DEFAULT 0,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE users (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID REFERENCES tenants(id),
|
||
email VARCHAR(255) UNIQUE NOT NULL,
|
||
password_hash VARCHAR(255),
|
||
display_name VARCHAR(255),
|
||
avatar_url TEXT,
|
||
preferences JSONB DEFAULT '{}',
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- ============ 记忆系统 ============
|
||
CREATE TABLE memory_episodic (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
user_id UUID NOT NULL,
|
||
content TEXT NOT NULL,
|
||
embedding VECTOR(1536),
|
||
importance FLOAT DEFAULT 0.5,
|
||
decay_factor FLOAT DEFAULT 1.0,
|
||
last_accessed TIMESTAMP DEFAULT NOW(),
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
) PARTITION BY LIST (tenant_id);
|
||
|
||
CREATE TABLE memory_semantic (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
user_id UUID NOT NULL,
|
||
entity_type VARCHAR(100),
|
||
entity_value TEXT,
|
||
confidence FLOAT DEFAULT 1.0,
|
||
source_conversation_id UUID,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE user_profile (
|
||
user_id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
expertise_domains TEXT[],
|
||
communication_style JSONB,
|
||
preferences JSONB,
|
||
behavior_patterns JSONB,
|
||
updated_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- ============ 知识库 ============
|
||
CREATE TABLE knowledge_bases (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
user_id UUID NOT NULL,
|
||
name VARCHAR(255),
|
||
description TEXT,
|
||
chunk_strategy VARCHAR(50) DEFAULT 'semantic',
|
||
embedding_model VARCHAR(255),
|
||
total_documents INTEGER DEFAULT 0,
|
||
total_chunks INTEGER DEFAULT 0,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE documents (
|
||
id UUID PRIMARY KEY,
|
||
kb_id UUID REFERENCES knowledge_bases(id),
|
||
tenant_id UUID NOT NULL,
|
||
filename VARCHAR(500),
|
||
file_type VARCHAR(50),
|
||
storage_path TEXT,
|
||
chunk_count INTEGER,
|
||
status VARCHAR(50) DEFAULT 'processing',
|
||
metadata JSONB DEFAULT '{}',
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE document_chunks (
|
||
id UUID PRIMARY KEY,
|
||
doc_id UUID REFERENCES documents(id),
|
||
tenant_id UUID NOT NULL,
|
||
content TEXT NOT NULL,
|
||
embedding VECTOR(1536),
|
||
chunk_index INTEGER,
|
||
metadata JSONB DEFAULT '{}'
|
||
);
|
||
|
||
-- ============ Hub 集市 ============
|
||
CREATE TABLE hub_assets (
|
||
id UUID PRIMARY KEY,
|
||
type VARCHAR(50) NOT NULL, -- skill | mcp_server | agent | application
|
||
name VARCHAR(255) NOT NULL,
|
||
slug VARCHAR(255) UNIQUE,
|
||
description TEXT,
|
||
author_id UUID REFERENCES users(id),
|
||
version VARCHAR(50) DEFAULT '1.0.0',
|
||
category VARCHAR(100),
|
||
tags TEXT[],
|
||
pricing_model VARCHAR(50),
|
||
price DECIMAL(10,4) DEFAULT 0,
|
||
status VARCHAR(50) DEFAULT 'draft', -- draft | pending_review | approved | published | suspended
|
||
download_count INTEGER DEFAULT 0,
|
||
rating_avg DECIMAL(3,1) DEFAULT 0,
|
||
rating_count INTEGER DEFAULT 0,
|
||
deployment_config JSONB,
|
||
security_scan_result JSONB,
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
published_at TIMESTAMP
|
||
);
|
||
|
||
CREATE TABLE hub_asset_versions (
|
||
id UUID PRIMARY KEY,
|
||
asset_id UUID REFERENCES hub_assets(id),
|
||
version VARCHAR(50) NOT NULL,
|
||
changelog TEXT,
|
||
artifact_url TEXT,
|
||
docker_image TEXT,
|
||
is_latest BOOLEAN DEFAULT FALSE,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE hub_transactions (
|
||
id UUID PRIMARY KEY,
|
||
buyer_id UUID REFERENCES users(id),
|
||
asset_id UUID REFERENCES hub_assets(id),
|
||
transaction_type VARCHAR(50), -- purchase | subscription | usage
|
||
amount DECIMAL(10,4),
|
||
platform_fee DECIMAL(10,4),
|
||
developer_earnings DECIMAL(10,4),
|
||
stripe_payment_id VARCHAR(255),
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- ============ 用量与计费 ============
|
||
CREATE TABLE usage_records (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
user_id UUID,
|
||
service_type VARCHAR(50), -- chat | skill | mcp | agent | storage
|
||
asset_id UUID,
|
||
model_name VARCHAR(255),
|
||
input_tokens BIGINT DEFAULT 0,
|
||
output_tokens BIGINT DEFAULT 0,
|
||
cost_usd DECIMAL(10,6) DEFAULT 0,
|
||
request_id UUID,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- ============ Agent 编排 ============
|
||
CREATE TABLE agents (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
creator_id UUID REFERENCES users(id),
|
||
name VARCHAR(255),
|
||
description TEXT,
|
||
graph_definition JSONB NOT NULL, -- LangGraph 状态图定义
|
||
system_prompt TEXT,
|
||
model_config JSONB,
|
||
skill_bindings UUID[],
|
||
mcp_bindings UUID[],
|
||
is_published BOOLEAN DEFAULT FALSE,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- ============ 对话 ============
|
||
CREATE TABLE conversations (
|
||
id UUID PRIMARY KEY,
|
||
tenant_id UUID NOT NULL,
|
||
user_id UUID NOT NULL,
|
||
title VARCHAR(500),
|
||
agent_id UUID REFERENCES agents(id),
|
||
context_summary TEXT, -- 长对话压缩摘要
|
||
message_count INTEGER DEFAULT 0,
|
||
total_tokens BIGINT DEFAULT 0,
|
||
created_at TIMESTAMP DEFAULT NOW(),
|
||
updated_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
CREATE TABLE messages (
|
||
id UUID PRIMARY KEY,
|
||
conversation_id UUID REFERENCES conversations(id),
|
||
tenant_id UUID NOT NULL,
|
||
role VARCHAR(20), -- user | assistant | system | tool
|
||
content TEXT,
|
||
metadata JSONB DEFAULT '{}',
|
||
token_count INTEGER DEFAULT 0,
|
||
created_at TIMESTAMP DEFAULT NOW()
|
||
);
|
||
|
||
-- ============ 行级安全策略 ============
|
||
ALTER TABLE memory_episodic ENABLE ROW LEVEL SECURITY;
|
||
CREATE POLICY tenant_isolation ON memory_episodic
|
||
USING (tenant_id = current_setting('app.current_tenant')::UUID);
|
||
|
||
-- 对所有租户表重复此模式
|
||
```
|
||
|
||
---
|
||
|
||
## 八、项目目录结构
|
||
|
||
```
|
||
ai-hub-platform/
|
||
├── apps/
|
||
│ ├── web/ # Next.js 前端
|
||
│ │ ├── app/
|
||
│ │ │ ├── (auth)/ # 登录/注册/SSO
|
||
│ │ │ ├── (dashboard)/ # 主控台
|
||
│ │ │ │ ├── chat/ # AI 对话
|
||
│ │ │ │ ├── knowledge/ # 知识库管理
|
||
│ │ │ │ ├── agents/ # Agent 管理
|
||
│ │ │ │ ├── memory/ # 记忆可视化
|
||
│ │ │ │ └── settings/ # 用户设置
|
||
│ │ │ ├── hub/ # 能力集市
|
||
│ │ │ │ ├── skills/
|
||
│ │ │ │ ├── mcp/
|
||
│ │ │ │ ├── agents/
|
||
│ │ │ │ └── apps/
|
||
│ │ │ └── studio/ # Agent 画布编辑器
|
||
│ │ ├── components/
|
||
│ │ ├── lib/
|
||
│ │ └── package.json
|
||
│ │
|
||
│ ├── api/ # NestJS 主后端
|
||
│ │ ├── src/
|
||
│ │ │ ├── modules/
|
||
│ │ │ │ ├── auth/ # 认证模块
|
||
│ │ │ │ ├── user/ # 用户管理
|
||
│ │ │ │ ├── tenant/ # 租户管理
|
||
│ │ │ │ ├── memory/ # 记忆引擎
|
||
│ │ │ │ ├── knowledge/ # 知识库
|
||
│ │ │ │ ├── conversation/ # 对话管理
|
||
│ │ │ │ ├── agent/ # Agent 编排
|
||
│ │ │ │ ├── hub/ # 集市核心
|
||
│ │ │ │ ├── billing/ # 计费
|
||
│ │ │ │ └── gateway/ # API 网关
|
||
│ │ │ ├── shared/
|
||
│ │ │ │ ├── middleware/
|
||
│ │ │ │ ├── guards/
|
||
│ │ │ │ ├── interceptors/
|
||
│ │ │ │ └── decorators/
|
||
│ │ │ └── main.ts
|
||
│ │ └── package.json
|
||
│ │
|
||
│ └── ai-engine/ # Python AI 引擎
|
||
│ ├── src/
|
||
│ │ ├── memory_engine/ # 记忆系统
|
||
│ │ │ ├── perception.py
|
||
│ │ │ ├── distillation.py
|
||
│ │ │ ├── association.py
|
||
│ │ │ ├── consolidation.py
|
||
│ │ │ └── reflection.py
|
||
│ │ ├── retrieval/ # 混合检索
|
||
│ │ │ ├── vector_store.py
|
||
│ │ │ ├── bm25_index.py
|
||
│ │ │ ├── hybrid_search.py
|
||
│ │ │ └── reranker.py
|
||
│ │ ├── agent_runtime/ # Agent 执行
|
||
│ │ │ ├── coordinator.py
|
||
│ │ │ ├── planner.py
|
||
│ │ │ ├── executor.py
|
||
│ │ │ └── tool_registry.py
|
||
│ │ ├── model_router/ # 模型路由
|
||
│ │ │ └── litellm_wrapper.py
|
||
│ │ └── pipelines/
|
||
│ │ ├── ingest.py # 文档 ingestion
|
||
│ │ └── embed.py # 向量化
|
||
│ ├── pyproject.toml
|
||
│ └── Dockerfile
|
||
│
|
||
├── packages/ # 共享包
|
||
│ ├── sdk/ # 平台 SDK（供第三方应用接入）
|
||
│ │ ├── auth/
|
||
│ │ ├── billing/
|
||
│ │ ├── memory/
|
||
│ │ └── model-router/
|
||
│ ├── ui-kit/ # 共享 UI 组件
|
||
│ ├── config/ # 共享配置/规范
|
||
│ └── types/ # 共享 TS 类型定义
|
||
│
|
||
├── infra/ # 基础设施
|
||
│ ├── docker/
|
||
│ │ ├── docker-compose.dev.yaml
|
||
│ │ ├── docker-compose.prod.yaml
|
||
│ │ └── Dockerfile.*.tpl
|
||
│ ├── k8s/
|
||
│ │ ├── helm-charts/
|
||
│ │ ├── manifests/
|
||
│ │ └── kustomize/
|
||
│ ├── pulumi/ # IaC (Pulumi)
|
||
│ │ ├── index.ts
|
||
│ │ └── Pulumi.yaml
|
||
│ └── monitoring/
|
||
│ ├── prometheus/
|
||
│ ├── grafana/
|
||
│ └── otel-collector/
|
||
│
|
||
├── services/ # 独立微服务
|
||
│ ├── mcp-gateway/ # MCP 协议网关
|
||
│ ├── deployment-engine/ # GitHub → Docker 自动部署
|
||
│ ├── review-bot/ # 自动审核服务
|
||
│ └── billing-engine/ # 计费引擎
|
||
│
|
||
├── .github/
|
||
│ └── workflows/ # CI/CD
|
||
│ ├── ci.yaml
|
||
│ ├── deploy-staging.yaml
|
||
│ └── deploy-prod.yaml
|
||
│
|
||
├── docs/ # 文档
|
||
│ ├── architecture/
|
||
│ ├── api/
|
||
│ ├── developer-guide/
|
||
│ └── sdk-docs/
|
||
│
|
||
├── pnpm-workspace.yaml
|
||
├── package.json
|
||
├── tsconfig.base.json
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 九、分阶段实施路线图
|
||
|
||
### Phase 1：MVP 底座（第 1-3 月）
|
||
|
||
**目标**：跑通核心闭环——用户注册 → 对话 → 知识库 → 记忆积累
|
||
|
||
| 周次 | 任务 | 产出 |
|
||
|------|------|------|
|
||
| W1-2 | 项目初始化、Monorepo 搭建、CI/CD | 可运行的空骨架 |
|
||
| W3-4 | 用户认证（Keycloak 集成）、租户隔离 | 注册/登录/SSO 可用 |
|
||
| W5-6 | 对话引擎（LiteLLM + 基础 RAG） | 可对话 + 简单知识库 |
|
||
| W7-8 | 向量检索（Qdrant 集成）、文档上传 | 知识库语义检索可用 |
|
||
| W9-10 | 记忆引擎 V1（对话摘要 + 用户画像） | 跨会话记忆生效 |
|
||
| W11-12 | 前端主控台、计费埋点 | MVP 可演示 |
|
||
|
||
**技术验证清单**：
|
||
- [ ] 用户 A 上传文档 → 对话时能检索到相关内容
|
||
- [ ] 用户 A 的对话记忆不会泄露给用户 B（租户隔离验证）
|
||
- [ ] 用户第二次对话时，AI 记得之前的偏好
|
||
- [ ] Token 消耗被正确计量并展示
|
||
|
||
### Phase 2：Hub 集市 V1（第 4-6 月）
|
||
|
||
**目标**：Skills 和 MCP Server 可发布、可发现、可调用
|
||
|
||
| 周次 | 任务 | 产出 |
|
||
|------|------|------|
|
||
| W13-14 | 集市前端（浏览/搜索/详情页） | 商店 UI 上线 |
|
||
| W15-16 | Skill 发布流程 + 审核流水线 | 开发者可上传 Skill |
|
||
| W17-18 | MCP Gateway + GitHub URL 自动部署 | 输入 GitHub URL → 自动上线 |
|
||
| W19-20 | 交易引擎 + Stripe 集成 | 付费 Skill 可购买 |
|
||
| W21-22 | 版本管理 + 评分评论 | 完整集市闭环 |
|
||
| W23-24 | 安全扫描 + 沙箱测试自动化 | 上架前自动审核 |
|
||
|
||
### Phase 3：Agent 画布 + 自进化（第 7-9 月）
|
||
|
||
**目标**：可视化 Agent 编排 + 记忆系统全面自进化
|
||
|
||
| 周次 | 任务 | 产出 |
|
||
|------|------|------|
|
||
| W25-26 | 集成 Langflow 作为 Agent 编辑器 | 拖拽式 Agent 编排 |
|
||
| W27-28 | 多 Agent 协作（LangGraph 后端） | 复杂工作流可执行 |
|
||
| W29-30 | 记忆引擎 V2（反思/巩固/遗忘） | AI 越用越懂你 |
|
||
| W31-32 | 用户认知模型（行为模式学习） | 个性化推荐生效 |
|
||
| W33-34 | Agent 画布导出为 MCP Server | 创作即可分发 |
|
||
| W35-36 | Eval 系统（Langfuse 集成） | 质量可量化 |
|
||
|
||
### Phase 4：应用工厂 + 规模化（第 10-12 月）
|
||
|
||
**目标**：第三方应用可一键接入 + 平台规模化
|
||
|
||
| 周次 | 任务 | 产出 |
|
||
|------|------|------|
|
||
| W37-38 | 平台 SDK 开发（Auth/Billing/Memory/Model） | 标准化接入工具包 |
|
||
| W39-40 | MuMuAINovel 接入示范（改造为平台应用） | 首个接入应用上线 |
|
||
| W41-42 | 应用商店 UI + 订阅管理 | 应用可上架/购买 |
|
||
| W43-44 | K8s 生产部署 + 自动扩缩容 | 可承载千级并发 |
|
||
| W45-46 | 监控告警 + SLA 保障 | 99.9% 可用性 |
|
||
| W47-48 | 文档完善 + 开发者社区启动 | 开放生态 |
|
||
|
||
---
|
||
|
||
## 十、给非技术创始人的执行建议
|
||
|
||
### 10.1 团队配置建议
|
||
|
||
| 角色 | 人数 | 职责 | 何时需要 |
|
||
|------|------|------|---------|
|
||
| **技术合伙人 / 架构师** | 1 | 整体技术决策、代码审查、关键技术攻关 | 第 1 天 |
|
||
| **全栈工程师** | 2-3 | Next.js + NestJS 前后端开发 | 第 1 月 |
|
||
| **Python/AI 工程师** | 1-2 | 记忆引擎、检索、Agent 编排 | 第 2 月 |
|
||
| **DevOps 工程师** | 1 | Docker/K8s/CI-CD/监控 | 第 3 月 |
|
||
| **UI/UX 设计师** | 1 | 产品设计、交互设计 | 第 1 月 |
|
||
| **安全工程师**（兼职） | 1 | 安全审计、渗透测试 | 第 4 月 |
|
||
|
||
### 10.2 AI 辅助开发工具使用指南
|
||
|
||
由于你使用 **Trea / WorkBuddy / Qoder**，以下是最大化效率的方法：
|
||
|
||
```
|
||
1. 每个模块给 AI 工具提供：
|
||
├── 本架构文档（让它理解全局）
|
||
├── 对应模块的详细 specs（在 docs/ 中）
|
||
├── 标准代码模板（在 packages/config/ 中）
|
||
└── 明确的验收标准（可测试的 checklist）
|
||
|
||
2. 推荐工作流：
|
||
架构师出方案 → 产品经理写 specs → AI 工具生成代码 → 工程师审查+调试
|
||
|
||
3. 关键原则：
|
||
• AI 工具生成代码后，必须人工审查安全相关代码
|
||
• 数据库 migration 必须人工确认
|
||
• 支付/计费代码必须双人审查
|
||
• 每个 PR 必须有测试覆盖
|
||
```
|
||
|
||
### 10.3 关键技术风险与应对
|
||
|
||
| 风险 | 影响 | 应对策略 |
|
||
|------|------|---------|
|
||
| 租户数据泄露 | 灾难性 | 多层隔离 + 定期渗透测试 + RLS 审计 |
|
||
| AI 成本失控 | 资金风险 | 严格限流 + 模型路由优化 + 缓存命中率监控 |
|
||
| 集市恶意代码 | 平台信誉 | 四层审核 + 沙箱隔离 + 紧急下架机制 |
|
||
| 模型依赖风险 | 业务中断 | 多模型备份 + LiteLLM 自动降级 + 本地模型兜底 |
|
||
| 自进化失控 | 用户体验 | 记忆衰减 + 用户可查看/编辑/删除记忆 + 人工审核接口 |
|
||
|
||
---
|
||
|
||
## 十一、核心 API 接口设计（示例）
|
||
|
||
### 11.1 对话接口
|
||
|
||
```typescript
|
||
// POST /api/v1/chat/completions
|
||
interface ChatRequest {
|
||
conversation_id?: string;
|
||
message: string;
|
||
agent_id?: string;
|
||
context?: {
|
||
knowledge_base_ids?: string[];
|
||
skill_ids?: string[];
|
||
memory_enabled?: boolean;
|
||
};
|
||
stream?: boolean; // SSE 流式
|
||
}
|
||
|
||
interface ChatResponse {
|
||
success: boolean;
|
||
data: {
|
||
message_id: string;
|
||
content: string;
|
||
reasoning_steps?: ReasoningStep[];
|
||
used_skills?: string[];
|
||
token_usage: {
|
||
input: number;
|
||
output: number;
|
||
total_cost_usd: number;
|
||
};
|
||
memory_updates?: MemoryUpdate[];
|
||
};
|
||
meta: {
|
||
request_id: string;
|
||
latency_ms: number;
|
||
quota_remaining: number;
|
||
};
|
||
}
|
||
```
|
||
|
||
### 11.2 Hub 发布接口
|
||
|
||
```typescript
|
||
// POST /api/v1/hub/assets/publish
|
||
interface PublishRequest {
|
||
type: 'skill' | 'mcp_server' | 'agent' | 'application';
|
||
name: string;
|
||
description: string;
|
||
source: {
|
||
type: 'github_url' | 'upload' | 'platform_built';
|
||
url?: string;
|
||
files?: UploadedFile[];
|
||
};
|
||
pricing: {
|
||
model: 'free' | 'freemium' | 'paid' | 'subscription';
|
||
price?: number;
|
||
free_quota?: number;
|
||
};
|
||
metadata: {
|
||
category: string;
|
||
tags: string[];
|
||
permissions: string[];
|
||
};
|
||
}
|
||
|
||
// 响应
|
||
interface PublishResponse {
|
||
success: boolean;
|
||
data: {
|
||
asset_id: string;
|
||
status: 'pending_review' | 'auto_approved';
|
||
review_pipeline: {
|
||
security_scan: 'queued' | 'running' | 'passed' | 'failed';
|
||
sandbox_test: 'queued' | 'running' | 'passed' | 'failed';
|
||
manual_review: 'pending' | 'approved' | 'rejected';
|
||
};
|
||
estimated_publish_time: string;
|
||
};
|
||
}
|
||
```
|
||
|
||
### 11.3 记忆检索接口
|
||
|
||
```typescript
|
||
// GET /api/v1/memory/retrieve
|
||
interface MemoryQuery {
|
||
query: string;
|
||
memory_types?: ('episodic' | 'semantic' | 'procedural')[];
|
||
top_k?: number;
|
||
time_range?: { from: string; to: string };
|
||
min_relevance?: number;
|
||
}
|
||
|
||
// 响应
|
||
interface MemoryRetrieveResponse {
|
||
success: boolean;
|
||
data: {
|
||
memories: Array<{
|
||
id: string;
|
||
type: string;
|
||
content: string;
|
||
relevance_score: number;
|
||
created_at: string;
|
||
source: string; // 来自哪次对话/哪个文档
|
||
}>;
|
||
synthesized_context: string; // AI 自动综合的上下文摘要
|
||
};
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 十二、总结：技术决策一览
|
||
|
||
| 决策点 | 选择 | 理由（一句话） |
|
||
|--------|------|---------------|
|
||
| 前端框架 | Next.js 18 | 全栈一体、SSR、生态最成熟 |
|
||
| 后端主框架 | NestJS (TS) | 与前端统一语言、模块化强、企业级 |
|
||
| AI/ML 引擎 | Python (FastAPI) | AI 生态几乎全是 Python |
|
||
| 数据库 | PostgreSQL 18 + pgvector | 关系 + 向量一体、RLS 天然多租户 |
|
||
| 向量数据库 | Qdrant | 多租户命名空间、Rust 性能、开源 |
|
||
| 缓存/队列 | Redis 7 Cluster | 缓存/会话/限流/消息 四位一体 |
|
||
| 分析引擎 | ClickHouse | 海量日志/用量分析、Langfuse 验证过 |
|
||
| 身份认证 | Keycloak | 企业级 SSO、多租户、开源可控 |
|
||
| 模型网关 | LiteLLM Proxy | 统一格式、智能路由、内置计费 |
|
||
| Agent 编排 | LangGraph + Langflow | 编程式 + 可视化双模式 |
|
||
| 容器编排 | Docker → K8s | 渐进式演进、行业标准 |
|
||
| 可观测性 | OpenTelemetry + Langfuse | 全链路追踪、AI 专项指标 |
|
||
| 支付 | Stripe + 微信/支付宝 | 全球覆盖 + 国内合规 |
|
||
| CI/CD | GitHub Actions + ArgoCD | GitOps 最佳实践 |
|
||
| IaC | Pulumi (TS) | 用 TypeScript 写基础设施 |
|
||
|
||
---
|
||
|
||
> **最后的话**：这份架构设计的核心理念是——**不要重复造轮子，但要掌握轮子的接口**。所有能借用的开源项目都已经标注，你的团队应该专注于**业务逻辑、用户体验和生态建设**，而不是底层基础设施的重复开发。
|
||
>
|
||
> 用 AI 编程工具（Trea/WorkBuddy/Qoder）时，把这份文档作为「系统上下文」喂给 AI，它能生成更符合整体架构的代码。每一步都先有设计、再有代码、最后有测试。
|
||
>
|
||
> **祝你的 AI Hub 平台早日上线！** 🚀
|