本附录采用“规范条款 -> 数据结构/接口 -> 实现文件 -> 测试证据 -> 部署配置 -> 维护责任”的链路描述实现，而不把仓库名称本身当作功能证明。当前核心运行实现由共享协议库、根平台、注册服务节点、发现服务节点、内容分发组件和链下信任索引器组成；SDK、社区技能包和官网是客户端与公共入口；第三方节点准入测试套件是独立测评支持，不是生产运行节点。oan-onboard-tests 和根目录 genesis 在当前工作区中不是可直接核对的独立目录，因此涉及它们的历史引用只能视为资料来源约定，不能作为当前实现证据。

映射状态使用以下含义：

每项实现事实应同时记录来源版本和验证时间。对于输入，说明它如何转换成校验条件、授权域过滤条件或查询条件；对于输出，说明它是原始事实、验证结果、缓存投影、搜索排序还是展示摘要；对于根平台可信发布证明、VC、签名和治理状态，必须保留签发者、验证者、绑定内容和状态来源。能力标签、语义相关性、A2A Agent Card 或 MCP 元数据只描述或辅助发现能力，不能替代控制权和治理验证。 映射记录至少应区分三种证据：源码证据说明逻辑和字段在哪里定义，测试证据说明该逻辑在固定输入下得到什么结果，运行证据说明指定环境中的服务、配置和依赖实际能够完成什么。三者分别回答“写了什么”“测过什么”和“运行了什么”，不能用 README、一次编译成功或一个健康接口相互替代。对于动态数据，还应记录证据生成时的提交、配置摘要、数据库/索引状态和请求关联标识。

F.1 oan-protocol-common

该仓是 Rust workspace 级共享基础，主要映射第 4 至第 8 章、第 15 章和附录 A 至 C。crates/oan-core 承载 DID文档、资源类型和核心领域对象；oan-crypto 负责密码套件、密钥和哈希相关逻辑；oan-credentials 负责凭证构造或验证；oan-package 负责资源包及其绑定；oan-protocol 负责跨节点请求、响应和协议常量；oan-publication-events 负责发布事件；oan-storage 提供 JSON、SQLite 或 PostgreSQL 存储抽象；oan-service-security 提供请求信封、nonce、request ID 和签名相关公共逻辑；oan-semantic-recommender 及其 data 目录提供能力标签树、授权域分类和推荐/规范化辅助。

共享库的维护责任是保持跨节点数据结构、序列化、错误码和密码学绑定的一致性；任何字段变更都应同步检查根平台、注册服务节点、发现服务节点、SDK、社区技能包和固定 fixture。共享库没有权限代替上层服务决定节点授权、资源发布或业务调用。

从 HTTP 接口向下追踪时，可以按实现链定位契约：注册服务节点的 services/registrar-node/src/main.rs 将 /resources/register 和 /resources/submit 绑定到 register_resource，根平台的 services/root-node/src/main.rs 将 /root/resources/verify-and-publish 绑定到 verify_resource_and_publish，发现服务节点的同名服务目录将 /discovery/resources/query 绑定到 resource_query，内容分发平台的 services/cdn-node/src/main.rs 负责 /cdn/resources、批量发布和资源读取，链下信任索引器的 src/api.rs 负责 /v1/status、/v1/events 等读接口。handler 签名是确认输入与输出类型的直接证据，路由表是确认 HTTP 方法和路径的直接证据。

