搜索与检索
Search & Retrieval
多搜索源聚合、树状递归深度研究、知识缺口检测。Agent 获取外部知识的核心能力。
子问题
1.多源聚合：整合 Web 搜索、学术搜索、代码搜索等多种来源
2.递归深入：初始搜索不够时，自动生成子查询深入研究
3.知识缺口检测：识别当前信息不足以回答的部分
4.源可信度：评估搜索结果的可信度和相关性
5.去重与融合：多源结果的去重和信息融合
6.anti-look-ahead 过滤：回测中如何确保搜索结果不包含交易日之后发布的信息
7.搜索结果随机采样：多条搜索结果如何在控制成本的同时保持信息多样性
8.搜索能力自诊断：Agent 如何在运行时判断自己能访问哪些搜索源并获取修复建议
9.凭证安全管理：多平台 Cookie/Token/API Key 的统一存储、权限保护与自动脱敏
10.跨平台 Cookie 提取：如何从 Chrome/Firefox 等浏览器自动提取多平台登录凭证
11.VDB 客户端暴露：如何在封装统一接口的同时保留底层客户端的完整功能访问权限
12.ID 生成策略：不同 VDB 对 ID 类型要求不同（int/string/UUID）时如何统一生成唯一标识
13.分块边界处理：sentence/paragraph 模式下超长单元如何截断而不破坏语义
14.模态校验时机：嵌入模型不支持某种模态时应在 add_documents 还是 Reader 阶段报错
15.异步接口一致性：文件读取等同步操作是否应该包装为 async 以保持接口统一
16.Parent-Child 分块边界选择：按标题切分 vs 按固定长度切分对不同文档结构的适用性差异
17.parent 存储介质选择：JSON 文件 vs 数据库在并发读写和规模扩展上的权衡
18.Agent 检索深度自适应：如何让 Agent 根据查询复杂度自主决定 child→parent 回溯的层数
19.URL 类型自动检测：用户粘贴 URL 后如何自动识别 Twitter/RSS/Reddit 等源类型
20.采集频率分级：不同源类型如何设定差异化采集间隔避免过度请求
21.订阅组合去重：多用户相同订阅组合如何共享 Digest 降低 LLM 调用成本
22.Source 软删除级联：源被删除后订阅者和 Pack 安装如何优雅处理
23.搜索成本感知：Agent 如何在搜索结果中获取本次调用成本并据此调整后续策略
24.搜索-记忆闭环：搜索结果如何自动格式化并持久化到 Agent 长期记忆
25.记忆文件自动索引：工作目录下记忆文件变更时如何自动触发向量库和全文索引重建
26.存储后端平台适配：向量数据库在不同操作系统上的兼容性差异如何通过自动检测选择后端
27.搜索工具条件注册：API Key 缺失时如何优雅地从 Agent 工具列表中移除搜索能力
28.搜索调用预算：如何通过 prompt 硬限制搜索次数防止 Agent 无限搜索消耗配额
29.搜索后反思：每次搜索后如何强制 Agent 评估信息充分性再决定是否继续搜索
30.代码语义索引：如何用 LLM 理解代码功能并构建可检索的结构化索引
31.离线索引与在线检索分离：如何平衡索引构建成本与检索实时性
32.引擎选择：不同文档类型和精度需求下如何自动选择最优 RAG 引擎
33.组件正交：RAG 管道各阶段（解析/分块/嵌入/索引/检索）如何独立替换不互相影响
34.嵌入后端适配：如何统一接口支持 OpenAI/Jina/Cohere/Ollama 等多种嵌入服务
35.嵌入维度一致性校验：切换嵌入后端后如何确保已有索引与新向量维度匹配
36.代码文件 token 预算：不同文件类型设定差异化 token 上限避免嵌入 API 超限
37.索引缓存失效判定：持久化索引加载后如何判断嵌入是否仍然有效
38.搜索源热切换：如何在不改代码的情况下切换底层搜索 API 实现
39.页面内容净化：从原始 HTML 中提取正文并转为结构化 Markdown
40.搜索结果字段归一化：不同供应商返回字段名不同时如何统一映射为标准格式
41.图片搜索零成本方案：如何用免费 API 满足图片生成场景的参考图需求
42.HTML 多模态提取：网页内容中的图片如何转为 VLM 可处理的消息格式
43.置信度驱动迭代深度：如何用 LLM 评估检索充分性并动态决定是否继续检索
44.自适应检索预算：如何根据查询复杂度动态调整迭代次数、置信度阈值和行预算
45.Full/Filtered 双索引：多仓库场景下如何分离全量索引与按需子索引避免跨仓库噪声
46.仓库选择降级链：LLM 选仓库失败时如何逐级降级到 embedding+BM25 再到用户原始选择
47.引用 URL 验证：LLM 生成的引用如何通过搜索结果白名单校验防止幻觉
48.CJK 语义去重：中英文混合标题如何用双字组合+ASCII词的Jaccard相似度去重
49.概念驱动搜索：如何用 LLM 先提取需解释的技术概念再定向搜索而非盲目全文搜索
50.评论内容分离：抓取内容中正文与社区评论如何分离处理避免评论噪声污染分析
51.记忆类型分区检索：不同类型记忆（工作/长期/用户/工具/技能）如何设计独立检索路径并行执行
52.LLM 驱动检索充分性判断：如何用 LLM 在每轮迭代中评估当前记忆是否足以回答查询并生成补充检索短语
53.记忆重组增强：多轮检索累积的记忆碎片如何通过 LLM 重组为连贯的增强记忆
54.Reranker 策略选择：不同对话场景（单轮/多轮/带背景）如何选择不同的文档拼接策略进行重排序
55.元数据 Boost 加权：如何基于 user_id/session_id/tags 等元数据对 Reranker 分数进行动态加权
56.对象检索：如何将结构化 Python 对象（工具定义、API Schema）存入 RAG 索引并在检索后还原
57.能力检测：混合检索器中如何验证子检索器是否支持 persist/add_nodes 等操作
58.嵌入维度自适应：不同嵌入后端输出维度不同时如何自动匹配 FAISS 索引维度
59.CAPTCHA 冷却机制：搜索 fallback 被反爬后如何快速失败避免无意义重试
60.缓存 key_state 区分：API Key 热更新后如何自动失效旧缓存结果
61.SSRF 逐跳检查：手动重定向跟踪中每跳都重新做 DNS 解析防止 rebinding
62.Reranker 候选截断：LLM 上下文有限时如何限制 rerank 候选数量并截断 passage
63.API Key 前缀推断路由：如何从 Key 格式自动判断应连接直连 API 还是代理网关
64.Gemini Grounding 重定向解析：Google 搜索引用 URL 需要 HEAD 请求解析真实地址
65.HTML 深度嵌套防护：恶意 HTML 嵌套数千层导致 DOM 解析 stack overflow 的防御
66.Cloudflare Markdown for Agents 协议：服务端预渲染 Markdown 时的 Content-Type 识别与直接使用
67.记忆文件常青判定：MEMORY.md 等常青知识文件不应被时间衰减惩罚的识别逻辑
68.搜索参数白名单过滤：不同搜索源接受不同参数时如何安全传递配置
69.原生搜索检测：如何判断 OpenAI/Anthropic 的原生 web search 是否在响应中被调用
70.搜索源限流差异化：不同 API 的限流策略（固定延迟/指数退避/自适应）如何统一管理
71.MCP 工具名冲突：外部 MCP 工具与内置工具同名时的检测与跳过机制
72.素材质量排序：多维评分（分辨率距离+质量等级+文件大小）的权重设计
73.标签过滤空结果降级：硬约束过滤后无结果时的随机采样兜底策略
74.嵌入模型本地缓存：预下载模型与 Hub 自动下载的优先级切换
75.目录递归深度控制：如何在层级检索中平衡搜索深度与延迟，收敛检测的轮数阈值选择
76.分数传播系数调优：父子分数混合比例 α 对不同数据分布的敏感性
77.热度衰减半衰期选择：不同业务场景下 half_life_days 的最优值差异
78.意图分析可靠性：LLM 生成的 TypedQuery 解析失败时的降级策略
79.多模态实体归属：图表公式抽取的子实体如何通过 belongs_to 关系关联到主实体
80.查询时视觉增强：检索上下文中的图片路径如何安全地转换为 VLM 可处理的 base64 格式
81.多模态处理状态跟踪：文本处理和多模态处理异步完成时如何准确标记文档完整处理状态
82.过滤器格式归一化：Qdrant 结构化 JSON 与 LanceDB SQL 字符串的双向自动转换
83.增量嵌入索引：文档更新时如何通过 chunk 内容比对仅对变更部分重新计算向量
84.向量点序列化迁移：如何用 Avro 二进制格式导出向量点实现跨用户跨实例文档复制
85.嵌入长文本分块平均：超过 API 限制的文本如何按句子边界分块后取平均向量
86.LLM-as-Reranker：用本地 LLM 生成 0-1 相关性评分替代专用 Reranker API
87.供应商降级触发条件：仅限流降级 vs 所有异常降级的权衡
88.记忆索引增量更新：全量重建 vs 增量追加的性能取舍
89.多报告拼接检索：多份分析报告拼接为单一查询的信噪比问题
90.视觉粒度控制：全页检索粒度太粗时如何通过坐标裁剪获取细粒度视觉信息
91.多向量与单向量引擎选择：token 级多向量精度高但索引大，单向量适合大规模的权衡
92.视觉嵌入像素预算：VLM 输入 token 数与图片分辨率的平衡策略
93.RL 训练搜索环境：如何将检索-裁剪-回答循环封装为可训练的多轮强化学习环境
94.多模态增量索引：图片/视频/文本混合语料的增量索引构建与检查点恢复
95.LLM-as-Search：用 LLM 的搜索 grounding 能力替代传统搜索 API 的可行性与成本权衡
96.金融数据源认证：SEC EDGAR 身份配置、CNINFO 反爬 Header 伪装、RootData Playwright 自动化的差异化接入
97.检索即导入一致性：工具调用获取文档后立即写入向量库时的幂等性和并发安全
98.向量引擎可选性：向量数据库不可用时搜索系统如何仍提供有意义结果
99.粒度化向量文档：一条记录拆分为多个语义单元独立嵌入时的去重与排名合并
100.MCP 协议搜索集成：通过 MCP stdio 与向量数据库子进程通信的连接管理与容错
101.层级递进深度控制：三层检索中如何通过 LLM 充分性判断实现 early termination 避免过度检索
102.双模式检索统一接口：RAG 向量检索与 LLM 排序两套实现如何共享相同的 workflow 步骤结构
103.引用追踪检索：Category summary 中的 [ref:ITEM_ID] 引用如何跳过全量搜索直接定向获取关联 Item
104.Salience 三因子平衡：cosine similarity × reinforcement log × recency decay 三因子的权重平衡与半衰期选择
105.搜索源质量分级：如何为 20+ 搜索源建立静态质量权重体系并用于结果排序
106.AI 话题自动增强：检测到特定领域话题时如何自动扩展搜索源覆盖范围
107.查询回滚保护：重复查询检测后的回滚操作如何防止死循环
108.语言感知搜索路由：中英文混合查询如何自动选择对应语言区域的搜索引擎
109.微信公众号搜索：如何通过搜狗/腾讯云 SearchPro 搜索微信生态内容
110.多索引类型共存：同一 Collection 不同向量字段如何绑定不同索引算法（HNSW/IVF/Flat）
111.距离度量归一化：L2/IP/COSINE 不同度量的分数如何统一到 [0,1] 区间进行加权融合
112.嵌入函数 Protocol 设计：如何用 duck typing 而非继承实现嵌入后端可插拔
113.查询并发度控制：多向量并行查询的线程池大小如何根据部署环境自适应
各项目的解法36 solutions
横向对比
| 维度 | GPT-Researcher | MiroThinker | DeepResearch | AI-Trader | Agent-Reach | AgentScope | agentic-rag-for-dummies | ClawFeed | ClawWork | CoPaw | DeepAgents | DeepCode | DeepTutor | DeepWiki | DeerFlow | FastCode | Horizon | LightRAG | MemOS | MetaGPT | Moltis | OpenClaw | Open | OpenManus | OpenStoryline | OpenViking | PageIndex | RAG-Anything | Refly | TradingAgents | VRAG | ValueCell | claude-mem | memU | vibe-blog | zvec |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 搜索架构 | DeepResearchSkill 树状递归（breadth=4, depth=2） | Serper + 智谱双引擎语言感知路由 | Visit 两阶段目标导向提取管线 | Jina Search + Alpha Vantage 双源 MCP 工具，无向量数据库 | 零 wrapper 模式：Channel 只做 URL 路由和可用性检查，Agent 直接调用上游工具 | 三层抽象：Reader/Store/KnowledgeBase，组件正交可独立替换 | Qdrant 混合检索（dense HuggingFace + sparse BM25），Agent 驱动两阶段检索 | URL 模式匹配 + HTTP 内容嗅探两阶段检测，9 种源类型统一抽象 | 环境变量驱动双供应商路由（Tavily/Jina），Agent 无感知切换 | ReMe 双通道（向量+全文检索）+ MCP StdIO 外部搜索 | Tavily 单源直连，无向量数据库，无本地索引 | MCP Server 化双引擎：Bocha 中文 AI 搜索 + Brave 英文搜索 + LLM 代码索引 | 双层架构：RAG 三引擎（LlamaIndex/LightRAG/RAGAnything）+ Web 六 provider | AdalFlow Sequential 管道：TextSplitter→ToEmbeddings→FAISS FlatL2 | 四源声明式配置：Tavily + Jina AI + Firecrawl + DuckDuckGo，config.yaml 切换 | FAISS HNSW 语义 + BM25 关键词 + NetworkX 图遍历三层混合，IterativeAgent 多轮迭代 | 五源并发采集 + DuckDuckGo 概念驱动搜索增强，无向量数据库 | — | 五路并行分区检索 + 四引擎混合召回（Graph/Vector/BM25/Fulltext） | 双层架构：Web 搜索(策略模式6后端) + RAG 检索(工厂模式4引擎) | 双子系统：Web 搜索工具 + Memory 混合检索，AgentTool trait 统一注册 | 四引擎路由（Brave/Perplexity/Grok/Gemini）+ API Key 自动探测 | 双版本架构：主版本 Tavily/OpenAI/Anthropic+MCP，Legacy 版本 10+ 搜索源统一路由 | — | 双通道：本地 FAISS 向量召回 + Pexels REST API 在线搜索 | 目录递归层级检索：L0/L1 全局定位 → heapq 优先队列递归下钻 L2 | — | LightRAG 三级索引：chunk VDB + entity VDB + relationship VDB + KG 图遍历 | 双引擎并行：向量搜索(Qdrant/LanceDB) + 全文搜索(ES/Prisma)，配置切换 | BM25Okapi 词法检索 + 多源供应商路由表 | 双引擎：ColQwen2 多向量 + GVE/bge-m3 FAISS 单向量，FastAPI 分别暴露 | LLM 自主路由 7 工具 + LanceDB hybrid search（向量+BM25） | 三策略模式：Chroma 语义 + SQLite 过滤 + Hybrid 交集排序，Orchestrator 三路径决策树 | 双模式（RAG cosine topk / LLM 排序）三层级递进（Category→Item→Resource），每层后 sufficiency check | LLM 智能路由 + 规则降级，5 源并行（智谱/Serper/搜狗/arXiv/专业博客×17） | C++ 嵌入式引擎 + Python SDK，HNSW/IVF/Flat 三索引 + BM25/SPLADE 稀疏向量混合检索 |
| 去重机制 | visited_urls 跨层 URL 级去重 | filter_google_search_result() 结果过滤 | 无（每次 Visit 独立） | 随机采样 1 条 URL 抓取，隐式避免重复处理 | 无内置去重，由调用方 Agent 自行处理多源结果合并 | — | retrieval_keys Set 跟踪已检索 parent ID 和查询，压缩时注入已执行列表 | 数据库 UNIQUE(source_id, dedup_key) + INSERT OR IGNORE 天然幂等 | 无去重，每次搜索独立调用 | ReMe 内部融合，CoPaw 层不额外去重 | 无显式去重，依赖 Tavily 服务端去重 | 无显式去重，依赖 LLM 预过滤减少冗余文件分析 | RAG 实例缓存（_instances dict 按 working_dir 去重），无跨 provider 结果去重 | 无显式去重，依赖 FAISS 向量距离排序自然去重 | 无内置去重，依赖 LLM Agent 层面的 URL 去重判断 | element ID 去重合并三路分数，containment-aware 去重消除包含关系重复 | 双层去重：URL 归一化 + Jaccard 标题语义去重（ASCII+CJK） | — | 双层去重：GraphMemoryRetriever 按 ID 字典去重 + Searcher 按 memory 文本去重保留最高分 | SimpleHybridRetriever 按 node_id 集合去重，deepcopy 隔离查询 | chunk_id HashMap 累加加权分数，同一 chunk 跨通道合并 | 缓存 key 含 provider+query+参数，MMR Jaccard 去重 | URL 级去重，支持 keep_first/keep_last 策略 | — | URL seen set 跨页去重，向量召回依赖 FAISS 天然去重 | visited set 防重入 + collected 列表 URI 去重 | — | MD5 哈希 chunk_id 天然去重，查询缓存用 MD5(query+mode+content) 做 key | 增量嵌入：chunk 内容比对复用已有向量，delete-then-insert 更新 | 新闻按标题 seen_titles 集合去重 | uid/file_path 集合去重防重复索引 + repeated_nums 控制检索去重 | LanceDB 表级去重，同名文件覆盖写入 | Chroma 粒度化文档按 sqlite_id 正则提取去重，seen Set 保留最高排名 | WorkflowState 单一 query_vector 传递，同层不重复 embed；引用追踪按 ID 精确获取避免重复 | URL 集合去重 + QueryDeduplicator 按 Agent 隔离 LRU 查询去重 | Reranker 层 id_to_doc 字典自动去重，多路召回同一文档只保留一份 |
| 结果处理 | trim_context_to_word_limit(25000) 硬裁剪 | 直接返回搜索 snippet | EXTRACTOR_PROMPT → {rational, evidence, summary} 结构化提取 | Jina Reader 返回结构化 JSON，内容截断 1000 字符 | 不处理结果，Agent 直接消费上游工具的原始输出 | — | score_threshold=0.7 硬过滤 + Agent 自主判断信息充分性 | LLM 策展固定 15-20 条输出，Source 越多质量越高篇幅不变 | Tavily 返回结构化 JSON + AI 摘要，Jina 返回 Markdown 手动解析 | ToolResponse 包裹 TextBlock，Agent 直接消费文本 | markdownify 全量 HTML→Markdown 转换 | 三维度评分（文件名0.3+类型0.2+关键词0.5）排序 | AnswerConsolidator 双策略：Jinja2 模板渲染 + LLM 摘要合成 | top_k=20 检索后按 file_path 分组注入 prompt | 统一 {title, url, snippet} JSON + 4096 字符硬截断 | 类型权重 Rerank + 文件级 diversity_penalty 多样性控制 | AI 评分门控 → 概念提取 → Web 搜索 → 双语背景生成 | — | LLM 迭代深搜 thinking_stages=3 + memory_recreate_enhancement 记忆重组 | node_postprocessors 链式后处理，支持 LLM/ColBERT/Cohere/BGE 重排序 | 3 倍 over-fetch → 加权合并 → 可选 LLM Reranker → citation 格式化 | Brave 返回链接列表，其余三引擎返回 AI 合成摘要+citations | 双模式：LLM summarization（structured output）或 split-and-rerank（embedding 向量检索） | — | 三阶段：向量 top-32 → 标签 include/exclude → LLM JSON 精选 | 分数传播 α=0.5 混合父子分数 + hotness 热度衰减融合 | — | QueryParam.mode 控制 naive/local/global/hybrid/mix 五种结果合并策略 | 三层 Reranker 降级链：Jina API → Ollama LLM → 顺序评分 | BM25 得分归一化到 [0,1]，取 top-n 返回 | 渐进式：search→全页图片→bbox→裁剪区域，模拟人类粗到细阅读 | 检索即导入：工具获取文档后立即写入向量库 | Chroma 返回 ID → SQLite 水合完整数据 → ResultFormatter Markdown 表格输出 | 三层结果分别 materialize 为 dict，含 score 字段，统一 response 结构返回 | HTML 标签清洗 + SourceCurator 质量排序 + SourceCredibilityFilter LLM 四维评估 | QueryExecutor 模板方法：validate→build→execute→merge_rerank 四步流水线 |
| 容错策略 | asyncio.Semaphore(2) 并发控制 | 双引擎互为降级 | 渐进式截断（70%→70%→25K）+ JSON 容错 3 次重试 | 5 级 try-except 日期解析链，API 错误返回空列表 | 三态诊断(ok/warn/off) + 每个 Channel 内置降级建议 + Jina Reader 全局兜底 | — | NO_RELEVANT_CHUNKS 信号触发查询重写，迭代超限进入 fallback_response 兜底 | 连续失败 5 次自动暂停 Source，单源失败不影响其他源采集 | ImportError 降级 + AttributeError fallback，但无供应商间自动降级 | API Key 缺失自动降级；MCP 3 次失败放弃；连接 60s 超时 | 7 种 Tavily 异常统一捕获，快速失败返回错误字典 | 三层异常捕获 + LLM 重试线性退避 + 并发降级顺序 | FAISS→cosine 降级、ImportError 捕获、KB metadata 回退到 env var | 嵌入维度两遍扫描过滤 + token 超限去掉 RAG 上下文降级 | Firecrawl try-except 返回 Error 字符串，DuckDuckGo 延迟导入降级为空列表 | LLM 仓库选择三级降级（LLM→embedding+BM25→scope_repos），Round N 失败返回 fallback | asyncio.gather return_exceptions + tenacity 指数退避 + 429 限流重试 | — | 每引擎独立 try-catch 返回空列表；deep_search stage 异常 continue；LLM 解析 max_retry_times=2 | SearchEngine ignore_errors 返回空结果；延迟加载避免缺依赖启动失败 | Brave→DDG fallback + CAPTCHA 1h 冷却 + 嵌入断路器 3 次/60s | 嵌入五后端链式降级 → FTS-only 兜底，Readability→Firecrawl→htmlToMarkdown 三级净化 | 摘要超时返回原文，各搜索源独立限流退避，token 超限渐进截断 | — | LLM 解析失败取首条，过滤为空随机采样，API Key 三级 fallback | collection 不存在返回空结果，收敛检测 3 轮提前终止 | — | 4 策略 JSON 降级解析 + batch→individual 处理降级 + VLM→普通查询降级 | 后端初始化 10s 超时+重试；Reranker 失败返回原始结果 | AlphaVantageRateLimitError 触发供应商降级链 | try/except continue 跳过失败文件，无效 action 返回提示让模型重试 | 双层 try-except 懒初始化，嵌入不可用时退化为纯工具模式 | Chroma 不可用自动降级 SQLite，MCP 传输错误重试一次，退避重连 10s | LLM 解析失败默认 RETRIEVE（安全降级）；JSON 解析异常 catch 后返回空列表 | SourceCurator 熔断（3 次失败/30 分钟冷却）+ Serper/搜狗 3 次指数退避重试 | API Reranker 可降级到本地 CrossEncoder 或无模型 RRF |
| 成本控制 | ~36 次搜索 + 20 次 LLM 调用 | Serper 免费 2500 次 | 独立摘要 LLM 可选 7B 级别降低成本 | random.sample(urls, 1) 限制抓取数量，固定 limit=20 | tier 分层渐进解锁，tier=0 全免费，Exa MCP 免费无需 API Key | — | 本地 HuggingFace 嵌入零 API 成本，Ollama 本地 LLM，MAX_TOOL_CALLS=8 硬限制 | Source 级采集（N 用户共享 1 次请求），订阅组合 hash 缓存 Digest | 双计费模型（flat-rate/per-token）+ 经济追踪器实时扣费 + 成本注入结果 | embedding 缓存避免重复计算；min_score 阈值过滤低质量结果 | HITL 审批提示 API credits + 搜索调用次数硬预算 | LLM 预过滤减少分析文件数 + max_content_length 截断 | 三引擎按速度/精度分级选择，嵌入适配器支持本地 Ollama 零成本方案 | 大文件跳过（代码>81920 token，文档>8192 token）+ 低维嵌入(256d) | config.yaml 声明 max_results 限制单次返回数量，无 token 级成本追踪 | max_total_lines 行预算 + ROI 分析 + 五重停止条件 + 自适应参数 | AI 评分门控只对高分内容执行搜索增强，概念查询限 3 条 | — | fast/fine 双模式：fast 跳过 LLM 解析直接分词；CoT 仅复杂查询触发；BM25 LRU Cache 避免重建 | NoEmbedding 协议跳过 BM25 嵌入；MockEmbedding 占位避免无效计算 | TTL 内存缓存 + Reranker 限 20 候选 + passage 截断 500 字符 | 15 分钟 TTL 缓存 + FIFO 淘汰，FTS-only 模式零嵌入成本 | 独立摘要模型（gpt-4.1-mini）+ Anthropic cache_control + 搜索调用预算硬限制 | — | 本地 all-MiniLM-L6-v2 零 API 成本，Pexels 免费 200 请求/小时 | — | — | 多模态查询缓存复用 + VLM 按需调用（仅检索到图片时触发） | 增量嵌入避免重复计算；Langfuse 自动监控所有嵌入调用 | BM25 零 API 调用 + CSV 文件缓存避免重复下载 | — | Web 搜索用 LLM-as-Search 替代传统 API，嵌入用 SiliconFlow 低成本模型 | chroma-mcp 本地子进程零 API 费用，90 天时间窗口限制搜索范围 | sufficiency check 实现 early termination，粗粒度够用就不深入；route_intention 跳过闲聊查询 | 可信度评估 ≤5 条跳过、GlobalRateLimiter 按域限流、AI 话题增强环境变量开关 | 本地 SentenceTransformer/BM25 零 API 成本，LRU 缓存减少重复嵌入调用 |
| 搜索源热切换 | — | — | — | start_mcp_services.py 注释切换 Jina/AlphaVantage | mcporter config add/remove 动态注册 MCP 服务，Channel check() 实时检测可用性 | — | — | type + config JSON 模式，新增源类型只需添加 resolveSourceUrl 分支 | WEB_SEARCH_PROVIDER 环境变量，运行时可切换无需改代码 | MCPConfigWatcher 轮询 config.json mtime，后台 Task 热重载 | 不支持，硬编码 Tavily 单源 | — | — | — | 改 config.yaml 的 use 字段即可切换供应商，无需改代码 | — | config.json 中 enabled 字段控制各源开关，无需改代码 | — | — | — | EnvVarProvider 运行时热更新 API Key，cache_key 含 key_state 自动失效 | config.tools.web.search.provider 配置切换，或删除 Key 自动降级 | Enum + Pydantic 配置 + 环境变量覆盖，运行时切换无需改代码 | — | — | — | — | — | — | config data_vendors 类别级 + tool_vendors 工具级双层配置 | — | WEB_SEARCH_PROVIDER 环境变量切换 Google/Perplexity | — | — | 环境变量控制源可用性（SERPER_API_KEY/TENCENTCLOUD_SECRET_ID），规则路由动态检测 | — |
| 页面内容净化 | — | — | — | Jina Reader API 自动 HTML→JSON，免解析 | Jina Reader(r.jina.ai) 自动将 HTML 转为 Markdown，零代码实现 | — | — | extractRssPreview 正则提取 + HTML title/og:title 降级提取 | Tavily Extract 返回 Markdown 格式正文，Jina 返回原始 Markdown | — | markdownify 库 + 自定义 User-Agent 头 | — | — | — | Jina 路径: Mozilla Readability + markdownify 双阶段净化 | — | Telegram 用 BeautifulSoup 解析 HTML，HN 评论用 regex 去标签 | — | — | — | 自实现 html_to_text：strip script/style + 块级标签换行 + 实体解码 | Readability + Cloudflare MD for Agents + htmlToMarkdown 三级管道 | — | — | — | — | — | — | — | — | — | — | — | — | re.sub 正则清洗 HTML 标签，搜狗结果标记微信公众号来源 | — |
| 金融数据源集成 | — | — | — | Alpha Vantage NEWS_SENTIMENT 带 ticker 情感评分 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | SEC EDGAR + CNINFO A股 + RootData Crypto 三大金融数据源 | — | — | — | — |
| 解析容错 | — | — | — | parse_date_to_standard 5 格式降级链，未知日期保留不丢弃 | — | — | — | RSS 用正则非 DOM 解析，JSON Feed try-catch 静默降级到 website | Jina Markdown 解析器容忍格式不规范，逐行状态机提取 | — | — | JSON 解析失败回退基础分析 + mock 模式测试 | FileTypeRouter 多编码尝试（UTF-8→GBK→Latin-1→replace），二进制检测跳过 | — | Jina AI 双层提取（Reader API + readabilipy），空内容返回 fallback 文本 | — | — | — | — | — | — | — | — | — | — | — | 三级降级（有TOC有页码→有TOC无页码→无TOC）+ 验证修复闭环最多3轮 | 4 策略渐进式 JSON 解析：直接→清理→引号修复→正则字段提取 | — | — | — | — | — | — | — | — |
| 时间隔离 | — | — | — | TODAY_DATE 运行时配置驱动 anti-look-ahead 过滤 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 检索方式 | — | — | — | — | 多后端并存：CLI 工具(bird/gh/yt-dlp) + MCP 协议(mcporter) + HTTP API(Jina/Reddit JSON) | 向量检索，基于嵌入模型+VDB，支持 score_threshold 过滤 | child 精确匹配 → parent_id 回溯完整上下文 | — | — | 语义搜索（向量）+ 精确匹配（FTS）双通道并行 | 纯在线搜索，无 RAG/向量检索 | 离线 LLM 索引构建 + 运行时多维评分检索 | 向量（FAISS/cosine）、知识图谱（LightRAG hybrid/local/global/naive）、多模态（RAGAnything） | FAISS FlatL2 向量近邻，无 BM25 混合 | 实时 API 调用，无本地索引或向量检索 | 两阶段：先 LLM/embedding 选仓库，再 filtered 索引精确检索 | — | — | Graph 结构化 key/tag 匹配 + Vector embedding 相似度 + BM25Okapi + jieba 全文检索 | FAISS 向量/Chroma 向量/Elasticsearch 向量+文本/BM25 关键词，可混合 | 向量 0.7 + 关键词 0.3 加权混合，无嵌入时降级为纯关键词 | SQLite-vec 向量 + FTS5 全文的加权混合检索 | — | — | 语义向量检索（本地资源）+ 关键词 API 搜索（在线素材） | 意图驱动多 TypedQuery 分类检索 + 目录递归 | LLM 推理式树搜索，无向量数据库，生产环境结合 MCTS | mix 模式同时搜索三级索引，local 模式通过 KG 邻居扩展检索范围 | keyword/vector 双模式路由，hybrid 预留未实现 | 纯词法 BM25，无向量嵌入 | — | LanceDB SearchType.hybrid（向量相似度 + BM25 全文） | 语义向量检索（Chroma embedding）+ 结构化过滤（SQLite WHERE）+ 混合交集 | RAG: numpy 矩阵乘法 + argpartition O(n) topk；LLM: prompt 驱动排序返回 JSON ID 列表 | 纯 Web 搜索（无向量索引），5 种 API 并行调用 | — |
| 扩展性 | — | — | — | — | 新增平台只需实现 Channel 子类(can_handle+check)，注册到 ALL_CHANNELS 列表 | 抽象基类+子类实现，新增 VDB/Reader 无需修改核心代码 | — | PLATFORM_RULES 数组模式，新平台只需添加 test+resolve 函数对 | 模块化 productivity/ 目录 + README 新工具添加指南 | MCP 协议可插拔任意搜索服务，config.json 声明式添加 | 条件注册模式，无 Key 时自动降级为无搜索 | MCP 协议标准化，新搜索源只需注册新 Server | Component Protocol + 装饰器注册，新增 pipeline/provider 零修改核心代码 | 环境变量切换 4 种嵌入后端，JSON 配置驱动 | 反射加载 resolve_variable + config.yaml 声明，新增搜索源零侵入 | 配置驱动（config.yaml），支持 OpenAI/Anthropic 双 LLM 后端，多仓库动态加载 | — | — | 记忆类型可扩展（Working/LongTerm/User/Tool/Skill/RawFile/Outer），每类型独立 Path | ConfigBasedFactory 开闭原则：新增后端只需 Config 类 + creator 函数 | — | 新引擎只需添加 run*Search 函数 + provider 枚举值 | MCP 协议支持任意外部工具集成，含 OAuth token exchange 认证 | — | — | 4 后端适配器注册表工厂 + FilterExpr AST 统一过滤 | 三种多文档策略（metadata SQL / semantics DocScore / description LLM） | Mixin 组合模式 + BaseModalProcessor 继承体系，新模态只需加子类 | VectorSearchBackend 接口 + 工厂模式，新增后端只需实现 8 方法 | VENDOR_METHODS 字典注册新供应商，无需改调用方 | — | 9-Provider 工厂模式，新增 Provider 只需继承 ModelProvider 基类 | 策略模式 + MCP 协议，新增搜索引擎只需实现 SearchStrategy 接口 | — | PROFESSIONAL_BLOGS 字典注册新源，AI_BOOST_SOURCES 列表控制增强范围 | — |
| 嵌入后端适配 | — | — | — | — | — | EmbeddingModelBase 抽象层，支持 OpenAI/Jina/Cohere/本地模型 | dense 维度通过 embed_query('test') 动态检测，切换模型无需改 collection 配置 | — | — | 环境变量驱动：EMBEDDING_BASE_URL + MODEL_NAME + DIMENSIONS | — | — | — | 工厂函数 get_embedder() 统一接口，支持 OpenAI/Google/Ollama/Bedrock | — | — | — | — | OllamaEmbedder 统一接口，支持批量 embed 多查询向量 | — | EmbeddingProvider trait + FallbackChain 断路器，支持 OpenAI/Local GGUF/Ollama | OpenAI/Gemini/Voyage/Mistral/Local 五后端 auto 模式链式探测 | — | — | HuggingFaceEmbeddings 本地优先，Hub 自动降级下载 | 三层基类 Dense/Sparse/Hybrid + CompositeHybridEmbedder 组合模式 | — | — | 4 Provider 工厂：OpenAI/Fireworks/Jina/Ollama，统一 LangChain Embeddings 接口 | — | VL_Embedding 通过 model 名称分支加载 ColQwen2/ColPali/OpenBMB/bge-m3 | ModelFactory 9 种 Provider 统一 create_embedder() 接口 | — | — | — | Protocol 接口 + 6 种内置后端（OpenAI/Qwen/Jina/ST/SPLADE/BM25） |
| 文档格式转换 | — | — | — | — | — | 6 种 Reader：Text/PDF/Word/Excel/PPT/Image，统一输出 Document | pymupdf4llm 将 PDF 转 Markdown，忽略图片，保留标题结构 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | Avro 二进制序列化向量点，支持跨用户跨实例文档复制 | — | — | SEC filing.document.markdown() + PDF URL 直接导入 | — | — | — | — |
| 组件正交 | — | — | — | — | — | Reader/Store/Embedding 三者独立，任意组合不互相影响 | VectorDbManager / ParentStoreManager / DocumentChuncker / ToolFactory 四组件独立可替换 | — | — | — | — | — | — | TextSplitter 和 Embedder 通过 adal.Sequential 串联，可独立替换 | — | — | — | — | Retriever/Reranker/Reasoner/GoalParser 四组件独立可替换，通过构造函数注入 | — | — | — | — | — | — | Embedder/Storage/Retriever/IntentAnalyzer 四组件独立替换 | — | — | 向量/全文/嵌入/重排序四层独立，通过 NestJS DI 注入组合 | 记忆检索与数据路由完全独立，各 Agent 按需绑定工具子集 | 嵌入/索引/API/Agent 四层分离，嵌入层可独立替换不影响索引层 | — | — | — | — | Schema/Index/Embedding/Reranker 四层独立，任意组合不互相影响 |
| 多模态支持 | — | — | — | — | — | Document.content 支持 TextBlock/ImageBlock/VideoBlock | — | — | — | — | — | ai_search 跳过 image 类型，仅处理文本和结构化数据 | RAGAnything 支持 PDF 图片/表格/公式提取，MinerU 解析 + 图片迁移到 canonical 路径 | 仅文本嵌入，无图片/音频处理 | DuckDuckGo image_search 支持图片搜索，含尺寸/类型/布局过滤 | — | — | — | — | — | — | — | — | — | 文本嵌入检索 BGM/模板 + REST API 搜索图片视频，双通道互补 | Volcengine multimodal embedding API 支持，检索侧预留 todo | Vision RAG：VLM 直接对 PDF 页面图片推理，无需 OCR | 4 类专用处理器（Image/Table/Equation/Generic）+ VLM 增强查询 | — | — | 纯视觉检索：PDF页面图片直接嵌入，不做OCR，支持图片/视频/文本统一嵌入 | — | — | — | — | — |
| 缓存机制 | — | — | — | — | — | 无内置缓存，依赖 VDB 自身的索引持久化 | — | subscription_hash = SHA256(sorted(source_ids)) 相同订阅组合共享 Digest | — | embedding enable_cache 配置项，ReMe 内部实现缓存 | Tavily 客户端模块级单例缓存，无结果缓存 | 可选 FIFO 内容缓存 + 文件 mtime+size 缓存键 | RAG 实例级缓存（ClassVar dict），无查询结果缓存 | ~/.adalflow/databases/{repo}.pkl 索引缓存，命中则跳过重建 | — | index_scan_cache TTL=30s 缓存仓库扫描结果，BM25/FAISS pickle 持久化 | — | — | BM25 模型 LRU Cache maxsize=100 按 corpus_name 缓存 | — | Mutex<HashMap> TTL 缓存，超 100 条惰性淘汰过期项 | Map 内存缓存，TTL 15min，FIFO 淘汰，最大 100 条 | — | — | — | meta_data_cache 缓存 Collection 元数据避免重复查询 | 树索引一次构建持久化为 JSON，检索时只传树结构不传原文 | 解析缓存（parse_cache）+ LLM 响应缓存 + 多模态查询缓存，三层独立 | 无显式缓存层，依赖 Qdrant/ES 自身缓存机制 | CSV 文件缓存，文件名含 symbol+日期范围作为键 | 检查点式：每 save_interval 个样本持久化索引+元数据+文件列表 | — | ChromaMcpManager 单例持久连接，collectionCreated 标志避免重复创建 | — | — | 嵌入函数 LRU cache(maxsize=10) + SPLADE 类级别模型缓存共享实例 |
| 对象检索 | — | — | — | — | — | Document 标准化数据结构，包含 metadata/embedding/score | — | — | — | — | — | — | — | — | — | — | — | — | — | ObjectNode 将 Pydantic 对象序列化入 RAG，检索后动态反序列化还原 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 索引结构 | — | — | — | — | — | 依赖底层 VDB（Qdrant HNSW/Milvus IVF），无自定义索引逻辑 | Parent-Child 分层索引：大 parent 存 JSON，小 child 存 Qdrant 双向量 | — | — | — | — | JSON 文件存储 FileSummary + FileRelationship 双层结构 | FAISS IndexFlatIP + LightRAG 知识图谱 + LlamaIndex VectorStoreIndex 三种并存 | FAISS FlatL2 + LocalDB pickle 持久化 | — | Full/Filtered 双索引分离，per-repo pickle 持久化，仓库概览独立存储 | — | — | Neo4j 图数据库存储记忆节点，embedding 向量内嵌节点属性 | VectorStoreIndex 统一抽象，FAISS/Chroma/ES 三种向量存储后端 | — | SQLite-vec 单表向量索引 + FTS5 全文索引，同库共存 | — | — | FAISS flat 内存索引，384 维 all-MiniLM-L6-v2 嵌入 | 单 Collection 双向量字段 dense+sparse + 12 标量索引 | 层次化树索引（标题/页码/摘要），PDF 自动 TOC 检测 + MD header 解析 | 知识图谱（实体+关系）+ 三个独立向量数据库 + text_chunks KV 存储 | Qdrant HNSW+Cosine+磁盘存储；LanceDB 本地文件表 | BM25Okapi 内存倒排索引，增量全量重建 | FAISS IndexFlatIP 精确内积，支持多索引 merge_from 合并 | LanceDB 单表 research_agent_knowledge_base，hybrid 模式 | SQLite FTS5（已弃用保留兼容）+ ChromaDB 向量集合，粒度化拆分 narrative/fact | 内存 dict 存储，无外部向量数据库；corpus 按需构建 numpy 矩阵 | — | HNSW（在线低延迟）/ IVF（大规模离线）/ Flat（精确暴力搜索）三种可选 |
| 排序策略 | — | — | — | — | — | — | Qdrant HYBRID 模式内置 dense+sparse 融合排序，COSINE 距离 | — | — | — | — | relevance_score 多维加权 + confidence_score 降序 | DenseRetriever cosine similarity top-k，LightRAG 内置排序，Tavily 自带 relevance score | FAISS L2 距离排序，无重排序(reranker) | — | 三路加权融合(semantic 0.5 + keyword 0.5 + pseudocode 0.4) + 类型权重 Rerank | — | — | 策略模式 Reranker（BGE 远程/Cosine 本地/Noop）+ 元数据 Boost 加权 | 5 种 Ranker 可组合：LLM/ColBERT/Cohere/BGE/ObjectSort | LLM-as-Reranker：70% LLM 评分 + 30% 原始分数，失败回退原始排序 | 加权融合 → 时间衰减 → MMR 多样性重排序三阶管道 | 各搜索源原生排序 + split_and_rerank 模式的 embedding 相似度排序 | — | 视频按 1080p 距离 + 质量偏好 + 文件大小三元组排序 | 语义分数 × 0.8 + hotness(sigmoid×exp_decay) × 0.2 混合排序 | LLM 推理输出 thinking + node_list，非相似度排序 | — | Jina API 相关性评分 / Ollama LLM 0-1 评分 / 顺序递减评分 | BM25 TF-IDF 变体得分降序 | 内积相似度 top_k，多向量用 score_multi_vector 跨 token 聚合 | — | Hybrid 四步：SQLite 过滤候选集 → Chroma 语义排名 → 交集保留排名 → 水合 | RAG 模式支持 similarity/salience 双排序；salience = cosine × log(reinforcement+1) × exp(-decay) | 两级排序：SourceCurator 静态权重（0.50-0.95）→ CredibilityFilter LLM 动态评分 | RRF/Weighted/Qwen-API/LocalCrossEncoder 四种 Reranker 策略模式可插拔 |
| 搜索工具条件注册 | — | — | — | — | — | — | — | — | — | bool(api_key) 一行判断，Key 缺失时工具不注册而非报错 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | API Key 缺失时 SearchMediaNode 抛出 RuntimeError 并提示用户配置 | — | — | — | — | — | — | — | — | — | — | — |
| 记忆文件自动索引 | — | — | — | — | — | — | — | — | — | file_watcher 监听 MEMORY.md 和 memory/ 目录变更自动重建索引 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 专家知识集成 | — | — | — | — | — | — | — | — | — | — | — | target_structure 注入目标项目结构引导 LLM 分析方向 | ArXiv PaperSearchTool 学术搜索 + Serper scholar 模式 + 引用格式化 | — | — | — | — | — | — | — | — | — | — | — | — | — | 树搜索 prompt 中直接注入领域偏好，无需微调 embedding | ContextExtractor 注入周围页面文本作为 LLM 分析上下文 | — | — | — | — | — | — | — | — |
| 采集频率分级 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 统一 time_window_hours 窗口，各源独立 min_score/fetch_limit 阈值 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 搜索结果字段归一化 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 五源统一映射到 ContentItem 模型，metadata 存源特有字段 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 引用验证 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | available_urls 白名单校验，只保留搜索结果中实际存在的 URL | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| SSRF防护 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | DNS 解析后逐 IP 校验私有地址，CIDR 白名单例外，每跳重新检查 | fetchWithSsrFGuard 逐跳 DNS 解析 + 跨域 Header 剥离 | — | — | — | — | — | — | — | — | — | — | — | — | — | — |
| 搜索后反思 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | think_tool 强制 Agent 每次搜索后评估信息充分性再决定是否继续 | — | — | — | — | — | — | — | — | — | — | 每层检索后 LLM 判断 RETRIEVE/NO_RETRIEVE + 输出 rewritten_query，驱动下一层 | — | — |
| 视觉粒度控制 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 像素预算 [min_pixels, max_pixels] + bbox pad_size=56 外扩裁剪 | — | — | — | — | — |
| 层级递进深度控制 | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | — | 三层各自 enabled/top_k 独立配置，sufficiency_check 全局开关控制是否启用层间判断 | — | — |
最佳实践
1.树状递归搜索是深度研究的标配：breadth 逐层减半控制指数爆炸，visited_urls 去重避免重复
2.双引擎互为降级：不依赖单一搜索源，语言感知路由提升中英文搜索质量
3.目标导向提取优于全文返回：用 LLM 只提取与当前 goal 相关的信息，节省 token
4.渐进式降级截断：宁可截断不可失败，70% → 70% → 25K 字符三级降级
5.独立摘要 LLM 降低成本：摘要用便宜模型，不占主推理 LLM 上下文
6.搜索策略要可配置：breadth/depth 参数化，不同任务需要不同的搜索深度
7.运行时日期配置驱动搜索过滤：通过共享配置文件传递模拟日期，搜索工具每次调用时读取并过滤
8.日期解析宁松勿严：无法解析的日期保留结果而非丢弃，避免因格式问题丢失有价值信息
9.零 wrapper 优于全量封装：只做安装和诊断，让 Agent 直接调用上游工具保留完整能力
10.tier 分层渐进解锁：tier=0 零配置即用降低门槛，tier=2 按需配置避免一次性配置负担
11.mcporter 统一 MCP 网关：一个 CLI 管理多个 MCP 服务端，避免每个服务单独管理连接
12.抽象基类定义最小接口：VDBStoreBase 只定义 add/search/delete 三个核心方法，get_client 可选实现
13.数据结构标准化：Document 作为统一数据载体，避免各组件间的格式转换开销
14.批量操作优先：add_documents 一次性嵌入所有文档，减少 API 调用次数
15.工具化封装降低集成成本：retrieve_knowledge 返回 ToolResponse，Agent 可零配置调用
16.延迟初始化：collection 在首次 add 时才创建，避免不必要的初始化开销
17.Parent-Child 分层索引解决精度-上下文矛盾：小 child 精确匹配，大 parent 提供完整语境，两者通过 parent_id 关联
18.嵌入维度动态检测优于硬编码：通过 embed_query('test') 获取实际维度，切换模型时零修改
19.检索信号字符串优于异常抛出：NO_RELEVANT_CHUNKS 等信号让 Agent 可编程地响应检索失败
20.URL 优先正则再 HTTP 嗅探：已知平台零网络开销，未知 URL 才发请求
21.数据库 UNIQUE 约束替代应用层去重：天然幂等，重启不丢状态，零额外代码
22.Source 级采集与用户无关：同一源 100 人订阅只采集 1 次，线性扩展
23.DNS 解析后检查所有 IP 防 SSRF：比仅检查 hostname 更安全，防 DNS rebinding
24.成本注入搜索结果：将 api_cost 字段写入返回值让 Agent 实时感知搜索开销
25.装饰层解耦成本追踪：搜索逻辑与经济追踪分层实现，搜索模块可独立测试
26.API Key 存在性作为搜索能力开关：bool(api_key) 一行实现条件降级，零配置用户也能用全文检索保底
27.MCP 客户端热重载采用 connect-outside-lock + swap-inside-lock 模式：最小化锁持有时间，新连接失败不影响旧客户端
28.条件工具注册优于运行时报错：无 API Key 时不注册工具，比注册后运行时报错的用户体验更好
29.搜索+全文抓取二阶段：先用搜索引擎发现 URL，再抓取完整网页内容，比仅依赖搜索摘要信息更丰富
30.MCP Server 封装搜索 API 实现协议标准化：新搜索源只需注册 Server 无需改 Agent 代码
31.LLM 预过滤减少无关文件分析：先用目录树让 LLM 筛选再逐文件深度分析，节省 70%+ API 调用
32.工厂懒加载避免重依赖污染：闭包延迟 import，用户只装需要的 RAG 后端依赖
33.Fluent API 组装管道比继承更灵活：跳过不需要的阶段（如 LightRAG 不需要 chunker）
34.SERP 结果用 provider 专属 Jinja2 模板整合，AI provider 直接用自带 answer
35.FAISS 不可用时静默降级为 numpy cosine，保持接口一致性
36.两遍扫描法校验嵌入维度：先统计维度分布找众数，再过滤异常维度文档，比逐条校验更鲁棒
37.代码文件与文档文件差异化 token 上限：代码允许 10 倍于文档的 token 上限，因为代码文件通常更长且更有价值
38.嵌入后端工厂+环境变量切换：一个工厂函数统一 4 种后端，部署时只改环境变量不改代码
39.统一工具名 + 反射加载实现搜索源透明切换：Agent prompt 无需感知底层 API 变化
40.Pydantic extra=allow 模式存储工具参数：同一工具不同部署可有不同配置，无需改代码
41.可选依赖延迟导入：函数内 import 避免未安装的库导致整个模块加载失败
42.Pydantic extra=allow 让工具配置完全开放：无需为每个供应商定义专用 Config 类
43.反射式加载优于工厂注册表：新供应商只需加模块+配置，零侵入主代码
44.getattr+or 双重防御处理供应商返回值不一致：防属性缺失 + 防 None 值
45.Full/Filtered 双索引分离：全量索引用于仓库选择，按需重建子索引用于精确检索，避免跨仓库噪声
46.五重停止条件防止迭代失控：置信度达标、硬迭代上限、行预算耗尽、停滞检测、递减收益缺一不可
47.类型权重 Rerank 优先返回函数级结果：function(1.2) > class(1.1) > file(0.9)，代码问答场景函数粒度最有价值
48.AI 评分门控搜索增强：先用廉价 LLM 评分过滤，只对高分内容执行昂贵的搜索增强
49.引用白名单验证：构建 available_urls 索引，LLM 输出的 sources 必须在搜索结果中存在
50.五源共享 httpx.AsyncClient：复用连接池降低 TCP 握手开销，统一 timeout 配置
51.四引擎结果用 ID 字典去重比 set 更高效：同一记忆被多引擎召回时自动保留一份
52.LLM 迭代深搜应设置 thinking_stages 上限防止无限循环，每阶段异常 continue 而非中断
53.fast/fine 双模式平衡延迟与精度：实时对话用 fast（分词直检），深度问答用 fine（LLM 解析意图）
54.Reranker 策略模式比硬编码更灵活：通过工厂按配置选择 BGE 远程/Cosine 本地/Noop 透传
55.多路检索必须 deepcopy query：防止某个检索器修改查询对象影响后续检索器
56.NoEmbedding 协议标记免嵌入检索器：BM25 等不需要向量的检索器用 MockEmbedding 占位，避免无效嵌入计算
57.工厂模式优于 if-else 分发：新增检索/排序后端只需注册 Config+Creator，不修改已有代码
58.无 API Key 时跳过必定失败的 API 调用直接走 fallback，避免浪费网络往返
59.Reranker 失败时优雅回退原始排序而非报错，保证检索可用性不受 LLM 影响
60.嵌入 fallback 链用断路器（3 次失败/60s 冷却）而非简单重试，防止雪崩
61.API Key 前缀推断比显式配置更友好：pplx- 前缀自动直连，sk-or- 前缀走 OpenRouter
62.MMR 用 Jaccard 而非余弦相似度：文本片段级去重不需要额外嵌入调用，计算更轻量
63.嵌入不可用时降级到 FTS+查询扩展而非报错：搜索能力不应因嵌入服务故障完全丧失
64.SSRF 逐跳检查而非仅首次检查：防止 DNS rebinding 攻击绕过首次 IP 校验
65.去重前置于摘要：先 URL 去重再做 LLM 摘要，避免对重复内容浪费 token
66.摘要失败降级为原文：LLM 摘要超时或报错时返回原始内容而非抛异常
67.搜索参数白名单过滤：每个搜索源定义接受的参数列表，防止非法参数传入
68.Anthropic cache_control 降低摘要成本：对重复网页内容启用 ephemeral 缓存减少 API 费用
69.向量宽召回+标签硬过滤+LLM精选三阶段分离关注点：语义相关性、业务约束、最终质量各司其职
70.元数据即嵌入文本：资源库自带 description 字段直接嵌入，避免维护独立文本的同步成本
71.heapq 优先队列按分数排序探索目录：高分目录优先下钻，低分目录自然被截断
72.收敛检测提前终止：连续 N 轮 top-k 不变即停，避免深层无意义遍历
73.热度衰减用纯函数实现：sigmoid(log1p(count)) × exp(-λt) 可独立测试和调参
74.多模态内容统一为文本描述+KG实体后复用全部文本检索能力，避免独立多模态索引的复杂度
75.VLM 查询时按需加载图片（only_need_prompt 先获取上下文再编码），索引时不存 base64 避免存储膨胀
76.图片路径安全校验（safe_dirs 白名单 + symlink 拒绝）防止 prompt 注入读取任意文件
77.向量后端接口只需 8 个方法即可覆盖 CRUD+搜索+滚动全场景，新增后端实现成本低
78.增量嵌入用 content→vector Map 比对，仅对变更 chunk 调用嵌入 API，大幅降低编辑场景成本
79.过滤器归一化层让上层代码完全不感知底层是 Qdrant 还是 LanceDB
80.Reranker 失败时静默降级到顺序评分而非抛错，保证搜索可用性
81.BM25 适合金融术语词汇匹配场景，零 API 成本且离线可用
82.供应商路由仅对限流异常降级，其他异常直接抛出避免掩盖真实错误
83.技术指标批量计算一次下载全量数据，比逐日请求性能提升 10x+
84.纯视觉检索优于 OCR+文本检索：对图表密集型文档直接嵌入页面图片保留完整视觉信息
85.渐进式粒度检索：先全页后裁剪模拟人类阅读行为，bbox 外扩 padding 避免裁剪过紧
86.增量索引 + 检查点保存：uid 去重避免重复嵌入，周期性持久化防止长时间构建中断丢失
87.向量库懒初始化返回 Optional：嵌入不可用时 Agent 退化为纯工具模式，不阻塞启动
88.LLM 自主路由优于硬编码：将多个检索工具注册给 Agent 由 LLM 选择，比关键词匹配路由更灵活
89.三层配置驱动嵌入选择：YAML 默认值 + .env 开发覆盖 + 环境变量生产覆盖，一套代码适配多环境
90.交集排序优于串行过滤：先 SQLite 精确过滤再 Chroma 语义排序取交集，兼顾精度与相关性
91.向量引擎作为增强而非必需：搜索栈在无向量引擎时仍完整工作，降低部署门槛
92.粒度化文档提升检索精度：将 narrative/facts 拆分为独立向量文档，按 sqlite_id 去重合并
93.充分性判断默认 RETRIEVE：LLM 解析失败时安全降级为继续检索，宁可多检索不可漏信息
94.Query Rewriting 与 sufficiency check 合一：一次 LLM 调用同时完成充分性判断和查询重写，减少调用次数
95.argpartition O(n) topk：大规模向量检索用 numpy argpartition 替代全排序，从 O(n log n) 降到 O(n)
96.两级过滤管线降低成本：先用零成本规则排序粗筛，再用 LLM 精评，结果 ≤5 条时跳过 LLM 评估
97.LLM 路由 + 规则兜底双保险：LLM 理解语义选源，失败时关键词规则匹配保底，general 源始终包含
98.源健康熔断避免无效请求：连续 N 次失败自动禁用 + 冷却期自动恢复，比永久禁用或无限重试都更合理
99.按域独立限流适配不同 API：arXiv 免费但限流严（3s），商业 API 间隔短（0.5s），统一间隔无法兼顾
100.Protocol 优于 ABC：嵌入接口用 @runtime_checkable Protocol 定义，第三方实现无需继承即可接入
101.模板方法锁定流程：QueryExecutor.execute() 用 @final 固定 validate→build→execute→merge 四步，子类只覆写策略点
102.RRF 是最稳健的多路融合起点：不依赖分数尺度，rank_constant=60 是经验最优值
103.类级别模型缓存：SPLADE 等大模型用 ClassVar dict 缓存，多实例共享避免重复加载