# 🧠 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 平台早日上线！** 🚀