本章的流程统一采用“准备、提交、验证、传播、发现、调用、更新或恢复”的状态链。参考实现中的接口名称、网站按钮和部署地址属于示例环境；规范不要求所有实现采用同一界面，但要求关键事实可以被独立验证。端到端记录至少关联资源 DID、资源类型、版本、请求标识、来源节点、观察时间和证据摘要。流程中的“完成”应以对应事实和证据为准：注册服务节点返回受理结果、根平台形成发布事实、内容分发平台完成材料传输、发现服务节点建立索引，分别是不同阶段，不能合并为一个成功状态。

flowchart LR
  A[本地身份与资源材料] --> B[注册服务节点]
  B --> C{根平台验证}
  C -- 拒绝 --> X[记录错误并停止]
  C -- 接受 --> D[根平台可信发布证明]
  D --> E[内容分发平台]
  E --> F[发现服务节点索引]
  F --> G[调用方验证与调用]

本章以“本地身份和测试资源已准备、节点端点可访问、测试环境与生产环境隔离”为前提，给出从资源创建、注册、可信发布、发现、验证到更新和故障处理的参考路径。示例展示可复现的交互关系，不把某个官网按钮、当前部署地址或一次成功响应扩大为所有实现的强制接口。执行时应将测试资源、测试主体和请求标识与生产资源隔离，并保存请求材料、响应摘要、DID文档、注册凭证、根平台可信发布证明、同步游标和查询结果之间的关联。

sequenceDiagram
    participant U as 资源控制方
    participant R as 注册服务节点
    participant Root as 根平台
    participant C as 内容分发平台
    participant D as 发现服务节点
    participant V as 调用方
    U->>R: 资源材料与控制证明
    R->>Root: 验证/发布请求
    Root-->>R: 接受、拒绝或处理中
    Root->>C: 已验证资源包与证明
    C->>D: 游标同步
    D-->>V: 查询结果与来源
    V->>V: DID、VC、治理和端点验证

每一步都应记录输入来源、事实产生者、验证者、状态变化和证据；页面提示或单个 HTTP 成功响应不能代表端到端完成。

22.1 创建本地身份

客户端在本地生成主体密钥和主体 DID，建立本地身份记录，并导出带时间标识的身份备份文件。注册智能体服务、技能包、MCP 服务或工具 API 时，再由该主体在本地生成或关联资源身份和资源控制证明。私钥只留在发布者控制范围内，不随普通注册请求发送；恢复时重新校验文件结构、公钥与私钥对应关系、主体 DID 一致性以及可否重新签名。验收证据包括 DID、公钥、备份摘要和恢复后的等价性，而不是把私钥上传成功作为结果。

22.2 注册智能体服务

以一个声明“代码仓库检索和项目结构总结”的智能体服务为例，发布者先准备资源 DID、能力标签、能力描述、用例、端点、协议声明、认证条件和版本，再使用本地控制密钥签署 DID文档或资源包材料。客户端将公开注册材料和控制证明提交给注册服务节点；注册服务节点校验请求并向根平台提交，成功时返回登记结果和可能存在的注册 VC。随后还要等待根平台发布、内容分发和发现服务节点索引，分别取得相应状态和证据。

{
  "resourceType": "agent_service",
  "capabilityTags": ["code.repository", "analysis.summary"],
  "version": "1.0.0",
  "authorizedDomains": ["technology.software_engineering"]
}

注册材料、请求摘要、注册 VC（如有）、根平台状态、资源包摘要和发现结果应分别留存，不能把“提交成功”写成“已被全网发现”。同一资源再次提交时，应先判断资源 DID、版本和材料是否变化；相同版本的重复请求应按注册服务节点实际返回判断是否幂等，不能据页面提示推断产生了新版本。

22.3 注册技能包

技能包示例应给出名称、能力、输入输出、用例、依赖、版本、安装或调用入口、标签、主体 DID 和资源 DID，并计算资源包内容摘要。发布者先在本地完成材料规范化和签名，再向注册服务节点提交；提交后核对受理结果、资源类型、版本、摘要和注册凭证（如有），随后按 22.6 的顺序核对根平台发布和发现服务节点索引。技能包能够安装或在本地运行，不等于已经获得根平台发布或发现服务节点索引。

