本附录中的模式是协议实现、测试向量和接口校验的共同依据。字段名称以实际 JSON 序列化结果为准，Rust 类型、TypeScript 类型和 HTTP 示例不得各自发明同义字段；如果某字段只在参考实现或特定资源类型中存在，应明确标为可选或 profile 扩展。模式版本、内容摘要、签名覆盖范围和未知字段处理规则应与正文第4至7章、第15章和第24章一致。

A.1 DID Document 模式

did:oan DID 文档的公共 Rust 类型包含 @context、id、verificationMethod、authentication、assertionMethod、service 和可选的 oanMetadata。其中 id 必须与被解析的 DID 完全一致；验证方法的 id、controller、公钥材料和引用关系必须能够支持签名验证。oanMetadata 中的资源类型、能力标签、用例、协议绑定、实现链接和资源包信息属于 OpenAgenet (OAN) 扩展，具体字段以 oan-core 的序列化定义为准。示例中的公钥、摘要和 DID 均为占位值；缺少 id、验证方法引用无法解析、服务端点不是有效 URI，或资源类型与 DID 语义码不匹配时，注册和索引校验应失败。当前公共类型未将 controller 作为 DID 文档顶层字段；若某个 DID profile 使用该字段，应单独说明其兼容范围，不能与 verificationMethod.controller 混同。

{
  "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/oan/v1"],
  "id": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "verificationMethod": [{
    "id": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu#key-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
    "publicKeyMultibase": "zExamplePublicKey"
  }],
  "authentication": ["did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu#key-1"],
  "assertionMethod": ["did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu#key-1"],
  "service": [],
  "oanMetadata": {
    "subjectType": "skill",
    "resourceType": "skill",
    "resourceDescription": {
      "name": "Example repository structure skill",
      "description": "Searches a repository and summarizes its project structure.",
      "capabilityTags": ["code-repository", "project-structure"],
      "useCaseExamples": ["Summarize the layout of a source repository."]
    },
    "capabilityTags": ["code-repository", "project-structure"],
    "authorizedDomains": ["software-development"]
  }
}

A.2 资源元数据模式

四类资源共用资源 DID、资源类型、名称、描述、版本、能力标签、用例、端点、协议绑定和实现链接等信息，但当前公共类型在不同层次承载这些信息：ResourceMetadata 使用 resourceDid、resourceType、subjectType、name、description、capabilityTags、authorizedDomains、protocolBindings、services、lifecycleState、packageVersion、哈希和 updatedAt；DID 文档则通过 oanMetadata.resourceDescription、capabilityTags、protocolBindings 和 packageInfo 表达对应信息。四类资源的枚举值是 agent_service、skill、mcp_server 和 tool_api，不能把展示名称 agent 当作协议值。字符串、数组和 URI 的长度、重复项及格式限制，应由具体 profile 或节点校验规则补充；未知资源类型、空 DID、摘要缺失或端点无法解析时，不能把数据当作完整元数据。兼容新增可选字段，破坏性变化应通过版本管理处理。

{
  "resourceDid": "did:oan:SKDM:ExampleResourceDid",
  "resourceType": "skill",
  "subjectType": "skill",
  "name": "Repository analysis",
  "description": "Searches a repository and summarizes its project structure.",
  "capabilityTags": ["software-development", "code-analysis"],
  "authorizedDomains": ["software-development"],
  "packageVersion": "1.2.0",
  "packageHash": "sha256:example-package-hash",
  "metadataHash": "sha256:example-metadata-hash",
  "hashAlgorithm": "sha256",
  "lifecycleState": "active",
  "updatedAt": "2026-09-07T01:02:08Z"
}

A.3 ResourcePackage 模式

资源包是当前公共 oan-package 类型定义的可验证、可分发版本对象，字段包括 packageVersion、resourceDid、resourceType、完整 didDocument、didDocumentHash、metadataHash、packageHash、hashAlgorithm、metadata、rootProof 和 createdAt。资源包内部没有通用的 manifest、contentDigest 或 resourceMetadata 顶层字段；如具体资源需要文件清单，应放入约定的扩展字段或外部资源材料，并明确 profile。包内摘要按当前实现分别覆盖 DID 文档、资源元数据和包声明，资源包版本不能代替 DID 文档或资源版本。缺少资源 DID、版本、摘要、元数据或根平台可信发布证明，摘要不一致，或资源类型不一致时拒绝验证。

