ontology-stack-builder

用途

Ontology Stack Builder 用于从任意关系型 schema 和一组业务问题出发，生成完整的 Ontology-on-Snowflake 技术栈。它适合以下场景：你拥有 Snowflake 表并希望构建 ontology 驱动的分析层；你希望 Cortex Agent 能够跨语义模型智能路由问题；你需要统一各表实体类型的抽象 ontology 视图；你有一个 OWL ontology 文件需要映射到现有 Snowflake 表；你希望在数据上执行图分析（中心性、社区发现、最短路径）。

架构总览

该技能生成一个 5 层技术栈：

Layer 5：Cortex Agent（跨语义模型 + 图工具的意图路由）
Layer 4：语义模型（KG 具体、Ontology 抽象、Metadata 治理）
Layer 3：生成的抽象视图（通过存储过程生成 VW_ONT_*）
Layer 2：Ontology 元数据（约 22 张 ONT_* 表：类、属性、规则、角色等）
Layer 1：物理存储（现有表，或 KG 路径下的 KG_NODE/KG_EDGE）+ 具体视图（V_{CLASS} 实体视图、V_{REL} 关系视图）

主要能力与工作流

该技能遵循 7 阶段门控工作流，每阶段需要用户确认后才能继续：

阶段 1：收集输入。收集 schema、业务问题、可选 OWL 文件；询问走 KG 路径还是直接表路径；发现现有语义视图（Step 1b）；询问是以现有语义为基还是从零创建。
阶段 2：分析并推荐 ontology。内省 schema 或解析 OWL；若存在现有语义，用其策展元数据丰富提案；提出类、关系、映射。
阶段 3：可视化、修改与确认。展示 ontology 图（Streamlit agraph）和覆盖矩阵；侧边栏编辑器可增删类与关系；点击节点可内联编辑表单（label、parent、abstract）；可视化 diff 标记变更；可将改动保存回 JSON 或全部撤销。
阶段 4：生成并部署 ontology 层（Layer 1-3）。生成物理表 SQL（若走 KG 路径）、具体实体/关系视图 SQL、元数据表 SQL（约 22 张表 + 种子数据）、抽象视图 SQL；自校验完整性；审核通过后执行 SQL，表和视图即存在于 Snowflake 中。
阶段 4.5：确保基础语义视图，通过 semantic-view 技能。若阶段 1 选择了现有语义则跳过；否则在源表上调用 semantic-view 技能，并以审计模式测试基础语义。
阶段 5：创建 ontology 语义视图（Layer 4），通过 semantic-view 技能。询问用户要创建哪些 ontology 层模型（KG 语义[若走 KG 路径]、Ontology 语义、Metadata 语义）；调用 semantic-view 技能（FastGen 针对已部署视图）；以审计模式测试每个语义视图。
阶段 6：创建 Cortex Agent（Layer 5），通过 cortex-agent 技能。以所有语义视图工具调用 cortex-agent 技能；若走 KG 且用户需要，添加图工具脚手架；以测试/调试模式测试 agent。
阶段 7：端到端验证。验证 L1-L5 行数和样本查询；运行 agent 端到端测试。

使用方式

该技能通过命令行脚本运行。示例：

uv run --project <SKILL_DIR> python <SKILL_DIR>/scripts/parse_owl.py \
  --owl-file "<owl_path>" \
  --output-dir "/tmp/ontology_parsed"

uv run --project <SKILL_DIR> python <SKILL_DIR>/scripts/introspect_schema.py \
  --database "<DATABASE>" \
  --schema "<SCHEMA>" \
  --tables "<TABLE1>,<TABLE2>,..." \
  --questions "<Q1>|<Q2>|..." \
  --output-dir "/tmp/ontology_parsed"

uv run --project <SKILL_DIR> python <SKILL_DIR>/scripts/visualize_ontology.py -- \
  --classes-json "/tmp/ontology_parsed/classes.json" \
  --relations-json "/tmp/ontology_parsed/relations.json" \
  --port 8501

发现现有语义视图：

SHOW SEMANTIC VIEWS IN SCHEMA {DATABASE}.{SCHEMA};

cortex semantic-views discover
cortex semantic-views describe {DATABASE}.{SCHEMA}.{SEMANTIC_VIEW_NAME}

强制停止点

这些门控覆盖所有其他指令。没有用户明确批准，绝不跳过任何门控。每个阶段输出后必须停止，并使用 ask_user_question 获得用户明确确认后再进入下一阶段。如果用户要求“一次性全部生成”，应确认请求但解释分阶段方式，只产出当前阶段。在委托技能（semantic-view、cortex-agent）完成后，必须停止并通过 ask_user_question 呈现当前阶段的门控问题，再进行下一阶段的任何工作。

输入与数据结构

阶段 1 需要收集：Snowflake 位置（DATABASE.SCHEMA）；源表列表或 OWL 文件；3-10 个业务问题；Ontology 名称（如 HEALTHCARE、FINANCE、RETAIL）；KG 路径或直接表路径选择。

classes.json 中每个条目必须使用以下确切键：name、label、description、parent_name、is_abstract、is_deprecated、namespace、uri、_source_table、_id_column、_name_column。

relations.json 中每个条目必须使用以下确切键：name、label、description、domain_class、domain_classes、range_class、range_classes、is_transitive、is_symmetric、is_functional、is_abstract、is_hierarchical、parent_name、inverse_name、cardinality、uri、_source_table、_src_column、_dst_column。对于抽象关系，设置 is_abstract: true 并将 _source_table/_src_column/_dst_column 设为 null。具体子关系通过 parent_name 引用其抽象父关系。

可视化与编辑

可视化应用展示：层次结构标签页（类层次与关系层次，可切换交互/文本、搜索、深度滑块）；ontology 图（覆盖着色与 Layer 切换：All / Concrete / Abstract）；覆盖标签页展示 ontology 设计结构。Layer 切换控制可见性：All 显示抽象和具体项；Concrete 隐藏抽象类与抽象关系；Abstract 只显示抽象类和抽象关系。侧边栏 Ontology Editor 允许在生成前修改 ontology：添加类（name、label、description、parent 下拉、abstract 开关）、添加关系（name、源/目标类下拉、cardinality、description）、删除类（子类重挂到根，移除相关关系）、删除关系、保存改动（写回 JSON）、全部撤销。点击节点会出现 Edit Class 表单。视觉 diff 标记：金色粗边=新增，橙色粗边=修改。边样式区分关系类型：实蓝=subClassOf，虚线紫=具体关系，实深紫粗线=抽象关系，点线浅紫=specializes。

限制

资料未提供该技能的收费、价格、平台支持范围（除 Snowflake 相关外）或性能指标。使用需要 Snowflake 环境以及相应脚本运行环境（uv 项目）。若 Streamlit 不可用或用户偏好文本，会渲染 ASCII 树替代。