本章说明 OAN 如何治理能力标签、别名、授权域和语义配置，并将资源名称、描述、用例、协议绑定等语义信息用于注册建议、结构化过滤、文本召回、语义排序和结果解释。章节同时划清语义相关性与身份、控制权、发布证明、生命周期和治理状态之间的边界，确保语义发现提升资源匹配能力，而不改变可信发布和授权判断。

12.1 语义模型与能力词汇

在 OpenAgenet (OAN) 中，语义模型把资源的“能做什么”拆成几类可以被注册和发现复用的信息：资源名称和描述提供自然语言上下文，能力标签提供相对稳定的分类键，用例说明适用任务，协议绑定说明交互方式，资源类型说明对象类别。它们共同参与推荐和检索，但承担的事实范围不同。能力标签树回答“这个词属于哪一类能力”，资源包回答“某个具体资源声明了哪些能力”，DID文档和凭证材料回答“该资源由谁控制、是否完成登记以及发布事实是否可验证”。

因此，语义匹配的结果应被理解为候选发现线索，而不是可信结论。注册服务节点可以依据名称、描述、用例和协议生成标签建议，提供方确认后再写入资源元数据；发现服务节点可以复用这些字段进行过滤、词法检索或语义排序。无论推荐分数多高，都不能替代控制权验证、注册凭证、根平台可信发布证明、生命周期状态和授权域检查。

12.2 根平台管理的能力标签树

能力标签树由根平台发布其版本和快照，供注册推荐器和发现服务节点作为共同语义材料使用。当前公共实现中的标签树对象包含 version、可选的 snapshotHash 和 tags；标签节点至少包含稳定的 id、展示用 label，并可包含 aliases 和递归的 children。下面是根据该数据结构整理的最小示例，值均为说明性占位值：

{
  "version": 1,
  "snapshotHash": "sha256:example",
  "tags": [
    {
      "id": "code.repository.search",
      "label": "代码仓库检索",
      "aliases": ["检索代码库"],
      "children": []
    }
  ]
}

标签树的节点结构用于组织语义和复现查询，不等于资源授权清单。根平台新增或调整标签后，注册推荐可以使用新版本，发现服务节点也可以据此重建索引；已经提交的资源原始描述和原始标签不能因为标签树变化而被静默改写。若节点使用旧快照，应记录所用版本，以便解释推荐或发现结果的差异。

12.2.1 标签树的组织方式

能力标签树采用“稳定标识 + 父子关系 + 展示名称 + 词汇版本”的组织方式。树节点表达能力分类，不直接表达资源是否已经注册、发布或可信。资源可以关联多个叶节点，也可以只关联较高层级节点，但注册服务节点应保存资源实际选择的标签，而不是仅保存推荐路径。

{
  "id": "code.repository.search",
  "parent": "developer.tools",
  "labels": {"zh-CN": "代码仓库检索", "en-US": "Code Repository Search"},
  "vocabularyVersion": "v1"
}

12.2.2 标签标识与层级关系

标签 ID 是跨节点关联键，父子关系用于组织检索范围，不能在没有词汇规则的情况下自动推导能力继承。查询结果应同时保留命中的标签 ID、匹配路径和词汇版本，避免只返回本地化名称导致跨节点无法复现。

12.2.3 标签推荐与发现使用

注册阶段的推荐结果由资源提供方确认后进入资源元数据；发现阶段可以使用同一标签 ID、别名和层级路径进行筛选或排序。推荐命中、标签命中和资源可信验证应在响应中分开表达。

资源描述 -> 推荐候选 -> 提供方确认 -> 写入资源包
                                     -> 发现索引
查询文本 -> 意图与别名解析 -> 标签条件 -> 候选排序

12.2.4 标签树版本管理

标签树发布时应有可比较的版本标识和生效时间。旧版本标签可以在迁移期保留解析映射，但不得静默改写资源原始声明；索引重建完成前，查询结果应标注所使用的词汇版本。

12.3 标签层级、标识符、别名与本地化

