# 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，逐项验证并推进落地执行。