维护接口时应把“共享 DTO 变更”和“动态响应字段变更”分开记录：前者需要检查 oan-protocol、oan-package、所有反序列化调用方和跨语言 SDK；后者需要检查生成 JSON 的 handler、错误码测试、公开代理和附录 B 的端点表。Rust 编译通过只能证明类型层可编译，不能证明 JSON 字段、HTTP 路径、认证边界和异步状态语义仍与对外文档一致。 维护人员定位一个共享字段时，应按“领域结构 -> 序列化实现 -> 调用方 -> fixture”顺序核对。例如，资源包字段先在 oan-package 的结构和校验方法中确认，再检查 oan-protocol 的请求/响应类型、注册服务节点和发现服务节点的反序列化路径，最后用资源 fixture 验证缺失、篡改和版本冲突时的行为。只修改某个节点能够编译，并不能说明跨仓协议已经兼容；至少还要检查对应 SDK 导出和社区技能包的输入输出。 当共享库中的字段发生变化时，维护人员应先判断变化属于序列化兼容、校验语义变化还是纯内部实现变化。序列化字段、枚举值、错误码和哈希计算方式属于跨仓影响面；即使 Rust workspace 内部编译通过，也要继续核对节点 HTTP 载荷、TypeScript 类型、社区技能包脚本和准入测试夹具。若只改变内部辅助函数且外部载荷与错误行为不变，则应保留相应单元测试作为边界证据，不必扩大协议版本范围。

F.2 oan-root-services

该仓对应第 3 章、第 9 至第 10 章、第 13 至第 15 章及相关生命周期、分发和运维章节。根平台主服务位于 services/root-node/src/main.rs，其路由包括根 DID文档、状态、注册服务节点和发现服务节点目录、资源详情与版本、能力标签树、公告/事件、授权、撤销以及面向内容分发和发现服务节点的内部接口。services/cdn-publisher 负责消费发布任务、从根平台准备资源包、向 CDN 批量发布并回写发布结果；services/cdn-node 负责内容分发平台的数据面服务。配置样例位于各服务目录的 config.example.toml。

根平台实现的责任边界可按以下方式核对：

根平台维护者还需关注幂等、版本冲突、发布重试、队列积压、数据库备份和治理状态失联等运行边界。根平台签发根平台可信发布证明，只证明其验证和发布范围内的事实；不证明资源端点业务质量，也不持有资源控制私钥。 根平台代码排查应把公开查询路由和内部写入路由分开记录。/root/resources/{did}、版本查询和能力标签查询属于读路径；注册服务节点提交、节点授权、撤销、内容分发队列和发现服务节点通知属于受保护的写或协调路径。维护人员在修改 services/root-node/src/main.rs 时，应同时核对 services/cdn-publisher/src/main.rs 对发布任务的消费、services/cdn-node/src/main.rs 对资源包的读取，以及根平台配置中的队列、数据库和上游端点；不能仅凭根平台 HTTP 响应判断内容已经完成分发。 根平台变更的核对重点是发布事实何时产生。维护人员应分别记录注册服务节点提交时间、根平台验证结果、资源版本与哈希、根平台可信发布证明、内容分发任务状态和发现服务节点通知状态；只有通过根平台验证并形成发布事实，后续分发和发现链路才有可引用的根来源。根平台的查询接口、内容分发平台的缓存和发现服务节点的索引条目应作为不同证据保存。

F.3 oan-registrar-node

该仓主要对应第 5 至第 8 章、第 15 章和资源生命周期部分。实现入口为 services/registrar-node/src/main.rs，当前路由包含 /health、/registrar/did、/resources/register、兼容的 /resources/submit、资源列表与详情、状态、统计、根平台授权、能力标签树、标签建议、标签规范化、注册域目录和注册建议。配置样例位于 services/registrar-node/config.example.toml，数据目录、密钥目录和可选 SQLite/PostgreSQL 数据库由配置解析后确定。

注册服务节点处理链路是：

资源控制方提交公开材料和控制证明
  -> 形状、DID、资源类型、元数据和授权域校验
  -> 构造面向根平台的签名请求
  -> 接收根平台验证/发布响应
  -> 生成并保存注册 VC 与登记记录
  -> 向调用方返回登记结果和根平台响应

