Nacos AI Resource Import 插件规范实战：从外部 Registry 与 Marketplace 导入 MCP Server 与 Skill

Nacos AI Resource Import 插件规范实战：从外部 Registry 与 Marketplace 导入 MCP Server 与 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

本指南系统讲解 Nacos 的ai-resource-import托管插件类型：它如何将运营商配置的外部 MCP Registry、Skill Marketplace 等外部源中的 AI 资源，经过搜索、拉取、转换后汇入 Nacos AI Registry 治理流程。读完本文，你将掌握该插件的核心概念、SPI 契约、托管配置项、四个内置 Importer 的实操配置、统一导入 API 流程、旧版 MCP 导入兼容策略与安全边界，并了解其源码级实现细节。

插件定位与职责边界

ai-resource-import是 Nacos 插件体系中的一种托管插件类型，其完整定义见 AI Resource Import Plugin Spec，公共插件运行时契约见 Nacos Plugin Spec。它的职责是从运营商配置的外部 Registry 或 Marketplace 导入 AI 资源，适用于 MCP Server、Skill 以及未来需要“外部发现 + 转换”后才能进入 Nacos AI Registry 治理流程的 AI 资源类型。

关键在于职责边界：导入插件只拥有外部源协议和到 Nacos 导入产物（Import Artifact）的转换，它不拥有Nacos 资源身份、授权、可见性、存储、版本生命周期、发布管道或追踪行为。这些规则仍由 AI Registry Spec、资源类型规范以及 AI Registry 域选择的资源算子（Resource Operator）负责。从执行模式上看，ai-resource-import是路由型（ROUTED）托管插件，与encryption、visibility、ai-storage同属一类——多个实现可同时加载，由领域根据请求上下文选择一个服务。

插件类型对核心插件管理器暴露为ai-resource-import，对应的pluginId形如ai-resource-import:{pluginName}。SPI 契约位于plugin/ai模块（与 AI storage、visibility 等其他插件类型一致），默认实现则位于plugin-default-impl，而非 AI Registry 领域模块——ai模块负责导入 API、插件路由、校验与资源算子，plugin-default-impl负责默认外部源适配器及其配置定义。

核心概念模型

两个 API 字段有明确约定：现有 API 字段sourceId就是托管的pluginName；现有 API 字段pluginName保留为 importer/protocol 元数据以兼容 Console。最终用户在请求中选择sourceId，不得提交任意 endpoint URL、IP 地址、凭据或 Registry 根路径。

执行模式与请求路由

ai-resource-import是路由型托管插件类型，多个 Builder 实现可以同时加载（例如mcp-official、mcp-registry-protocol、skills-well-known或企业内部 Marketplace importer）。对于每个请求，领域管理器直接把sourceId解析到一个启用的 Builder。Importer 在搜索时返回 candidates，在校验（validate）与执行（execute）时拉取选中项的 artifacts，随后 AI Registry 导入管理器把每个 artifact 按resourceType路由到对应的资源算子。整体调用链为：

sourceId(managed pluginName) -> AiResourceImportServiceBuilder(current configuration snapshot) -> request-scoped AiResourceImportService -> AiResourceOperator(resourceType)

从源码看，Builder 的生命周期与请求级 Service 是严格分离的。AiResourceImportServiceBuilder接口（见 AiResourceImportServiceBuilder.java）继承自PluginConfigSpec，是进程级稳定托管插件；而build()每次调用返回一个请求级AiResourceImportService。内置 Builder 的公共实现集中在 AbstractAiResourceImportServiceBuilder.java：applyConfig原子地替换不可变配置快照，build()在未初始化或 endpoint 缺失/非法时抛出参数校验异常（NacosApiException），保证请求级服务总是基于一份已被接受的快照构建。

托管配置

模块总开关：

nacos.plugin.ai-resource-import.enabled=true

旧键nacos.ai.resource.import.enabled是别名：标准键存在时标准键生效，默认值为true，只有显式false才会禁用 AI Resource Import。每个实现使用标准的插件状态键：

nacos.plugin.ai-resource-import.{pluginName}.enabled=true

每个可配置项使用：

nacos.plugin.ai-resource-import.{pluginName}.{itemKey}=value