标签对象至少应能区分规范标识、显示名称、别名、语言和版本：

未知标签可以作为未治理的提供方文本保存，但不得被伪装成根平台正式标签。

标签 ID、显示名称、别名和层级路径的职责应保持分离。查询输入可以先通过本地化名称或别名找到规范 ID，再使用规范 ID进行结构化过滤；返回结果则应同时保留实际资源声明和命中的规范标签。这样既能支持中文、英文和同义词查询，也不会把展示层的翻译误当成新的能力声明。

12.4 注册过程中的标签选择与推荐

12.4.1 资源提供方选择

资源提供方可以接受、取消或修改推荐标签。最终提交内容应同时保留提供方原始描述和规范标签选择，便于后续解释“资源声明了什么”与“系统推荐了什么”。

12.4.2 根平台推荐

根平台或其治理材料提供标签树、别名和版本；推荐器根据资源类型、名称、描述、用例和协议生成候选。推荐器不负责签发资源控制证明，也不替代注册校验。

12.4.3 自定义标签补充

自定义标签用于表达正式词汇尚未覆盖的业务术语。自定义标签必须带来源或命名空间，并与正式标签分开存储；它可以参与文本检索，但不能直接改变资源类型、授权域或发布状态。

12.4.4 标签校验与保存

保存前至少校验标签 ID、词汇版本、父节点关系、语言、重复项和资源类型适配性。校验结果应与资源 DID、资源版本和资源包摘要关联，推荐失败或标签过期不得导致静默改写。

12.5 自定义标签与提供方描述

自定义标签适合表达具体业务术语、组织内部叫法或暂未进入公共词汇的能力。它应与根平台正式标签分开保存，并带有提供方命名空间或来源信息；名称、描述、用例等自由文本也应保留原文和语言标记。正式标签 ID 需要来自当前可用的标签树，自定义词汇不能借助格式相似或语义相近自动升级为正式标签。

发现服务节点可以把自定义标签和提供方描述用于词法或语义召回，但结果解释必须区分“提供方声明”“正式标签命中”和“检索模型推断”。重复标签、超长文本、无效字符、与资源类型明显冲突的标签以及试图操纵排序的关键词，应按节点的输入校验和索引策略拒绝、截断或降级为普通文本；处理结果应保留可追溯的原因，不得覆盖原始提交内容。

12.6 语义治理变更流程

语义治理变更应以新版本材料表达，而不是直接改写旧标签或历史资源。一个变更记录至少需要能够说明变更类型、影响的标签 ID、旧版本与新版本、别名或层级映射、生效时间以及对注册推荐和发现索引的影响。新增和改名通常可以通过新增映射兼容；合并和拆分需要明确旧标签如何查询；废弃标签则应停止新推荐，同时保留历史资源的原始值和可解析关系。

变更发布后，注册推荐器可以加载新词汇，发现服务节点可以按资源 DID 和资源版本逐步重建相关索引。重建未完成时，查询结果应能说明使用的词汇或索引版本；如果旧标签无法映射，节点可以保留其原文用于文本检索，但不得把它伪装为新标签的确定命中。标签治理只改变语义解释和检索材料，不改变资源 DID、控制关系、注册凭证或根平台发布事实。

12.7 发现节点的语义索引构建

12.7.1 索引输入

发现服务节点的索引输入分为三类：

1. 资源事实：资源 DID、版本、资源类型、公开 DID文档和资源包元数据。
2. 语义材料：规范标签、别名、名称、描述、用例、协议和语言。
3. 治理材料：生命周期、根平台可信发布证明引用、授权域、标签树版本和来源节点。

私钥、未发布草稿和内部配置不得进入索引。

12.7.2 标签索引

标签索引至少支持按规范标签 ID、层级路径、语言和词汇版本过滤，并保留标签来源。索引命中只能说明资源声明或索引记录匹配，仍需检查资源是否处于可发现状态。

12.7.3 文本和语义索引

