Nacos AI 资源导入插件ai-resource-import全面指南SPI 契约、统一配置与内置 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本篇技术指南围绕 AI 资源导入插件规范 展开系统讲解 Nacos 如何通过ai-resource-import插件类型从外部 Registry 或 Skill 市场导入 MCP Server、Skill 等 AI 资源。读完本文你将掌握该插件的统一配置体系、Builder/Service 双层 SPI 契约、内置 importermcp-official、mcp-registry-protocol、skills-sh、skills-well-known的配置与工作原理、统一导入 API 流程、依赖处理预留策略以及 SSRF 防护在内的完整安全要求。为什么需要 AI 资源导入插件Nacos 的 AI Registry 负责 AI 资源的身份、鉴权、可见性、存储、版本生命周期、发布流水线与 Trace 行为但 AI 资源的来源往往在外部官方 MCP Registry、企业内部的 Skill 市场、私有 MCP registry甚至 Git 索引。运维人员希望从外部发现候选资源 - 转换 - 进入 Nacos AI Registry 治理流程这正是 AI 资源导入插件要解决的转换边界问题。该插件类型以ai-resource-import暴露给核心插件管理器通用插件生命周期与状态规则由 Nacos 插件化规范 定义导入后的资源治理规则仍由 AI Registry 规范、资源类型规范以及资源 Operator 负责。核心原则是导入插件只拥有外部来源协议与外部模型 - Nacos 导入 artifact的转换逻辑不拥有 Nacos 资源身份、鉴权、可见性、存储、版本、发布或 Trace 行为。在代码层面SPI 契约定义在plugin/ai模块的importer包下与 AI storage、visibility 等插件类型保持一致默认 importer 实现则放在plugin-default-impl下的nacos-default-ai-importer-plugin模块而不是 AI Registry 领域模块。职责划分明确ai模块导入 API、插件路由、校验和资源 Operatorplugin-default-impl默认外部来源适配器及对应的配置 definitions。核心概念从 Candidate 到 Artifact 再到资源规范定义了六个核心概念它们贯穿整个导入流程概念含义Managed importer通过pluginName标识的稳定 Builder 插件一个实现表示一个外部来源。Import service从 Builder 的一份不可变配置快照创建的请求级协议适配器。Candidatesearch 阶段返回的外部资源摘要不包含可导入完整内容。Artifact可被资源 Operator 应用的 payload 和元数据。Resource operator校验并写入某一资源类型的 Nacos 领域服务。Dependency被导入 artifact 引用的其他资源例如 Skill 依赖 MCP tools。值得特别注意的是 API 字段的语义约定API 现有sourceId字段等于 managedpluginNameAPI 现有pluginName字段继续作为 importer/protocol metadata 返回以兼容 Console。终端用户只选择sourceId导入请求不得提交任意 endpoint URL、IP 地址、凭证或 registry base path——这些全部来自运维配置这是整个安全模型的地基。执行形态路由型统一管理插件ai-resource-import是路由型统一管理插件同一进程可以加载多个 Builder 实现例如mcp-official、mcp-registry-protocol、skills-well-known或企业内部市场 importer每次请求中领域管理器直接把sourceId解析为一个已启用 Builder。Importer 在 search 阶段返回 candidate在 validate 和 execute 阶段按选中项拉取 artifact随后 AI Registry 导入管理器根据 artifact 的resourceType路由到对应资源 Operator。整体调用链如下sourceId(managed pluginName) - AiResourceImportServiceBuilder(当前配置快照) - 请求级 AiResourceImportService - AiResourceOperator(resourceType)Builder 与 Service 的生命周期差异从源码契约 AiResourceImportServiceBuilder.java 可以看出Builder 是进程级稳定实例而 AiResourceImportService.java 是请求级适配器Builder 实例只被发现一次由统一PluginManager注册、恢复持久化 state、通过标准配置来源链解析并applyConfig之后才暴露给导入请求search 每次请求创建一个 Servicevalidate 和 execute 各自创建一个 Service 并在请求内复用全部选中项最终在finally中关闭Service 的close()默认实现可以为空操作源码中default void close() {}。search应无副作用并且不得返回 MCP tools、Skill 包内容、secret 或其他完整可导入 payloadfetch可以访问外部来源并返回字节或结构化 payload但不得写入 Nacos 资源——写入由 Operator 完成。统一配置开关、state key 与 item key模块总开关为nacos.plugin.ai-resource-import.enabledtrue旧nacos.ai.resource.import.enabled作为 alias。标准 key 只要存在就优先默认值为true只有显式配置false才关闭 AI Resource Import。每个实现使用标准插件 state keynacos.plugin.ai-resource-import.{pluginName}.enabledtrue每个配置项使用nacos.plugin.ai-resource-import.{pluginName}.{itemKey}value一份pluginName只表示一个来源不支持通过配置把同一个 managed 实现复制为多个 endpoint 实例需要另一个固定来源时应提供具有不同pluginName的 Builder。旧的nacos.ai.resource.import.sources[N].*、Source 模型和 Source Provider SPI 已被移除且由于旧模型允许一个 importer 创建多个 source 实例不提供自动迁移。配置项定义与生效模式内置 Builder 的配置定义在 AbstractAiResourceImportServiceBuilder.java 中统一构建每个ConfigItemDefinition都带有效果模式RESTART/RUNTIME和默认值。公共 effective configuration 汇总如下Item key生效范围适用实现含义endpointRESTART可配置 endpoint 实现Registry 或 marketplace root。allow-httpRESTART可配置 endpoint 实现允许非 HTTPS 目标。allow-private-networkRESTART可配置 endpoint 实现允许本地或私网目标。display-nameRUNTIME全部内置实现API 和 Console 展示名称。descriptionRUNTIME全部内置实现API 和 Console 描述。max-item-countRUNTIME全部内置实现单请求结果或文件数上限默认500。max-artifact-sizeRUNTIME全部内置实现响应或 artifact 字节上限默认10485760。常量定义可在 AiResourceImportConstants.java 中核对DEFAULT_MAX_ITEM_COUNT 500、DEFAULT_MAX_ARTIFACT_SIZE 10 * 1024 * 102410MB。解析时对非正数会直接抛IllegalArgumentExceptionpositiveInt/positiveLong校验。固定 endpoint 实现mcp-official、skills-sh不暴露endpoint、allow-http或allow-private-networkdefinitions也不接受旧 endpoint override——其来源身份和 endpoint 属于实现契约。在AbstractAiResourceImportServiceBuilder中构造参数fixedEndpoint非空时configurableEndpoint为 false从而跳过这三个配置项的定义与解析。SPI 契约Builder 与 Service 方法要求Builder 是稳定的 managed plugin并实现PluginConfigSpecBuilder 方法要求pluginName()稳定 managed pluginName也是 APIsourceId。importerType()兼容 importer/protocol metadata返回到 APIpluginName。displayName()/description()从当前已接受配置快照返回展示 metadata。supportedResourceTypes()该来源可以产出的资源类型。getConfigDefinitions()该实现拥有的全部配置定义。applyConfig(config)原子替换不可变 effective configuration 快照。build()从一份快照创建一个请求级 Service不再接收额外 Properties。导入服务实现Service 方法要求search(context)从配置来源返回 candidate 分页结果只包含必要元数据。fetch(context, item)从配置来源拉取一个被选择的 artifact。close()释放请求级资源默认实现可以为空操作。context见 AiResourceImportContext.java包含 namespace、resource type、query、cursor、limit、options、requestId、operator、clientIp不再携带 source 配置或用户传入的 endpoint——source 配置属于 managed builder 快照被刻意排除在请求上下文之外。导入 Artifact 结构Artifact见 AiResourceImportArtifact.java是导入边界对象不是持久化资源模型资源 Operator 负责把它转换为当前存储和生命周期模型字段含义resourceType目标 Nacos AI 资源类型。externalId来源内部的稳定 ID。name候选 Nacos 资源名如已知。version候选版本如已知。description资源描述。payloadKindPayload 形态例如MCP_DETAIL、SKILL_ZIP或JSON。payload拉取到的字节或结构化数据。dependencies可选的被引用资源。sourceMetadata用于 Trace 和诊断的非 secret 来源元数据。源码中 Artifact 还包含payloadJson结构化 payload 的 JSON 形态与checksum字段分别用于承载 JSON payload 与校验和供 Operator 校验内容完整性。Resource Operator领域内的写入者Resource Operator 位于 AI Registry 领域内不属于导入插件。它们通过资源类型当前的服务层校验并写入 artifactMCPOperator 调用当前McpOperationService完整兼容 application contract 和相关校验服务。生命周期 reconciliation 仍处于SYNCING时该完整契约使用历史策略并在写成功后立即 reconcile原子切换后则使用标准生命周期策略、MCP Version Storage 和按标准名称调度的异步 Search 任务。切换前后 Import 插件和统一导入 API 保持不变且不得再直接调用已移除的 Config-backedMcpServerOperationService。SkillOperator 保持 Skill 包边界通过 Skill upload 或 draft 生命周期 API 写入。导入成功后如果 artifact 包含sourceMetadata.artifactUrlSkill Operator 应将该 URL 记录为导入后资源的来源字段ai_resource.c_from如果没有artifactUrl则回退使用sourceMetadata.source。Skill 冲突处理Skill 冲突处理遵循 AI 资源 working-version 生命周期如果 Skill 不存在导入会创建新草稿如果 Skill 已存在且没有 editing/reviewing 版本导入会创建下一个草稿版本如果 Skill 已存在 editing 或 reviewing 版本validate 返回 working-version 冲突execute 默认跳过该项只有overwriteExistingtrue时才允许覆盖当前可编辑草稿或按 Skill 服务生命周期创建新草稿。内置 Importer四个默认来源默认内置 importer 由plugin-default-impl下的nacos-default-ai-importer-plugin模块提供Managed pluginNameAPI importer type资源Endpoint默认 statemcp-officialmcp-registrymcp固定官方 MCP Registry endpointenabledmcp-registry-protocolmcp-registrymcp必须由运维配置disabledskills-shskills-shskill固定https://skills.shenabledskills-well-knownskills-well-knownskill必须由运维配置disabled固定内置实现保持当前 Console 展示 metadatamcp-officialdisplay name 为Official MCP Registrydescription 为Import MCP servers from the official MCP registry.skills-shdisplay name 为skills.shdescription 为Import Skills from skills.sh.。这些元数据可以在 McpOfficialImportServiceBuilder.java固定 endpoint 为https://registry.modelcontextprotocol.io/v0/servers和 SkillsShImportServiceBuilder.javaSKILLS_SH_ENDPOINT https://skills.sh中逐一印证。mcp-registry-protocol与skills-well-known则由 McpRegistryImportServiceBuilder.java 与 SkillWellKnownImportServiceBuilder.java 提供构造参数传入的 fixed endpoint 为null因此可配置 endpoint。运维配置示例私有 MCP Registrynacos.plugin.ai-resource-import.mcp-registry-protocol.enabledtrue nacos.plugin.ai-resource-import.mcp-registry-protocol.endpointhttps://registry.example.com/v0/serversMCP Registry 实现在 search 阶段返回摘要在 fetch 阶段返回MCP_DETAILartifact。运维配置示例私有 Skill well-known 来源nacos.plugin.ai-resource-import.skills-well-known.enabledtrue nacos.plugin.ai-resource-import.skills-well-known.endpointhttps://skills.example.comSkill well-known 实现连接运维配置的 Skill marketplace 或 registry rootendpoint 不是 well-known 路径时它先尝试/.well-known/agent-skills再尝试/.well-known/skillsendpoint 已是 well-known 路径时直接使用。两类 Skill well-known discovery 版本Importer 必须同时支持 v0.1.0legacy与 v0.2.0 两个版本v0.1.0 或 legacy 来源通过缺失$schema字段或https://schemas.agentskills.io/discovery/0.1.0/schema.jsonschema URI 识别v0.2.0 来源通过https://schemas.agentskills.io/discovery/0.2.0/schema.jsonschema URI 识别。v0.1.0 / legacy的index.json使用每个 Skill 的文件列表{ skills: [ { name: demo-skill, description: Demo skill, files: [ SKILL.md, docs/guide.md ] } ] }Search 阶段只能返回name、description和非 secret metadata。Fetch 阶段按{wellKnownBase}/{skillName}/{file}拉取被选择 Skill 的文件校验文件路径安全性组装为标准 Skill ZIP artifact并交给 Skill Resource Operator 通过普通 Skill upload 或 draft 生命周期写入。v0.2.0的index.json使用 artifact 引用{ $schema: https://schemas.agentskills.io/discovery/0.2.0/schema.json, skills: [ { name: demo-skill, type: skill-md, description: Demo skill, url: /.well-known/agent-skills/demo-skill/SKILL.md, digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef }, { name: archive-skill, type: archive, description: Demo archive skill, url: /.well-known/agent-skills/archive-skill.tar.gz, digest: sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef } ] }Search 阶段不得下载 artifact 内容只能暴露name、description、type、url、digest、schema version 和其他 Console 所需的非 secret metadata。Fetch 阶段必须以 index URL 为基准解析url在服务端下载被选择的 artifact校验sha256digest并将 artifact 转换为标准 Nacos Skill ZIP 边界。内置 importer 必须支持skill-md单文件 artifact以及 ZIP、TAR、TAR.GZ、TGZ 形式的archiveartifact。Archive 解包必须校验路径安全性限制文件数量和解压后总大小并在交给 Skill Resource Operator 前拒绝不支持的 archive 格式。skills.sh 发现流程skills-shimporter 使用内置固定的https://skills.shAPI root遵循 skills.sh CLI 的发现流程对应实现见 SkillsShImportService.java其中API_SEARCH /api/search、API_DOWNLOAD /api/download、DEFAULT_SEARCH_QUERY skill、MIN_SEARCH_QUERY_LENGTH 2Search 阶段调用GET {endpoint}/api/search?q{query}limit{limit}并且只返回候选摘要如果用户 query 为空importer 应默认使用skill作为查询词如果 trim 后的用户 query 只有 1 个字符importer 应在本地拒绝请求skills.sh 要求 query 至少 2 个字符。Fetch 阶段根据被选择候选的source和skillId调用GET {endpoint}/api/download/{owner}/{repo}/{skillId}校验返回文件路径组装标准 Skill ZIP artifact并交给 Skill Resource Operator 写入。Search metadata 只能暴露 skills.sh 页面 URL、GitHub repository URL、repository source、skill id、安装次数等非 secret 信息Fetch source metadata 可以额外包含 download snapshot hash。Fetch 必须将sourceMetadata.artifactUrl设置为对应的 skills.sh 页面 URL使导入后的 Skill 资源记录具体外部来源而不是local。旧配置 alias 与迁移旧nacos.plugin.ai.importer.*中 display、description、limits、state 和可配置 endpoint 等价 key 可以作为一个迁移周期的 alias使用 alias 时应输出迁移 WARN。旧固定来源 endpoint override、auth-ref、source/global timeout、max-page-count、block-private-network、全局 defaults 和任意properties.*被移除——因为它们未生效或与 managed identity 冲突。统一导入 API 与浏览器流程Nacos 暴露统一的 Admin 和 Console 导入 API方法路径目的GET/v3/admin/ai/import/sources查询可用导入来源。POST/v3/admin/ai/import/search根据 source 查询候选摘要。POST/v3/admin/ai/import/validate校验被选择的候选并返回冲突、依赖和 warning。POST/v3/admin/ai/import/execute导入被选择的候选。GET/v3/console/ai/import/sourcesConsole 来源列表。POST/v3/console/ai/import/searchConsole search 流程。POST/v3/console/ai/import/validateConsole validate 流程。POST/v3/console/ai/import/executeConsole execute 流程。所有统一 API 必须使用标准 v3ResultT响应、错误和鉴权约定。统一导入 API 遵循 Nacos v3 表单绑定约定Controller 方法应暴露*Form参数而不是直接以 request model 作为RequestBody契约标量字段可以通过 query 参数或application/x-www-form-urlencoded表单字段提交selectedItems、options等复杂导入字段应作为 JSON 字符串表单字段提交并由 Form 对象转换为内部 request model。推荐的浏览器流程list sources(resourceType) - select sourceId - search candidates by sourceId and query - user selects candidates - validate selected candidates - show conflicts, dependency warnings, and overwrite options - execute selected candidates交互约束浏览器 search 后不应默认选中候选项可以提供显式全选控件并且用户全选后仍必须能够逐项反选如果提供导入全部有效项动作该动作只能作用于用户显式选择并已完成校验的候选项且应包含同一 source 下多次校验批次累积出的有效候选项。浏览器不得接收完整 artifact——MCP 的 tools/specification、Skill zip 或其他可导入内容只允许在服务端 Importer、Import Manager 和 Resource Operator 之间流转。旧 MCP 导入兼容现有 MCP 导入 API 可以在兼容窗口期内保留POST /v3/console/ai/mcp/import/validate POST /v3/console/ai/mcp/import/executevalidate 和 execute 端点应通过兼容 adapter 路由到统一导入管理器不应继续作为独立导入实现扩展。GET /v3/console/ai/mcp/importToolsFromMcp不属于外部 registry 导入兼容范围它是 Console 在构建 MCP Server schema 时从用户自有 MCP runtime endpoint 拉取 tools 的辅助能力不属于 AI 资源市场或 registry 导入流程。该辅助接口会让 Console 进程向请求指定的 MCP runtime 发起服务端网络连接公网目标默认允许私网或本地目标默认拒绝只有baseUrl解析得到的每一个此类地址都命中nacos.console.ai.mcp.import.allowed-private-addresses时才允许访问。运维可以通过nacos.console.ai.mcp.import.enabledfalse关闭全部出站 tools 导入。请求baseUrl只能使用 HTTP 或 HTTPSendpoint参数必须是相对 URI不得替换baseUrl的 scheme 或 authority请求不得跟随重定向私网白名单中存在非法项时必须按拒绝处理不得忽略非法项后继续访问。兼容端点已废弃仅保留至 Nacos 3.3.x并计划在 Nacos 3.4.0 移除端点默认关闭。运维可以通过nacos.core.api.compatibility.enabledtrue临时重新开启客户端应迁移到/v3/{admin|console}/ai/import/*。旧的nacos.ai.resource.import.legacy-mcp-api-enabled参数不再识别共享兼容开关还会重新开启其他显式接入门禁的废弃 v3 API具体范围由兼容与废弃策略规范定义。对于旧的importTypeurl请求默认不得把用户传入 URL 作为网络目标当data匹配已启用 source 时可以按sourceId解释否则应失败并提示迁移到nacos.plugin.ai-resource-import.{pluginName}.*受管插件配置并启用对应sourceId。旧的直接 URL 导入只能由运维同时开启nacos.core.api.compatibility.enabledtrue和nacos.ai.resource.import.allow-user-urltrue后用于受控部署。旧的importTypejson和importTypefile可以映射为内置本地 importer因为它们不需要服务端发起网络访问。依赖处理预留扩展点导入 artifact 可以引用其他 AI 资源例如 Skill 可能需要 MCP tools 或 servers。依赖处理是预留扩展点不要求在统一导入初始实现中完整落地在资源类型暴露明确、可版本化的依赖描述之前importer 可以保持dependencies为空导入管理器也不应要求请求中必须提供dependencyPolicy内置 importer 不得推断、安装或递归导入隐藏依赖。当 Nacos 后续补充明确的 AI 资源依赖描述后统一导入流程可以引入如下依赖策略策略含义IGNORE保留依赖元数据但不校验、不关联。VALIDATE_ONLY报告 Nacos 内是否已有匹配资源。LINK_EXISTING尽量关联已有匹配资源。IMPORT_SELECTED只导入用户显式选择的依赖。依赖描述可用后的默认策略应为VALIDATE_ONLY。自动递归导入不应作为默认行为因为它会扩大供应链和鉴权边界。安全要求把外部来源视为不可信导入流程必须把外部来源视为不可信安全要求层层递进用户不能提交任意 URL、IP、registry root 或凭证运维配置的 HTTP source 默认应使用 HTTPS非 HTTPS source endpoint 必须被拒绝除非运维在 source 配置中显式开启allow-httplocalhost、loopback、link-local、multicast 和私网 source endpoint 必须被拒绝除非运维在 source 配置中显式开启allow-private-network内置 importer 的 HTTP 请求必须对每个派生出来的请求 URL重新执行同一套 scheme 和网络策略校验包括从 index 或 search response 中发现的 URL内置 importer 的 HTTP 请求必须在发送前解析目标 host并在 DNS 结果为 loopback、link-local、multicast 或私网地址时默认拒绝除非 source 显式开启allow-private-networkredirect 必须禁用或按同一安全策略重新校验DNS 解析后默认阻断 loopback、link-local、multicast 和私网目标内置请求必须强制固定的连接/读取超时并执行已配置的max-item-count和max-artifact-size限制除非具体协议有更严格限制每个 HTTP response 都必须由max-artifact-size限制导入、查询或下载 Skill 包时不得执行包内脚本importer 插件不得在 API 响应、Trace 事件或日志中泄露 secret。从实现侧看DefaultImportHttpClient统一承载allowHttp/allowPrivateNetwork与maxArtifactSize限制内置 Service如SkillsShImportService在构造时通过DefaultImportHttpClient(allowHttp, allowPrivateNetwork, maxArtifactSize)建立客户端并设置固定读超时skills.sh 实现中DEFAULT_READ_TIMEOUT_SECONDS 20确保所有内置 HTTP 请求遵守同一套策略。Console MCP tools 导入辅助接口虽然不属于 importer plugin 操作仍必须遵循旧 MCP 导入兼容章节中单独定义的公网目标与私网例外策略。需要从私网导入的部署必须通过运维配置显式开启。Trace 与审计Search、validate 和 execute 操作应发出 Trace 或审计事件包含source idimporter 类型资源类型candidate 数量和选中数量单项成功、跳过或失败状态非 secret 来源元数据可用时的操作者身份和客户端地址。Trace 行为必须遵循 Trace 插件规范。演进说明稳定的转换边界该插件类型是转换边界单个资源的存储实现演进时它应保持稳定。特别是 MCP 从 Config-backed 记录迁移到标准 AI 资源模型时应通过替换 MCP Resource Operator 保持导入兼容而不是修改每个外部 importer。统一 managed 模型是对 3.2.x 中短期存在的 Importer/Source 双 SPI 的 breaking replacement外部实现必须迁移为一个实现PluginConfigSpec的AiResourceImportServiceBuilder已移除的 Source 模型和 Source Provider SPI 不提供兼容 adapter。因此任何希望扩展新 importer 来源如企业内部 Skill 市场、私有 MCP registry 或 Git 索引的团队都应基于AiResourceImportServiceBuilderAiResourceImportService双层 SPI 实现并通过nacos.plugin.ai-resource-import.{pluginName}.*前缀暴露配置定义——这正是本规范给出的标准扩展路径。【免费下载链接】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），仅供参考