Nacos AI 资源生命周期规范详解从 Draft 到 Online 的版本化治理实战【免费下载链接】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 并列的一等能力负责 AI 资源的注册、治理、发现与分发。本文以 AI 资源生命周期规范 为骨架结合 AI 资源模型规范 与ai模块源码完整讲解 MCP Server、Agent、Prompt、Skill、AgentSpec 等版本化 AI 资源的状态机、审核发布流程、Labels、删除与审计规则。读完本文你将掌握 AI 资源从创建草稿、提交审核、发布上线到删除回收的全生命周期治理方案并能对照源码理解AiResourceManager中每一个状态转换背后的实现细节。1. 生命周期规范的定位在 Nacos 的 AI 领域规范体系中生命周期规范处于承上启下的位置上层由 AI Registry 规范 定义领域范围与设计原则——AI Registry 负责元数据、版本、标签、状态、scope、owner以及 draft 创建、审核、发布、强制发布、上线/下线、删除、上传、导入和下载等管理流程中间由 AI 资源模型规范 定义标准元数据行AiResource与版本行AiResourceVersion的字段结构本文讨论的生命周期规范则定义这些版本化资源通用的状态模型、流转规则与横切行为具体资源类型如 Agent 管理规范、A2A Agent 规范、MCP Server 规范可以在其基础上进一步细化规则。从源码结构看这套生命周期逻辑被集中实现在 AiResourceManager.java 中其 Javadoc 明确说明它是 Skill、AgentSpec 等资源类型共用操作服务的共享管理器将原本在各OperationServiceImpl中复制粘贴的 CAS 更新、校验、版本解析和流水线回调逻辑统一收敛到一处。生命周期相关的状态常量则集中在 AiResourceConstants.java。2. 状态模型元数据与版本的双层状态机生命周期规范将状态划分为两层元数据状态与版本状态。2.1 元数据状态状态含义enable资源可见且存在可查询版本时可用。disable资源在元数据层被禁用具体查询行为由类型规范定义。元数据状态存储在AiResource.status字段中源码常量见 AiResourceConstants.javapublic static final String META_STATUS_ENABLE enable; public static final String META_STATUS_DISABLE disable;元数据状态的切换由AiResourceManager.metaEnableDisable()实现它通过 CAS 循环更新status字段并在成功后发出ENABLE/DISABLE审计事件见 AiResourceManager.java。2.2 版本状态状态含义draft正在编辑的版本。reviewing已提交到发布流水线审核。reviewed流水线审核已完成等待显式发布、强制发布、退回编辑或重新提交。online已发布且可查询。offline已存在但从普通运行时路由中移除。五个版本状态对应源码中的五个常量AiResourceConstants.javapublic static final String VERSION_STATUS_DRAFT draft; public static final String VERSION_STATUS_REVIEWING reviewing; public static final String VERSION_STATUS_REVIEWED reviewed; public static final String VERSION_STATUS_ONLINE online; public static final String VERSION_STATUS_OFFLINE offline;AiResourceManager中还提供了三个状态判定辅助方法isDraftVersion()、isReviewingVersion()、isReviewedVersion()AiResourceManager.java所有生命周期操作都基于这些判定做分支。2.3 状态与指针的关系版本状态的记录载体不止版本行本身还包括元数据行AiResource.versionInfoJSON 中的指针摘要。按 AI 资源模型规范versionInfo包含四个字段字段含义editingVersion当前 draft 版本。reviewingVersion当前审核中版本。onlineCntonline 版本数量。labelslabel 到 version 的映射包括latest。这些字段在ai模块中由 ResourceVersionInfo.java 承载解析与兜底逻辑见AiResourceManager.requireVersionInfo()AiResourceManager.java当versionInfo为空或labels为空时会自动补一个空的HashMap保证后续 CAS 更新不会因 NPE 失败。同一资源最多应有一个editingVersion和一个reviewingVersion除非类型规范明确覆盖或多 draft 行为已有 working version 时应拒绝创建新 draft。3. 标准流程一次完整的发布之旅规范给出的标准生命周期为create/upload draft - update draft - submit - reviewing - reviewed - publish - online - offline/online toggle or delete几个关键分流规则如果没有启用发布流水线或没有匹配该资源类型的流水线节点submit可以根据类型实现直接发布force-publish会绕过流水线校验必须保持为管理操作。它仅接受draft、reviewing和reviewed版本online和offline版本必须被拒绝。流水线框架本身由 AI 发布流水线插件规范 定义本领域规范只定义 AI 资源生命周期如何响应流水线结果。在源码中AiResourceManager.doForcePublish()明确拒绝 online/offline 版本AiResourceManager.java并打出一条[FORCE-PUBLISH] Bypassing pipeline validation ...的 WARN 日志作为管理审计痕迹。4. Draft 规则草稿的创建、更新与删除Draft 是生命周期中最灵活的阶段规范规定除非类型规范定义覆盖或多 draft 行为一个资源最多应有一个 working draft创建 draft 可以创建新的元数据行也可以从 online 版本 fork更新 draft 只能修改当前 draft 版本删除 draft 会清理元数据中的editingVersion指针并删除 draft 版本行和存储内容上传操作可以是类型专属行为但除 bootstrap/import 外通常应生成 draft 版本。4.1 创建 Draft新建或 ForkAiResourceManager.initOrUpdateMetaForDraft()AiResourceManager.java实现了两种路径新建资源直接插入一条AiResource元数据行status置为enablescope通过可见性服务解析默认值versionInfo初始化为{editingVersion: version, onlineCnt: 0, labels: {}}metaVersion初始化为1L已有资源通过 CAS 更新versionInfo先调用ensureNoEditingVersion()检查不存在 working draft再把editingVersion指向新版本。从 online 版本 fork 时resolveBaseVersion()AiResourceManager.java负责解析基础版本优先级为显式basedOnVersion→latestlabel → 最大 SemVer → 最大vN。4.2 并发保护CAS 重试循环由于versionInfo是元数据行上的单个 JSON 字段所有指针更新都必须防并发覆盖。AiResourceManager提供了两套 CAS 辅助doCasLoop()通用 CAS 重试循环冲突时回调onConflictRefresh刷新非目标字段AiResourceManager.javaupdateVersionInfoCas()针对versionInfo的 mutator 式 CAS 更新冲突时重新读取最新元数据行、用mutator基于最新versionInfo重新计算AiResourceManager.java。重试次数上限是常量MAX_WORKING_VERSION_RETRY 3AiResourceConstants.java。超过重试次数或元数据行丢失时会抛出CONFLICT或SERVER_ERROR异常要求调用方重试。4.3 删除 DraftdoDeleteDraft()提供了两个重载AiResourceManager.java无精确版本的重载以editingVersion为主目标缺失时回退到reviewingVersion仅限 reviewed/draft 状态;携带精确版本的重载先删除类型自有存储与版本行最后清理 working 指针——这种存储先行的顺序保证即使版本行已删除重试时仍能通过保留的指针完成清理。两种实现都通过VersionStorageDeleter回调把类型自有存储的物理清理委托给具体类型实现符合删除 draft 会清理元数据中的editingVersion指针并删除 draft 版本行和存储内容的规范要求。5. 审核与发布规则Submit、Publish 与 Force-Publish审核与发布是生命周期规范中规则最密集的部分下面逐条结合源码展开。5.1 Submit 的目标解析Submit 会解析明确版本、当前editingVersion或处于reviewing/reviewed状态的reviewingVersion。源码resolveSubmitTarget()AiResourceManager.java的解析优先级是显式 version - editingVersion - reviewingVersion当三者都不存在时抛出NOT_FOUND即当不存在 draft、reviewing 或 reviewed 目标时Submit 必须失败。5.2 Submit 的状态约束与幂等语义requireSubmitVersion()AiResourceManager.java校验目标版本必须处于draft、reviewing或reviewed三者之一对online/offline版本调用 Submit 会返回INVALID_PARAM且不得修改版本状态或元数据指针。三种可提交状态的语义各不相同draft与reviewed进入审核或直接发布流程reviewed目标按重新提交处理不能绕过流水线直接进入发布流程reviewing目标按幂等调用处理返回当前版本且不得重复启动流水线。5.3 Reviewing 遗留结果的收敛规范特别处理了一个边界场景reviewing版本遗留当前审核轮次的APPROVED/REJECTED终态结果时视为审核完成回调未完成状态切换先收敛为reviewed再重新提交标记为historicaltrue的结果属于之前的审核轮次不能据此判定当前审核已完成Submit 仍按幂等调用返回。源码prepareSubmitVersion()AiResourceManager.java精确实现了这一规则if (pipelineInfo null || Boolean.TRUE.equals(pipelineInfo.getHistorical())) { return v; // 无结果或历史结果 - 幂等返回 } if (status ! PipelineExecutionStatus.APPROVED status ! PipelineExecutionStatus.REJECTED) { return v; // 仍在进行中 - 幂等返回 } // 当前轮次终态结果 - 收敛为 reviewed updateStatus(..., VERSION_STATUS_REVIEWED);5.4 进入审核moveToReviewingmoveToReviewing()AiResourceManager.java只允许draft或reviewed状态进入审核reviewed 即重新提交它会把版本状态置为reviewing清空editingVersion指针如果指向该版本并把reviewingVersion指向该版本——满足审核中版本必须在元数据中记录为reviewingVersion的要求。流水线执行状态可以写入publishPipelineInfo和pipeline_execution。runPipelineExecution()AiResourceManager.java会先生成一个UUID作为executionId写入IN_PROGRESS状态的publishPipelineInfo再异步串行执行流水线节点若流水线同步落空返回空结果则清除流水线信息并回退为直接发布。5.5 流水线结果回调批准与拒绝都收敛到 reviewedonPipelineComplete()AiResourceManager.java实现流水线通过和拒绝都会把版本改为reviewed无论APPROVED还是REJECTED都持久化PublishPipelineInfo并把版本状态置为reviewed对应发出REVIEW_APPROVED或REVIEW_REJECTED审计事件拒绝后如果需要继续编辑用户必须显式 redraft 该版本——doRedraft()AiResourceManager.java只接受reviewed状态或中断重试的 draft并把版本退回draft、把流水线信息标记为historicaltrue避免历史审核结果干扰新一轮提交。5.6 Publish上线、指针清理与 latest 维护Publish 会把版本改为online清理 working 指针按需增加onlineCnt并由服务端按照资源类型规范维护latestlabel。核心实现doPublish()AiResourceManager.java的执行顺序为加载元数据行并做可见性写权限检查找到版本行校验其状态必须为reviewing/reviewed/onlineonline用于兼容重复发布若存在流水线执行记录校验其状态必须为APPROVED否则拒绝发布更新版本状态为onlineCAS 更新versionInfo清空reviewingVersion指针、onlineCnt 1、labels[latest] version发出PUBLISH审计事件。5.7 Force-Publish绕过校验的管理操作doForcePublish()AiResourceManager.java在跳过流水线通过校验的同时执行与 publish 成功时一致的状态转换置online、清空 editing/reviewing 指针、onlineCnt 1、移动latest。区别在于它拒绝online/offline版本并打 WARN 日志、发出FORCE_PUBLISH审计事件确保可追溯。5.8 updateLatestLabel 参数已废弃Publish 和 force-publish 请求可以为兼容历史调用保留updateLatestLabel参数该参数已废弃新客户端不得继续发送。未指定或指定为true时发布版本成为服务端维护的最新版本。源码中doPublish()、doForcePublish()、doSystemPublish()的 Javadoc 均注明updateLatestLabel retained for compatibility and ignored——即参数被接收但总是更新latest不存在不更新 latest的路径。5.9 latest 的回退规则除非类型规范给出确定性细化成功的 publish 或 online 操作会使目标版本成为latest。当前 latest 被删除或下线时默认选择剩余 online Version 中最大的一个不存在 online Version 时删除latest。源码resolveMaxVersion()AiResourceManager.java实现了版本大小的三级比较VersionUtils.maxSemver()取最大的 SemVer 版本VersionUtils.maxVNumberVersion()取数值最大的vN兜底稳定且区分大小写的最大字符串。这与 MCP Server 规范 中 Latest 回退依次选择最大的 SemVer、数值最大的vN最后选择稳定且区分大小写的最大字符串 的描述完全一致。toggleVersionOnlineStatus()AiResourceManager.java实现 online/offline 切换上下线时同步增减onlineCnt并调用refreshLatestLabelForOnlineVersions()重新计算latest——若目标版本就是当前 latest下线后latest会回退到剩余 online 版本中最大者若已无 online 版本则移除latest。5.10 类型专属细化Agent 与 MCP 的兼容 FacadeAgent 类型只对旧 A2A 直接上线 facade 细化该规则setAsLatestfalse可以保留当前有效指针。标准 Agent publish 和 online 仍会移动latest当前指针被删除或下线时选择剩余 online Agent Version 中最大的一个。详见 Agent 管理规范 和 A2A Agent 规范。MCP 类型具有同类的兼容专用 direct-online facade通过旧 API 创建的新 Version 会立即 online旧latest参数可以保留当前有效指针。历史更新 Facade 还可以覆盖已有精确 Version但这只是需要审计的兼容例外标准 Draft/生命周期 API 绝不得复用该放宽。详见 MCP Server 规范。5.11 Serving 投影的一致性收敛当某个资源类型还维护独立的兼容 Serving 投影时生命周期 Row 是耐久的期望状态。投影在生命周期变更后收敛且只有投影重读验证成功后操作才返回成功。投影收敛失败时保留生命周期 Row供幂等重试或 Reconciler 完成投影。从源码结构看ai模块中 McpLifecycleOperationService.java、McpLifecycleManagementStateService.java 与 McpLifecycleReconciliationTask.java 共同构成了 MCP 的生命周期管理状态 Reconciler实现骨架可以推断其工作方式为生命周期操作只修改 Resource/Version 行期望状态后台 Reconciler 任务持续把 Serving 平面如 Naming Endpoint 布局向期望状态收敛。6. Labels服务端维护的 latest 与用户标签规范对 Labels 的核心要求latest是保留的默认 label表示最近发布版本latest由服务端维护。为了兼容性手动更新 labels 的请求可以包含latest但服务端必须忽略客户端传入的latest值并将当前服务端维护的latest合并到最终 labels 中Labels 映射到版本字符串且不得指向draft或reviewing版本修改 labels 不应直接修改版本内容或版本状态运行时通过 label 查询时应在请求时解析 label。源码validateAndUpdateLabels()AiResourceManager.java完整实现上述规则removeReservedLatestLabel()先剔除客户端请求中传入的latestkeyAiResourceManager.javamergeReservedLatestLabel()把当前服务端维护的latest值合并回最终 labelsAiResourceManager.javavalidateLabelsDoNotPointToWorkingVersion()逐一校验每个 label 的目标版本不是当前editingVersion或reviewingVersion否则抛INVALID_PARAMAiResourceManager.java。运行时解析 label 的入口是静态方法resolveVersion()AiResourceManager.java优先级为显式 label → 显式 version →latestlabel。这正是运行时通过 label 查询时应在请求时解析 label的实现体现——每次请求都读取当前元数据行中的 labels 映射保证解析结果总是最新。7. 删除规则存储清理与幂等重试删除是生命周期中最强调一致性的操作规范要求删除版本应删除版本行和该版本的类型自有存储内容删除资源应删除元数据、所有版本行和所有类型自有存储内容删除资源前必须加载所有版本的存储描述符再修改元数据。存储清理必须使用每个描述符中持久化的 provider 路由并尝试清理全部被引用的内容对象全部描述符加载完成后类型实现可以先把 Resource 及其 Version 转换为非 Serving 生命周期状态再收敛外部兼容投影并开始物理清理。在清理完成前这些保留 Row 是耐久重试锚点只有全部被引用的存储内容清理成功后才能删除元数据和版本行。任一清理失败时删除操作必须返回失败并保留重试所需的数据行和存储描述符只有公开 API 契约明确说明缺失资源视为成功时删除操作才应具备该幂等语义删除 online 版本时类型实现支持的情况下应更新onlineCnt或 labels领域规范要求的类型自有物理清理必须进入类型 Storage Delete Callback并且在 Metadata Row 删除前完成。源码deleteResourceWithVersions()AiResourceManager.java精确遵循先清理存储、后删除行的顺序先分页加载全部版本行listAllVersions()每页 500 条逐个调用调用方传入的VersionStorageDeleter执行类型自有存储清理任一版本存储清理失败都立即抛异常保留元数据行与版本行供重试全部成功后才删除元数据行与全部版本行并发出DELETE_RESOURCE审计事件。关于 provider 路由AI 资源模型规范 明确规定每个版本必须在AiResourceVersion.storage中持久化选定的存储 provider有效 provider 配置只在写入新版本时选择 provider已有版本的读取、draft 覆盖和删除必须按已持久化的 provider 路由缺少 provider 的历史存储描述归属于nacos_config。这意味着删除操作永远不会重新解析 provider 配置而是严格按版本行中固化的描述符执行物理清理。MCP 类型自有 Direct Naming 清理和 MCP Version Config 清理遵循相同的 Row 保留规则任一失败都表示删除尚未完成并保留 Resource/Version Row 和 Descriptor 供重试。普通被引用 Service 和 Client 自有 Runtime 状态不属于类型自有清理目标。8. Trace 与计数全量审计事件AI 资源操作应对以下操作发出 Trace/审计事件create draft、update draft、submit、review approved/rejected、publish、 force publish、online/offline、delete、label update、description update、 scope update、download源码 AiResourceTraceService.java 定义了与之对应的操作常量例如OP_CREATE_DRAFT、OP_UPDATE_DRAFT、OP_DELETE_DRAFT、OP_SUBMIT_REVIEW、OP_REVIEW_APPROVED、OP_REVIEW_REJECTED、OP_PUBLISH、OP_FORCE_PUBLISH、OP_ONLINE_VERSION、OP_OFFLINE_VERSION、OP_DELETE_VERSION、OP_DELETE_RESOURCE、OP_REDRAFT等AiResourceTraceService.java。AI 资源 Trace 通过AiResourceTraceEvent发出。默认 AI 资源 Trace 插件保留ai-resource-trace.log中的 JSON 行审计日志同时允许外部 Trace 订阅者消费同一批事件。该类的 Javadoc 给出了日志格式示例AiResourceTraceService.java{timestamp:2026-03-30T10:15:30Z,operator:admin,resource_type:skill, resource_id:my-skill,version:v1.0,operation:PUBLISH, status:SUCCESS,ip:192.168.1.1}Javadoc 同时注明该格式designed for ELK/Loki integration即默认输出可直接接入 ELK/Loki 等日志聚合平台。Trace 插件行为由 Trace 插件规范 定义计数如downloadCount只用于诊断不得定义鉴权或生命周期状态。9. 演进说明为 AI 发布流程的成熟留出空间随着 AI 发布流程成熟生命周期状态可能扩展例如支持审批链、分阶段发布、策略评估、签名或 artifact 扫描。规范明确新增状态必须定义与现有draft、reviewing、reviewed、online、offline行为的兼容关系。从 AI Registry 规范 的迁移与演进事项可以看到这一设计哲学的实际落地MCP 迁移遵循异步、单向管理状态SYNCING - LIFECYCLE_MANAGED历史 A2A AgentCard 和 Naming endpoint 数据通过滚动升级方案迁移到 Agent 模型Prompt 已有从旧 Config 形态迁移到标准 AI 资源模型的路径。所有这些迁移都要求明确迁移和兼容规则与生命周期规范的演进约束保持一致。10. 相关规范速查AI 资源生命周期规范本文主题定义状态模型与通用流转规则AI 资源模型规范定义AiResource/AiResourceVersion字段、versionInfoJSON 与存储模型AI Registry 规范定义 AI Registry 领域范围、设计原则、资源类型清单与接口面AI 发布流水线插件规范定义流水线节点 SPI、执行器与nacos.plugin.ai-pipeline.*配置项Agent 管理规范、A2A Agent 规范、MCP Server 规范Agent 与 MCP 类型的生命周期细化规则。核心源码索引AiResourceConstants.java状态与 label 常量、AiResourceManager.javaCAS 更新、Submit/Publish/Force-Publish/Redraft/DeleteDraft/DeleteResource 全量生命周期操作、AiResourceTraceService.java审计事件与操作常量、ResourceVersionInfo.javaversionInfo指针模型、McpLifecycleOperationService.java 与 McpLifecycleReconciliationTask.javaMCP Serving 投影收敛示例。理解这套生命周期规范是使用 Nacos AI Registry 管理 MCP Server、Agent、Prompt、Skill 等 AI 资产的基石它把编辑中 → 审核 → 已审核 → 上线 → 下线这一内容治理流程标准化并借助 CAS 乐观锁、耐久重试锚点和全量审计事件让 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辅助生成（AIGC），仅供参考