单项目深读

Firecrawl：把网页抓成 LLM 可直接用的 Markdown

面向 AI agent 与 RAG 的网页抓取 API，把站点抓成 Markdown 或结构化 JSON，省去自建爬虫和清洗。

2026-10-18|INS-0019

给 AI agent 喂网页，真正的成本从来不在「下载 HTML」这一步。难的是下载之后：JS 渲染完没有、正文和导航广告怎么切、PDF 和 DOCX 怎么办、代理被封了怎么换、几千个 URL 怎么并发还不炸目标站。Firecrawl 把这一整条链路收进一个 API，对外只暴露几个动词：search、scrape、interact、crawl、map、agent。

先把六个动词分清楚

README 把端点分成两组，这个分组本身就说明了它的设计意图。

核心端点（一次调用解决一件事）：

端点	职责	输入 → 输出
Search	搜网页并直接带回结果页的完整内容	query + limit → 带 `markdown` 字段的结果数组
Scrape	单个 URL 转 markdown / HTML / 截图 / 结构化 JSON	url → 页面内容
Interact	先抓页面，再用自然语言 prompt 或代码操作它	scrape_id + prompt → 操作结果 + liveViewUrl

扩展端点（把抓取扩成任务）：

端点	职责	形态
Agent	只描述需求，不用给 URL，由 AI 自己搜索、导航、取数	prompt（+ 可选 schema / urls / effort）→ 结构化结果 + sources
Crawl	一次请求抓完整站	返回 job id，轮询状态
Map	快速发现站点上的所有 URL	站点 → URL 列表
Batch Scrape	异步抓成千上万个 URL	批量任务

关键区分在 Search 和 Scrape：Search 返回的每条结果自带 markdown，也就是说搜索和抓取被合并成一次调用，省掉了「先搜到链接、再逐个抓」的两跳。对 RAG 场景这是最省事的一步。

架构：四层，从协议面到执行面

README 没有贴架构图，但从端点划分和功能描述可以还原出一条清晰的四层结构。

第一层：接入层（SDK / CLI / MCP）

同一套能力有四种进入方式，README 的每个端点都并列给出了 Python、Node.js、cURL、CLI 四种写法。Python 侧是 from firecrawl import Firecrawl，Node 侧是 import { Firecrawl } from 'firecrawl'，cURL 直打 https://api.firecrawl.dev/v2/...，CLI 是 firecrawl scrape ...。再往上一层是 MCP：firecrawl-mcp 通过 npx 启动，任何兼容 MCP 的客户端配上 FIRECRAWL_API_KEY 就能连。这一层的意义是把「抓网页」从代码里的事变成 agent 运行时能直接调用的工具。

第二层：任务编排层

Crawl、Map、Batch Scrape、Agent 都属于这一层。它们的共同特征是不返回内容、返回 job id。Crawl 的响应是 {"success": true, "id": "123-456-789", "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"}，之后用 GET 轮询，完成时拿到 status、total、completed、creditsUsed 和 data 数组。这一层负责把「一个 URL」放大成「一个站点」或「一批 URL」，并管理并发、限速和任务状态。

第三层：抓取执行层

真正干活的地方。README 的 Why 段落把这里做的事列得很直白：轮换代理、编排、限速、JS 阻塞内容，「zero configuration」。它还提到覆盖面 96% 的网页（含 JS 重的页面）、跨百万页面的 P95 延迟 3.4s——这两个数字来自官方 benchmark 博文，README 里给了链接。同一层还负责媒体解析：网页上托管的 PDF、DOCX 等格式的内容抽取。

第四层：输出层

把抓到的内容规整成 LLM 能直接吃的形式：干净的 markdown、结构化 JSON、截图。结构化输出靠 schema 驱动——Agent 端点接受 pydantic 模型作为 schema，返回的 JSON 直接对齐字段定义。这一层是「省 token」的实际发生地：markdown 比原始 HTML 少掉大量标签噪音。

请求的流转大致是：SDK/CLI/MCP 发起 → 编排层判断是单页还是任务 → 执行层渲染、绕反爬、抽内容 → 输出层转成 markdown 或按 schema 组装 JSON → 回传。Interact 是个例外路径，它把一次 scrape 的结果留成一个 scrape_id，后续的 prompt 都作用在这个会话上，所以能「先搜再点第一条结果」这种连续动作。

最小可用用法

装好 SDK、拿到 API key 之后，最省事的一条路是直接抓一个页面：

python
from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

result = app.scrape('firecrawl.dev')

返回的就是 markdown，形如：


# Firecrawl

Firecrawl helps AI agents search, scrape, and interact with the web.

## Features
- Search: Find information across the web
- Scrape: Clean data from any page
- Interact: Click, navigate, and operate pages
- Agent: Autonomous data gathering

如果只要正文、不要导航和页脚，CLI 有个开关：

bash
firecrawl scrape https://firecrawl.dev
firecrawl https://firecrawl.dev --only-main-content

需要多步操作时，用 Interact 把 scrape 和后续动作串起来——先抓 Amazon，拿到 scrape_id，再让它搜关键词、点第一个结果：

python
result = app.scrape("https://amazon.com")
scrape_id = result.metadata.scrape_id

app.interact(scrape_id, prompt="Search for 'mechanical keyboard'")
app.interact(scrape_id, prompt="Click the first result")

返回里除了 output，还有一个 liveViewUrl，指向这次会话的实时视图。这个设计对调试很有用：agent 点错了地方，你能回看它当时看到的页面。

接 agent 更省事，一条命令：

bash
npx -y firecrawl-cli@latest init --all --browser

