本章是本技术手册的阅读入口，面向资源提供方、节点运营者、客户端和 SDK 开发者、协议实现者、集成开发者以及需要评估 OpenAgenet (OAN) 的技术人员。手册覆盖智能体服务、技能包、MCP 服务和工具 API 等资源，也覆盖主体身份、资源 DID、DID 文档、注册 VC、根平台可信发布证明、内容分发、发现索引和调用前验证等支撑机制。读者可以把它作为一份从概念到实现的导航：先通过第 1 至第 4 章理解目标、角色、架构和资源模型，再按需要进入身份、注册、发布、发现、运维和符合性章节。

手册中的内容需要区分四种状态：设计依据说明为什么这样设计；当前系统事实说明现有代码、接口或部署已经表现出的行为；参考实现说明 OAN 代码仓采用的一种实现方式；运行证据说明某个环境在特定时间的构建、部署和烟测结果。规范性要求只在需要保证互操作、安全或数据完整性时使用，不能把官网展示、示例配置或一次部署结果扩大解释为所有节点的强制能力。后续章节引用接口、代码或运行数据时，应明确其证据类型和适用范围。

{
  "manual": "technical manual",
  "scope": ["resource identity", "registration", "trusted publication", "discovery", "governance"],
  "evidence_types": ["design", "current-fact", "reference-implementation", "runtime-evidence"],
  "status_rule": "每项结论都应说明来源、适用范围和核验时间"
}

本手册把材料分为设计依据、规范规则、实现证据和运行证据。设计依据解释目标和取舍；规范规则说明互操作底线；实现证据说明代码如何落实；运行证据说明特定环境在特定时间是否正常。四类材料可以互相引用，但不能跨层级替代。发布或审查时，应记录手册版本、引用材料版本、实现提交、配置版本、测试时间和适用环境。

flowchart LR
    A[设计依据] --> B[手册说明]
    B --> C[实现证据]
    C --> D[运行证据]
    D -.发现差异或问题.-> B
    B -.需要修订设计.-> A

目的与规范范围

手册覆盖一条资源从本地准备到被发现和验证的完整路径：资源提供方准备资源和本地身份，客户端向注册服务节点提交材料，注册服务节点完成接入校验，根平台验证并发布可信资源包，内容分发平台承载可获取材料，发现服务节点同步并建立索引，调用方在连接前检查 DID、凭证、版本和治理状态。对应章节分别解释资源模型、did:oan、DID 文档、资源包（ResourcePackage）、VC/VP、签名消息、节点授权、语义标签、公共 HTTP API、SDK、社区 Skill、生命周期、运维和符合性。

手册不规定智能体内部采用何种模型或推理算法，不规定业务系统的全部业务逻辑，也不替代 A2A、MCP 等外部协议本身。每个章节应说明适用角色、输入输出、责任主体、验证主体、状态变化、异常处理和可留存证据；如果某个结论只适用于参考实现或当前部署，应明确标注版本、环境和边界。

与 OAN 白皮书和黄皮书的关系

白皮书是项目的概念入口，主要回答为什么建设面向智能体互联网（Internet of Agents，IoA）的资源身份、可信发布和语义发现基础设施；黄皮书更关注机制如何工作，解释角色、数据对象、信任边界、发布链路、授权域、状态机、安全不变量和参考验证方法；本手册则把这些材料组织成读者能够查阅和使用的技术说明，补充实现映射、示例、操作边界和验证路径。

阅读时可以从白皮书了解“为什么”，从黄皮书了解“如何组织机制”，再回到本手册查找“如何理解、接入、实现和验证”。如果不同材料只是抽象层级不同，应在手册中说明层级关系；如果确实存在字段、流程或安全边界冲突，应记录冲突位置、影响范围、适用版本和修订状态，不能用模糊表述掩盖。

flowchart LR
    A[白皮书：目标与原则] --> B[黄皮书：机制与边界]
    B --> C[统一技术规范：可执行规则]
    C --> D[代码与测试：实现证据]
    D --> E[部署与运行记录：环境证据]
    E -.反馈修订.-> C
    D -.发现偏差.-> C

