Nacos AI Registry 规范深度解析：3.x 一等能力的 AI 资源注册、治理与发现体系

Nacos AI Registry 规范深度解析3.x 一等能力的 AI 资源注册、治理与发现体系【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosAI Registry 是 Nacos 3.x 中与 Config、Naming 并列的一等能力负责 MCP Server、Agent、Prompt、Skill、AgentSpec 等 AI 资源的注册、治理、发现和分发。本文以 AI Registry 规范 为主线结合ai模块源码AiResource.java、AiResourceVersion.java 等完整讲解标准资源模型、生命周期状态机、接口面与横切规则帮助你掌握如何在 AI 云原生应用中落地版本化的 AI 资产治理。1. AI Registry 的定位与边界1.1 领域职责AI Registry 是 Nacos 中专门负责 AI 资源注册、治理、发现和分发的领域在 Nacos 3.x 中与 Config、Naming 并列为一等能力。它使用 资源模型规范 中定义的共享身份namespaceId - resourceType - resourceNameAI Registry 负责AI 资源元数据、版本、标签、状态、scope、owner 和业务标签的统一建模MCP Server、Agent、Prompt、Skill、AgentSpec等资源类型契约的定义与落地已支持 AI 资源的运行时查询和订阅行为draft 创建、审核、发布、强制发布、上线/下线、删除、上传、导入和下载等管理流程AI发布流水线、存储插件、可见性、鉴权和 Trace 钩子的领域使用方式。1.2 领域边界不负责什么Config 资源语义即使默认 AI 存储实现通过 Config 保存资源内容见 NacosConfigAiResourceStorage.javaConfig 在此只是存储后端AI 内容不应被视为用户拥有的 Config 资源Naming service 语义即使 MCP 或 Agent endpoint 通过 Naming service 和 instance 表达AI Registry 也不接管服务发现本身的语义AI Registry 适配器规范 暴露的社区 registry 协议定义插件扩展契约流水线、存储、资源导入、可见性和 Trace 的扩展规则由对应插件规范单独定义。从源码结构看ai模块的controller、service、storage、pipeline、importer、plugin等包见 ai/src/main/java/com/alibaba/nacos/ai正是按上述职责拆分的各类型agent、mcp、prompt、skill、agentspec各自拥有独立的 admin/client 控制器与 service 实现。2. 设计原则规范明确五条设计原则是整个 AI Registry 架构的决策依据以版本为中心标准模型基于AiResource元数据和AiResourceVersion版本。新增资源类型应优先适配该模型而不是引入自定义存储形态。规范特意强调AI 资产变化通常比应用配置或服务发现数据更快见 AI 资源模型规范这正是版本化模型的根本动机。运行时与管理面分离Client API 和 SDK 暴露运行时查询、endpoint 注册和订阅Admin、Console 和 Maintainer SDK 负责宽范围列表、上传、发布治理和删除。资源身份稳定resourceType是第二层身份。AI 资源不应引入 Config 风格的groupName身份除非兼容路径必须保留。插件组合可见性、存储、Trace 和发布流水线应通过插件组合外部资源导入也使用相同插件模型并把导入 artifact 路由回资源 Operator。不应定义隐藏的 AI 专用扩展机制。代码中 plugin 包下的AiPipelinePluginProvider、AiStoragePluginProvider、AiResourceImportPluginProvider、AiVectorPluginProvider即是对该原则的直接落地。允许快速演进AI 协议和资源格式变化很快。当 MCP、A2A、Agent 包格式或模型工具生态变化时规范可能需要不兼容或大幅调整调整必须按照 兼容与废弃策略规范 说明迁移、兼容和废弃行为。3. 标准 AI 资源模型元数据行 版本行3.1 目标标准模型AiResource(namespaceId, type, name) - AiResourceVersion(namespaceId, type, name, version)字段和生命周期细则参见 AI 资源模型规范 和 AI 资源生命周期规范。3.2 AiResource 元数据行AiResource是元数据行对应数据库表ai_resource。源码实体 AiResource.java标注since 3.2.0继承自VisibilityResource字段与规范一一对应字段含义源码字段namespaceIdNamespace 隔离边界namespaceIdtype资源类型mcp、agent、prompt、skill、agentspectypename稳定资源名namedesc资源描述descstatus元数据状态enable/disablestatusowner创建者或所属 identity继承自VisibilityResourcescope可见性 scopePUBLIC/PRIVATE继承自VisibilityResourcebizTags用于筛选或 UI 分组的业务标签bizTagsext由资源类型拥有的扩展 JSONextfrombootstrap、import 或 sync 来源标记fromversionInfo版本治理摘要 JSONversionInfometaVersion元数据 CAS 更新使用的乐观锁版本metaVersiondownloadCount支持时记录聚合下载或使用次数downloadCount注意name、type、namespaceId是身份字段不应作为普通元数据修改。源码中AiResource重写了getResourceName()与getResourceType()返回name与type使其可以直接参与共享可见性插件的资源判定逻辑。3.3 AiResourceVersion 版本行AiResourceVersion是版本行对应数据库表ai_resource_version。源码实体 AiResourceVersion.java字段含义源码字段namespaceId,type,name父元数据身份namespaceId/type/nameversion父资源下唯一的版本字符串versionauthor创建或导入该版本的操作者authordesc版本描述或 commit messagedescstatus版本生命周期状态statusstorage通过 AI 存储插件管理的内容存储指针 JSONstoragepublishPipelineInfo与流水线执行关联的发布审核状态 JSONpublishPipelineInfodownloadCount支持时记录该版本的下载或使用次数downloadCount已发布内容默认应视为不可变如果某个类型必须允许内容修改它的类型规范必须定义明确的安全规则。3.4 VersionInfo JSON 与 LabelsAiResource.versionInfo保存资源级版本摘要包含字段含义editingVersion当前 draft 版本reviewingVersion当前审核中版本onlineCntonline 版本数量labelslabel 到 version 的映射包括latest规则要点同一资源最多应有一个editingVersion和一个reviewingVersion除非类型规范明确定义覆盖或多 draft 行为否则已有 working version 时应拒绝创建新 draftLabels 不得指向 draft 或 reviewing 版本运行时客户端可以通过明确 version、label 或类型默认 latest 查询latest是保留的默认 label由服务端维护手动更新 labels 的请求可以包含latest但服务端必须忽略客户端传入的latest值并把当前服务端维护的latest合并回最终 labels map。以上常量在 AiResourceConstants.java 中集中定义包括RESOURCE_TYPE_SKILL skill、RESOURCE_TYPE_PROMPT prompt、RESOURCE_TYPE_MCP mcp、LABEL_LATEST latest以及元数据状态META_STATUS_ENABLE/DISABLE和版本状态VERSION_STATUS_ONLINE/DRAFT/REVIEWING/REVIEWED/OFFLINE六种状态字面量。3.5 存储抽象Nacos Config 只是默认后端标准模型把元数据存入持久化表把 payload 内容通过AI 存储抽象保存。默认存储实现基于 Nacos Config即 NacosConfigAiResourceStorage.javaTYPE nacos_config其 StorageKey 按资源类型区分LegacySkillnamespaceId:name:version:filePath4 段默认skill__前缀TypednamespaceId:resourceType:name:version:filePath5 段resourceType 为skill/agentspec/promptAgent VersionnamespaceId:agent-version:dataId3 段不透明 keyMCP Version contentnamespaceId:mcp-owned-group:dataId3 段不透明 key。关键约束每个版本必须在AiResourceVersion.storage中持久化选定的存储 provider。有效 provider 配置只在写入新版本时选择 provider已有版本的读取、draft 覆盖和删除必须按已持久化的 provider 路由。缺少 provider 的历史存储描述归属于nacos_config。扩展行为由 AI 存储插件规范 定义数据库方言行为由 数据源方言插件规范 定义。不同类型对ext与storage的契约各不相同typeagentext保存目录扩展和派生的在线版本目录Versionstorage指向完整 Agent Version 内容对象详见 Agent 管理规范 与 Agent 存储规范Runtime Agent Endpoint 遵循客户端拥有的 Naming 生命周期不写入AiResourceVersion.storagetypemcp标准资源名为mcpName。Resourceext只保存 Schema Version 和已废弃的 UUID 形态mcpIdVersionstorageDescriptor 通过 Allowlist 限定的mcp-config-v1Key 格式指向现有 MCP Server 与可选 Tools/Resources Config 对象不会复制、重写或扩展这些 Payload。精确字段由 MCP Server 规范 及 mcp-resource-ext.schema.json、mcp-version-storage.schema.json 定义。4. 资源类型清单规范为当前支持的资源类型建立了统一清单Type标准身份当前或已批准目标持久化形态规范mcpnamespaceId - mcp - mcpName已批准目标由ai_resource和ai_resource_version托管管理生命周期Descriptor 指向不变的 Config 内容历史 Manifest 以及现有 Direct、Service Ref、frontend/backend 和 Runtime Naming 布局继续作为 Serving 平面MCP Server 规范agentnamespaceId - agent - agentName已批准目标为ai_resource、ai_resource_version、AI 存储和 Naming 承载的 Runtime Endpoint publication迁移完成前历史 A2A 存储仍是兼容来源Agent 管理规范promptnamespaceId - prompt - promptKey使用ai_resource、ai_resource_version和 AI 存储旧 Prompt 数据可迁移Prompt 规范skillnamespaceId - skill - name使用ai_resource、ai_resource_version、AI 存储和轻量 discovery manifestSkill 规范agentspecnamespaceId - agentspec - name使用ai_resource、ai_resource_version和 AI 存储AgentSpec 规范特别说明A2A AgentCard 是agentVersion 内的一种协议 binding。历史a2a资源身份和 API 是 A2A Agent 规范 定义的兼容 facade不得形成第二套标准 Agent 身份。从源码看ai模块为每种类型都建立了独立的 admin/client 控制器如 McpAdminController.java、AgentAdminController.java、SkillAdminController.java、PromptAdminController.java、AgentSpecAdminController.java 等并保留了 A2aAdminController.java 作为兼容入口。5. 接口面五类访问途径AI Registry 通过多个接口面暴露分别服务不同受众接口面受众规则/v3/client/ai/...运行时客户端和 Agent framework查询已知资源、下载运行时产物、订阅以及注册客户端拥有的 endpoint/v3/admin/ai/...管理工具和 Maintainer SDK创建、更新、列表、发布、删除、上传和版本运维/v3/console/ai/...Nacos 控制台围绕相同领域语义进行 UI 编排gRPC AI requestsJava Client SDK 运行时流量查询 AI 资源、执行 RAD 发现与订阅并在支持时发布客户端拥有的 endpointJava SDK运行时应用集成参见 Java SDK 实现规范Java Maintainer SDK类型化管理集成应与 Admin API 语义和资源类型规范保持一致AI Registry 适配器外部社区 registry 客户端独立端口上的可选兼容端点参见 AI Registry 适配器规范以 MCP 的 Admin 控制器为例McpAdminController.java 在Constants.MCP_ADMIN_PATH下暴露了完整的管理端点GET /list、GET /versions、GET /version、POST /draft、POST /submit、POST /publish、POST /force-publish、POST /redraft、POST /online、POST /offline——这正是生命周期规范在 HTTP 接口面的直接投影。6. 横切规则AI Registry 的所有功能必须遵守一组横切规则HTTP API 规则AI Registry API 必须遵循 HTTP API 规范 中的 v3 响应、错误、鉴权和 API 类型规则gRPC 规则gRPC payload 必须遵循 gRPC API 规范查询路由运行时查询和订阅应优先通过版本或 label 路由而不是宽范围资源列表可见性必须使用 可见性插件规范。ai模块中的 VisibilityHelper.java 及service/visibility包即是其接入点AiResource继承VisibilityResource也保证了与共享可见性插件的兼容发布流水线扩展行为必须使用 AI 发布流水线插件规范实现位于 PublishPipelineExecutor.java 与 PublishPipelineManager.java存储扩展必须使用 AI 存储插件规范外部导入必须使用 AI 资源导入插件规范。导入插件负责把运维配置的外部来源转换为导入 artifact资源 Operator 负责把 artifact 应用到当前存储和生命周期模型。源码中 importer 包的AiResourceImportManager、AiResourceImportPluginManager与operator子包的AiResourceOperator/AiResourceOperatorRegistry/McpResourceOperator/SkillResourceOperator完整实现了这条职责链Trace 与审计应使用 Trace 插件规范 和共享可观测规则。7. 生命周期状态机与管理流程虽然生命周期细则由 AI 资源生命周期规范 单独定义但 AI Registry 规范要求其管理流程draft 创建、审核、发布、强制发布、上线/下线、删除、上传、导入和下载必须可用这里归纳关键状态与规则元数据状态enable资源在可见且存在可查询版本时可用、disable元数据层禁用。版本状态draft编辑中→reviewing流水线审核中→reviewed审核完成等待发布/退回/重新提交→online已发布可查询→offline已存在但从运行时路由移除。标准流程create/upload draft - update draft - submit - reviewing - reviewed - publish - online - offline/online toggle or delete如果没有启用发布流水线或没有匹配该资源类型的流水线节点submit可以根据类型实现直接发布force-publish会绕过流水线校验必须保持为管理操作它仅接受draft、reviewing和reviewed版本online和offline版本必须被拒绝draft规则除非类型规范定义覆盖或多 draft 行为一个资源最多应有一个 working draft创建 draft 可以新建元数据行也可以从 online 版本 fork删除 draft 会清理editingVersion指针并删除 draft 版本行和存储内容latest由服务端维护成功的 publish 或 online 操作使目标版本成为latest当前 latest 被删除或下线时默认选择剩余 online Version 中最大的一个不存在 online Version 时删除latest。MCP 类型的最新值回退顺序为最大的 SemVer → 数值最大的vN→ 稳定且区分大小写的最大字符串详见 MCP Server 规范删除规则删除版本应删除版本行和类型自有存储内容删除资源应删除元数据、所有版本行和所有类型自有存储内容只有全部被引用的存储内容清理成功后才能删除元数据和版本行任一清理失败时删除必须返回失败并保留重试所需的数据行和存储描述符。这些状态字面量与 CAS 重试参数MAX_WORKING_VERSION_RETRY 3在 AiResourceConstants.java 中均有源码级定义。Trace 与计数create draft、update draft、submit、review approved/rejected、publish、force publish、online/offline、delete、label update、description update、scope update 和 download 都应发出 Trace/审计事件。AI 资源 Trace 通过AiResourceTraceEvent发出默认 AI 资源 Trace 插件保留ai-resource-trace.log中的 JSON 行审计日志同时允许外部 Trace 订阅者消费同一批事件。计数只用于诊断不得定义鉴权或生命周期状态。8. 迁移与演进事项规范对历史形态与未来演进给出了明确的契约MCP 迁移遵循 MCP Server 规范中的异步、单向管理状态SYNCING - LIFECYCLE_MANAGED只创建 Resource/Version 指针不修改 Config 字节或 Naming等待零差异对账和全节点管理能力门禁切换后继续维护历史 Manifest 和当前 Endpoint Serving 布局。该契约完成实现和验证前Production 行为仍未落地仓库中 McpLifecycleReconciliationTask.java 即对应对账任务A2A 迁移历史 A2A AgentCard 和 Naming endpoint 数据必须通过滚动升级方案迁移到 Agent 模型旧 API 只是投影视图不再拥有独立资源存储Prompt 迁移已有从旧 Config 形态 Prompt 数据迁移到标准 AI 资源模型的路径见 PromptDataMigrationTask.java。旧映射必须作为兼容存储而不是正式 Config 资源语义RAD 语义RAD 返回确定性的 endpoint 集合。健康过滤、priority/weight 选择和负载均衡属于客户端策略不改变 Registry snapshot参见 RAD 协议规范Schema 演进随着 MCP、A2A 和 Agent 包生态演进AI 资源 schema 和协议 payload 可能需要大幅调整调整必须遵循 兼容与废弃策略规范 的迁移、兼容和废弃要求。9. 延伸阅读AI Registry 作为领域总纲与其下游规范构成完整体系建议按需深入模型与生命周期AI 资源模型规范、AI 资源生命周期规范、AI 资源搜索规范类型规范MCP Server 规范、Agent 管理规范、Prompt 规范、Skill 规范、AgentSpec 规范、A2A Agent 规范插件契约AI 发布流水线插件规范、AI 存储插件规范、AI 资源导入插件规范、Trace 插件规范、可见性插件规范源码实现模型实体见 ai/src/main/java/com/alibaba/nacos/ai/model控制器见 ai/src/main/java/com/alibaba/nacos/ai/controller存储与导入见 storage 与 importer【免费下载链接】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），仅供参考