Nacos AI 资源检索规范深度解析：协议无关的 Search Core、索引任务与 Readiness 机制

Nacos AI 资源检索规范深度解析：协议无关的 Search Core、索引任务与 Readiness 机制

【免费下载链接】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 资源检索规范》（specs/zh-cn/ai/ai-resource-search-spec.md）为核心骨架，结合ai模块的真实源码（AiResourceSearchService.java）逐层拆解 Nacos 为 Agent、AgentSpec、Skill、Prompt、MCP 等标准 AI 资源构建的统一检索运行时：从配置激活、类型化 predicate、关键词/向量双通道召回与 RRF 融合，到ai_resource_task持久化任务的两阶段收敛、lease/revision 防并发覆盖，以及按(resourceType, projectionVersion)维护的集群共享 Readiness。读完本文，你将掌握该检索内核的配置项含义、HTTP Facade 契约、索引表结构与升级迁移路径，并能据此排查索引不一致、读模式选择与 Enhancement 回退等生产问题。

1. 范围与激活：一套内核，多协议复用

规范的第一条原则是：AI Resource Search 是ai模块内可复用、协议无关的逻辑能力。RAD、ARD、通用 AI Resource Search 以及 Agent/Skill/Prompt/MCP 等资源专用 Search 都必须复用这一套索引与检索内核，不得各自维护独立索引或搜索引擎。HTTP、Java SDK、Console 和外部协议响应则由各自的 API 或适配器规范单独定义，检索内核不感知协议语义。

1.1 配置项与非法组合

检索运行时的激活与三个配置项直接相关，均可在application.properties中设置：

其中前两个键在源码常量类中均有明确定义：Constants.java 中声明了ARD_ENABLED_KEY = "nacos.ai.ard.enabled"与AI_RESOURCE_SEARCH_ENABLED_KEY = "nacos.ai.resource.search.enabled"，后者注释明确写着“Enables the protocol-neutral AI Resource Search runtime”；Constants.java 则声明了RAD_SEARCH_MODE_CONFIG_KEY = "nacos.ai.rad.search.mode"。

规范特别强调了一个非法组合：

nacos.ai.ard.enabled=true且nacos.ai.resource.search.enabled=false必须被拒绝。

理由是 ARD 端点本身依赖检索运行时，服务端必须在启动配置校验时明确失败，不能隐式创建一套 ARD 专属索引。这一点在ai模块测试中有专门覆盖：AiResourceSearchConfigurationValidatorTest.java。同时，检索实现不得依赖ARD 的请求、响应、identifier、federation、media type 或 artifact 语义——这是保证“一套内核多协议复用”的硬约束。

2. 所有权边界：内核与适配器各管一段

规范用清晰的所有权划分避免职责混乱：

AI 模块（Search Core）负责：

• 标准 search document、chunk 和 facet 投影；
• 资源类型处理器注册、Query Planner 与多召回通道结果融合；
• 持久化索引任务与 reconciliation（对账修复）；
• 关键词召回和可选向量召回；
• 排序及确定性 tie-breaking（并列时的稳定次序）；
• 可见性 query advice 与逐资源可见性校验；
• latest label 与当前 online version 校验；
• 类型化 predicate、不透明 cursor、numbered page 与完整结果集聚合；
• 每种资源投影代际（generation）的 readiness。

协议适配器 / 资源专用 API Facade 负责：

• 请求解析与协议校验；
• 类型专用 filter 到标准 predicate 的转换；
• 响应 DTO 与错误映射。

而 identifier、media type、artifact URL 与 federation 行为仅属于对应协议适配器，不进内核。

源码中这一边界的直接体现是 AiResourceSearchService.java：其 Javadoc 写明它是 “Canonical AI resource discovery application service”，拥有 recall、ranking、visibility 和 current-version 检查、canonical field 过滤、排序与分页，而协议适配器只负责转换请求与响应模型。

3. 检索模型：类型化 Predicate 与查询语义