技能包验收同时检查两条线：产品线核对入口、依赖、输入输出和用例，网络线核对 DID、资源包版本、摘要、控制签名、登记、发布和索引状态。两条线的结果分开记录；产品线失败说明资源本身不可按声明使用，网络线失败说明资源尚未形成可验证的网络发布链路，不能用一条线的通过结果替代另一条线。

22.4 注册 MCP 服务

MCP 服务示例应准备服务器身份、工具或资源清单、传输方式、端点、认证方式、协议版本和兼容性声明。发布者将清单摘要、服务端点和资源版本纳入资源材料并在本地签署，注册服务节点验证字段和控制证明；调用方在发现后仍需按 MCP 流程建立会话，并按 OpenAgenet (OAN) 规则核对 DID、资源包、发布证据和治理状态。

22.5 注册工具 API

工具 API 以 OpenAPI 或等价描述作为输入，明确操作、参数、请求体、响应、错误、认证、服务器端点和版本。发布者先确定描述文件来源和版本，再将规范化描述摘要绑定到资源包并签名；注册服务节点验证材料，调用方可通过摘要确认取得的 API 契约未被替换。摘要验证不能证明接口当前可用，实际业务权限仍由 API 服务端决定。

operationId: searchRepository
source: openapi.yaml#/paths/~1repositories~1search/get
version: 1.0.0
schemaHash: sha256:<value>

原始描述、规范化摘要和 OAN 控制签名应分别保存；文档可读不等于接口可调用。

22.6 发布与分发资源

资源经注册服务节点受理后，根平台验证控制证明、节点授权、资源类型、版本、内容摘要和发布条件，形成根平台可信发布证明；内容分发平台按发布清单或游标保存、传输已验证材料，发现服务节点按游标接收、验签、校验并建立结构化和语义索引。每一步独立记录结果，不能以注册成功代替可发现，也不能以材料已分发代替索引已完成。

flowchart LR
  A[注册受理] --> B{根平台验证}
  B -- 拒绝 --> X[错误记录/无发布状态]
  B -- 接受 --> C[根平台可信发布证明]
  C --> D[内容分发]
  D --> E[发现服务节点校验]
  E --> F[可查询索引]

22.6.1 注册结果

注册结果至少包含资源 DID、资源类型、版本或摘要、受理状态、注册 VC（如接口返回）和关联标识。VC 为空时只能如实记录为空，不能自行伪造凭证；注册服务节点受理失败应保留错误原因，客户端可依据请求标识或协议允许的幂等方式重试。客户端还应记录注册结果由哪个节点返回以及观察时间，以免把后续异步发布状态混入登记结果。

{
  "resourceDid": "did:oan:AGDM:<identifier>",
  "status": "submitted",
  "registrationCredential": null,
  "observedAt": "<timestamp>"
}

submitted 仅表示登记阶段结果，不能解释为根平台发布或发现可见。

22.6.2 根平台发布

根平台核对注册服务节点授权、资源控制签名、资源包完整性、版本关系和治理条件，接受后记录发布序列并形成根平台可信发布证明。拒绝、重复或异步处理中均应有明确状态；根平台没有接受时，不得把内容分发或本地缓存标记为可信发布。发布证据至少要与资源 DID、版本和各项摘要绑定，重复处理不能产生互相冲突的当前版本。

根平台发布记录至少关联资源 DID、版本、DID文档哈希、元数据哈希、包哈希、注册服务节点 DID、发布序列和处理状态；重复处理应保持幂等。

22.6.3 内容分发

内容分发平台按根平台发布清单或游标提供 DID 文档、资源包、摘要和证明材料，接收方校验完整性后记录接收游标。断点续传和重复投递应幂等；分发成功只说明材料可取得，不说明发现服务节点已经建立可查询索引。接收方发现摘要、版本或证明不一致时，应拒绝写入可见索引并保留失败材料的诊断信息。

分发校验顺序为“清单、内容、摘要、证明、游标”。发送端记录批次和游标，接收端先验证每项版本和摘要，再提交本地状态；传输成功不等于索引完成。

22.6.4 发现节点索引

发现服务节点接收材料后验证根平台可信发布证明、摘要、版本、治理状态和授权域，再写入结构化及语义索引。索引完成应有资源 DID、版本、来源、索引时间和游标证据；语义索引命中不能覆盖证明无效或资源已撤销。查询方应根据索引时间和同步游标判断结果是否新鲜，并在需要最新状态时回到可验证来源复核。

