microsoft/Ontology-Playground Source: https://github.com/microsoft/Ontology-Playground # Ontology Playground（预览）☕ > 注意：本项目使用了 AI 辅助编码。 立即试用 → microsoft.github.io/Ontology-Playground (https://microsoft.github.io/Ontology-Playground/) Ontology Playground 截图 (https://microsoft.github.io/Ontology-Playground/) 一个免费、开源的学习本体和 Microsoft Fabric IQ 的 Web 应用程序。浏览预构建的本体，在可视化编辑器中设计自己的本体，导出为 RDF/XML，并分享交互式图表——这一切都来自一个完全静态的站点，无需任何后端依赖。 Microsoft Fabric React TypeScript License ## 功能特性 ### 交互式图谱探索 基于 Cytoscape.js 的图谱，可将任何本体渲染为交互式的节点-边图。支持平移、缩放、点击节点查看属性，并使用实时搜索栏过滤实体和关系。 ### 本体目录 一个精选库，包含官方和社区贡献的本体，涵盖六个领域（零售、电子商务、医疗、金融、制造、教育）。可按类别浏览、按名称或标签搜索、一键加载任意本体并查看其 RDF 源代码。每个本体都有可共享的深度链接（/#/catalogue/official/cosmic-coffee）。 ### 可视化本体设计器 全屏分栏编辑器，用于从头创建本体或编辑现有本体。可添加带图标、颜色和类型属性的实体类型；定义带基数约束的关系；实时预览图谱并在工作时更新。支持撤销/重做（50 层）、实时验证以及导出为 RDF/XML 或 JSON。 ### RDF 导入与导出 完全支持 RDF/XML 的往返操作（OWL 类、数据类型属性、带基数约束的对象属性）。可导入 .rdf / .owl 文件，以 Microsoft Fabric IQ 所期望的精确格式导出，并通过自动化往返测试验证保真度。 ### 一键目录 PR 使用 GitHub（设备流）登录，直接从设计器将您的本体提交到社区目录——应用会自动 fork 仓库、创建分支、提交 RDF 和元数据，并自动发起一个拉取请求。 ### 可嵌入小部件 一个自包含的 JavaScript 文件（ontology-embed.js），只需一个 <script> 标签即可在任何网页上渲染交互式本体查看器。支持深色/浅色主题、多种加载方式（目录 ID、URL、内联 base64）以及点击查看详情。详情请参阅嵌入指南。 ### 本体学堂 结构化学习中心（/#/learn），包含 9 门课程，涵盖概念学习路径和动手实验： - 本体基础 — 6 篇文章，涵盖核心概念（什么是本体？→ RDF/OWL → Fabric IQ → 构建第一个本体 → 设计模式 → 贡献指南） - 7 个领域学习路径 — Fourth Coffee、电子商务、金融、医疗、制造、大学和人力资源系统。每个路径包含 4 篇渐进式文章，逐步构建本体，并附带实时嵌入图谱显示每个阶段的新实体。 - IQ 实验：零售供应链 — 7 步动手实验，从零开始构建包含 15 个实体的本体（从 3 到 15 个实体，跨越 6 个渐进式目录条目）。每篇文章支持演示模式（以 ## 标题分隔幻灯片）并包含交互式测验，即时反馈。本体嵌入可从目录加载实时图谱，并可选择突出差异。 ### 任务系统 五个渐进式任务，通过多步指令、提示、进度条和成就徽章引导用户学习本体概念。 ### 自然语言查询游乐场 输入自然语言问题（“哪些客户下了订单？”），查看它们如何映射到本体实体和关系——这是 Fabric IQ 的 NL2Ontology 能力的预览。 ### 命令面板与键盘快捷键 在任何位置按 ⌘K / Ctrl+K 可打开可搜索的命令面板。无需离开键盘即可跳转到目录、设计器、本体学堂、导入/导出、帮助等页面。按 ? 快速访问帮助。使用方向键 + Enter 导航面板。 ### 起始模板 设计器提供五个领域模板（零售、医疗、金融、IoT、教育），让新用户不会面对空白页面。每个模板创建 3 个实体（带属性）和 2 个关系，可随时自定义。 ### 交互式引导导览 首次访问者将经历一个 5 步引导导览，带有聚光灯叠加层，依次高亮显示标题栏、图谱、任务、检查器和设计器。可通过“不再显示”选项关闭，该选项持久化到 localStorage。 ### 深度链接与 URL 路由 基于哈希的客户端路由，为每个页面提供可分享的 URL： | 路由 | 页面 | |—––|——| | /#/ | 首页（默认本体） | | /#/catalogue | 本体画廊 | | /#/catalogue/<source>/<slug> | 特定本体（例如 /#/catalogue/official/cosmic-coffee） | | /#/designer | 可视化设计器 | | /#/designer/<source>/<slug> | 带目录本体的设计器（例如 /#/designer/official/cosmic-coffee） | | /#/learn | 本体学堂——课程目录 | | /#/learn/<course> | 课程详情——文章列表 | | /#/learn/<course>/<article> | 文章视图（带演示模式） | ## 官方本体 | 领域 | 本体名称 | 实体数 | 关系数 | |––––|–––––|–––––|—————| | 零售 | Fourth Coffee | 6 | 7 | | 电子商务 | 在线零售 | 5 | 6 | | 医疗 | 临床系统 | 5 | 6 | | 金融 | 银行与金融 | 5 | 6 | | 制造 | 工业 4.0 | 5 | 5 | | 教育 | 大学系统 | 5 | 6 | ## 快速开始 ### 前置条件 - Node.js 18+ - npm 9+ ### 安装 bash cd Ontology-Playground npm install ### 开发 bash npm run dev 访问 http://localhost:5173 ### 生产构建 bash npm run build 构建流程会编译目录、编译学习内容 markdown、进行类型检查、打包应用并构建嵌入小部件。输出在 build/ 目录。 ### 运行测试 bash npm test # 单次运行 npm run test:watch # 监听模式 ## 部署 ### Azure 静态 Web 应用（主要） 仓库附带一个 GitHub Actions 工作流，每次推送到 main 分支时部署到 Azure SWA。 1. 在 Azure 门户中创建一个静态 Web 应用 2. 连接到您的 GitHub 仓库 3. 复制部署令牌并添加为 GitHub 密钥 AZURE_STATIC_WEB_APPS_API_TOKEN_GREEN_PLANT_0BB1D2910 4. 推送到 main——工作流 .github/workflows/azure-static-web-apps-green-plant-0bb1d2910.yml 会处理其余部分 5. 拉取请求的预览环境会自动创建 ### GitHub Pages（适用于 fork） 另一个工作流部署到 GitHub Pages，适合 fork 场景： 1. Fork 本仓库 2. 进入 设置 → Pages → 源 并选择 GitHub Actions 3. 推送到 main——工作流 .github/workflows/deploy-ghpages.yml 会构建并部署到 https://<用户名>.github.io/<仓库名>/ 在 GitHub Pages 构建过程中会自动设置 VITE_BASE_PATH 环境变量为 /<仓库名>/，以确保资源路径正确。 ### 环境变量 | 变量 | 默认值 | 描述 | |–––––|———|———––| | VITE_ENABLE_AI_BUILDER | false | 启用 Azure OpenAI 本体构建器 | | VITE_ENABLE_LEGACY_FORMATS | false | 启用 JSON/YAML/CSV 导入/导出格式 | | VITE_BASE_PATH | / | 应用的基路径（GitHub Pages 会自动设置） | | VITE_GITHUB_CLIENT_ID | (空) | GitHub OAuth 应用客户端 ID，用于一键目录 PR（设置指南） | | VITE_GITHUB_OAUTH_BASE | (空) | 用于 GitHub Pages 部署的外部 OAuth 代理 URL（例如 Cloudflare Worker URL） | ## 项目结构 Ontology-Playground/ ├── src/ │ ├── components/ # React 组件（图谱、设计器、模态框、学习页面） │ ├── data/ # 本体模型、查询引擎、任务定义 │ ├── lib/ # 路由器、RDF 解析器/序列化器、目录辅助函数 │ ├── store/ # Zustand 存储（应用状态、设计器状态） │ ├── styles/ # CSS（受 Microsoft Fluent 启发的深色/浅色主题） │ └── types/ # TypeScript 类型定义 ├── catalogue/ # 官方 + 社区本体 RDF 文件 ├── content/learn/ # 课程目录，包含 markdown 文章、测验和元数据 ├── scripts/ # 构建时编译器（目录、学习内容） ├── api/ # Azure Functions 后端（可选，用于 AI 构建器） ├── docs/ # 指南和文档 ├── public/ # 静态资源（编译后的 catalogue.json、learn.json） └── .github/workflows/ # CI/CD（Azure SWA + GitHub Pages） ## 文档 下表列出了主要的最终用户和贡献者指南。内部规划笔记（例如 docs/TODO-*.md）有意不包含在已发布的文档集中。 | 指南 | 描述 | |—––|———––| | 本体创作指南 | 如何在 Playground 中创建好用的本体——逐字段参考、最佳实践及分步指南 | | 贡献本体：从设计到 GitHub | 端到端贡献工作流：设计、RDF 导出、元数据、本地验证和拉取请求 | | Playground 功能演示指南 | 分步演示脚本，展示 Playground 的关键功能并将其与 Fabric IQ 和实时智能关联 | | 本体学堂演示指南 | 针对课程、嵌入、测验、演示模式和学习工作流的分步实时演示计划 | | 嵌入指南 | 如何在任意网页中嵌入交互式本体小部件 | | GitHub OAuth 设置 | 如何配置 GitHub OAuth 以实现一键目录 PR | | 嵌入安全性 | 可嵌入小部件的安全模型 | | 学习内容指南 | 如何为本体学堂编写课程、文章、测验和本体嵌入 | | 本体学堂审查工作流 | 用于学堂课程内容的人工审核与批准流程 | | 主题创作指南 | 如何为 Playground 添加新配色主题——令牌契约、appStore + CSS 步骤及对比度注意事项 | ## AI 代理快速入门 本仓库包含 Copilot 自定义文件，使代理能够可靠地： - 将客户 RDF/OWL 导入为目录就绪格式 - 生成渐进式的本体学堂模块 - 将课程内容路由到人工审查工作流 包含的资源： - 技能： - .github/skills/ontology-catalog-import/ — 将外部/客户 RDF/OWL 导入目录格式 - .github/skills/ontology-school-path-generator/ — 生成渐进式的本体学堂模块 - .github/skills/community-ontology-contribution/ — 在 catalogue/community/ 下添加贡献者本体，包含正确的目录结构、元数据和验证 - .github/skills/name-generator/ — 从经批准的 CSV 资产中生成示例、演示、任务、测试和示例数据中使用的人名 - RDF 摄入指令： - .github/instructions/rdf-intake.instructions.md - 可复用提示： - .github/prompts/import-rdf-to-catalog.prompt.md - .github/prompts/generate-ontology-school-module.prompt.md 推荐在合并前进行验证： bash npm run qa:tutorial-content npm run build ## 技术栈 - React 19 + TypeScript 5 - Cytoscape.js — 图谱可视化（fcose 布局） - Zustand — 状态管理 - Vite — 构建工具 - Framer Motion — 动画 - Lucide Icons — 图标库 - marked — Markdown 编译（构建时） ## 了解更多 - Microsoft Fabric IQ 本体文档 (https://learn.microsoft.com/en-us/fabric/iq/ontology/overview) - Azure 静态 Web 应用 (https://docs.microsoft.com/azure/static-web-apps/) ## 许可证 MIT ## 商标声明 本项目中可能包含项目、产品或服务的商标或徽标。经授权的 Microsoft 商标或徽标的使用必须遵守 Microsoft 的商标和品牌指南。在修改版本中使用 Microsoft 商标或徽标不得引起混淆或暗示 Microsoft 的赞助。任何第三方商标或徽标的使用均受该第三方政策的约束。