内部 query model 包含：namespace、text、一个或多个标准resource type、类型化 predicate、时间边界、排序及 cursor 或 numbered page 信息。不得包含协议 DTO 或协议专属字段名。

标准 predicate 结构：

field operator = EXACT_ANY | EXACT_ALL | LITERAL_CONTAINS values[] caseSensitive

语义要点：

• 同一个 predicate 内由operator定义 ANY、ALL 或 literal contains；多个 predicate 使用AND组合；
• metadata.<facetKey>是协议无关的 facet 路径；
• 实现必须把%、_和 escape char 当作普通输入字符，不能让数据库 LIKE 通配符改变 literal contains 语义；
• 类型专用 Facade 可以固定 resource type、允许的字段、大小写和字段权重，但不得改变公共可见性、enabled 和 currentness 规则；
• 既有协议 filter 可保留兼容入口，但进入 Search Core 前必须转换为标准 predicate。

检索结果返回application DTO 而非持久化实体：可暴露标准资源键、当前版本、展示与检索元数据、时间戳和相关度分数；数据库行 ID、索引状态、任务状态则保留在检索实现内部。

3.1 通用 Client HTTP Search Facade

通用（跨类型）搜索端点为：

GET /v3/client/ai/resources/search

该路径在源码中定义为 Constants.java 的AI_RESOURCE_SEARCH_CLIENT_PATH，并由 AiResourceSearchClientController.java 暴露。

请求参数与默认值：

边界约束：每个重复 filter 最多包含32 个非空值；query最长1024 字符；未知资源类型和非法边界统一返回参数校验错误。

响应语义：响应为Result<AiResourceSearchResponse>，items包含协议无关的资源身份、当前 Version、展示/检索元数据、时间戳和score；没有下一页时不返回nextCursor；通用 cursor page不暴露numbered-page 的 total。

源码侧的分发逻辑位于 AiResourceSearchApplicationService.java：空白 query 走core.list(query)（确定性列表），非空 query 走core.search(query)（相关度搜索），并完成资源类型解析（未知类型抛出PARAMETER_VALIDATE_ERROR）。

3.2 资源专用 Client HTTP Facade

各 numbered Facade 的行为约定：

• 省略pageNo/pageSize时使用公共分页默认值（源码中 AiResourceSearchService.java 定义DEFAULT_NUMBERED_PAGE_SIZE = 20），非正数必须拒绝；
• 空白 text 按稳定资源键列出当前资源；非空 text 复用共享召回和排序路径；
• AgentSpec 为兼容既有keyword契约，保留 resource name 的literal contains语义（见 AiResourceSearchApplicationService.java，将 keyword 转为resourceName字段的LITERAL_CONTAINSpredicate）；
• 各 Facade 映射与通用单类型 Search 相同的合法 Document，不得在分页后再次过滤。

4. 聚合：基于完整合法匹配集

聚合（Aggregation）必须基于完整的合法匹配集，而不是单个结果页。服务按消费者需要返回：标准 bucket value、count、超过 bucket limit 的数量以及匹配总数。

协议派生值由适配器映射——例如，适配器可以把标准 resource type bucket 转换成 ARD media type，而不把 ARD media type 语义塞进 AI 模块。

源码中 AiResourceSearchService.java 的aggregate方法：空白 text 时走aggregateList（按文档 ID 有界分批扫描全量合法集合再统计），非空 text 时基于searchCandidates的完整候选集聚合；aggregateCandidates 与 buildAggregation 完成桶计数、按 count 降序 + key 升序的稳定排序，以及超出limit的桶归入otherCount。

5. 索引与 Schema：可重建的派生状态

关系检索索引使用三个协议无关对象，所有支持的主数据源（MySQL、PostgreSQL、Derby、Oracle）都提供：

• ai_resource_search_document；
• ai_resource_search_chunk；
• ai_resource_task。

要点：