这里的注册 VC 由注册服务节点针对登记事实签发，不能代替根平台可信发布证明；根平台拒绝时，Registrar 不应把本地受理作为全网发布。注册服务节点可以看到资源公开材料、公钥、签名和凭证，但正常流程不应取得资源控制私钥。oan-third-party-node-admission-test-kit/fixtures/v1-alpha/resources 提供 DID、资源类型、授权域、VC 主体、哈希、控制挑战、证明完整性和生命周期等固定验证样例；SDK 与官网测试覆盖客户端调用形状，但不取代 Registrar 的服务端校验。

维护重点是保持 /resources/register 与协议类型的字段一致、明确错误码和 HTTP 状态、确保上游失败不造成假成功、避免重复提交产生冲突记录，并同步更新配置样例、公共错误文档、SDK 和社区技能包。 注册问题的定位应沿请求关联关系展开：先在 register_resource 的输入校验和错误转换处确认请求是否被本地拒绝，再检查面向根平台的 ResourceVerifyAndPublishRequest 是否正确构造，最后对照注册记录、VC 和根平台响应判断是否只是受理成功。一个可复用的排查记录至少保留资源 DID、请求标识、版本、错误码、上游状态和数据库写入结果；不要用“页面显示成功”替代节点之间的实际结果。 注册服务节点的实现映射还应标明每个结果属于哪一层：本地请求校验、注册记录写入、向根平台提交、注册 VC 返回和根平台发布结果不能合并为一个“注册成功”。对网络超时或响应不完整的重试，应使用原请求的关联信息核对服务端是否已经产生登记事实；只有确认幂等条件和最终状态后，客户端才能决定是否再次提交。

F.4 oan-discovery-node

该仓对应第 3 章、第 6 章、第 10 至第 12 章、第 14 至第 15 章及新鲜度和生命周期要求。services/discovery-node/src/main.rs 提供节点 DID、状态、授权域、同步历史、索引统计、查询统计、资源索引、资源查询、查询建议、查询解释、拒绝包和能力标签树等接口；semantic_aliases.v1.json 是发现侧语义别名材料。services/embedding-service 提供可选的文本向量服务，配置、测试和真实模型 smoke 文件位于该服务目录，不能把启用语义模型写成所有部署的强制依赖。

发现节点的数据路径应按四层区分：

1. 同步层接收根平台或内容分发平台材料，记录来源、游标和同步结果。
2. 验证层检查根平台可信发布证明、资源包哈希、DID文档、版本、授权域和生命周期。
3. 索引层把已验证材料写入结构化索引，并按能力标签、文本字段或可选向量建立检索索引。
4. 查询层把 DID、结构化条件和自然语言输入转换为条件，返回候选及来源、版本、状态和解释信息。

当前固定 fixture 已覆盖域内可见、域外不可见、空结果、任意标签匹配和非法查询；真实同步、向量模型质量、并发索引和跨节点收敛仍需服务集成或部署测试确认。发现节点维护者负责索引一致性、查询错误契约、来源保留、治理状态过滤和语义配置版本化。 发现查询的维护定位可以从入口向后追踪：/discovery/resources/query 负责请求解析和查询调度，索引表负责已验证资源的读模型，语义别名和能力标签材料负责规范化与候选辅助，services/embedding-service/src/server.ts 和 src/embedding.ts 只在启用向量模式时参与文本向量生成。排查“结果重复”时，应分别检查同一 DID 的版本去重、索引副本去重、分页游标和前端展示映射，不能只调整排序或前端数组。 发现服务节点的代码映射还要保留“原始材料 -> 验证结果 -> 索引记录 -> 查询候选”的转换关系。原始资源包或根平台发布通知不应直接等同于可查询结果；只有完成来源、哈希、版本、授权域和生命周期检查后，才可进入索引。查询响应中的相关性分数、标签命中和文本片段属于排序或解释证据，资源 DID、版本、来源和治理状态才是调用方继续验证的事实入口。

F.5 oan-trust-indexer

