用途
本体术语解析技能用于在任何本体标识符即将被写入或被信任时进行解析与校验，典型场景包括：为元数据列添加注释、填写提交模板、审计他人产出的表格，或检查旧文件中的 ID 是否仍然有效。其核心规则是：绝不凭记忆写本体 ID，也绝不未经校验就接受一个 ID。本体 ID 在形式上易于记忆，但细节是任意的——一个看似合理的 UBERON:0002108 是真实术语（小肠），却不是肝脏，而下游没有任何环节能发现这种替换：ID 格式正确、本体正确，元数据却悄然出错，审稿人也难以察觉，因此这类错误会一直留存到已发表的数据集中。
主要能力
技能提供四个脚本，均接受单值或文件输入，输出 TSV 或 JSON，除标准库外无需任何依赖包：
- resolve_terms.py：通过 OLS 将自由文本解析为术语。搜索按 exact（标签与同义词）→ token → fulltext 逐级升级，并在第一个返回候选的策略处停止，同时报告触发的是哪一级。
--exact-only禁用该阶梯并本地拒绝 partial、related、broad、narrow 及未限定作用域的同义词匹配。搜索返回的是有界候选列表（--top），而非穷尽的歧义检查。--branch UBERON:0000465使用 OLS 层级祖先关系，包括 part-of/develops-from。 - validate_terms.py：校验已有 ID。状态包括 ok（通过）、matched_synonym、imported_only、not_a_class（警告）、not_found、obsolete、label_mismatch、wrong_ontology、wrong_branch、malformed_curie（失败）。退出码为：有失败为 1，否则为 0，用法或网络问题为 2，因此可作为元数据文件的 CI 门禁。
--strict将警告提升为失败；--expect-ontology检查标识符命名空间；--branch-relation is-a仅做子类校验。 - lookup_prefix.py：借助 Bioregistry 与 Identifiers.org 检查前缀或紧凑标识符，返回 preferred_prefix、canonical_curie、pattern 等。Bioregistry 接受同义前缀，Identifiers.org 不接受。落地页列来自 Bioregistry 映射，而非对首选前缀做模板化。该脚本不判断术语是否存在，这仍由 validate_terms.py 负责。
- map_terms.py：通过 ZOOMA 映射实验室简写（如 PBMC、WT），在 resolve_terms.py 返回 unresolved/partial 后使用。
--ontology为该客户端必填；HIGH/GOOD 是排序分桶，不是校准概率或精确匹配。
使用方式
在 skills/ontology-term-resolution/scripts 目录下运行。示例：
python3 resolve_terms.py "liver" --ontology uberon
python3 resolve_terms.py --input tissues.txt --ontology uberon --exact-only --format tsv -o resolved.tsv
python3 resolve_terms.py "left ventrical of heart" --ontology uberon --top 3
python3 validate_terms.py UBERON:0002107 EFO:0001067 UBERON:9999999
python3 validate_terms.py --input metadata.tsv --strict
python3 validate_terms.py --input tissue_ids.tsv --branch UBERON:0000465 --expect-ontology uberon
python3 lookup_prefix.py HP HPO HP:0001250 HPO:0001250
python3 map_terms.py PBMC --ontology cl --high-confidence-only
使用结果前需阅读 match_type：exact_label 与 exact_synonym 建立的是词法一致（后者还要求精确同义词注释），而非正确的样本上下文；related_synonym、broad_synonym、narrow_synonym、unspecified_synonym 与 partial 需要人工审校。每个选中的 ID 都必须校验；搜索不会在其记录中暴露过时信息。unresolved 是合法输出。
适用场景
- 为元数据列或提交模板解析组织、疾病、表型、细胞类型等术语。
- 审计他人产出的表格，检查 ID 是否真实、当前、标签一致。
- 在 CI 中作为元数据文件的门禁。
- 查询前缀、紧凑标识符、落地页与实验室简写。
本体选择建议：疾病用 MONDO，表型用 HP，组织用 UBERON，细胞类型用 CL，检测用 EFO，化合物用 ChEBI，生物体用 NCBITaxon。PATO 的性别/正常术语仅在目标模式允许且源数据确立相关状态时适用；缺失疾病或对照组标签并不能确立健康状态。
限制
- 搜索是有界候选列表，不是穷尽的歧义检查。
- OLS 的
/search从不返回 is_obsolete 或 term_replaced_by，只有术语详情能回答“该 ID 是否仍然当前”。 ontology=efo会返回 MONDO 和 CL 命中，需自行按 CURIE 前缀过滤；同一术语会按导入本体重复出现，需按 obo_id 去重并保留 is_defining_ontology: true。- OLS 本体 id 与 Bioregistry 首选前缀不可互换（ORPHA/Orphanet 使用 OLS 的 ordo）。
- not_found 表示在该 OLS 查询中不存在，并非证明全局不存在。
- 实时 OLS 校验不能替代对归档所固定本体版本的校验；提交时应使用该版本及其校验器。
- Ontobee 仅有 HTML 页面，无 JSON API，不应抓取。
- 报告结果时应给出 ID 与标签，并说明各自如何匹配；裸 ID 表格无法审阅。应明确说明未解析的术语，而不是用最接近的命中填充。记录查询日期、本体标识符及本体版本 IRI 或发布元数据（如可用），连同原始输入与所选术语 IRI。
参考资料
- references/ols4-api.md — 端点、参数、响应字段及所有已验证的 OLS 陷阱。
- references/companion-apis.md — Bioregistry、Identifiers.org、ZOOMA 与 Ontobee 的使用时机及陷阱。
- references/ontology-registry.md — 前缀/本体 id 表、分支根、概念归属。
- references/curation-rules.md — 候选选择流程、可重试的规范化、审计现有表格、过时术语、跨本体映射。