本章规定资源元数据和 ResourcePackage 的数据边界、字段关系、确定性哈希和接收方验证方式。资源元数据描述资源是什么、能够做什么以及如何连接，ResourcePackage 将特定资源版本的 DID文档、元数据、哈希和根平台可信发布证明组织为可分发对象。注册提交是进入验证流程的输入，根平台验证资源包是经过网络级验证后的发布产物，三者不能互相替代。

本章以 oan-protocol-common 的资源类型、序列化实现和资源包校验代码为主要依据。当前注册 payload schema 只提供对象级入口约束，具体字段语义由协议类型和校验逻辑共同确定；当 schema、实现和部署配置存在差异时，应标明适用版本和差异，不能把单一示例直接视为所有实现的强制行为。

6.1 资源元数据模式

资源元数据在 Rust 实现中由 ResourceMetadata 表达，核心字段如下：

这些字段可以公开用于注册、分发和发现，但控制私钥、内部访问凭证和不应公开的运行细节不得放入元数据。未知扩展字段只有在不改变核心字段含义、哈希输入和验证结果时才可保留；核心字段类型错误、资源 DID 缺失或枚举值不受支持时，接收方应拒绝。

下面的片段展示一个 ResourceMetadata 实例的字段关系；哈希值使用示例值，不能直接作为生产材料。packageHash 和 metadataHash 在元数据哈希计算阶段需要先清空，之后再回填计算结果。

{
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "resourceType": "skill",
  "subjectType": "skill",
  "publisherDid": "did:oan:ORLG:8LcR3Vn5YpQw2Tx7Mb9Zd4Fa6GhKsEuJ",
  "subjectDid": "did:oan:DVLG:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
  "name": "Repository Structure Summary",
  "description": "Summarizes the structure of a code repository.",
  "capabilityTags": ["code-repository", "project-structure-summary"],
  "authorizedDomains": ["public"],
  "protocolBindings": [],
  "services": [],
  "lifecycleState": "active",
  "packageVersion": "1.0.0",
  "packageHash": "sha256:example-package",
  "metadataHash": "sha256:example-metadata",
  "hashAlgorithm": "sha256",
  "updatedAt": "2026-09-09T08:30:00Z"
}

6.2 必填字段与可选字段

ResourcePackage 的结构性必需字段包括 packageVersion、resourceDid、resourceType、didDocument、didDocumentHash、metadataHash、packageHash、hashAlgorithm、metadata、rootProof 和 createdAt。元数据中的资源 DID、资源类型、主体类型、包版本、三个关键哈希和哈希算法是形成可验证发布对象的核心字段；能力标签、授权域、协议绑定和服务端点可以为空数组或按资源类型不声明，但省略后不得宣称具备相应能力。

四类资源共享公共身份、描述、版本、完整性和治理字段。智能体服务通常需要能力描述、用例、交互协议和服务端点；技能包需要包入口、安装或加载信息及依赖；MCP 服务需要传输方式、工具或资源清单和认证要求；工具 API 需要操作、参数、输出和调用约束。具体必填性以对应版本的协议模型为准，网页输入项不能直接替代底层 schema。

协议要求的字段为空时必须拒绝，可选字段缺失时按“未声明”处理；未知扩展字段可以在兼容模式下保留，但不得被用于无法解释的权限判断。注册服务节点应在登记前检查，ResourcePackage 接收方应再次检查。

四类资源共享资源 DID、资源类型、主体类型、描述、能力标签、版本、授权域和完整性字段，但资源类型决定哪些能力描述和端点信息具有实际意义。字段缺失时，应区分“未声明”与“结构不完整”：例如没有可选服务端点可以表示尚未声明调用入口，但缺少 resourceDid、资源类型、DID文档或资源包哈希则无法形成可验证资源包。

6.3 资源类型与主体类型约束

资源类型与 did:oan 语义编码应保持一致：agent_service 对应 AG，skill 对应 SK，mcp_server 对应 MC，tool_api 对应 TL。资源元数据中的 resourceType 和 subjectType 在当前资源包校验中必须相同，并且都应与资源 DID 的主体代码一致。基础设施节点、组织和开发者可以作为方法层标识对象，但不能把节点 DID 直接填充为产品资源 DID。

一个主体可以控制多个资源 DID，一个资源提供方也可以运营多个资源；主体 DID、资源 DID 和节点 DID 的身份边界不因关系字段而合并。资源类型、主体类型、DID文档 id 或包内元数据不一致时，验证方必须拒绝该资源包。

6.4 名称、描述、标签与用例