• ai_resource_task可供 AI 资源域内的持久化异步任务复用，但它不是 Nacos 全局工作流引擎；
• 每种任务类型拥有自己的版本化 JSON 输入和结果 Schema；逻辑 JSON 使用 text 或 CLOB 存储，不使用数据源专属的原生 JSON 类型；
• 可选 PostgreSQL vector 实现负责独立的 pgvector Schema 与ai_resource_search_embedding_pg表；主数据源 Schema不得创建 pgvector 扩展或 embedding 表；
• 标准资源写入始终是事实来源（source of truth），Search document 和 chunk 属于可重建的派生状态。

逻辑IndexProjection由一个 document、零到多个 chunk 和 facet 集合组成：

• document：保存资源身份、展示信息、状态、当前版本、source digest 和稳定排序字段；
• facet：保存精确过滤属性。第一代实现可以把通用 key/value 或 array facet 保存在 document metadata 中，不要求立即增加物理表；
• chunk：只保存关键词或向量召回所需的文本内容；facet不生成独立 chunk，也不进入 embedding；
• 结构化 document/facet + 关键词索引是基础 Search 的必选组成，向量索引是可选召回通道；
• Agent 等资源只能填充自己拥有的 facet，不能要求 Skill、Prompt、MCP 或 AgentSpec 增加 Agent 专属列。

所有召回通道由同一个 Query Planner/Fusion负责候选生成、结构化过滤、去重、分数融合、可见性、当前性和分页。向量 Provider 不能下推 facet 时，Planner 必须使用有界且可证明完整的候选策略；禁止对固定 top-K 结果只做一次后过滤就声称 total 或分页完整。

源码中的两阶段写入实现可参考 AiResourceIndexServiceImpl.java 与 JdbcAiResourceSearchRepository.java。

5.1 资源类型处理器

每个声明可检索的资源类型必须注册协议无关的类型处理器，至少提供：

resourceType() project(namespaceId, resourceName) -> Optional<IndexProjection> scan(namespaceId, cursor, batchSize) -> SourcePage isCurrent(document) -> boolean exists(namespaceId, resourceName) -> boolean

语义约束：

• project返回空表示资源不存在、不可发现或没有合法当前版本，索引服务应删除该逻辑资源的派生文档；
• scan只用于 Backfill/Reconciliation，必须按稳定资源键有界扫描；
• isCurrent必须执行该资源的 enabled、可见性、当前版本和 source digest 校验；
• 处理器属于ai模块，不能引用ARD DTO、URL 或 media type；
• 每个可检索处理器必须声明正数projectionVersion，初始 generation 为1，投影契约变化时递增；
• Readiness 是所有可检索类型共享的完整性与可观测信号，不是仅由保留旧扫描路径的类型实现的兼容切换开关。

本规范声明的可检索类型为Agent、AgentSpec、Skill、Prompt 和 MCP。若将来某个 AI Resource 不参加通用 Search，必须在该资源规范中明确声明，不能仅因尚未实现处理器而静默漏掉。

源码中的处理器实现包括 AgentAiResourceSearchTypeHandler.java、AgentSpecAiResourceSearchTypeHandler.java、McpAiResourceSearchTypeHandler.java 与 StoredAiResourceSearchTypeHandler.java，统一注册于 AiResourceSearchTypeHandlerRegistry.java。

5.2 Agent 投影

每个(namespaceId, agentName)最多维护一个 enabled document，其resourceVersion是 commonlatest指向的精确 online Version。Agent document 至少投影：

• display name、description、business tags、provider、icon 和 scope 等目录字段；
• 全部 online Version 的有序紧凑 version catalog；
• 全部 online Version 的 protocol有序去重并集metadata.protocols；
• common latest 精确 Version 可完整导出的表示 key 集合metadata.artifactKinds；
• metadata.projectionVersion与由稳定业务事实生成的sourceDigest。

protocols表示调用协议，artifactKinds表示可完整返回的版本制品，两者不得混用。

Chunk 与结构化字段的划分：Agent name、description、tags、能力和示例可以生成 chunk；scope、owner、status、protocols 和 artifactKinds 仅作为结构化字段。Runtime Endpoint、健康状态、Publisher、心跳和 Runtime revision 永远不进入持久搜索索引。

