Ontology Playground（预览版）☕

注意：此项目借助 AI 辅助编码完成。

立即试用 → microsoft.github.io/Ontology-Playground

这是一款免费、开源的网页应用，用于学习本体以及 Microsoft Fabric IQ。你可以浏览预建本体、在可视化编辑器中设计自己的本体、导出为 RDF/XML，并分享交互式图表——所有功能都运行在一个完全静态的站点上，零后端依赖。

交互式图谱探索

基于 Cytoscape.js 的图谱引擎，可将任何本体渲染为交互式的节点-关系图表。支持平移、缩放、点击节点查看属性，并使用实时搜索栏过滤实体和关系。

一个精选的官方和社区贡献本体库，涵盖六大领域（零售、电子商务、医疗、金融、制造、教育）。可按分类浏览、按名称或标签搜索，一键加载任意本体并查看其 RDF 源码。每个本体都有一个可分享的深层链接 (/#/catalogue/official/cosmic-coffee)。

全屏分栏编辑器，可从零开始创建本体或编辑已有本体。添加实体类型时支持图标、颜色和带类型的属性；定义关系时可设置基数；编辑器实时提供图形预览，随编写同步更新。包含撤销/重做（50 级）、实时校验以及导出为 RDF/XML 或 JSON 的功能。

对 RDF/XML（OWL 类、数据类型属性、带基数约束的对象属性）实现了完整的往返支持。可导入 .rdf / .owl 文件，导出为 Microsoft Fabric IQ 所需的准确格式，并通过自动化的往返测试验证保真度。

使用 GitHub（设备流）登录，即可直接从设计器将本体提交到社区目录——应用会自动 fork 仓库、创建分支、提交 RDF 和元数据，并自动打开 Pull Request。

一个自包含的 JavaScript 文件 (ontology-embed.js)，只需一个 <script> 标签即可在任何网页上渲染交互式本体查看器。支持深色/浅色主题、多种加载方式（目录 ID、URL、内联 base64）以及点击查看详情。详见 嵌入指南。

一个结构化的学习中心 (/#/learn)，提供 9 门课程，涵盖概念学习路径和动手实验：

• 本体基础 — 6 篇文章覆盖核心概念（什么是本体？→ RDF/OWL → Fabric IQ → 构建第一个本体 → 设计模式 → 贡献指南）
• 7 条领域学习路径 — Fourth Coffee、电子商务、金融、医疗、制造、大学和人力资源系统。每条路径包含 4 篇渐进式文章，逐步构建本体，每阶段均通过嵌入的实时图谱展示新实体。
• IQ 实验：零售供应链 — 一个 7 步动手实验，从零开始构建包含 15 个实体的本体（通过 6 个递进目录条目从 3 个实体扩展到 15 个）。

每篇文章都支持演示模式（按 ## 标题分页）并包含交互式测验，可即时获得反馈。本体嵌入会从目录加载实时图谱，并可选择高亮差异。

五个渐进式任务，通过多步指令、提示、进度条和成就徽章引导用户理解本体概念。

自然语言查询体验场

输入自然语言问题（“哪些客户下了订单？”），即可查看如何映射到本体实体和关系——这是 Fabric IQ 的 NL2Ontology 能力的预览。

命令面板与键盘快捷键

在任何位置按 ⌘K / Ctrl+K 即可打开可搜索的命令面板。无需离开键盘即可跳转到目录、设计器、Ontology School、导入/导出、帮助等。按 ? 快速访问帮助。使用方向键 + Enter 浏览面板。

设计器提供五种领域模板（零售、医疗、金融、物联网、教育），让新用户不会面对空白页面。每个模板创建 3 个具有属性和 2 个关系的实体，随时可以自定义。

交互式引导教程

首次访问者会看到一个 5 步引导教程，通过聚光灯覆盖层依次突出显示页头、图谱、任务、检查器和设计器。可通过持久保存到 localStorage 的“不再显示”选项关闭。

深层链接与 URL 路由

客户端 hash 路由，为每个页面提供可分享的 URL：

路由	页面
/#/	首页（默认本体）
/#/catalogue	本体画廊
/#/catalogue/<source>/<slug>	特定本体（例如 /#/catalogue/official/cosmic-coffee）
/#/designer	可视化设计器
/#/designer/<source>/<slug>	加载目录本体的设计器（例如 /#/designer/official/cosmic-coffee）
/#/learn	Ontology School — 课程目录
/#/learn/<course>	课程详情 — 文章列表
/#/learn/<course>/<article>	文章视图（含演示模式）

领域	本体	实体数	关系数
零售	Fourth Coffee	6	7
电子商务	Online Retail	5	6
医疗	Clinical System	5	6
金融	Banking & Finance	5	6
制造	Industry 4.0	5	5
教育	University System	5	6

bash cd Ontology-Playground npm install

访问 http://localhost:5173

构建管道会编译目录、编译学习内容 Markdown、进行类型检查、打包应用并构建嵌入组件。输出位于 build/ 目录。

bash npm test # 单次运行 npm run test:watch # 监听模式

Azure Static Web Apps（主要方式）

仓库附带一个 GitHub Actions 工作流，每次推送到 main 分支时自动部署到 Azure SWA。

1. 在 Azure Portal 中创建一个 Static Web App
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. 拉取请求会自动创建 PR 预览环境

另一个工作流用于部署到 GitHub Pages，适合 fork 后的使用：

1. Fork 本仓库
2. 进入 Settings → Pages → Source，选择 GitHub Actions
3. 推送到 main 分支——.github/workflows/deploy-ghpages.yml 工作流会构建并部署到 https://<username>.github.io/<repo-name>/

VITE_BASE_PATH 环境变量在 GitHub Pages 构建过程中会自动设置为 /<repo-name>/，以确保资源路径正确解析。

变量	默认值	描述
VITE_ENABLE_AI_BUILDER	false	启用 Azure OpenAI 本体构建器
VITE_ENABLE_LEGACY_FORMATS	false	启用 JSON/YAML/CSV 导入/导出格式
VITE_BASE_PATH	/	应用的基路径（GitHub Pages 部署时自动设置）
VITE_GITHUB_CLIENT_ID	(空)	用于一键目录 Pull Request 的 GitHub OAuth App 客户端 ID（设置指南）
VITE_GITHUB_OAUTH_BASE	(空)	用于 GitHub Pages 部署的外部 OAuth 代理 URL（例如 Cloudflare Worker URL）

text 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 导出、元数据、本地校验和 Pull Request
Playground 特性演示指南	分步演示脚本，展示核心 Playground 功能，并连接到 Fabric IQ 和 Real-Time Intelligence
Ontology School 演示指南	针对课程、嵌入、测验、演示模式和学习工作流的分步现场演示计划
嵌入指南	如何将交互式本体组件嵌入任何网页
GitHub OAuth 设置	如何配置 GitHub OAuth 以实现一键目录 PR
嵌入安全性	可嵌入组件的安全模型
学习内容指南	如何为 Ontology School 创作课程、文章、测验和本体嵌入
Ontology School 审核工作流	学校课程内容的人工审核和批准流程
主题创作指南	如何将新的颜色主题插入 Playground——令牌约定、appStore + CSS 步骤以及对比度注意事项

本仓库包含 Copilot 自定义文件，使代理能够可靠地：

• 将客户 RDF/OWL 导入为目录就绪格式
• 生成渐进式的 Ontology School 模块
• 通过人工审核工作流路由课程内容

包含的资产：

• 技能：
  • .github/skills/ontology-catalog-import/ — 将外部/客户 RDF/OWL 导入为目录格式
  • .github/skills/ontology-school-path-generator/ — 生成渐进式 Ontology School 模块
  • .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 编译（构建时）

MIT

Trademarks This project may contai

Ontology Playground (Preview) ☕

Note: This project was developed with AI-assisted coding.

Try it live → microsoft.github.io/Ontology-Playground

A free, open-source web application for learning about ontologies and Microsoft Fabric IQ. Explore pre-built ontologies, design your own in a visual editor, export as RDF/XML, and share interactive diagrams — all from a fully static site with zero backend dependencies.

Interactive Graph Exploration

Cytoscape.js-powered graph that renders any ontology as an interactive node-and-edge diagram. Pan, zoom, click nodes to inspect properties, and use the live search bar to filter entities and relationships.

A curated library of official and community-contributed ontologies spanning six domains (Retail, E-Commerce, Healthcare, Finance, Manufacturing, Education). Browse by category, search by name or tags, load any ontology with one click, and view its RDF source. Every ontology has a shareable deep link (/#/catalogue/official/cosmic-coffee).

A full-screen, split-pane editor for creating ontologies from scratch or editing existing ones. Add entity types with icons, colors, and typed properties; define relationships with cardinalities; see a live graph preview that updates as you work. Includes undo/redo (50 levels), real-time validation, and export to RDF/XML or JSON.

Full round-trip support for RDF/XML (OWL classes, datatype properties, object properties with cardinalities). Import .rdf / .owl files, export in the exact format Microsoft Fabric IQ expects, and verify fidelity with automated round-trip tests.

Sign in with GitHub (device flow) and submit your ontology to the community catalogue directly from the designer — the app forks the repo, creates a branch, commits the RDF + metadata, and opens a pull request automatically.

A self-contained JavaScript file (ontology-embed.js) that renders an interactive ontology viewer on any web page with a single <script> tag. Supports dark/light themes, multiple loading methods (catalogue ID, URL, inline base64), and click-to-inspect. See the Embedding Guide for details.

A structured learning hub (/#/learn) with 9 courses spanning conceptual learning paths and hands-on labs:

• Ontology Fundamentals — 6 articles covering core concepts (What is an Ontology? → RDF/OWL → Fabric IQ → Build Your First → Design Patterns → Contributing)
• 7 Domain Learning Paths — Fourth Coffee, E-Commerce, Finance, Healthcare, Manufacturing, University, and HR System. Each path has 4 progressive articles that build an ontology step-by-step, with live embedded graphs showing new entities at each stage.
• IQ Lab: Retail Supply Chain — A 7-step hands-on lab that builds a 15-entity ontology from scratch (3 → 15 entities across 6 progressive catalogue entries).

Every article supports presentation mode (slides split at ## headings) and includes interactive quizzes with instant feedback. Ontology embeds load live graphs from the catalogue with optional diff highlighting.

Five progressive quests that guide users through ontology concepts with multi-step instructions, hints, progress bars, and achievement badges.

Natural Language Query Playground

Type natural language questions ("Which customers placed orders?") and see how they map to ontology entities and relationships — a preview of Fabric IQ's NL2Ontology capability.

Command Palette & Keyboard Shortcuts

Press ⌘K / Ctrl+K anywhere to open a searchable command palette. Jump to the Catalogue, Designer, Ontology School, Import/Export, Help, and more without leaving the keyboard. Press ? for quick help access. Arrow keys + Enter to navigate the palette.

The designer offers five domain templates (Retail, Healthcare, Finance, IoT, Education) so new users never face a blank page. Each template creates 3 entities with properties and 2 relationships, ready to customise.

Interactive Onboarding Tour

First-time visitors get a 5-step guided tour with a spotlight overlay that highlights the Header, Graph, Quests, Inspector, and Designer in sequence. Dismissable with a "don't show again" option persisted to localStorage.

Deep Linking & URL Routing

Client-side hash routing with shareable URLs for every page:

Route	Page
/#/	Home (default ontology)
/#/catalogue	Ontology gallery
/#/catalogue/<source>/<slug>	Specific ontology (e.g. /#/catalogue/official/cosmic-coffee)
/#/designer	Visual designer
/#/designer/<source>/<slug>	Designer with catalogue ontology (e.g. /#/designer/official/cosmic-coffee)
/#/learn	Ontology School — course catalogue
/#/learn/<course>	Course detail — article list
/#/learn/<course>/<article>	Article view (with presentation mode)
Domain	Ontology
---	---
Retail	Fourth Coffee
E-Commerce	Online Retail
Healthcare	Clinical System
Finance	Banking & Finance
Manufacturing	Industry 4.0
Education	University System

cd Ontology-Playground
npm install

Visit http://localhost:5173

The build pipeline compiles the catalogue, compiles learning content markdown, type-checks, bundles the app, and builds the embed widget. Output is in build/.

npm test            # single run
npm run test:watch  # watch mode

Azure Static Web Apps (primary)

The repo ships with a GitHub Actions workflow that deploys to Azure SWA on every push to main.

1. Create a Static Web App in the Azure Portal
2. Connect to your GitHub repository
3. Copy the deployment token and add it as the GitHub secret AZURE_STATIC_WEB_APPS_API_TOKEN_GREEN_PLANT_0BB1D2910
4. Push to main — the workflow at .github/workflows/azure-static-web-apps-green-plant-0bb1d2910.yml handles the rest
5. PR preview environments are created automatically for pull requests

A separate workflow deploys to GitHub Pages, ideal for forks:

1. Fork this repo
2. Go to Settings → Pages → Source and select GitHub Actions
3. Push to main — the workflow at .github/workflows/deploy-ghpages.yml builds and deploys to https://<username>.github.io/<repo-name>/

The VITE_BASE_PATH env var is set automatically to /<repo-name>/ during the GitHub Pages build so asset paths resolve correctly.

Variable	Default	Description
VITE_ENABLE_AI_BUILDER	false	Enable the Azure OpenAI ontology builder
VITE_ENABLE_LEGACY_FORMATS	false	Enable JSON/YAML/CSV import/export formats
VITE_BASE_PATH	/	Base path for the app (set automatically for GitHub Pages)
VITE_GITHUB_CLIENT_ID	(empty)	GitHub OAuth App client ID for one-click catalogue PRs (setup guide)
VITE_GITHUB_OAUTH_BASE	(empty)	External OAuth proxy URL for GitHub Pages deployments (e.g. Cloudflare Worker URL)

Ontology-Playground/
├── src/
│   ├── components/       # React components (graph, designer, modals, learn page)
│   ├── data/             # Ontology model, query engine, quest definitions
│   ├── lib/              # Router, RDF parser/serializer, catalogue helpers
│   ├── store/            # Zustand stores (app state, designer state)
│   ├── styles/           # CSS (Microsoft Fluent-inspired dark/light themes)
│   └── types/            # TypeScript type definitions
├── catalogue/            # Official + community ontology RDF files
├── content/learn/        # Course directories with markdown articles, quizzes, and metadata
├── scripts/              # Build-time compilers (catalogue, learning content)
├── api/                  # Azure Functions backend (optional, for AI builder)
├── docs/                 # Guides and documentation
├── public/               # Static assets (compiled catalogue.json, learn.json)
└── .github/workflows/    # CI/CD (Azure SWA + GitHub Pages)

The table below lists the main end-user and contributor guides. Internal planning notes (for example, docs/TODO-*.md) are intentionally not part of the published documentation set.

Guide	Description
Ontology Authoring Guide	How to create ontologies that work well in the Playground — field-by-field reference, best practices, and a step-by-step walkthrough
Contribute an Ontology: From Design to GitHub	End-to-end contributor workflow: design, RDF export, metadata, local validation, and pull request
Playground Feature Demo Guide	Step-by-step demo script to showcase key Playground capabilities and connect them to Fabric IQ and Real-Time Intelligence
Ontology School Demo Guide	Step-by-step live demo plan for courses, embeds, quizzes, presentation mode, and learning workflow
Embedding Guide	How to embed interactive ontology widgets on any web page
GitHub OAuth Setup	How to configure GitHub OAuth for one-click catalogue PRs
Embed Security	Security model for the embeddable widget
Learning Content Guide	How to author courses, articles, quizzes, and ontology embeds for the Ontology School
Ontology School Review Workflow	Human review and approval flow for school lesson content
Theme Authoring Guide	How to plug a new color theme into the Playground — token contract, the appStore + CSS steps, and contrast gotchas

This repository includes Copilot customization files so agents can reliably:

• import customer RDF/OWL into catalogue-ready format
• generate progressive Ontology School modules
• route lesson content through human review workflows

Included assets:

• Skills:
  • .github/skills/ontology-catalog-import/ — import external/customer RDF/OWL into catalogue format
  • .github/skills/ontology-school-path-generator/ — generate progressive Ontology School modules
  • .github/skills/community-ontology-contribution/ — add a contributor ontology under catalogue/community/ with the correct directory structure, metadata, and validation
  • .github/skills/name-generator/ — generate person names for examples, demos, quests, tests, and sample data from the approved CSV fixture
• RDF intake instruction:
  • .github/instructions/rdf-intake.instructions.md
• Reusable prompts:
  • .github/prompts/import-rdf-to-catalog.prompt.md
  • .github/prompts/generate-ontology-school-module.prompt.md

Recommended validation before merge:

npm run qa:tutorial-content
npm run build

• React 19 + TypeScript 5
• Cytoscape.js — Graph visualization (fcose layout)
• Zustand — State management
• Vite — Build tool
• Framer Motion — Animations
• Lucide Icons — Icon library
• marked — Markdown compilation (build-time)

MIT

Trademarks This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft’s Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party’s policies.