ontology-explorer

本体浏览器

目标

帮助 Agent 理解、浏览和查询材料科学本体的结构，而无需直接加载冗长的 OWL/XML 文件。通过预处理的 JSON 摘要，快速访问类层次结构、属性定义以及定义域-值域关系。

要求

• Python 3.10+
• 无外部依赖（仅使用 Python 标准库）
• 仅在通过 owl_parser.py 和 ontology_summarizer.py 获取远程 OWL 文件时需要互联网连接

需要收集的输入

输入	描述	示例
本体名称	要查询的已注册本体	cmso
类名称	要检查的特定类	Material、UnitCell
属性名称	要查询的特定属性	hasMaterial、hasSpaceGroupNumber
搜索词	用于搜索标签的关键词	crystal、lattice
OWL 源	OWL/XML 文件的路径或 URL（用于解析/生成摘要）	https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl

决策指南

What do you need?
├── Understand overall ontology structure
│   └── class_browser.py --ontology cmso --list-roots
├── Inspect a specific class
│   └── class_browser.py --ontology cmso --class <name>
├── Find properties for a class
│   └── property_lookup.py --ontology cmso --class <name>
├── Look up a specific property
│   └── property_lookup.py --ontology cmso --property <name>
├── Search for a concept
│   ├── class_browser.py --ontology cmso --search <term>
│   └── property_lookup.py --ontology cmso --search <term>
├── Parse a new/updated OWL file
│   └── owl_parser.py --source <path-or-url>
└── Generate/refresh a summary JSON
    └── ontology_summarizer.py --source <url> --output <path>

脚本输出（JSON 字段）

脚本	主要输出
scripts/owl_parser.py	results.metadata、results.classes、results.object_properties、results.data_properties、results.class_hierarchy
scripts/ontology_summarizer.py	results.output_file、results.statistics
scripts/class_browser.py	results.class_info、results.subtree、results.properties、results.path_to_root、results.roots、results.search_results
scripts/property_lookup.py	results.property_info、results.class_properties、results.search_results

工作流

1. 确定用户使用的本体（默认：CMSO）。
2. 使用 class_browser.py --list-roots 查看顶层概念。
3. 使用 class_browser.py --class <name> 深入查看特定类，了解其层次结构、子类和适用属性。
4. 使用 property_lookup.py --property <name> 查询单个属性。
5. 如果用户提到了某个概念，但未提供本体名称，则使用 --search 查找匹配的类或属性。
6. 对于新的或更新的本体，运行 owl_parser.py 解析原始 OWL，然后运行 ontology_summarizer.py 生成摘要 JSON。

对话工作流示例

User: I have an FCC copper simulation. What CMSO classes should I use to describe it?

Agent: Let me explore the CMSO ontology to find the relevant classes. I'll run
a few targeted searches and property lookups (the answer below is synthesized
from several commands, per the Workflow section).

[Runs: class_browser.py --ontology cmso --search "crystal" --json]
  → Crystalline Material, Crystal Structure (among others)
[Runs: class_browser.py --ontology cmso --search "sample" --json]
  → Computational Sample, Atomic Scale Sample
[Runs: class_browser.py --ontology cmso --search "unit cell" --json]
  → Unit Cell
[Runs: class_browser.py --ontology cmso --search "space group" --json]
  → Space Group
[Runs: class_browser.py --ontology cmso --search "element" --json]
  → Chemical Element
[Runs: property_lookup.py --ontology cmso --property "has material" --json]
  → domain Computational Sample → range Material
[Runs: property_lookup.py --ontology cmso --property "has structure" --json]
  → domain Material → range Structure
[Runs: property_lookup.py --ontology cmso --property "has unit cell" --json]
  → domain Crystal Structure → range Unit Cell

For an FCC copper simulation, the relevant CMSO classes are:

- **Computational Sample** → **Atomic Scale Sample**: your simulation is an atomic-scale sample
- **Material** → **Crystalline Material**: copper is crystalline
- **Crystal Structure**: describes the FCC arrangement
- **Unit Cell**: the repeating FCC unit cell (a=b=c=3.615 Å, α=β=γ=90°)
- **Space Group**: FCC copper is space group 225 (Fm-3m)
- **Chemical Element**: Cu

The key relationship chain (from the property domains/ranges above):
  Computational Sample → has material → Material → has structure → Structure
  → (Crystal Structure) → has unit cell → Unit Cell

