smart-web-search

智能联网搜索工具，整合多项优化能力：

核心特性

1. 区域自动切换（HTTP 优先，cookies 兜底）

• 国内网络: 自动使用 Bing 国内版（HTTP 直连优先）
  • 结果不足 3 条时，启动有头浏览器获取 cookies 后立即关闭，用 cookies 重试 HTTP
  • 浏览器只用于获取 session cookies，搜索仍走 HTTP 通道
• 国际网络: 自动使用 DuckDuckGo HTML（纯 HTTP，速度快）
• 兜底策略: 主引擎无结果时自动切换备用引擎
• 架构优势: 主路径基于 HTTP 请求，速度快、资源占用低

2. Query 智能改写

基于搜索意图自动优化关键词，提升结果相关性：

可通过 --no-rewrite 跳过改写。

3. 双层内容抓取

搜索后自动抓取前 N 条 URL 的正文内容：

• 第 1 层: 轻量 HTTP + cheerio（秒出，不启动浏览器）
  • 支持 JSON API、JSON-LD、Next.js 数据提取
  • 自动处理 GBK 编码
• 第 2 层: Playwright headed 浏览器兜底（支持 JS 渲染页面）

4. 低质量域名过滤

可选参数 --filter，自动过滤：

• 百度经验/知道/贴吧/文库
• 知乎（可选）

使用示例

# 基础搜索（自动检测区域，抓取前3条正文）
node scripts/search.js "Claude Code 教程"

# 指定区域
node scripts/search.js "最新科技新闻" --region=cn

# 只搜索不抓正文
node scripts/search.js "React hooks" --no-fetch

# 过滤低质量域名
node scripts/search.js "编程入门" --filter

# 跳过 Query 改写
node scripts/search.js "今日金价" --no-rewrite

# 抓取前5条正文
node scripts/search.js "AI 发展趋势" --fetch=5

# 最多返回20条结果
node scripts/search.js "开源项目" --max=20

安装

自动安装（推荐）

cd smart-web-search
bash scripts/setup.sh   # Linux/macOS

Windows PowerShell：

cd smart-web-search
npm install
npx playwright install chromium

依赖

说明：

• 搜索功能完全基于 HTTP，无需浏览器
• 正文抓取优先用 HTTP，失败时 Playwright 兜底（需要 Chromium）
• 如果只使用 --no-fetch（不抓正文），可以不安装 Chromium

国内用户安装时自动使用镜像源加速。

参数说明

性能优化

• 复用浏览器守护进程（提速约70%）
• 国内/海外引擎智能选择
• HTTP 优先，Playwright 兜底
• 并行抓取多个 URL

已知限制

• Bing 即时答案卡片（天气、计算器）不返回网页链接，会触发补词重试
• DDG 国内访问：DuckDuckGo 在国内被墙，国内策略不使用 DDG 主引擎
• JS 渲染页面：部分需要 JS 渲染的页面，HTTP 抓取失败时自动用 Playwright headed 重试
• 代理环境：出口 IP 走代理可能影响区域检测，可手动指定 --region=cn/intl

技术架构

区域检测（三轮并行探测，3秒超时）
  ↓
Query 改写（意图识别规则，可选）
  ↓
搜索引擎（纯 HTTP，无浏览器）
  - 国内: Bing HTML (cn.bing.com)
  - 海外: DDG HTML (html.duckduckgo.com)
  ↓
去重（域名+路径主干） + 域名过滤（可选）
  ↓
正文抓取（默认前3条）
  - 第1层: HTTP + cheerio（秒出，JSON-LD/Next.js 数据提取）
  - 第2层: Playwright headed 兜底（处理 JS 渲染页面）
  ↓
返回 JSON 结果（title, url, snippet, content）

性能优化：

• 搜索阶段无浏览器启动，响应时间 \x3C 3 秒
• 正文抓取并行执行，HTTP 优先保证速度
• 复用浏览器守护进程（如果启用），提速约 70%

与其他搜索工具的对比

推荐使用场景：

• 本工具 (smart-web-search): 需要快速稳定搜索，国内外环境都适用，OpenClaw 社区推荐
• free-web-search-js: 已在项目中使用且稳定运行
• free-web-search (Python): Python 技术栈，无 Node.js 环境

与 Claude Code 内置 WebFetch 的关系：

• 本工具侧重 搜索 + 批量抓取，适合"查资料、找教程、搜新闻"场景
• WebFetch 侧重 单 URL 精确抓取，适合"读取已知网页内容"场景
• 两者互补，可配合使用

验证环境

cd smart-web-search
node scripts/search.js "测试搜索" --max=2 --no-fetch

成功返回 JSON 数组即可。