Web Search Pro

核心用法

Web Search Pro 2.1 是一款面向 Agent 的代码级 Node 运行时搜索工具，提供「零配置即用 + 可选高级服务商」的双层架构：

• 无 Key 基线层：内置 DuckDuckGo 搜索与原生 fetch 抓取，无需任何 API Key 即可执行网页搜索、站点爬取、站点地图生成和内容提取
• 联邦增强层：通过配置 Tavily、Exa、Querit、Serper、Brave、SerpAPI、You.com、SearXNG、Perplexity/Sonar 等 10+ 服务商，实现智能路由与多源交叉验证

核心脚本包括：search.mjs（多类型搜索）、extract.mjs（单页内容提取）、crawl.mjs（站点爬取）、map.mjs（站点地图）、research.mjs（深度研究）、doctor.mjs（环境诊断）等 11 个 CLI 工具。

显著优点

1. Agent-native 设计：输出结构专为 LLM Agent 优化，包含 routingSummary（路由解释）、federated.value（联邦增益指标：额外提供商数、结果恢复数、交叉验证数、去重节省）等元数据
2. 零门槛启动：首次运行无需注册任何服务，Node 环境 + 一行命令即可开始搜索
3. 智能联邦路由：自动在多服务商间进行 fanout 查询，通过 resultsCorroboratedByFanout 等指标量化信息可信度
4. 多场景覆盖：支持新闻实时搜索、技术文档定向检索、代码实现研究、企业竞品分析、多语言搜索（含百度）等垂直场景
5. 灵活的 Perplexity 接入：原生 API、OpenRouter、KiloCode、自定义网关四种接入方式适配不同网络环境

潜在缺点与局限性

• 基线层质量波动：DuckDuckGo 结果受反爬策略影响，复杂查询或高并发场景下稳定性不及付费 API
• 服务商依赖风险：联邦层功能需配置对应 API Key，部分服务商（如 Tavily、Exa）存在额度限制与计费风险
• Node 环境绑定：非纯指令型 Skill，必须依赖 Node 运行时，轻量化场景部署成本较高
• SearXNG 自托管门槛：隐私优先的 metasearch 方案需要用户自行部署维护实例
• 路由透明度有限：联邦路由逻辑封装于代码层，高级用户难以自定义权重策略

适合人群

• AI Agent 开发者：需要结构化、可解释搜索输出的 LLM 应用构建者
• 研究型用户：新闻追踪、技术调研、竞品分析等需要多源交叉验证的场景
• 隐私敏感用户：可通过 SearXNG 自托管实现去中心化搜索
• 渐进式采用者：希望先免费试用、再按需接入付费 API 的务实用户

常规风险

| 风险类别 | 说明 | 缓解建议 |

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

| API 密钥泄露 | 多服务商配置增加暴露面 | 使用环境变量注入，避免硬编码 |

| 服务可用性 | 第三方 API 存在单点故障 | 配置多服务商联邦，启用 fallback |

| 成本控制 | Tavily/Perplexity 等按量计费 | 监控 `federated.value` 指标，优化 provider 组合 |

| 内容合规 | 搜索结果可能含敏感信息 | 下游应用增加内容过滤层 |

| 反爬封禁 | 基线层高频请求可能触发限制 | 降低并发，优先使用付费 API 层 |

核心用法

web-search-pro 是一款面向 Agent 的联邦化网络搜索与检索工具，采用 Node.js 纯标准库实现（零第三方依赖）。核心工作流围绕 search.mjs、extract.mjs、crawl.mjs、research.mjs 等 CLI 脚本展开，支持两种启动模式：

• 无密钥基线：零配置即可使用 DuckDuckGo HTML 解析 + 内置 fetch 完成基础搜索、提取与站点爬取。
• 多引擎增强：通过环境变量注入 Tavily、Exa、Perplexity/Sonar、Serper、Brave、SerpAPI、You.com、Querit、SearXNG 等 10+ 家搜索提供商 API 密钥，实现智能路由与结果联邦聚合。

典型调用示例：

node scripts/search.mjs "OpenAI Responses API" --preset docs --plan --json
node scripts/research.mjs "LLM 推理优化技术" --json
node scripts/crawl.mjs https://example.com --depth 2

输出采用结构化 JSON，包含 routingSummary、federated.providersUsed、federated.value（增益指标）等字段，便于 Agent 消费。

显著优点

• 零依赖安全基线：不引入任何 npm 包，完全基于 Node.js 内置模块（fs/path/crypto/dns/net/child_process），彻底消除供应链攻击面。
• 智能联邦路由：自动选择最优搜索提供商，支持并行扇出（fanout），返回结果去重与交叉验证，提升召回率与准确性。
• 完善的 SSRF 防护：内置 assertSafeRemoteUrl 机制，阻断私有 IP、localhost、云 metadata 端点等危险目标。
• 隐私合规：API 密钥仅读取自环境变量，无遥测、无数据出境，缓存本地可控，符合 GDPR 数据最小化原则。
• 多路径 Perplexity 接入：原生支持 Perplexity API、OpenRouter、KiloCode 网关及自定义 OpenAI-compatible 端点，灵活适配企业代理场景。

潜在缺点与局限性

• 个人开发者维护（T3）：由 GitHub 用户 Zjianru 独立维护，虽代码开源透明，但长期维护稳定性、企业 SLA 保障弱于商业产品。
• DuckDuckGo 基线脆弱性：无密钥回退依赖 DDG HTML 解析，页面结构变更可能导致解析失败，且受限于 DDG 反爬策略。
• 多密钥管理复杂度：联邦模式需维护多家 API 密钥，轮换与权限管控成本随规模上升。
• 子进程调用 curl：部分场景下使用 child_process.execFile 调用 curl，虽参数已严格转义，但在极端受限容器环境可能受限。
• 缓存无自动过期策略：本地缓存默认写入 .cache/web-search-pro，需用户自行监控清理，长期运行可能累积磁盘占用。

适合人群

• AI Agent 开发者：需要可编程、结构化、带引用溯源的搜索能力，替代传统搜索引擎 API 的封装成本。
• 隐私敏感团队：希望数据不出境、零第三方依赖、可审计全部代码的安全优先场景。
• 多源聚合研究者：需要同时对比 Tavily/Perplexity/Exa 等多引擎结果，进行交叉验证与证据打包。
• 企业内网代理用户：支持 SearXNG 自托管与 OpenRouter/KiloCode 网关，适配复杂网络拓扑。

常规风险

• API 密钥泄露风险：密钥存储于环境变量，若在 CI/CD 日志、共享终端或协作环境中误输出，可能导致密钥滥用与账单异常。
• 搜索结果不可控性：第三方搜索引擎返回内容可能包含恶意链接、偏见信息或版权争议内容，需下游应用二次过滤。
• 网络可达性依赖：运行环境需能访问 Tavily/Perplexity 等海外 API 端点，企业防火墙或地域限制可能影响功能。
• 缓存污染风险：若攻击者控制搜索查询输入并诱导缓存写入恶意内容，可能影响后续同查询用户的响应（虽需本地代码执行权限）。