Web Search Pro

核心用法

Web Search Pro 是一套面向 AI Agent 的检索基础设施，无需 API Key 即可启动基础功能，通过环境变量注入可选服务商（Tavily、Exa、Serper、SerpAPI）实现增强覆盖。

基础能力矩阵

| 命令 | 功能 | 无Key fallback |

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

| `search.mjs` | 多源搜索 | DuckDuckGo (ddg) |

| `extract.mjs` | 单页内容提取 | 原生 fetch |

| `crawl.mjs` | 站点级爬取 | 原生 fetch |

| `map.mjs` | 链接拓扑映射 | 原生 fetch |

| `research.mjs` | 结构化研究输出 | 组合基础源 |

| `doctor.mjs` / `health.mjs` | 诊断与自检 | 本地执行 |

| `capabilities.mjs` | 能力清单导出 | 本地执行 |

| `review.mjs` | 结果复盘 | 本地执行 |

| `cache.mjs` | 检索缓存管理 | 本地存储 |

智能路由机制：selectedProvider 由规划器动态选择；federated.providersUsed 记录多路并发时的实际响应源。研究模块输出包含 topicType、topicSignals、researchAxes 的结构化摘要，便于下游模型消费。

显著优点

• 零门槛启动：Node.js 环境即装即用，无密钥依赖降低试用成本
• 渐进增强架构：基线功能完备，按需叠加付费 API 不破坏既有代码
• 研究原生设计：非简单搜索包装，内置主题分解、信号提取、研究轴规划等 AI 友好输出
• 全链路可观测：诊断、复盘、健康检查脚本齐全，便于生产环境运维
• 开源可控：GitHub 托管，可审计、可 fork、可定制

潜在缺点与局限性

• 基线质量波动：DuckDuckGo 与原生 fetch 的稳定性、反爬策略、时效性弱于专业商业 API
• 并发与速率限制：无 Key 模式下缺乏服务商级别的 SLA 保障，大规模采集易触发源站限流
• 中文/区域内容：DDG 对中文搜索结果优化有限，国内站点（如百度）需依赖 SerpAPI 等可选源
• 缓存一致性：cache.mjs 为本地文件级实现，多机部署需自行解决同步
• 错误恢复粒度：文档未明确描述失败源自动剔除与降级策略的透明度

适合人群

• 构建 RAG/Agent 系统的开发者，需要可插拔的检索层
• 知识管理工具构建者，追求「搜索-提取-研究」一体化工作流
• 预算敏感型用户，希望从免费方案起步、业务验证后再升级
• 数据分析师与研究人员，需要结构化研究输出而非原始网页堆砌

常规风险

• API Key 泄露：Tavily/Exa/Serper/SerpAPI 等密钥若硬编码存在泄露风险，建议配合机密管理服务
• 网络侧信道：fetch fallback 直接暴露客户端 IP，高匿名场景需配合代理
• 内容合规：爬取与提取行为需遵守目标站点的 robots.txt 及当地法规（如 GDPR 数据留存）
• 依赖供应链：Node.js 运行时与 npm 生态的安全更新需持续跟踪

核心用法

Web Search Pro 2.0 是专为 AI Agent 设计的检索增强工具集，提供 10 个核心命令覆盖搜索全流程：

| 命令 | 功能 |

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

| `search.mjs` | 多引擎智能搜索，自动选择最优 provider |

| `extract.mjs` | 网页内容提取与结构化解析 |

| `crawl.mjs` | 深度网页爬取 |

| `map.mjs` | 站点地图生成 |

| `research.mjs` | 多轴研究模式，生成结构化调研报告 |

| `doctor.mjs` / `capabilities.mjs` | 诊断与能力自检 |

| `review.mjs` / `cache.mjs` / `health.mjs` | 审计、缓存与健康检查 |

使用模式：

• 零配置模式：无需任何 API Key，自动降级至 DuckDuckGo HTML 抓取 + Node.js fetch
• 增强模式：配置 Tavily/Exa/Serper/SerpAPI 密钥，解锁深度搜索、语义检索、新闻 API 等高级能力

关键语义：

• selectedProvider：规划器选择的主路由
• federated.providersUsed：实际返回结果的 provider 列表（多路扇出时）
• topicType / topicSignals / researchAxes：面向模型的结构化研究摘要

显著优点

1. 零门槛启动：无 API Key 即可运行 baseline，适合快速原型与轻量场景
2. 多引擎联邦架构：智能路由 + 多 provider 扇出，自动容错与结果融合
3. 企业级安全防护：

4. 纯原生依赖：56 个 JS 模块零第三方 npm 依赖，供应链攻击面极小
5. 模块化设计：各脚本独立可调用，易于集成到现有工作流

• assertSafeRemoteUrl 函数阻断私有 IP、内网域名访问，有效防御 SSRF
• 所有外部 API 强制 HTTPS (TLS 1.2+)

潜在局限

1. 来源可信度 T3：个人开发者维护（GitHub @Zjianru），非企业背书，需持续关注更新动态
2. 子进程依赖：使用 child_process.execFile 调用 curl/python 作为 fetch 备选，虽参数受控但增加攻击面
3. DuckDuckGo 稳定性：无 Key 模式依赖 HTML 抓取，易受页面结构变更影响
4. 无持久化加密：缓存文件默认明文存储，需手动设置目录权限
5. 网络延迟敏感：多 provider 扇出时总耗时取决于最慢响应

适合人群

• AI Agent 开发者：需要为 LLM 提供实时检索能力的工程团队
• 研究型用户：需要 research.mjs 多轴调研模式生成结构化报告
• 隐私敏感场景：可选择仅使用 DuckDuckGo + fetch，避免向商业 API 暴露查询
• 离线/受限环境：依赖纯 Node.js 内置模块，无需复杂依赖安装

常规风险

| 风险项 | 等级 | 说明 |

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

| API 密钥泄露 | 中 | 环境变量读取，需避免 `.env` 文件误提交 |

| SSRF | 低 | 已缓解：URL 白名单 + 私有 IP 阻断 |

| 命令注入 | 低 | 已缓解：`execFile` 参数转义，无用户输入直接拼接 |

| 缓存数据暴露 | 低 | 建议设置 `chmod 700 .cache/web-search-pro` |

| 供应链攻击 | 极低 | 零第三方依赖 |

| 账号盗用/恶意更新 | 中 | T3 来源固有风险，建议锁定版本并验证 hash |

监控建议：启用 WEB_SEARCH_PRO_DEBUG=1 审计日志，定期轮换 API 密钥，90 天重新评估 Skill 安全性。