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负责默认外部源适配器及其配置定义。核心概念模型概念含义Managed importer稳定的 Builder 插件以pluginName标识一个实现代表一个外部源Import service请求级协议适配器由一份不可变的 Builder 配置快照构建Candidate搜索阶段返回的外部资源摘要不含完整可导入内容Artifact已拉取的负载与元数据可被资源算子应用Resource operatorNacos 领域服务负责校验并写入某一资源类型Dependency导入产物引用的其他资源如 Skill 需要 MCP 工具两个 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.javaapplyConfig原子地替换不可变配置快照build()在未初始化或 endpoint 缺失/非法时抛出参数校验异常NacosApiException保证请求级服务总是基于一份已被接受的快照构建。托管配置模块总开关nacos.plugin.ai-resource-import.enabledtrue旧键nacos.ai.resource.import.enabled是别名标准键存在时标准键生效默认值为true只有显式false才会禁用 AI Resource Import。每个实现使用标准的插件状态键nacos.plugin.ai-resource-import.{pluginName}.enabledtrue每个可配置项使用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_COUNT500、DEFAULT_MAX_ARTIFACT_SIZE10MB。SPI 契约Builder 是稳定托管插件实现PluginConfigSpec其方法要求如下Builder 方法要求pluginName()稳定的托管插件名即 API 中的sourceIdimporterType()兼容性 importer/protocol 元数据返回于 API 的pluginName字段displayName()/description()来自已接受配置快照的当前展示元数据supportedResourceTypes()该源产出的资源类型getConfigDefinitions()该实现拥有的全部可配置项applyConfig(config)原子替换不可变有效配置快照build()基于一个快照构建请求级服务不接受额外属性请求级导入服务实现Service 方法要求search(context)从配置的源返回 candidate 页仅含必要元数据fetch(context, item)从配置的源拉取一个选中的 artifactclose()释放请求级资源默认实现可为 no-opcontext包含 namespace、资源类型、query、cursor、limit 与 importer options不携带源配置或用户提供的 endpoint。Builder 实例被发现一次、注册到统一PluginManager、恢复持久化状态、经标准配置源链解析并在暴露给导入请求前应用。search 为每个请求创建一个 servicevalidate 与 execute 各创建一个 service 并在所有选中项上复用最后在finally块中关闭。search应无副作用且不得返回MCP tools、Skill 包内容、机密或其他完整可导入负载fetch可以调用外部源并返回字节或结构化负载但不得写入Nacos 资源。Import Artifact 模型Artifact 是导入边界对象不是持久化的资源模型资源算子负责将其转换为当前的存储与生命周期模型。一个 artifact 应包含字段含义resourceType目标 Nacos AI 资源类型externalId源特定的稳定 IDname候选的 Nacos 资源名如已知version候选版本如已知description资源描述payloadKind负载形态如MCP_DETAIL、SKILL_ZIP、JSONpayload拉取的负载字节或结构化数据dependencies可选引用的资源sourceMetadata非机密源元数据供追踪与诊断使用以 McpRegistryImportService.java 为例search调用client.fetchOfficialRegistryPage(cursor, limit, query)构造 candidate 页并携带nextCursor/hasMorefetch调用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 不存在 → 导入创建新 draftSkill 存在且无 editing/reviewing 版本 → 创建下一个 draft 版本Skill 存在 editing/reviewing 版本 → 校验返回工作版本冲突除非overwriteExistingtrueexecute 必须跳过该项开启覆盖后按 Skill 服务生命周期替换当前可编辑 draft 或创建新 draft。内置 Importer默认内置 Importer 由plugin-default-impl中的nacos-default-ai-importer-plugin模块交付托管 pluginNameAPI importer 类型资源Endpoint默认状态mcp-officialmcp-registrymcp固定官方 MCP Registry endpointenabledmcp-registry-protocolmcp-registrymcp需运营商配置disabledskills-shskills-shskill固定https://skills.shenabledskills-well-knownskills-well-knownskill需运营商配置disabled固定内置源保留现有 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。公共有效配置项项键作用域适用范围含义endpointRESTART可配置 endpoint 的实现Registry 或 Marketplace 根allow-httpRESTART可配置 endpoint 的实现允许非 HTTPS 目标allow-private-networkRESTART可配置 endpoint 的实现允许本地或私有目标display-nameRUNTIME全部内置源API 与 Console 显示名descriptionRUNTIME全部内置源API 与 Console 描述max-item-countRUNTIME全部内置源单次请求最大结果/文件数默认500max-artifact-sizeRUNTIME全部内置源最大响应/artifact 字节数默认10485760固定 endpoint 实现不暴露endpoint、allow-http、allow-private-network定义也不接受旧的 endpoint 覆盖——其源身份与 endpoint 属于实现契约的一部分。这一点在AbstractAiResourceImportServiceBuilder中得到印证构造参数fixedEndpoint非空时configurableEndpointfalsebuildDefinitions跳过三个 endpoint 相关配置项定义。运营商配置的 MCP Registry 源示例nacos.plugin.ai-resource-import.mcp-registry-protocol.enabledtrue nacos.plugin.ai-resource-import.mcp-registry-protocol.endpointhttps://registry.example.com/v0/servers运营商配置的 Skill well-known 源示例nacos.plugin.ai-resource-import.skills-well-known.enabledtrue nacos.plugin.ai-resource-import.skills-well-known.endpointhttps://skills.example.com各实现的协议行为MCP Registrysearch 返回摘要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.shsearch 走GET /api/search?q{query}limit{limit}下载走GET /api/download/{owner}/{repo}/{skillId}见 SkillsShImportService.java。空查询使用skill单字符查询被拒绝源码中MIN_SEARCH_QUERY_LENGTH2返回路径与聚合大小在生成 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方法路径用途GET/v3/admin/ai/import/sources列出启用的导入源POST/v3/admin/ai/import/search从某源搜索候选摘要POST/v3/admin/ai/import/validate校验选中候选返回冲突、依赖与警告POST/v3/admin/ai/import/execute导入选中的候选GET/v3/console/ai/import/sourcesConsole 源列表POST/v3/console/ai/import/searchConsole 搜索流程POST/v3/console/ai/import/validateConsole 校验流程POST/v3/console/ai/import/executeConsole 执行流程所有统一 API 必须使用标准 v3ResultT响应、错误与授权约定。统一导入 API 遵循 Nacos v3 表单绑定约定Controller 方法应暴露*Form参数而非直接的 request-modelRequestBody契约标量字段可作为查询参数或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/executevalidate 与 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.enabledfalse关闭全部出站工具导入。请求baseUrl必须为 HTTP 或 HTTPSendpoint参数必须是相对 URI 且不能替换baseUrl的 scheme 或 authority不跟随重定向非法的私有 allowlist 条目按 fail-closed 处理。兼容端点已废弃仅在 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规则见 Compatibility And Deprecation Spec。对于旧importTypeurl默认不得把用户提供的 URL 当作网络目标当它匹配某个已启用源时可解释为sourceId否则请求应返回迁移提示。旧版直接 URL 导入仅在受控部署中由显式运营商配置启用同时设置nacos.ai.resource.import.allow-user-urltrue与nacos.core.api.compatibility.enabledtrue。旧importTypejson与importTypefile可映射到内置本地 importer因为它们不要求服务端网络访问。依赖处理导入产物可能引用其他 AI 资源例如 Skill 需要 MCP tools 或 servers。依赖处理是预留扩展点初始统一导入实现不要求支持。在资源类型暴露具体、带版本的依赖描述符之前importer 可让dependencies为空导入管理器也不应要求dependencyPolicy请求参数内置 importer不得推断、安装或递归导入隐藏依赖。当 Nacos 引入显式 AI 资源依赖描述符后统一导入流程可能引入以下策略策略含义IGNORE保留依赖元数据但不校验、不链接VALIDATE_ONLY报告 Nacos 中是否存在匹配资源LINK_EXISTING尽可能链接到已存在的匹配资源IMPORT_SELECTED只导入用户显式选中的依赖依赖描述符可用后默认应为VALIDATE_ONLY自动递归导入不得成为默认因为它扩大了供应链与授权边界。安全要求导入流程必须将外部源视为不可信用户不能提交任意 URL、IP、Registry 根或凭据运营商配置的 HTTP 源默认应使用 HTTPS非 HTTPS 源 endpoint 必须被拒绝除非运营商拥有的源配置显式启用allow-httplocalhost、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 idimporter typeresource typecandidate 数与选中数每项的成功、跳过或失败状态非机密源元数据可用的操作者身份与客户端地址。追踪行为必须遵循 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考