Spring AI Alibaba 1.x 系列【13】Nacos AI Agent 管理平台与 Skill Registry 发布详解：从配置骨架到验证落地

1. 从配置中心到 AI 资源中心我为什么要在 Nacos 里管 Agent 和 Skill如果你已经在用 Nacos 做 Spring Cloud 的配置中心那接下来这一步会有点意思Nacos 从 3.x 开始把自己从「配置 服务发现」扩展成了「AI Agent 管理平台」。也就是说你原来放application.yml的那个控制台现在可以放 Agent 元数据、MCP Server 注册项、Prompt 模板以及本篇的重点——Skill Registry。先把概念说清楚避免后面配置时对不上号。Skill Registry是 Nacos 提供的 Skill 管理中心你可以把它理解成团队私有的 Skill 仓库Skill 的存储、版本管理、安全审核、灰度分发都集中在这里。它解决的是企业落地 Skill 时的四个老大难——安全恶意代码、凭证泄漏、权限谁能看谁能改、稳定性版本冲突、回滚、治理审计追溯。而AI Agent 管理平台则是把这些资源Agent、MCP、Skill、Prompt、AgentSpec统一注册、发现和治理的控制面。这篇适合谁已经用 Nacos 做配置中心、现在想用 Spring AI Alibaba 1.x 把 Agent 和 Skill 管起来的 Java 开发者。我会给出一份可复制的 Nacos 配置骨架含 Skill Registry 注册项和 Agent 元数据再配一段 TaoToken 统一 Key/API 通道的settings.json最后演示一次发布后通过 API 验证 Skill 能被 Agent 正确拉取。整个过程你照着敲就能跑通。需要提前说明一点Skill 的发布流程里「未通过不发布」是硬约束安全审核是系统强约束而不是文档规范所以下面配置里审核相关的字段不要图省事跳过。2. 前置准备Nacos 3.2 环境与 TaoToken 统一通道2.1 装 Nacos 3.2 并确认 Skill Registry 可用Skill Registry 是 Nacos 3.2.0 开始提供的Agent 注册中心A2A Registry从 3.1.0 就有。所以版本别低于 3.2.0否则控制台里根本看不到 Skill 管理入口。MacOS/Linux 一条命令装curl -fsSL https://nacos.io/nacos-installer.sh | bashWindows PowerShelliwr -UseBasicParsing https://nacos.io/nacos-installer.ps1 | iex脚本跑完会自动打开控制台。装好后先确认两件事控制台左侧能看到 Skill 管理以及nacos-cli可用。nacos-setup --help nacos-cli --helpnacos-cli后面验证 Skill 拉取时会用到先确认它在 PATH 里。2.2 用 TaoToken 统一 Key/API 通道Agent 要调模型最烦的是每个模型厂商一套 Key、一套 Base URL散落在各个配置文件里。我习惯用 TaoToken 做统一通道一个 Key 走所有模型Base URL 固定换模型只改 model 字段。先到控制台建 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole建完 Key在项目里放一份settings.json让 Agent 和本地工具都读它{ api_key: sk-你的TaoTokenKey, base_url: https://taotoken.net/api, default_model: claude-sonnet-4-5, models: { fast: gpt-4o-mini, reasoning: claude-sonnet-4-5 } }注意base_url用https://taotoken.net/api不要带任何查询参数。Key 别提交进 Git放.gitignore里或者用环境变量注入。提示如果你后面要跑 Claude Code 这类编码 AgentTaoToken 也提供了对应的接入方式配置逻辑和上面一致都是统一 Base URL 单 Key。3. 可复制的 Nacos 配置骨架Skill Registry 注册项 Agent 元数据这一节是核心。Nacos 里的 AI 资源分几类我按「先注册 Skill再注册 Agent最后把两者关联」的顺序给配置。3.1 Skill Registry 注册项Skill 在 Nacos 里以资源形式存在关键字段包括名称、版本、标签、可见性和审核状态。下面是一份 Skill 注册的配置骨架字段名按 Nacos 3.2 的约定来nacos: ai: skill: registry: enabled: true namespace: ai-prod skills: - name: mysql-query version: 1.0.0 description: 安全执行只读 SQL 查询返回结构化结果 tags: - dev - stable visibility: PRIVATE audit: required: true pipeline: default-security entry: SKILL.md - name: redis-query version: 1.0.0 description: 查询 Redis 键值与 TTL tags: - stable visibility: PRIVATE audit: required: true pipeline: default-security entry: SKILL.md几个字段值得单独说version是不可变的一旦发布就不能改内容只能发新版本。tags用来做灰度比如dev指向新版本、stable指向稳定版本出问题切标签就能秒级回滚。visibility支持公开、私有、指定范围团队内部用PRIVATE。audit.required设成true后Skill 必须过安全审核流水线才能发布这是「未通过不发布」的落地方式。3.2 Agent 元数据AgentCardAgent 注册走 A2A Registry核心是 AgentCard。下面这份元数据描述了一个能调用上面两个 Skill 的 Agentnacos: ai: agent: registry: enabled: true namespace: ai-prod agents: - name:>spring: ai: alibaba: nacos: server-addr: ${NACOS_ADDR:127.0.0.1:8848} namespace: ai-prod agent: enabled: true registry: nacos skill: enabled: true registry: nacos auto-refresh: trueauto-refresh: true让 Skill 描述和工具定义支持运行时热更新改了不用重启服务。这点在调试 Skill 时特别省事。4. 发布与验证确认 Skill 能被 Agent 正确拉取配置写完接下来是发布和验证。很多人卡在「配置看着对但 Agent 拉不到 Skill」所以这一步我拆细一点。4.1 发布 Skill 并过审核先把 Skill 内容按SKILL.md组织好然后通过 CLI 发布。发布前审核流水线会自动跑# 列出当前可用 Skills确认注册项已生效 nacos-cli skill-list --name mysql-query --page 1 --size 20 # 下载指定 Skill 到本地验证内容可拉取 nacos-cli skill-get mysql-query -o ~/.skills如果审核没过skill-list里这个 Skill 的状态会停在审核中不会进入可分发状态。这时候去看审核日志常见问题是 Skill 里硬编码了凭证或者有可疑的 shell 调用。4.2 用 API 验证 Agent 能拉到 Skill发布完成后最直接的验证是调 Nacos 的 Skill 查询接口确认 Agent 视角能看到这个 Skill。先拿访问令牌再查# 获取 access token TOKEN$(curl -s -X POST http://127.0.0.1:8848/nacos/v1/auth/login \ -d usernamenacospasswordnacos | jq -r .accessToken) # 以 Agent 身份查询可拉取的 Skill 列表 curl -s http://127.0.0.1:8848/nacos/v1/ai/skill/list?namespaceIdai-prodagentNamedata-assistant \ -H accessToken: ${TOKEN} | jq返回里应该能看到mysql-query和redis-query且visibility和version与配置一致。如果返回空八成是 Agent 的capabilities没写对或者 Skill 的visibility没放开给这个 Agent。4.3 端到端跑一次 Agent 调用最后让 Agent 真正调一次 Skill确认链路通。用 TaoToken 的模型对话接口做一次快速验证curl -s https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的TaoTokenKey \ -H Content-Type: application/json \ -d { model: claude-sonnet-4-5, messages: [ {role: user, content: 用 mysql-query skill 查一下 users 表前 5 行} ] } | jq .choices[0].message.content如果 Agent 配置正确它会通过 Nacos 发现mysql-querySkill走审核通过的版本执行查询。这一步跑通说明「Skill 注册 → 审核 → 发布 → Agent 发现 → 调用」整条链路是通的。注意验证阶段建议用只读 Skill别一上来就接生产库的写操作。Skill 的权限边界在 Nacos 里是按命名空间和可见性隔离的先在测试命名空间跑通再迁生产。5. 本篇常见错排查控制台看不到 Skill 管理入口版本低于 3.2.0。Skill Registry 是 3.2.0 才有的升级 Nacos 即可。nacos-cli skill-list报连接失败SKILLS_API_URL没配或端口不对。批量拉取场景下需要显式指定export SKILLS_API_URLhttp://127.0.0.1:9080 npx skills add mysql-query redis-query注意这里是 9080 端口不是控制台的 8848。Agent 查询 Skill 返回空三个地方按顺序查——Agent 的capabilities是否包含skill:mysql-querySkill 的visibility是否对该 Agent 开放命名空间是否一致ai-prod对ai-prod。Skill 发布卡在审核中审核流水线没过。看审核日志常见是凭证泄漏或可疑代码。修完内容发新版本别想着改旧版本版本不可变。改了 Skill 描述但 Agent 没更新确认auto-refresh: true生效或者手动触发一次刷新。热更新依赖 Nacos 配置中心的推送网络不通会静默失败。TaoToken 调用返回 401Key 写错或base_url带了多余路径。base_url就是https://taotoken.net/api不要拼/v1之外的额外段。6. 把 Key 和接入文档收进日常流程跑通之后建议把两件事固定下来一是 Key 的获取和轮换走控制台二是接入细节随时查文档别靠记忆。Key 管理入口https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys接入文档Base URL、模型名、参数说明都在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc如果你后面要长期跑编码类 Agent比如让 Agent 自己改代码、跑测试那用 Coding Plan 会更省心额度模型和按次调用不一样https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan想先在网页上试模型效果、确认 Skill 返回格式再写进代码用模型对话页最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat最后留个我踩过的坑Skill 的version字段别用latest这种浮动值Nacos 里版本是不可变标识浮动标签交给tags去做。我一开始把version写成latest结果灰度回滚时切标签切不动排查了半天才发现是版本标识本身的问题。把版本号写死、灰度靠标签回滚就是改一行标签映射的事。