用途
该技能适用于任何即将写入或信任本体标识符的场合：注释元数据列、填写提交模板、审计他人产出的表格，或检查旧文件中的 ID 是否仍然有效。其核心规则是：绝不凭记忆写本体 ID，也绝不未经检查就接受一个 ID。本体 ID 形式易记但细节任意，一个看似合理的 UBERON:0002108 是真实术语（小肠）而非肝脏，下游不会发现这种替换——ID 格式正确、本体正确，元数据却静默错误。该技能发出的每个 ID 都来自实时 OLS 查询，收到的每个 ID 都会被验证。Bioregistry、Identifiers.org、ZOOMA 和 Ontobee 回答前缀、落地页和简写问题，但不能替代 OLS 检查。
主要能力
- 文本解析为术语：使用
scripts/resolve_terms.py，通过 OLS 将自由文本解析为术语。搜索按 exact（标签和同义词）→ token → fulltext 逐级升级，并在第一个返回结果的策略处停止，报告触发了哪个策略。--exact-only禁用该阶梯。--branch UBERON:0000465将候选限制为某术语的后代。使用结果前需阅读 match_type：exact_label 和 exact_synonym 安全；partial 表示 OLS 对不存在的字符串返回了最佳猜测，需要人工决定；unresolved 是合法输出。 - 校验现有 ID：使用
scripts/validate_terms.py，检查 ID 是否存在、当前、与断言一致。状态包括 ok（通过）、matched_synonym（警告）、imported_only（警告）、not_a_class（警告）、not_found（失败）、obsolete（失败）、label_mismatch（失败）、wrong_ontology（失败）、wrong_branch（失败）、malformed_curie（失败）。--strict将警告提升为失败。退出码：任何失败为 1，否则为 0，用法或网络问题为 2，因此可作为元数据文件的 CI 门禁。 - 检查前缀或紧凑标识符：使用
scripts/lookup_prefix.py，借助 Bioregistry 检查前缀是否真实、CURIE 是否匹配模式，并给出落地页 URL。Bioregistry 接受同义前缀，Identifiers.org 不接受——HPO:0001250 是 HTTP 400，需改写为首选前缀后再交给 OLS。落地页列来自 Bioregistry 映射（providers.miriam、mappings.ontobee），而非模板化首选前缀：ORPHA:558 是 400，orphanet:558 是 200，OBA 没有 Identifiers.org 命名空间。空单元格表示该服务不托管该前缀。此脚本不表示术语存在，那仍由 validate_terms.py 负责。 - 映射实验室简写（ZOOMA）：使用
scripts/map_terms.py，在 resolve_terms.py 返回 unresolved / partial 后使用。--ontology为必填。未过滤的 ZOOMA annotate 对 liver 会返回 FOODON、XAO、BTO 和 UBERON，均为 HIGH 置信度。HIGH/GOOD 命中仅为候选，写入前必须对每个 CURIE 运行 validate_terms.py。
使用方式
所有四个脚本接受单值或文件，输出 TSV 或 JSON，除标准库外无需任何包。示例：
cd 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 --exact-only
适用场景
- 元数据列注释、提交模板填写、表格审计、旧文件 ID 检查。
- 作为 CI 门禁校验元数据文件中的 ID 与标签一致性。
- 组织列必须仅含 UBERON 解剖实体时，通过
--branch和--expect-ontology约束。 - 选择本体：MONDO 用于疾病，HP 用于表型，UBERON 用于组织，CL 用于细胞类型，EFO 用于检测，ChEBI 用于化合物，NCBITaxon 用于生物体，PATO 用于性别和正常。前缀到 OLS id 的映射（HP 以 hp 提供，Orphanet 以 ordo 提供）、
--branch的分支根以及重叠本体的判断依据见 references/ontology-registry.md。
限制与注意事项
- OLS API 陷阱：
exact=true是精确 token 匹配，liver 在 UBERON 中返回 161 个命中，添加 queryFields=label 后返回 1 个；/search从不返回 is_obsolete 或 term_replaced_by，即使列入 fieldList 也会被静默丢弃，只有术语详情能回答“此 ID 是否仍然当前”；ontology=efo会返回 MONDO 和 CL 命中，本体相互导入，需自行按 CURIE 前缀过滤；同一术语在每个导入本体中各出现一次，需按 obo_id 去重并保留 is_defining_ontology: true；obo_id 索引有空洞，MONDO:0000001 是活的但未被 obo_id 索引，需要 IRI 回退以避免误报 not_found；IRI 并非都是 OBO PURL，EFO 和 Orphanet 使用自己的命名空间，应解析 IRI 而非模板化；OxO 已退役，返回 HTTP 200 的 HTML，应使用术语交叉引用或 SSSOM；分支检查不会将细胞类型排除在解剖之外，CARO 将细胞置于解剖结构下，需同时约束前缀；ZOOMA 无本体过滤时 liver 返回 100+ 个跨 FOODON、XAO、BTO、UBERON 的 HIGH 命中；Identifiers.org 同义前缀 HPO:0001250 是 HTTP 400，而 Bioregistry 接受同一 CURIE；Identifiers.org 编码冒号 HP%3A0001250 是 HTTP 400，路径必须保留:；Bioregistry 的 preferred_prefix 不是 Identifiers.org 命名空间，ORPHA:558 是 400，orphanet:558 是 200，hp:0001250 和 chebi:15377 是 400，因为这些命名空间将前缀嵌入 LUI，应使用 /api/reference/{CURIE} 的 providers.miriam，当该映射缺失时省略 URL（OBA、XAO、ECTO）；Ontobee 搜索仅有 HTML 页面，无 JSON API，不要抓取。 - 报告结果：给出 ID 和标签，并说明各自如何匹配。仅含裸 ID 的表格无法审查。明确说明未解析的术语，而不是用最近的命中填充。
- 代理操作流程：检查环境（确认网络访问、API 密钥、数据库当前 API 文档和速率限制）；确定输入（从数据或用户确认格式、标识符和参数，对任何改变结果的值应询问而非猜测）；先运行小版本（获取单个已知记录并检查响应格式后再批量查询）；执行完整任务；验证结果（标识符可解析、报告记录数、记录数据库版本或访问日期）；报告（说明运行了什么、检查了什么、仍不确定什么）。
- 异常处理：HTTP 429 或 5xx 错误时，遵守速率限制并退避、批量请求、如实报告部分结果；安装版本中缺少函数、标志或端点时，查阅已安装版本自己的文档（help()、--help、官方文档），适配并告知用户，绝不虚构 API；必需输入、标识符或参数不明确时，询问用户或在运行前明确说明假设。
- 完整性规则：绝不捏造结果、参数、标识符、引用或统计；无法运行或验证时明确说明；绝不虚构登录号、ID 或记录，应报告“未找到”；将此处版本特定细节视为可能过时，对照已安装版本的官方文档确认；在涉及花钱、消耗共享 GPU 或云配额、触及个人或患者数据或不可撤销的操作前先询问。
参考资料
- references/ols4-api.md — 端点、参数、响应字段以及每个已验证的 OLS 陷阱。
- references/companion-apis.md — Bioregistry、Identifiers.org、ZOOMA 和 Ontobee：各自何时使用，以及使未过滤或同义前缀调用看似成功的陷阱。
- references/ontology-registry.md — 前缀/本体 id 表、分支根、哪个本体拥有哪个概念。
- references/curation-rules.md — 候选选择流程、值得重试的规范化、审计现有表格、过时术语、跨本体映射。