本章将 OpenAgenet (OAN) 的公开 HTTP API 组织为可实现、可测试的接口契约，覆盖官网后端、注册服务节点、根平台、内容分发平台、发现服务节点和链下信任索引器的公开及节点间调用。接口在浏览器、TypeScript SDK、社区技能包中的路径、字段和错误语义应保持一致。公开 API 只返回公开服务所需材料，不返回私钥、本地身份备份、数据库管理能力或访问统计后台数据；HTTP 成功也不自动表示资源已完成根平台发布、全网分发或发现索引。

15.1 API 约定与基础 URL

OAN 接口使用 UTF-8 编码传递 JSON，时间字段采用 RFC 3339 字符串，DID、版本、哈希和游标按字符串处理，不应被客户端转换为有损数字。生产环境基础 URL 由部署配置确定，协议规范只约束路径和语义，不把官网当前域名写成所有部署的固定条件。请求应携带能够贯穿一次调用链的请求 ID；响应应以稳定的机器可读字段表达结果，展示层文字不能作为程序判断依据。

15.1.1 服务基础地址

官网当前后端的公开基础地址与各节点地址由网站前端的 API 配置、节点配置和部署环境共同决定。SDK 提供注册服务节点、发现服务节点、根平台和内容分发平台的独立端点配置，调用方不得假定所有服务必然部署在同一主机或同一域名。跨节点请求还应记录目标节点 DID，避免仅凭网络地址判断通信对象。

15.1.2 路径和版本约定

路径中的版本应通过明确的路径、协议字段或能力协商表达，不能从页面标题或服务名称推断。兼容增加字段时，客户端应忽略未知非必填字段；改变字段含义、签名覆盖范围或状态语义时必须提高协议版本或提供迁移期。接口路径、方法和媒体类型构成契约的一部分，大小写和尾部斜杠差异不得由客户端自行猜测。

15.1.3 请求认证

公开查询和健康接口可以按部署策略匿名访问；资源注册、节点间提交和治理操作分别需要资源控制证明、节点授权材料或运维认证。浏览器的 CORS 许可只决定页面是否能够读取响应，不授予资源控制权。认证失败应返回稳定错误，不应通过模糊的 404 或成功空结果掩盖权限问题。

15.1.4 响应格式

成功响应应使用 JSON 对象表达数据、状态、版本、新鲜度或来源；错误响应应至少包含机器可读错误码、请求 ID 和必要的字段定位。服务不得把 HTML 错误页当作 JSON 返回。对于异步发布和索引，响应应明确区分已受理、处理中、已完成和失败，不能用 HTTP 200 单独表示全链路完成。

15.2 健康、就绪与服务状态端点

健康检查应区分进程存活、服务就绪、关键依赖可用和业务烟测通过。官网后端的 /health 只能说明后端进程能够响应，不能证明注册服务节点、发现服务节点、根平台或数据库均正常。运维部署完成后，应分别检查节点健康、数据库连接、索引器同步状态，以及注册和发现最小业务路径；对外状态接口应避免泄露内部连接串、令牌和堆栈。

15.3 注册节点注册端点

参考实现同时接受 POST /resources/register 和兼容入口 POST /resources/submit，二者进入同一资源登记处理函数。浏览器或 SDK 在本地生成资源 DID、DID文档、元数据、版本与摘要，并以 ResourceRegistrationSubmission 提交；私钥和本地身份备份不属于请求正文。注册服务节点先检查结构、资源类型、授权域和主体控制证明，再以签名上游请求调用根平台的验证发布接口。

当前成功响应的核心字段如下，示例值仅用于说明结构：

{
  "status": "submitted",
  "resourceDid": "did:oan:SKLG:example",
  "resourceType": "skill",
  "registrationCredential": {},
  "rootResponse": {}
}

status: submitted 表示注册服务节点已完成本次处理并取得根平台响应，不等于内容分发和所有发现服务节点索引完成。参考实现会签发并返回 registrationCredential；客户端仍应允许凭证字段为空或无法解析时保留提交结果和原始响应，以便区分“登记失败”与“凭证缺失”。GET /resources、GET /resources/{did}、GET /registrar/status 和 GET /registrar/stats 用于读取注册记录及节点状态，但公开范围仍由部署的反向代理和访问策略决定。

15.4 根平台发布与状态端点