Shall I look up the specific properties for any of these classes?

CLI 示例

# List root classes in CMSO
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --list-roots --json

# Inspect the Material class hierarchy
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --class Material --json

# Search for crystal-related classes
python3 skills/ontology/ontology-explorer/scripts/class_browser.py \
  --ontology cmso --search crystal --json

# Find all properties for UnitCell
python3 skills/ontology/ontology-explorer/scripts/property_lookup.py \
  --ontology cmso --class UnitCell --json

# Look up a specific property
python3 skills/ontology/ontology-explorer/scripts/property_lookup.py \
  --ontology cmso --property "has space group" --json

# Parse a remote OWL file
python3 skills/ontology/ontology-explorer/scripts/owl_parser.py \
  --source https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl --json

# Generate a summary JSON from an OWL file
python3 skills/ontology/ontology-explorer/scripts/ontology_summarizer.py \
  --source https://raw.githubusercontent.com/OCDO/cmso/main/cmso.owl \
  --output summary.json --json

错误处理

错误	原因	解决方案
Ontology 'X' not in registry	本体名称未注册	检查 references/ontology_registry.json 中的可用名称
Class 'X' not found	类标签与任何条目都不匹配	使用 --search 查找相似名称，或使用 --list-roots 查看可用类
Property 'X' not found	属性标签不匹配	使用 --search 查找相似属性
Cannot parse OWL source	XML 无效或 URL 无法访问	检查文件路径或 URL；确保文件是有效的 OWL/XML
Summary file not found	尚未生成摘要 JSON	先运行 ontology_summarizer.py

解读指南

• 类层次结构：根类代表最宽泛的概念；叶类代表最具体的概念。一个类会继承其所有祖先类的属性。
• 对象属性：展示类之间的关系（定义域 → 值域）。定义域为 UnitCell、值域为 Basis 的属性表示晶胞具有基底。
• 数据属性：展示类所携带的字面值。定义域为 ChemicalElement、值域为 xsd:string 的属性表示元素具有字符串类型的属性值。
• 并集定义域：一个属性可以适用于多个类。如果是这样，定义域会显示为用竖线连接的类，例如 A | B。（当前捆绑的 CMSO/ASMO 摘要中不包含并集定义域属性。）
• 搜索相关性：1.0 = 标签匹配；0.5 = 仅描述匹配。

验证清单

在将任何类、属性或关系作为事实呈现之前，请先确认并记录：

• 使用 class_browser.py --class <name>（或 property_lookup.py）解析目标，并记录 results.class_info.label / results.property_info.name 返回的确切规范 label——不要引用 Agent 输入的名称；应引用工具解析出的标签（例如，UnitCell → Unit Cell）。
• 对于陈述的每条关系链，都引用 property_lookup.py --property <name> 调用返回的实际 domain 和 range（记录 results.property_info.domain 和 .range），而不是根据类名推断关系。
• 当属性的 domain 包含竖线（A | B）时，将其报告为并集（适用于列出的每个类），并确认相关类与其中一个规范化成员匹配——不要默默假定其领域只有一个类。
• 对于 --search 结果，记录每个匹配项的 relevance，并说明它是标签匹配（1.0）还是仅描述匹配（0.5）；不要将 0.5 的描述命中说成已确认的术语匹配。
• 使用注册表键（cmso 或 asmo）识别本体，并确认它存在于 references/ontology_registry.json 中；不要查询未注册的本体，也不要混淆 CMSO 和 ASMO 的术语。
• 依赖生成或刷新的摘要时，记录其 metadata.source_url、metadata.generated_at 以及 statistics（num_classes、num_object_properties、num_data_properties），以便追溯结果对应的具体 OWL 源。
• 将缺失的父类、描述或 domain/range 视为缺失数据（而非“没有这种关系”），因为解析器只提取简单的 rdfs:subClassOf 和已声明的 domain/range，不执行推理。

常见陷阱与错误说辞