索引记录至少包含 resourceDid、版本、来源、授权域、生命周期、indexedAt 和同步游标。只有验证通过的材料进入可见索引，语义命中只提供检索入口。

22.7 按 DID 发现

调用方将完整资源 DID 作为精确查询条件提交发现服务节点，例如请求 /discovery/resources/query 时将 DID 放入查询字段。发现服务节点返回当前索引中的资源版本、摘要、来源、生命周期状态、索引时间和根平台可信发布证明状态。得到结果后仍要执行调用前验证；未找到、节点未同步、索引过期和资源已撤销应区分处理，不能把空结果直接解释为资源不存在。

{
  "resourceDid": "did:oan:SKDM:<identifier>",
  "limit": 1
}

验收应区分精确命中、未找到、尚未同步、索引过期、暂停/撤销和查询错误，并保留查询节点、请求标识、观察时间和响应摘要。

22.8 按结构化条件发现

调用方按资源类型、主体类型、标签、协议、版本、状态和授权域组合条件查询，并明确字段编码、交集/并集关系、过滤顺序、分页和排序。发现服务节点先应用授权域和生命周期等硬条件，再进行标签、协议或文本相关性处理；不同接口的实际过滤顺序以其协议说明为准。结果中的标签匹配只说明检索条件满足，调用方仍需检查 DID、签名、凭证、发布证据、版本和端点。

22.9 按自然语言任务描述发现

调用方提交任务描述，例如“I need a tool that can search code repositories and summarize the project structure.”。发现服务节点或其语义组件从描述中提取能力、用例、资源类型、协议、标签和状态条件，再执行硬条件过滤与语义排序；当前实现可能使用词法、结构化或向量/混合路径，具体取决于部署配置。返回结果时应保留命中资源 DID、资源版本、来源和解释字段（接口提供时），语义相关性不是控制权或安全授权。

任务描述 -> 能力/用例提取 -> 标签与结构化条件 -> 发现查询 -> 命中理由

解释结果应区分文本、标签、结构化过滤和语义相关性来源。

22.10 调用前验证已发现资源

调用方从发现结果取得 DID 文档、资源包、根平台可信发布证明、注册 VC 和状态信息，依次验证 DID 解析、控制关系、凭证、发布证据、治理授权、版本和端点，再根据本地策略决定是否调用。发现结果是候选资源和证据入口，不是调用授权；验证失败、状态未知、证据过期或端点认证条件不满足时，应停止高风险调用，并记录停止原因。

• [ ] DID 和 DID文档验证通过。
• [ ] 资源包、版本和摘要一致。
• [ ] 注册 VC 与根平台可信发布证明可验证。
• [ ] 治理状态和新鲜度满足策略。
• [ ] 端点、认证和业务权限满足调用条件。

调用方不应把发现接口返回的候选对象直接作为最终调用对象。候选通常是 ResourceDiscoveryCandidate 的索引表示，完整 DID文档和资源包需要通过相应读取接口取得；内容分发平台的资源包读取返回 ResourcePackage，DID文档读取返回 DidDocument，元数据读取返回 ResourceMetadata。读取成功后，再将资源 DID、版本、三类哈希、注册 VC、根平台可信发布证明和治理状态放在同一验证上下文中核对。

22.10.1 DID 解析

解析完整资源 DID，确认方法为 did:oan，读取 DID 文档并校验 id、验证方法、控制关系、服务端点和资源元数据一致性。解析未找到、方法不支持、文档结构无效和状态异常分别处理，不能以任意同名 JSON 替代。

解析结果至少应带出以下字段，供后续步骤继续核验：

22.10.2 控制权验证

依据 DID文档中的验证方法和控制关系验证资源签名，确认签名覆盖的规范化内容、资源 DID、版本和前序关系。公钥与签名数学上一致不代表发布者有权控制另一个 DID，验证还必须绑定目标 DID 和既有控制关系。验证输入应来自当前取得的 DID文档和资源包，而不是只使用发现结果中经过截断的展示字段。

控制权验证应按以下顺序完成：

1. 从 DID 文档取得验证方法和公钥引用。
2. 确认公钥属于目标 DID 的控制关系。
3. 按声明的规范化规则重建签名输入。
4. 验证签名覆盖的 DID、版本、资源包摘要和前序关系。
5. 将验证结果与注册服务节点、根平台和发现服务节点返回的来源信息关联。