一个pluginName只代表一个源：Nacos 不支持通过配置把同一托管实现克隆成多个 endpoint 实例；部署需要另一个固定源时，应提供另一个具有不同pluginName的 Builder。旧的nacos.ai.resource.import.sources[N].*模型、旧 Source 模型与旧 Source Provider SPI 已被移除，且没有自动迁移——因为旧模型中一个带索引的 importer 可能创建多个 source 实例。相关迁移对照也记录在 Nacos Plugin Spec 的"Deprecated Compatibility Scheduled For Removal"一节。

配置项常量在 AiResourceImportConstants.java 中定义：endpoint、allow-http、allow-private-network、display-name、description、max-item-count、max-artifact-size，其中DEFAULT_MAX_ITEM_COUNT=500、DEFAULT_MAX_ARTIFACT_SIZE=10MB。

SPI 契约

Builder 是稳定托管插件，实现PluginConfigSpec，其方法要求如下：

请求级导入服务实现：

context包含 namespace、资源类型、query、cursor、limit 与 importer options，不携带源配置或用户提供的 endpoint。Builder 实例被发现一次、注册到统一PluginManager、恢复持久化状态、经标准配置源链解析并在暴露给导入请求前应用。search 为每个请求创建一个 service；validate 与 execute 各创建一个 service 并在所有选中项上复用，最后在finally块中关闭。

search应无副作用，且不得返回MCP tools、Skill 包内容、机密或其他完整可导入负载；fetch可以调用外部源并返回字节或结构化负载，但不得写入Nacos 资源。

Import Artifact 模型

Artifact 是导入边界对象，不是持久化的资源模型，资源算子负责将其转换为当前的存储与生命周期模型。一个 artifact 应包含：

以 McpRegistryImportService.java 为例：search调用client.fetchOfficialRegistryPage(cursor, limit, query)构造 candidate 页并携带nextCursor/hasMore；fetch调用fetchOfficialRegistryServer(externalId, limit)，将McpServerDetailInfo序列化为 JSON 负载，payloadKind置为MCP_DETAIL，同时把 id、protocol、status、repository URL 等写入sourceMetadata。

资源算子（Resource Operators）

资源算子位于 AI Registry 域而非导入插件中，通过资源类型当前的 service 层校验并写入 artifacts。

• MCP：算子调用当前的McpOperationService兼容应用契约及相关校验服务。生命周期调和处于SYNCING时，该完整契约沿用历史策略并立即调和成功写入；原子切换后将使用规范生命周期策略、MCP Version Storage 与规范 name-keyed 异步 Search 任务。导入插件与统一导入 API 在切换前后保持不变，且不得直接调用已移除的 Config-backedMcpServerOperationService。
• Skill：算子应保持 Skill 包边界，通过 Skill upload 或 draft 生命周期 API 写入。导入成功后，若 artifact 含sourceMetadata.artifactUrl，则记录为导入资源来源（ai_resource.c_from）；缺失时回退到sourceMetadata.source。

Skill 冲突处理遵循 AI 资源工作版本生命周期：

• Skill 不存在 → 导入创建新 draft；
• Skill 存在且无 editing/reviewing 版本 → 创建下一个 draft 版本；
• Skill 存在 editing/reviewing 版本 → 校验返回工作版本冲突；除非overwriteExisting=true，execute 必须跳过该项；开启覆盖后，按 Skill 服务生命周期替换当前可编辑 draft 或创建新 draft。

内置 Importer

默认内置 Importer 由plugin-default-impl中的nacos-default-ai-importer-plugin模块交付：

固定内置源保留现有 Console 展示元数据：mcp-official显示名Official MCP Registry、描述Import MCP servers from the official MCP registry.；skills-sh显示名skills.sh、描述Import Skills from skills.sh.。这些元数据与固定 endpoint 可在 McpOfficialImportServiceBuilder.java 中看到，其OFFICIAL_ENDPOINT为https://registry.modelcontextprotocol.io/v0/servers。

公共有效配置项：

固定 endpoint 实现不暴露endpoint、allow-http、allow-private-network定义，也不接受旧的 endpoint 覆盖——其源身份与 endpoint 属于实现契约的一部分。这一点在AbstractAiResourceImportServiceBuilder中得到印证：构造参数fixedEndpoint非空时configurableEndpoint=false，buildDefinitions跳过三个 endpoint 相关配置项定义。

运营商配置的 MCP Registry 源示例：

nacos.plugin.ai-resource-import.mcp-registry-protocol.enabled=true nacos.plugin.ai-resource-import.mcp-registry-protocol.endpoint=https://registry.example.com/v0/servers