名称和描述是资源提供方对资源能力的公开声明，能力标签和用例是供注册推荐、语义治理和发现检索使用的信息。标签应优先引用根平台能力标签树中的标识，扩展标签应标明来源或命名空间。自然语言可使用中文、英文或其它声明语言，但字段类型和数组结构必须稳定，不能混入 HTML、脚本或不可解析对象。描述详细不等于能力已验证，相关性排序也不构成控制权或业务质量证明。

名称和描述是资源提供方对资源能力的公开声明，能力标签和用例是供注册推荐、语义治理和发现检索使用的信息。标签应优先引用根平台能力标签树中的标识；扩展标签应标明来源或命名空间。自然语言可使用中文、英文或其它声明语言，但字段类型和数组结构必须保持稳定，不能将 HTML、脚本或不可解析对象混入文本字段。

描述和用例越详细并不等于能力已经验证，发现节点的相关性排序也不构成控制权、端点可用性或业务质量证明。长度、数量和内容过滤应由部署配置或符合性配置明确，并在接入和索引前执行。

能力标签和用例进入发现流程时，可以同时作为结构化条件和语义检索文本，但结果应保留原始值及其来源。例如，查询“我需要一个可以检索代码仓库并总结项目结构的工具”可以命中相应的能力描述和用例；是否可调用仍需继续检查资源 DID、发布证明、端点和凭证要求。标签命中只是相关性证据，不是资源控制权或业务效果的证明。

6.5 语义标签与协议绑定

capabilityTags 表达资源能力分类，authorizedDomains 表达传播和发现权限范围，二者不能互换。protocolBindings 中的绑定对象至少应说明协议名称，并可包含版本、传输方式、serviceRef 和 schemaRef；协议绑定描述接入方式，不自动赋予调用权限。注册服务节点可以据此提供标签推荐，发现服务节点可以据此进行结构化或语义检索，但返回结果仍须保留来源和验证状态。

capabilityTags 表达资源能力分类，authorizedDomains 表达传播和发现权限范围，二者不能互换。protocolBindings 中的绑定对象至少应说明协议名称，并可包含版本、传输方式、serviceRef 和 schemaRef；协议绑定描述接入方式，不自动赋予调用权限。标签树版本、标签标识和别名应保留来源，以便不同节点解释同一标签。

注册服务节点可以根据能力描述和标签树提供推荐，发现服务节点可以据此进行结构化或语义检索，但对外返回结果时仍须保留原始标签、协议绑定、来源和验证状态。标签匹配成功而根平台发布证明缺失时，不得进入可信发现结果。

协议绑定的最小表达可以写成如下对象，serviceRef 和 schemaRef 是资源内部引用或外部 schema 引用，不能被解释为新的身份：

{
  "id": "mcp-http",
  "protocol": "MCP",
  "version": "2025-06-18",
  "transport": "streamable-http",
  "serviceRef": "#mcp-service",
  "schemaRef": "https://example.invalid/schema/mcp.json"
}

6.6 服务端点与调用要求

资源端点由服务端点数组表达，核心结构包括端点 ID、服务类型和 serviceEndpoint，并可包含版本、协议、服务器类型和端口。端点可以是智能体交互入口、MCP 服务入口、工具 API 地址、资源包地址或协议描述地址；端点类型和协议应能解释其用途，多个端点之间的版本和认证差异应明确。认证声明可以表达凭证类型、签发方、范围、呈现方式或调用前提，但只是公开调用要求；端点存在或 HTTP 可达不等同于调用方已经获得访问许可。敏感 token、私钥和内部网络凭据不得作为公开元数据发布。

6.7 资源版本与兼容性字段

packageVersion 标识资源包版本，资源描述中的 version 或协议绑定中的版本可以表达资源能力或协议版本，不能无说明地相互替代。previousVersion、版本约束或发布说明可以建立更新链和兼容关系，但版本字符串本身不证明内容来源。每个版本都必须绑定资源 DID、DID文档哈希、元数据哈希、资源包哈希和哈希算法；同一资源 DID 的新版本应通过新的资源包和控制证明进入验证流程。

版本比较至少要把资源包版本、协议版本和资源生命周期分开记录：

版本字符串相同也不代表内容相同，接收方仍应检查资源 DID、三类哈希、根平台证明和治理状态；内容变化却沿用旧哈希时，应按完整性失败处理。

6.8 包哈希与元数据哈希