README 说它对 Claude Code、Antigravity、OpenCode 等都可用，装完重启 agent 即可。MCP 客户端则用配置块接入：

json
{
  "mcpServers": {
    "firecrawl-mcp": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "fc-YOUR_API_KEY"
      }
    }
  }
}

Agent 端点：把「找 URL」这一步也交出去

Agent 是 README 里唯一被明确标注为「演进」的端点——它取代了旧的 /extract，理由是更快、更可靠，而且不需要你事先知道 URL。调用只需要一句 prompt：

bash
curl -X POST 'https://api.firecrawl.dev/v2/agent' \
  -H 'Authorization: Bearer fc-YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Find the pricing plans for Notion"}'

返回的 data 里有 result（自然语言答案）和 sources（来源 URL）。要结构化数据就传 schema，比如用一个 FoundersSchema 定义 founders 列表，每个元素有 name 和可选的 role，返回就是干净的 JSON 对象。也可以传 urls 把 agent 限定在指定页面内做对比。

这里有个容易被忽略的参数：effort。它分 low / medium / high 三档，README 说得很清楚——每一档跑的都是 spark-2 模型，effort 改的是推理预算，不是模型。旧名字 spark-1-pro 和 spark-1-mini 仍然接受，但已废弃，实际也跑 spark-2。这个区分对成本估算很重要：调高 effort 不等于换更贵的模型，而是让同一个模型多想几步。

effort	适用场景
`low`	单站点上的简单查找
`medium`	少数几个页面上的多步任务
`high`	深度研究、复杂导航、关键数据

Crawl 的异步模型

抓整站不是一次请求能完成的，所以 Crawl 走任务模式。发起时给 URL、limit 和 scrapeOptions（比如 formats: ["markdown"]），拿回 job id；轮询 GET /v2/crawl/{id}，完成时拿到：

json
{
  "status": "completed",
  "total": 50,
  "completed": 50,
  "creditsUsed": 50,
  "data": [
    {
      "markdown": "# Page Title\n\nContent...",
      "metadata": {"title": "Page Title", "sourceURL": "https://..."}
    }
  ]
}

注意 creditsUsed 和 total 是并列出现的——用量是按抓取页数计的，这一点在估算批量任务成本时是唯一可靠的依据。data 里每一项都带 metadata.sourceURL，回溯来源不用额外记录。

和同主题项目比，它站在哪

把 Firecrawl 放进这批对照项目里看，定位差异非常明显：其余几个解决的是「agent 怎么想、怎么调工具」，Firecrawl 解决的是「agent 从哪拿到可信的输入」。

项目	语言	核心问题	与 Firecrawl 的关系
Firecrawl	TypeScript	把网页变成 LLM 可用的干净数据	—
ECC	JavaScript	给现有 agent 加 skills 与记忆层，长任务更稳、更省 token	消费方：Firecrawl 可作为它的一个 skill 提供实时网页输入
hermes-agent	Python	把 prompt、工具调用、workflow 串成 agent	消费方：Firecrawl 是它可调用的外部工具之一
AutoGPT	Python	目标驱动的多步任务拆解与执行	消费方：需要外部数据源时接 Firecrawl
ollama	Go	本地一条命令跑模型，离线推理	互补：一个管推理侧，一个管数据侧
prompts.chat	HTML	社区 prompt 分享与自托管	无关但同层：都在给 LLM 应用补基础设施

这张表能看出一件事：这批项目里大部分是 agent 框架或模型运行时，Firecrawl 是少数站在数据供给侧的项目。它的竞争对手不是这些框架，而是每个团队自己写的 requests + BeautifulSoup + Playwright + 代理池那一套。

值得注意的几个工程细节

输出格式是可选的，不是固定的。 Scrape 支持 markdown、HTML、截图、结构化 JSON 四种产物。给 RAG 用 markdown，给需要精确字段的下游用 JSON，给需要视觉判断的场景用截图。

媒体解析在抓取层完成。 网页上挂的 PDF、DOCX 不需要你先下载再另找解析器，README 把它列在「We handle the hard stuff」里。

Actions 让抓取前可以先操作。 Click、scroll、write、wait、press——这些动作在提取内容之前执行。这解决的是「内容要点开才出现」的页面，比如折叠面板、懒加载列表、需要输入才显示的查询结果。

开源与托管并存。 仓库是 AGPL-3.0，同时官方提供托管服务。这意味着自建可行，但要接受 AGPL 的传染性条款；不想承担运维就直接用 api.firecrawl.dev。这个双轨结构也是它能同时服务个人开发者和企业客户的原因。

agent 可以自助接入。 README 里有一段专门写给 AI agent 看的说明：curl -s https://firecrawl.dev/agent-onboarding/SKILL.md，让 agent 自己去注册用户、拿 API key、开始构建。这是个有意思的产品动作——把接入文档写成 agent 能读的格式，而不是只给人看。

项目事实

源码：github.com/firecrawl/firecrawl
官网：firecrawl.dev
语言：TypeScript · 许可：AGPL-3.0
星标 192,520 · forks 10,168 · open issues 621
创建于 2024-04-15，最近推送 2026-10-17
topics 覆盖 ai-scraping、html-to-markdown、web-crawler、data-extraction、ai-agents 等

官网首页的定位写得很直接：「Web Data API for AI Agents」。README 的口号更进一步，「Building the library for superintelligence」。口号归口号，但从端点设计看，它真正在做的事很具体：把网页抓取这件脏活标准化成六个动词，让 agent 只需要说「我要什么」，不用管「怎么拿到」。

返回解读列表