Nacos Agent 存储规范深度解析持久化模型、运行时发布与一致性契约【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos导读本文是 Agent Storage Spec 的中文深度解读。该规范定义了 Nacos 中 Agent 资源的内部持久化、运行时发布Runtime Publication、Naming 映射、编解码、摘要Digest与修订Revision契约是 Agent 模型迁移的规范性目标契约也是 RADResource Advertisement and Discovery数据面消息事实Facts的生产源头。读完本文你将掌握ai_resource/ai_resource_version两张表与 AI Storage、Naming 运行态之间的职责切分理解rad-ascii-v1与sha256.编解码的边界并能看懂运行时端点如何映射为 Nacos Naming 服务、如何计算sourceRevision以及整套容量与安全约束。1. 存储职责总览谁拥有什么事实Agent 状态按生命周期与访问模式被拆分为四类事实源。服务端禁止持久化合并后的AgentDiscoveryResult——概要、管理详情、目录、发现与 Watch 对象都只是对这些事实的只读投影Read Projection。Agent metadata ----------------------- ai_resource Agent Version metadata --------------- ai_resource_version CallInterface DECLARED Endpoint ---- AI Storage | -- built-in nacos_config provider RUNTIME publisher contributions ------ Naming Client runtime state存储拥有不拥有ai_resourceAgent 身份、目录catalog、治理、版本摘要与派生的在线目录版本载荷payload或运行时健康ai_resource_version精确的版本身份、生命周期状态、作者、存储指针与流水线状态CallInterface 载荷或运行时端点AI Storage单个 Version 的规范化AgentVersionContent字节资源身份、生命周期、标签或可见性Naming Client 状态活跃的发布者贡献、健康、启用状态与单一运行时 Version/范围事实Agent 定义或 Version 生命周期从源码看AI Storage 抽象由 StorageKey 承载——它类似于 Nacos 的 dataId/group/tenant 封装是一个携带 provider 标识的不透明键如nacos_config、oss对上层统一、对具体实现不透明。这与规范中Agent 服务组合一个 provider 中立的逻辑StorageKey.key并作为不透明值传递给每个 provider的约定一一对应。2. AI 资源持久化身份、扩展与版本行2.1 Agent 资源行Agent Resource RowAgent 的规范身份canonical identity为namespaceId typeagent nameagentName其映射到ai_resource的字段关系如下ai_resource字段Agent 映射namespace_id、type、namenamespaceId、常量agent、原始agentNamec_descdescriptionstatusenable或disableowner、scope同名的治理字段biz_tags用户提供的公开标签ext类型化AgentResourceExtc_from创建、导入或同步来源version_info共享的编辑中、审核中、在线数与标签摘要meta_version元数据 CAS 版本gmt_create、gmt_modified审计时间戳AgentResourceExt是 schema-version-1 的固定形态其 Java 模型见 AgentResourceExtSCHEMA_VERSION 1字段依次为displayName、iconUrl、provider、extensions、versionCatalog字段归属含义schemaVersionServer常量1displayName、iconUrl、providerUser校验后目录展示extensionsUser校验后公开的 Agent 级扩展versionCatalogServer派生的在线版本目录versionCatalog包含latestVersion与onlineVersions[]其中每个条目只含version、labels[]、protocols[]。onlineVersions按 Agent 版本优先级降序存储。版本状态与version_info.labels始终是事实facts发布、上线、下线、删除、打标签或变更 latest 都会以一次逻辑上的 Resource 更新重建目录。几个需要特别注意的约束biz_tags不存储服务端派生的索引读写投影必须保留用户标签的值与顺序。RAD 协议过滤使用AgentResourceExt.versionCatalog.onlineVersions[].protocols作为逻辑来源。实现可以维护独立的派生协议索引以提升查询效率但该索引不得编码进biz_tags也不得增删或重新解释公开标签。AgentName 与 Version 身份在 DAO 查询、唯一约束、缓存、标签与鉴权键中大小写敏感比较。实现不得依赖数据库默认的大小写不敏感排序规则collation。2.2 Agent 版本行Agent Version Row每个 Agent Version 对应一行ai_resource_versionai_resource_version字段Agent Version 映射namespace_id、type、name、version精确的版本身份statusdraft、reviewing、reviewed、online或offlineauthor、c_desc作者与变更说明storageProvider、不透明键、摘要、媒体类型、schema 与大小publish_pipeline_info审核执行与结果gmt_create、gmt_modified审计时间戳物理 Version 字段与每个新的 Agent 写入都支持最长 64 字符。存储 schema 不会创造出比 Agent 管理契约更宽的公开身份空间。版本列表操作只读取 Resource 与 Version 行精确版本详情在解析 Version 行后执行一次AI Storage 读取。3. AI Storage 中的 Agent 版本内容3.1 内容对象与存储指针一个 Version 恰好对应一个完整的存储对象AgentVersionContent kind AgentVersionContent schemaVersion 1 callInterfaces[] protocol / protocolVersion descriptorMediaType / nativeDescriptor endpointSourceOrder[] declaredEndpoints[]Java 模型见 AgentVersionContentKIND AgentVersionContent、SCHEMA_VERSION 1核心载体是ListAgentCallInterface。服务端校验对象、创建下述存储投影然后用公共的 Nacos JSON 序列化器以UTF-8序列化一次。产出的确切字节交给 AI Storage同时用于size与contentDigestsha256:小写hex。注意Agent 存储不定义语义级 JSON 规范化——两个解码后等价的 JSON 表示并不要求产生相同的摘要。序列化前服务端创建存储投影的五个步骤拒绝 envelope、CallInterface 与 Endpoint 对象上的未知 schema 属性只投影 schema-version-1 字段通过公共 Endpoint 规范化器canonicalizer规范化每个 DECLARED Endpoint URI并校验、保留其 transport物化有效的 Endpointpriority0与weight1省略缺失或为空的 Endpointmetadata与declaredEndpoints其余情况下完整保留所有数组顺序与描述符 JSON 值。nativeDescriptorJSON 成员与 Endpointmetadatamap 条目在各自单独定义的值约束内保持开放内容。投影规则只规范化 Agent 拥有的字段不重排nativeDescriptor内部成员也不改写协议拥有的 JSON。读取时完整性校验对 AI Storage 返回的确切字节做哈希后再解码禁止为了比对摘要而重新序列化解码对象。Version 行的storageJSON 字段如下对应 Java 常量见 AgentVersionStorageDescriptor字段值或含义provider存储 provider内置值为nacos_configkeyProvider 不透明的键keyFormat内置 provider 为agent-version-config-v1agentNameCodec内置 provider 为rad-ascii-v1contentDigestsha256:小写hexmediaTypeapplication/vnd.nacos.agent-versionjsonschemaVersion1size持久化内容的字节数Agent 服务组合一个 provider 中立的逻辑StorageKey.key并作为不透明值传给每个 provider。替换 provider 必须保持一 Version 一对象规则并自行维护逻辑键到物理键的映射。3.2 内置 Nacos Config 映射agent-version-config-v1provider 的键携带如下逻辑 Config 坐标逻辑值逻辑config_info坐标namespaceIdtenant_idnamespaceId内容类别group_idagent-versionagentName、versiondata_idagent__encodedAgentId__version.jsonAgentVersionContentUTF-8 JSONcontenttypejson随后内置 provider 对完整的逻辑 group 与 data id 应用公共的 NacosAiConfigKeyCodec在 Config 限制内的安全值原样存储超长的 data id 使用 codec 确定性的sha256.digest物理回退。因此物理键并不总是可逆任何上层都不得从物理键推导 Agent 身份合法的 Agent 身份也不得仅仅因为逻辑 data id 超过 Config 物理限制而被拒绝。provider 中立的StorageKey.key将逻辑身份序列化为namespaceId:agent-version:logicalDataId每个 provider 都收到该值但只有内置 provider 会解析它。该键恰好是三个冒号分隔段——因为 Namespace、编码后 AgentName 与 Version 语法都排除:。已有的四段、五段 Skill / Prompt / AgentSpec 键保留原有解释不参与此约定。draft 更新会覆盖同一键Version 进入 reviewing 后内容变为不可变。contentDigest从不参与 data id它只校验确切的持久化字节与缓存等价性。读取、审核与发布操作都必须校验存储指针、字节数与摘要。3.3 RAD ASCII AgentName 编解码器Config data id 与 Naming 服务名共享 RadAsciiAgentIdCodecCODEC_ID rad-ascii-v1其算法为输入是原始 1~64 字符的可打印 ASCIIagentName若整个输入匹配[A-Za-z0-9-]原样返回否则输出enc-body编码形态中保留 ASCII 字母与数字其余每个字符包括-编码为-DDDDDD是该字符的三位十进制 ASCII 值保留大小写绝不 trim 或转小写解码仅限已知使用该 codec 的段拒绝截断、非十进制、越界或非规范转义。规范中的示例Nacos-Agent - Nacos-Agent Nacos Agent - enc-Nacos-032Agent name-ok.1:2 - enc-name-045ok-0461-0582编码输出只含[A-Za-z0-9-]。Codec v1 有意不保留以enc-开头的原始名——因此一个原始安全名与另一个名的编码结果理论上可能产生相同的物理段。v1 接受这一低概率歧义不定义碰撞索引、保留或原子编码映射。公开身份永远来自ai_resource.name代码不得通过解码无类型的物理键来推断身份。未来需要无碰撞 codec 时必须引入新的 codec id 与显式迁移契约而不是原地修改rad-ascii-v1。解码端的防呆逻辑长度上限 260、-DDD越界与字母数字回退校验、最终encode(decoded)重编码比对在源码 RadAsciiAgentIdCodec.java 中有完整实现配套测试见 RadAsciiAgentIdCodecTest。Version 只使用字母、数字、.与-不经过AgentName codec。通用的 Config 物理键 codec 可能仅因物理长度限制而哈希完整逻辑 data id——这不会截断、哈希或改写任一公开身份字段。4. 运行时发布模型4.1 公开端点与版本绑定DECLARED 与 RUNTIME 源共享同一个 Endpoint 值对象。在同一 Agent 协议组内公开 Endpoint 的自然键natural key为(namespaceId, agentName, protocol, normalizedHost(uri), effectivePort(uri), normalizedTransport)URI path、query、priority、weight 与 metadata 是公开 Endpoint 的 payload但不参与自然键。不存在公开 Endpoint id。运行时版本绑定包含字段含义runtimeVersion实际运行的实现 VersionversionRange该发布所服务的 Agent Versions缺失的 range 规范化为精确[runtimeVersion]。range 是一个 Maven 风格的连续区间边界与比较使用大小写敏感的 Agent Version 规则而非 MavenComparableVersion。规范形态包括精确[1.0.6]、有界[1.0.0,2.0.0)、下界[1.0.0,)、上界(,2.0.0]不含空白、至少一个边界、等边界时用精确形式。区间并集与离散集合无效runtimeVersion必须落在其 range 内。4.2 发布命令AgentEndpointRegistrationBatch结构namespaceId / agentName / runtimeVersion / versionRange? / protocol endpoints[1..1000]一个批次内的所有 Endpoint 共享同一runtimeVersion/versionRange对与协议单元素数组即通用的单端点形式。命令本身不被持久化。该批次是发布者针对组合出的 Naming Service 的完整期望状态服务端校验完整批次后委托给 NamingbatchRegisterInstance。Naming原子地替换同一 Client 与 Service 的上一批次被省略的 Endpoint 会被移除。重复自然键拒绝批次重复相同内容则幂等。AgentEndpointDeregistrationBatch只含namespaceId、agentName、protocol与endpoints[] {uri, transport}。它是SDK 侧意图模型不是服务端部分删除命令SDK 从其 redo 状态移除所列自然键再通过同一注册路径提交保留的完整批次无剩余 Endpoint 时注销整个 Client 与 Service 的发布。服务端从不读取并合并上一批次来执行部分注销。4.3 内部发布者贡献Naming 发布身份为publisherIdentity namespaceId agentName protocolNaming 对该 Client 与 Service 恰好存储一个BatchInstancePublishInfo其 Instances 携带一个共享runtimeVersion与规范versionRange。后续注册整体替换该记录包括共享的 Version 字段因此首个版本允许每个发布者、Agent、协议单一runtimeVersion/versionRange对支持多对需要未来完整的快照线模型而不是服务端 read-merge-write 循环。Agent 层写入前不检查旧发布者记录、不直接依赖ClientServiceIndexesManager、不加服务锁、不扫描其他发布者。替换、连接清理、索引、事件与 Distro AP 收敛全部由 Naming 负责。不同发布者可能贡献收敛到同一公开自然键的 Instances读投影聚合规范相同的 payload若收敛后的 Naming 状态对同一自然键包含不同的 URI payload、priority、weight 或公开 metadata读取以RESOURCE_CONFLICT失败而不是任选一个值。这是投影安全校验不是写时预留或 CP 约束。4.4 绑定聚合每个 Naming Instance 在单一元数据键中存储一条规范绑定__nacos.agent.endpoint.version__ runtimeVersion __nacos.agent.endpoint.versionRange__ canonicalVersionRange不存在序列化的bindings元数据值。RuntimeVersionBinding对象与公开的bindings[]数组只在读取 Naming Service 投影时创建。绑定按runtimeVersion的 Agent SemVer 升序去重排序再按versionRange的大小写敏感字符串升序。RuntimeEndpointSnapshot从ServiceStorage读取完整的内部 Naming Service 投影再聚合投影后的 Instances不暴露发布者身份每个公开自然键恰好一个条目携带规范 Endpoint payload 与全部有效bindings[]。按 Version 过滤的快照只保留匹配绑定无剩余时省略条目。ServiceStorage可去重完全相同的 Instance——这不改变公开投影因为相同的 Instance payload、绑定、启用状态与健康会聚合进同一个公开条目。RAD 发现先按兼容目标集过滤绑定再把相等自然键聚合为一个公开 Endpoint省略 selector 时目标集为所有在线 Versions精确 Version 或任意显式标签时只使用解析出的 Version。投影重建在 AP 收敛后拒绝不一致 payload因此一次成功的投影不会包含同一自然键的两个不同公开 payload。4.5 预注册与生命周期运行时发布独立于 Agent 定义创建。即使 Agent、Version 或 CallInterface 不存在服务端也接受结构合法、已授权的发布——注册成功只代表运行时意图被接受不代表当前可被发现。注册校验 AgentName、运行时 Version、range、protocol、Endpoint、授权与批次容量不校验定义存在性、Version 生命周期状态或其他发布者的当前值。发布者身份是内部的gRPC 贡献归属一个 connection idHTTP 贡献归属公共 Naming ClientHTTP_CLIENTexternalClientId使用单个 client 级 Publisher 心跳公开管理对象与 RAD 对象不暴露身份或发布者数量。断开、Publisher 过期或 Client 过期只移除该发布者的贡献其他相等贡献保留。HTTP 查询只续约 Client不续约、恢复或保留 Publisher。聚合healthy在至少一个匹配的活跃贡献健康时为 true仅在全部不健康时为 false。仅心跳或仅发布者数量的变化不改变公开投影。enabled是独立的 Naming 运维状态不被心跳覆盖。Agent Endpoint 元数据不得设置 Naming 心跳间隔、心跳超时或实例删除超时键。显式注销、发布者丢失或 Naming 清理结束运行时状态Agent 禁用、Version 下线或定义删除只把它从适用的发现投影中移除。5. 运行时到 Naming 的映射5.1 服务与集群身份逻辑 Naming 范围namespaceId groupNameagent-endpoints serviceNameradServiceName(encodedAgentId, protocol) clusterNamenormalizedTransport规范协议 token 匹配[A-Za-z0-9][A-Za-z0-9-]{0,31}。服务名算法rad-encodedAgentId-protocol结果保留大小写、只含[A-Za-z0-9-]、以字母数字开头、可以字母数字或-结尾、不含 Version。在字段限制下有效最大值 297 字符低于 Naming 的 512 字符限制。示例Nacos-Agent / a2a - rad-Nacos-Agent-a2a Nacos Agent / a2a - rad-enc-Nacos-032Agent-a2aVersion 1 偏好简洁可读的物理名在encodedAgentId与 protocol 之间不加长度分帧因此(A, B-C)与(A-B, C)都组合为rad-A-B-C。v1 接受这一低概率碰撞且不定义碰撞索引或额外消歧实现不得从 serviceName 反解两个组成部分读者应使用已知的 AgentName 与 protocol 重组并比对。未来无碰撞规则需要新 composer id 与显式迁移契约。该字母表保证lb://serviceName可被解析为 Gateway URI但不定义 DNS 名也不小写化大小写敏感的 Nacos 服务身份——把 service id 规范化为小写的集成不在兼容性保证内。公开规范化 transport 匹配[0-9A-Za-z-]{1,64}。NamingclusterName为RadAsciiAgentIdCodec.encode(transport)只含[A-Za-z0-9-]例如HTTPJSON - enc-HTTP-043JSON。原始 transport 同时存入保留元数据。读取时必须对元数据中的 transport 重新编码并与clusterName交叉校验不得通过解码clusterName推断公开 transport。5.2 实例字段映射Agent 运行时字段Naming 字段namespaceIdService namespace固定 groupagent-endpoints编码后的 Agent 与 protocol5.1 节规范服务名编码后的规范化 transportInstance.clusterName规范化 URI host 与有效 portInstance.ip、Instance.portURI path__nacos.agent.endpoint.path__规范化 transport__nacos.agent.endpoint.transport__URI scheme__nacos.agent.endpoint.protocol__遗留 A2A 协议版本可选__nacos.agent.endpoint.protocolVersion__HTTPS 状态__nacos.agent.endpoint.supportTls__原始 URI query__nacos.agent.endpoint.query__native tenant存在时__nacos.agent.endpoint.tenant__运行时 Version__nacos.agent.endpoint.version__规范 Version range__nacos.agent.endpoint.versionRange__priority__nacos.agent.endpoint.priority__weightInstance.weight公开 Endpoint metadata其余Instance.metadata运行时状态Instance.enabled、Instance.healthy、ephemeraltrue这些保留元数据键在 Constants.Agent 中统一定义前缀__nacos.agent.endpoint.group 常量AGENT_ENDPOINT_GROUP agent-endpoints。用户元数据不得覆盖任何__nacos.agent.endpoint.*__键服务端在接受发布前构造并校验完整的 Naming 元数据。缺失的 range 输入在写入versionRange前先规范化。__nacos.agent.endpoint.protocolVersion__仅是遗留兼容事实被排除在公开 RAD Endpoint 元数据与 Runtime 修订输入之外。投影旧 A2A 响应时兼容适配器优先使用该值缺失时回退到目标 CallInterface 的protocolVersion。公开自然键映射到 service、cluster、IP、portpath 与 query 保持为 payload 元数据。serviceName 与 clusterName 中不出现 Version因此服务数量不会随兼容的 Agent Versions 增长。5.3 Naming 事实边界Naming Client 状态是 RUNTIME 写入事实拥有发布者身份、连接或分层心跳活性、清理、完整批次替换、索引、事件与 AP 收敛。注册把完整 Agent Endpoint 批次转换为 Naming Instances 并调用 Naming 一次完整注销移除 Client 与 Service 发布。Agent 服务端不读不合并旧发布者记录。HTTP 发布复用 Naming 公共的HttpConnectionBasedClient、ClientManagerDelegate与Nacos:Naming:v2:ClientDataDistro 路径。AI 模块只校验外部 Client id、拥有其 Distro Filter 路由并把 Agent Endpoints 转换为 Naming Instances——不维护 Agent 专属的 ClientData processor 或 Distro 资源类型。Runtime Snapshot 与 Discover 读取使用 NamingServiceStorage缓存的完整内部 Service 投影由 service 范围的 Client 索引构建含运维 Instance 元数据。Agent 层解析每个 Instance 的单一绑定、应用可选的目标 Version 过滤器、校验 payload 一致性并按公开自然键聚合。ServiceStorage内完全一致 Instance 的去重是安全的因为冗余的相同发布不改变任何公开聚合字段。ServiceStorage返回的内部ServiceInfo容器不是经 SDK、HTTP API、selector 或健康保护路径暴露的 Naming 结果契约外部或后处理的 NamingServiceInfo不得当作 Runtime 事实源也不得直接转发为 RAD Watch 快照。enabled与weight的运维 Naming 元数据对运行时发布值有正常优先级。Agent 投影仍保留不健康实例并暴露其原始聚合健康不应用 Naming 健康保护回退。6. 运行时发现投影一个 RUNTIME Endpoint 只有满足全部 5 个条件才有资格进入发现结果Agent 存在、可见且启用enabled定义 Version 处于 online定义 Version 拥有相同协议的 CallInterface 且允许RUNTIME源至少一个有效绑定包含 selector 兼容目标集内的 VersionNaming Endpoint 的enabledtrue。healthyfalse的合格 Endpoint仍然出现在 RAD 输出中——SDKselectOneHealthy会过滤它get-all 与 watch 保留它被禁用的 Endpoint 则缺席。投影使用定义 Version 的 CallInterface 提供协议版本、描述符与端点源顺序运行时贡献从不覆盖这些定义字段遗留专用的 Naming 协议版本元数据被 RAD 忽略。7. 运行时源修订sourceRevision对每个 Runtime 发现投影服务端生成不透明的sourceRevision流程如下从ServiceStorage读取完整内部 Naming Service 投影选择包含至少一个兼容目标 Version 的绑定规范化每个 Endpoint URI、校验并保留 transport、物化有效priority0与weight1、要求healthy校验每个自然键恰好一个规范 payload移除enabledfalse保留两种健康状态为每个启用的 Endpoint 附加排序去重后的匹配绑定并集按自然键对 Endpoints 排序元数据键按 UTF-16 code-unit 序排序对下述修订字节计算 MurmurHash3 x64 128。同一投影内自然键排序normalizedHost按 UTF-16 code-unit 序 →effectivePort数值 → transport 按 UTF-16 code-unit 序。实现不得使用 locale 敏感排序。URI path 与 query 不参与排序非自然键字段。外部 token 格式murmur3-x64-128-v1:32 lowercase hex修订输入包含 URI、transport、有效 priority 与 weight、公开 Endpoint metadata、healthy以及每个返回的runtimeVersion与规范versionRange绑定排除发布者身份与数量、心跳时间、最后更新时间与 Naming 内部修订。因此即使 endpoint payload 不变绑定或在线兼容目标变化也会推进修订。缺失与为空的公开 Endpoint metadata 都按零条目计数。空集有稳定修订冗余发布者的增删不改变它。该 token 只用于缓存等价性与 watch 去重不是身份、鉴权、CAS 或防篡改。所有节点使用 seed0与固定大端二进制布局元素编码Endpoint 数量无符号四字节整数uri、transport无符号四字节 UTF-8 字节长度 字节priority有符号四字节整数weight八字节 IEEE-754 binary64 位负零规范化为正零metadata无符号四字节条目数 按序 key/value字符串编码同上healthy一字节0false1truebindings无符号四字节绑定数 按序runtimeVersion与规范versionRange字符串编码同上空集恰为uint32be(0)。Murmur 结果先输出h1再输出h2各为无符号八字节大端随后小写十六进制。这些规则在内部存储 schema 中机器可读见 agent-storage.schema.json。NamingServiceStorage提供当前缓存的 Service 投影Agent 读路径从中派生公开 Endpoint 集与修订不维护另一份投影缓存。持久化的 AgentVersion 内容继续使用 SHA-256DECLARED 端点集使用 Version 的contentDigest作为不透明源修订。8. 读写、缓存与一致性路径读操作读取的事实AI Storage 读取管理 Agent 列表ai_resource分页否RAD 或通用 Agent 搜索当前 Agent Search 文档AUTO/INDEX就绪前可能返回部分当前快照SCAN显式使用兼容扫描否Agent 概览Resource 有界 Version 行分页否精确版本详情一行 Version一次运行时端点快照单协议的完整内部ServiceStorage投影可选绑定过滤否RAD DiscoverResource、在线 Version、缓存内容与合格运行时投影摘要未命中时一次变更写入目标一致性规则Agent 目录、治理、扩展ai_resourcemetaVersionCAS创建或更新 draftAI Storage 固定键 Version 行指针、字节、size 与摘要一致发布、上线、下线、删除、标签/latestVersion 行 Resource 摘要重建派生目录运行时注册、Publisher 心跳、注销Naming Client 运行时状态不写 AI Resource 或 StorageAgent 目录或 Version 生命周期提交ai_resource_task中合并的search_index修订异步重读事实并重建派生索引缓存校验器事实校验器Agent 元数据metaVersionAgent Version 内容contentDigest目标运行时投影sourceRevisionNamingServiceStorage拥有完整的 per-Service 投影缓存Agent 层从当前ServiceStorage结果派生所需投影sourceRevision由最终公开 Endpoint 集计算。AI Storage provider 保证单个 StorageKey 的原子字节与声明的读一致性Agent Registry 负责跨 Resource、Version、存储指针、摘要与派生目录的编排、校验、幂等重试与失败补偿。发布必须重读内容并校验摘要。draft 更新校验目标 Version 等于 Resource 当前editingVersion且仍为 draft覆盖 Version 既有固定 StorageKey再用既有 AI ResourceupdateStorageAndDesc操作更新存储指针与描述。Agent 层不新增资源专属 CAS 机制跨ai_resource_version与 AI Storage 的条件更新是 AI Resource 公共能力应由 Agent、Prompt、Skill、AgentSpec 一致设计与采用。存储写成功但元数据写失败会产生可观察的不完整操作以孤儿内容重试或清理。摘要不匹配绝不返回未校验内容。versionCatalog与 Resource 版本摘要是可重建派生数据其一致性不委托给 Storage provider。Agent Search 投影同样是可重建派生状态每个(namespaceId, agentName)至多一个当前文档。其resourceVersion是 common latest 引用的精确在线 Version并包含完整确定性排序的在线 Version 目录、protocols与artifactKinds面facets、投影版本与源摘要。源摘要覆盖规范 Agent 元数据、Version 目录、common latest、最新 Version 的contentDigest、artifact kinds 与投影版本——修改时间戳不是唯一输入。关系文档、chunk 与内嵌面在单个事务中整体替换索引不存储 Runtime Endpoint、健康、Publisher、心跳或 Runtime 修订。Backfill/Reconciliation 以有界资源键批次经资源类型 handler 扫描按(agent, projectionVersion)维护集群就绪任务、租约与读模式语义由 AI Resource Search Spec 定义。9. 容量与安全运行时或物理字段限制序列化biz_tagsJSON1024 字符只含用户标签runtimeVersion64 字符规范versionRange256 字符一个连续区间注册批次1~1000 个 Endpoint每发布者 Client 的运行时发布条目软水位默认 100可用nacos.ai.rad.capacity.publication.max-publications-per-client配置从下方准入的完整批次可越过它每 Agent 每协议的运行时 Endpoint1000受更低集群配额约束最终 Endpoint 元数据32 个公开条目键 64、值 256 字符最终 Naming 元数据键值String.length()之和为 1024Agent Version 物理 Config data id255 字符由NacosAiConfigKeyCodec强制超长逻辑 id 走 SHA-256 回退Agent Version 内容1 MiB服务端在写 Naming 前校验完整生成元数据含保留键拒绝溢出绝不截断或静默丢弃字段。配置常量与默认值见 Constants.AgentDEFAULT_MAX_PUBLICATIONS_PER_CLIENT 100默认配置项可在 distribution/conf/application.properties 中查看。AI Storage 内容、Endpoint 元数据与发布者状态不得包含明文凭据日志与审计事件不得向普通用户暴露完整 native descriptor、安全方案、发布者身份或敏感 Endpoint 元数据。10. A2A 运行时兼容边界A2A 适配器是此存储契约的第一个消费者遗留 A2A 事实新存储投影AgentCard 定义Version 内容中的 A2AAgentCallInterface.nativeDescriptorRoot 与附加接口适配器派生的 DECLARED Endpoints运行时 AgentEndpoint VersionruntimeVersionversion、versionRange[version]运行时调用协议规范 Agent 协议 tokena2a遗留 endpoint transport 与 URI 部件公共 Endpoint 与保留 Naming 元数据CANONICAL兼容分支把遗留 A2A 运行时注册写入公共的版本中立 Service。为保持每发布者每 Service 一个完整单一绑定批次的规范适配器为每个(original connection, namespaceId, agentName, exactVersion)派生一个内部子发布者每个子发布者为其精确 Version 提交完整批次因此 Versions 不会互相覆盖服务端也不做 read-merge-write断开原始连接释放全部子发布者。LEGACY分支完整保留历史的版本专属 Naming 布局。BetaCANONICAL分支不双写历史 Service。依赖遗留 serviceName 的 Naming Gateway 调用方兼容、混合集群双读/双写、回滚、旧 Service 清理与畸形历史身份处理属于独立的后 Beta 滚动升级与迁移契约不在本契约范围内。结语从规范到实现agent-storage-spec.md给出的是一份机器可执行的契约ai_resource/ai_resource_version是管理事实AI Storage 是版本内容事实Naming Client 状态是运行时事实而目录、发现、Watch 与搜索文档全部是派生投影。三个校验器——metaVersion、contentDigest、sourceRevision——分别守住元数据、内容与运行时投影的缓存等价性。仓库中 RadAsciiAgentIdCodec、NacosAiConfigKeyCodec、AgentVersionStorageDescriptor 与 Constants.Agent 等实现与测试如 RadAsciiAgentIdCodecTest、AgentVersionContentSerializerTest、NacosAiConfigKeyCodecTest逐条印证了规范中的算法与边界配合 Agent Management Spec、RAD Protocol Spec 与 A2A Agent Spec 可形成完整的阅读闭环。【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacos创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考