该仓对应第 13 章、第 19 至第 20 章以及授权状态和恢复要求。src/event_source.rs 负责事件来源，src/sync.rs 负责游标推进和同步，src/store.rs 负责投影存储，src/domain.rs 负责领域状态，src/api.rs 和 src/grpc.rs 提供查询接口，src/config.rs 负责运行配置。configs/mainnet.example.toml、mainnet.current-events.toml 和单检查点 smoke 配置用于区分持续同步、当前事件观察和诊断性运行方式。

索引器的可信链路是“读取链上事件 -> 按顺序或游标处理 -> 校验事件结构和状态转换 -> 写入链下读模型 -> 对外提供状态查询”。读模型必须保存事件来源、游标、最后成功处理时间、投影时间、错误和必要的版本信息。链下投影是治理事实的可查询缓存，不创造链上授权；根平台、注册服务节点和发现服务节点在使用它时应考虑延迟、过期和 fail-closed 边界。trust/v1/status 或等价接口返回的最新序列只能作为索引进度观察，不能单独证明某项链上交易已经最终确认。

现有准入 fixture 可验证 active、suspended、revoked 状态和治理快照的一致性，但不等同于真实链 RPC、GraphQL 端点、最终性、断点恢复和持续增长的证明。维护责任包括事件源兼容、游标不回退、重复事件幂等、异常重试、数据库备份和状态新鲜度监控；更换链端点时不得只修改地址而忽略 package、对象、事件类型和解析逻辑的联动核对。 链下信任索引器的接口返回只能说明其读模型状态。维护人员应把事件来源、最后处理游标、投影时间、错误和链端点配置放在同一份运行记录中，并将“链上事件已读取”“链下状态已投影”“根平台已采用该状态”分别记录；三者不能因一个健康接口返回成功而合并为单一结论。 链下信任索引器的版本升级应至少做一次小范围回放或检查点恢复验证：使用已知事件序列检查解析结果、游标、重复事件处理和状态投影，再比较 API 返回的主体、节点、凭证签发者和事件序列。若更换 package、对象或事件类型，旧读模型是否可以继续使用必须单独判断；不能因为进程重新启动且 /health 返回成功，就认定历史治理状态已经正确恢复。

F.6 oan-sdk-ts

该仓对应第 4 至第 8 章、第 11 章、第 15 至第 16 章和附录 A 至 C。packages/sdk-ts/src/index.ts 集中提供资源 DID文档草稿、资源包形状验证、生命周期检查、注册、发现、查询解释、能力标签辅助和治理读接口；identity.ts 负责本地主体/资源身份记录、密钥对生成、身份包导入导出和从身份生成注册材料；did-oan.ts 负责 did:oan 解析、规范化、主体代码到资源类型映射和语义冲突检查。packages/protocol-types/src/index.ts 提供跨包协议类型。测试位于 tests/sdk-core-tests.ts、identity-store-node-tests.ts 和 client-workflow-tests.ts。

SDK 的定位是调用方工具，而不是 Registrar、Root 或 Discovery 的权威实现。它可以在本地生成密钥、构造 DID文档和注册材料、调用公共接口并对资源包进行结构验证，但不能替调用方确认链上最终状态，也不应把推荐结果当作授权结论。测试中的 endpoint stub、固定 DID 和占位哈希用于接口行为验证，发布示例必须替换为真实端点、包哈希、授权域和资源描述。私钥和本地身份包由调用方保存，不发送给 OpenAgenet (OAN) 节点。