运营商配置的 Skill well-known 源示例：

nacos.plugin.ai-resource-import.skills-well-known.enabled=true nacos.plugin.ai-resource-import.skills-well-known.endpoint=https://skills.example.com

各实现的协议行为：

• MCP Registry：search 返回摘要，fetch 返回MCP_DETAILartifact（实现见 McpRegistryImportService.java）。
• Skill well-known：支持 discovery schema v0.1.0 与 v0.2.0（见 SkillWellKnownImportService.java）。当配置 endpoint 是 Registry 根时，依次尝试/.well-known/agent-skills/index.json与/.well-known/skills/index.json。search 不下载 artifact 内容；fetch 校验路径与摘要，并把skill-md、ZIP、TAR、TAR.GZ、TGZ 分发转换为标准 Skill ZIP artifact。v0.2.0 条目要求sha256:前缀摘要且必须匹配，TAR 解压条目数与解压后总字节数分别受max-item-count与内置 50MB 上限约束。
• skills.sh：search 走GET /api/search?q={query}&limit={limit}，下载走GET /api/download/{owner}/{repo}/{skillId}（见 SkillsShImportService.java）。空查询使用skill，单字符查询被拒绝（源码中MIN_SEARCH_QUERY_LENGTH=2）；返回路径与聚合大小在生成 Skill ZIP artifact 前会校验，且产物必须包含SKILL.md。

旧版nacos.plugin.ai.importer.*的 display、description、limits、state 与可配置 endpoint 键可在一个迁移窗口内作为别名使用，服务端在使用别名时输出迁移警告。旧固定源的 endpoint 覆盖、auth-ref、源/全局超时、max-page-count、block-private-network、全局默认值与任意properties.*均已移除——它们无效或与托管身份模型冲突。

统一导入 API 流程

Nacos 暴露统一的 Admin 与 Console 导入 API（路径常量见 Constants.java，实现见 AiResourceImportAdminController.java）：

所有统一 API 必须使用标准 v3Result<T>响应、错误与授权约定。统一导入 API 遵循 Nacos v3 表单绑定约定：Controller 方法应暴露*Form参数而非直接的 request-model@RequestBody契约；标量字段可作为查询参数或application/x-www-form-urlencoded表单字段提交；复杂导入字段（如selectedItems、options）应以 JSON 字符串表单字段提交，由表单对象转换为内部请求模型。

推荐浏览器流程：

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

浏览器不得默认选中搜索出的 candidates；可以提供显式全选控件，全选后仍须允许用户取消个别项。如有 import-all-valid 动作，只能作用于用户显式选择并校验过的 candidates（包括同一源中跨多个校验批次累积的候选）。浏览器不得接收完整 artifacts——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/execute

validate 与 execute 端点应经兼容适配器路由到统一导入管理器（源码见 McpLegacyImportAdapter.java），不得再作为独立实现扩张。

GET /v3/console/ai/mcp/importToolsFromMcp不属于外部 Registry 导入兼容范围：它是从用户自有的 MCP 运行时 endpoint 构建 MCP Server schema 的 Console 辅助功能，位于 AI 资源 Marketplace/Registry 导入流程之外。该辅助功能会让 Console 进程对请求选定的 MCP 运行时发起服务端网络连接：默认允许公网目标，私有/本地目标被拒绝，除非从baseUrl解析出的每个地址都匹配nacos.console.ai.mcp.import.allowed-private-addresses；运营商可用nacos.console.ai.mcp.import.enabled=false关闭全部出站工具导入。请求baseUrl必须为 HTTP 或 HTTPS，endpoint参数必须是相对 URI 且不能替换baseUrl的 scheme 或 authority；不跟随重定向；非法的私有 allowlist 条目按 fail-closed 处理。

