firecrawl-scraper

Firecrawl 抓取技能

触发条件与端点选择

根据用户意图选择 Firecrawl 端点：

• scrape：需要提取单个网页的内容（markdown、html、json、截图、pdf）
• crawl：需要抓取整个网站，并控制深度和筛选路径
• map：需要快速获取网站上的所有 URL 列表
• batch-scrape：需要并行抓取多个 URL
• crawl-status：提供抓取任务 ID 后，检查抓取进度／结果（可选 --wait）

推荐架构（主技能 + 子技能）

此技能采用两阶段架构：

1. 主技能（当前上下文）：理解用户问题 → 选择端点 → 组装 JSON 负载
2. 子技能（分叉上下文）：仅负责执行 HTTP 调用，避免浪费对话历史令牌

执行方法

使用 Task 工具调用 firecrawl-fetcher 子技能，并传入命令和 JSON（stdin）：

Task parameters:
- subagent_type: Bash
- description: "Call Firecrawl API"
- prompt: cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs <scrape|crawl|map|batch-scrape|crawl-status> [--wait]
  { ...payload... }
  JSON

负载示例

1) 抓取单个页面

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs scrape
{
  "url": "https://example.com",
  "formats": ["markdown", "links"],
  "onlyMainContent": true,
  "includeTags": [],
  "excludeTags": ["nav", "footer"],
  "waitFor": 0,
  "timeout": 30000
}
JSON

可用格式：

• "markdown"、"html"、"rawHtml"、"links"、"images"、"summary"
• {"type": "json", "prompt": "Extract product info", "schema": {...}}
• {"type": "screenshot", "fullPage": true, "quality": 85}

2) 使用操作抓取（页面交互）

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs scrape
{
  "url": "https://example.com",
  "formats": ["markdown"],
  "actions": [
    {"type": "wait", "milliseconds": 2000},
    {"type": "click", "selector": "#load-more"},
    {"type": "wait", "milliseconds": 1000},
    {"type": "scroll", "direction": "down", "amount": 500}
  ]
}
JSON

可用操作：

• wait、click、write、press、scroll、screenshot、scrape、executeJavascript

3) 解析 PDF

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs scrape
{
  "url": "https://example.com/document.pdf",
  "formats": ["markdown"],
  "parsers": ["pdf"]
}
JSON

4) 提取结构化 JSON

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs scrape
{
  "url": "https://example.com/product",
  "formats": [
    {
      "type": "json",
      "prompt": "Extract product information",
      "schema": {
        "type": "object",
        "properties": {
          "name": {"type": "string"},
          "price": {"type": "number"},
          "description": {"type": "string"}
        },
        "required": ["name", "price"]
      }
    }
  ]
}
JSON

5) 抓取整个网站

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs crawl
{
  "url": "https://docs.example.com",
  "formats": ["markdown"],
  "includePaths": ["^/docs/.*"],
  "excludePaths": ["^/blog/.*"],
  "maxDiscoveryDepth": 3,
  "limit": 100,
  "allowExternalLinks": false,
  "allowSubdomains": false
}
JSON

5.1) 抓取并等待完成

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs crawl --wait
{
  "url": "https://docs.example.com",
  "formats": ["markdown"],
  "limit": 100
}
JSON

6) 映射网站 URL

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs map
{
  "url": "https://example.com",
  "search": "documentation",
  "limit": 5000
}
JSON

7) 批量抓取多个 URL

cat <<'JSON' | node .claude/skills/firecrawl-scraper/firecrawl-api.cjs batch-scrape
{
  "urls": [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3"
  ],
  "formats": ["markdown"]
}
JSON

8) 检查抓取状态

node .claude/skills/firecrawl-scraper/firecrawl-api.cjs crawl-status <crawl-id>

等待完成：

node .claude/skills/firecrawl-scraper/firecrawl-api.cjs crawl-status <crawl-id> --wait

主要功能

格式

• markdown：清晰的 markdown 内容
• html：解析后的 HTML
• rawHtml：原始 HTML
• links：页面上的所有链接
• images：页面上的所有图片
• summary：AI 生成的摘要
• json：使用 schema 提取结构化数据
• screenshot：页面截图（PNG）

内容控制

• onlyMainContent：仅提取主要内容（默认值：true）
• includeTags：要包含的 CSS 选择器
• excludeTags：要排除的 CSS 选择器
• waitFor：抓取前的等待时间（ms）
• maxAge：缓存时长（默认值：48 小时）

操作（浏览器自动化）

• wait：等待指定时间
• click：按选择器点击元素
• write：在字段中输入文本
• press：按下键盘按键
• scroll：滚动页面
• executeJavascript：运行自定义 JS

抓取选项

• includePaths：要包含的正则表达式模式
• excludePaths：要排除的正则表达式模式
• maxDiscoveryDepth：最大抓取深度
• limit：抓取页面的最大数量
• allowExternalLinks：跟进外部链接
• allowSubdomains：跟进子域名

环境变量与 API 密钥

可通过以下两种方式配置 API 密钥（优先级：环境变量 > .env）：

1. 环境变量：FIRECRAWL_API_KEY
2. .env 文件：放置在 .claude/skills/firecrawl-scraper/.env，可从 .env.example 复制

响应格式

所有端点均返回 JSON，包含：

• success：表示是否成功的布尔值
• data：提取的内容（格式取决于端点）
• 对于 crawl：返回任务 ID，使用 crawl-status（或 GET /v2/crawl/{id}）检查状态