Yao Agent Search 模块设计深度解析：统一 RAG 搜索、JSAPI 与引用追踪实战指南

• Agent 框架
• 后端
• 低代码
• RAG

导读

本文基于 Yao 开源仓库中 agent/search/DESIGN.md 的设计文档，结合 agent/search 目录下的实际源码，系统讲解 Yao Agent 内置的 Search 模块。该模块为 Agent 提供统一的 RAG（检索增强生成）接口，覆盖 Web 搜索、知识库（KB）向量/图谱检索与数据库（DB）结构化查询三大场景，并对外暴露ctx.searchJSAPI 供 Create/Next Hook 灵活调用。读完本文，你将掌握搜索模块的三层配置体系、Handler + Registry 架构、Promise风格的并行搜索语义、引用（Citation）与 Trace 可观测性设计，并能在自己的 Assistant 中落地带引用追踪的检索增强对话。

模块定位：一个统一接口，三类数据源

Search 模块解决的核心问题是：Agent 需要实时信息（Web）、内部知识（知识库）与业务数据（数据库）时，不应各自为政。它把三类检索统一到同一个接口之下：

从源码结构看，整个模块遵循与content模块一致的Handler + Registry 模式：types/只定义类型、interfaces/只依赖types/、handlers/（web/kb/db）提供具体实现、根包search.go统一组装对外 API，同时通过 jsapi.go 暴露 JS 绑定。

模块的关键能力清单（均已在 DESIGN.md 与源码中确认）：

• 统一 JSAPI：ctx.search.Web()、ctx.search.KB()、ctx.search.DB()、ctx.search.All()/Any()/Race()；
• 引用系统：为每条结果自动生成引用 ID（#ref:xxx），供 LLM 在回答中标注来源；
• 实时输出：通过 Loading 组件 + Replace 模式把搜索进度流式推送给客户端；
• Trace 集成：以最小化的 Trace 节点向用户透明报告搜索执行状态；
• Reranking：内置（权重打分）、Agent（委托 LLM）或 MCP（外部服务）三种重排模式；
• 优雅降级：单路搜索失败不会阻断 Agent 主流程。

快速上手：在 Create Hook 中发起搜索

文档给出的最小可用示例位于 Create Hook 中，直接调用ctx.search即可：

// 在 Create hook 中（assistants/my-assistant/index.ts） function Create(ctx, messages, options) { const query = messages[messages.length - 1].content; // 简单 Web 搜索 const result = ctx.search.Web(query, { limit: 5 }); // 或者跨数据源并行搜索 const [web, kb, db] = ctx.search.Parallel([ { type: "web", query, limit: 5 }, { type: "kb", query, collections: ["docs"] }, { type: "db", query, models: ["product"] }, ]); return { messages: [{ role: "system", content: formatContext(web, kb, db) }], uses: { search: "disabled" }, // Hook 已处理搜索，禁用自动搜索 }; }

要点：Hook 内调用ctx.search.*得到的每一条结果都会被标记为source = "hook"（权重 0.8）；当 Hook 已经注入搜索结果时，通过返回uses: { search: "disabled" }关闭自动搜索，避免重复检索。若 Hook 未处理，则返回{ messages: [] }，让系统按 Assistant 配置自动执行搜索。

总体架构与搜索流程

搜索主流程

文档用一张流程图概括了整个搜索链路（Stream Start → 判断 Uses.Search → Hook 处理判定 → 自动搜索 → 并行执行 → 合并 → 重排 → 生成引用 → 注入 System Prompt → LLM 调用 → 带引用输出）。其核心判定逻辑如下：

1. Uses.Search == "disabled"→ 跳过搜索；
2. Hook 已返回uses.search = "disabled"→ 跳过搜索；
3. 否则进入自动搜索（executeAutoSearch），读取 Assistant 合并后的搜索配置，并行执行 Web/KB/DB，重排并生成引用，最后把上下文注入消息。

Stream() 中的时序