SDK 发布维护还需检查构建输出、导出入口、Node/浏览器运行边界和协议版本兼容，避免 README、npm 包内容和源码 API 不一致。 SDK 的公开入口以 package.json 的 exports 为准：根入口、./client、./governance、./protocol-types 和 ./identity-store-node 分别对应构建输出中的模块。变更 packages/*/src 后，应检查 npm run build 是否生成相应 JavaScript 和声明文件，再运行 tests/sdk-core-tests.ts、tests/client-workflow-tests.ts 和 tests/identity-store-node-tests.ts；如果只是内部实现变化但导出路径、请求字段或错误类型变化，仍应视为客户端兼容性变更。 SDK 映射应同时记录“本地生成”和“远端确认”的边界：身份、DID 文档草稿、资源包形状和签名材料可以在调用方本地生成或验证，注册 VC、根平台可信发布证明、发现索引状态和治理状态则来自节点或调用方的后续查询。SDK 方法名存在并不代表远端业务已经完成；示例和测试应明确哪些响应由 stub 提供，哪些需要真实注册服务节点或发现服务节点。

F.7 oan-community-skill

该仓对应第 16 章以及第 4 至第 8、11、15 和 18 章面向社区调用方的操作路径。其 SKILL.md 明确技能包用于资源描述整理、本地身份管理、注册材料生成、注册服务节点提交、发现查询、语义查询解释、生命周期观察和只读治理辅助；它不负责启动或维护根平台、注册服务节点、发现服务节点、内容分发平台、NATS、PostgreSQL 或链下信任索引器，也不执行链上治理写操作。实现说明要求继续核对 src/index.ts、validation.ts、registration.ts、resource-description.ts、discovery.ts、lifecycle.ts、capability-assist.ts 和 tests/oan-community-skill-tests.ts。

社区技能包的典型输入是资源 README、技能包说明或用户提供的产品描述；它先生成候选登记材料，再报告缺失字段和质量问题，要求用户补充名称、描述、公开访问地址、授权域、能力标签、用例、输入输出、许可证和维护者等事实，最后调用 SDK 的正常注册路径。它不能凭空发明端点、维护者、许可证或授权域，也不能把能力标签当作授权范围。对批量资源，应逐项报告成功、跳过、失败、缺失输入和下一步，不因某一项失败而静默丢弃其它结果。

Skill 维护责任是保持用户操作语义、SDK 调用、公共端点默认值、错误分类和隐私边界一致；发布包必须包含运行所需脚本、文档和资源，而不只包含 TypeScript 编译产物。它可以调用公开或用户明确提供的 Registrar、Discovery 和可选的信任查询端点，但不得暴露节点私有治理材料或读取根平台私有索引器。 社区技能包的实现核对应从 src/index.ts 的公开调用入口开始，分别追踪 registration.ts、resource-description.ts、validation.ts、discovery.ts 和 lifecycle.ts 的输入输出，再对照 tests/oan-community-skill-tests.ts 和发布包文件清单。技能包负责整理和调用，不负责替用户生成未经确认的事实；因此新增自动补全、标签建议或重试逻辑时，必须确认它不会把推测内容直接写入注册材料，也不会在结果未知时无条件重复提交。 社区技能包与 SDK 的变更也应区分“帮助生成材料”和“写入网络事实”。技能包可以整理描述、提示缺失字段和调用公开接口，但不能把推测出的端点、标签、授权域或许可证直接当作用户确认的注册事实；当请求结果未知时，也不能通过无条件重试制造重复 VC、重复版本或重复发布任务。

F.8 官网与公开开发者入口

官网是公共展示和操作入口，对应第 15、16、19、20、22 和 24 章的部分实现。前端使用公开的注册、发现、根平台、内容分发平台和链下信任索引器端点；后端通过 /api/* 和 /health 提供网站所需的聚合、统计、访问分析或代理能力。生产部署说明、构建与烟测脚本以及 Nginx 和 systemd 配置描述构建、配置、反向代理和验证边界。官网的 Home、Register、Discover、Network 和 Docs 页面可以调用或展示协议数据，但页面文案、地图、统计、缓存快照和推荐排序都属于展示层。

官网注册页可以在浏览器侧生成或导入本地身份，构造 DID文档和注册材料，再向指定注册服务节点提交；私钥不应发送到网站后端。发现页可以提交 DID 或自然语言任务描述，展示发现服务节点返回的候选资源和 DID文档预览；用户仍需根据资源 DID、VC、根平台可信发布证明、状态和端点执行最终验证。Network 页面展示节点和指标时，应区分当前实时数据、旧快照、未知状态和统计聚合，不能把 UI 状态作为治理权威。

官网部署维护的硬性核对项包括：生产前端构建变量不得残留本机地址；后端应只通过反向代理暴露；静态资源和后端版本一致；公共 HTTPS、语言切换、注册传输、发现查询、Network 摘要和浏览器路由均通过烟测。SEO、访问统计和页面缓存只能是松耦合增强，不能改变注册、发现、治理或节点服务的协议行为。 官网问题定位应先区分浏览器层、官网后端聚合层和节点服务层：前端页面及 frontend/src/api.ts 负责请求发起和展示，后端 backend/src/http/router.rs 与相应 handler 负责公共聚合接口，注册服务节点和发现服务节点才是注册/发现业务的直接处理者。访问统计写入、SEO 元数据、浏览器缓存和旧快照读取失败时，页面可以降级或不记录，但不得阻塞注册提交、发现查询或节点状态判断；任何跨层修改都要分别执行页面路由、公共接口和节点业务烟测。 网站组件与协议实现的变更边界可以用接口方向核对：浏览器到官网后端的 /api/* 是公共聚合或代理路径，官网后端到节点的请求是服务间调用，节点自身的 /resources/register 和 /discovery/resources/query 才是协议业务入口。修改官网缓存、统计、SEO 或页面文案时，应验证这些功能失败不会改变节点请求体、响应语义、注册/发现结果和治理状态；修改节点接口时，则不能只做网页回归而跳过协议和客户端测试。

F.9 规范章节与实现模块映射

下表提供面向维护和发布的主索引。章节编号是规范责任的入口，具体实现仍需结合前述仓库小节、当前提交和目标部署配置核对。

交叉索引维护遵循四条规则：第一，新增或修改共享字段时，先更新规范与 oan-protocol-common，再检查所有生产服务和客户端；第二，新增接口时同时更新错误契约、SDK、社区技能包和固定请求样例；第三，治理状态、根平台可信发布证明和语义匹配必须保留各自事实来源，不得在聚合层合并成一个无法解释的“可信”布尔值；第四，部署脚本和烟测通过只证明目标环境达到该次检查条件，不把环境变量、域名、模型、节点数量或数据库选型写成协议固定要求。

当实现与规范不一致时，维护者应在变更记录中说明受影响章节、输入输出差异、兼容策略、测试证据、是否产生数据迁移以及回滚方式。只有在代码、测试、配置和运行验证共同支持时，才能把“参考/待核对”提升为“已实现”；任何缺少事实来源、验证主体或状态边界的聚合结果，都只能作为观察信息，不能作为跨节点信任证明。

一次跨仓变更的最小追踪记录可以按以下顺序建立：

章节或字段变化
  -> oan-protocol-common 类型/校验/错误
  -> Root、Registrar、Discovery 或索引器调用路径
  -> SDK 与社区 Skill 输入输出
  -> fixture、单元测试和集成测试
  -> 配置、systemd/反向代理和部署烟测
  -> 兼容结论、发布提交和回滚依据

如果变更只涉及官网文案、SEO 或访问统计，应明确记录为官网展示层变更，不得把它列入协议版本变更；如果变更涉及协议字段、DID 文档、资源包、授权域、错误码或生命周期状态，则必须回到共享类型和所有消费方逐项核对。该追踪链用于维护和审查，不改变各仓库原有的职责边界。

交叉索引中的“已实现”应以最小证据集为准：对应代码入口可定位、至少有一项针对性测试或可重复检查、运行配置能够解析所需依赖，并且没有与当前协议字段或错误契约冲突。只有目录中存在文件而没有调用路径、测试结果或运行配置时，应保留为“参考/待核对”；只有测试夹具通过而没有服务集成时，应标为“测评支持”或“部分实现”，不能直接提升为生产能力。

参考来源