文本索引可以覆盖名称、描述和用例；语义索引可以使用推荐器或可选向量实现。两者都应返回命中字段、索引版本和匹配依据，不能补写资源没有声明的能力。

12.7.4 索引更新与删除

资源版本、生命周期、发布证明或标签树版本变化时，应按资源 DID 和版本执行增量更新。撤销、暂停或删除事件到达后，索引可以保留审计记录，但不得继续作为正常可发现候选返回。

12.8 标签、文本、协议与资源类型匹配

四类条件在查询中的作用不同：资源类型和明确指定的版本通常用于限制候选类别，能力标签和协议可以作为显式过滤条件，名称、描述和用例中的文本主要用于相关性排序。多个显式条件一般按交集处理；标签查询要求候选满足请求的标签集合，协议可以从协议绑定或服务声明中匹配。语义相似只能改善排序，不能让不满足硬条件的候选重新进入结果。

候选资格 = 可见性与生命周期 + 显式结构化条件
相关排序 = 标签/协议命中 + 文本相关性 + 语义相似度
可信判断 = DID文档 + 凭证/发布证明 + 调用方策略

其中，前两行属于发现检索范围，最后一行属于独立的身份、发布和调用前验证。语义服务不可用时，发现节点可以退回词法或结构化路径，但不得因此放宽授权域、生命周期和显式条件。

12.9 查询解释与匹配说明

12.9.1 查询意图解析

查询解析应输出可审计的中间条件，例如资源类型、能力标签、协议、语言和状态过滤。无法确定的词语可以作为文本条件保留，不得被强行转换成正式标签。

{
  "query": "我需要一个可以检索代码仓库并总结项目结构的工具",
  "parsed": {
    "resourceType": "tool",
    "capabilities": ["code.repository.search", "code.structure.summarization"]
  }
}

12.9.2 标签和文本匹配

标签命中、别名命中、原文命中和语义推断命中应分类返回。硬过滤条件不满足时，相关性得分不得使候选重新进入结果集。

12.9.3 结构化条件匹配

资源类型、协议、授权域、生命周期和发布状态属于结构化条件。结构化条件的结果应明确为满足、不满足或未知，未知不能按满足处理。

12.9.4 结果解释

当前发现服务节点的查询解释接口接收与普通发现查询相同的 ResourceDiscoveryQuery，但返回的是动态 JSON，而非 ResourceDiscoveryResponse。解释结果可包含 items、candidateCount、matched、各类匹配分数、标签重合、结构化条件命中和语义搜索状态；这些字段是检索过程的可观察结果，不是新的资源证明。客户端应把解释用于回答“为什么返回”，仍以候选资源的 DID文档、资源包、根平台可信发布证明和治理状态回答“是否可以信任或调用”。

结果解释至少应包含资源 DID、命中的字段或标签、词汇/索引版本和可信状态来源。可用以下方式区分两类信息：

“相关”说明查询与资源描述存在匹配；“可信”还需要 DID、控制证明、发布证明、授权状态和生命周期等独立验证。

查询解释应保留从自然语言到结构化条件的可观察链路。例如，用户输入“我需要一个可以检索代码仓库并总结项目结构的工具”时，系统可以识别“工具”作为资源类型候选，把“检索代码仓库”和“总结项目结构”作为能力或文本检索线索；如果当前词汇没有可靠的正式标签映射，就应保留原句和普通文本命中，而不是凭模型推断创建新标签。解释内容可以展示命中的标签、字段、别名和索引版本，但不应暴露不必要的模型内部细节。

12.10 多语言语义发现

12.10.1 中英文资源描述

中文和英文描述可以同时保存，原文应带语言标记。翻译或机器生成文本只能作为检索投影，不得覆盖提供方原始描述。

12.10.2 多语言标签

不同语言的标签名称应映射到同一规范标签 ID；如果没有可靠映射，应保留为普通文本而不是创建未经治理的新同义关系。

12.10.3 查询语言识别

语言识别只选择词法、别名和分词路径，不能改变资源类型、状态或信任过滤条件。混合语言查询应保留各片段的解析依据。