Agent source digest 使用canonical JSON 的 SHA-256，覆盖影响目录或检索投影的 Agent metadata、完整 version catalog、common latest、latest VersioncontentDigest、artifactKinds 和 projection version；无语义的修改时间不单独触发 digest 变化。

标准资源标识字段和任务控制字段必须与标准资源存储保持一致，使用精确且大小写敏感的比较；关键词匹配通过 Locale 无关的查询规范化实现大小写不敏感，不得依赖数据源专属的表级大小写不敏感排序规则。

5.3 MCP 投影

每个(namespaceId, mcpName)最多存在一个 Enable Document：

• resourceName必须是标准mcpName，绝不能是已废弃的mcpId；
• resourceVersion是 Commonlatest指向的 Online Version。

MCP Handler 从AiResource、AiResourceVersion以及持久化 MCP Storage Descriptor 加载的内容生成投影；不得通过历史 MCP Operation Service、Serving Manifest、最终一致的 Search 或 MCP 内存 ID Index 定位源内容。

可进入 Document 的字段：公开 Description、Tools、Resources、Business Tag、Protocol 和 Capability。绝不进入耐久索引的字段：Credential、敏感 Auth Metadata、Naming Instance、Health、Heartbeat 和 Runtime Endpoint 状态。

只有兼容 DTO 要求时，历史mcpId才可以作为 Response Metadata 保留，不能成为 Document Identity。生命周期托管投影递增 MCPprojectionVersion；Backfill 重建 Name-Keyed Document，Reconciliation 删除过期或孤立的 ID-Keyed Document 与 Task，确保 MCP不会长期保留两个标准 Search 身份。

6. 一致性：原子替换、两阶段任务与租约防并发

6.1 原子性与任务 Key

单个逻辑资源的关系 document、chunks 和内嵌 facets 必须原子替换。关系索引与向量索引之间不要求分布式事务——系统使用幂等的search_index持久化任务重新读取标准资源状态并收敛两类索引。

任务 key =task type、namespace、以及由resource type + resource name组成的逻辑 subject 的SHA-256。Key 包含 task type，因此其他 AI 资源工作流复用同一张表时不会与检索索引任务冲突。

6.2 调度触发规则

标准资源生命周期事务成功提交后，按(namespaceId, resourceType, resourceName)调度合并任务；调度失败不得回滚已经成功的事实写入，由指标、告警和 reconciliation 修复。

Agent 必须调度的场景：创建、目录 metadata 或治理字段变化、Version publish/online/offline/delete、common latest 或自定义 label 变化、legacy A2A facade 产生的 canonical 定义变化、Agent 删除。

Agent 不得调度的场景：Endpoint register/deregister、heartbeat、健康变化和 Runtime revision。

MCP 必须调度的场景：Create/Update、Publish、Online/Offline/Delete、Enable/Disable、Label 和 Import（按标准mcpName）；不得调度的场景：Endpoint Register/Deregister、Heartbeat、Reconnect 及其他仅 Runtime 变更。

6.3 两个持久化阶段

同一任务行负责两个持久化阶段：

每个阶段使用pending、processing、completed状态。首次执行和可重试任务均使用pending；通过retry_count、next_execute_at、last_error区分延迟重试与新任务。成功行作为每个存活资源的有界完成检查点保留，不记录任务历史。

6.4 Revision 与 Lease Token：防旧 Worker 覆盖

这是并发安全的核心设计：

• 资源生命周期变更递增任务revision，并从base_index重新开始；
• 已领取的 revision 只有在仍持有任务行时才能推进、重试或完成；
• Revision 表示已调度的任务内容，领取任务不得递增 revision；
• 每次领取成功都必须递增独立且单调的lease_token；续租、状态迁移和 superseded work 释放都必须比较该 token；过期 worker 不得修改或释放后来 worker 的租约；
• 生命周期任务无论连续合并多少次更新，都必须保留尚未过期的租约；替代 revision 只有在当前 token 持有者释放租约或租约过期后才能被领取；
• 进程失败后，其他节点可在 lease 过期后接管；Enhancement 任务回退到base_index同样必须使用 revision 和 lease token 条件；
• 基础阶段和 Enhancement 阶段都必须通过独立于轮询线程的执行器续租；领取的 Enhancement 任务数不得超过已配置的 worker 并发数。