容易采用的捷径	错在哪里／应该怎么做
“类名 UnitCell 没有返回结果，所以这个术语不存在。”	标签中可能带有空格（Unit Cell）。工具按精确匹配 → 不区分大小写匹配 → 空格规范化匹配的顺序解析；直接猜测失败时，请运行 --search，并使用工具返回的规范 label，而不是输入的字符串。
“这两个类显然有关联，所以我就写出这条关系。”	只有对象属性声明了关系，关系才存在。请使用 property_lookup.py --property <name> 验证，并引用记录的 domain → range；切勿仅根据类名推断三元组。
“脚本运行了，也打印了结果，所以答案完整了。”	运行成功 ≠ 信息完整。缺少 parent、description 或 domain/range，表示 OWL 中缺少相应注释——解析器不会推断，也会忽略复杂的 OWL 限制。请明确说明缺少了什么。
“--search crystal 匹配到了，所以这就是正确的术语。”	匹配项的相关度可能是 0.5（仅匹配描述），而非标签匹配。请检查 relevance 字段，优先采用相关度为 1.0 的标签匹配；对于 0.5 的命中，应报告为“描述中提及”，而不是规范术语。
“一个属性只有一个领域类。”	领域可以是并集（`A
“任意 OCDO 本体都能用／CMSO 和 ASMO 可以互换。”	目前仅注册了 cmso 和 asmo；CDCO/PODO/PLDO/LDO 尚在规划中，暂不可用。请选择正确的注册表键，不要混用不同本体的术语。
“我会让解析器读取这个 http:// OWL URL。”	owl_parser.py/ontology_summarizer.py 按设计会拒绝非 https:// URL。请使用 https:// 源或本地文件路径。

安全

输入验证

• --ontology 会根据 ontology_registry.json 中注册的本体名称进行验证（固定允许列表）
• --class 和 --property 名称会根据安全字符模式进行验证，以防止注入
• --search 词条的长度受到限制，且仅用于与预处理后的标签进行子字符串匹配（绝不会插入查询或代码中）
• owl_parser.py 的 --source 接受文件路径或 URL；URL 仅会验证是否使用 https:// 协议

文件访问

• class_browser.py 和 property_lookup.py 会从 references/ 目录读取预处理后的 JSON 摘要文件（只读）
• owl_parser.py 会从本地路径或 HTTPS URL 读取单个 OWL/XML 文件；远程获取的超时时间为 30 秒
• ontology_summarizer.py 会将单个 JSON 摘要文件写入 --output 指定的路径
• 没有脚本会修改或删除现有文件

工具限制

• Read：用于检查脚本源代码、参考文件和本体摘要
• Bash：用于执行四个 Python 脚本（owl_parser.py、ontology_summarizer.py、class_browser.py、property_lookup.py），并显式传入参数列表；URL 获取在 Python 脚本内执行，并设有超时限制

安全措施

• 不使用 eval()、exec() 或动态代码生成
• 所有子进程调用均使用显式参数列表（不使用 shell=True）
• OWL/XML 解析使用 Python 的 xml.etree.ElementTree，该模块默认不会解析外部实体，从而降低 XXE 攻击风险
• 远程 URL 获取仅允许使用 HTTPS，且超时时间为 30 秒，以防止滥用
• 搜索结果数量设有上限，以防止输出过多

限制

• 仅支持 OWL/XML 格式（不支持 Turtle、JSON-LD 或 N-Triples）
• 不支持 OWL 推理或推断（例如，不会计算传递闭包）
• 类层次结构提取仅处理简单的 rdfs:subClassOf（不处理复杂的 OWL 限制）
• 对于缺少 rdfs:comment、skos:definition 或 IAO 注释的类，可能没有描述
• URL 获取需要互联网连接，且可能超时（上限为 30 秒）

参考资料

• OWL/RDF 入门指南 — OWL 概念简介
• CMSO 指南 — CMSO 本体的说明性指南
• 本体注册表 — 已注册本体及其元数据
• CMSO 摘要 — 预处理后的 CMSO 结构
• CMSO 文档 — CMSO 官方文档
• CMSO 仓库 — OWL 源文件和开发内容

版本历史

日期	版本	变更
2026-06-24	1.2.2	添加了验证清单（基于证据，涵盖规范标签解析、已记录的 domain/range、联合域、搜索相关性、注册表键和摘要溯源），以及常见陷阱与合理化说辞表。
2026-06-23	1.2.0	修复了 property_lookup 中的 --class，使其能够解析规范标签（现在无空格的名称如 UnitCell 也能匹配）；统一了各工具中的类/属性域匹配；落实了文档中说明的安全控制（安全字符模式、长度上限、搜索结果上限、仅 HTTPS URL）；修正了联合域文档示例和 eval 断言；将描述范围限定为 CMSO/ASMO。
2026-02-25	1.0	首次发布，支持 CMSO