From 2439f7956da3c0d26c2acb5d60f38deae8a0f2e3 Mon Sep 17 00:00:00 2001 From: qyyfw <120122225@qq.com> Date: Mon, 27 Jul 2026 09:20:51 +0800 Subject: [PATCH] =?UTF-8?q?=E5=88=A0=E9=99=A4=20AI=5FPaaS=5FPlatform=5FAna?= =?UTF-8?q?lysis=5Fand=5FExecution=5FPlan.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...aS_Platform_Analysis_and_Execution_Plan.md | 1759 ----------------- 1 file changed, 1759 deletions(-) delete mode 100644 AI_PaaS_Platform_Analysis_and_Execution_Plan.md diff --git a/AI_PaaS_Platform_Analysis_and_Execution_Plan.md b/AI_PaaS_Platform_Analysis_and_Execution_Plan.md deleted file mode 100644 index fbfc869..0000000 --- a/AI_PaaS_Platform_Analysis_and_Execution_Plan.md +++ /dev/null @@ -1,1759 +0,0 @@ -# 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 倒排索引 | - ---- - -> **文档版本**：v1.0.0 -> **生成日期**：2026-07-27 -> **适用平台版本**：AI PaaS Platform MVP → v1.0 -> **反馈渠道**：平台内部 Issue Tracker / 架构组邮件 -> **下一步行动**：将此文档喂给 WorkBuddy，逐项验证并推进落地执行。