{
  "packageVersion": "1.2.0",
  "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
  "resourceType": "skill",
  "didDocument": {
    "@context": ["https://www.w3.org/ns/did/v1", "https://w3id.org/oan/v1"],
    "id": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
    "verificationMethod": [{
      "id": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
      "publicKeyMultibase": "zExamplePublicKey"
    }],
    "authentication": ["did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu#key-1"],
    "assertionMethod": ["did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu#key-1"],
    "service": []
  },
  "didDocumentHash": "sha256:example-did-document-hash",
  "metadataHash": "sha256:example-metadata-hash",
  "packageHash": "sha256:example-package-hash",
  "hashAlgorithm": "sha256",
  "metadata": {
    "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
    "resourceType": "skill",
    "subjectType": "skill",
    "name": "Repository analysis",
    "description": "Searches a repository and summarizes its project structure.",
    "capabilityTags": ["software-development", "code-analysis"],
    "authorizedDomains": ["software-development"],
    "lifecycleState": "active",
    "packageVersion": "1.2.0",
    "packageHash": "sha256:example-package-hash",
    "metadataHash": "sha256:example-metadata-hash",
    "hashAlgorithm": "sha256",
    "updatedAt": "2026-09-07T01:02:08Z"
  },
  "rootProof": {
    "rootDid": "did:oan:INRT:7YpQm9Kx2VnRb6Ts3WfHa4Cd5Ej8LgNz",
    "packageClaims": {
      "resourceDid": "did:oan:SKLG:5HkPq7Vm3RdT9Ya2WcX8Ns4Bf6GjLeZu",
      "resourceType": "skill",
      "version": "1.2.0",
      "didDocumentHash": "sha256:example-did-document-hash",
      "metadataHash": "sha256:example-metadata-hash",
      "packageHash": "sha256:example-package-hash",
      "hashAlgorithm": "sha256",
      "lifecycleState": "active",
      "authorizedDomains": ["software-development"]
    }
  },
  "createdAt": "2026-09-07T01:02:08Z"
}

发布校验按以下顺序执行：

1. 解析包版本、资源类型和必填结构。
2. 校验资源 DID、DID 文档、元数据和包声明的一致性。
3. 按规范化规则重新计算内容摘要。
4. 验证根平台可信发布证明后，才进入分发或发现流程。

A.4 根平台可信发布证明模式

根平台可信发布证明在当前公共 RootProof 类型中至少包含 rootDid，并可以包含 bulletinEventHash、signature、packageClaims、proof、cryptoSuite 和 hashAlgorithm。资源 DID、资源类型、版本、DID 文档摘要、元数据摘要、包摘要、生命周期状态和授权域主要位于 packageClaims，而不是强制平铺在证明对象顶层。签发者必须是当前有权执行根平台发布的根平台身份；验证方应检查根平台签名、声明范围、哈希绑定、版本关系、公告事件引用和治理状态，而不能只检查 JSON 字段存在。证明失效、摘要不匹配、签发者未授权或目标版本已撤销时，发现服务节点不得把对应包作为当前有效资源。

A.5 注册 VC 模式

注册 VC 的公开响应采用 W3C 风格的 type、issuer、issuanceDate、credentialSubject、credentialStatus 和 proof 表达注册服务节点签发的登记事实；公共 Rust 凭证模型还提供 subject、status、issuedAt、expiresAt 和 claims 形式的内部结构，二者不能在同一 profile 中混写。当前官方注册节点返回的资源注册 VC 使用 credentialSubject.resourceDid、resourceType、didDocumentHash、metadataHash、packageHash、packageVersion、hashAlgorithm、authorizedDomains 和 lifecycleState 等声明。它证明注册服务节点对登记请求的受理，不自动证明根平台已发布或资源端点可用。缺少签发者、目标 DID、声明绑定或 proof 时验证失败；VC 为空、过期、吊销或状态未知时，调用方应区分不完整、无效和暂不可判定。