根平台将公开读取路由与管理写入路由分开。资源发布入口为 POST /root/resources/verify-and-publish，由注册服务节点调用并携带 upstreamAuth；根平台重新验证来源节点身份、节点授权、资源 DID、DID文档、摘要和控制证明。资源查询使用 GET /root/resources/{did}，历史版本列表和指定版本分别使用 /root/resources/{did}/versions 与 /root/resources/{did}/versions/{version}。

发布接口成功表示根平台接受并保存了符合要求的资源版本，随后由内容分发发布器和发现通知任务继续处理。调用方应通过资源版本、发布队列或后续状态确认传播进度，不能把根平台的一次 2xx 响应解释为全网可见。

15.5 内容分发端点

内容分发平台对外提供单资源读取、批量读取、增量索引和拆分材料读取：GET /cdn/resources/{did} 返回资源包，POST /cdn/resources/batch-get 按 DID 批量读取，GET /cdn/documents/{did} 与 GET /cdn/metadata/{did} 分别返回 DID文档和元数据。目录类接口位于 /cdn/catalog/...。根平台发布器使用受保护的 POST /cdn/resources 或 POST /cdn/resources/batch 写入；POST /cdn/purge 属于管理操作，不应作为公开写入接口暴露。

增量同步使用 GET /cdn/resources/index?afterCursor=<n>&limit=<n>。当前参考实现未传参数时可返回兼容格式；传入游标或数量参数时返回结构化页面：

{
  "items": [],
  "count": 0,
  "afterCursor": 42,
  "nextCursor": 42,
  "hasMore": false
}

发现服务节点应在完整校验本批资源包后保存 nextCursor，不能因 HTTP 请求成功就提前推进。当前服务对批量发布请求设置了实现层 body 上限，该数值属于参考实现的部署保护，不是所有 OAN 节点永久固定的协议值。

15.6 发现查询与资源详情端点

发现查询入口为 POST /discovery/resources/query，请求类型允许使用自然语言描述、资源类型、能力标签、协议、版本、版本模式和数量限制。若查询文本可识别为完整资源 DID，参考实现优先执行精确 DID 查询；否则优先使用可用的语义索引，并在语义后端不可用或无结果时回退到关键词候选流程。响应中的 discoveryDid 表示本次返回结果的发现服务节点，createdAt 表示响应生成时间，候选项的 score 只表达检索相关性。

{
  "query": "I need a tool that can search code repositories and summarize the project structure.",
  "resourceType": "skill",
  "capabilityTags": [],
  "versionMode": "latest",
  "limit": 10
}

索引资源读取和诊断接口包括 /discovery/index/resources、/discovery/index/resources/{did}、/discovery/index/stats 与 /discovery/query/stats；它们是否对互联网公开，应由部署暴露策略确定。空候选数组是有效查询结果，不应转换为网络错误；语义后端回退、索引滞后或快照降级应在可观测信息中体现，不能制造重复候选来掩盖数据源差异。

15.7 DID 解析端点

基础设施节点分别通过 GET /registrar/did、GET /root/did 和 GET /discovery/did 返回自身 DID文档。资源 DID 的解析可通过根平台资源详情、内容分发平台的 /cdn/documents/{did}，或发现服务节点已经索引的资源详情取得，具体选择取决于调用方需要的是权威保存版本、分发副本还是发现读模型。

解析响应中的 id 应与请求 DID 完全一致，并保留公开验证方法、验证关系、服务端点和 OAN 元数据。客户端需要区分三类结果：DID 格式非法属于请求问题，资源不存在属于无记录，依赖或节点暂时不可用属于可恢复故障。任何解析路径都不应返回浏览器本地身份备份、私钥或服务端密钥文件。

15.8 VC 与证明获取端点

注册 VC、节点授权 VC 和根平台可信发布证明覆盖不同事实。注册服务节点在登记成功响应及资源记录中保存 registrationCredential；根平台可通过资源详情和版本接口返回资源包及其根平台可信发布证明；注册服务节点和发现服务节点的 /.../root-authorization 状态接口用于展示其根平台授权材料或验证状态。根平台的基础设施授权 VC 签发入口属于受保护操作，不应被当作匿名自助获取接口。