22.10.3 注册 VC 验证

验证注册 VC 的签发者、主体 DID、资源类型、版本或摘要、签名、有效期及吊销/暂停状态。VC 缺失或接口不返回 VC 时，按协议定义的未知或不完整处理，不能把页面提交成功文字当作凭证；注册 VC 只证明注册服务节点签发的登记事实，不自动证明根平台发布和发现索引已经完成。

22.10.4 根平台可信发布证明验证

验证根平台可信发布证明的签发者、目标资源 DID、资源包版本、包摘要、元数据摘要、发布序列和签名，并确认根平台自身授权状态有效。证明只覆盖其声明事实，不保证端点业务质量。

根平台可信发布证明验证结果应与注册 VC 分开记录。下面是验证结果记录示例，状态值用于说明验证阶段，不是固定接口响应：

{
  "resourceDid": "did:oan:<method-specific-id>",
  "registrationCredential": "verified|missing|invalid",
  "rootPublicationProof": "verified|missing|invalid",
  "governanceStatus": "active|suspended|revoked|unknown"
}

只有证明之间的目标 DID、版本和摘要相互一致时，调用方才可以把“已登记”和“已由根平台发布”作为连续证据使用；其中任一项缺失都不能由另一项代替。发布证明验证通过后，还要根据发现服务节点的索引时间和游标判断是否已经可查询。

22.10.5 治理状态检查

从可信治理状态来源检查节点授权、授权域、暂停或撤销事件及其新鲜度，记录链上位置、索引游标和检查时间。治理数据过期或来源不可用时，对敏感调用采取拒绝或人工复核，而不是默认通过。

治理检查至少输出以下判断，而不是只返回一个布尔值：

22.11 在保留 DID 的情况下更新资源

原控制方生成同 DID 的新 DID 文档或资源包版本，携带前序版本和内容摘要并使用既有控制关系签名。注册服务节点和根平台重新验证后产生新登记或发布证据，分发和发现节点按发布序列收敛；相同内容重复提交应幂等，未授权的新文档不得覆盖旧版本。更新完成的判定应同时看新版本发布证明、下游同步状态和查询结果，而不是只看注册接口再次返回成功。

22.12 暂停、撤销与恢复资源

资源暂停由控制者、治理或有效证据状态触发，撤销针对资源或版本，恢复需重新检查控制证明、凭证、发布证据和端点。各节点应按自身职责记录触发事实、处理时间和传播状态；发现结果中的状态是节点已同步到的状态，不一定等于刚发生的操作时间。网络超时或节点暂时离线不等于资源撤销；发现节点传播未完成时，应显示状态和新鲜度，保留历史证据。

stateDiagram-v2
    [*] --> active
    active --> suspended: 有效暂停事实
    suspended --> active: 有依据的恢复
    active --> revoked: 撤销事实
    suspended --> revoked: 撤销事实
    revoked --> [*]

22.13 接入第三方注册节点

第三方提交节点 DID文档、授权申请、授权域、公开端点和运行配置，完成身份、签名、接口、资源校验、安全边界和上游提交测试。通过后只获得明确范围的注册资格；节点运行中仍需检查授权状态、版本和失败重试，不能用一次验收永久替代治理状态。接入测试应使用隔离资源，并保存测试请求、响应、错误分支、授权范围和有效期，避免将测试资源误认为正式网络资源。

• [ ] 节点 DID文档、角色、端点和协议版本一致。
• [ ] 授权域与治理授权材料一致。
• [ ] 正向、负向、重试和恢复用例均有证据。
• [ ] 私钥和治理秘密未进入公开材料。

22.14 接入第三方发现节点

第三方发现节点获取节点身份、授权材料和发布源配置，先完成全量同步建立基线，再进行增量同步、摘要校验、版本选择、DID/结构化/语义查询、去重、新鲜度和降级测试。对外提供结果时保留来源、版本、索引时间和授权域，不能把本地排序改写为根平台发布事实；查询接口可用也不代表同步数据已经覆盖最新发布序列。

接入顺序为“全量建立基线 → 增量同步 → 注入重复/乱序/缺失 → 查询与去重 → 新鲜度和恢复验证”。本地排序只影响展示顺序。

22.15 通过网络观察治理事件