发布或审查时，应至少记录规范版本、引用材料版本、实现提交、配置版本、测试时间和适用环境。若材料之间出现差异，先区分是抽象层级不同还是实际冲突；只有后者才进入冲突记录和修订流程。

与 did:oan 方法规范的关系

did:oan 方法材料负责方法特定 DID 的语法、方法特定标识符、DID 文档结构、验证方法、公钥表达、服务端点、解析行为和控制权证明边界。本手册的相关章节不重复发明这些方法规则，而是解释 OAN 如何使用它们：客户端如何生成和保存本地密钥，资源控制方如何证明控制关系，注册服务节点如何校验 DID 文档，根平台如何把资源版本与可信发布记录关联，发现服务节点如何建立可验证索引，调用方如何在连接前解析和验签。

一个最小的状态判断可以表示为：

DID 文档有效
    -> 资源控制证明有效
    -> 注册服务节点受理
    -> 根平台发布
    -> 发现服务节点索引
    -> 调用方完成版本、治理和本地权限检查

上述步骤不是同一个“可用”状态的不同名称。DID 文档在语法、结构和签名上有效，不代表资源已经被注册服务节点受理、被根平台发布、被发现服务节点索引或获得调用许可；根平台的发布事实也不能替代调用方对 DID 文档、VC、端点、版本、治理状态和本地业务权限的检查。后续章节应通过字段、流程和状态说明它们如何衔接。

与实现仓库和部署文档的关系

手册中的实现映射用于帮助读者回答“这项能力在哪里实现、如何验证、当前有什么边界”，而不是把仓库名称当作符合性证明。共用数据结构、序列化、哈希和密码学行为优先核对 oan-protocol-common；根平台发布、治理状态和发布证明核对 oan-root-services；注册接入和注册凭证核对 oan-registrar-node；同步、索引、语义检索和发现响应核对 oan-discovery-node；链上治理事件到运行时授权读模型的投影核对 oan-trust-indexer；客户端集成核对 oan-sdk-ts 与社区 Skill。README、schema、路由处理器、测试、配置样例和部署脚本承担的证据作用不同，应在引用时说明用途。

mapping:
  manual_section: "第 8 章 注册协议"
  repository: "oan-registrar-node"
  evidence: "路由处理器、请求校验、集成测试"
  status: "已实现并有测试证据"
  checked_at: "YYYY-MM-DD"
  boundary: "具体提交和部署配置以目标环境为准"

每项映射至少应记录章节、仓库和模块或文件、对应版本、实现状态、验证方法以及已知偏差。实现状态应区分已实现并有测试证据、已实现但证据不足、部分实现和仅有设计；部署材料还应记录环境变量、外部服务、数据库、密钥边界、构建产物、启动顺序和部署后烟测。官方环境的地址、节点数量和运行指标属于运行证据，不应写成所有环境的必需条件。

规范性语言与符合性术语

本手册沿用 RFC 风格关键词来标识强制程度：MUST 对应“必须”，MUST NOT 对应“不得”，SHOULD 对应“应”，SHOULD NOT 对应“通常不应”，MAY 对应“可以”。这些词只在已经确认的互操作、安全、数据完整性或符合性要求中使用；描述当前代码行为、部署现状或操作建议时，应改用“当前实现”“通常”“建议”“可以”等更准确的说法。

符合性判断应针对具体角色和配置文件，而不是对整个 OAN 做笼统评价。资源提供方、注册服务节点、根平台、内容分发平台、发现服务节点、链下信任索引器、解析器和 SDK 的能力边界并不相同。每项测试或运行检查应说明固定输入、前置配置、执行步骤、预期输出、失败影响和证据保存方式；参考实现通过测试不等于所有第三方实现天然符合，官方部署运行正常也不等于协议覆盖所有环境。

• [ ] 已说明本条内容属于规范要求、参考实现、当前部署还是待实现能力。
• [ ] 已给出能够复核的来源、版本或提交信息。
• [ ] 已区分资源登记、根平台发布、发现索引和调用前验证的证据。
• [ ] 已说明偏离规范或实现失败时的影响范围和处理方式。

参考来源