{
  "@context": ["https://www.w3.org/2018/credentials/v1", "https://openagenet.org/credentials/v1"],
  "type": ["VerifiableCredential", "OANResourceRegistrationCredential"],
  "issuer": "did:oan:INRG:RegistrarExample",
  "issuanceDate": "2026-09-07T00:00:00Z",
  "credentialSubject": {
    "id": "did:oan:SKDM:ExampleResourceDid",
    "resourceDid": "did:oan:SKDM:ExampleResourceDid",
    "resourceType": "skill",
    "didDocumentHash": "sha256:example-did-document-hash",
    "metadataHash": "sha256:example-metadata-hash",
    "packageHash": "sha256:example-package-hash",
    "packageVersion": "1.2.0",
    "hashAlgorithm": "sha256",
    "authorizedDomains": ["software-development"],
    "lifecycleState": "active"
  },
  "credentialStatus": {
    "type": "OANResourceRegistrationStatus",
    "status": "active"
  },
  "proof": { "type": "DataIntegrityProof", "proofValue": "..." }
}

注册 VC 证明注册服务节点已受理并签发登记凭证；只有根平台发布证明和发现索引状态均满足要求时，资源才可作为全网可发现资源使用。

A.6 节点授权 VC 模式

节点授权 VC 在公共凭证模型中以 credential_type、issuer、subject、role、status、issuedAt、可选的 expiresAt、claims 和 proof 表达节点资格；通过 JSON 序列化后字段名分别为 type、issuer、subject、role、status、issuedAt、expiresAt、claims 和 proof。授权域和能力范围通常位于 claims，而不是固定平铺字段。角色值应与节点角色枚举和部署 profile 一致；授权域和能力范围应使用可比较的结构化值。验证方须同时检查凭证签名、治理状态和当前有效期，不能因历史 VC 存在就忽略暂停或撤销事件。下面的 credentialSubject、validFrom 等字段仅用于展示层兼容示例，采用公共凭证模型时应使用上述字段。

{
  "type": "NodeAuthorizationCredential",
  "issuer": "did:oan:INRT:RootPlatformExample",
  "subject": "did:oan:INDS:DiscoveryNodeExample",
  "role": "discovery",
  "status": "active",
  "issuedAt": "2026-09-01T00:00:00Z",
  "expiresAt": "2027-09-01T00:00:00Z",
  "claims": {
    "authorizedDomains": ["software-development"],
    "capabilities": ["query", "index", "serve_public_results"]
  },
  "proof": { "type": "DataIntegrityProof", "proofValue": "..." }
}

A.7 治理事件模式

治理事件的公共公告模型由 Bulletin、BulletinEvent 和 BulletinEventCore 组成。事件核心字段为 sequence、previousHash、eventType、subjectDid、actorDid、payload 和 createdAt；事件本体再增加 eventHash、signature，以及可选的 proof、cryptoSuite 和 hashAlgorithm。当前事件类型包括根平台初始化、内容分发平台信息更新、注册服务节点授权/撤销、发现服务节点授权/域更新/撤销、节点撤销和能力标签树更新。链下投影可以另外记录接收时间、投影时间、游标和错误，但这些不是 BulletinEvent 的公共核心字段。链上或公告链原始事件是事实来源，页面展示文本和投影状态是派生信息；事件缺少序列、前序哈希、签名或目标主体，或投影顺序不连续时不得静默更新授权状态，应保留异常并等待补齐。

{
  "sequence": 1842,
  "previousHash": "sha256:example-previous-event-hash",
  "eventType": "DISCOVERY_NODE_AUTHORIZED",
  "subjectDid": "did:oan:INDS:DiscoveryNodeExample",
  "actorDid": "did:oan:INRT:RootPlatformExample",
  "payload": { "authorizedDomains": ["software-development"] },
  "createdAt": "2026-09-07T01:02:03Z",
  "eventHash": "sha256:example-event-hash",
  "signature": "zExampleSignature",
  "cryptoSuite": "ed25519-sha256",
  "hashAlgorithm": "sha256"
}

A.8 注册请求与响应模式

当前官方注册服务节点的浏览器/客户端入口为 POST /resources/register，请求反序列化为 ResourceRegistrationSubmission，包含 resourceDid、resourceType、didDocument、didDocumentHash、metadata、packageVersion、packageHash、metadataHash、hashAlgorithm、可空的 registrationCredential 和 subjectControlProof。节点内部向根平台转发时，才会包入 registrarDid 和 upstreamAuth，使用 POST /root/resources/verify-and-publish。因此，不能把内部转发包直接当作公网注册请求。响应通常包含 status、resourceDid、resourceType、registrationCredential 和 rootResponse；不同部署可以追加状态或关联标识。相同 DID、版本和摘要的重试是否完全幂等，应以节点存储和根平台实现为准；缺失控制证明、字段不完整或前序版本不匹配时不得写入有效登记。

