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/nacos

AI 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 -> resourceName

AI Registry 负责：

• AI 资源元数据、版本、标签、状态、scope、owner 和业务标签的统一建模；
• MCP Server、Agent、Prompt、Skill、AgentSpec等资源类型契约的定义与落地；
• 已支持 AI 资源的运行时查询和订阅行为；
• draft 创建、审核、发布、强制发布、上线/下线、删除、上传、导入和下载等管理流程；
• AI发布流水线、存储插件、可见性、鉴权和 Trace 钩子的领域使用方式。

1.2 领域边界（不负责什么）

• Config 资源语义：即使默认 AI 存储实现通过 Config 保存资源内容（见 NacosConfigAiResourceStorage.java），Config 在此只是存储后端，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 架构的决策依据：

1. 以版本为中心：标准模型基于AiResource元数据和AiResourceVersion版本。新增资源类型应优先适配该模型，而不是引入自定义存储形态。规范特意强调："AI 资产变化通常比应用配置或服务发现数据更快"（见 AI 资源模型规范），这正是版本化模型的根本动机。
2. 运行时与管理面分离：Client API 和 SDK 暴露运行时查询、endpoint 注册和订阅；Admin、Console 和 Maintainer SDK 负责宽范围列表、上传、发布治理和删除。
3. 资源身份稳定：resourceType是第二层身份。AI 资源不应引入 Config 风格的groupName身份，除非兼容路径必须保留。
4. 插件组合：可见性、存储、Trace 和发布流水线应通过插件组合，外部资源导入也使用相同插件模型，并把导入 artifact 路由回资源 Operator。不应定义隐藏的 AI 专用扩展机制。代码中 plugin 包下的AiPipelinePluginProvider、AiStoragePluginProvider、AiResourceImportPluginProvider、AiVectorPluginProvider即是对该原则的直接落地。
5. 允许快速演进：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，字段与规范一一对应：

注意：name、type、namespaceId是身份字段，不应作为普通元数据修改。源码中AiResource重写了getResourceName()与getResourceType()（返回name与type），使其可以直接参与共享可见性插件的资源判定逻辑。

3.3 AiResourceVersion 版本行

AiResourceVersion是版本行，对应数据库表ai_resource_version。源码实体 AiResourceVersion.java：

已发布内容默认应视为不可变；如果某个类型必须允许内容修改，它的类型规范必须定义明确的安全规则。

3.4 VersionInfo JSON 与 Labels

AiResource.versionInfo保存资源级版本摘要，包含：

规则要点：

• 同一资源最多应有一个editingVersion和一个reviewingVersion；除非类型规范明确定义覆盖或多 draft 行为，否则已有 working version 时应拒绝创建新 draft；
• Labels 不得指向 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.java（TYPE = "nacos_config"），其 StorageKey 按资源类型区分：

• Legacy（Skill）：namespaceId:name:version:filePath（4 段，默认skill__前缀）；
• Typed：namespaceId:resourceType:name:version:filePath（5 段，resourceType 为skill/agentspec/prompt）；
• Agent Version：namespaceId:agent-version:dataId（3 段不透明 key）；
• MCP Version content：namespaceId:mcp-owned-group:dataId（3 段不透明 key）。

关键约束：每个版本必须在AiResourceVersion.storage中持久化选定的存储 provider。有效 provider 配置只在写入新版本时选择 provider；已有版本的读取、draft 覆盖和删除必须按已持久化的 provider 路由。缺少 provider 的历史存储描述归属于nacos_config。扩展行为由 AI 存储插件规范 定义，数据库方言行为由 数据源方言插件规范 定义。

不同类型对ext与storage的契约各不相同：

• type=agent：ext保存目录扩展和派生的在线版本目录，Versionstorage指向完整 Agent Version 内容对象（详见 Agent 管理规范 与 Agent 存储规范）；Runtime Agent Endpoint 遵循客户端拥有的 Naming 生命周期，不写入AiResourceVersion.storage；
• type=mcp：标准资源名为mcpName。Resourceext只保存 Schema Version 和已废弃的 UUID 形态mcpId；VersionstorageDescriptor 通过 Allowlist 限定的mcp-config-v1Key 格式指向现有 MCP Server 与可选 Tools/Resources Config 对象，不会复制、重写或扩展这些 Payload。精确字段由 MCP Server 规范 及 mcp-resource-ext.schema.json、mcp-version-storage.schema.json 定义。

4. 资源类型清单

规范为当前支持的资源类型建立了统一清单：

特别说明：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 通过多个接口面暴露，分别服务不同受众：

以 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