6.5 任务 Payload 与 Result

• 检索索引任务输入保存在task_payload：必须包含schemaVersion、保存 resource type 和 resource name 的subject、options.enhancementRequested；
• 调度新 revision 时整体替换Payload，该 revision 执行期间 Payload不可变；
• Enhancement 完成元数据保存在版本化task_result，当前结果包含完成时的 Enhancement fingerprint；
• 轮询、领取、重试、lease 接管、revision 防并发覆盖和 lease token fencing 的调度元数据继续使用独立关系列；
• 无法解析或 Schema 版本不支持的任务 Payload 必须以带解码错误的完成检查点隔离，不能导致同一批其他到期任务失败或饥饿；后续 reconciliation 可使用当前 Payload 重新打开该任务。

6.6 时钟纪律

调度截止点以Unix Epoch 毫秒保存到 BIGINT 类型的next_execute_at和lease_expire_at。轮询、领取、重试和 lease 续期必须使用同一个注入的应用时钟生成比较时间及截止点，不得混用JVM 经 JDBC 转换的 timestamp 和数据源CURRENT_TIMESTAMP。Nacos 集群节点应保持系统时钟同步。

6.7 Enhancement 语义

• Enhancement 写入必须幂等：AI 生成的 chunk type 必须事务性替换、不能追加；向量索引按完整资源版本替换；只有两类写入都成功后才能完成任务；
• Enhancement 配置 fingerprint 包含 provider endpoint、model、Prompt 版本、输出 Schema 版本及相关输出限制，不得包含密钥；fingerprint 仅用于审计和问题诊断，不作为收敛目标——配置变化不得重新调度已完成资源；
• 资源生命周期任务在调度时持久化当时是否开启 Enhancement；只有明确请求 Enhancement 的任务才能从base_index推进到llm_enhancement，执行时使用当时生效的配置；
• Enhancement 关闭时：仍处于base_index的任务可直接完成；已进入llm_enhancement的任务不得直接完成，必须创建options.enhancementRequested=false的新 revision 回到base_index，清除可能部分写入的 Enhancement chunk、重新收敛基础向量索引后作为基础索引检查点完成；之后重新开启 Enhancement不得重新调度该已完成资源；
• 开关已开启但配置不完整时，Enhancement 阶段必须回到pending并保留重试元数据，不能当作关闭处理。

6.8 失败重试与 Reconciliation

失败时将当前阶段恢复为pending，增加retry_count，按指数退避设置next_execute_at。周期性 reconciliation 检测遗漏、部分、过期和孤儿基础索引：

• 索引缺失或不一致时按正常建索引流程重建，并根据修复任务调度时的 Enhancement 开关决定是否请求 Enhancement；
• 索引已一致时，不得仅因历史资源缺少 Enhancement 检查点而触发修复——开启 Enhancement 不会导致历史数据全量刷新；
• 同一资源已有活动任务时，reconciliation 必须保留其 Payload 中持久化的 Enhancement 意图，以及 revision、阶段、重试延迟和 lease；
• 向量 reconciliation 除模型和 chunk 数量外，还必须比较关系 document 标识；
• 每个类型处理器的 reconciliation 必须检测缺失、部分、过期和孤儿投影；Agent 还必须比较 projection version、source digest、common latest、version catalog 和可选向量状态；
• 无 online Version、disabled 或 deleted 资源的正确收敛结果是删除派生文档，而不是永久重试。

7. 资源边界：有界扫描与候选上限