文档中的时序图清晰地展示了Stream(ctx, messages, options)的执行顺序：初始化 →（可选）Create Hook → BuildRequest/BuildContent → 自动搜索判定 → LLM 调用（携带搜索上下文）→（可选）Next Hook → 输出（响应可能包含#ref:xxx引用）。实现文件为 agent/assistant/search.go（核心集成逻辑）与 agent/assistant/agent.go（Stream 集成点）。

从源码结构可以推断，executeAutoSearch中关键字提取的触发条件是：Web 搜索启用、Skip.Keyword未置位、且uses.keyword已配置——满足时先通过keyword.NewExtractor提取关键词，再用关键词拼接后的字符串发起 Web 搜索。

目录结构与依赖规则

文档给出的目录结构已在仓库中完全落地（agent/search/下可见defaults/、handlers/{web,kb,db}/、interfaces/、nlp/{keyword,querydsl}/、rerank/、types/等子包）。依赖规则是分层解耦的关键：

1. types/—— 零内部依赖，仅依赖标准库与外部包；
2. interfaces/—— 仅导入types/；
3. rerank/、nlp/、defaults/—— 导入types/与interfaces/；
4. handlers/*—— 导入types/、interfaces/，可按需使用nlp/；
5. 根包（search.go、registry.go、jsapi.go等）—— 汇总所有子包，提供公共 API。

该分层让各子包互不产生循环依赖，这也是interfaces/与types/被独立拆包的根本原因。

核心实现：Searcher 与并行搜索语义

Searcher 主实现

agent/search/search.go 中的Searcher是模块的门面：持有合并后的*types.Config、按搜索类型注册的handlers映射、reranker与citation生成器。New()构造时按类型注入具体 handler（Web 依据uses.Web决定模式、KB 固定内置、DB 依据uses.QueryDSL）。

Search()单次搜索的执行链路非常清晰：

1. 按req.Type找到 handler 并执行（handler 实现interfaces.ContextHandler时优先走SearchWithContext，为 Agent/MCP 模式提供上下文）；
2. 依据req.Source为每条结果赋予权重（Config.GetWeight，见 agent/search/types/config.go）；
3. 若请求要求重排，调用reranker.Rerank()；
4. 为每条结果顺序生成引用 ID。

任何 handler 错误都不会向上抛出阻断主流程，而是包装进Result.Error返回（文档明确强调"搜索失败不应阻断 Agent 主流程"这一设计目标）。

Promise 风格的并行搜索

并行搜索是模块最具设计感的特性：三种模式直接对标 JavaScript Promise 语义，源码中三种方法的实现逻辑与文档一致：

Searcher接口（agent/search/interfaces/searcher.go）对外暴露Search、All、Any、Race与BuildReferences。这一设计让 Hook 作者可以用熟悉的Promise心智模型编排多源检索。

核心类型与统一上下文协议

Request / Result / ResultItem

types.Request（agent/search/types/types.go）是搜索请求的完整描述：通用字段（query、type、limit、source），Web 专属（sites、time_range），KB 专属（collections、threshold、graph），DB 专属（models、wheres、orders、select——其中wheres/orders直接复用 GOU QueryDSL 的gou.Where/gou.Orders类型，保证与 Yao 查询系统完全兼容），以及可选的rerank选项。

Result的设计值得注意：它不再只装最终条目，而是同时承载中间处理产物——Keywords（Web 提取的关键词）、DSL（DB 生成的 QueryDSL）、Entities/Relations（Graph RAG 抽取的实体与关系）、GraphNodes（KB 图谱关联节点）。文档中的设计说明指出，这样做有三个目的：

1. 便于调试：所有处理步骤都被留存，可供后续分析；
2. 支撑调优：可分析关键词质量、DSL 生成质量与实体抽取质量；
3. 统一数据流：Handler 在执行过程中直接填充这些字段，executeAutoSearch无需另行收集。

Reference 与<references>XML

所有数据源（Content 模块、Hook、自动搜索）最终都归一为同一份Reference结构，再格式化为统一的<references>XML 注入 LLM：

<references> <ref id="ref_001" type="db" weight="1.0" source="user"> Product: iPhone 15 Pro Price: $999 Category: Electronics </ref> <ref id="ref_002" type="kb" weight="0.8" source="hook"> The iPhone 15 Pro features the A17 Pro chip with improved performance... URL: https://example.com/iphone-review </ref> </references>

BuildReferenceContext（agent/search/reference.go）负责组装ReferenceContext：包含References列表、格式化好的XML与引用指令Prompt；FormatReferencesXML完成 XML 渲染。GetCitationPrompt则按"自定义 Prompt > 默认 Prompt"的优先级取引用指令。

引用系统：让 LLM 的输出可溯源

引用系统是搜索模块与 LLM 输出衔接的桥梁。文档给出两个层次的引用方案：

• 生成侧：CitationGenerator（agent/search/citation.go）用atomic.AddUint64生成线程安全的递增引用 ID。文档示例为ref_001格式；实际源码则返回纯数字字符串（Next()返回1, 2, 3...），并提供NextInt()/Current()/Reset()辅助方法。
• 输出侧：LLM 以 HTML 链接形式输出引用，前端可解析渲染：

The iPhone 15 Pro<a class="ref" ># 全局搜索配置，对所有 Assistant 生效，可被 Assistant 级配置覆盖 web: provider: "tavily" # "tavily", "serper", 或 "serpapi"（仅内置模式） api_key_env: "TAVILY_API_KEY" max_results: 10 kb: threshold: 0.7 graph: false db: max_results: 20 keyword: max_keywords: 10 language: "auto" querydsl: strict: false rerank: top_n: 10 citation: format: "#ref:{id}" auto_inject_prompt: true weights: user: 1.0 hook: 0.8 auto: 0.6 options: skip_threshold: 5 # 用户提供 >= N 条结果时跳过自动搜索

仓库测试目录 unit-test/agent/app/agent/search.yml 中提供了可参考的完整配置实例。

Uses 配置（agent/agent.yml）

uses决定每个处理环节采用哪种实现（内置 / Agent 委托 / MCP 工具）：

# agent/agent.yml uses: keyword: "builtin" # "builtin", "workers.nlp.keyword", "mcp:my-server.extract_keywords" querydsl: "builtin" # "builtin", "workers.nlp.querydsl", "mcp:my-server.generate_dsl" rerank: "builtin" # "builtin", "workers.rerank", "mcp:my-server.rerank" web: "builtin" # "builtin", "workers.search.web", "mcp:my-server.web_search" # 注：kb 与 db 始终使用内置实现（访问内部数据）

工具值格式统一为"builtin"、"<assistant-id>"（Agent）或"mcp:<server>.<tool>"（MCP）。Uses.Search的取值语义如下：

Assistant 级配置（package.yao）

assistants/<assistant-id>/package.yao可在uses与search两个键下覆盖全局配置，例如把关键词提取切换为 LLM 模式、把重排切换为 MCP 工具：

{ "uses": { "search": "builtin", "web": "builtin", "keyword": "workers.nlp.keyword", // 用 LLM 做关键词提取 "querydsl": "workers.nlp.querydsl", "rerank": "mcp:my-server.rerank" // 用 MCP 工具重排 }, "search": { "web": { "provider": "tavily", "max_results": 5 }, "kb": { "collections": ["docs", "faq"], "threshold": 0.7, "graph": true }, "db": { "models": ["product", "order"], "max_results": 20 }, "keyword": { "max_keywords": 5 }, "querydsl": { "strict": true }, "rerank": { "top_n": 5 }, "citation": { "format": "#ref:{id}", "auto_inject_prompt": true } }, "kb": { "collections": ["docs", "faq"] }, "db": { "models": ["product", "order", "customer"] } }

配置加载与合并

全局配置加载在 agent/load.go 中完成（initSearchConfig从agent/search.yml读取并与SystemDefaults合并），Assistant 级合并则在 agent/assistant/load.go 的GetMergedSearchConfig()中执行（global < assistant）。文档给出的三段 Go 伪代码与实际源码结构一致，可直接对照阅读。

JSAPI：Hook 内调用搜索

架构与工厂注入

为避免context与search包之间的循环依赖，JSAPI 采用接口 + 工厂注册模式：agent/context/jsapi_search.go定义SearchAPI接口与 V8 绑定方法，agent/search/jsapi.go的JSAPI结构体实现该接口；Assistant 包初始化时通过SetJSAPIFactory(ConfigGetter)注入工厂函数（按ctx.AssistantID解析该 Assistant 的合并配置与 uses），最终在context/jsapi.go的NewObject()中把search对象挂载到ctx上。这样ctx.search在 Hook 中即可用。

API 方法一览

// 单次搜索 ctx.search.Web(query: string, options?: WebOptions): Result ctx.search.KB(query: string, options?: KBOptions): Result ctx.search.DB(query: string, options?: DBOptions): Result // 并行搜索（Promise 语义） ctx.search.All(requests: Request[]): Result[] // 等全部完成 ctx.search.Any(requests: Request[]): Result[] // 首个成功即返回 ctx.search.Race(requests: Request[]): Result[] // 首个完成即返回

对应选项类型（agent/search/jsapi.go 的buildRequest会逐项解析这些选项）：

• WebOptions：limit（默认 10）、sites、timeRange（"day"/"week"/"month"/"year"）、rerank；
• KBOptions：collections、threshold（0-1）、limit、graph、rerank；
• DBOptions：models、wheres（GOU QueryDSL Where 格式）、orders、select、limit（默认 10）、rerank。

wheres的字段表达式与操作符沿用 GOU QueryDSL 约定：field/value/op（"="、"like"、">"、"<"、">="、"<="、"in"、"is null"等）/or（OR 条件）/wheres（嵌套分组）。

实战示例

文档提供了 5 组可直接套用的 Hook 示例：Web 搜索（限定timeRange: "week"）、KB 图谱搜索（collections + threshold + graph）、DB 搜索（models + wheres预过滤）、All()三源并行合并、Any()/Race()快速返回，以及自定义引用格式（返回citation: { autoInjectPrompt: false }覆盖默认引用指令）。这些示例均以"有结果 → 注入 system 消息并禁用自动搜索；无结果 → 返回空 messages 交由自动搜索兜底"为统一范式，值得在实际 Assistant 中复用。

搜索执行与 NLP 处理

查询处理链路

关键词提取（nlp/keyword/）

采用 Handler + Registry 模式，三种模式：

文档给出了直观对比："I want to find the best wireless headphones under $100"经 builtin 提取得到["wireless", "headphones", "find", "best"]，而 agent 模式得到语义更准的["wireless headphones", "under $100", "best"]。需要高精度时优先 Agent/MCP 模式。

Embedding：跟随 KB collection 配置

Embedding不在nlp/包内——每个 KB collection 自持 embedding provider 与模型配置，KB handler 直接调用 collection 的 embedding API（见文档中handlers/kb/handler.go的伪代码流程：取 collection → 用其配置生成向量 → 向量检索）。GraphRAG 所需的实体类型同样按 collection 定义。

QueryDSL 生成（nlp/querydsl/）

与关键词提取同构："builtin"基于模型 schema 做模板匹配；Agent 模式由 LLM 结合自然语言与 schema 生成 DSL；MCP 模式调用外部服务。文档示例展示了从"Products cheaper than $100 from Apple"到{"wheres": [{"column": "price", "op": "<", "value": 100}, {"column": "brand", "value": "Apple"}]}的生成过程。

三大 Handler 与内置 Provider

Web 搜索（handlers/web/）

三种模式由uses.web决定（agent/search/handlers/web/handler.go 中的SearchWithContext分发逻辑与文档一致）：builtin 直接调内置 provider；mcp:前缀走 MCP；其余视为 Assistant ID 走 Agent 模式（Agent 模式缺少 ctx 时返回带错误提示的空结果）。

内置 Provider（uses.web = "builtin"时）：

SerpAPI 支持多引擎切换（engine配置）：google（默认）、bing、baidu、yandex、yahoo、duckduckgo、naver、ecosia、seznam等：

# agent/search.yml web: provider: "serpapi" api_key_env: "SERPAPI_API_KEY" engine: "bing" # 改用 Bing max_results: 10

值得注意的实现细节：内置 Web 搜索实际委托给tools/websearch（websearch.Search(req.Query, limit, userID, teamID)），配置读取遵循 Settings → ENV 的优先级；同时传入ctx.Authorized中的 user/team 信息，说明内置搜索与权限体系存在联动。

Agent 模式（AI Search）：当uses.web指向某个 Assistant（如"workers.search.web"）时，搜索被升级为意图感知流程：理解用户意图 → 生成多条优化查询 → 多源执行 → 去重/排序/总结 → 返回结构化结果。文档给出了完整流程示意（用户查询 → 意图理解 → 优化查询词 → 多查询执行 → 分析去重 → 高质量结果）与示例 AI Search Assistant 代码（在 Create Hook 中调用analyzeIntent、generateQueries，逐条ctx.search.Web()收集结果后mergeAndRank）。

KB 搜索（handlers/kb/）

KB handler 仅依赖配置（KBConfig），固定为内置实现，负责向量检索与可选的图谱关联（GraphRAG）。文档标注vector.go（向量相似度检索）与graph.go（图谱关联）为规划中的文件，handler 主体已就绪。

DB 搜索（handlers/db/）

DB handler 依据uses.querydsl决定查询 DSL 的生成方式，核心链路为：自然语言 → 模型 schema 感知 → LLM 生成 QueryDSL → 在各模型上执行。它深度集成 Yao 的 Model/QueryDSL 体系，支持三类模型 ID：

文档还强调 DB 查询是权限感知的（尊重__yao_*权限字段）。文档中的 QueryDSL 生成 Prompt 示例（给定 schema → 用户查询 → 输出含wheres/orders/limit的 DSL）可作为自建 AI Search Assistant 的提示词模板。

重排（Reranking）

rerank.Reranker（agent/search/rerank/reranker.go）按uses.rerank分发到三种实现：

• Builtin：加权打分排序，weightedScore = score * weight，降序取 TopN；
• Agent：委托 LLM Assistant 语义重排，Agent 需返回两种格式之一——{ "order": ["ref_003", "ref_001", ...] }或{ "items": [{ "citation_id": "ref_003" }, ...] }；
• MCP：调用外部 MCP 工具，MCP 引用格式非法时自动回退到 builtin。

mergeOptions的实现体现了"运行时选项 > 配置默认值 > 内置默认 10"的优先级。源码注释同样提示：生产环境需要语义理解时优先 Agent/MCP 模式。

可观测性：Trace 与实时输出

Trace 节点

搜索操作创建最小化 Trace 节点向用户报告执行状态（状态常量来自trace/types.NodeStatus：pending/running/completed/failed）。单次搜索的节点结构为search类型节点，携带label（i18n："Search"/"搜索"）、status、input（query+types）、output（result_count）；并行搜索则在父节点下挂search_item子节点（web/kb/db 各一个），各自独立报告状态与结果数。

节点日志方法（node.Info/Debug/Warn/Error）会把详情广播给客户端：搜索开始（Info）、各类型完成（Debug，含数量与耗时）、单路失败（Warn，非阻断）、最终汇总（Info）。日志事件结构types.TraceLog含timestamp/level/message/data/node_id，经 SSE 推送。

实时输出：Loading + Replace

搜索进度通过Loading 组件 + Replace模式呈现：ctx.Send()发送{ type: "loading", props: { message: "Searching..." } }→ 搜索完成后ctx.Replace(loading_id, ...)更新为结果消息 → 再置done: true让前端移除指示器。Loading props 仅两个：message（本地化文本）与done（true 时前端移除指示器）。本地化文案覆盖六种场景：加载中、成功 1 条、成功 N 条、部分失败、全部失败、无结果。

搜索结果存储与引用点击溯源

为支撑引用点击与历史回放，搜索结果按请求落库。数据模型为Chat → Request → Message[] + SearchResult[] → Reference[]，存储表agent_search（yao/models/agent/search.mod.yao）的核心字段包括：request_id/chat_id（均建索引）、query、config（本次使用的搜索配置，供调优分析）、keywords/entities/relations/dsl（中间产物）、source、references（含全局索引的引用数组）、graph、xml、prompt、duration、error，并开启时间戳与软删除。

引用定位路径为request_id + index：LLM 输出使用<a index="1" />形式的带索引标签，前端点击后通过接口GET /api/chat/{chat_id}/request/{request_id}/reference/{index}精确取回该引用。多路搜索（如工具调用触发二次搜索）时，index全局递增，因此request_id + index恒唯一。

ChatStore接口扩展了四个方法（agent/store/types/store.go 的规划）：SaveSearch、GetSearches、GetReference、DeleteSearches；Xun 存储实现（store/xun/search.go）把Search记录 JSON 序列化后插入，GetReference则跨全部搜索记录按索引查找。存储逻辑封装在 agent/assistant/search.go 的saveSearch方法中，executeAutoSearch执行完毕后一次性把完整中间产物写入存储（文档给出的SearchExecutionResult结构体完整承载了 Query/Config/Keywords/Entities/Relations/DSL/Source/RefCtx/Graph/Duration/Error）。

与 Content 模块的统一数据源协议

用户消息可能携带type="data"的 ContentPart（DataSourceModel、DataSourceKBCollection、DataSourceKBDocument、DataSourceTable、DataSourceAPI、DataSourceMCPResource），用户只声明数据源 ID，过滤条件由 Search 模块从自然语言生成。例如：

{ "role": "user", "content": [ { "type": "text", "text": "Show me products under $100" }, { "type": "data", "data": { "sources": [ { "type": "model", "name": "product" }, { "type": "kb_collection", "name": "product-docs" } ] } } ] }

处理逻辑（content.Vision()中的processDataContent()，规划位置为 agent/content/content.go）：model走 DB handler 生成 QueryDSL 并执行；kb_collection走 KB handler 向量检索；kb_document直接取回文档；mcp_resource读取 MCP 资源。这样 Search 模块被复用两处：自动搜索与用户显式数据引用。

统一上下文协议：三路来源归一为统一Reference后，按score × weight合并去重排序（同一记录来自不同源时保留最高权重版本），再构建<references>XML 注入 LLM。权重与行为规则为：用户数据足够（≥skip_threshold）时跳过自动搜索；最终排序为score * weight。权重可通过全局/Assistant 配置调整（如提高 hook 权重到 0.9、降低 auto 到 0.5）。系统自动完成这一整套加权与上下文构建，Hook 内无需手工处理权重。

错误处理与优雅降级

搜索错误不会阻断 Agent 流程：错误被包装进Result.Error字段返回（Search方法对 handler 错误统一包装，并行执行对每个 goroutine 都有recover()兜底）。Hook 内可按如下方式优雅处理：

const result = ctx.search.Web(query); if (result.error) { console.warn("Search failed:", result.error); // 回退或继续主流程 }

相关文件索引

• 设计文档：agent/search/DESIGN.md
• 类型定义：agent/search/types/types.go、agent/search/types/config.go、agent/search/types/reference.go、agent/search/types/graph.go
• 接口定义：agent/search/interfaces（handler.go、searcher.go、reranker.go、nlp.go）
• 默认配置：agent/search/defaults/defaults.go
• 核心实现：agent/search/search.go、agent/search/registry.go、agent/search/citation.go、agent/search/reference.go、agent/search/jsapi.go
• Handler：agent/search/handlers/web、agent/search/handlers/kb、agent/search/handlers/db
• 重排与 NLP：agent/search/rerank、agent/search/nlp/keyword、agent/search/nlp/querydsl
• 测试与示例配置：unit-test/agent/app/agent/search.yml、agent/search/search_integration_test.go、agent/search/jsapi_integration_test.go
• 相关设计文档：agent/context/JSAPI.md、agent/store/CHAT_STORAGE_DESIGN.md

需要说明的是：文档中标注为TODO的部分（如 KB 的vector.go/graph.go、DB 的query.go/schema.go、querydsl 的 builtin 实现）属于规划中的能力，实际能力以当前仓库已落地的 handler 与测试覆盖为准。在 Yao 中为 Agent 接入检索增强时，建议按"全局agent/search.yml定基线 → Assistantpackage.yao按业务覆盖 → Create Hook 按场景自定义并返回uses.search控制自动搜索"的路径落地，即可获得带权重、引用与 Trace 的完整搜索体验。

• Agent 框架
• 后端
• 低代码
• RAG