治理事件在链上产生后，由链下信任索引器按序读取并形成节点授权状态读模型，根平台和发现服务节点再依据同步状态执行策略。观察者应记录事件类型、链上位置、索引游标、投影时间和页面显示时间，区分链上事实与网站展示。latest_sequence 继续增长只能证明索引器在读取新事件；具体节点授权状态是否已经变化，还要核对对应事件是否进入读模型。

链上事件 -> 索引器游标 -> 授权状态读模型 -> 根平台/发现服务节点判断 -> 页面观察

22.16 解析并验证资源 DID

客户端先解析资源 DID 和 DID文档，再验证控制关系、资源元数据、服务端点、版本和相关发布证据。解析结果可以被 SDK 或本地验证器封装，但调用方仍应能取得原始文档、摘要和错误状态，以便审计和复核。解析成功只证明文档能够读取和通过结构检查，不能跳过资源包、凭证、根平台发布证明和治理状态检查。

建议输出 resolved、invalid、not-found 和 status-unknown 等可区分状态，避免所有失败都被压缩为空对象。

22.17 获取资源历史版本

调用方按 DID、版本或发布序列请求历史资源包及其 DID文档、摘要和证明，并明确其已替代、已撤销或仅供审计的状态。历史内容不得因可读取而自动恢复为当前可发现或可调用版本；当历史版本缺少对应发布证明或状态证据时，应标记为不可完整验证，而不是补用当前版本证明。

历史记录至少关联 DID、版本/序列、摘要、发布证据、当前状态和查询时间；“可读取”和“当前可调用”必须是两个字段。

22.18 处理不可用或数据过期的发现节点

调用方根据响应错误、节点健康、索引时间、游标和声明的新鲜度判断发现结果是否可用。可以先展示已有旧快照以改善体验，但必须标注时间和降级状态；对需要最新授权或版本的动作，应重新从可信来源验证，不能只依赖旧缓存。

22.18.1 发现节点不可用

发现请求超时、连接失败或返回明确服务错误时，记录节点和关联标识，按策略重试或切换其它授权发现服务节点。不可用表示基础设施状态，不自动表示资源撤销，也不能把空结果当作网络中不存在资源。

重试记录至少包含端点、请求标识、错误类型、次数、退避时间和最后已知索引时间；连接失败与合法空结果不可混淆。

22.18.2 返回旧快照

旧快照可用于有限只读展示，必须携带生成时间、来源和降级标识。它可以展示资源名称、类型、历史命中结果和上次索引时间，但不可单独用于判断当前授权、撤销状态、端点可用性或调用资格。若快照中的资源涉及调用、授权或敏感决策，应在动作前重新获取并验证当前 DID 文档、凭证、发布证明和治理状态；重新取得在线证据后，应以新结果覆盖快照，并保留新旧来源的时间关系。

{
  "source": "discovery-node",
  "snapshotAt": "<timestamp>",
  "stale": true,
  "usableFor": "read-only-display"
}

22.18.3 数据新鲜度判断

以索引时间、事件游标、上游最新序列和允许延迟判断新鲜度；latest_sequence 不增长可能是没有新事件，也可能是同步停止，需结合最近成功时间和错误证据判断。未知新鲜度不能默认为最新。

新鲜度报告应同时给出 indexedAt、lastSuccessfulSyncAt、latestSequence、cursor 和错误状态，不能只展示一个序列号。

22.18.4 切换其它发现节点

切换前确认候选节点的授权状态、端点和支持的查询 profile，并在结果中保留来源节点。来自不同节点的结果需要按 DID、版本、摘要和发布证据去重和交叉验证，不能简单拼接成同等可信结果。

切换检查单：

• [ ] 候选节点 DID、角色和授权状态有效。
• [ ] 查询 profile 和授权域满足调用方需求。
• [ ] 结果按 DID、版本、摘要去重。
• [ ] 冲突结果回到根平台发布证据核验。

22.18.5 恢复后的重新同步

节点恢复后从持久化游标或受信发布序列补齐缺口，重新验证受影响版本和撤销状态，再更新索引投影。恢复完成以游标追上允许范围、关键资源查询一致和错误告警恢复为判据，而不是进程重新启动。

恢复验证应至少抽查一条新增资源、一条更新资源、一条撤销或暂停资源和一条在故障期间未变化的资源，确认恢复过程没有只补齐数量而遗漏生命周期状态。

恢复完成判据可写成：

游标补齐 + 关键资源一致 + 生命周期重新过滤 + 错误告警恢复

参考来源