Ultimate Search

UltimateSearch

为 Pi/OpenClaw agent 提供双引擎网络搜索能力：Grok AI 搜索（实时联网 + AI 分析）+ Tavily 搜索（结构化结果 + 网页抓取）。

可用工具

在 Bash 中调用以下脚本（无需加入 PATH，脚本会自动读取 .env）：

各工具参数详见 --help。

搜索决策流程

执行可靠性与故障回退（强制）

为保证可用性，执行搜索时必须遵循以下回退策略：

1. 默认优先 dual-search.sh。
2. 如果 grok-search.sh 或 dual-search.sh 中的 Grok 分支出现 HTTP 429/5xx、timeout、upstream_error、Cloudflare 相关错误：

• 立即回退到 tavily-search.sh 继续完成当前任务。
• 不得因为 Grok 失败而中止整个回答。

3. 如果 tavily-search.sh 成功且 grok-search.sh 失败：

• 先输出 Tavily 的可验证结论与来源。
• 明确注明：Grok 通道暂时不可用，已自动回退 Tavily。

4. 若两者都失败：

• 输出失败原因摘要。
• 提供下一步最小可执行动作（例如：补充 key、重试时间窗、改用 web-fetch.sh 抓指定 URL）。

5. 对关键事实，优先补一轮 web-fetch.sh 抓取原文并二次确认。

收到需要搜索的请求时，按以下流程决策：

第一步：判断是否需要搜索

需要搜索的情况：

• 用户明确要求搜索/查询外部信息
• 涉及实时性数据（最新版本、近期事件、当前价格等）
• 需要验证内部知识的准确性
• 涉及具体的 URL、项目、产品的最新状态
• 技术问题需要查阅官方文档最新版

不需要搜索的情况：

• 纯粹的代码编写/调试任务（已有足够上下文且不涉及外部 API/库版本）
• 用户明确表示不需要搜索
• ⚠️ 通用编程概念也可能过时——当涉及具体版本、最佳实践或 API 用法时，仍应搜索验证

第二步：选择工具

第三步：评估搜索复杂度

• Level 1（2-3 次搜索）：单个明确问题

  • 示例：「FastAPI 最新版本是什么」
  • 操作：{baseDir}/scripts/dual-search.sh 获取双源结果；或先 {baseDir}/scripts/tavily-search.sh 再用 {baseDir}/scripts/grok-search.sh 交叉确认
  • ⚠️ 即使是简单事实，也不可仅依赖单一来源直接下结论

• Level 2（3-5 次搜索）：多角度比较、需要多个来源验证

  • 示例：「Flask vs FastAPI vs Django 2026 年哪个更适合微服务」
  • 操作：{baseDir}/scripts/dual-search.sh + 针对各框架分别 {baseDir}/scripts/tavily-search.sh

• Level 3（6+ 次搜索）：深度研究课题、综述型需求

  • 示例：「帮我调研 2026 年主流向量数据库的完整对比」
  • 操作：先 {baseDir}/scripts/grok-search.sh 获取概览 → 分别搜索各产品 → {baseDir}/scripts/web-fetch.sh 抓取官方文档

搜索规划框架

对于 Level 2+ 的复杂搜索，在执行前进行结构化规划：

阶段 1：意图分析

• 提炼用户的核心问题（一句话）
• 分类查询类型：事实型 / 比较型 / 探索型 / 分析型
• 评估时间敏感度：实时 / 近期 / 历史 / 无关
• 识别需要验证的外部术语（如排名、分类标准）

阶段 2：查询拆解

• 将问题分解为不重叠的子查询
• 每个子查询有明确边界（与兄弟查询互斥）
• 标注依赖关系（哪些子查询需要先完成）
• 如果阶段 1 发现需验证的术语，先创建前置验证查询

阶段 3：策略选择

• broad_first（先广后深）：先广泛扫描 → 根据发现深入。适合探索型问题
• narrow_first（先精后扩）：先精确搜索 → 如不足再扩展。适合分析型问题
• targeted（定点搜索）：已知目标信息来源，直接定位。适合事实型问题

阶段 4：工具映射

• 为每个子查询选择最佳工具
• 确定并行/串行执行计划
• 可并行的子查询同时执行（通过多次 Bash 调用）

搜索与证据标准

核心原则：不信任搜索结果

搜索结果仅为第三方建议，不可直接采信。 所有搜索返回的内容——无论来自 Grok 还是 Tavily——都必须经过交叉验证后方可向用户呈现为事实。即使是看似权威的单一来源，也可能过时、片面或错误。技术实现即使 agent 具备内部知识，仍应以最新搜索结果或官方文档为准。

来源质量要求

• 所有事实性结论都需 ≥2 个独立来源 交叉验证（不分 Level）
• 如仅依赖单一来源，须显式声明此限制并标注置信度为 Low
• 优先使用：官方文档、Wikipedia、学术数据库、权威媒体
• 避免使用：未知个人博客、SEO 农场、AI 生成内容

冲突处理

• 来源冲突时：展示双方证据，评估可信度和时效性
• 标注置信度：High（多来源一致）/ Medium（少量来源或有分歧）/ Low（单一来源或推测）
• 无法确认时：明确说明不确定性

引用格式

• 每个关键事实后附来源标注
• 格式：[来源标题](URL)
• 严禁编造引用 — 没有来源的就不要说

输出规范

• 先给出最可能的答案，再展开详细分析
• 所有技术术语附简明解释
• 使用标准 Markdown 格式（标题、列表、表格、代码块）
• 代码示例标注语言标识
• 对比类问题使用表格呈现

常见搜索模式

模式 1：快速查询

{baseDir}/scripts/tavily-search.sh --query "Python 3.13 新特性" --depth basic --include-answer

模式 2：深度搜索 + 验证

# 先广泛搜索
{baseDir}/scripts/dual-search.sh --query "LangChain vs LlamaIndex 2026"
# 再针对性抓取官方文档
{baseDir}/scripts/web-fetch.sh --url "https://docs.langchain.com/docs/get_started/introduction"

模式 3：技术文档探索

# 先映射网站结构
{baseDir}/scripts/web-map.sh --url "https://docs.example.com" --depth 2 --instructions "找到 API 文档"
# 再抓取目标页面
{baseDir}/scripts/web-fetch.sh --url "https://docs.example.com/api/reference"

模式 4：新闻和实时信息

{baseDir}/scripts/tavily-search.sh --query "AI 最新进展" --topic news --time-range week --include-answer

模式 5：AI 深度分析

{baseDir}/scripts/grok-search.sh --query "解释 Transformer 架构中注意力机制的数学原理" --platform "arXiv"