• 列表、聚合、reconciliation 和持久化任务轮询必须按有界数据库批次扫描关系状态；资源源扫描和 numbered list 使用稳定的 resource-keykeyset；排序并列时使用不可变行键消除歧义；
• 完成 predicate、可见性和当前版本校验后，列表分页在内存中只保留请求页及一条用于判断下一页的记录；numbered page 只额外保留计数器，不能保留全部匹配项；
• Reconciliation不得在内存中保留全部标准资源名称；集群扫描 lease 必须记录 owner 和过期时间，扫描期间通过CAS 续租，并且只有相同 owner 仍持有 lease 时才能释放；
• 关键词和向量召回分别设置可配置的候选上限。任一通道超过上限时，检索必须明确失败，不得返回静默截断的结果。

源码中的默认值与配置键位于 AiResourceSearchService.java：DEFAULT_MAX_RECALL_CANDIDATES = 10000，配置键为nacos.ai.resource.search.max-recall-candidates；超限时通过 ensureWithinRecallLimit 抛出SERVER_ERROR。

8. Readiness 与读模式

8.1 集群共享的 Readiness

每个可检索资源类型都必须按(resourceType, projectionVersion)维护持久、集群共享的 readiness。Backfill 扫描 lease 只表示当前扫描 owner，不能替代readiness。

一个 projection generation 只有在以下条件全部满足时才能通过 CAS 标记为READY：

1. 成功枚举全部有效 namespace，且没有用publicfallback 掩盖枚举失败；
2. 完成一轮该资源类型的有界 source scan，扫描差异均已成功调度；
3. 后续验证轮没有未修复的缺失、过期或孤儿文档；
4. 没有属于该轮的 pending、processing 或 retry 任务；
5. readiness record 写入当前 projection version。

READY对同一 generation 是sticky的：普通生命周期任务短暂 pending 不把该 generation 退回未就绪；查询的 currentness 校验先排除陈旧文档，任务随后收敛。投影契约变化必须递增 projection version 并创建新的 readiness generation。

NOT READY不是 API 可用性错误：通用 Search、资源专用 Search、RAD 和 ARD 都继续调用 Search Core 并返回当前索引快照；在 Backfill 和持久化任务收敛前，结果可能不完整。查询路径缓存 readiness 观测，并对未就绪的资源类型和 generation 输出限频警告；日志不得包含查询文本或结构化 predicate 值。一次请求不得混合部分索引和标准资源扫描结果。索引运行时失败仍然明确返回错误，并与 projection readiness 区分。

源码侧可参考 AiResourceSearchReadinessService.java、ConfigAiResourceSearchReadinessService.java 与 DefaultAiResourceSearchReadinessObserver.java。

8.2 RAD Search 读模式：AUTO / INDEX / SCAN

RAD Search 使用nacos.ai.rad.search.mode=AUTO|INDEX|SCAN选择读路径，默认AUTO：

• AUTO仍是默认值，当前与INDEX一样选择共享索引；保留独立值用于配置兼容和未来选择策略；
• SCAN是显式诊断与兼容路径；
• 模式不得改变RAD 名称、Tag、Protocol、大小写、排序、可见性或 version catalog 契约；
• Generation 未就绪时，索引支持的 total 和分页只覆盖当前已索引集合。

源码中 AgentSearchModeResolverTest.java 覆盖了模式解析逻辑，AUTO/INDEX/SCAN的交叉行为也是规范第 10 节明确要求的测试项。

9. 升级与初始化：表迁移与兼容路径

如果部署环境曾在引入持久化重试之前创建过 ARD 检索表，则在开启nacos.ai.resource.search.enabled前，必须使用当前数据库对应的 Schema 补齐三个协议无关关系表：

• ai_resource_search_document；
• ai_resource_search_chunk；
• ai_resource_task。

MySQL、PostgreSQL、Derby 和 Oracle 应分别使用匹配的当前主数据源 Schema。即使 document 和 chunk 表中已存在数据，也必须创建 task 表——该表保存任务类型、版本化 Payload 和 Result、阶段、重试、租约、revision 和完成检查点，不能替代两个索引表。

9.1 从旧表迁移到 ai_resource_task

已经创建ai_resource_search_index_task的部署必须在开启检索前迁移到ai_resource_task：

