Nacos Skill 资源规范详解：AI Registry 中的 Skill 包模型、版本治理与客户端监听契约

Nacos Skill 资源规范详解AI Registry 中的 Skill 包模型、版本治理与客户端监听契约【免费下载链接】nacosan easy-to-use dynamic service discovery, configuration and service management platform for building AI cloud native applications.项目地址: https://gitcode.com/GitHub_Trending/na/nacosSkill技能是 Nacos AI Registry 中可复用的 AI Agent 能力包本文以 Skill 规范 为核心完整梳理 Skill 资源的身份模型、ZIP 包结构、上传预检契约、Agent Skills 标准兼容、存储索引、生命周期治理以及面向运行时客户端的轮询监听契约并结合仓库源码与示例包给出可落地的实战指引。读完本文你将掌握如何在 Nacos 中正确构建、上传、预检、发布、检索与订阅 Skill并能理解其底层持久化与版本路由机制。1. Skill 身份模型Skill 在 AI Registry 中的稳定身份由三元组构成namespaceId - skill - namenamespaceId所属命名空间隔离不同团队或环境的 Skill 资源skill资源类型固定为 skillname稳定资源名在上传时从SKILL.md的 YAML frontmatter 元数据中解析得到是后续所有管理、查询与订阅操作的唯一标识。服务端对 Skill 名的规范化贯穿整个链路在 SkillRequestUtil 的normalizeSkillFrontmatter中服务端会把SKILL.mdfrontmatter 的name与 Nacos 侧权威名称对齐首次创建以 frontmatter 为准编辑时以 Nacos 侧名为准确保包内声明与注册中心记录一致。2. Skill 包模型与目录约定Skill 是可复用的 AI Agent 能力包包含SKILL.md主描述与指令文件由 YAML frontmatter 与 Markdown 指令正文组成描述文件引用的可选资源文件标准包根目录下可包含scripts/、references/、assets/等子目录description、bizTags、owner、scope、labels、version、download count 等注册中心元数据。仓库中自带一个可直接对照的示例包 skills/nacos-skill-registry/SKILL.md其 frontmatter 仅有两行必填字段--- name: nacos-skill-registry description: Discover, install, update, merge, and publish AI skills with Nacos for personal or team skill registries. ---正文则为 Markdown 指令描述何时使用该 Skill、CLI 命令契约、操作步骤等供 Agent 激活后执行。2.1 Skill name 命名规则Skill name 应遵循上游 Agent Skills 命名规则仅使用小写字母、数字和连字符不能以连字符开头或结尾不能包含连续连字符长度不超过 64 个字符。2.2 平台元数据文件的过滤上传解析必须忽略平台生成的 ZIP 元数据文件这些文件不得作为 Skill resource 存储或分发。从 SkillZipParser 源码可以看到对应实现常量.DS_StoremacOS 目录元数据._*AppleDouble 文件如._LICENSE.txt__MACOSX/目录。同时该解析器还会剥离 UTF-8 BOM 字符并可通过以下配置项调整上传防护阈值配置键定义见 SkillZipParser 源码配置键说明nacos.ai.skill.zip.max-upload-size-mb原始压缩 ZIP 的最大上传大小MB默认值以Constants.Skills.MAX_UPLOAD_ZIP_BYTES为基准nacos.ai.skill.zip.max-entriesZIP 内最大条目数nacos.ai.skill.zip.max-uncompressed-size-mb解压后总大小上限MB非正数值会被忽略视为未配置。该过滤只作用于平台元数据不得影响普通资源文件也不得把嵌套 Skill 目录特殊隐藏。3. 上传、批量上传与上传预检契约3.1 单 Skill 上传Skill upload 接收 ZIP 包。管理端入口见 SkillAdminController 的POST /v3/admin/ai/skills/upload表单字段包括参数必填说明namespaceId否命名空间缺省按 Nacos 默认规则处理file是Skill ZIP 包multipart/form-dataoverwrite否是否覆盖已有编辑中草稿默认falsetargetVersion否期望的目标版本见版本来源优先级commitMsg否版本级提交说明创建或覆盖 draft 时必须保存为该版本描述uploadAction否上传动作扩展autoPublishIfNew否首次上传的版本是否自动发布默认false上传版本来源优先级按序取第一个合法且可用的候选SKILL.mdfrontmatter 的versionSKILL.mdfrontmatter 的metadata.version同目录_meta.json的version请求参数targetVersion服务端默认版本。服务端必须按此顺序检查显式版本候选高优先级候选非法或已被占用时若存在低优先级可用候选不得直接进入服务端版本生成逻辑。当前编辑中版本可用于覆盖但替换该编辑中版本的候选必须更大且未被占用只有所有显式候选均不可用时服务端才生成版本。因此上传请求携带targetVersion时实际版本可以不同于此前预检推算的版本。3.2 批量上传best effortBatch upload 采用 best effort 策略接收一个包含多个一级子目录每个子目录各自含SKILL.md的 ZIP 包返回兼容对象保留原有的succeeded与failed字段并在results中为每个 Skill 或候选目录返回一条结果。每条结果包含name、success、errorCode、errorMessage与可选的owner成功项successtrue、错误码SUCCESS、错误信息success失败项successfalse并返回具体失败信息。Batch upload 对等失败复用 precheck 业务码NOT_A_SKILL、INVALID_SKILL与NO_PERMISSION无法分类的失败使用UPLOAD_FAILED。当上传已有 Skill 因调用方缺少写权限而失败时结果必须在可获取时包含当前 owner。批量场景中NOT_A_SKILL与INVALID_SKILL项不计入 Skill 数量也不计入阻断 Skill 数量。只有没有有效 Skill、或所有有效 Skill 都被阻断时客户端才应禁止上传只要至少一个有效 Skill 可以上传就可以调用 batch upload。上传接口必须重新执行权限、版本与工作版本校验不能信任预检结果作为写入授权。3.3 上传预检契约上传预检接收与上传接口相同的 ZIP 包由服务端统一解析单个或批量 Skill为每个有效 Skill 返回一条精简结果。预检结果字段包括namespaceId、entryPath、skillName、reason、owner、maxPublishedVersion、parsedVersion、targetVersion、exists、editingVersion、reviewingVersion与单值precheckCode。其中entryPathSkill 或无效目录在 ZIP 中的相对路径skillName解析失败时可以为空reason说明解析失败原因maxPublishedVersion已发布过的最大版本含 ONLINE 与 OFFLINE从未发布过版本时为空不包含 DRAFT、REVIEWING、REVIEWED 版本targetVersion本次上传成功后的草稿版本。预检版本来源优先级SKILL.mdfrontmatter 的version、SKILL.mdfrontmatter 的metadata.version、同目录_meta.json的version、服务端默认版本。预检请求只包含 ZIP 包与可选 namespace不接受targetVersion——预检结果中的targetVersion是服务端根据 ZIP 内容与当前服务端状态推算的版本。precheckCode语义如下表precheckCode含义与客户端动作READY可以按targetVersion创建草稿VERSION_ADJUSTED可以创建草稿但解析版本经过规范化、替换或递增实际版本为targetVersionDRAFT_EXISTS已有编辑中草稿只能覆盖后继续上传REVIEWING_EXISTS已有审核中版本阻断上传NO_PERMISSION调用方无权修改已有 SkillNOT_A_SKILLZIP 中候选目录缺少SKILL.mdINVALID_SKILL候选目录存在SKILL.md但描述文件无效同时命中多个条件时预检必须按以下优先级返回唯一编码NOT_A_SKILL INVALID_SKILL NO_PERMISSION REVIEWING_EXISTS DRAFT_EXISTS VERSION_ADJUSTED READY客户端必须将未知编码按阻断处理。管理端预检端点见 SkillAdminController 的POST /v3/admin/ai/skills/upload/precheck。4. Agent Skills 标准兼容Nacos Skill 包与 Agent Skills Specification 上游标准对齐。上游将 Skill 定义为一个目录至少包含一个SKILL.md文件Nacos 采用该包约定作为外部内容契约并在其上增加注册中心元数据、版本、可见性与存储语义。符合标准的包遵循SKILL.md必须存在内容由 YAML frontmatter 与 Markdown 指令正文组成name与description是必填 frontmatter 字段。Nacos 将name映射为 AI resource name将description映射为可搜索元数据服务端解析 frontmatter 的逻辑见 SkillRequestUtil 的parseFrontmatterFieldlicense、compatibility、metadata与allowed-tools是标准可选字段Nacos 必须在SKILL.md中保留这些字段后续可选索引其中一部分但描述文件仍是包内容的事实来源标准包根目录可包含可选的scripts/、references/与assets/目录Nacos 将其作为 Skill resource 存储与分发。4.1 Progressive Disclosure 模型上游的 progressive disclosure 模型也是 Nacos 契约的一部分metadata 用于发现客户端激活 Skill 时才加载SKILL.md只有需要时才加载引用资源。Nacos 可以索引 metadata 用于发现但必须保持包文件边界使客户端能够执行渐进式加载。4.2 注册中心路径不执行脚本Nacos 注册中心路径upload、query、download不得执行包内脚本。脚本执行、静态分析或安全扫描属于发布流水线插件或属于显式激活 Skill 的客户端行为。相关契约由 AI 流水线插件规范 定义。4.3 社区 registry 与外部导入社区 registry 兼容能力skills CLI 与 well-known discovery 端点由 AI Registry 适配器规范 定义适配器是可选兼容面不替代标准 Skill resource 生命周期。从外部市场或 registry 导入 Skill 由 AI 资源导入插件规范 定义导入插件必须产出标准 Skill 包 artifactSkill Resource Operator 必须通过普通 Skill upload 或 draft 生命周期应用这些 artifact不得绕过包校验、可见性、存储或发布治理。5. 存储与索引5.1 元数据与内容存储Skill 元数据与版本使用ai_resource与ai_resource_version两张表Skill 文件内容通过 AI 存储保存默认存储为nacos_config——但它只是实现后端不是契约的一部分。关键约束每个版本必须在ai_resource_version的存储描述中持久化存储 provider读取与删除必须按该版本已持久化的 provider 路由有效 AI Resource 存储 provider 配置只控制新写入不得重定向已有版本缺少provider的历史存储描述归属于nacos_config更新或覆盖 draft 时必须替换完整包内容写入替换文件后旧存储描述符中已引用但替换包中未包含的文件必须在持久化新描述符前通过该版本已持久化的 provider 删除清理失败时更新必须失败并保留旧描述符以便重试清理。默认存储 provider 可通过配置键nacos.ai.storage.provider见 Constants调整存储扩展规则由 AI 存储插件规范 定义。5.2 Manifest 索引与 SearchSkill 维护一个轻量 manifest 以支持客户端发现。Manifest 由 Skill 元数据派生是索引而非生命周期状态的事实来源实现见 SkillIndexManifestService。Skill 参与通用 AI Resource Search并提供固定resourceTypeskill的资源专用 Search Facade。两者复用 AI 资源检索规范 的 document/chunk/facet、当前性、可见性与分页语义不得把 manifest 或既有管理列表当作第二套 Search 索引。Skill handler 投影 latest online Version 的 name、description、tags 与可检索 manifest 内容包内脚本、credential 与未声明的二进制内容不进入检索 chunk。客户端专用 Search Facade 为GET /v3/client/ai/skills/search接受query、可重复的tagsAll、pageNo与pageSize返回既有PageSkillBasicInfo结构端点实现见 SkillClientController。6. 生命周期治理Skill 遵循共享的 AI 资源生命周期规范版本状态包括 DRAFT、REVIEWING、REVIEWED、ONLINE、OFFLINE对应枚举定义可参考 AiConstants 中VERSION_STATUS_*常量upload根据请求选项创建或覆盖 draft可接收可选 commit message创建或覆盖 draft 时必须保存为该版本描述bootstrap内置 Skill 可以直接创建 online 元数据与版本行对应 SkillDataBootstrapInitializer提交提交 draft 或 reviewed 版本可运行发布流水线并发布或保留为 reviewed提交 reviewing 版本应按幂等调用返回元数据更新labels、online/offline、scope、bizTags 与 delete 操作按需通过 CAS 更新元数据导入导入的 Skill 遵循 upload 与 draft 规则除非该操作是服务端拥有的显式 bootstrap 流程依赖处理例如 Skill 引用 MCP tools应通过统一导入流程 preview默认不得递归导入依赖。管理端全部生命周期端点集中在 SkillAdminController可在v3/admin/ai/skills前缀下找到HTTP 方法与路径功能GET /获取 Skill 管理详情含版本治理信息与全部版本摘要GET /version获取指定版本完整内容GET /version/download以 ZIP 下载指定版本POST /upload上传 ZIP 创建或覆盖草稿POST /upload/precheck上传预检POST /upload/batch批量上传POST /draft/PUT /draft/DELETE /draft创建 / 更新 / 删除草稿POST /submit提交版本进入审核流水线POST /publish/POST /force-publish发布 / 强制发布force-publish 仅管理员POST /redraft将 reviewed 版本回退为草稿PUT /labels/PUT /biz-tags更新路由标签 / 业务标签POST /online/POST /offline上线 / 下线按版本或按 Skill 范围PUT /scope更新可见性范围PUBLIC / PRIVATEDELETE /删除 Skill7. 运行时行为与轮询监听契约7.1 下载与 md5 语义运行时客户端可以按 latest、明确版本或 label 下载 Skill ZIP 内容支持时下载应增加计数并发出 Trace 或下载事件下载计数实现见 SkillDownloadCountManager。运行时客户端可以通过name、可选version、可选label与可选md5查询 Skill若 md5 与当前命中版本的内容 md5 一致服务端返回 not-modified 错误响应不携带 ZIP 主体客户端不传 md5 时服务端必须按当前内容返回 ZIP 与对应 md5该契约用于支持轮询监听订阅应基于 md5 变更报告 Skill 内容变化但不向运行时客户端暴露宽范围管理列表能力。内容 md5 计算口径md5 是版本级字段必须在 upload 或发布写入版本内容时一次性计算并随ai_resource_version持久化运行时查询不得重新计算。计算输入是发布版本的全部包字节内容SKILL.md与所有引用资源计算口径必须与下载返回的 ZIP 字节内容保持一致避免出现客户端 md5 命中但服务端返回不同字节的偏差。对升级前已存在但缺少 md5 的历史版本服务端首次响应监听类查询时必须回填 md5 并在同一次响应中返回只要 md5 缺失或回填失败服务端必须返回带 ZIP 的 200 响应不得返回 not-modified。7.2 客户端轮询监听契约Nacos 不为 Skill 提供推送通道客户端 SDK 通过周期性条件查询GET /v3/client/ai/skills实现监听语义端点见 SkillClientControllermd5 短路与回填逻辑见 SkillClientOperationServiceImpl。契约要素如下200 响应头响应头值Content-Typeapplication/zipContent-Dispositionattachment;filenamename.zipETagmd5X-Nacos-Skill-Md5md5X-Nacos-Skill-Resolved-Versionversion反映 label/latest 等路由参数解析后的真实版本响应构造见 SkillRequestUtil 的buildSkillZipResponseWithMd5与applyListenerHeaders。304 响应客户端传入 md5 与服务端命中版本 md5 一致时返回304 Not Modifiedbody 必须为空必须携带ETag与X-Nacos-Skill-Md5按 RFC 7232 不得携带Content-Type不得携带X-Nacos-Skill-Resolved-Version304 不应再次声明实体元信息。404 响应skill 名合法但资源缺失时返回404与业务错误码20004客户端必须将其翻译为本地缓存淘汰并发布内容缺失事件不得视为暂时性错误重试。轮询调度SDK 必须采用单线程schedule 任务尾端自调度模式使下一次查询的起点为上一次任务的结束时刻而非开始时刻避免服务端慢响应导致请求堆积SDK 不应使用scheduleAtFixedRate。频率默认值与覆盖默认轮询间隔10000毫秒AiConstants.DEFAULT_AI_CACHE_UPDATE_INTERVAL见 AiConstants首次查询发生在订阅后第一个 interval 之后——订阅本身已同步预热缓存因此不应再立即发起一次轮询客户端通过Properties传入nacosAiSkillCacheUpdateInterval即AiConstants.AI_SKILL_CACHE_UPDATE_INTERVAL覆盖默认值单位毫秒该配置仅作用于 Skill与 Prompt、MCP Server、AgentCard 等其他资源的轮询配置相互独立对应各自的nacosAiPromptCacheUpdateInterval、nacosAiMcpServerCacheUpdateInterval、nacosAiAgentCardCacheUpdateInterval。取消语义unsubscribeSkill必须取消对应任务并移除 md5 缓存项且不得继续向服务端发起轮询请求。8. 使用示例以 nacos-cli 操作 Skill 生命周期仓库自带的 skills/nacos-skill-registry/SKILL.md 是一个真实的 Skill 包示例展示了 Skill 在 Agent 场景中的完整用法以nacos-cli为工具。其核心命令与本文上述契约一一对应nacos-cli skill-list搜索与列出可用 Skill对应客户端列表/搜索查询nacos-cli skill-get name下载并本地安装 Skill对应运行时下载契约支持--version、--label精确路由nacos-cli skill-upload path上传 Skill 并创建编辑中草稿对应 upload 端点nacos-cli skill-review name提交草稿进入审核对应 submit 端点nacos-cli skill-release name --version version发布已审核版本上线对应 publish 端点nacos-cli skill-describe name查看 Skill 元数据与各版本状态对应管理详情查询。典型的发布工作流为skill-upload→skill-review→ 等待审核通过 →skill-release与第 6 节的 DRAFT → REVIEWING → REVIEWED → ONLINE 生命周期严格对应。9. 待对齐问题与演进说明9.1 待对齐问题规范明确列出以下待对齐事项upload 时强制执行完整的上游 name 校验规则判断哪些标准可选 frontmatter 字段应索引到 Nacos metadata同时保持SKILL.md作为包内容事实来源如果未来 Agent Skills 版本改变包结构、frontmatter 字段或 progressive disclosure 建议需要定义兼容行为。9.2 演进说明Skill 包约定可能随 AI Agent framework 演进而变化新的 Skill 包格式应定义解析、校验、存储与迁移规则除非明确废弃已有 Skill 版本必须保持可获取。结语Nacos Skill 资源规范以 Agent Skills 上游标准为包内容契约叠加了注册中心身份、版本治理、可见性、存储 provider 与客户端监听语义形成一套标准兼容、注册中心强化的完整体系。无论是通过管理 API 完成上传预检与发布治理还是通过客户端 SDK 实现基于 md5 的轻量轮询监听理解 skill-spec.md 中定义的这些领域契约都是将 Skill 能力正确接入 Nacos AI Registry 的前提。配套的 AI 资源生命周期规范、AI 资源检索规范 与 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），仅供参考