TheCrawler

TheCrawler — 面向 AI 的网页抓取工具，具有经过验证的提取契约

抓取网页、运行 LLM 驱动的结构化提取，或在消耗 LLM 令牌前，诊断 URL 是否符合内置提取契约的要求。开源引擎（AGPL-3.0）。在 Apify 上，每成功抓取一个页面收费 $0.005。

先进行安全测试：在 Apify 上使用 dryRun: true 运行一个公开 URL，或克隆当前 GitHub 源代码，并从 engine/ 运行本地 CLI/MCP 构建。小型验证包位于 examples/diagnostic-challenge，其中包含一份示例就绪度报告：examples/diagnostic-challenge/sample-report.md。

$500 提取就绪度冲刺

如果你需要在投入工程时间进行提取之前，判断一个实际的公开网络工作流是否值得自动化，可使用此服务。

• 范围：最多 25 个公开 URL，以及一种目标输出格式。
• 第一步：通过结构化问题表单提交公开的适配性检查，或通过冲刺页面进行私密适配性检查。
• 付款：仅在确认工作流适用后才会要求付款，可通过一次性 $500 付款链接或发票支付。
• 交付内容：一份就绪度报告，提供就绪、部分就绪、受阻或暂不值得自动化的建议。
• 抵扣：如果工作流继续进入设置或托管使用阶段，$500 可抵扣下一步费用。

公开服务帖见 GitHub issue #1。验证包中包含一份示例就绪度报告，展示买家提交 URL 前的报告格式。

公开适配性检查应采用以下格式：

Workflow type:
Public URLs (up to 25):
Target output shape / required fields:
Known blockers or constraints:
Timing:

请勿在 GitHub issues 中包含登录凭据、私密 URL、个人数据或原始客户数据。

有何不同

• 经过验证的提取契约：选择内置契约，即可获得规范化数据，以及 validation.valid、必填字段和缺失字段证据。当前契约：real-estate-listing、product-page、docs-page。
• 品牌标识提取（extractBrand: true）：一次调用即可返回网站按排名排列的颜色 palette、themeColor，以及最可能的 logo 候选项（JSON-LD / 页眉 SVG / 网站图标 / og:image）。在 Playwright 模式下，会通过 getComputedStyle 读取渲染后的颜色，适用于无法使用静态 CSS 的 SPA。确定性提取，无需大模型。
• 内容控制：通过 onlyMainContent 以及 includeTags / excludeTags（CSS 允许/拒绝规则），从文本、Markdown、链接和 HTML 输出中剔除导航栏、页脚、侧边栏和广告。兼容 Firecrawl。支持 waitFor 别名。
• HTML 格式：除 Markdown 外，还支持 extractHtml（清理后的主要内容 HTML）和 extractRawHtml（完整序列化 DOM）。
• 无需大模型的诊断：运行 diagnoseMode，即可评估数据源就绪情况、找出阻碍因素，并在提取前保存一份便于买家阅读的 Markdown 报告。
• 大模型驱动的提取：发送 JSON Schema 或使用契约，即可获取解析后的类型化数据。与端点无关，可连接到 OpenAI、你自己的 llama.cpp / vLLM / LM Studio / Ollama。由你提供大模型，不受供应商锁定。
• 自适应爬取：优先使用 Cheerio（HTTP 请求与解析速度快），检测到 SPA 外壳时自动回退到 Playwright。浏览器渲染为可选项，无需对每个页面都强制启用。
• 结构化错误：errorType 枚举（dns | timeout | rate-limit | blocked-bot | js-required | http-4xx | http-5xx | parse | network | unknown）+ errorRetryable 布尔值。Agent 可通过程序逻辑进行分支判断，无需对错误字符串使用正则表达式。
• 挑战页面检测：对于带有访问控制或挑战页面内容的 200 OK 响应，会标记为 errorType: 'blocked-bot'，而不是将挑战页面 HTML 当作有效内容返回。
• 开箱即用的提取器：JSON-LD、微数据、电商数据（价格/SKU/评分）、带字段类型的表单、16 种已检测的分析跟踪器（GA4、GTM、Meta Pixel、Hotjar、Segment、Mixpanel 等）、hreflang、分页、重定向链。类似电子邮件和电话号码的公开文本提取为可选功能。
• 感知标题结构的 RAG 分块：在 h1-h3 边界处对 Markdown 分块，包含重叠内容和每块的 SHA。可直接传入向量数据库。

