Web Search Pro

核心用法

Web Search Pro 是一款面向 AI Agent 的联邦搜索与检索工具，核心设计遵循「Agent-first」理念。用户可通过 Node 运行时直接调用，无需任何 API Key 即可完成基础搜索（基于 DuckDuckGo 无 Key 搜索）。

主要命令：

• search.mjs：实时网页/新闻搜索，支持 --preset docs/news 定向检索
• extract.mjs：单页内容提取
• crawl.mjs：站点深度爬取
• map.mjs：站点地图生成
• research.mjs：多轴研究计划与执行
• doctor.mjs / capabilities.mjs：环境诊断与能力自检

路由与联邦机制：

• selectedProvider：主选路由
• routingSummary：紧凑路由解释含置信度
• federated.*：多服务商结果聚合指标（新增覆盖率、结果恢复量、交叉验证、去重节省）

服务商矩阵（可选）：

| 服务商 | 特性 |

|--------|------|

| Tavily | 深度搜索、新闻、内容提取 |

| Exa | 语义搜索与提取 |

| Querit | 多语言原生地理/语言过滤 |

| Serper | 类 Google 搜索与新闻 |

| Brave | 结构化搜索，OpenClaw 兼容 |

| SerpAPI | 多引擎含百度 |

| You.com | LLM-ready 搜索，时效性/本地化 |

| Perplexity/Sonar | 原生答案优先搜索 |

| SearXNG | 自托管隐私元搜索 |

显著优点

1. 零门槛基线：Node 唯一硬依赖，无 Key 即可运行，适合快速验证与隐私敏感场景
2. 可解释路由：--explain-routing / --plan 暴露完整决策链路，便于 Agent 审计
3. 联邦增益量化：federated.value.* 指标让多服务商策略的价值可测量
4. 多模态输出：JSON 结构化响应兼容自动化流水线，缓存命中与 TTL 透明
5. 弹性部署：支持原生 API、OpenRouter/Kilo 网关、自定义 OpenAI-compatible 代理

潜在局限

• 基线质量波动：DuckDuckGo 无 Key 搜索受反爬策略影响，复杂查询可能降级
• 服务商成本分散：高级功能需管理多组 API Key，配置复杂度随覆盖需求上升
• Node 运行时绑定：非 Node 环境需额外适配层
• 实时性边界：缓存机制（.cache/web-search-pro）可能滞后于极速变化的信息源

适合人群

• AI Agent 开发者：需要可解释、可审计的搜索中间件
• 自动化工作流构建者：追求结构化 JSON 输出与缓存优化
• 隐私优先用户：SearXNG 自托管 + 无 Key 基线满足合规需求
• 多语言/多地域研究者：Querit 原生过滤 + 百度覆盖

常规风险

| 风险类型 | 说明 | 缓解 |

|----------|------|------|

| API Key 泄露 | 多服务商配置增加暴露面 | 使用 env 注入，避免硬编码 |

| 数据隐私 | 第三方服务商可能记录查询 | 敏感场景优先 SearXNG 自托管 |

| 服务可用性 | 单一服务商故障影响深度功能 | 联邦设计天然冗余，基线保底 |

| 结果可信度 | 聚合来源质量参差 | 利用 `resultsCorroboratedByFanout` 交叉验证 |

核心功能与架构

Web Search Pro 2.1 是一款面向Agent场景的专业级网络检索工具，采用纯Node.js原生模块实现，零第三方依赖。其核心设计围绕"联邦搜索"（Federated Search）架构，支持10+搜索服务商的聚合调用，包括Tavily、Exa、Brave、Serper、Perplexity Sonar等主流API，以及DuckDuckGo无密钥基线和SearXNG自托管方案。

显著优点

1. 零配置开箱体验
无需任何API密钥即可启动基础搜索功能，通过DuckDuckGo HTML接口和原生fetch实现真正的"no-key baseline"。这对快速验证、隐私敏感场景或预算受限用户极具价值。

2. 智能路由与可解释性
内置routingSummary和federated.value指标，暴露additionalProvidersUsed、resultsRecoveredByFanout、resultsCorroboratedByFanout等增益数据，让Agent决策透明可审计。

3. 全链路检索能力
覆盖搜索（search）、提取（extract）、爬取（crawl）、站点地图（map）、深度研究（research）完整工作流，非简单的搜索包装器。

4. 安全架构优势

• 零第三方npm依赖，完全Node.js原生实现
• SSRF防护完善（url-safety.mjs模块验证目标URL）
• 无eval/exec危险函数，子进程调用仅限于curl检测
• 缓存TTL机制避免数据长期滞留

潜在局限

1. 来源可信度限制
T3级个人开发者维护（Zjianru），虽代码公开透明、版本迭代活跃（2.1.4），但缺乏企业级SLA背书和长期维护保障。

2. 网络依赖风险
集成10+外部API，任一服务商可用性变化或策略调整均可能影响功能。虽有多源冗余，但路由决策依赖外部服务健康状态。

3. 搜索数据暴露
查询内容必然发送至第三方API（HTTPS加密），敏感业务关键词可能泄露至搜索服务商日志。

4. 缓存安全边界
搜索结果缓存于本地文件系统，若目录权限配置不当（未设置700），存在多用户环境搜索历史泄露风险。

适合人群

• AI Agent开发者：需要可解释路由决策和结构化证据包（evidence packs）的场景
• 隐私敏感用户：优先使用DuckDuckGo基线或自托管SearXNG，避免商业搜索服务商追踪
• 多源验证需求：研究、新闻核查、竞品分析等需要交叉验证结果的场景
• Node.js技术栈团队：零依赖特性降低供应链攻击面

常规风险与缓解

| 风险场景 | 缓解措施 |

|---------|---------|

| API密钥泄露 | 环境变量配置，无硬编码，建议最小权限原则仅启用必需提供商 |

| SSRF攻击 | `assertSafeRemoteUrl`验证，阻断私有IP、元数据服务访问 |

| 缓存数据残留 | 定期执行`cache.mjs --clear`，配置700权限目录 |

| 敏感查询外泄 | 避免在搜索词中包含PII/内部项目名，优先SearXNG自托管 |

| 供应链攻击 | 零第三方依赖，持续监控后续版本是否引入npm包 |

快速启动建议

推荐配置路径：DuckDuckGo基线验证 → 添加Tavily API密钥提升深度搜索质量 → 配置SearXNG自托管实现隐私与功能平衡。通过doctor.mjs和capabilities.mjs完成环境诊断后再投入生产使用。