AI Agent 网页抓取与搜索开源工具箱 CrawlEyes：抓取 + 搜索 + 语义重排 + MCP 全打通（零 API Key）

【摘要】让 Agent 真正看见网页：抓取、搜索、语义重排、MCP 接入全打通。自托管零 key 可跑，国内实测稳定；正文降噪 89%，相关结果浮顶；内置深度调研与站点发现。MIT 开源，欢迎 Star 与 PR。

构建 Agent 应用时，一个绕不开的问题是：模型本身无法直接获取实时网页内容。要让 Agent 真正落地，通常需要自行整合一整条链路，包括页面抓取（处理 JS 渲染、动态加载、反爬拦截）、内容清洗、搜索接口接入、结果整理成模型可读的文本，再挂到 tool 调用上。链路上的每个环节都有成熟工具，但组合到一起时，接口不统一、限流策略各异、依赖相互冲突，往往要花费数天时间调试。

CrawlEyes 是这个项目的开源版本，将这条链路封装为统一的工具箱。下文按功能模块逐一说明。

抓取：从 URL 到干净的 Markdown

抓取层基于 Crawl4AI（无头浏览器），可处理大部分 JS 渲染、动态加载与 UA 拦截的页面，输出经过清洗的 Markdown。

python scripts/crawl4ai_cli.py https://example.com --text

输出支持四种格式：markdown（默认，去噪后的完整内容）、fit（精简核心段落）、raw（原始内容）、markdown_with_citations（每段附带来源引用）。

配套能力包括：正文降噪（实测一篇典型文章从 24.6k 压缩至 2.8k 字符，约 89% 的噪声被清除）、失败指数退避重试（1s/2s/4s）、同进程会话复用（连续抓取多个 URL 无需冷启动）、robots.txt 可选遵守（按 RFC 9309 实现，默认关闭，是否遵循由使用者根据合规需求决定）。

搜索：SearXNG 优先，Tavily 兜底

from crawl_search_standalone import CrawlSearch
r = CrawlSearch(rerank=True).search('AI agent web scraping')

主搜索走自托管的 SearXNG，不依赖第三方厂商；服务不可用时自动切换至 Tavily keyless，零配置、零 API key。可靠性方面内置熔断器（连续 3 次失败后进入 60 秒冷却）、SQLite 共享缓存（带 TTL）、统一限流与指数退避，避免高并发请求打垮下游服务。

语义重排：让相关结果浮上来

关键词匹配的搜索结果相关性有限，CrawlEyes 使用本地 embedding 进行重排。重排层基于 fastembed 与 BAAI/bge-small-zh-v1.5 模型，512 维向量，无 torch 依赖，模型约 50MB，加载约 0.6s。实测中相关结果可稳定浮至前列（相关性 0.817/0.732），无关结果下沉（0.302/0.139）。

MCP Server：标准协议接入

pip install crawleyes   # 或直接运行 scripts/mcp_crawl_server.py

项目提供标准 MCP server（stdio 传输），暴露四个工具：search（搜索）、extract（抓取，支持四种格式与 robots 开关）、sitemap（站点发现，通过 sitemap.xml 梳理页面结构）、deep_research（深度调研）。不绑定任何 Agent 框架，Claude Desktop、Cursor 等 MCP 客户端均可直接接入。

深度调研：从主题到带引用的报告

from crawleyes.deep_research import deep_research_sync
r = deep_research_sync("MCP protocol 2026")
r['report']   # 带引用来源的完整报告
r['sources']  # 来源列表

该功能自动拆解子问题、逐路搜索、抓取与降噪、最终合成报告。报告合成依赖 LLM，为可选能力（支持任意 OpenAI 兼容端点）；未配置 LLM 时降级为纯证据聚合，零依赖亦可运行。

设计取舍

每一层都有兜底。 抓取以 Crawl4AI 为基础，搜索采用 SearXNG + Tavily 双通道，均经过验证的 fallback 路径，单一环节故障不至于整体瘫痪。

面向境内环境优化。 Tavily keyless 无需注册、无需 key；安装默认走清华源，Playwright 走 npmmirror，模型走 hf-mirror，不依赖 Google 系服务。

合规边界明确。 项目不提供代理池、指纹轮换、验证码对抗能力，遵循 robots.txt 与站点条款；无法抓取的页面（如验证码墙）会如实标记为「不可解」，而非尝试绕过。

部署实践中遇到的问题

搜索链路在国内环境真正跑通，是开发过程中耗时最多、也最值得记录的部分，具体如下：

• SearXNG 默认配置启用的几乎全部是境外引擎（Google、DuckDuckGo、Brave 等），境内网络一个都连不上，中文搜索必然失败；
• 补充境内引擎后，百度高频查询会触发 CAPTCHA 风控，连续 10 次即被限制，需要增加 yandex 作为冗余；
• bing 在 JSON API 模式下静默返回空结果，连错误提示都没有，无法作为主力引擎使用；
• 最终采用 baidu + yandex 双主力配置，实测 10/10 连续查询稳定。

以上经验均已写入 README，便于后来者复用。

项目现状

• 源码：github.com/waiky-github/CrawlEyes（MIT 协议）
• 发布：PyPI pip install crawleyes，当前版本 0.2.0（含 sitemap、robots、多格式 extract、统一限流）
• MCP Registry：已收录 io.github.waiky-github/CrawlEyes
• CI：GitHub Actions 全绿（Python 3.10/3.12 测试 + ruff + 构建）
• 内部使用：项目作者维护的 Hermes Agent 5 个环境日常运行
• 合规：Credits 中标注了全部灵感来源（Crawl4AI、Readability、Firecrawl 等 9 个项目）

参与方式

项目采用 MIT 协议开源，欢迎通过 GitHub 提交 Issue 或 Pull Request。

---

（本文同步发布于掘金 / 知乎 / 公众号，欢迎 Star：https://github.com/waiky-github/CrawlEyes）