POST /resources/register
Content-Type: application/json

{
  "resourceDid": "did:oan:SKDM:ExampleResourceDid",
  "resourceType": "skill",
  "didDocument": {},
  "didDocumentHash": "sha256:example-did-document-hash",
  "metadata": {
    "resourceType": "skill"
  },
  "packageVersion": "1.2.0",
  "packageHash": "sha256:example-package-hash",
  "metadataHash": "sha256:example-metadata-hash",
  "hashAlgorithm": "sha256",
  "registrationCredential": null,
  "subjectControlProof": {
    "challenge": {},
    "proof": {}
  }
}

A.9 发现请求与响应模式

公共 ResourceDiscoveryQuery 的字段是可选的 query、resourceType、capabilityTags、protocol、version，以及带默认值的 versionMode 和 limit。完整 DID 精确查询、结构化条件查询、标签查询和自然语言查询是节点对这些字段的使用方式，不是另设的 queryType 核心字段；分页和新鲜度字段可以出现在节点读模型或扩展 profile 中。公共 ResourceDiscoveryResponse 包含发现服务节点 DID、候选数组、创建时间和可选响应 proof；候选包含资源 DID、资源类型、分数、版本、生命周期、能力标签、授权域、服务、协议绑定、资源包信息和根平台可信发布证明引用。索引时间、来源说明和查询解释属于节点或官网派生展示信息。语义分数不能替代可信证据；未知条件、非法 DID、过期游标或查询服务不可用应返回可识别错误，不以空结果掩盖失败。

{
  "query": "I need a tool that can search code repositories and summarize the project structure.",
  "resourceType": "tool_api",
  "capabilityTags": ["code-analysis", "repository-search"],
  "protocol": "https",
  "versionMode": "latest",
  "limit": 20
}

{
  "discoveryDid": "did:oan:INDS:DiscoveryNodeExample",
  "candidates": [{
    "resourceDid": "did:oan:SKDM:ExampleResourceDid",
    "resourceType": "skill",
    "score": 0.94,
    "version": "1.2.0",
    "lifecycleState": "active",
    "capabilityTags": ["code-analysis", "repository-search"],
    "authorizedDomains": ["software-development"],
    "services": [],
    "protocolBindings": [],
    "packageInfo": { "packageHash": "sha256:example-package-hash" },
    "rootProof": { "rootDid": "did:oan:INRT:ExampleRootDid" }
  }],
  "createdAt": "2026-09-07T01:02:08Z",
  "proof": null
}

A.10 错误响应模式

当前节点公开错误结构以 { "error": "machine_readable_error_code" } 为基础；可信调用拒绝时还可能包含 reason。未来或特定网关可以扩展为对象，加入消息、关联请求标识和重试提示，但这不是所有节点当前都保证提供的字段。错误码应区分输入错误、签名/凭证错误、未授权、未找到、重复、版本冲突、依赖不可用、同步滞后和内部错误。面向公众的消息不得泄露私钥、数据库或内部配置；未知错误码的客户端应按失败处理而不是默认成功。

{
  "error": "sync_stale",
  "reason": "discovery_index_behind_publication"
}

若网关采用扩展错误对象，客户端应先判断 error 是字符串还是对象，再读取可选字段；不能假定对象形状，也不能把 HTTP 状态码单独当作业务错误码。注册服务节点当前会将部分上游错误映射为自身的 HTTP 错误响应，调用方应同时保留 HTTP 状态和响应体。

A.11 节点授权与治理状态模式

节点授权状态和治理状态通常由链下信任索引器或节点状态接口形成读侧投影，不等同于 NodeAuthorizationCredential 或公告事件本体。投影可包含节点 DID、节点角色、授权域、当前状态、状态原因、有效期、最近治理事件、事件序列、同步游标、数据时间和新鲜度；具体字段以对应接口为准。状态值至少应能区分有效、暂停、撤销、过期、未知和同步中；缺失治理来源或索引器落后时，不得伪造有效状态。敏感写入动作在状态未知或超过部署允许的新鲜度时采用拒绝或人工确认策略，展示接口可以单独标注延迟。