中间版本的ai_resource_task若仍使用 timestamp 类型的next_execute_time和lease_until，必须转换为 Epoch 毫秒类型的next_execute_at和lease_expire_at。已有ai_resource_task表还必须增加非空且默认值为0的 BIGINTlease_token列。迁移行的task_type为search_index，并按包含 task type 的新规则重新生成 task key。在线升级时必须保留已有任务意图。对于允许丢弃任务状态的未发布开发环境，也可以删除旧 task 表并使用当前 Schema 重建，之后由 reconciliation 修复不一致的基础索引。

9.2 初始化与向量插件

• 开启 Enhancement不得修改索引正常的历史检索数据；周期 reconciliation 只有在基础索引或已配置向量索引确实需要修复时才会对历史资源执行 Enhancement；对其他索引正常的历史资源执行 Enhancement，必须由运维显式触发；
• PostgreSQL 环境如果不开启默认向量插件，无需创建任何 pgvector 对象；如果开启，则必须另外执行nacos-default-ai-vector-plugin自己维护的可选 Schema（参考 plugin-default-impl/nacos-default-ai-vector-plugin）；
• 每个新增资源类型和 projection generation 都运行 Backfill 与 readiness；Search 可以在 readiness 前使用当前快照，并随收敛自然变得完整；
• 索引是可重建派生状态，不改变标准资源或 Runtime Endpoint 的事实源，也不要求把 Runtime 状态迁移到关系检索表。

10. 兼容与测试

内部检索命名、持久化模型、表、配置和 Vector SPI package 必须保持协议无关。现有 ARD Skill、Prompt 和 MCP 的请求、cursor、排序与 artifact 行为在共享内核扩展时保持兼容。

规范明确要求测试覆盖（对应 AiResourceSearchServiceTest.java、AiResourceSearchApplicationServiceTest.java、JdbcAiResourceIndexTaskRepositoryTest.java、JdbcAiResourceSearchRepositoryTest.java 等测试类）：

• 关键词和向量召回、结构化 facet、类型化 predicate、排序、可见性、当前版本校验；
• cursor 和 numbered page、超过单页范围的全量聚合；
• 通用单类型与资源专用 Search 的一致性；
• 事务替换、两个持久化任务阶段、lease 恢复、过期 revision；
• Enhancement 幂等重试、版本化任务 Payload 和 Result、task type 隔离；
• 时区无关的 Epoch 调度、确定性时钟下的 lease 与重试边界；
• 连续生命周期合并保留活动租约、基于 lease token 防止旧 worker 释放新租约；
• 配置 fingerprint 记录但不全量重调度、生命周期 Enhancement 意图；
• 仅对实际修复资源执行 Enhancement 且不全量刷新历史数据的 reconciliation；
• Agent lifecycle 调度与 Runtime Endpoint 非调度；
• 所有可检索类型的 readiness CAS / 重启 / 新 generation；
• NOT READY 限频观测、非阻塞部分快照行为；
• AUTO/INDEX/SCAN交叉行为。

各协议适配器和资源 API 则分别测试自己的请求语法、响应一致性和单类型交叉结果。

总结

Nacos AI 资源检索规范描述了一个完全协议无关的检索内核：RAD、ARD、通用 Search 与五种资源专用 Search 共享同一套索引、Query Planner、持久化任务与 readiness 体系。理解三个关键配置（nacos.ai.resource.search.enabled、nacos.ai.resource.search.max-recall-candidates、nacos.ai.rad.search.mode）、三类关系表（document / chunk / task）、两阶段任务收敛（base_index/llm_enhancement）以及 revision + lease token 的防并发模型，是运维与二次开发该能力的基础；而升级迁移到ai_resource_task的字段映射表，则是存量 ARD 部署平滑接入检索的必经之路。需要继续深入时，可直接阅读 ai-resource-search-spec.md 原文，并结合 ai/src/main/java/com/alibaba/nacos/ai/service/search 下的核心实现逐行对照。

【免费下载链接】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