企业官网建设流程全解析

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

Skill（技能）是 Nacos AI Registry 中可复用的 AI Agent 能力包，本文以 Skill 规范 为核心，完整梳理 Skill 资源的身份模型、ZIP 包结构、上传预检契约、Agent Skills 标准兼容、存储索引、生命周期治理以及面向运行时客户端的轮询监听契约，并结合仓库源码与示例包给出可落地的实战指引。读完本文，你将掌握如何在 Nacos 中正确构建、上传、预检、发布、检索与订阅 Skill，并能理解其底层持久化与版本路由机制。

1. Skill 身份模型

Skill 在 AI Registry 中的稳定身份由三元组构成：

namespaceId -> skill -> name

• namespaceId：所属命名空间，隔离不同团队或环境的 Skill 资源；
• skill：资源类型固定为 skill；
• name：稳定资源名，在上传时从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_Store（macOS 目录元数据）；
• ._*AppleDouble 文件（如._LICENSE.txt）；
• __MACOSX/目录。

同时该解析器还会剥离 UTF-8 BOM 字符，并可通过以下配置项调整上传防护阈值（配置键定义见 SkillZipParser 源码）：

非正数值会被忽略（视为未配置）。该过滤只作用于平台元数据，不得影响普通资源文件，也不得把嵌套 Skill 目录特殊隐藏。

3. 上传、批量上传与上传预检契约

3.1 单 Skill 上传

Skill upload 接收 ZIP 包。管理端入口见 SkillAdminController 的POST /v3/admin/ai/skills/upload，表单字段包括：

上传版本来源优先级（按序取第一个合法且可用的候选）：

1. SKILL.mdfrontmatter 的version；
2. SKILL.mdfrontmatter 的metadata.version；
3. 同目录_meta.json的version；
4. 请求参数targetVersion；
5. 服务端默认版本。

服务端必须按此顺序检查显式版本候选：高优先级候选非法或已被占用时，若存在低优先级可用候选，不得直接进入服务端版本生成逻辑。当前编辑中版本可用于覆盖，但替换该编辑中版本的候选必须更大且未被占用；只有所有显式候选均不可用时，服务端才生成版本。因此，上传请求携带targetVersion时，实际版本可以不同于此前预检推算的版本。

3.2 批量上传（best effort）

Batch upload 采用 best effort 策略，接收一个包含多个一级子目录（每个子目录各自含SKILL.md）的 ZIP 包，返回兼容对象：保留原有的succeeded与failed字段，并在results中为每个 Skill 或候选目录返回一条结果。每条结果包含：

• name、success、errorCode、errorMessage与可选的owner；
• 成功项：success=true、错误码SUCCESS、错误信息success；
• 失败项：success=false并返回具体失败信息。

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。其中：

• entryPath：Skill 或无效目录在 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语义如下表：

同时命中多个条件时，预检必须按以下优先级返回唯一编码：

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 的parseFrontmatterField）；
• license、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 包 artifact，Skill 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 索引与 Search

Skill 维护一个轻量 manifest 以支持客户端发现。Manifest 由 Skill 元数据派生，是索引而非生命周期状态的事实来源（实现见 SkillIndexManifestService）。

Skill 参与通用 AI Resource Search，并提供固定resourceType=skill的资源专用 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，返回既有Page<SkillBasicInfo>结构（端点实现见 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前缀下找到：

7. 运行时行为与轮询监听契约

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实现监听语义（端点见 SkillClientController，md5 短路与回填逻辑见 SkillClientOperationServiceImpl）。契约要素如下：

200 响应头：

响应构造见 SkillRequestUtil 的buildSkillZipResponseWithMd5与applyListenerHeaders。

304 响应：客户端传入 md5 与服务端命中版本 md5 一致时，返回304 Not Modified：

• body 必须为空；
• 必须携带ETag与X-Nacos-Skill-Md5；
• 按 RFC 7232 不得携带Content-Type；
• 不得携带X-Nacos-Skill-Resolved-Version（304 不应再次声明实体元信息）。

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