A.12 分发清单与同步游标模式

分发侧当前公共结构分为两类：内容分发平台索引响应使用 items、count、afterCursor、nextCursor 和 hasMore，每个条目包含 cursor 与完整资源包；根平台向发现服务节点发送的批量通知使用批次标识、根平台 DID、目标发现服务节点 DID、授权域、序列范围、条目、内容分发平台清单地址、更新地址和 proof。条目再携带资源 DID、操作、资源包版本、DID 文档摘要、元数据摘要、包摘要、哈希算法、生命周期状态、公告序列和公告事件哈希。清单版本、生成时间、错误或确认字段可由具体接口补充，不能把一个接口的字段直接套到另一接口。游标必须单调推进，重复批次应可安全重放，序列缺口或摘要不匹配时暂停该条目处理。游标是传输进度，不等于资源已经在发现服务节点建立索引。

{
  "items": [{
    "cursor": 1842,
    "package": {
      "packageVersion": "1.2.0",
      "resourceDid": "did:oan:SKDM:ExampleResourceDid",
      "resourceType": "skill",
      "didDocument": { "id": "did:oan:SKDM:ExampleResourceDid" },
      "didDocumentHash": "sha256:example-did-document-hash",
      "metadataHash": "sha256:example-metadata-hash",
      "packageHash": "sha256:example-package-hash",
      "hashAlgorithm": "sha256",
      "metadata": {
        "resourceDid": "did:oan:SKDM:ExampleResourceDid",
        "resourceType": "skill",
        "subjectType": "skill",
        "name": "Repository analysis",
        "lifecycleState": "active",
        "packageVersion": "1.2.0",
        "packageHash": "sha256:example-package-hash",
        "metadataHash": "sha256:example-metadata-hash",
        "hashAlgorithm": "sha256",
        "updatedAt": "2026-09-07T01:02:08Z"
      },
      "rootProof": { "rootDid": "did:oan:INRT:ExampleRootDid" },
      "createdAt": "2026-09-07T01:02:08Z"
    }
  }],
  "count": 1,
  "afterCursor": 1800,
  "nextCursor": 1842,
  "hasMore": false
}

根平台通知条目的最小形状示例为：

{
  "resourceDid": "did:oan:SKDM:ExampleResourceDid",
  "resourceType": "skill",
  "operation": "upsert",
  "packageVersion": "1.2.0",
  "didDocumentHash": "sha256:example-did-document-hash",
  "metadataHash": "sha256:example-metadata-hash",
  "packageHash": "sha256:example-package-hash",
  "hashAlgorithm": "sha256",
  "lifecycleState": "active",
  "bulletinSequence": 1842,
  "bulletinEventHash": "sha256:example-event-hash",
  "capabilityTags": ["software-development"],
  "authorizedDomains": ["software-development"]
}

清单/通知 -> 校验摘要、证明、序列和授权域 -> 确认传输进度 -> 建立或更新发现索引

sequenceDiagram
    participant D as 内容分发平台
    participant I as 发现服务节点
    D->>I: 清单(afterCursor)
    I->>I: 校验摘要、证明与序列
    I-->>D: 确认(acceptedCursor)
    I->>I: 建立或更新发现索引
    I-->>D: 索引状态(current/stale/partial)

A.13 搜索解释与证据模式

搜索解释应说明查询类型、解析后的条件、命中的能力标签或用例、结构化过滤、相关性分数、结果来源、版本、资源状态、索引时间、根平台可信发布证明和新鲜度。解释是帮助调用方理解结果的派生信息，不能作为签名或授权证据。字段缺失、语义模型版本不兼容或来源不可验证时，应明确标注未知或不完整，而不是补写推测性理由。

{
  "queryExplanation": {
    "queryType": "semantic",
    "normalizedIntent": "repository structure summarization",
    "matchedTags": ["code-analysis", "repository-search"],
    "filtersApplied": { "resourceTypes": ["skill", "tool_api"] },
    "modelVersion": "semantic-index-v1"
  },
  "evidence": {
    "resourceDid": "did:oan:SKDM:ExampleResourceDid",
    "rootPublication": "verified",
    "governance": "active",
    "indexedAt": "2026-09-07T01:02:08Z",
    "freshness": "current"
  }
}

参考来源