兼容端点已废弃：仅在 Nacos 3.3.x 内可用，计划在 Nacos 3.4.0 移除，默认禁用；运营商可临时以nacos.core.api.compatibility.enabled=true重新打开，以便客户端迁移到/v3/{admin|console}/ai/import/*。原nacos.ai.resource.import.legacy-mcp-api-enabled属性不再被识别；共享兼容开关也会重新打开其他显式门控的废弃 v3 API，规则见 Compatibility And Deprecation Spec。

对于旧importType=url：默认不得把用户提供的 URL 当作网络目标；当它匹配某个已启用源时可解释为sourceId，否则请求应返回迁移提示。旧版直接 URL 导入仅在受控部署中由显式运营商配置启用：同时设置nacos.ai.resource.import.allow-user-url=true与nacos.core.api.compatibility.enabled=true。旧importType=json与importType=file可映射到内置本地 importer，因为它们不要求服务端网络访问。

依赖处理

导入产物可能引用其他 AI 资源（例如 Skill 需要 MCP tools 或 servers）。依赖处理是预留扩展点，初始统一导入实现不要求支持。在资源类型暴露具体、带版本的依赖描述符之前，importer 可让dependencies为空，导入管理器也不应要求dependencyPolicy请求参数；内置 importer不得推断、安装或递归导入隐藏依赖。

当 Nacos 引入显式 AI 资源依赖描述符后，统一导入流程可能引入以下策略：

依赖描述符可用后，默认应为VALIDATE_ONLY；自动递归导入不得成为默认，因为它扩大了供应链与授权边界。

安全要求

导入流程必须将外部源视为不可信：

• 用户不能提交任意 URL、IP、Registry 根或凭据；
• 运营商配置的 HTTP 源默认应使用 HTTPS；
• 非 HTTPS 源 endpoint 必须被拒绝，除非运营商拥有的源配置显式启用allow-http；
• localhost、loopback、link-local、multicast 与私有网络源 endpoint 目标必须被拒绝，除非显式启用allow-private-network；
• 内置 importer 的 HTTP 请求必须对每个派生请求 URL（包括从索引或搜索结果发现的 URL）重新应用同样的 scheme 与网络策略；
• 内置 importer 的 HTTP 请求必须在发送前解析请求主机，除非源显式启用allow-private-network，否则拒绝 loopback、link-local、multicast 与私有网络 DNS 结果；
• 重定向必须禁用或按同一安全策略重新校验；
• DNS 解析后默认应阻止 loopback、link-local、multicast 与私有网络目标；
• 内置请求必须强制固定连接/读超时以及配置的max-item-count与max-artifact-size限制；每个 HTTP 响应都必须受max-artifact-size封顶（除非有更严格的协议限制）；
• 拉取的 Skill 包在导入、查询或下载期间不得执行脚本；
• importer 插件不得在 API 响应、追踪事件或日志中泄露机密。

这些约束在 DefaultImportHttpClient.java 中有完整实现证据：HttpClient以followRedirects(NEVER)构建，连接超时固定 10 秒；get()先解析并校验请求目标——非 http/https、HTTP 且未开allow-http、host 为空、isUnsafeHost命中（localhost/.localhost后缀、any-local、loopback、link-local、site-local、multicast、IPv6 unique-localfc/fd前缀）且未开allow-private-network都会被拒绝；响应体由LimitedByteArrayBodySubscriber在流式接收阶段按maxResponseBytes即时截断。

Console MCP 工具导入辅助功能遵循上述"旧版 MCP 兼容"一节所述的独立公网目标策略与私有例外（尽管它不属于 importer 插件操作）。有意从私有网络导入的部署必须通过运营商拥有的配置显式 opt in。

追踪与审计

search、validate、execute 操作应发出包含以下内容的 trace/audit 事件：

• source id；
• importer type；
• resource type；
• candidate 数与选中数；
• 每项的成功、跳过或失败状态；
• 非机密源元数据；
• 可用的操作者身份与客户端地址。

追踪行为必须遵循 Trace Plugin Spec。

演进说明

该插件类型是转换边界：在单个资源存储实现演进时它应保持稳定。特别是 MCP 导入必须能在从 Config-backed 记录迁移到标准 AI 资源模型的过程中继续工作——方式是改变 MCP 资源算子而非每个外部 importer。统一托管模型是对 3.2.x 系列引入的短暂 Importer/Source 双 SPI 的破坏性替代：外部实现必须迁移到实现PluginConfigSpec的单个AiResourceImportServiceBuilder；已移除的 Source 模型与 Source Provider SPI 没有兼容适配器。

从源码结构看，这种"Builder 稳定、Service 请求级、Operator 领域化"的三层划分是整套设计的主线：plugin/ai提供 SPI 与常量，plugin-default-impl/nacos-default-ai-importer-plugin提供AbstractAiResourceImportServiceBuilder统一生命周期与四个内置实现，ai模块提供 AiResourceImportManager.java 负责路由与资源算子衔接。理解这条链路，就能为任意新的外部 AI 资源源编写一个规范、安全、可托管的 Nacos 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