接口返回凭证对象不等于凭证已经验证。调用方应根据 proof.verificationMethod 解析签发者公钥，并检查凭证时间和治理状态；无法取得状态时，应明确返回“不确定”或收紧高风险操作，而不是默认为有效。

15.9 治理状态与事件端点

根平台通过 /root/registrars、/root/discovery-nodes 及其 DID 详情接口提供基础设施节点目录，通过 /root/bulletin/events 和 /root/bulletin/events/{sequence} 提供治理事件读模型。注册服务节点与发现服务节点分别通过 /registrar/root-authorization、/discovery/root-authorization 暴露本节点观察到的授权状态；发现服务节点还通过 /discovery/authorized-domains 表达当前授权域。

链下信任索引器的数据属于链上治理事实的链下投影，状态响应应携带最新序列、观察时间或同步位置，使调用方能够判断新鲜度。根平台的授权、授权域更新和撤销接口属于管理路由，需要管理员认证。若链上读取失败、索引序列长期不增长或本地状态无法确认，根平台和发现服务节点应将结果标记为陈旧或不确定，并收紧发布、同步或发现可见性判断。

15.10 指标与可观测性端点

官网后端将多个节点和数据源整理为 /api/public/home/summary、/api/public/network/summary、/api/public/network/governance-events、节点目录与节点统计等公开读接口。节点侧另有 /registrar/stats、/discovery/index/stats、/discovery/query/stats、/cdn/catalog/resources/stats 等角色相关统计。官网汇总结果是展示读模型，不应被当作替代各节点原始状态的权威接口。

指标字段应同时给出生成时间、统计窗口、来源和缺失状态。TODAY、THIS WEEK、THIS MONTH 等窗口需要采用同一时区与明确起止边界；累计资源数不能和窗口新增量混为一项。公开接口只返回必要的聚合信息，访问统计明细、完整日志、数据库路径、管理令牌和内部错误堆栈仍属于运维数据。节点向官网汇报统计使用内部上报入口，其认证与暴露范围应独立于公开读取接口。

15.11 请求与响应模式

请求和响应应至少能表达成功、处理中、失败和不确定四类结果：

status = accepted | processing | completed | failed | unknown
requestId = 用于跨节点追踪一次调用

客户端必须按机器可读状态判断异步阶段，不以 HTTP 200 或页面提示单独推断发布、分发和发现已经完成。

请求和响应模式是接口字段、状态和错误的稳定边界。字段的存在性、类型、枚举、哈希算法、时间格式、DID 语法和嵌套关系应与 oan-protocol-common 及节点实际类型一致。对未知字段的处理应按协议版本确定；对缺失必填字段、重复字段、空值和不兼容版本应返回可定位的错误。

核心节点接口的实际类型关系如下。表中的 Value 表示当前 handler 返回动态 JSON，并不表示任意字段都构成稳定契约；具体字段仍需以对应 handler、共享结构和错误测试共同核对。

接口的业务阶段不能仅由 HTTP 状态码推断。注册服务节点返回 submitted 时，登记记录已写入；根平台返回 resource-verified-and-queued 时，资源已通过根平台当前验证并进入分发队列；内容分发平台返回 published 时，资源包已在分发平台写入；发现响应返回候选时，只表示当前发现节点的索引可见。调用方仍需按资源 DID、版本、哈希、根平台证明、治理状态和新鲜度完成后续判断。

15.11.1 注册请求与响应

注册请求至少关联资源 DID、DID文档、资源类型、元数据、资源包、版本、哈希、注册服务节点和控制证明。服务端应在验签前确认请求路径、目标、挑战、nonce 和内容摘要，验签后再执行重复判断和写入。响应应分别表达登记受理、注册 VC、根平台提交结果和可重试错误，不能让客户端从一条“success”文字推断所有阶段完成。

参考实现的公开登记入口直接接收 ResourceRegistrationSubmission；注册服务节点向根平台转发时再构造 ResourceVerifyAndPublishRequest，并在 upstreamAuth 中绑定方法、路径、目标、时间、nonce 和业务正文哈希。浏览器只提交资源材料与控制证明，不应自行构造或持有基础设施节点的上游签名身份。

15.11.2 发布请求与响应

发布请求至少关联注册服务节点来源、资源版本、资源包摘要、DID文档哈希、元数据哈希、授权材料和请求 ID。发布响应应携带根平台可信发布证明或明确说明其尚未产生，并返回发布状态、批次或游标引用。哈希不一致、节点无权、控制证明无效和依赖暂时不可用应分为不可重试失败与可重试失败。