12.10.4 跨语言匹配

跨语言命中应返回规范标签 ID、实际命中的语言和别名，并标明是标签映射还是文本翻译命中。跨语言命中不等于资源具备额外能力。

12.11 面向向量检索与混合检索的扩展性

当前发现节点的语义扩展可以使用 PostgreSQL/pgvector 和 HTTP 嵌入服务构建资源级语义索引；本地语义推荐器则提供能力标签、资源类型和协议等推荐辅助。采用哪一种后端属于部署和参考实现选择，不能改变资源 DID、资源包、授权域、生命周期及根平台可信发布证明的处理规则。语义索引还应记录模型名称、模型版本、向量维度、索引版本和语义源哈希，使重建前后的结果能够解释。

当模型、维度或语义词汇发生不兼容变化时，应先重建相应索引，再将新结果作为同一索引版本提供给调用方。旧索引可以在迁移期保留，但不能把不同模型产生的分数直接横向比较。

12.12 语义治理兼容性与迁移

迁移时应同时保留三种信息：资源提供方提交的原始标签和描述、当时使用的词汇版本、以及新版本中的可解析映射。兼容映射可以让旧查询继续找到资源，但不能改写历史资源包中的原始字段。发现服务节点完成索引迁移后，应更新索引版本；迁移未完成或存在无法映射的标签时，结果可以继续作为有限的文本参考，但需要说明其语义治理状态。

12.13 语义词汇版本管理与变更影响

词汇版本与语义索引版本应分开记录：前者说明标签树和别名材料的版本，后者说明某个发现节点实际用哪些输入构建了检索数据。两者变化对系统的影响可以按以下方式理解：

发生回滚时，应恢复到上一套可验证的词汇和索引版本，而不是删除资源历史记录。查询结果和运维诊断至少应能指出使用的词汇版本、索引版本和更新时间，便于解释“同一查询为何在不同节点返回不同排序”。

12.14 语义治理可审计性

语义治理的审计记录需要回答“谁在什么时间对哪一个词汇版本做了什么改变，以及哪些推荐和索引受到了影响”。建议至少关联以下对象：操作者或治理主体、操作时间、变更类型、旧值和新值、词汇版本、原因、影响范围、索引重建状态和回滚依据。审计记录用于解释语义材料的变化，不应把标签变更记录误当成资源注册凭证或资源控制证明。

注册推荐和发现查询也应保留必要的引用关系。例如，推荐结果可以关联输入摘要、词汇版本和推荐候选；发现解释可以关联命中的标签 ID、别名或文本字段、索引版本和资源 DID。对于自然语言原文、调用方信息和内部模型输出，应遵守部署方的访问控制和最小留存策略，公开接口只暴露解释所需的最小内容。

12.15 自然语言查询与结构化条件映射

自然语言映射应分为“可以落到结构化字段的条件”和“只能作为检索线索的表达”。例如，“找一个可以检索代码仓库并总结项目结构的工具”可能得到资源类型候选、能力标签候选和文本检索词；“最新”“可信”“可调用”等词只有在协议和治理材料提供对应字段或事实时，才能参与确定性过滤，否则只能作为排序或解释提示。无法确认的词语必须保留其原文，不得强行映射为正式标签或授权条件。

{
  "query": "我需要一个可以检索代码仓库并总结项目结构的工具",
  "structuredConditions": {
    "resourceType": "tool_api",
    "capabilityTags": ["code.repository.search"]
  },
  "textTerms": ["总结项目结构"],
  "mappingStatus": "suggested"
}

上述对象是解释性中间结果示例，不是当前发现接口固定返回格式。正式请求仍应使用第11章规定的发现查询字段；中间结果中的 suggested 表示语义建议，调用方或资源提供方仍需确认标签、资源类型和协议条件。映射失败、词汇版本不兼容或语言不匹配时，可以退回原文检索或返回明确的无可用映射结果，但不能把失败隐藏为错误的正式条件。

参考来源