当前实现分别计算 DID文档哈希、资源元数据哈希和资源包哈希。哈希值以算法前缀表达，例如 sha256:<digest>；hashAlgorithm 必须与哈希引用的算法前缀一致。元数据哈希计算前会清空元数据自身的 metadataHash 和 packageHash，避免循环依赖；资源包哈希只对包版本、资源 DID、资源类型、DID文档哈希、元数据哈希和哈希算法等固定声明计算。验证方应使用相同密码套件和序列化方式重算三类哈希；哈希匹配不能单独证明控制权、节点授权或端点可用性。

资源包哈希的输入不是整个资源包的递归序列化，而是当前实现明确选取的包声明字段：

{
  "packageVersion": "1.0.0",
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "resourceType": "skill",
  "didDocumentHash": "sha256:example-did-document",
  "metadataHash": "sha256:example-metadata",
  "hashAlgorithm": "sha256"
}

该输入用于说明 verify_package_hash 的字段边界；实际哈希值应由实现按统一密码套件计算，不能把示例摘要写入生产包。元数据哈希则针对清除自身两个哈希字段后的 ResourceMetadata 计算，二者的输入集合不能混用。

6.9 规范化序列化与确定性哈希

确定性哈希要求实现使用相同字段名、枚举序列化、数组顺序、时间格式、空值处理和字符编码。当前 Rust 实现通过 serde 序列化对象后交由统一哈希函数处理；跨语言实现不得改变字段命名、补入任意默认值或在哈希前排序数组，除非规范版本明确规定。元数据和包哈希均不应把自身输出字段再次纳入输入；规范化失败、对象无法序列化或算法不支持时，应停止构造并返回错误。

跨语言复现时应把哈希前对象记录下来，便于定位“字段不同”和“序列化不同”两类问题：

ResourceMetadata for hashing
  -> clear metadataHash and packageHash
  -> serialize with protocol field names and stable enum values
  -> hash with the selected crypto suite
  -> write metadataHash back to the package

Package hash input
  -> packageVersion, resourceDid, resourceType
  -> didDocumentHash, metadataHash, hashAlgorithm
  -> serialize and hash

如果只改变元数据中的描述、标签顺序、授权域或时间字段，规范化后的元数据输入就会变化，接收方应得到不同的元数据哈希；如果只回填计算结果而不改变其它输入，已有哈希不应再次变化。

6.10 ResourcePackage 构造规则

ResourcePackage 的构造顺序是：确定资源 DID、资源类型、DID文档和元数据；计算 DID文档哈希和元数据哈希；计算资源包哈希；组织版本、哈希、生命周期状态和授权域声明；由资源控制方提交控制证明，并由注册服务节点和根平台分别处理其登记与发布职责。根平台可信发布证明只能在根平台验证通过后产生，不能由客户端预先构造为已发布事实。

资源元数据、DID文档、资源包、根平台可信发布证明和发现索引记录的责任边界如下：

构造和发布之间的关系可以表示为：

flowchart LR
    META[资源元数据] --> MH[元数据哈希]
    DID[DID文档] --> DH[DID文档哈希]
    MH --> PKG[ResourcePackage]
    DH --> PKG
    PKG --> PH[资源包哈希]
    PKG --> PROOF[根平台可信发布证明]
    PROOF --> DIST[分发材料]
    DIST --> INDEX[发现服务节点索引]

构造过程可以用一条可复核的依赖链表示：

flowchart LR
    INPUT[资源 DID、DID文档、元数据、版本] --> DID_HASH[DID文档哈希]
    INPUT --> META_HASH[清除自身哈希后的元数据哈希]
    DID_HASH --> PACKAGE_INPUT[包哈希输入]
    META_HASH --> PACKAGE_INPUT
    PACKAGE_INPUT --> PACKAGE_HASH[资源包哈希]
    PACKAGE_HASH --> PACKAGE[ResourcePackage]
    PACKAGE --> CONTROL[资源控制证明]
    CONTROL --> REGISTRAR[注册服务节点登记处理]
    REGISTRAR --> ROOT[根平台验证并产生根平台可信发布证明]

图中的登记处理和根平台验证属于资源网络阶段，不能提前写入客户端构造的普通资源包。每一步都应保留输入版本和输出哈希；任一步输入改变，都应重新执行后续依赖步骤。

6.10.1 输入材料

输入材料包括资源 DID、资源类型、DID文档、资源元数据、资源包版本、哈希算法、资源控制证明和必要的注册凭证或来源引用。DID文档 id、元数据 resourceDid、包 resourceDid 和控制挑战目标 DID 应一致，资源类型和主体类型应与 DID 语义编码一致。

6.10.2 字段规范化