根平台向内容分发平台提交时，单条和批量请求分别使用 ResourceCdnPublishRequest 与 ResourceCdnBatchPublishRequest，批量条目以 publicationCursor 关联根平台发布顺序。响应中的接受数量、失败条目或完成游标用于发布任务恢复，不代表发现服务节点已经完成索引。

15.11.3 发现请求与响应

发现请求可以使用资源 DID、资源类型、能力标签、协议、授权域、生命周期、关键词或自然语言任务描述。响应应返回候选 DID、版本、资源类型、匹配原因、来源发现服务节点、索引版本、治理状态和证明引用；分页游标必须绑定查询条件和排序快照。空结果不是接口失败，服务不可用、索引滞后和快照降级应被明确标记。

当前 ResourceDiscoveryResponse 包含 discoveryDid、candidates、createdAt 和可选 proof。候选项包含资源 DID、资源类型、得分、版本、生命周期、能力标签、授权域、服务端点、协议绑定、资源包信息和根平台证明等字段；可选字段缺失时，客户端不能用展示层默认文本补造可信事实。

15.11.4 状态和错误响应

状态和错误响应使用 HTTP 状态码表达粗粒度结果，JSON 错误码表达业务原因，requestId 表达追踪关联。错误中可包含字段路径、是否可重试、建议等待时间和当前处理状态，但不得回显私钥、完整控制证明或内部异常堆栈。客户端应保留原始错误以便审计，同时向用户提供与敏感程度相称的说明。

当前多个 Rust 节点的错误正文采用简洁结构 {"error":"machine_readable_reason"}，并由 HTTP 状态码区分请求错误、权限错误或服务错误。并非所有现有响应都已经包含 requestId、字段路径和重试提示，因此这些字段属于接口一致化时应补齐的方向，调用方不能假定当前每个节点都会返回完整错误包络。

15.12 HTTP 状态码与常见错误

建议使用 2xx 表示请求已按接口语义处理，4xx 表示请求、认证、授权或业务前置条件不满足，5xx 表示服务端或依赖异常。202 Accepted 只能表示异步任务已受理，不能表示发布完成；409 Conflict 可用于同 DID 版本冲突或重复状态需要客户端确认的场景；429 Too Many Requests 应配合限流信息。各服务应避免为相同业务原因随意返回不同状态码。

客户端应首先判断 HTTP 状态，再解析 JSON 中的 error 或业务状态。连接失败、TLS 失败和浏览器 CORS 拒绝没有可用的 HTTP 响应，不能统一显示成“服务器返回 500”；对仅支持 GET 的端点发送 POST 时，路由层通常返回 405 Method Not Allowed，应优先核对调用方法和反向代理转发规则。

15.13 速率限制、缓存与安全请求头

限流应至少考虑来源 IP、认证主体、节点 DID、资源 DID和接口类别，并对注册、发现、同步和健康请求使用不同配额。只读公开查询可以使用短时缓存，但 DID文档、VC、根平台证明、治理状态和发现结果必须带有版本或新鲜度边界。条件请求的 ETag 必须对应响应内容版本；安全请求头、内容类型检查和响应体大小限制应在网关或服务层落实。

当前节点代码中的请求体限制、查询数量边界和 CORS 配置属于第一层保护，生产部署还需由反向代理承担连接数、速率、超时和请求大小控制。缓存测试至少应验证：首次请求取得数据和新鲜度信息，条件请求不会返回错误版本，治理撤销后旧缓存不会继续授权写入，后端不可用时旧快照被明确标记而不是伪装成实时结果。写入接口和带签名请求不应由共享缓存保存。

15.14 CORS、浏览器客户端与跨源策略

浏览器调用节点 API 时，服务端只允许必要的官网来源、方法和请求头，预检请求不得放宽业务授权。不得使用 Access-Control-Allow-Origin: * 配合凭据传递敏感材料。公开官网跨源读取与节点间认证是两层控制：前者服务浏览器安全模型，后者验证请求主体和权限。CORS 配置变化应作为部署检查项，避免前端出现难以区分的 Failed to fetch。

