diff --git a/元宝 - AI_Hub_Platform_Architecture.md b/元宝 - AI_Hub_Platform_Architecture.md new file mode 100644 index 0000000..329d4e0 --- /dev/null +++ b/元宝 - AI_Hub_Platform_Architecture.md @@ -0,0 +1,1278 @@ +# 🧠 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 平台早日上线！** 🚀