构造方应使用协议字段名和确定性序列化规则，固定时间为可解析的 UTC 表示，保持数组顺序和枚举值稳定。计算元数据哈希前清除元数据中的 metadataHash、packageHash，计算包哈希时只纳入规定的包声明字段。

这些字段通过 serde 映射到 HTTP JSON，而不是在编译时自动生成一份独立的接口模式。ResourceRegistrationSubmission 的 didDocument 使用 DID文档类型，metadata 使用动态 JSON；ResourcePackage 的 metadata 使用资源元数据类型，rootProof 使用根平台证明类型。接收方因此既要依据 Rust 类型完成反序列化，也要执行资源类型、哈希和证明的业务校验；能够反序列化不等于能够发布。

6.10.3 哈希计算

依次计算 DID文档哈希、元数据哈希和资源包哈希，并将算法前缀写入相应字段。回填哈希后不得改变参与哈希的其它字段；任一重算结果变化都表示当前版本内容发生变化。

6.10.4 签名与证明生成

资源控制方对控制挑战和规定的资源控制材料签名，注册服务节点可以对登记事实签发注册凭证，根平台在验证节点授权、控制证明、哈希和发布条件后生成根平台可信发布证明。证明的签发者、验证方法、目标 DID、用途和覆盖哈希必须可核对。

6.10.5 构造后的校验

构造完成后应依次检查资源类型一致性、元数据一致性、DID文档哈希、元数据哈希、资源包哈希和根平台声明绑定。任何检查失败都不得将对象标记为可分发或可信发布；失败对象可以作为本地诊断材料保存，但不应进入公开索引。

构造后的检查结果可以记录为机器可读的诊断摘要：

{
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "packageVersion": "1.0.0",
  "checks": [
    { "name": "resource_type_consistency", "status": "passed" },
    { "name": "metadata_consistency", "status": "passed" },
    { "name": "did_document_hash", "status": "passed" },
    { "name": "metadata_hash", "status": "passed" },
    { "name": "package_hash", "status": "passed" },
    { "name": "root_claim_binding", "status": "passed" }
  ],
  "publishable": true
}

publishable 只表示本地对象通过当前包校验，不能替代注册服务节点受理或根平台发布。若任一检查失败，诊断结果应包含对应错误类别，包不得进入可信分发或发现索引。

6.11 根平台验证的 ResourcePackage 结构

根平台验证后的 ResourcePackage 仍然以资源控制方提供的 DID文档、资源元数据和哈希为基础，但新增或绑定根平台对该特定资源版本的验证结果。rootProof 中的根平台 DID、packageClaims、签名或数据完整性证明，以及必要的公告事件引用，共同表达根平台已经检查并接受哪些事实。发布序列、发布时间和同步游标属于发布或传播层信息，不能倒写成资源提供方原始声明。

6.11.1 资源身份部分

资源身份部分包括 resourceDid、resourceType、包内 DID文档及 didDocumentHash。接收方应检查包字段与 DID文档 id 一致，解析 did:oan 并验证资源类型映射；身份部分有效只说明包绑定了一个可解析资源 DID，不说明资源已被根平台发布。

6.11.2 资源元数据部分

资源元数据部分包括名称、描述、能力标签、用例、授权域、协议绑定、服务端点、生命周期和版本信息。接收方应检查元数据哈希、资源类型、资源 DID、包版本、授权域和生命周期与包外声明一致，并保留元数据来源和更新时间。

6.11.3 根平台验证证明

根平台验证证明至少应能关联根平台 DID、资源 DID、资源类型、包版本、DID文档哈希、元数据哈希、包哈希、哈希算法、生命周期状态和授权域。packageClaims 与包内容不一致、证明签名无法验证或证明来源不在信任范围内时，包不得被视为根平台验证资源包。

6.11.4 分发和索引所需字段

分发和索引至少需要资源 DID、资源类型、包版本、三类哈希、根平台证明、生命周期状态、授权域、来源引用和发布或同步游标。发现服务节点还应记录本地接收时间、验证时间、当前同步位置和拒绝原因，以便解释旧快照、索引滞后和跨节点不一致。

6.12 ResourcePackage 完整性与来源验证

接收方应先验证结构和资源身份，再按 DID文档哈希、元数据哈希、资源包哈希、字段一致性和根平台证明的顺序完成验证，最后结合生命周期、授权域、版本和治理状态决定是否写入分发缓存或发现索引。哈希或证明失败必须阻止进入可信读模型；网络暂时不可用可以进入待重试状态，但不得把未完成验证的对象标记为已发布。