三种模式

安全首次运行

使用 dryRun: true 进行 Apify 冒烟测试。该 Actor 会爬取页面，但不会产生计费事件。

{
  "urls": ["https://example.com"],
  "extractMarkdown": true,
  "dryRun": true
}

当前本地 MCP/CLI 版本：

git clone https://github.com/manchittlab/TheCrawler.git
cd TheCrawler/engine
npm install
npm run build
node dist/cli.js crawl https://example.com --markdown

普通爬取（默认）

{
  "urls": ["https://example.com"],
  "extractMarkdown": true,
  "rotateUserAgent": true,
  "requestRetries": 3
}

每个 URL 返回丰富的 PageData：标题、描述、语言、规范 URL、robots 指令、完整文本、剔除模板内容的 Markdown、链接（含内部/外部标记）、图片（含延迟加载的 src）、元标签、OG/Twitter Card、JSON-LD、微数据、电商数据、表单、检测到的分析跟踪器、可选的类似电子邮件/电话号码的公开文本字段、社交链接、hreflang、分页、重定向链、响应头与耗时，以及失败时的结构化 errorType + errorRetryable。

大模型驱动的提取模式

{
  "urls": ["https://shop.example.com/products/123"],
  "extractMode": true,
  "extractJsonSchema": {
    "type": "object",
    "properties": {
      "productName": { "type": "string" },
      "price": { "type": "number" },
      "currency": { "type": "string" },
      "inStock": { "type": "boolean" }
    },
    "required": ["productName"]
  },
  "llmBaseUrl": "https://api.openai.com/v1/chat/completions",
  "llmModel": "gpt-4o-mini"
}

爬取 URL → 清理为 Markdown → 将 (markdown + schema) 发送到你的 OpenAI 兼容聊天补全端点 → 为每个 URL 返回解析后的类型化数据。在支持的情况下，基于 Schema 的提取会使用 JSON Schema 响应格式；对于仅支持 JSON 对象或文本输出的端点，则会采用回退方案。支持使用自然语言 extractPrompt 代替 Schema，或与 Schema 搭配使用。Actor 按普通方式按页面计费；大模型调用费用由你的端点决定。

注意：提取模式需要可从公网访问的大模型端点。局域网 URL（例如 http://192.168.x.x）无法从 Apify 基础设施访问。请使用 OpenAI、托管的 vLLM，或通过隧道公开你的本地服务。

将 THECRAWLER_LLM_API_KEY 设置为 Actor 环境变量，这样大模型密钥就不会出现在运行输入中（运行历史记录可见）。

合同诊断模式

{
  "urls": ["https://example.com/listing-1", "https://example.com/listing-2"],
  "diagnoseMode": true,
  "extractContract": "real-estate-listing",
  "diagnosticReport": true
}

运行爬取和就绪度评分，不调用大模型。数据集输出包含每个 URL 的 verdict、readyForExtraction、score、blockers、warnings 和 recommendedNextStep，以及工作流摘要。当 diagnosticReport 为 true 时，Actor 会在运行的键值存储中以 Markdown 格式保存 contract-diagnostic-report，其中包含缺失的就绪度信号摘要。报告有意排除提取出的原始联系详情。

合同提取模式

{
  "urls": ["https://example.com/listing-1"],
  "extractMode": true,
  "extractContract": "product-page",
  "llmBaseUrl": "https://api.openai.com/v1/chat/completions",
  "llmModel": "gpt-4o-mini"
}

使用所选合同架构和提示词，然后将合同验证结果附加到提取结果中。Agent 可以根据 validation.valid 和 validation.missingRequiredFields 进行分支判断，而不必依赖不严格的 Markdown。内置合同目前涵盖 real-estate-listing 和 product-page。

