From 7da886a42be87cdeeb9c11489e581c6b4e470903 Mon Sep 17 00:00:00 2001 From: qyyfw <120122225@qq.com> Date: Mon, 27 Jul 2026 09:21:01 +0800 Subject: [PATCH] =?UTF-8?q?=E4=B8=8A=E4=BC=A0=E6=96=87=E4=BB=B6=E8=87=B3?= =?UTF-8?q?=E3=80=8C/=E3=80=8D?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...Platform_Analysis_and_Execution_Plan v2.md | 2056 +++++++++++++++++ 1 file changed, 2056 insertions(+) create mode 100644 AI_PaaS_Platform_Analysis_and_Execution_Plan v2.md diff --git a/AI_PaaS_Platform_Analysis_and_Execution_Plan v2.md b/AI_PaaS_Platform_Analysis_and_Execution_Plan v2.md new file mode 100644 index 0000000..6c0ebdf --- /dev/null +++ b/AI_PaaS_Platform_Analysis_and_Execution_Plan v2.md @@ -0,0 +1,2056 @@ +# AI PaaS 平台 · Starred 项目分析报告 + 落地可执行方案 + +> **文档用途**：本文件为 AI PaaS 平台（技能市场 + Agent 编排 + 多租户 SaaS）的技术决策与落地执行手册。 +> 包含：(1) Starred 项目分层分析矩阵；(2) Open WebUI 深度架构拆解；(3) dashi-ppt-skill 平台化改造方案；(4) 平台技能开发标准规范。 +> **目标读者**：平台架构师、后端工程师、前端工程师、技能开发者、产品负责人。 +> **适用阶段**：MVP 开发 → 内测 → 公测 → 规模化运营。 + +--- + +## 目录 + +- [第一部分：Starred 项目分层分析矩阵](#第一部分starred-项目分层分析矩阵) + - [1.1 总览：项目分层地图](#11-总览项目分层地图) + - [1.2 第一梯队：值得借鉴（架构/模式/产品哲学）](#12-第一梯队值得借鉴架构模式产品哲学) + - [1.3 第二梯队：直接参考价值（能力组件）](#13-第二梯队直接参考价值能力组件) + - [1.4 第三梯队：可运行参考实现（可上架技能）](#14-第三梯队可运行参考实现可上架技能) + - [1.5 落地建议总表](#15-落地建议总表) +- [第二部分：深度拆解 Open WebUI 架构](#第二部分深度拆解-open-webui-架构) + - [2.1 拆解目标与方法论](#21-拆解目标与方法论) + - [2.2 整体架构拓扑](#22-整体架构拓扑) + - [2.3 核心子系统逐一拆解](#23-核心子系统逐一拆解) + - [2.3.1 认证与多租户体系（RBAC + SSO）](#231-认证与多租户体系rbac--sso) + - [2.3.2 模型路由与供应商抽象层](#232-模型路由与供应商抽象层) + - [2.3.3 RAG 管线与向量检索引擎](#233-rag-管线与向量检索引擎) + - [2.3.4 插件/技能扩展体系](#234-插件技能扩展体系) + - [2.5 Token 驾驶舱与用量计量](#25-token-驾驶舱与用量计量) + - [2.6 管理后台与审计](#26-管理后台与审计) + - [2.7 对照映射：Open WebUI 模块 → 本平台模块](#27-对照映射open-webui-模块--本平台模块) + - [2.8 可直接复用的代码/模式清单](#28-可直接复用的代码模式清单) +- [第三部分：dashi-ppt-skill 平台化改造方案](#第三部分dashi-ppt-skill-平台化改造方案) + - [3.1 改造目标](#31-改造目标) + - [3.2 原项目能力盘点](#32-原项目能力盘点) + - [3.3 平台化改造架构](#33-平台化改造架构) + - [3.4 SKILL.md 规范定义](#34-skillmd-规范定义) + - [3.5 API 适配层设计](#35-api-适配层设计) + - [3.6 多租户隔离与配额](#36-多租户隔离与配额) + - [3.7 上架清单与验收标准](#37-上架清单与验收标准) + - [3.8 改造排期（2 周落地）](#38-改造排期2-周落地) +- [第四部分：AI PaaS 平台技能开发标准](#第四部分ai-paas-平台技能开发标准) + - [4.1 设计原则](#41-设计原则) + - [4.2 技能包目录结构（强制规范）](#42-技能包目录结构强制规范) + - [4.3 SKILL.md 元数据规范（Schema）](#43-skillmd-元数据规范schema) + - [4.4 技能生命周期状态机](#44-技能生命周期状态机) + - [4.5 审核流程与质量标准](#45-审核流程与质量标准) + - [4.6 评分与排行算法](#46-评分与排行算法) + - [4.7 安全与沙箱规范](#47-安全与沙箱规范) + - [4.8 变现与分润模型](#48-变现与分润模型) + - [4.9 技能 SDK 与脚手架](#49-技能-sdk-与脚手架) + - [4.10 版本兼容与迁移](#410-版本兼容与迁移) +- [附录](#附录) + - [A. 技术选型最终建议表](#a-技术选型最终建议表) + - [B. 数据库 Schema 草案（PostgreSQL）](#b-数据库-schema-草案postgresql) + - [C. 术语表](#c-术语表) + +--- + +# 第一部分：Starred 项目分层分析矩阵 + +## 1.1 总览：项目分层地图 + +以下项目不在同一抽象层，需分层理解后才能正确使用： + +``` +┌──────────────────────────────────────────────────────────────┐ +│ L4 平台级产品（可直接对标平台形态） │ +│ · Open WebUI · Octop · StaffDeck · Langflow │ +├──────────────────────────────────────────────────────────────┤ +│ L3 架构/模式参考（设计理念值得借鉴） │ +│ · OpenWorker · Goose · EigenFlux · Loop Engineering │ +├──────────────────────────────────────────────────────────────┤ +│ L2 能力组件（可嵌入平台的具体能力） │ +│ · Meilisearch · FAISS · Semantica · txtai │ +│ · TreeSearch · Agent-Reach · Next-AI-Draw-IO · HyperFrames │ +├──────────────────────────────────────────────────────────────┤ +│ L1 技能/Skill 模板（可上架到技能市场） │ +│ · baoyu-skills · marketing-skills · dashi-ppt-skill │ +│ · equity-research-skill · hue · ai-job-search │ +├──────────────────────────────────────────────────────────────┤ +│ L0 设计基础设施（UI 体系支撑） │ +│ · Astryx · OpenCut │ +└──────────────────────────────────────────────────────────────┘ +``` + +## 1.2 第一梯队：值得借鉴（架构/模式/产品哲学） + +### 1.2.1 Open WebUI + +- **链接**：https://github.com/open-webui/open-webui +- **定位**：本地优先、模型无关、多用户 AI 交互平台。146K+ Stars。 +- **借鉴点**： + - **RBAC 用户组体系**：角色分级（Admin/User/Pending），用户组权限继承，模型/技能按组分配。 + - **9 种向量数据库可插拔**：Chroma / PGVector / Qdrant / Milvus / Elasticsearch / OpenSearch / Neptune / GraphRAG / None。后端抽象统一，切换零代码。 + - **RAG 混合检索**：BM25 全文 + 向量相似度 + Rerank 重排序，三阶段管线。 + - **Token 用量分析仪表盘**：按用户/模型/时间维度的消耗统计，直接对应本平台的"Token 驾驶舱"。 + - **模型 Arena**：A/B 对比测试，用户投票选择最佳回答。 + - **插件体系**：Filters（请求/响应拦截）/ Actions（事件触发）/ Pipes（模型路由）/ Tools（函数调用）/ Skills（提示词模板），五类插件覆盖全链路。 + - **企业认证**：LDAP / SSO / SCIM / OAuth2，开箱即用。 +- **对本平台的直接映射**：本平台的后台管理、模型路由、知识库 RAG、技能插件、Token 计量几乎可以在 Open WebUI 的架构上做"减法 + 多租户外化"。 + +### 1.2.2 Octop（腾讯云） + +- **链接**：https://github.com/TencentCloud/Octop +- **定位**：多用户、多 Agent 的自托管 AI 助手平台。 +- **借鉴点**： + - **IM 集成架构**：飞书 / 钉钉 / QQ / 企微 / Discord 的统一接入层，每种 IM 抽象为"消息收发器 + 事件处理器"。 + - **ACP 双向集成**：既能被外部工具调用（作为 Agent），也能委派任务给 Claude Code / Codex（作为编排器）。 + - **单进程部署**：轻量启动，适合中小团队。 +- **对本平台的直接映射**：本平台的"IM Bot"模块（微信 Bot / 企微 / 飞书 / QQ / 悟空 IM）应直接参考 Octop 的 IM 抽象层设计。 + +### 1.2.3 StaffDeck（OpenBMB） + +- **链接**：https://github.com/OpenBMB/StaffDeck +- **定位**：企业数字员工平台——把员工经验、业务流程、决策标准变成可复用、可演进、可追溯的数字员工。 +- **借鉴点**： + - **数字员工 = 技能包 + 知识库 + 工作流**的三元组模型。 + - **市场资源权限保护**：技能上架后可设"复制绑定"，防止未授权分发。 + - **可演进机制**：数字员工在执行中积累经验，自动更新知识库。 +- **对本平台的直接映射**：本平台的"技能市场 + 知识库 + Agent 编排"三合一的产品形态，与 StaffDeck 高度一致。其"市场授权模型"可直接用于本平台的技能版权保护。 + +### 1.2.4 OpenWorker（Andrew Ng） + +- **链接**：https://github.com/andrewyng/openworker +- **定位**：本地优先、模型无关、交付成品（而非聊天）的桌面 AI 同事。 +- **借鉴点**： + - **四级风险审批模型**：read / write_local / exec / external，每级默认行为明确。 + - **无人值守收件箱**：Agent 遇到需确认操作时入队，等待用户回来审批，不擅自提权。 + - **aisuite 引擎**：统一多厂商 chat-completions API，模型字符串即插即用。 + - **"要结果不要答案"哲学**：产品设计核心是交付成品文件/邮件/日历变更。 +- **对本平台的直接映射**：本平台的 Agent 执行沙箱、敏感操作审批流、模型路由层应直接采用此设计。 + +### 1.2.5 Loop Engineering + +- **链接**：https://github.com/cobusgreyling/loop-engineering +- **定位**：AI Agent 循环工程的模式库与 CLI 工具集。 +- **借鉴点**： + - **核心范式转变**：从"写 prompt"到"设计 loop"——给 Agent 一个目标、一组工具、一个终止条件，让它自治运行。 + - **Verifier Skills**：每个 loop 配一个验证器，判断目标是否达成。 + - **Goal Audit CLI**：审计 loop 执行轨迹，复盘决策路径。 +- **对本平台的直接映射**：本平台的"Agent 编排引擎"应内置 loop 原语，技能开发者只需声明目标 + 工具集 + 验证条件。 + +### 1.2.6 EigenFlux + +- **链接**：https://github.com/phronesis-io/eigenflux +- **定位**：Agent 间广播网络——Agent 既广播也监听，AI 引擎做治理和匹配。 +- **借鉴点**： + - **去中心化 Agent 通信**：Agent 发布能力声明，网络自动匹配调用方与被调用方。 + - **治理层**：速率限制、权限校验、调用审计集中在网络层。 +- **对本平台的直接映射**：未来"技能间协作"和"Agent 市场互发现"的通信协议参考。 + +## 1.3 第二梯队：直接参考价值（能力组件） + +### 1.3.1 Meilisearch + +- **链接**：https://github.com/meilisearch/meilisearch +- **定位**：Rust 编写的闪电级搜索引擎，支持 AI 混合搜索。58K+ Stars。 +- **参考价值**： + - **sub-50ms 搜索延迟**，内置中文分词（jieba），BM25 + 向量混合搜索。 + - **租户令牌（Tenant Tokens）**：天然适配多租户数据隔离，可在令牌中嵌入过滤规则。 + - **过滤 / 分面搜索 / 排序规则**：完美匹配技能市场"按分类/场景/下载量筛选"。 +- **落地建议**：作为本平台**技能市场搜索、应用服务检索、平台内容 SEO 索引**的首选搜索引擎。 + +### 1.3.2 FAISS（Facebook Research） + +- **链接**：https://github.com/facebookresearch/faiss +- **定位**：密集向量高效相似度搜索与聚类算法库。40K+ Stars。 +- **参考价值**： + - **GPU 加速**的十亿级向量检索。 + - HNSW / IVF 多种索引算法可选。 +- **局限性**：只是"发动机"，不负责多租户、元数据过滤、事务、权限。 +- **落地建议**：当向量规模超过 PGVector/Meilisearch 舒适区（千万级+）时引入，作为底层检索引擎嵌入自建记忆服务。 + +### 1.3.3 Semantica + +- **链接**：https://github.com/semantica-agi/semantica +- **定位**：图原生上下文 + 审计合规基础设施。1.4K Stars。 +- **参考价值**： + - **W3C PROV-O 溯源**：每次决策可追溯到数据来源。 + - **决策生命周期管理**：草稿 → 验证 → 生效 → 过期。 + - **冲突检测与因果推理**。 +- **落地建议**：当平台服务金融 / 医疗 / 法律等受监管行业时引入，作为"可解释 AI + 审计轨迹"合规层。 + +### 1.3.4 txtai + +- **链接**：https://github.com/neuml/txtai +- **定位**：一体化语义搜索 + LLM 编排框架。12.7K Stars。 +- **参考价值**： + - Embeddings 数据库 = 向量索引 + 图网络 + 关系数据库三合一。 + - 比 FAISS 更高层抽象，但仍需自行封装多租户。 +- **落地建议**：如需自建记忆/检索服务且团队 Python 技术栈强，可基于 txtai 快速搭建。 + +### 1.3.5 TreeSearch + +- **链接**：https://github.com/shibing624/TreeSearch +- **定位**：零向量、零 API 的结构化文档树检索。FTS5 + 文档树解析。 +- **参考价值**： + - 毫秒级搜索万级文档，无 Embedding 开销。 + - 适合代码仓库、结构化文档、平台帮助中心。 +- **落地建议**：作为平台"代码类技能检索"和"帮助文档搜索"的轻量补充。 + +### 1.3.6 Agent-Reach + +- **链接**：https://github.com/Panniantong/Agent-Reach +- **定位**：给 Agent 装上互联网能力（Twitter / Reddit / YouTube / GitHub / B站 / 小红书）。60K+ Stars。 +- **参考价值**： + - **能力层路由设计**：选型 / 安装 / 体检 / 路由分离。 + - 零 API 费用（利用公开接口）。 +- **落地建议**：本平台"技能依赖管理"和"外部数据源接入"的架构参考。 + +### 1.3.7 Goose（AAIF） + +- **链接**：https://github.com/aaif-goose/goose +- **定位**：跨平台桌面 AI Agent，Rust 编写，15+ 模型供应商 + 70+ MCP 扩展。51K+ Stars。 +- **参考价值**： + - **模型供应商抽象**：统一接口适配多厂商。 + - **MCP 扩展机制**：技能即 MCP Server，动态加载。 +- **落地建议**：本平台"模型路由 + MCP 技能扩展"的参考实现。 + +### 1.3.8 Next AI Draw-IO + +- **链接**：https://github.com/DayuanJiang/next-ai-draw-io +- **定位**：自然语言生成流程图 / 架构图，MCP 集成。33K+ Stars。 +- **参考价值**： + - draw.io XML 生成 + 多模型适配。 + - 架构图 / 流程图 / 思维导图的自然语言驱动。 +- **落地建议**：本平台"可视化技能"（架构图生成、流程图生成）的实现参考。 + +### 1.3.9 HyperFrames（HeyGen） + +- **链接**：https://github.com/heygen-com/hyperframes +- **定位**：HTML → MP4 确定性视频渲染。37K+ Stars。 +- **参考价值**： + - headless Chrome + FFmpeg 渲染管线。 + - 支持 GSAP / Three.js / Lottie 动画。 +- **落地建议**：本平台"视频类技能"（短视频生成、课件录屏）的渲染管线参考。 + +### 1.3.10 Astryx（Facebook） + +- **链接**：https://github.com/facebook/astryx +- **定位**：Meta 8 年沉淀、13000+ 应用验证的设计系统。10K+ Stars。 +- **参考价值**： + - 150+ 组件、品牌级主题引擎、暗色模式、AI Agent 友好。 +- **落地建议**：本平台 UI 设计系统的底座参考，尤其适合"科技感 + 护眼亮色"诉求。 + +## 1.4 第三梯队：可运行参考实现（可上架技能） + +### 1.4.1 dashi-ppt-skill + +- **链接**：https://github.com/chuspeeism/dashi-ppt-skill +- **定位**：AI 生成带浏览器编辑控制台的 PPT，支持 20+ 维度调节，一键导出 PPTX/PDF。4K+ Stars。 +- **上架价值**：本平台"办公提效"定位的标杆技能。详见第三部分完整改造方案。 + +### 1.4.2 baoyu-skills + +- **链接**：https://github.com/JimLiu/baoyu-skills +- **定位**：20+ 内容创作技能合集（封面图 / 信息图 / SVG / 漫画 / 小红书卡片 / 幻灯片）。24K+ Stars。 +- **上架价值**：本平台"内容创作专区"的现成货架。其 SKILL.md 规范值得作为平台统一技能开发标准的参考。 + +### 1.4.3 marketing-skills + +- **链接**：https://github.com/coreyhaines31/marketingskills +- **定位**：SEO / CRO / 增长营销技能集。41K+ Stars。 +- **上架价值**：包含 SEO 技能，直接对应本平台"全平台适合 SEO 和 GEO 搜索"的需求。 + +### 1.4.4 equity-research-skill + +- **链接**：https://github.com/rollingSirius/equity-research-skill +- **定位**：九章个股研报 + 九章财报分析 + 脚本化 DCF/EPV 估值 + Beneish M-Score 财务质量核查。174 Stars。 +- **上架价值**："垂直专业技能"标杆——证明平台可承载高价值、可审计、可复算的专业技能。 + +### 1.4.5 ai-job-search + +- **链接**：https://github.com/MadsLorentzen/ai-job-search +- **定位**：AI 求职框架——自评 / 搜职位 / 改简历 / 写求职信 / 面试准备，drafter-reviewer 双 Agent。26K+ Stars。 +- **上架价值**："工作流编排 + 多 Agent 协作"的参考实现，可改造成"职场提效技能包"。 + +### 1.4.6 hue + +- **链接**：https://github.com/dominikmartn/hue +- **定位**：从 URL / 名称 / 截图学习任意品牌，输出完整设计系统。765 Stars。 +- **上架价值**：辅助本平台自身的 UI 设计系统生成与迭代。 + +### 1.4.7 OpenCut + +- **链接**：https://github.com/OpenCut-app/OpenCut +- **定位**：开源版 CapCut。78K+ Stars。 +- **上架价值**：视频编辑能力的参考实现，可作为"视频创作技能市场"的技术底座。 + +## 1.5 落地建议总表 + +### 架构层（借鉴 + 参考实现） + +| 本平台模块 | 参考项目 | 行动 | +|---|---|---| +| 整体架构对标 | Open WebUI | 深度研究 RBAC / 向量库可插拔 / RAG 管线 / Token 仪表盘 | +| IM Bot 模块 | Octop | 参考飞书/钉钉/QQ/企微/Discord 集成架构 | +| Agent 编排引擎 | Loop Engineering + OpenWorker | 把"prompt 工程"升级为"loop 工程"，加入四级风险审批 | +| 模型路由层 | aisuite（OpenWorker 引擎） | 模型无关的统一 chat-completions API | +| 设计系统 | Astryx | 150+ 组件 + 品牌主题 + 亮暗双模 | + +### 能力层（集成或自建） + +| 本平台能力 | 技术方案 | +|---|---| +| 搜索 / SEO / GEO | Meilisearch（中文分词 + 混合搜索 + 租户令牌） | +| 向量检索 | PGVector（先上）→ Qdrant / Milvus（规模上来后） | +| 知识图谱 / 审计 | Semantica（受监管行业场景） | +| 文档检索补充 | TreeSearch（轻量、零依赖） | +| 互联网数据源 | Agent-Reach 的路由设计 | +| 可视化 / 视频 | Next AI Draw-IO + HyperFrames | + +### 技能市场上架（第一批真实内容） + +| 技能来源 | 上架为 | +|---|---| +| dashi-ppt-skill | "AI 写 PPT"技能 | +| baoyu-skills | "内容创作工具箱"技能包 | +| marketing-skills | "SEO 优化助手"+"营销文案生成"技能 | +| equity-research-skill | "AI 投研报告"专业技能 | +| ai-job-search | "智能求职助手"工作流技能 | + +--- + +# 第二部分：深度拆解 Open WebUI 架构 + +## 2.1 拆解目标与方法论 + +**目标**：将 Open WebUI 的架构逐层拆解，提取可复用于本 AI PaaS 平台的设计模式与代码范式。 + +**方法论**： +- 静态分析：目录结构、模块依赖、配置项 +- 动态分析：请求生命周期、事件流、数据流 +- 模式提取：认证、路由、插件、RAG、计量 + +## 2.2 整体架构拓扑 + +``` + ┌───────────────────┐ + │ 用户浏览器 │ + │ (Web UI / PWA) │ + └────────┬──────────┘ + │ HTTPS + ┌────────▼──────────┐ + │ Nginx 反向代理 │ + │ (TLS / 负载均衡) │ + └────────┬──────────┘ + │ + ┌────────▼──────────┐ + │ FastAPI 后端 │ + │ (Python 异步) │ + └─┬──┬──┬──┬──┬──┬─┘ + │ │ │ │ │ │ + ┌────────────┘ │ │ │ │ └────────────┐ + │ │ │ │ │ │ + ┌────────▼────┐ ┌──────▼──┐│ │ │ ┌──────────▼──────┐ + │ 认证模块 │ │ RBAC ││ │ │ │ 插件引擎 │ + │ JWT/OAuth2 │ │ 用户组 ││ │ │ │ Filters/Actions │ + └─────────────┘ └─────────┘│ │ │ │ Pipes/Tools │ + │ │ │ └─────────────────┘ + ┌────────▼──┐│ │ + │ 模型路由 ││ │ + │ Pipe/Proxy││ │ + └────────┬──┘│ │ + │ │ │ + ┌─────────────┘ │ │ + │ │ │ + ┌────────▼────┐ ┌────────▼──┐ + │ 供应商适配 │ │ RAG 引擎 │ + │ OpenAI/ │ │ 混合检索 │ + │ Anthropic/ │ │ BM25+Vec │ + │ Google/... │ │ +Rerank │ + └─────────────┘ └────┬─────┘ + │ + ┌─────────────┤ + │ │ + ┌────────▼────┐ ┌─────▼──────┐ + │ 向量数据库 │ │ 文档存储 │ + │ Chroma/ │ │ SQLite/ │ + │ Qdrant/ │ │ S3/本地 │ + │ PGVector/...│ │ │ + └─────────────┘ └────────────┘ + + ┌──────────────────────────────┐ + │ 持久化层 │ + │ SQLite（默认）/ PostgreSQL │ + │ + 可选 S3 兼容对象存储 │ + └──────────────────────────────┘ +``` + +## 2.3 核心子系统逐一拆解 + +### 2.3.1 认证与多租户体系（RBAC + SSO） + +**Open WebUI 实现**： + +1. **认证方式**： + - 本地账号（bcrypt 密码哈希） + - OAuth2（Google / GitHub / Microsoft / 自定义 OIDC） + - LDAP / Active Directory + - SSO / SAML（企业版） + +2. **角色模型**： + ``` + Admin（管理员） + ├── 用户管理（创建/禁用/重置密码） + ├── 模型管理（启用/禁用/配额） + ├── 技能/插件管理（审核/上下架） + └── 系统设置（全局配置） + + User（普通用户） + ├── 个人对话 + ├── 个人知识库 + ├── 个人技能库 + └── API Key 管理 + + Pending（待审核） + └── 注册后等待管理员批准 + ``` + +3. **用户组（Groups）**： + - 用户可属于多个组 + - 组级权限：可访问的模型列表、可使用的技能列表、知识库共享 + - 组级配额：Token 上限、文件上传大小、对话轮次 + +4. **关键代码模式**： + +```python +# backend/open_webui/models/auths.py +class Auths: + # JWT 签发 + def insert_signin_token(self, user_id: str, token_type: str = "access"): + # 生成 JWT，包含 user_id + role + group_ids + ... + + # 权限校验装饰器 + def requires("role", ["admin", "user"]): + def decorator(func): + @wraps(func) + async def wrapper(*args, **kwargs): + token = kwargs.get("token") + payload = decode_token(token) + if payload["role"] not in roles: + raise HTTPException(403) + return await func(*args, **kwargs) + return wrapper + return decorator +``` + +**对本平台的映射**： + +| Open WebUI | 本平台对应 | +|---|---| +| Admin / User / Pending | 超级管理员 / 技能开发者 / 普通用户 / 待认证企业用户 | +| Groups（用户组） | 租户（Tenant）+ 工作区（Workspace） | +| 组级模型配额 | Token 驾驶舱的配额管理 | +| LDAP / SSO | 企业微信 / 飞书 SSO 接入 | + +### 2.3.2 模型路由与供应商抽象层 + +**Open WebUI 实现**： + +1. **统一接口**：所有模型供应商适配为 OpenAI 兼容的 chat-completions API +2. **Pipe 机制**：可编写自定义路由逻辑（如 A/B 测试、负载均衡、降级策略） +3. **模型注册表**： + +```python +# backend/open_webui/models/models.py +class Model: + id: str # 模型唯一标识 + name: str # 显示名称 + base_model_id: str # 底层模型（如 gpt-4o） + provider: str # openai / anthropic / google / ollama + context_length: int + pricing: dict # 输入/输出 Token 单价 + capabilities: list # tool_call / vision / streaming +``` + +4. **Pipe 示例（模型路由）**： + +```python +# 自定义 Pipe：按用户等级路由到不同模型 +class TieredModelRouter: + def __init__(self): + self.free_tier_model = "gpt-4o-mini" + self.pro_tier_model = "gpt-4o" + self.enterprise_tier_model = "claude-3.5-sonnet" + + async def pipe(self, body: dict, user: dict) -> str: + tier = user.get("subscription_tier", "free") + model_map = { + "free": self.free_tier_model, + "pro": self.pro_tier_model, + "enterprise": self.enterprise_tier_model, + } + body["model"] = model_map.get(tier, self.free_tier_model) + return await self._proxy_to_provider(body) +``` + +**对本平台的映射**： +- 本平台的"模型路由层"应直接采用 Pipe 模式 +- 结合 OpenWorker 的 aisuite，实现 13+ 供应商统一抽象 +- 在路由层加入"Token 配额检查"和"成本控制" + +### 2.3.3 RAG 管线与向量检索引擎 + +**Open WebUI 实现**（三阶段管线）： + +``` +用户提问 + │ + ▼ +┌──────────────┐ +│ 1. 查询重写 │ ← LLM 将用户问题改写为更适合检索的形式 +└──────┬───────┘ + │ + ▼ +┌──────────────────────────────────────┐ +│ 2. 混合检索 │ +│ ├── BM25 全文检索（关键词匹配） │ +│ ├── 向量相似度检索（语义匹配） │ +│ └── 结果融合（RRF 倒数排名融合） │ +└──────┬───────────────────────────────┘ + │ + ▼ +┌──────────────┐ +│ 3. Rerank │ ← Cross-Encoder 精排，Top K 重排序 +└──────┬───────┘ + │ + ▼ +┌──────────────┐ +│ 4. 上下文组装 │ ← 将 Top N 文档拼入 Prompt +└──────┬───────┘ + │ + ▼ + LLM 生成回答 +``` + +**关键配置项**： + +```yaml +# config.yaml +rag: + enable: true + embedding_model: "text-embedding-3-large" + vector_db: "pgvector" # chroma/qdrant/milvus/pgvector + chunk_size: 1500 + chunk_overlap: 200 + retrieval: + top_k: 10 + bm25_weight: 0.4 + vector_weight: 0.6 + rrf_k: 60 + rerank: + enable: true + model: "bge-reranker-v2-m3" + top_n: 5 +``` + +**对本平台的映射**： +- 知识库模块直接采用此三阶段管线 +- 向量库首选 PGVector（与 PostgreSQL 统一部署） +- 重排序模型部署为独立微服务 + +### 2.3.4 插件/技能扩展体系 + +**Open WebUI 的五类插件**： + +| 插件类型 | 触发时机 | 典型用途 | +|---|---|---| +| **Filters** | 请求发出前 / 响应返回后 | 敏感词过滤、Token 计量、日志审计 | +| **Actions** | 特定事件发生时 | 对话创建时通知、消息发送后存档 | +| **Pipes** | 模型调用时 | 模型路由、负载均衡、降级 | +| **Tools** | Agent 调用工具时 | 搜索、计算、文件操作 | +| **Skills** | 对话中触发 | 提示词模板、工作流预设 | + +**插件目录结构**： + +``` +open_webui/plugins/ +├── filters/ +│ ├── token_counter.py +│ └── content_moderation.py +├── actions/ +│ └── notify_slack.py +├── pipes/ +│ └── tiered_router.py +├── tools/ +│ └── web_search.py +└── skills/ + └── code_reviewer/ + ├── SKILL.md + └── prompt.txt +``` + +**对本平台的映射**： +- 本平台的"技能市场"对应 Open WebUI 的 Skills + Tools +- 本平台的"Filters"用于 Token 计量和审计日志 +- 本平台的"Actions"用于 IM Bot 消息推送 + +### 2.5 Token 驾驶舱与用量计量 + +**Open WebUI 实现**： + +1. **实时计量**：每次模型调用后，Filter 拦截响应，提取 `usage` 字段 +2. **存储**：写入 `chat_history` 表 + 聚合到 `usage_stats` 表 +3. **仪表盘**：按用户 / 模型 / 时间维度的消耗统计 + +```python +# backend/open_webui/main.py +@app.post("/api/chat/completions") +async def chat_completion(body: dict, user: User): + # 调用模型 + response = await provider.chat_completions(body) + + # Filter: 计量 + usage = response.get("usage", {}) + await log_token_usage( + user_id=user.id, + model=body["model"], + input_tokens=usage.get("prompt_tokens", 0), + output_tokens=usage.get("completion_tokens", 0), + cost=calculate_cost(body["model"], usage) + ) + + return response +``` + +**对本平台的映射**： +- 直接复用此 Filter 模式 +- 扩展为"实时配额检查"（调用前检查余额，调用后扣减） +- 仪表盘增加"近 30 天消耗趋势图""模型分布饼图" + +### 2.6 管理后台与审计 + +**Open WebUI 管理后台功能**： +- 用户管理（列表 / 搜索 / 禁用 / 重置密码 / 调整配额） +- 模型管理（启用 / 禁用 / 编辑参数 / 设置可见性） +- 技能管理（审核 / 上下架 / 查看安装量） +- 系统设置（全局参数 / 认证方式 / 存储配置） +- 日志查看（对话日志 / 操作日志 / 审计日志） + +**对本平台的映射**： +- 本平台后台"数据驾驶舱"在 Open WebUI 基础上增加业务指标（订阅收入、技能交易额） +- 审计日志增加"技能执行轨迹"和"Agent 决策路径" + +## 2.7 对照映射：Open WebUI 模块 → 本平台模块 + +| Open WebUI 模块 | 本平台对应模块 | 差异说明 | +|---|---|---| +| 用户管理 | 用户管理 + 会员订阅 | 本平台增加付费订阅体系 | +| 模型管理 | AI 技能中心 → 大模型库 | 本平台增加模型标签体系 | +| 知识库（RAG） | 知识库 | 本平台增加多租户隔离 + 企业知识库共享 | +| 技能/插件 | 技能市场 + 应用服务 | 本平台增加交易变现、分润、版权保护 | +| Token 计量 | Token 驾驶舱 | 本平台增加成本分析、预算告警 | +| 对话历史 | AI 聊天 + 进化看板 | 本平台增加对话进化追踪 | +| 管理后台 | 后台全模块 | 本平台增加商业变现、运营推广 | +| Pipe 路由 | 模型路由层 | 本平台增加技能路由 | +| Filter 链 | 审计 + 风控 | 本平台增加合规审查 | + +## 2.8 可直接复用的代码/模式清单 + +| 模式 | 来源模块 | 复用方式 | +|---|---|---| +| JWT + 角色装饰器 | `models/auths.py` | 直接移植，扩展租户字段 | +| Pipe 路由框架 | `pipes/` | 移植框架，重写路由策略 | +| Filter 拦截链 | `filters/` | 移植框架，增加计量/审计 Filter | +| RAG 三阶段管线 | `rag/` | 移植管线，替换向量库为 PGVector | +| 插件动态加载 | `plugins/` | 移植加载器，适配技能市场 | +| Token 计量 Filter | `main.py` | 直接复用 | +| 用户组权限 | `models/users.py` | 扩展为租户 + 工作区 | +| 模型注册表 | `models/models.py` | 扩展标签体系和定价 | + +--- + +# 第三部分：dashi-ppt-skill 平台化改造方案 + +## 3.1 改造目标 + +将 dashi-ppt-skill（开源 AI 生成 PPT 技能）改造为符合本 AI PaaS 平台规范的**平台原生技能**，实现： + +1. **平台化接入**：通过统一 Skill API 注册到技能市场 +2. **多租户隔离**：每个用户的文档/模板/配置独立存储 +3. **配额与计费**：按生成次数/Token 消耗计量，对接平台会员体系 +4. **浏览器端编辑**：保留原项目的浏览器控制台编辑能力 +5. **可上架可交易**：符合平台技能审核标准，支持订阅/单次付费 + +## 3.2 原项目能力盘点 + +| 能力 | 实现方式 | 平台化改造点 | +|---|---|---| +| 文档 → PPT 生成 | LLM 解析文档 → 生成 HTML 幻灯片 | 接入平台模型路由层 | +| 20+ 维度样式调节 | 浏览器侧控制台实时修改 CSS 变量 | 改为平台统一编辑器组件 | +| 9 种切换动画 | CSS animation + JS 控制 | 保留，封装为平台动画库 | +| 图表版式 | Chart.js / ECharts 集成 | 接入平台数据可视化模块 | +| 分析模型版式 | 预置 SWOT/PEST/4P 等模板 | 扩展为平台模板市场 | +| 导出 PPTX | html2pptx 转换 | 保留 | +| 导出 PDF | headless Chrome 渲染 | 保留 | +| 浏览器内编辑 | 原地编辑 + 实时预览 | 集成平台编辑器 | + +## 3.3 平台化改造架构 + +``` +┌─────────────────────────────────────────────────────────┐ +│ 平台技能市场 → 用户点击"使用" → 创建技能实例 │ +└────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ Skill Runtime（平台技能运行时） │ +│ ├── 鉴权：验证用户订阅/配额 │ +│ ├── 计费：预扣 Token + 生成次数 │ +│ ├── 隔离：创建工作区（用户 ID + 技能 ID + 实例 ID） │ +│ └── 编排：调用 dashi-ppt-skill 的 API │ +└────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ dashi-ppt-skill 适配层（改造后的入口） │ +│ ├── /api/generate POST 生成 PPT │ +│ ├── /api/edit POST 编辑幻灯片 │ +│ ├── /api/export/pptx GET 导出 PPTX │ +│ ├── /api/export/pdf GET 导出 PDF │ +│ └── /api/templates GET 获取模板列表 │ +└────────────────────┬────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────┐ +│ 存储层（多租户隔离） │ +│ ├── PGVector：幻灯片 Embedding（用于模板推荐） │ +│ ├── S3/对象存储：用户上传的文档/图片/生成产物 │ +│ └── PostgreSQL：技能实例状态、版本历史 │ +└─────────────────────────────────────────────────────────┘ +``` + +## 3.4 SKILL.md 规范定义 + +```yaml +# SKILL.md — dashi-ppt-skill v1.0.0 +name: dashi-ppt +display_name: "AI 智能 PPT 生成器" +version: "1.0.0" +author: + name: "Dashibase" + url: "https://github.com/chuspeeism/dashi-ppt-skill" + license: "MIT" + +description: | + 上传文档或输入主题，AI 自动生成可编辑的专业 PPT 演示文稿。 + 支持 20+ 维度样式调节、9 种切换动画、图表版式、分析模型版式， + 一键导出 PPTX / PDF。 + +category: "办公提效" +tags: ["ppt", "presentation", "office", "文档生成", "可视化"] + +# 能力声明 +capabilities: + - text_to_presentation + - document_to_presentation + - template_based_generation + - browser_inline_editing + - chart_slide + - analysis_model_slide # SWOT/PEST/4P + +# 输入输出规范 +inputs: + - name: "source_text" + type: "string" + description: "源文本内容（文档全文或主题描述）" + required: false + - name: "source_file" + type: "file" + description: "上传的文档文件（PDF/DOCX/MD）" + required: false + - name: "template_id" + type: "string" + description: "模板 ID，不填则自动选择" + required: false + - name: "slide_count" + type: "integer" + description: "目标页数，默认 10" + required: false + default: 10 + +outputs: + - name: "slides_html" + type: "html" + description: "可编辑的 HTML 幻灯片" + - name: "pptx_url" + type: "url" + description: "导出的 PPTX 文件下载链接" + - name: "pdf_url" + type: "url" + description: "导出的 PDF 文件下载链接" + +# 资源消耗声明 +resource: + model_calls: 3 # 生成一次 PPT 平均调用 3 次模型 + estimated_tokens: 8000 # 平均 Token 消耗 + storage_mb: 5 # 平均存储占用 + +# 权限声明 +permissions: + - read:workspace # 读取用户工作区文件 + - write:workspace # 写入生成的文件 + - exec:model_api # 调用模型 API + +# 依赖 +dependencies: + models: ["gpt-4o", "claude-3.5-sonnet"] + libraries: ["chart.js", "html2pptx"] + +# 定价 +pricing: + model: "subscription" # subscription / pay_per_use / free + tier_required: "pro" # free / pro / enterprise + pay_per_use: + tokens_per_generation: 8000 + extra_storage_mb: 5 +``` + +## 3.5 API 适配层设计 + +### 3.5.1 统一入口 + +```python +# skill_adapter/app.py +from fastapi import FastAPI, Depends, HTTPException +from pydantic import BaseModel + +app = FastAPI(title="dashi-ppt-skill Adapter") + +class GenerateRequest(BaseModel): + source_text: str | None = None + source_file_url: str | None = None + template_id: str | None = None + slide_count: int = 10 + style_preferences: dict | None = None + +class SkillContext(BaseModel): + user_id: str + tenant_id: str + subscription_tier: str + quota_remaining: int + +@app.post("/api/generate") +async def generate_ppt( + req: GenerateRequest, + ctx: SkillContext = Depends(verify_skill_access) # 平台鉴权 +): + # 1. 配额预检查 + if ctx.quota_remaining <= 0: + raise HTTPException(402, "配额不足，请升级会员") + + # 2. 创建工作区 + workspace = await create_workspace( + tenant_id=ctx.tenant_id, + user_id=ctx.user_id, + skill="dashi-ppt", + instance_id=generate_uuid() + ) + + # 3. 下载源文件（如有） + if req.source_file_url: + file_path = await download_to_workspace(req.source_file_url, workspace) + + # 4. 调用原项目核心逻辑 + result = await dashi_generate( + text=req.source_text, + file=file_path, + template=req.template_id, + slide_count=req.slide_count, + model=select_model_for_tier(ctx.subscription_tier), # 按会员等级选模型 + workspace=workspace + ) + + # 5. 后处理：生成预览图、存储产物 + preview_url = await generate_preview(result.html, workspace) + pptx_url = await export_pptx(result.html, workspace) + pdf_url = await export_pdf(result.html, workspace) + + # 6. 扣减配额 + 记录计量 + await deduct_quota(ctx.user_id, tokens=result.tokens_used) + await log_skill_usage( + user_id=ctx.user_id, + skill="dashi-ppt", + tokens=result.tokens_used, + duration_ms=result.duration_ms + ) + + return { + "instance_id": workspace.instance_id, + "preview_url": preview_url, + "pptx_url": pptx_url, + "pdf_url": pdf_url, + "tokens_used": result.tokens_used, + "slides_html": result.html + } +``` + +### 3.5.2 模型路由集成 + +```python +def select_model_for_tier(tier: str) -> str: + """按会员等级选择最优模型""" + tier_model_map = { + "free": "gpt-4o-mini", # 快速但便宜 + "pro": "gpt-4o", # 高质量 + "enterprise": "claude-3.5-sonnet" # 最强推理 + } + return tier_model_map.get(tier, "gpt-4o-mini") +``` + +## 3.6 多租户隔离与配额 + +### 3.6.1 工作区隔离 + +``` +/workspace/ +├── {tenant_id}/ +│ ├── {user_id}/ +│ │ ├── dashi-ppt/ +│ │ │ ├── {instance_id}/ +│ │ │ │ ├── source/ # 用户上传的源文件 +│ │ │ │ ├── output/ # 生成的产物 +│ │ │ │ ├── preview.png # 预览图 +│ │ │ │ └── meta.json # 实例元数据 +│ │ │ └── {instance_id}/ +│ │ │ └── ... +│ │ └── other-skills/ +│ └── another-user/ +└── shared/ + └── templates/ # 平台共享模板 +``` + +### 3.6.2 配额策略 + +| 会员等级 | 每日生成次数 | 单次最大页数 | 可用模型 | 存储空间 | +|---|---|---|---|---| +| Free | 3 次 | 10 页 | gpt-4o-mini | 50 MB | +| Pro | 50 次 | 30 页 | gpt-4o | 2 GB | +| Enterprise | 无限 | 100 页 | 全部 | 20 GB | + +### 3.6.3 数据库 Schema + +```sql +-- 技能实例表 +CREATE TABLE skill_instances ( + id UUID PRIMARY KEY, + tenant_id UUID NOT NULL, + user_id UUID NOT NULL, + skill_name TEXT NOT NULL, -- 'dashi-ppt' + version TEXT NOT NULL, -- '1.0.0' + status TEXT NOT NULL, -- 'generating'/'ready'/'failed'/'archived' + input_meta JSONB, -- 输入参数快照 + output_meta JSONB, -- 输出产物路径 + tokens_used INTEGER DEFAULT 0, + duration_ms INTEGER DEFAULT 0, + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); + +-- 配额表 +CREATE TABLE user_quotas ( + user_id UUID PRIMARY KEY, + skill_name TEXT NOT NULL, + daily_limit INTEGER NOT NULL, + daily_used INTEGER DEFAULT 0, + last_reset DATE DEFAULT CURRENT_DATE, + total_storage_mb INTEGER DEFAULT 0, + max_storage_mb INTEGER NOT NULL +); + +-- RLS 策略：用户只能访问自己的实例 +ALTER TABLE skill_instances ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON skill_instances + USING (tenant_id = current_setting('app.current_tenant')::UUID); +``` + +## 3.7 上架清单与验收标准 + +### 3.7.1 上架检查清单 + +- [ ] SKILL.md 完整填写（名称/版本/作者/描述/输入输出/权限/定价） +- [ ] 通过平台安全沙箱扫描（无恶意代码、无硬编码密钥） +- [ ] 资源消耗声明准确（模型调用次数、Token 估算、存储占用） +- [ ] 多租户隔离验证通过（A 用户无法访问 B 用户的产物） +- [ ] 配额扣减正确（预扣 → 实际使用 → 多退少补） +- [ ] 错误处理完善（模型超时/文件过大/格式不支持） +- [ ] 导出功能正常（PPTX/PDF 格式兼容主流办公软件） +- [ ] 预览图生成正常 +- [ ] 平台编辑器可正常编辑生成的幻灯片 +- [ ] 审计日志记录完整（谁/何时/用什么参数/生成了什么） + +### 3.7.2 验收测试用例 + +```yaml +test_cases: + - name: "基础生成-文本输入" + input: { source_text: "介绍量子计算的基本原理和应用前景", slide_count: 8 } + expect: + slides_count: 8 + has_title_slide: true + has_content_slides: true + tokens_used: "<= 10000" + + - name: "文档上传-PDF" + input: { source_file: "report.pdf", slide_count: 15 } + expect: + slides_count: 15 + content_from_pdf: true + pptx_exportable: true + + - name: "模板选择" + input: { source_text: "2026年营销计划", template_id: "business_blue" } + expect: + template_applied: "business_blue" + style_consistent: true + + - name: "配额超限" + setup: { daily_used: 50, daily_limit: 50 } + expect: + status_code: 402 + error: "配额不足" + + - name: "多租户隔离" + setup: + user_a: { tenant: "T1", generate: true } + user_b: { tenant: "T2", try_access: "user_a_instance" } + expect: + user_b_status: 403 +``` + +## 3.8 改造排期（2 周落地） + +| 天数 | 任务 | 产出 | +|---|---|---| +| D1-D2 | 原项目代码审计 + 依赖分析 | 审计报告 + 改造方案确认 | +| D3-D4 | 搭建适配层框架 + 平台鉴权对接 | 可运行的 /api/generate 骨架 | +| D5-D6 | 移植核心生成逻辑 + 模型路由集成 | 文本→PPT 端到端跑通 | +| D7-D8 | 多租户工作区 + 文件存储隔离 | 隔离验证通过 | +| D9-D10 | 配额系统 + 计量日志 + 计费对接 | 配额扣减正确 | +| D11 | 导出功能适配（PPTX/PDF）+ 预览图 | 导出验证通过 | +| D12 | 平台编辑器集成 + 样式调节适配 | 浏览器内可编辑 | +| D13 | 测试 + 安全扫描 + 性能压测 | 测试报告 | +| D14 | 上架到技能市场 + 文档 + 演示视频 | 正式上线 | + +--- + +# 第四部分：AI PaaS 平台技能开发标准 + +## 4.1 设计原则 + +1. **安全优先**：所有技能在沙箱中运行，权限最小化 +2. **模型无关**：技能不绑定特定模型供应商，通过平台路由层调用 +3. **多租户隔离**：数据/文件/配置按租户 + 用户严格隔离 +4. **可观测**：每次执行有完整日志（输入/输出/耗时/Token/错误） +5. **可计费**：资源消耗透明声明，精确计量 +6. **可进化**：支持版本迭代、A/B 测试、用户反馈闭环 +7. **标准化**：统一目录结构、统一元数据、统一接口规范 + +## 4.2 技能包目录结构（强制规范） + +``` +my-skill/ +├── SKILL.md # 技能元数据（必须） +├── README.md # 用户文档 +├── CHANGELOG.md # 版本变更记录 +├── LICENSE # 许可证 +├── manifest.json # 机器可读清单 +├── icon.png # 技能图标（512x512） +├── preview/ # 预览图/视频 +│ ├── preview-1.png +│ └── demo.mp4 +├── src/ # 源代码 +│ ├── main.py # 入口（必须） +│ ├── config.py # 配置 +│ ├── models.py # 数据模型 +│ └── utils/ # 工具函数 +├── templates/ # 模板文件（如适用） +│ └── default.html +├── tests/ # 测试 +│ ├── unit/ +│ └── integration/ +├── docs/ # 开发者文档 +│ ├── API.md +│ └── ARCHITECTURE.md +└── scripts/ # 构建/部署脚本 + ├── build.sh + └── deploy.sh +``` + +## 4.3 SKILL.md 元数据规范（Schema） + +```yaml +# === 必填字段 === +name: string # 技能唯一标识（小写+连字符） +display_name: string # 展示名称（≤20 字符） +version: string # 语义化版本（SemVer） +author: + name: string + email: string + url: string + license: string # MIT / Apache-2.0 / 商业授权 + +description: string # 一句话描述（≤100 字符） +long_description: string # 详细说明（Markdown，≤2000 字符） + +category: string # 一级分类 +subcategory: string # 二级分类 +tags: string[] # 搜索标签（≤10 个） + +# === 能力声明 === +capabilities: string[] # 能力标签 +inputs: # 输入参数 schema + - name: string + type: string # string/number/boolean/file/url/json + description: string + required: boolean + default: any + validation: object # min/max/regex/enum +outputs: + - name: string + type: string + description: string + +# === 资源消耗 === +resource: + model_calls: integer # 平均模型调用次数 + estimated_tokens: integer # 平均 Token 消耗 + estimated_duration_ms: integer # 平均执行耗时 + storage_mb: integer # 平均存储占用 + memory_mb: integer # 运行时内存需求 + cpu_cores: number # 运行时 CPU 需求 + +# === 权限声明 === +permissions: + - read:workspace # 读用户工作区 + - write:workspace # 写用户工作区 + - read:knowledge_base # 读知识库 + - write:knowledge_base # 写知识库 + - exec:model_api # 调用模型 + - exec:external_api # 调用外部 API + - exec:terminal # 执行终端命令 + - network:egress # 出网访问 + +# === 依赖 === +dependencies: + models: string[] # 需要的模型能力标签 + libraries: string[] # Python/Node 依赖 + external_services: string[] # 外部服务（如需要 API Key） + skills: string[] # 依赖的其他技能 + +# === 运行时 === +runtime: + language: string # python3.11 / node20 / rust + entrypoint: string # src/main.py + health_check: string # /health + timeout_seconds: integer # 执行超时 + max_concurrent: integer # 最大并发实例数 + +# === 定价 === +pricing: + model: string # free / subscription / pay_per_use / one_time + tier_required: string # free / pro / enterprise + pay_per_use: + price_per_generation: number + price_per_1000_tokens: number + subscription: + included_in: string[] # 包含在哪些会员套餐 + +# === 兼容性 === +compatibility: + platform_version: string # 最低平台版本 + supported_models: string[] # 经过验证的模型 + min_memory_mb: integer + min_storage_mb: integer + +# === 合规 === +compliance: + data_handling: string # 数据处理说明 + pii_handling: string # 个人信息处理说明 + output_filtering: boolean # 是否过滤输出内容 + content_policy: string # 内容政策声明 +``` + +## 4.4 技能生命周期状态机 + +``` +┌──────────┐ submit ┌──────────┐ review ┌──────────┐ +│ Draft │─────────────▶│ Pending │────────────▶│ Review │ +└──────────┘ └──────────┘ └────┬─────┘ + │ + ┌──────────┐ approve ┌─────────▼──────┐ + │ Rejected │◀───────────│ Approved │ + └──────────┘ └────┬───────────┘ + │ publish + ▼ + ┌──────────┐ unpublish ┌──────────────┐ + │ Archived │◀────────────│ Published │ + └──────────┘ └────┬─────────┘ + │ update + ▼ + ┌──────────┐ + │ Updated │ + │ (re-review│ + │ if major)│ + └──────────┘ +``` + +| 状态 | 说明 | 可见性 | +|---|---|---| +| Draft | 开发者本地/沙箱 | 仅自己 | +| Pending | 提交审核 | 仅审核员 | +| Review | 审核中 | 仅审核员 | +| Approved | 审核通过待发布 | 仅审核员 | +| Published | 已上架 | 全平台可见 | +| Updated | 更新待审核 | 保留旧版本可见 | +| Rejected | 审核拒绝 | 仅自己+拒绝原因 | +| Archived | 下架归档 | 不可新安装，已安装可用 | + +## 4.5 审核流程与质量标准 + +### 4.5.1 自动审核（CI 流水线） + +``` +提交技能 + │ + ▼ +┌──────────────────┐ +│ 1. 结构检查 │ → SKILL.md 完整性、目录结构、文件大小 +├──────────────────┤ +│ 2. 依赖扫描 │ → 检测恶意依赖、已知漏洞（CVE） +├──────────────────┤ +│ 3. 代码静态分析 │ → 硬编码密钥、不安全反序列化、SQL 注入 +├──────────────────┤ +│ 4. 沙箱动态测试 │ → 在隔离环境中运行，监控网络/文件/进程 +├──────────────────┤ +│ 5. 资源声明验证 │ → 实际消耗 vs 声明消耗偏差 +├──────────────────┤ +│ 6. 输出安全过滤 │ → 检测有害内容、PII 泄露 +└──────────────────┘ + │ + ▼ +通过 → 进入人工审核 +失败 → 返回报告 + 修改建议 +``` + +### 4.5.2 人工审核标准 + +| 维度 | 标准 | 权重 | +|---|---|---| +| 功能性 | 核心功能可用、无严重 Bug | 30% | +| 安全性 | 无后门、无数据泄露、权限合理 | 25% | +| 文档质量 | README 清晰、参数说明完整、有使用示例 | 15% | +| 用户体验 | 输出质量高、响应速度快、错误处理友好 | 15% | +| 创新性 | 解决真实痛点、差异化价值 | 10% | +| 资源效率 | Token/存储消耗合理、不浪费 | 5% | + +### 4.5.3 审核 SLA + +- 自动审核：≤ 5 分钟 +- 人工审核：≤ 2 个工作日 +- 紧急审核（安全补丁）：≤ 4 小时 + +## 4.6 评分与排行算法 + +### 4.6.1 综合评分公式 + +``` +Score = 0.35 × 下载量分 + 0.25 × 评分分 + 0.20 × 活跃度分 + 0.10 × 质量分 + 0.10 × 收入分 + +下载量分 = log10(总下载量 + 1) / log10(全平台最高下载量 + 1) × 100 +评分分 = 平均星级（1-5）× 20 +活跃度分 = (近30天下载量 / 总下载量) × 100 +质量分 = 审核得分（0-100） +收入分 = log10(总交易额 + 1) / log10(全平台最高交易额 + 1) × 100 +``` + +### 4.6.2 排行维度 + +| 排行榜 | 排序依据 | 更新频率 | +|---|---|---| +| 热门下载 | 近 7 天下载量 | 实时 | +| 最高评分 | 平均星级（≥10 条评价） | 每日 | +| 最新上架 | 上架时间 | 实时 | +| 编辑推荐 | 人工精选 | 每周 | +| 收入最高 | 近 30 天交易额 | 每日 | +| 分类排行 | 分类内综合评分 | 每日 | + +## 4.7 安全与沙箱规范 + +### 4.7.1 沙箱架构 + +``` +┌─────────────────────────────────────────────┐ +│ 平台技能运行时 │ +│ ┌───────────────────────────────────────┐ │ +│ │ gVisor / Firecracker 微虚拟机 │ │ +│ │ ┌─────────────────────────────────┐ │ │ +│ │ │ 技能进程 │ │ │ +│ │ │ - 只读根文件系统 │ │ │ +│ │ │ - 临时工作目录（执行后清除） │ │ │ +│ │ │ - 受限网络（仅平台代理出网） │ │ │ +│ │ └─────────────────────────────────┘ │ │ +│ │ ┌─────────────────────────────────┐ │ │ +│ │ │ 资源限制 │ │ │ +│ │ │ - CPU: 2 cores max │ │ │ +│ │ │ - Memory: 1GB max │ │ │ +│ │ │ - Disk: 500MB tmpfs │ │ │ +│ │ │ - Network: 仅平台 API + 白名单 │ │ │ +│ │ │ - Timeout: 300s │ │ │ +│ │ └─────────────────────────────────┘ │ │ +│ └───────────────────────────────────────┘ │ +└─────────────────────────────────────────────┘ +``` + +### 4.7.2 权限矩阵 + +| 权限 | 含义 | 默认 | 需审核 | +|---|---|---|---| +| `read:workspace` | 读用户工作区文件 | ✓ | | +| `write:workspace` | 写用户工作区文件 | | ✓ | +| `read:knowledge_base` | 读知识库 | | ✓ | +| `write:knowledge_base` | 写知识库 | | ✓ | +| `exec:model_api` | 调用模型 | ✓ | | +| `exec:external_api` | 调用外部 API | | ✓ | +| `exec:terminal` | 执行终端命令 | | ✓ | +| `network:egress` | 出网访问 | | ✓ | +| `read:other_users` | 读其他用户数据 | | ✓ | +| `admin:platform` | 平台管理操作 | | ✓ | + +### 4.7.3 安全红线（触发即下架） + +- 未经声明收集用户数据 +- 硬编码密钥/凭证 +- 执行未声明的网络请求 +- 生成恶意内容（病毒/钓鱼/诈骗） +- 绕过沙箱限制 +- 未授权的跨用户数据访问 + +## 4.8 变现与分润模型 + +### 4.8.1 定价模式 + +| 模式 | 说明 | 适用场景 | +|---|---|---| +| Free | 免费使用，平台补贴成本 | 引流技能、基础工具 | +| Subscription | 包含在会员套餐中 | 高频使用技能 | +| Pay Per Use | 按次/按 Token 付费 | 高成本技能（如视频生成） | +| One Time | 一次性购买永久使用 | 模板类技能 | +| Freemium | 基础免费 + 高级付费 | 大部分技能 | + +### 4.8.2 分润比例 + +``` +用户支付 100 元 +├── 平台服务费：30%（基础设施 + 分发 + 支付） +├── 技能开发者：60%（创作者激励） +├── 推荐人/推广：5%（如有推广链接） +└── 储备金：5%（退款/争议处理） +``` + +### 4.8.3 开发者结算 + +- 结算周期：月结（每月 15 日结算上月收入） +- 最低提现：100 元 +- 提现方式：支付宝 / 微信支付 / 银行卡 +- 税务：平台代扣代缴（如适用） + +## 4.9 技能 SDK 与脚手架 + +### 4.9.1 平台 SDK（Python） + +```python +# platform_sdk/client.py +from typing import Any +import httpx +import os + +class SkillContext: + """技能运行时上下文，由平台注入""" + def __init__(self, ctx: dict): + self.user_id = ctx["user_id"] + self.tenant_id = ctx["tenant_id"] + self.subscription_tier = ctx["tier"] + self.workspace_path = ctx["workspace_path"] + self.quota_remaining = ctx["quota"] + self.skill_config = ctx.get("config", {}) + +class PlatformClient: + """平台 API 客户端""" + def __init__(self, base_url: str, api_key: str): + self.base_url = base_url.rstrip("/") + self.client = httpx.Client(headers={"Authorization": f"Bearer {api_key}"}) + + def call_model(self, model: str, messages: list, **kwargs) -> dict: + """通过平台路由层调用模型（自动计量）""" + resp = self.client.post(f"{self.base_url}/api/v1/model/chat", json={ + "model": model, "messages": messages, **kwargs + }) + return resp.json() + + def upload_file(self, path: str) -> str: + """上传文件到用户工作区，返回 URL""" + with open(path, "rb") as f: + resp = self.client.post(f"{self.base_url}/api/v1/files", files={"file": f}) + return resp.json()["url"] + + def download_file(self, url: str, dest: str): + """下载文件到工作区""" + with self.client.stream("GET", url) as resp, open(dest, "wb") as f: + for chunk in resp.iter_bytes(): + f.write(chunk) + + def log_metric(self, name: str, value: Any): + """上报自定义指标""" + self.client.post(f"{self.base_url}/api/v1/metrics", json={"name": name, "value": value}) + + def check_quota(self) -> int: + """检查剩余配额""" + resp = self.client.get(f"{self.base_url}/api/v1/quota") + return resp.json()["remaining"] + +# === 技能入口模板 === +def main(ctx: SkillContext, params: dict, platform: PlatformClient) -> dict: + """ + 技能主入口函数。平台运行时调用此函数。 + ctx: 运行时上下文（用户/租户/配额/工作区） + params: 用户输入参数 + platform: 平台 API 客户端 + return: 输出结果（匹配 SKILL.md 的 outputs 声明） + """ + # 1. 检查配额 + if platform.check_quota() <= 0: + raise QuotaExceededError("配额不足") + + # 2. 调用模型（自动计量） + result = platform.call_model( + model="auto", # 平台自动选择最优模型 + messages=[{"role": "user", "content": params["text"]}] + ) + + # 3. 处理输出 + output = process_result(result) + + # 4. 上报指标 + platform.log_metric("tokens_used", result["usage"]["total_tokens"]) + + return {"result": output} +``` + +### 4.9.2 脚手架 CLI + +```bash +# 安装脚手架 +pip install platform-skill-cli + +# 创建新技能 +skill-cli create my-new-skill --template=presentation +# 交互式填写 SKILL.md +# 自动生成目录结构 + 示例代码 + +# 本地开发调试 +skill-cli dev my-new-skill +# 启动本地技能运行时 + 模拟平台上下文 + +# 运行测试 +skill-cli test my-new-skill +# 执行 tests/ 下的所有测试 + +# 打包提交 +skill-cli package my-new-skill +# 生成 .skill 包文件（ZIP + 签名） + +# 提交审核 +skill-cli submit my-new-skill.skill +# 上传到平台审核系统 +``` + +## 4.10 版本兼容与迁移 + +### 4.10.1 版本号规范（SemVer） + +``` +MAJOR.MINOR.PATCH + +MAJOR: 不兼容的 API 变更 +MINOR: 新增功能（向后兼容） +PATCH: Bug 修复（向后兼容） +``` + +### 4.10.2 平台版本兼容矩阵 + +| 技能版本 | 支持的平台版本 | 停止维护日期 | +|---|---|---| +| 2.x | ≥ 1.5.0 | TBD | +| 1.x | ≥ 1.0.0 | 2027-06-30 | + +### 4.10.3 迁移策略 + +- **自动迁移**：PATCH 版本自动更新，用户无感 +- **提示迁移**：MINOR 版本更新提示用户，可选跳过 +- **强制迁移**：MAJOR 版本更新需用户确认，旧版本保留 90 天 +- **灰度发布**：新版本先对 5% 用户开放，观察 48 小时无异常后全量 + +--- + +# 附录 + +## A. 技术选型最终建议表 + +| 层级 | 推荐方案 | 备选方案 | 选型理由 | +|---|---|---|---| +| 前端框架 | Next.js 15 + React 19 | Nuxt 3 / SvelteKit | 生态最丰富、SSR/SEO 友好 | +| UI 组件库 | shadcn/ui + Tailwind | Ant Design / Astryx | 可定制性强、设计感好 | +| 状态管理 | Zustand + TanStack Query | Redux Toolkit | 轻量、React 原生 | +| 后端框架 | FastAPI（Python） | NestJS（Node） | AI 生态最好、异步原生 | +| 数据库 | PostgreSQL 17+ | MySQL 8.4 | 向量/JSONB/RLS/图查询一体化 | +| 向量检索 | pgvector + pgvectorscale | Qdrant / Milvus | 与 PG 统一部署、运维简单 | +| 搜索引擎 | Meilisearch | Typesense / Elasticsearch | 中文分词、混合搜索、租户令牌 | +| 缓存/队列 | Redis 7+ | Dragonfly | 缓存 + 消息队列 + 限流 | +| 对象存储 | MinIO / S3 | 腾讯云 COS | 文件/图片/视频存储 | +| 认证 | JWT + OAuth2 + LDAP | Auth0 / Clerk | 自托管、可控 | +| 模型路由 | aisuite + 自研 Pipe | LiteLLM | 13+ 供应商统一抽象 | +| 沙箱 | gVisor / Firecracker | Docker seccomp | 强隔离、轻量 | +| 监控 | Prometheus + Grafana | Datadog | 开源、成熟 | +| 日志 | ELK / Loki | ClickHouse | 结构化日志、可检索 | +| CI/CD | GitHub Actions + Docker | GitLab CI | 生态最好 | +| 部署 | Docker Compose → K8s | 腾讯云 TKE | 从 MVP 到规模化的平滑路径 | + +## B. 数据库 Schema 草案（PostgreSQL） + +```sql +-- === 租户/用户 === +CREATE TABLE tenants ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name TEXT NOT NULL, + plan TEXT NOT NULL DEFAULT 'free', -- free/pro/enterprise + created_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE users ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID REFERENCES tenants(id), + email TEXT UNIQUE NOT NULL, + password_hash TEXT, + display_name TEXT, + role TEXT NOT NULL DEFAULT 'user', -- admin/developer/user/pending + subscription_tier TEXT DEFAULT 'free', + subscription_expires_at TIMESTAMP, + status TEXT DEFAULT 'active', + created_at TIMESTAMP DEFAULT NOW() +); + +-- === 技能 === +CREATE TABLE skills ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + name TEXT UNIQUE NOT NULL, + display_name TEXT NOT NULL, + version TEXT NOT NULL, + author_user_id UUID REFERENCES users(id), + category TEXT NOT NULL, + subcategory TEXT, + tags TEXT[], + description TEXT, + long_description TEXT, + icon_url TEXT, + status TEXT DEFAULT 'draft', -- draft/pending/approved/published/archived + pricing_model TEXT DEFAULT 'free', + tier_required TEXT DEFAULT 'free', + download_count INTEGER DEFAULT 0, + rating_average DECIMAL(3,2) DEFAULT 0, + rating_count INTEGER DEFAULT 0, + created_at TIMESTAMP DEFAULT NOW(), + updated_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE skill_versions ( + skill_id UUID REFERENCES skills(id), + version TEXT NOT NULL, + skill_md JSONB NOT NULL, -- 完整的 SKILL.md 内容 + manifest JSONB NOT NULL, + package_url TEXT NOT NULL, -- .skill 包下载地址 + is_current BOOLEAN DEFAULT false, + created_at TIMESTAMP DEFAULT NOW(), + PRIMARY KEY (skill_id, version) +); + +CREATE TABLE skill_installs ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id), + skill_id UUID REFERENCES skills(id), + version TEXT NOT NULL, + installed_at TIMESTAMP DEFAULT NOW(), + last_used_at TIMESTAMP, + settings JSONB DEFAULT '{}' +); + +-- === 技能实例（每次执行） === +CREATE TABLE skill_instances ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID REFERENCES tenants(id), + user_id UUID REFERENCES users(id), + skill_id UUID REFERENCES skills(id), + version TEXT NOT NULL, + status TEXT NOT NULL, -- generating/ready/failed/archived + input_params JSONB, + output_result JSONB, + tokens_used INTEGER DEFAULT 0, + duration_ms INTEGER DEFAULT 0, + error_message TEXT, + created_at TIMESTAMP DEFAULT NOW() +); + +-- === Token 计量 === +CREATE TABLE token_usage ( + id BIGSERIAL PRIMARY KEY, + tenant_id UUID REFERENCES tenants(id), + user_id UUID REFERENCES users(id), + skill_id UUID REFERENCES skills(id), + model TEXT NOT NULL, + input_tokens INTEGER NOT NULL, + output_tokens INTEGER NOT NULL, + cost DECIMAL(10,6) NOT NULL, + created_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE user_quotas ( + user_id UUID PRIMARY KEY REFERENCES users(id), + daily_token_limit INTEGER DEFAULT 100000, + daily_token_used INTEGER DEFAULT 0, + daily_skill_calls INTEGER DEFAULT 50, + daily_skill_used INTEGER DEFAULT 0, + last_reset DATE DEFAULT CURRENT_DATE, + total_storage_mb INTEGER DEFAULT 0, + max_storage_mb INTEGER DEFAULT 100 +); + +-- === 知识库 === +CREATE TABLE knowledge_bases ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + tenant_id UUID REFERENCES tenants(id), + user_id UUID REFERENCES users(id), + name TEXT NOT NULL, + description TEXT, + visibility TEXT DEFAULT 'private', -- private/shared/public + document_count INTEGER DEFAULT 0, + created_at TIMESTAMP DEFAULT NOW() +); + +CREATE TABLE documents ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + kb_id UUID REFERENCES knowledge_bases(id), + filename TEXT NOT NULL, + file_type TEXT, + file_size INTEGER, + chunk_count INTEGER DEFAULT 0, + embedding_model TEXT, + status TEXT DEFAULT 'processing', -- processing/ready/failed + created_at TIMESTAMP DEFAULT NOW() +); + +-- 向量表（pgvector） +CREATE TABLE document_chunks ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + document_id UUID REFERENCES documents(id), + chunk_index INTEGER NOT NULL, + content TEXT NOT NULL, + embedding vector(1536), -- text-embedding-3-large 维度 + metadata JSONB DEFAULT '{}' +); + +CREATE INDEX idx_chunks_embedding ON document_chunks + USING hnsw (embedding vector_cosine_ops) + WITH (m = 16, ef_construction = 64); + +-- === 订阅/计费 === +CREATE TABLE subscriptions ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id), + plan TEXT NOT NULL, -- free/pro/enterprise + status TEXT NOT NULL, -- active/cancelled/expired + started_at TIMESTAMP DEFAULT NOW(), + expires_at TIMESTAMP, + auto_renew BOOLEAN DEFAULT true +); + +CREATE TABLE payments ( + id UUID PRIMARY KEY DEFAULT gen_random_uuid(), + user_id UUID REFERENCES users(id), + amount DECIMAL(10,2) NOT NULL, + currency TEXT DEFAULT 'CNY', + payment_method TEXT, + status TEXT, -- pending/success/failed/refunded + description TEXT, + created_at TIMESTAMP DEFAULT NOW() +); + +-- === 审计日志 === +CREATE TABLE audit_logs ( + id BIGSERIAL PRIMARY KEY, + tenant_id UUID, + user_id UUID, + action TEXT NOT NULL, -- login/skill_execute/model_call/... + resource_type TEXT, + resource_id TEXT, + ip_address INET, + user_agent TEXT, + request_body JSONB, + response_code INTEGER, + duration_ms INTEGER, + created_at TIMESTAMP DEFAULT NOW() +); + +-- === RLS 策略 === +ALTER TABLE skill_instances ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON skill_instances + USING (tenant_id = current_setting('app.current_tenant')::UUID); + +ALTER TABLE documents ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON documents + USING (tenant_id = current_setting('app.current_tenant')::UUID); + +ALTER TABLE token_usage ENABLE ROW LEVEL SECURITY; +CREATE POLICY tenant_isolation ON token_usage + USING (tenant_id = current_setting('app.current_tenant')::UUID); +``` + +## C. 术语表 + +| 术语 | 定义 | +|---|---| +| PaaS | Platform as a Service，平台即服务 | +| RAG | Retrieval-Augmented Generation，检索增强生成 | +| MCP | Model Context Protocol，模型上下文协议 | +| Pipe | 模型路由管道，拦截并改写模型请求 | +| Filter | 请求/响应拦截器 | +| Skill | 平台上的可安装 AI 能力单元 | +| Tenant | 租户，平台上的独立组织/公司 | +| Workspace | 工作区，用户个人的文件/配置空间 | +| Token 驾驶舱 | 平台上的 Token 消耗监控仪表盘 | +| Loop Engineering | 设计 Agent 自治循环而非写 Prompt 的工程范式 | +| aisuite | 吴恩达团队的统一多厂商 LLM API 库 | +| gVisor | Google 的轻量级沙箱运行时 | +| Firecracker | AWS 的微虚拟机技术 | +| SemVer | Semantic Versioning，语义化版本规范 | +| RLS | Row Level Security，行级安全策略 | +| HNSW | Hierarchical Navigable Small World，向量索引算法 | +| BM25 | 经典信息检索排序算法 | +| Rerank | 对检索结果用精排模型重新排序 | +| FTS5 | SQLite 全文搜索扩展 | +| GIN | Generalized Inverted Index，PostgreSQL 倒排索引 | + +--- + +# 第五部分：七虎AI PaaS 平台 · 全面分析评估 + +> **被评估对象**：七虎AI（qihuyun.com）ARCHITECTURE.md v2.0 +> **评估方法**：「自家架构 vs 外部参照系」差距分析法 +> **参照系**：本文件前四部分（Open WebUI / Langflow / MemPalace / LiteLLM 等）+ Starred 28 个项目 +> **评估日期**：2026-07-27 + +## 5.1 评估方法论 + +评估采用"**自家架构 vs 外部参照系**"的差距分析法，覆盖 8 个维度： + +| 维度 | 权重 | 主要参照 | +|---|---|---| +| 多租户与隔离 | 12% | Open WebUI RBAC + PG RLS + Casdoor | +| 模型路由与 Failover | 14% | LiteLLM + OpenWorker aisuite + StaffDeck | +| 记忆/知识库/RAG | 14% | MemPalace + PGVector + Meilisearch | +| Agent 编排 | 12% | Langflow DAG + Loop Engineering + Octop | +| 技能市场与生命周期 | 14% | StaffDeck + dashi-ppt 改造方案 + baoyu-skills | +| 搜索/SEO/GEO | 8% | Meilisearch + TreeSearch | +| 安全与沙箱 | 14% | Open WebUI Filter + OpenWorker 四级审批 + Semantica | +| 运维/可观测/变现 | 12% | Prometheus + Langfuse + 分润模型 | + +每个维度给出：**现状 → 参照系最佳实践 → 差距 → 改进建议**。 + +## 5.2 逐维度差距分析 + +### 5.2.1 多租户与隔离（权重 12%） + +**现状**： +- Casdoor 统一认证（OAuth2/OIDC），JWT Bearer 认证 +- 角色仅 `user / admin` 两级 +- PG18 + pgvector，67 张表按域分组 +- RLS 策略未明确启用 + +**参照系**： +- Open WebUI：Admin/User/Pending + Groups + 组级配额 + LDAP/SSO/SCIM +- Casdoor v3.119：支持 RBAC + ABAC + Casbin + Agent-first IAM + MCP 网关 +- PG RLS：行级安全策略，租户隔离在数据库层强制实施 + +**差距与风险**： +1. 🔴 **角色模型过粗**：只有 user/admin 两级，无法支撑"技能开发者/企业管理员/普通用户/审核员"等细分角色 +2. 🔴 **RLS 未启用**：`token_usage_logs`、`skill_instances` 等表若无 RLS，应用层 bug 即可越权 +3. 🟡 **Casdoor 能力未充分释放**：2026 年的 Agent-first IAM 和 MCP 网关能力未被利用 +4. 🟢 **Casdoor 选型正确**：支持 OAuth2/OIDC/SAML/LDAP/SCIM/MFA，是最全面的开源 IAM 之一 + +**改进建议**： +| 优先级 | 行动 | 工期 | +|---|---|---| +| P0 | 启用 PG RLS，所有业务表加 `tenant_id` 隔离策略 | 3 天 | +| P0 | 角色扩展为 5 级：super_admin/admin/developer/user/guest | 5 天 | +| P1 | 用户组（Groups）机制，组级模型配额和技能可见性 | 5 天 | +| P1 | 利用 Casdoor 的 Agent-first IAM 做 MCP 工具鉴权 | 3 天 | +| P2 | SCIM 同步（企业用户生命周期） | 5 天 | + +### 5.2.2 模型路由与 Failover（权重 14%） + +**现状**： +- OpenAI 兼容协议接入 4+ 厂商（SiliconFlow/MiMo/AGNES/DeepSeek） +- 手动 failover：`try → except → continue 下一个模型`，最多 5 个备用 +- 自建 `build_openai_client`，支持 `auth_header` 自定义 +- 计划中：LiteLLM 集成 + +**参照系**： +- **LiteLLM**（27K+ Stars）：统一 100+ 供应商，OpenAI 格式一行切换，内置负载均衡、RPM/TPM 限流、虚拟密钥、成本追踪、自动 failover、Redis 缓存、Langfuse 日志。Netflix、Stripe 已在生产使用 +- **aisuite（OpenWorker）**：模型字符串即插即用，13+ 供应商 + +**差距与风险**： +1. 🔴 **自建 failover 是"穷人的 LB"**：顺序 try-except，没有 RPM/TPM 限流、没有加权负载均衡、没有按延迟路由。厂商部分降级时不会切流 +2. 🔴 **成本追踪缺失**：记了量但没按模型单价自动算钱，多模型混合场景下真实成本是一笔糊涂账 +3. 🟡 **auth_header 适配**：为 MiMo 写的自定义认证头思路正确，但 LiteLLM 已原生支持多种模式 +4. 🟢 **已识别到 LiteLLM**：路线图已列入，方向正确 + +**改进建议**： +| 优先级 | 行动 | +|---|---| +| P0 | 引入 LiteLLM Proxy 模式作为统一 AI 网关（客户端零改动） | +| P0 | 启用虚拟密钥（Virtual Keys），按租户/用户分发，精确追踪花费 | +| P1 | 启用 RPM/TPM 限流 + 加权负载均衡，替换 try-except failover | +| P1 | 启用 Redis 缓存（相同 prompt 不重复计费） | +| P2 | 接入 Langfuse/Arize 做全链路可观测 | + +> 💡 **关键判断**：模型路由是技术护城河的一部分。当前是"手动挡"，LiteLLM 一步升级到"自动驾驶"，开源自托管零抽成，与"平台不赚差价"定位完全契合。 + +### 5.2.3 记忆/知识库/RAG（权重 14%） + +**现状**： +- PG18 + pgvector 统一存储 +- 混合检索（BM25 + vector） +- 知识图谱节点/边表已建 +- 结构化记忆抽取（实体/事实/偏好/决策/待办 五类） +- 上下文压缩（后台异步递归压缩） + +**参照系**： +- **MemPalace v3.6**：原文逐字存储、Wing→Room→Drawer 分层、BM25+语义+结构混合、LongMemEval R@5 96.6%（raw）/ 98.4%（hybrid） +- **Meilisearch**：sub-50ms、TinySegmenter 中文分词（0.2ms，比 jieba 快 25 倍）、租户令牌、混合搜索 +- **Semantica**：图原生 + W3C PROV-O 溯源 + 决策生命周期 + 冲突检测 + +**差距与风险**： +1. 🟡 **pgvector 检索质量未量化**：没有公开 benchmark。建议跑 LongMemEval 或 BEIR 拿到 R@K +2. 🟡 **记忆分层缺失**：五类结构化记忆有了，但缺 Wing(人/项目)→Room(主题)→Drawer(原文) 的空间索引。长期运行会串味 +3. 🔴 **搜索体验是短板**：架构文档未提 Meilisearch，中文分词用 PG 的 `ts_zh` 效果远不如 Meilisearch 的 TinySegmenter +4. 🟢 **统一 PG 选型正确**：主库+向量+图谱同集群，零网络延迟、事务一致 +5. 🟢 **结构化记忆抽取**是亮点，比大多数平台超前 + +**改进建议**： +| 优先级 | 行动 | +|---|---| +| P0 | 引入 Meilisearch 做技能市场搜索 + 平台内容索引 | +| P1 | 引入 MemPalace 的 Wing/Room/Drawer 分层模型，叠加到五类结构化记忆 | +| P1 | 跑 LongMemEval benchmark，量化 RAG 真实召回率 | +| P2 | 评估 Semantica 做决策溯源 + 冲突检测（金融/医疗客户刚需） | + +### 5.2.4 Agent 编排（权重 12%） + +**现状**： +- DAG 图引擎 + YAML 定义 + Kahn 拓扑排序 + 分层并行 +- 节点类型：llm / local / external / reduce +- 失败隔离（per-node on_error=halt|continue） +- 外部 Agent 远程调用（Dify/n8n/Coze） +- 计划中：LangGraph 集成、Supervisor 多 Agent + +**参照系**： +- **Langflow**：400+ 内置组件、18 个 Service、React Flow 画布、SSE 事件流、MCP Composer +- **Loop Engineering**：从"写 prompt"到"设计 loop"，Verifier Skills + Goal Audit +- **Octop（腾讯云）**：IM 集成 + ACP 双向 +- **EigenFlux**：Agent 间广播网络 + +**差距与风险**： +1. 🟡 **缺可视化编排 UI**：有 DAG 引擎但用户需要画布（像 Langflow 拖拽连节点），否则只是工程师玩具 +2. 🟡 **Loop 原语缺失**：DAG 是有向无环图，但 Agent 自治需要循环（retry、self-refine、verifier-revisor） +3. 🟢 **外部 Agent 远程调用**是差异化亮点 +4. 🟢 **失败隔离 + 并发安全**实现正确 + +**改进建议**： +| 优先级 | 行动 | +|---|---| +| P0 | 前端加 Agent 可视化编排画布（基于 React Flow，参考 Langflow 交互） | +| P1 | 引入 Loop 原语：循环边 + 终止条件 + Verifier | +| P1 | 接入 Langfuse/LangSmith 做 Agent 执行轨迹追踪 | +| P2 | 评估 EigenFlux 的 Agent 广播模式做技能间协作 | + +### 5.2.5 技能市场与生命周期（权重 14%）—— 核心差异化 + +**现状**： +- Skills 上架-搜索-安装-执行闭环，14 个能力分类 +- 完整生命周期表：market_apps/versions/purchases/reviews/installations/publish_records/evolution_* +- 进化机制：evolution_skills/events/trajectories +- "Skill 真实执行器"进行中（当前是 LLM 转发模拟） +- 计划中：技能 SDK 发布工具 + +**参照系**： +- **StaffDeck**：数字员工 = 技能包 + 知识库 + 工作流，市场资源权限保护 + 复制绑定 +- **dashi-ppt-skill 改造方案**（本文件第三部分）：完整 SKILL.md Schema、API 适配层、多租户隔离、配额、上架清单 +- **baoyu-skills**：20+ 技能、统一 SKILL.md 规范 +- **Open WebUI 插件体系**：Filters/Actions/Pipes/Tools/Skills 五类 + +**差距与风险**： +1. 🔴 **技能执行仍是"模拟"**：当前是 LLM 转发提示词，不是真实可执行的能力单元。用户发现"技能=换了个提示词"后信任会崩塌 +2. 🔴 **SKILL.md 规范未标准化**：技能的元数据 Schema（输入输出/权限/资源/依赖声明）还没有统一规范 +3. 🟡 **进化机制需验证**：`evolution_*` 设计超前，但需证明"技能真的越用越聪明" +4. 🟢 **生命周期闭环**比 Dify/Coze/FastGPT 都完整 +5. 🟢 **14 个分类**覆盖面广 + +**改进建议**： +| 优先级 | 行动 | +|---|---| +| P0 | 落地"真实执行器"——先改造 3 个标杆技能（dashi-ppt/SEO 优化/投研报告）跑通端到端 | +| P0 | 发布平台统一 SKILL.md Schema（本文件 4.3 节 9 大区块规范） | +| P1 | 发布技能 SDK + 脚手架 CLI（本文件 4.9 节代码） | +| P1 | 技能审核流水线（自动 CI + 人工，本文件 4.5 节） | +| P2 | 进化机制可视化：技能详情页展示"这个技能最近学会了什么" | + +### 5.2.6 搜索/SEO/GEO（权重 8%） + +**现状**：架构文档未明确提及平台级搜索基础设施，技能市场搜索依赖 PG 全文检索（推测）。 + +**参照系**： +- **Meilisearch**：sub-50ms、TinySegmenter 中文分词、混合搜索、租户令牌、过滤/分面 +- **TreeSearch**：零向量零 API，FTS5 毫秒级 +- 平台定位强调"适合 SEO 和 GEO 搜索" + +**差距与风险**： +1. 🔴 **架构文档最大空白**：强调 SEO/GEO 却没有搜索基础设施设计章节 +2. 🔴 **PG 全文检索做技能市场搜索是错的**：中文分词弱、排序不灵活、无法分面筛选 +3. 🟢 方向已识别，只差落地 + +**改进建议**：立即引入 Meilisearch。投入产出比最高——单二进制部署、零依赖、中文分词开箱即用，同时解决技能市场搜索 + 平台 SEO 索引 + GEO 富摘要三个问题。 + +### 5.2.7 安全与沙箱（权重 14%） + +**现状**： +- `_check_tool_policy()` 三层防护：白名单/预算/每轮上限 +- 代码执行：独立 executor 容器沙箱 +- 密钥管理：credential.py 加解密 +- 认证：Casdoor + JWT + +**参照系**： +- **OpenWorker 四级审批**：read/write_local/exec/external + 无人值守收件箱 +- **Open WebUI Filter 链**：敏感词/Token 计量/审计统一拦截 +- **Semantica**：W3C PROV-O 决策溯源 + 冲突检测 +- **沙箱选项**：gVisor / Firecracker（比 Docker 隔离更强） + +**差距与风险**： +1. 🟡 **工具策略够用但不细**：缺 OpenWorker 的按风险等级分级审批和无人值守收件箱 +2. 🟡 **沙箱强度未说明**：executor 容器是 Docker 还是 gVisor/Firecracker？前者逃逸风险更高 +3. 🟢 Casdoor + JWT 选型正确 +4. 🟢 密钥加解密存储正确 + +**改进建议**： +| 优先级 | 行动 | +|---|---| +| P1 | 工具调用升级为四级风险分类（参考 OpenWorker），external 级必须显式确认 | +| P1 | executor 容器评估升级到 gVisor 或 Firecracker | +| P2 | 引入 Semantica 的 PROV-O 溯源做决策可解释（企业客户刚需） | + +### 5.2.8 运维/可观测/变现（权重 12%） + +**现状**： +- Prometheus + Grafana + Alloy + node-exporter +- 应用日志 → docker logs / Alloy +- CI：pre-push hook 跑 pytest + vitest +- 计费：Token + 会员 +- 28 个 pytest + 15 个 vitest 用例 + +**参照系**： +- **LiteLLM 成本追踪**：按 key/user/team 自动算钱、虚拟密钥预算上限 +- **Langfuse/Arize**：Agent 执行轨迹可视化 +- 本文件 4.8 节分润模型（平台 30%/开发者 60%/推荐 5%/储备 5%） + +**差距与风险**： +1. 🟡 **Token 计费是"批处理"不是"流式"**：记的是调用后 usage，用户用超了才发现 +2. 🟡 **变现模型未文档化**：架构文档没提分润比例、开发者结算周期、提现方式 +3. 🟢 监控栈选型标准、CI 门槛正确 +4. 🟢 测试覆盖存在 + +**改进建议**： +| 优先级 | 行动 | +|---|---| +| P0 | 接入 LiteLLM 成本追踪，实现流式扣费 + 实时余额 | +| P1 | 落地分润模型（本文件 4.8 节）+ 开发者结算后台 | +| P2 | Agent 轨迹接入 Langfuse，做"对话可回放" | + +## 5.3 综合竞争力评估 + +### 5.3.1 护城河再评估（修正自评） + +| 护城河 | 自评 | 修正 | 理由 | +|---|---|---|---| +| 多模型协议适配层 | 🔴 高 | 🟡→🔴 | 引入 LiteLLM 后才能算"高" | +| Skill 全生命周期 | 🔴 高 | 🔴 高 | 真实差异化，但需落地真实执行器 | +| Agent DAG 编排 | 🟡 中 | 🟡 中 | 缺可视化画布和 Loop 原语 | +| 工具调用标准化 | 🟡 中 | 🟡 中 | 基础正确，缺分级审批 | +| PG 统一数据层 | 🟡 中 | 🔴 高 | 被低估——PG18+pgvector+JSONB+RLS 是杀手锏 | +| IM Bot 多平台 | 🟢 低 | 🟢→🟡 | 统一消息网关有壁垒，尤其微信生态 | +| 安全沙箱 | 🟡 中 | 🟡 中 | 基础够用，沙箱强度待升级 | + +### 5.3.2 竞品对比修正 + +- **Dify**（75K+ Stars）：RAG 可控性和知识图谱 2025 已补强，是最强开源对手 +- **FastGPT**：私有化零抽成定位一致，但平台化/Skill 市场/Agent 编排远不如 +- **Coze Studio**：已开源（Apache 2.0），字节生态渠道分发能力是短板 + +### 5.3.3 总评 + +> **七虎AI v2.0 方向正确、骨架完整、关键肌肉待练。** +> +> 最该立刻动手的三件事（按 ROI 排序）： +> 1. **引入 LiteLLM + Meilisearch**——各 1-3 天，补上模型路由和搜索最大短板 +> 2. **落地技能真实执行器 + SKILL.md 规范**——差异化护城河核心，从模拟变真实 +> 3. **启用 PG RLS + 角色扩展**——多租户安全底线 + +## 5.4 落地优先级总表 + +| 序号 | 行动 | 维度 | 优先级 | 工期 | 依赖 | +|---|---|---|---|---|---| +| 1 | 引入 LiteLLM Proxy 做统一 AI 网关 | 模型路由 | P0 | 3 天 | 无 | +| 2 | 引入 Meilisearch 做技能市场搜索 | 搜索 | P0 | 2 天 | 无 | +| 3 | 启用 PG RLS + tenant_id 隔离 | 多租户 | P0 | 3 天 | 无 | +| 4 | 角色扩展为 5 级 + 用户组 | 多租户 | P0 | 5 天 | #3 | +| 5 | 落地 3 个标杆技能真实执行器 | 技能市场 | P0 | 2 周 | 无 | +| 6 | 发布统一 SKILL.md Schema | 技能市场 | P0 | 3 天 | 无 | +| 7 | 流式 Token 计费 + 实时余额 | 变现 | P0 | 5 天 | #1 | +| 8 | Agent 可视化编排画布 | Agent | P1 | 2 周 | 无 | +| 9 | 引入 Loop 原语 + Verifier | Agent | P1 | 1 周 | #8 | +| 10 | 工具调用四级风险审批 | 安全 | P1 | 3 天 | 无 | +| 11 | executor 升级 gVisor | 安全 | P1 | 3 天 | 无 | +| 12 | 跑 LongMemEval 量化 RAG | RAG | P1 | 2 天 | 无 | +| 13 | 引入 MemPalace 分层记忆 | RAG | P2 | 1 周 | #12 | +| 14 | 技能 SDK + 脚手架 CLI | 技能市场 | P1 | 1 周 | #6 | +| 15 | 技能审核流水线 | 技能市场 | P2 | 1 周 | #6 | +| 16 | 分润模型 + 开发者结算 | 变现 | P1 | 1 周 | #7 | +| 17 | Langfuse Agent 轨迹 | 可观测 | P2 | 3 天 | #1 | +| 18 | Semantica 决策溯源 | 安全/合规 | P2 | 评估 | 无 | +| 19 | 前端暗色模式 | 体验 | P2 | 3 天 | 无 | +| 20 | 移动端适配 | 体验 | P2 | 2 周 | 无 | + +--- + +> **文档版本**：v2.0.0 +> **更新日期**：2026-07-27 +> **变更说明**：新增第五部分「七虎AI PaaS 平台 · 全面分析评估」，基于 ARCHITECTURE.md v2.0 与外部参照系做差距分析 +> **下一步行动**：将本文件喂给 WorkBuddy，按 5.4 节优先级总表逐项推进落地。