注册服务节点、发现服务节点和内容分发平台均从配置构造 CORS 层；官网后端优先使用配置的前端来源，在配置值无法解析时才退回更宽松策略。生产环境应避免触发该退回分支，并在部署后分别从中文和英文页面执行注册、发现及预检烟测。浏览器显示 Failed to fetch 时，应依次核对请求 URL、HTTPS 混合内容、证书、DNS、反向代理、预检响应和允许来源，不能只检查后端业务日志。

15.15 公开端点与仅限运维端点的边界

公开边界按“公开读取、资源控制者签名、节点间授权、运维专用”划分。公开接口可以提供健康、公开目录、已发布资源和有限指标；资源控制者接口接收控制证明但不接收私钥；节点间接口要求节点身份、授权 VC 和请求签名；运维接口只在受控网络或认证边界内开放。访问统计数据只能由后台或运维授权主体读取，普通访客不应通过网站页面或公开 API 查询明细。

15.15.1 公开查询接口

公开查询接口包括公开目录、发现查询、已发布资源详情、公开 DID文档、公开证明和健康信息。返回数据应经过字段白名单处理，隐藏本地文件路径、私有端点、数据库管理字段和未公开凭证。公开查询仍需遵守生命周期、治理过滤和授权域可见性，不能因为接口匿名就绕过这些判断。

官网 /api/public/... 路由主要承担聚合展示，不等于将所有节点路由自动公开。部署时应建立公开路径白名单，并验证匿名访问只能读取经过筛选的数据。用于记录页面访问的 POST /api/public/site-analytics/visit 是单向采集入口，不提供统计明细读取能力。

15.15.2 节点间接口

节点间接口用于注册服务节点、根平台、内容分发平台、发现服务节点和链下信任索引器之间的协作。请求应携带来源和目标身份、授权材料、协议版本、请求 ID、时间窗口、nonce、内容摘要和签名。节点间接口不应由官网浏览器直接代替调用，浏览器提交资源应经过注册服务节点的公开入口和服务端校验。

典型节点间写入包括注册服务节点调用 /root/resources/verify-and-publish、根平台发布器调用 /cdn/resources/batch，以及根平台向发现服务节点发送授权范围内的同步通知。即使路径能够从互联网连通，接收方仍应验证可信上游包络和节点授权；网络可达性本身不是授权依据。

15.15.3 运维接口

运维接口包括部署状态、内部诊断、访问统计明细、数据库管理、密钥轮换和恢复操作。它们不得出现在公开 API 目录或浏览器端代码中，应使用独立认证、最小权限、审计日志和网络隔离。运维接口返回的错误也不得被公开代理完整透传给普通用户。

根平台的授权、撤销和发布管理路由，以及官网内部节点统计上报入口，均应在反向代理层与公开读取路由分开。服务代码中将路由合并到同一进程并不意味着它们应共享相同的互联网暴露策略；运维人员应同时核对应用认证和代理路径白名单。

15.15.4 访问控制和暴露边界

访问控制应同时检查路由、方法、认证主体、节点角色、授权域和资源范围；暴露边界应通过端口、反向代理和 CORS 配置共同落实。发布前应从匿名浏览器、资源控制者客户端、未授权节点和运维主体四类身份分别测试允许与拒绝路径，并保存状态码、响应字段和日志关联证据。

15.16 API 示例与机器可读接口描述

openapi: 3.1.0
info:
  title: OAN Agent Contract
  version: 0.1.0
paths: {}

上例是当前 oan-protocol-common/schemas/agent-contract/openapi.yaml 的实际骨架。它标明 OpenAPI 版本和契约文件版本，但 paths 仍为空，因此只能作为机器可读契约入口，不能当作已经覆盖全部公开及节点间 API 的完整描述。接口核对应以各服务 Router 定义、共享协议结构、配置和部署代理规则共同为准。

面向使用者的最小可执行示例应从无需签名的健康或公开查询开始。例如以下命令中的主机名是占位值：

curl --fail-with-body \
  --header "Accept: application/json" \
  "https://registrar.example/health"

注册、根平台发布和内容分发写入示例还需要真实生成的 DID、摘要、控制证明或节点间签名包络，不能用静态假签名冒充可执行请求。后续完善 OpenAPI 描述时，应逐路由补齐方法、请求体、响应、认证、错误和示例，并通过自动化测试检查描述与实际路由是否同步。

参考来源