可靠性功能

功能	默认值	原因
requestRetries	3	自动重试暂时性故障（5xx、网络、超时）
requestTimeoutSecs	30	限制每个请求的耗时
rotateUserAgent	true	使用标准浏览器 User-Agent 字符串以确保兼容性；不会覆盖访问控制
cacheEnabled	false	可选启用每个（URL + 提取标志）的 5 分钟内存 LRU 缓存
挑战页面检测	始终开启	将访问控制或挑战页面正文标记为 errorType: 'blocked-bot'
自适应爬取	可选	adaptiveCrawling: true 会先尝试 Cheerio，检测到 SPA 时再升级为 Playwright

搜索 → 抓取

一次调用即可爬取 Google 前 N 条结果。可选提供 SerpAPI 密钥以实现可靠搜索。

{ "searchQuery": "best CRM 2026", "searchLimit": 10, "extractMarkdown": true }

Sitemap → 抓取

自动解析 Sitemap.xml 和 sitemap-index 文件。

{ "sitemapUrl": "https://example.com/sitemap.xml", "maxPages": 50 }

文件提取

自动检测并解析 PDF 和 DOCX URL。返回提取出的文本，以及 PDF 的元数据和页数。

定价

• 爬取模式：每成功抓取一个页面收费 $0.005（失败页面不收费）。
• 提取模式 / 诊断模式：仍按成功抓取的页面收费。LLM 端点费用由端点所有者支付，而非此 Actor。
• 提取就绪度冲刺：确认适配后，为一个公开工作流收费 $500：最多 25 个公开 URL、一种目标输出格式，以及一份就绪 / 部分就绪 / 受阻报告。范围确认后，通过一次性付款链接或发票付款。如果工作流继续进行设置或托管使用，$500 可抵扣后续步骤的费用。如果其他技术栈更合适，报告会说明这一点。

超越 Apify Store

此 Actor 构建所用的当前开源引擎源码位于 engine/；可将其放入你自己的 Node 项目、MCP 服务、命令行工具或 REST API 服务中。已发布的 npm 包版本早于此 GitHub 源码；在下次发布 npm 包之前，如需使用当前已验证合同和 MCP 工具，请按下方 GitHub 源码路径操作。自托管可避免 Apify 按页面收费，但仍需承担自有基础设施和 LLM 端点的费用。

# Current GitHub source build
cd engine
npm install
npm run build

# CLI
node dist/cli.js crawl https://example.com --markdown
node dist/cli.js extract https://example.com --schema '{...}'

# MCP server (Cline, Claude Code, Cursor, Windsurf)
node dist/mcp.js

# REST API server
THECRAWLER_API_KEY=local_test_key node dist/server.js --port 3000
curl -H "Authorization: Bearer local_test_key" \
  "http://localhost:3000/v1/contracts?includeSchema=true"
curl -X POST "http://localhost:3000/v1/scrape" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/product","formats":["markdown","metadata","links","structuredData","commerceData"]}'
curl -X POST "http://localhost:3000/v1/diagnose" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"contractName":"product-page","urls":["https://example.com/product"],"reportMarkdown":true}'
curl -X POST "http://localhost:3000/v1/map" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","maxPages":1}'
curl -X POST "http://localhost:3000/v1/extract-contract" \
  -H "Authorization: Bearer local_test_key" \
  -H "Content-Type: application/json" \
  -d '{"contractName":"product-page","urls":["https://example.com/product"],"llmBaseUrl":"http://localhost:1234/v1/chat/completions","llmModel":"qwen/qwen3.5-9b"}'

# Older npm package; use for plain crawl only until the next publish
npm install thecrawler
thecrawler crawl https://example.com --markdown

从 GitHub 克隆仓库进行 Cline 设置时，请使用 llms-install.md。在更新 npm 之前，当前 GitHub 源码是已验证合同和 MCP 工具的审查路径。

GitHub：https://github.com/manchittlab/TheCrawler · 许可证：AGPL-3.0