接收方可以把验证结果划分为“通过”“拒绝”和“待重试”三类：

“待重试”不是一种已验证状态。即使包的 JSON 结构正确，只要根平台证明或必要来源无法确认，接收方也只能保留未完成状态。

6.13 ResourcePackage 来源链与来源归属

资源来源链至少包含五类事实：资源控制方产生 DID文档、元数据和控制证明；注册服务节点产生登记受理和注册凭证；根平台产生资源版本接受、根平台可信发布证明和发布引用；内容分发平台转发或缓存根平台允许传播的材料；发现服务节点产生本地验证和索引记录。每类事实都应标识来源主体、目标资源 DID、版本、时间或游标，并保持签名或哈希关联。

来源链可以按“声明、登记、发布、传输、索引”五个阶段阅读：

资源控制方
  -> DID文档、资源元数据、控制证明
注册服务节点
  -> 登记记录、注册凭证
根平台
  -> 接受记录、根平台可信发布证明、发布引用
内容分发平台
  -> 已验证材料的传输或缓存记录
发现服务节点
  -> 本地校验、同步位置和发现索引记录

后一个阶段只能补充自己的处理事实，不能替前一个阶段签发其没有产生的证明。例如发现服务节点的索引记录可以说明它验证并保存了某版本材料，但不能替代资源控制方的控制证明或根平台的发布证明。

6.13.1 资源控制方来源

资源控制方来源由 DID文档控制关系、资源控制证明及其签名验证方法确定。publisherDid 或 subjectDid 可以补充业务关系，但不能替代控制证明；接收方应将资源方声明与当前 DID文档和证明一起核对。

6.13.2 注册节点来源

注册服务节点来源由登记请求的接收记录、节点 DID、节点授权材料、注册凭证和处理状态表达。注册凭证的有效范围是登记事实，不自动证明根平台已经接受或发现服务节点已经索引。

6.13.3 根平台发布来源

根平台发布来源由根平台 DID、根平台可信发布证明、资源包声明和发布或公告引用表达。根平台证明必须绑定具体资源版本和哈希；同一资源 DID 的其它版本不能直接复用该证明。

6.13.4 来源链验证

来源链验证要求沿控制证明、注册凭证、根平台可信发布证明和分发记录逐层检查。内容分发平台只证明传输或缓存行为，发现服务节点只证明本地取得、验证和索引行为；任一层缺失都应在响应中反映，不得用下一层的存在掩盖上一层失败。

6.14 包大小、内容限制与校验策略

大小、长度、嵌套深度、端点数量、标签数量和协议绑定数量应由部署或符合性配置明确，并在注册服务节点和 ResourcePackage 接收方执行相同或不低于网络要求的限制。当前 schema 未给出统一业务数值上限时，不应在本章虚构固定数字；实现必须在超限时返回可识别错误，避免超大文本、深层嵌套或大量端点耗尽解析、索引和哈希资源。限制检查应在哈希计算前完成，避免因截断、丢弃或自动压缩产生不同哈希。

限制检查应针对原始输入执行，并把失败原因与字段路径关联起来，而不是静默截断内容：

{
  "validation": "rejected",
  "errors": [
    {
      "path": "metadata.capabilityTags",
      "code": "limit_exceeded",
      "message": "capability tag count exceeds the active profile"
    }
  ],
  "hashingStarted": false
}

示例中的限制值由实际部署配置决定。只要输入被截断、字段被丢弃或数组被自动重排，计算对象就已发生变化，不能继续使用原始签名或哈希。

6.15 模式演进与向后兼容

模式演进应区分新增可选字段、改变既有语义、删除字段，以及改变哈希输入或签名覆盖范围的升级。新增字段若不影响旧实现解析和既有哈希规则，可以通过版本化扩展使用；若改变资源身份、资源类型、版本、哈希输入、根平台声明或验证流程，则必须提升模式或协议版本，并明确旧节点的处理方式。旧节点遇到未知可选字段时可以忽略，但不得在重新计算已签名对象时静默丢弃被覆盖的字段；遇到未知必需字段、无法解释的哈希算法或证明无法验证时，应拒绝或进入待兼容状态。

本节只规定模式变化对解析和完整性校验的影响。资源元数据、DID文档、资源包、根平台可信发布证明和发现索引记录的职责边界，分别在 6.1、6.4、6.10 至 6.13 以及第9、10章中说明；模式版本变化不自动改变资源控制权、发布状态或发现可见性。接收方仍应按照既有校验顺序重新计算相关哈希并保留失败原因。

参考来源