Firecrawl Agent Skill

Firecrawl — 用于大规模搜索、抓取和与网络交互的 API。将任何网页转化为干净的 Markdown 或结构化数据。

概述

Firecrawl 是一个 Web 数据 API，专为 AI Agent 设计。支持以下核心能力：

| 功能 | 端点 | 说明 | |------|------|------| | Scrape | POST /v2/scrape | 抓取单个 URL，返回 Markdown/结构化数据/截图 | | Search | POST /v2/search | 搜索互联网，返回结果列表（含页面内容） | | Map | POST /v2/map | 获取网站所有可抓取的 URL 列表（站点地图） | | Crawl | POST /v2/crawl | 爬取整个网站，支持异步批量处理 | | Monitor | POST /v2/monitor | 监控网页/网站变化，变化时触发通知 |

API 配置

Base URL: https://api.firecrawl.dev
API Key: 通过环境变量或配置传入（FIRECRAWL_API_KEY）
认证方式: Authorization: Bearer <API_KEY>

触发条件

当用户需要以下操作时触发：

"用 Firecrawl 抓取网页"、"Firecrawl 抓取"、"用 Firecrawl 搜索"
"抓取这个网站"、"爬取网站内容"、"提取网页内容为 Markdown"
"搜索网页"、"网站地图"、"爬取整站"
"监控网页变化"、"网页变动提醒"
用户提供 Firecrawl API Key 并要求抓取/搜索时
关键词：firecrawl、fire crawl、网页抓取、web scraping、web crawl、site map、网页监控

使用方式

Python 代码模板

import os
import requests

FIRECRAWL_API_KEY = os.environ.get("FIRECRAWL_API_KEY", "")  # 从环境变量读取
BASE_URL = "https://api.firecrawl.dev"
HEADERS = {
    "Authorization": f"Bearer {FIRECRAWL_API_KEY}",
    "Content-Type": "application/json"
}

1. Scrape — 抓取单个页面

def scrape_url(url: str, formats: list = None) -> dict:
    """抓取单个 URL，返回 Markdown 或结构化数据。
    
    Args:
        url: 目标网页 URL
        formats: 输出格式列表，可选 ["markdown", "html", "screenshot", "links"]
                 默认 ["markdown"]
    """
    payload = {
        "url": url,
        "formats": formats or ["markdown"]
    }
    resp = requests.post(f"{BASE_URL}/v2/scrape", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()

2. Search — 搜索互联网

def search_web(query: str, limit: int = 5) -> dict:
    """搜索互联网，返回结果列表（含页面摘要）。
    
    Args:
        query: 搜索关键词
        limit: 返回结果数量，默认 5
    """
    payload = {
        "query": query,
        "limit": limit
    }
    resp = requests.post(f"{BASE_URL}/v2/search", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()

3. Map — 获取站点地图

def map_site(url: str, limit: int = 100) -> dict:
    """获取网站所有可抓取的 URL 列表。
    
    Args:
        url: 目标网站根 URL
        limit: 返回 URL 数量上限
    """
    payload = {
        "url": url,
        "limit": limit
    }
    resp = requests.post(f"{BASE_URL}/v2/map", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()

4. Crawl — 爬取整站（异步）

def crawl_site(url: str, max_depth: int = 2, limit: int = 100) -> dict:
    """异步爬取网站，返回任务 ID，需轮询获取结果。
    
    Args:
        url: 目标网站 URL
        max_depth: 爬取深度
        limit: 最大页面数
    """
    payload = {
        "url": url,
        "maxDepth": max_depth,
        "limit": limit
    }
    resp = requests.post(f"{BASE_URL}/v2/crawl", headers=HEADERS, json=payload, timeout=60)
    resp.raise_for_status()
    return resp.json()  # 返回 {"id": "..."} 任务 ID

def check_crawl_status(id: str) -> dict:
    """查询爬取任务状态和结果。"""
    resp = requests.get(
        f"{BASE_URL}/v2/crawl/{id}",
        headers=HEADERS,
        timeout=60
    )
    return resp.json()

5. Scrape with Extract — 结构化数据提取

def extract_data(url: str, prompt: str, schema: dict = None) -> dict:
    """使用 AI 从页面中提取结构化数据。
    
    Args:
        url: 目标网页 URL
        prompt: 提取指令（自然语言描述要提取什么）
        schema: 可选，输出 JSON Schema 约束
    """
    payload = {
        "url": url,
        "extract": {
            "prompt": prompt
        }
    }
    if schema:
        payload["extract"]["schema"] = schema
    resp = requests.post(f"{BASE_URL}/v2/scrape", headers=HEADERS, json=payload, timeout=90)
    resp.raise_for_status()
    return resp.json()

响应格式

Scrape 响应结构

{
  "success": true,
  "data": {
    "markdown": "...",
    "html": "...",
    "screenshot": "base64...",
    "links": ["..."],
    "metadata": {
      "title": "...",
      "description": "...",
      "url": "...",
      "statusCode": 200,
      ...
    }
  }
}

Search 响应结构

{
  "success": true,
  "data": [
    {
      "url": "...",
      "title": "...",
      "description": "...",
      "markdown": "...",
      "score": 0.95
    }
  ]
}

最佳实践

优先使用 formats 参数控制输出：不需要的字段不请求，节省 API credits
Search 用于发现，Scrape 用于深入：先 Search 定位，再 Scrape 获取完整内容
Map + Crawl 组合：先用 Map 确认网站结构，再决定 Crawl 范围
提取结构化数据：使用 extract 参数配合 prompt，从页面中精确提取所需字段
超时处理：大页面或复杂网站建议设置 60-90 秒超时
API Key 安全：不要将 API Key 硬编码在脚本中，通过环境变量或配置传入

注意事项

Firecrawl 是付费 API（有免费额度），每次调用消耗 credits
Crawl 操作是异步的，需要轮询获取结果
某些网站可能有反爬机制，Firecrawl 内置了绕过策略但不保证 100% 成功
抓取结果中的 Markdown 可能包含占位符（如混淆的文本），这是目标网站的反爬措施