# https://github.com/firecrawl/firecrawl 项目说明书

生成时间：2026-05-11 04:15:16 UTC

## 目录

- [项目概览](#project-overview)
- [系统架构](#system-architecture)
- [API路由与版本控制](#api-routes)
- [抓取引擎](#scraping-engines)
- [搜索与爬取功能](#search-crawl)
- [数据提取系统](#extraction-system)
- [监控与Webhook](#monitoring-webhooks)
- [多语言SDK](#multi-language-sdks)
- [部署与基础设施](#deployment-infra)
- [开发指南](#development-guide)

<a id='project-overview'></a>

## 项目概览

### 相关页面

相关主题：[系统架构](#system-architecture), [多语言SDK](#multi-language-sdks)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/firecrawl/firecrawl/blob/main/README.md)
- [apps/python-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/python-sdk/README.md)
- [apps/js-sdk/firecrawl/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/js-sdk/firecrawl/README.md)
- [apps/java-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/java-sdk/README.md)
- [apps/ruby-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/ruby-sdk/README.md)
- [apps/dotnet-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/dotnet-sdk/README.md)
- [apps/rust-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/rust-sdk/README.md)
- [apps/php-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/php-sdk/README.md)
</details>

# 项目概览

## 项目简介

Firecrawl 是一个由 Mendable.ai 开发的开源网页抓取和爬虫平台，旨在将网站转换为可供大语言模型（LLM）使用的结构化数据。Firecrawl 提供从网站搜索、内容抓取、页面交互到智能代理的全栈解决方案，帮助开发者轻松获取互联网数据并用于 AI 应用开发。

项目采用多语言 SDK 架构设计，提供了 Python、Node.js、Java、Ruby、Go、.NET、Rust、PHP 等多种编程语言的官方 SDK，支持开发者使用熟悉的开发环境集成 Firecrawl 功能。资料来源：[README.md:1-50]()

## 核心功能模块

Firecrawl 平台提供四大核心功能模块，分别对应不同的网页数据采集场景：

### Search（搜索）

Search 模块支持对互联网进行自然语言搜索，返回与查询关键词相关的网页列表。每个搜索结果包含 URL、标题和页面摘要的 Markdown 格式内容，非常适合构建知识库或信息检索应用。资料来源：[README.md:45-60]()

### Scrape（抓取）

Scrape 是 Firecrawl 最核心的功能模块，用于从单个 URL 提取结构化数据。支持多种输出格式，包括 Markdown、HTML、JSON（通过 Schema 提取）、链接列表、截图等。开发者可以配置只提取主内容、设置等待时间、控制输出格式等参数。资料来源：[README.md:70-95]()

### Interact（交互）

Interact 模块支持基于抓取结果的浏览器自动化交互。用户可以先使用 Scrape 抓取页面，然后通过 AI 提示词或 JavaScript 代码与页面进行交互，如点击按钮、填写表单、搜索内容等操作。资料来源：[README.md:100-120]()

### Agent（智能代理）

Agent 模块是 Firecrawl 的高级功能，允许开发者使用自然语言描述目标，系统自动完成数据采集和整理。例如，开发者可以描述"查找某公司的创始人信息"，Agent 会自动规划搜索路径、抓取相关页面并提取结构化结果。资料来源：[apps/python-sdk/README.md:30-35]()

## 系统架构

### 整体架构图

```mermaid
graph TD
    subgraph 客户端层
        Python[Python SDK]
        NodeJS[Node.js SDK]
        Java[Java SDK]
        Ruby[Ruby SDK]
        Go[Go SDK]
        DotNet[.NET SDK]
        Rust[Rust SDK]
        PHP[PHP SDK]
        CLI[Firecrawl CLI]
        DirectAPI[直接 API 调用]
    end

    subgraph API 网关层
        Gateway[API Gateway]
        Auth[身份验证]
        RateLimit[限流控制]
    end

    subgraph 核心服务层
        ScrapeService[Scrape 服务]
        CrawlService[Crawl 服务]
        MapService[Map 服务]
        SearchService[Search 服务]
        AgentService[Agent 服务]
        InteractService[Interact 服务]
    end

    subgraph 数据处理层
        HTMLParser[HTML 解析器]
        MarkdownConverter[Markdown 转换]
        JSONExtractor[JSON Schema 提取]
        ScreenshotEngine[截图引擎]
        GoHTML2MD[Go HTML-to-MD 库]
    end

    subgraph 监控服务
        Monitor[监控服务]
        Notification[通知服务]
    end

    客户端层 --> API 网关层
    API 网关层 --> 核心服务层
    核心服务层 --> 数据处理层
    核心服务层 --> 监控服务
```

### API 端点概览

| 端点 | 方法 | 功能描述 | 异步支持 |
|------|------|----------|----------|
| `/v2/scrape` | POST | 抓取单个 URL 的内容 | 否 |
| `/v2/crawl` | POST | 启动网站爬虫任务 | 是（轮询） |
| `/v2/map` | POST | 发现网站所有 URL | 否 |
| `/v2/search` | POST | 互联网全文搜索 | 否 |
| `/v1/scrape` | POST | 旧版抓取接口 | 否 |

资料来源：[README.md:20-80]()

## 多语言 SDK 支持

Firecrawl 提供了丰富的官方 SDK，覆盖主流编程语言生态：

### SDK 功能对比

| SDK | 包名称 | 安装方式 | 版本 | 特殊功能 |
|-----|--------|----------|------|----------|
| Python | `firecrawl-py` | `pip install firecrawl-py` | 2.x | Agent、异步爬虫 |
| Node.js | `@mendable/firecrawl-js` | `npm install @mendable/firecrawl-js` | 最新 | Zod Schema 支持 |
| Java | `com.firecrawl:firecrawl-java` | Maven/Gradle | 1.1.1 | 构建器模式 |
| Ruby | `firecrawl-sdk` | `gem install firecrawl-sdk` | 1.0 | - |
| Go | `github.com/firecrawl/firecrawl-go-sdk` | `go get` | - | - |
| .NET | `firecrawl-sdk` | `dotnet add package firecrawl-sdk` | - | HttpClient 可定制 |
| Rust | `firecrawl` | Cargo.toml | 2.1.0 | 异步运行时 |
| PHP | `firecrawl/sdk` | Composer | - | Laravel Facade |

资料来源：[apps/python-sdk/README.md:1-20]()[apps/js-sdk/firecrawl/README.md:1-30]()[apps/java-sdk/README.md:1-20]()[apps/ruby-sdk/README.md:1-25]()[apps/dotnet-sdk/README.md:1-20]()[apps/rust-sdk/README.md:1-30]()[apps/php-sdk/README.md:1-20]()

### Python SDK 示例

```python
from firecrawl import Firecrawl
from firecrawl.types import ScrapeOptions

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

# 抓取单个页面
doc = firecrawl.scrape("https://firecrawl.dev", formats=["markdown"])
print(doc.markdown)

# 批量爬虫
docs = firecrawl.crawl("https://docs.firecrawl.dev", limit=50)
for doc in docs.data:
    print(doc.metadata.source_url)

# 使用 Agent
result = firecrawl.agent(prompt="查找 Stripe 公司的创始人")
print(result.data)
```

资料来源：[apps/python-sdk/README.md:15-45]()

### Node.js SDK 示例

```javascript
import Firecrawl from '@mendable/firecrawl-js';
import { z } from 'zod';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// 使用 Zod Schema 提取结构化数据
const schema = z.object({
  title: z.string(),
  price: z.number(),
});

const result = await app.extract({
  urls: ['https://example.com/product'],
  prompt: '提取产品名称和价格',
  schema,
});

console.log(result.data);
```

资料来源：[apps/js-sdk/firecrawl/README.md:40-60]()

## 高级功能

### 批量抓取（Batch Scrape）

批量抓取功能允许开发者一次性提交多个 URL 进行抓取，适合需要对多个页面进行数据采集的场景。系统会自动管理任务队列和并发控制。资料来源：[README.md:80-95]()

```python
job = app.batch_scrape([
    "https://firecrawl.dev",
    "https://docs.firecrawl.dev",
    "https://firecrawl.dev/pricing"
], formats=["markdown"])

for doc in job.data:
    print(doc.metadata.source_url)
```

### 文件解析（Parse）

Parse 功能支持上传本地文件（HTML、PDF、DOCX 等）并进行解析，无需通过 URL 抓取。该功能适用于处理本地文档或通过其他渠道获取的文件内容。资料来源：[apps/python-sdk/README.md:60-80]()

```python
doc = firecrawl.parse(
    b"<!DOCTYPE html><html><body><h1>Content</h1></body></html>",
    filename="upload.html",
    content_type="text/html",
    options=ParseOptions(formats=["markdown"]),
)
```

### JSON Schema 提取

通过 JSON Schema 定义数据结构，Firecrawl 可以自动从页面中提取符合模式的数据，返回结构化的 JSON 输出。资料来源：[apps/java-sdk/README.md:50-75]()

```java
JsonFormat jsonFmt = JsonFormat.builder()
    .prompt("提取产品名称和价格")
    .schema(Map.of(
        "type", "object",
        "properties", Map.of(
            "name", Map.of("type", "string"),
            "price", Map.of("type", "number")
        )
    ))
    .build();

Document doc = client.scrape("https://example.com/product",
    ScrapeOptions.builder()
        .formats(List.of(jsonFmt))
        .build());
```

### 网站地图（Map）

Map 功能快速发现网站上的所有页面 URL，支持基于关键词的智能搜索排序。返回结果包含每个 URL 的标题和描述信息。资料来源：[README.md:40-50]()

```python
result = app.map("https://firecrawl.dev", search="pricing")
# 返回与 "pricing" 相关的 URL 列表
```

## 配置选项

### ScrapeOptions 参数表

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `formats` | List[str] | ["markdown"] | 输出格式列表 |
| `only_main_content` | bool | false | 仅提取主体内容 |
| `wait_for` | int | 0 | 等待加载时间（毫秒） |
| `timeout` | int | 60000 | 请求超时（毫秒） |
| `remove_base64_images` | bool | true | 移除 Base64 图片 |
| `include_raw_html` | bool | false | 包含原始 HTML |
| `extractor_options` | dict | None | JSON 提取配置 |
| `actions` | List[dict] | None | 自动化操作列表 |

### CrawlOptions 参数表

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `limit` | int | None | 最大页面数量 |
| `scrape_options` | ScrapeOptions | None | 抓取配置 |
| `poll_interval` | int | 2 | 轮询间隔（秒） |
| `depth` | int | None | 爬虫深度限制 |
| `allow_dangerous` | bool | false | 允许危险操作 |

资料来源：[apps/python-sdk/README.md:40-65]()[apps/rust-sdk/README.md:30-60]()

## 集成生态

Firecrawl 与多个主流平台和工具深度集成：

### AI 工具集成

| 集成产品 | 说明 | 文档链接 |
|----------|------|----------|
| Firecrawl Skill | CLI 工具集成 | [文档](https://docs.firecrawl.dev/sdks/cli) |
| Firecrawl MCP | Model Context Protocol 服务器 | [GitHub](https://github.com/mendableai/firecrawl-mcp-server) |
| DeepSeek V3 Crawler | DeepSeek 模型驱动的爬虫 | [示例](../examples/deepseek-v3-crawler/README.md) |
| Gemini 2.5 Extractor | Gemini 模型数据提取 | [示例](../examples/gemini-2.5-web-extractor/README.md) |

### 平台集成

| 平台 | 说明 |
|------|------|
| Lovable | 可在 Lovable 应用中直接使用 Firecrawl |
| Zapier | 通过 Zapier 自动化工作流集成 |
| n8n | 支持 n8n 工作流自动化平台 |

资料来源：[README.md:120-140]()

## 环境配置

### API Key 配置

Firecrawl 支持两种 API Key 配置方式：

1. **环境变量配置**（推荐）：设置 `FIRECRAWL_API_KEY` 环境变量
2. **代码显式传入**：在客户端初始化时直接传入 API Key

### 常用环境变量

| 变量名 | 说明 | 示例 |
|--------|------|------|
| `FIRECRAWL_API_KEY` | API 密钥（必填） | `fc-xxxxxxxxxxxx` |
| `FIRECRAWL_API_URL` | 自托管实例 URL | `http://localhost:3002` |
| `FIRECRAWL_BACKOFF_FACTOR` | 重试退避因子 | `0.5` |

```bash
# Bash/Shell
export FIRECRAWL_API_KEY="fc-your-api-key"
export FIRECRAWL_API_URL="http://localhost:3002"
```

```csharp
// .NET
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com",
    httpClient: new HttpClient { Timeout = TimeSpan.FromSeconds(60) }
);
```

资料来源：[apps/dotnet-sdk/README.md:20-45]()[apps/php-sdk/README.md:25-40]()

## 工作流程示例

### 典型数据采集流程

```mermaid
graph LR
    A[确定目标网站] --> B[使用 Map 发现 URL]
    B --> C[评估 URL 相关性]
    C --> D[配置抓取参数]
    D --> E[执行批量抓取]
    E --> F[解析响应数据]
    F --> G[存储结构化数据]
```

### 交互式数据提取流程

```mermaid
graph TD
    A[Scrape 抓取页面] --> B[获取 scrapeId]
    B --> C[使用 Interact 交互]
    C --> D[执行 JS 代码或 AI 提示]
    D --> E[等待操作完成]
    E --> F[获取更新后的页面状态]
    F --> G[提取最终数据]
```

## 总结

Firecrawl 是一个功能全面的网页数据采集平台，通过统一 API 和多语言 SDK 为开发者提供了便捷的网页抓取、爬虫、搜索和智能代理能力。其设计理念是简化网页数据获取的复杂性，让开发者能够专注于业务逻辑而非底层实现。无论是构建知识库、训练 AI 模型还是自动化数据采集任务，Firecrawl 都能提供可靠的解决方案。

---

<a id='system-architecture'></a>

## 系统架构

### 相关页面

相关主题：[项目概览](#project-overview), [API路由与版本控制](#api-routes), [部署与基础设施](#deployment-infra)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/api/src/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/index.ts)
- [apps/api/src/harness.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/harness.ts)
- [apps/api/native/src/lib.rs](https://github.com/firecrawl/firecrawl/blob/main/apps/api/native/src/lib.rs)
- [apps/api/src/services/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/index.ts)
- [apps/api/src/services/queue-service.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/queue-service.ts)
</details>

# 系统架构

Firecrawl 是一个现代化的网页抓取和数据提取平台，采用微服务化的 SDK 架构设计。系统由中央 API 服务器、多语言 SDK 客户端、异步任务队列服务以及原生性能优化库组成，旨在为 AI 系统提供搜索、抓取和网页交互的完整解决方案。

## 整体架构概览

Firecrawl 采用典型的客户端-服务器架构，API 服务器托管在 `api.firecrawl.dev`，通过 RESTful API 与多语言 SDK 进行通信。

```mermaid
graph TD
    A[多语言 SDK 客户端] --> B[Firecrawl API 服务器]
    B --> C[队列服务 Queue Service]
    B --> D[抓取引擎 Scraping Engines]
    B --> E[原生库 Native Libraries]
    C --> F[异步任务处理器]
    D --> G[网站内容]
    E --> H[HTML 转 Markdown]
```

## 核心组件

### API 服务器

API 服务器是整个系统的核心枢纽，基于 Node.js/TypeScript 构建，负责处理所有客户端请求并进行任务调度。

| 组件 | 功能 | 源码位置 |
|------|------|----------|
| 路由控制器 | 处理 API 端点路由 | apps/api/src/index.ts |
| 服务初始化 | 加载和管理各类服务模块 | apps/api/src/services/index.ts |
| 测试工具 | 开发环境验证 | apps/api/src/harness.ts |

### 队列服务

队列服务负责管理异步任务的调度和执行，确保长时间运行的任务不会阻塞主请求线程。

```typescript
// apps/api/src/services/queue-service.ts 核心职责
// - 任务入队和出队管理
// - 任务状态追踪
// - 优先级调度
// - 失败重试机制
```

队列服务支持异步爬取、批量抓取等长时间运行的操作，客户端可以通过轮询任务 ID 来获取执行结果。

### 原生性能库

为了优化核心性能，Firecrawl 集成了原生语言库：

| 库名称 | 语言 | 用途 |
|--------|------|------|
| go-html-to-md | Go | HTML 到 Markdown 的高性能转换 |
| Rust SDK | Rust | 底层高性能操作 |

```bash
# go-html-to-md 构建命令
cd apps/api/sharedLibs/go-html-to-md
go build -o <OUTPUT> -buildmode=c-shared html-to-markdown.go
```

输出文件根据操作系统不同：
- Windows: `html-to-markdown.dll`
- Linux: `libhtml-to-markdown.so`
- macOS: `libhtml-to-markdown.dylib`

## SDK 多语言架构

Firecrawl 提供统一的 SDK 体验，覆盖主流编程语言：

```mermaid
graph LR
    A[统一 API 接口] --> B[Python SDK]
    A --> C[Node.js SDK]
    A --> D[Ruby SDK]
    A --> E[Java SDK]
    A --> F[.NET SDK]
    A --> G[Rust SDK]
    A --> H[PHP SDK]
```

| SDK | 包名/依赖 | 文档位置 |
|-----|-----------|----------|
| Python | `firecrawl-py` | apps/python-sdk/README.md |
| Node.js | `@mendable/firecrawl-js` | apps/js-sdk/README.md |
| Ruby | `firecrawl-sdk` | apps/ruby-sdk/README.md |
| Java | `com.firecrawl:firecrawl-java` | apps/java-sdk/README.md |
| .NET | `firecrawl-sdk` | apps/dotnet-sdk/README.md |
| Rust | `firecrawl` | apps/rust-sdk/README.md |
| PHP | `firecrawl-sdk` | apps/php-sdk/README.md |

## 功能模块架构

### 核心功能

```mermaid
graph TD
    subgraph Firecrawl 核心功能
        S[Search 搜索] --> Scr[Scrape 抓取]
        Scr --> Cr[Crawl 爬取]
        Cr --> M[Map 站点地图]
        M --> Ex[Extract 提取]
        Ex --> I[Interact 交互]
        I --> Ag[Agent 智能代理]
    end
```

### 抓取引擎

系统支持多种专业化的抓取引擎，针对不同数据源进行优化：

| 引擎 | 用途 | 源码示例 |
|------|------|----------|
| Wikipedia 引擎 | 维基百科结构化数据 | apps/api/src/scraper/scrapeURL/engines/wikipedia/index.ts |
| 通用引擎 | 标准网页抓取 | 默认引擎 |

### 数据提取服务

Firecrawl 提供基于 AI 的数据提取能力：

```typescript
// apps/api/src/lib/extract/fire-0/extraction-service-f0.ts
// - Schema 验证
// - 单实体/多实体提取
// - 结果混合与去重
```

## 监控与通知系统

系统包含完整的监控通知机制：

```typescript
// apps/api/src/services/notification/monitoring_email.ts
// - 变更检测摘要邮件
// - 新增页面通知
// - 移除页面告警
// - 错误统计
```

监控邮件功能支持定期发送网站变更报告，包括新增、移除、变更的页面数量统计。

## 认证与配置

### API 密钥管理

Firecrawl 支持多种 API 密钥配置方式：

| 配置方式 | 优先级 | 示例 |
|----------|--------|------|
| 构造函数参数 | 最高 | `Client("fc-your-api-key")` |
| 环境变量 | 次高 | `FIRECRAWL_API_KEY` |
| 配置文件 | 最低 | 各 SDK 特定配置 |

### 客户端初始化示例

```python
# Python SDK
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")
```

```java
// Java SDK
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();
```

```rust
// Rust SDK
use firecrawl::{Client, ScrapeOptions, Format, CrawlOptions};
let client = Client::new("fc-YOUR_API_KEY")?;
```

## 数据流架构

```mermaid
sequenceDiagram
    participant C as 客户端 SDK
    participant A as API 服务器
    participant Q as 队列服务
    participant E as 抓取引擎
    participant N as 原生库
    
    C->>A: 发起抓取请求
    A->>Q: 入队异步任务
    A-->>C: 返回任务 ID
    Q->>E: 调度抓取任务
    E->>N: HTML 内容处理
    N-->>E: Markdown 输出
    E-->>Q: 任务完成
    C->>A: 轮询任务状态
    A-->>C: 返回抓取结果
```

## 安全与数据处理

### HTML 转义处理

系统对外部数据实施严格的 HTML 转义，防止 XSS 等安全问题：

```typescript
// apps/api/src/scraper/scrapeURL/engines/wikipedia/index.ts
function escapeHtml(str: string): string {
  return str
    .replace(/&/g, "&amp;")
    .replace(/</g, "&lt;")
    .replace(/>/g, "&gt;")
    .replace(/"/g, "&quot;");
}
```

### 内容过滤

系统内置内容安全过滤机制，包括：
- 仅提取主体内容选项
- 可配置的等待时间
- 格式选择（Markdown、HTML、JSON 等）

## 扩展与集成

### 第三方集成

| 平台 | 集成方式 | 说明 |
|------|----------|------|
| Mendable | Firecrawl Skill | AI 技能集成 |
| Lovalbe | 内置支持 | 无代码平台集成 |
| Zapier | App Integration | 自动化工作流 |
| n8n | Workflow Nodes | 自托管自动化 |
| Gemini | 示例项目 | AI 模型集成 |
| DeepSeek | 示例项目 | 大语言模型爬虫 |

### 品牌标识处理

系统包含品牌识别模块，能够从抓取页面中提取品牌名称和 Logo 信息。

## 技术栈总结

| 层级 | 技术选型 |
|------|----------|
| API 服务器 | Node.js / TypeScript / Express |
| 原生性能库 | Go (HTML→Markdown), Rust |
| 队列系统 | 基于 TypeScript 的异步队列 |
| SDK 生态 | Python, Node.js, Ruby, Java, .NET, Rust, PHP |
| 部署方式 | 云原生，支持自托管 |

该架构设计遵循松耦合原则，各组件通过明确定义的接口进行通信，便于独立扩展和维护。

---

<a id='api-routes'></a>

## API路由与版本控制

### 相关页面

相关主题：[系统架构](#system-architecture), [抓取引擎](#scraping-engines), [搜索与爬取功能](#search-crawl)

根据上下文，我无法找到用户指定的路由源码文件。以下是现有文档中关于 API 版本的相关信息：

# API 路由与版本控制

由于指定的路由源文件 (`apps/api/src/routes/v0.ts`, `apps/api/src/routes/v1.ts`, `apps/api/src/routes/v2.ts`, `apps/api/src/routes/admin.ts`, `apps/api/openapi.json`) 未出现在当前检索结果中，我无法提供详细的源码级分析。

## 现有文档中的 API 版本信息

根据主 README.md，以下是 v2 API 端点：

| API 功能 | 端点 | 方法 | 资料来源 |
|---------|------|------|---------|
| 搜索 | `/v2/search` | POST | README.md |
| 抓取 | `/v2/scrape` | POST | README.md |
| 映射网站 | `/v2/map` | POST | README.md |
| 批量抓取 | `/v2/batch` | POST | README.md |

## SDK 支持情况

| SDK 语言 | 仓库路径 | 支持版本 |
|---------|---------|---------|
| Python | apps/python-sdk | v1, v2 |
| Node.js | apps/js-sdk | v1, v2 |
| Rust | apps/rust-sdk | v1, v2 |
| Go | apps/go-sdk | v1, v2 |
| Ruby | apps/ruby-sdk | v1, v2 |
| Java | apps/java-sdk | v1, v2 |
| .NET | apps/dot-net-sdk | v1, v2 |
| PHP | apps/php-sdk | v1, v2 |

## 建议

要生成完整的 API 路由与版本控制 Wiki 页面，需要检索以下文件：
- `apps/api/src/routes/v0.ts`
- `apps/api/src/routes/v1.ts`
- `apps/api/src/routes/v2.ts`
- `apps/api/src/routes/admin.ts`
- `apps/api/openapi.json`

请提供这些文件的实际内容以继续生成 Wiki 页面。

---

<a id='scraping-engines'></a>

## 抓取引擎

### 相关页面

相关主题：[API路由与版本控制](#api-routes), [搜索与爬取功能](#search-crawl), [数据提取系统](#extraction-system)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/api/src/scraper/scrapeURL/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/index.ts)
- [apps/api/src/scraper/scrapeURL/engines/fetch/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/engines/fetch/index.ts)
- [apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts)
- [apps/api/src/scraper/scrapeURL/engines/playwright/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/engines/playwright/index.ts)
- [apps/api/src/scraper/scrapeURL/engines/pdf/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/engines/pdf/index.ts)
- [apps/api/src/scraper/scrapeURL/engines/document/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/engines/document/index.ts)
- [apps/api/native/src/document/providers/factory.rs](https://github.com/firecrawl/firecrawl/blob/main/apps/api/native/src/document/providers/factory.rs)
</details>

# 抓取引擎

## 概述

抓取引擎（Scrape Engine）是 Firecrawl 系统中负责实际执行网页内容抓取的核心组件模块。它位于 `apps/api/src/scraper/scrapeURL/engines/` 目录下，采用多引擎架构设计，根据不同的内容类型和抓取需求，智能选择最适合的底层抓取实现。

Firecrawl 的抓取引擎设计遵循**策略模式（Strategy Pattern）**，每个引擎实现相同的接口契约，但采用不同的技术栈来处理特定类型的内容。这种设计使得系统能够灵活应对静态网页、动态渲染页面、PDF 文档、Office 文档等多种内容源的抓取需求。

抓取引擎与上层的 `scrapeURL/index.ts` 主模块协同工作，主模块负责接收抓取请求、解析配置参数、路由到合适的引擎，并最终汇总各引擎的输出结果。资料来源：[apps/api/src/scraper/scrapeURL/index.ts]()

## 架构设计

### 整体架构图

```mermaid
graph TD
    A[scrapeURL 主模块] --> B[引擎选择器]
    B --> C[Fetch 引擎]
    B --> D[Fire-Engine 引擎]
    B --> E[Playwright 引擎]
    B --> F[PDF 引擎]
    B --> G[Document 引擎]
    
    C --> H[HTTP 请求处理]
    D --> I[浏览器自动化]
    E --> J[Chromium 实例]
    F --> K[PDF 解析库]
    G --> L[文档解析器]
    
    H --> M[HTML 响应]
    I --> N[渲染后 DOM]
    J --> N
    K --> O[PDF 文本/元数据]
    L --> P[文档内容]
```

### 引擎类型与职责

| 引擎名称 | 技术实现 | 适用场景 | 内容类型 |
|---------|---------|---------|---------|
| Fetch | Node.js 原生 HTTP 请求 | 静态页面、API 响应 | HTML、JSON |
| Fire-Engine | 浏览器自动化框架 | 动态渲染页面 | JavaScript 渲染后的 DOM |
| Playwright | Chromium 实例控制 | 复杂交互页面 | 完整网页快照 |
| PDF | PDF 解析库 | PDF 文档 | PDF 文本、元数据 |
| Document | 文档解析器 | Office 文档 | DOCX、XLSX、PPTX |

## 核心引擎详解

### Fetch 引擎

Fetch 引擎是抓取引擎家族中最轻量的实现，位于 `apps/api/src/scraper/scrapeURL/engines/fetch/index.ts`。它直接使用 Node.js 原生的 HTTP/HTTPS 模块发起请求，适用于静态网页和 API 接口的数据抓取。

Fetch 引擎的主要特点包括：

- **零外部依赖**：不依赖 Puppeteer、Playwright 等重型库
- **高性能**：异步 I/O 操作，支持高并发请求
- **可配置性**：支持自定义请求头、超时设置、代理配置
- **Cookie 处理**：内置 Cookie 管理和会话保持

该引擎特别适合抓取不依赖 JavaScript 渲染的静态内容，如博客文章、新闻页面、产品列表页等。对于需要登录认证的网站，Fetch 引擎支持通过 Cookie 或 Bearer Token 进行身份验证。

### Fire-Engine 引擎

Fire-Engine 引擎是 Firecrawl 自研的浏览器自动化引擎，位于 `apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts`。它提供了介于轻量级 Fetch 和完整浏览器自动化之间的抓取能力。

Fire-Engine 的核心优势在于：

- **轻量级浏览器**：相比完整的 Chromium 实例，占用资源更少
- **JavaScript 渲染**：支持执行页面内的 JavaScript 代码
- **DOM 操作**：提供点击、滚动、输入等交互能力
- **截图功能**：支持页面截图和元素截图

该引擎适用于需要部分 JavaScript 渲染但不需要完整浏览器环境的场景，例如单页应用（SPA）的初始内容抓取、无限滚动列表的加载等。

### Playwright 引擎

Playwright 引擎是 Firecrawl 中最强大的抓取引擎，位于 `apps/api/src/scraper/scrapeURL/engines/playwright/index.ts`。它基于 Microsoft 的 Playwright 框架，提供完整的浏览器自动化能力。

Playwright 引擎的核心特性：

- **多浏览器支持**：Chromium、Firefox、WebKit
- **完整渲染**：执行所有 JavaScript，包括框架级别的代码
- **网络拦截**：支持请求/响应拦截，可修改网络流量
- **元素定位**：支持 CSS 选择器、XPath、文本定位
- **等待策略**：智能等待元素出现、网络空闲等条件

对于需要模拟用户行为（如登录、表单填写、点击按钮）的复杂抓取场景，Playwright 引擎是最佳选择。它还支持无头模式（headless）和有头模式（headed），可根据调试或生产环境灵活切换。

### PDF 引擎

PDF 引擎专门用于处理 PDF 文档的抓取和解析，位于 `apps/api/src/scraper/scrapeURL/engines/pdf/index.ts`。

PDF 引擎支持的功能：

- **直接下载**：从 URL 下载 PDF 文件
- **文本提取**：从 PDF 中提取可搜索的文本内容
- **元数据读取**：获取 PDF 的标题、作者、创建日期等元数据
- **页面拆分**：支持按页面维度提取内容
- **加密处理**：处理有密码保护的 PDF 文件

该引擎在处理学术论文、报告、合同等 PDF 格式内容时表现出色。结合 Firecrawl 的 Map 功能，可以自动发现网站上的 PDF 资源并进行批量抓取。

### Document 引擎

Document 引擎用于处理 Office 格式的文档，位于 `apps/api/src/scraper/scrapeURL/engines/document/index.ts`。它与后端原生模块 `apps/api/native/src/document/providers/factory.rs` 协同工作。

Document 引擎支持的文档格式：

| 格式 | MIME 类型 | 提取内容 |
|-----|----------|---------|
| DOCX | application/vnd.openxmlformats-officedocument.wordprocessingml.document | 文本、段落、表格、列表 |
| XLSX | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | 表格数据、公式 |
| PPTX | application/vnd.openxmlformats-officedocument.presentationml.presentation | 幻灯片文本、备注 |

Document 引擎的核心优势在于其原生实现方式。通过 Rust 编写的底层解析器（位于 `apps/api/native/src/document/providers/factory.rs`），能够高效处理大文件和复杂结构的 Office 文档，同时保证内存使用的安全性。

### 原生文档工厂

`apps/api/native/src/document/providers/factory.rs` 是 Rust 原生模块中的核心组件，负责创建和管理各种文档格式的解析器实例。

```mermaid
graph LR
    A[Document Request] --> B[Factory]
    B --> C{DocType Detection}
    C -->|DOCX| D[DocxParser]
    C -->|XLSX| E[XlsxParser]
    C -->|PDF| F[PdfParser]
    C -->|Unknown| G[Error Handler]
    
    D --> H[Structured Output]
    E --> H
    F --> H
```

工厂模式的应用确保了：

- **类型安全**：编译时保证所有支持的文档类型都被处理
- **可扩展性**：新增文档格式只需实现对应的解析 trait
- **性能优化**：根据文档类型预分配内存，减少运行时开销

## 工作流程

### 抓取请求处理流程

```mermaid
sequenceDiagram
    participant Client as 客户端
    participant Main as scrapeURL 主模块
    participant Router as 引擎路由器
    participant Engine as 选中的抓取引擎
    participant Output as 结果处理器
    
    Client->>Main: 发送抓取请求 (URL, Options)
    Main->>Main: 验证 URL 和参数
    Main->>Router: 请求引擎选择
    Router->>Router: Content-Type 检测
    Router->>Engine: 路由到合适引擎
    Engine->>Engine: 执行抓取逻辑
    Engine-->>Output: 返回原始内容
    Output->>Output: 格式化与清洗
    Output-->>Main: 结构化结果
    Main-->>Client: 返回 Document 对象
```

### 引擎选择策略

抓取引擎根据以下因素自动选择最合适的引擎：

1. **URL 扩展名检测**：优先根据 URL 末尾的文件扩展名判断内容类型
2. **Content-Type 响应头**：HTTP 响应头中的 Content-Type 字段
3. **配置优先级**：用户通过 `ScrapeOptions` 明确指定的引擎类型
4. **降级策略**：主引擎失败时自动降级到备选引擎

## 配置选项

抓取引擎通过 `ScrapeOptions` 对象接收配置参数：

| 参数名 | 类型 | 默认值 | 说明 |
|-------|------|-------|------|
| formats | string[] | ["markdown"] | 输出格式列表 |
| onlyMainContent | boolean | false | 仅提取主体内容 |
| waitFor | number | 0 | 等待渲染的毫秒数 |
| timeout | number | 30000 | 请求超时（毫秒） |
| engine | string | "auto" | 强制指定引擎类型 |
| actions | Action[] | [] | 浏览器自动化动作序列 |

## SDK 集成

各语言 SDK 通过统一的接口调用抓取引擎，以 Python SDK 为例：

```python
from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

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

# 基础抓取（自动选择引擎）
doc = firecrawl.scrape('https://example.com', formats=['markdown'])

# 指定引擎抓取
doc = firecrawl.scrape(
    'https://example.com',
    formats=['markdown', 'html'],
    options=ScrapeOptions(
        engine='playwright',
        wait_for=3000
    )
)
```

## 错误处理机制

抓取引擎实现了多层次的错误处理策略：

| 错误类型 | 处理策略 | 降级引擎 |
|---------|---------|---------|
| 网络超时 | 重试 3 次，指数退避 | Playwright |
| 渲染失败 | 降级到 Fetch 引擎 | Fetch |
| 解析错误 | 返回原始内容，标记警告 | - |
| 资源不存在 | 返回 404 错误 | - |
| 认证失败 | 返回 401 错误 | - |

## 性能优化

### 并发控制

抓取引擎内置了并发控制机制：

- **全局并发限制**：防止对目标服务器造成过大压力
- **域名级限速**：基于域名的请求速率控制
- **连接池复用**：减少 TCP 连接建立开销

### 缓存策略

- **304 响应处理**：正确处理 HTTP 条件请求
- **ETag/Last-Modified**：支持服务端缓存验证
- **本地缓存**：对重复请求返回缓存结果

## 安全考量

抓取引擎在设计时充分考虑了安全因素：

- **请求来源伪装**：模拟真实浏览器请求头
- **反爬虫规避**：内置常用反爬虫策略应对
- **敏感信息过滤**：自动过滤密码、API Key 等敏感数据
- **沙箱执行**：浏览器引擎在隔离环境中运行

## 扩展开发指南

如需添加新的抓取引擎，可按以下步骤扩展：

1. 在 `engines/` 目录下创建新的引擎文件夹
2. 实现统一的引擎接口 `BaseEngine`
3. 在引擎路由器中注册新引擎
4. 添加对应的配置选项处理逻辑
5. 编写单元测试和集成测试

## 相关资源

- [Firecrawl API 文档](https://docs.firecrawl.dev)
- [Python SDK 文档](../python-sdk/README.md)
- [Node.js SDK 文档](../js-sdk/firecrawl/README.md)
- [抓取最佳实践指南](https://docs.firecrawl.dev/guides)

---

<a id='search-crawl'></a>

## 搜索与爬取功能

### 相关页面

相关主题：[抓取引擎](#scraping-engines), [数据提取系统](#extraction-system), [监控与Webhook](#monitoring-webhooks)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/api/src/search/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/search/index.ts)
- [apps/api/src/search/execute.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/search/execute.ts)
- [apps/api/src/search/fireEngine.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/search/fireEngine.ts)
- [apps/api/src/search/searxng.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/search/searxng.ts)
- [apps/api/src/scraper/WebScraper/crawler.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/WebScraper/crawler.ts)
- [apps/api/src/scraper/WebScraper/sitemap.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/WebScraper/sitemap.ts)
- [apps/api/src/scraper/crawler/sitemap.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/crawler/sitemap.ts)
</details>

# 搜索与爬取功能

## 概述

Firecrawl 的搜索与爬取功能是平台的核心能力，为 AI 系统提供网页搜索、抓取和交互能力。搜索功能允许用户在整个网络中查找信息，而爬取功能则支持对特定网站的深度遍历和数据提取。 资料来源：[README.md](https://github.com/firecrawl/firecrawl/blob/main/README.md)

## 架构设计

### 核心模块关系

```mermaid
graph TD
    A[API 入口] --> B[搜索模块 search/]
    A --> C[爬取模块 scraper/]
    B --> D[Fire Engine]
    B --> E[SearXNG 集成]
    C --> F[WebScraper]
    C --> G[Crawler]
    F --> H[Sitemap 解析]
    G --> H
    D --> I[搜索结果]
    H --> J[爬取结果]
```

### 搜索子系统架构

搜索功能通过多层抽象实现：

| 组件 | 文件路径 | 职责 |
|------|----------|------|
| 搜索入口 | `apps/api/src/search/index.ts` | 处理 API 请求分发和参数验证 |
| 执行引擎 | `apps/api/src/search/execute.ts` | 协调搜索执行流程 |
| Fire Engine | `apps/api/src/search/fireEngine.ts` | 自定义搜索引擎实现 |
| SearXNG 集成 | `apps/api/src/search/searxng.ts` | 开源搜索引擎后端适配 |

## 搜索功能详解

### 功能特性

搜索功能支持以下核心能力：

- **网络搜索**：在互联网上查找相关信息
- **结果排序**：按相关性对结果进行排序
- **数量限制**：支持限制返回结果数量
- **来源控制**：可指定搜索结果来源 资料来源：[README.md:45-50](https://github.com/firecrawl/firecrawl/blob/main/README.md)

### API 端点

```
POST https://api.firecrawl.dev/v2/search
```

**请求头**：

| 参数 | 说明 | 必填 |
|------|------|------|
| Authorization | Bearer token 认证 | 是 |
| Content-Type | application/json | 是 |

**请求体**：

| 字段 | 类型 | 说明 |
|------|------|------|
| query | string | 搜索查询关键词 |
| limit | number | 返回结果数量限制 |

### 响应格式

```json
{
  "data": [
    {
      "url": "https://firecrawl.dev",
      "title": "Firecrawl",
      "markdown": "Turn websites into..."
    }
  ]
}
```

## 爬取功能详解

### 爬取类型

Firecrawl 支持两种主要的网站爬取方式：

| 爬取类型 | 说明 | 适用场景 |
|----------|------|----------|
| **sitemap 爬取** | 通过解析网站的 sitemap.xml 发现页面 | 静态网站、结构化站点 |
| **智能爬取** | 通过模拟浏览器行为遍历页面 | JavaScript 渲染页面、动态内容 |

### Sitemap 解析模块

Sitemap 解析是爬取功能的基础组件：

| 文件 | 职责 |
|------|------|
| `apps/api/src/scraper/WebScraper/sitemap.ts` | WebScraper 场景下的 sitemap 解析 |
| `apps/api/src/scraper/crawler/sitemap.ts` | 独立爬虫场景下的 sitemap 解析 |

### 核心爬取流程

```mermaid
graph TD
    A[开始爬取] --> B{选择爬取模式}
    B -->|Sitemap| C[解析 sitemap.xml]
    B -->|智能爬取| D[启动浏览器实例]
    C --> E[提取 URL 列表]
    D --> F[遍历页面链接]
    E --> G[过滤有效链接]
    F --> G
    G --> H[抓取页面内容]
    H --> I[提取结构化数据]
    I --> J[返回结果]
```

### 爬取配置参数

```python
from firecrawl import Firecrawl

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

crawl_status = firecrawl.crawl(
    'https://firecrawl.dev', 
    limit=100, 
    scrape_options=ScrapeOptions(formats=['markdown', 'html']),
    poll_interval=30
)
```

| 参数 | 类型 | 说明 |
|------|------|------|
| limit | number | 最大抓取页面数量 |
| scrape_options | ScrapeOptions | 抓取选项配置 |
| poll_interval | number | 异步轮询间隔（秒） |
| exclude_paths | string[] | 需要排除的路径 |

## SDK 实现

### Python SDK

```python
from firecrawl import Firecrawl

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

# 搜索
results = app.search("best AI data tools 2024", limit=10)

# 爬取网站
docs = app.crawl("https://docs.firecrawl.dev", limit=50)
for doc in docs.data:
    print(doc.metadata.source_url, doc.markdown[:100])
```

### Node.js SDK

```javascript
import Firecrawl from '@mendable/firecrawl-js';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// 搜索
const results = await app.search('best AI data tools 2024', { limit: 10 });

// 爬取
const docs = await app.crawl('https://docs.firecrawl.dev', { 
    limit: 50,
    scrapeOptions: { formats: ['markdown', 'html'] }
});
```

### Java SDK

```java
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();

// 爬取
CrawlResponse response = client.crawl("https://example.com", 
    CrawlOptions.builder()
        .limit(50)
        .build());

for (Page page : response.getData()) {
    System.out.println(page.getMetadata().get("sourceURL"));
}
```

## 数据模型

### 搜索结果模型

| 字段 | 类型 | 说明 |
|------|------|------|
| url | string | 页面 URL |
| title | string | 页面标题 |
| description | string | 页面描述 |
| markdown | string | 页面内容（Markdown 格式） |

### 爬取结果模型

| 字段 | 类型 | 说明 |
|------|------|------|
| data | Page[] | 抓取的页面列表 |
| status | string | 爬取状态 |
| credits_used | number | 消耗的 credits |

### Page 模型

| 字段 | 类型 | 说明 |
|------|------|------|
| metadata | Record | 页面元数据 |
| markdown | string | Markdown 格式内容 |
| html | string | 原始 HTML |
| screenshot | string | 页面截图（Base64） |

## 配置选项

### ScrapeOptions 配置

| 选项 | 类型 | 说明 |
|------|------|------|
| formats | string[] | 输出格式：markdown、html、json |
| only_main_content | boolean | 仅提取主体内容 |
| wait_for | number | 等待渲染时间（毫秒） |
| location | LocationConfig | 地理位置配置 |

### CrawlOptions 配置

| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| limit | number | 100 | 最大页面数 |
| exclude_paths | string[] | [] | 排除路径 |
| include_paths | string[] | [] | 包含路径 |
| max_depth | number | 10 | 最大递归深度 |

## 异步操作处理

### 异步爬取流程

```mermaid
sequenceDiagram
    participant Client
    participant API
    participant Crawler
    participant Storage
    
    Client->>API: 发起爬取请求
    API->>Crawler: 启动爬取任务
    API-->>Client: 返回 Job ID
    loop 轮询状态
        Client->>API: 查询爬取状态
        API->>Crawler: 获取进度
        Crawler-->>API: 返回状态
        API-->>Client: 返回状态
    end
    Crawler->>Storage: 保存结果
    Client->>API: 获取完整结果
    API->>Storage: 读取结果
    Storage-->>API: 返回数据
    API-->>Client: 返回完整数据
```

### 异步爬取示例

```rust
// Rust SDK 异步爬取
let crawl_id = app.crawl_url_async("https://mendable.ai", None).await?.id;

// 检查爬取状态
let status = app.check_crawl_status(crawl_id).await?;

if status.status == CrawlStatusTypes::Completed {
    println!("爬取完成: {:#?}", status.data);
}
```

## 错误处理

| 错误类型 | 说明 | 处理建议 |
|----------|------|----------|
| TIMEOUT | 请求超时 | 增加超时时间或减少页面数量 |
| RATE_LIMIT | 请求频率超限 | 使用轮询间隔或降低请求频率 |
| INVALID_URL | URL 格式错误 | 检查 URL 格式是否正确 |
| ACCESS_DENIED | 访问被拒绝 | 网站可能禁止爬取 |

## 最佳实践

### 搜索优化

1. **精确查询**：使用具体关键词提高搜索准确性
2. **限制数量**：设置合理的 limit 值避免资源浪费
3. **结果缓存**：考虑对频繁查询的结果进行缓存

### 爬取优化

1. **路径过滤**：使用 exclude_paths 排除无关页面
2. **深度控制**：合理设置 max_depth 避免过度爬取
3. **格式选择**：根据需求选择合适的输出格式
4. **轮询间隔**：使用合适的 poll_interval 减少 API 调用

## 相关资源

- Python SDK 文档：[apps/python-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/python-sdk/README.md)
- Node.js SDK 文档：[apps/js-sdk/firecrawl/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/js-sdk/firecrawl/README.md)
- Java SDK 文档：[apps/java-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/java-sdk/README.md)
- Go SDK 文档：[apps/go-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/go-sdk/README.md)

---

<a id='extraction-system'></a>

## 数据提取系统

### 相关页面

相关主题：[抓取引擎](#scraping-engines), [搜索与爬取功能](#search-crawl), [监控与Webhook](#monitoring-webhooks)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/api/src/lib/extract/extraction-service.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/extraction-service.ts)
- [apps/api/src/lib/extract/build-document.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/build-document.ts)
- [apps/api/src/lib/extract/build-prompts.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/build-prompts.ts)
- [apps/api/src/lib/extract/completions/analyzeSchemaAndPrompt.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/completions/analyzeSchemaAndPrompt.ts)
- [apps/api/src/lib/extract/completions/batchExtract.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/completions/batchExtract.ts)
- [apps/api/src/lib/extract/completions/singleAnswer.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/completions/singleAnswer.ts)
- [apps/api/src/lib/extract/reranker.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/extract/reranker.ts)
- [apps/api/src/services/extract-queue.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/extract-queue.ts)
- [apps/api/src/services/extract-worker.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/extract-worker.ts)
</details>

# 数据提取系统

## 系统概述

数据提取系统（Extract System）是Firecrawl平台的核心组件之一，负责从网页内容中提取结构化数据。该系统支持JSON Schema定义的数据提取，通过大语言模型（LLM）将非结构化的网页内容转换为符合预定义模式的高质量结构化数据。

### 核心能力

| 能力 | 描述 |
|------|------|
| 单URL提取 | 从单个网页提取结构化数据 |
| 批量提取 | 一次处理多个URL，提高效率 |
| Schema验证 | 使用JSON Schema验证输出数据 |
| 智能提示词 | 自动分析和优化提取提示词 |
| 重排序 | 对提取结果进行相关性排序 |

资料来源：[apps/api/src/lib/extract/extraction-service.ts]()

## 系统架构

```mermaid
graph TD
    A[API请求] --> B[提取队列 extract-queue]
    B --> C[提取Worker extract-worker]
    C --> D[提取服务 ExtractionService]
    D --> E[构建文档 build-document]
    D --> F[构建提示 build-prompts]
    E --> G[完成处理 completions]
    F --> G
    G --> H[singleAnswer]
    G --> I[batchExtract]
    G --> J[analyzeSchemaAndPrompt]
    H --> K[重排序 reranker]
    I --> K
    J --> F
    K --> L[返回结构化数据]
```

### 核心组件

| 组件 | 文件路径 | 职责 |
|------|----------|------|
| 提取服务 | extraction-service.ts | 核心提取逻辑编排 |
| 文档构建 | build-document.ts | 构建提取结果文档 |
| 提示词构建 | build-prompts.ts | 生成LLM提示词 |
| 单答案处理 | singleAnswer.ts | 处理单个URL提取 |
| 批量提取 | batchExtract.ts | 处理多URL批量提取 |
| Schema分析 | analyzeSchemaAndPrompt.ts | 分析schema并优化提示词 |
| 重排序器 | reranker.ts | 结果相关性排序 |

资料来源：[apps/api/src/lib/extract/extraction-service.ts]()

## 工作流程

### 整体处理流程

```mermaid
graph LR
    A1[接收请求] --> B1[入队到extract-queue]
    B1 --> C1[Worker获取任务]
    C1 --> D1[调用ExtractionService]
    D1 --> E1[构建提示词]
    E1 --> F1[LLM调用]
    F1 --> G1[Schema验证]
    G1 --> H1[结果重排序]
    H1 --> I1[返回结果]
```

### 批量提取流程

当处理多个URL时，系统采用以下流程：

1. **URL分批处理**：将URL列表分成小批次
2. **并发LLM调用**：对每个批次并行调用LLM
3. **结果聚合**：合并所有批次的提取结果
4. **重排序**：根据相关性对最终结果排序

资料来源：[apps/api/src/lib/extract/completions/batchExtract.ts]()

## 核心模块详解

### 提取服务 (ExtractionService)

提取服务是整个数据提取系统的中枢，协调各组件完成数据提取任务。

**主要职责：**
- 管理提取任务的生命周期
- 协调文档构建和提示词构建
- 处理LLM调用和结果验证
- 支持单条和批量提取模式

资料来源：[apps/api/src/lib/extract/extraction-service.ts]()

### 文档构建 (build-document)

文档构建模块负责将提取的原始数据转换为标准化的文档格式。

**功能特点：**
- 规范化提取结果结构
- 添加元数据信息
- 处理多种输出格式

资料来源：[apps/api/src/lib/extract/build-document.ts]()

### 提示词构建 (build-prompts)

提示词构建模块生成用于LLM的结构化提示词，包含必要的上下文和提取指令。

**构建要素：**
- 系统指令（System Prompt）
- 用户提示（User Prompt）
- Schema定义嵌入
- 示例数据（可选）

**自适应优化**：该模块与analyzeSchemaAndPrompt协同工作，可根据Schema自动调整提示词以提高提取准确性。

资料来源：[apps/api/src/lib/extract/build-prompts.ts]()

### 完成处理模块 (completions)

#### 单答案处理 (singleAnswer)

处理单个URL的提取请求，返回完整的结构化数据。

**处理流程：**
```mermaid
graph TD
    A[输入URL和Schema] --> B[构建提示词]
    B --> C[调用LLM]
    C --> D[解析响应]
    D --> E[Schema验证]
    E --> F[返回结果]
```

资料来源：[apps/api/src/lib/extract/completions/singleAnswer.ts]()

#### 批量提取 (batchExtract)

支持同时处理多个URL的提取任务，适用于大规模数据采集场景。

**批处理策略：**
- 动态批次大小调整
- 并发请求控制
- 错误重试机制
- 部分失败容忍

资料来源：[apps/api/src/lib/extract/completions/batchExtract.ts]()

#### Schema分析 (analyzeSchemaAndPrompt)

分析输入的JSON Schema，评估其复杂度并提供优化建议。

**分析维度：**
| 维度 | 描述 |
|------|------|
| 字段数量 | Schema包含的属性数量 |
| 嵌套深度 | 对象嵌套的层级 |
| 数组复杂度 | 数组类型字段的复杂性 |
| 必需字段 | 必填属性的比例 |

资料来源：[apps/api/src/lib/extract/completions/analyzeSchemaAndPrompt.ts]()

### 重排序器 (reranker)

对提取结果进行相关性评分和排序，确保最相关的结果排在前面。

**排序依据：**
- 内容相关性评分
- 字段完整性
- 数据质量指标

资料来源：[apps/api/src/lib/extract/reranker.ts]()

## 队列与Worker机制

### 提取队列 (extract-queue)

提取队列负责管理待处理的提取任务，支持任务的入队、优先级调度和状态追踪。

**队列特性：**
- 异步任务处理
- 可配置并发数
- 任务状态监控
- 失败重试机制

资料来源：[apps/api/src/services/extract-queue.ts]()

### 提取Worker (extract-worker)

Worker进程从队列中获取任务并执行实际的提取操作。

**工作流程：**
```mermaid
graph TD
    A[启动Worker] --> B[连接队列]
    B --> C[等待任务]
    C --> D{有新任务?}
    D -->|是| E[获取任务]
    E --> F[执行提取]
    F --> G[更新状态]
    G --> H[任务完成]
    H --> C
    D -->|否| C
```

**错误处理：**
- 自动重试机制
- 死信队列处理
- 详细的错误日志

资料来源：[apps/api/src/services/extract-worker.ts]()

## API使用

### 基本提取示例

```python
from firecrawl import Firecrawl

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

result = app.extract(
    urls=["https://example.com/product/1"],
    prompt="提取产品名称、价格和描述",
    schema={
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "description": {"type": "string"}
        }
    }
)
```

### 批量提取示例

```python
result = app.extract(
    urls=[
        "https://example.com/products/1",
        "https://example.com/products/2",
        "https://example.com/products/3"
    ],
    prompt="提取所有产品的基本信息",
    schema={...}
)
```

## 配置参数

### 提取选项

| 参数 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| timeout | number | 60000 | 单次请求超时时间（毫秒） |
| maxRetries | number | 3 | 最大重试次数 |
| batchSize | number | 10 | 批量处理大小 |
| temperature | number | 0.0 | LLM温度参数 |

### Schema配置

| 属性 | 必需 | 描述 |
|------|------|------|
| type | 是 | JSON类型定义 |
| properties | 是 | 属性映射 |
| required | 否 | 必填字段列表 |
| additionalProperties | 否 | 允许额外字段 |

## 最佳实践

### 1. Schema设计

- 使用清晰的字段命名
- 合理设置必填字段
- 避免过深的嵌套结构
- 提供明确的类型定义

### 2. 性能优化

- 批量提取时控制并发数
- 合理设置超时时间
- 使用适当的批次大小
- 启用结果缓存（如适用）

### 3. 错误处理

- 实现重试机制处理临时故障
- 验证Schema格式确保有效性
- 检查LLM响应格式的正确性
- 记录详细的错误信息便于调试

## 相关文档

- [搜索系统](../search/README.md)
- [爬取系统](../crawl/README.md)
- [网站地图](../map/README.md)
- [监控服务](../monitor/README.md)

---

<a id='monitoring-webhooks'></a>

## 监控与Webhook

### 相关页面

相关主题：[数据提取系统](#extraction-system), [搜索与爬取功能](#search-crawl), [部署与基础设施](#deployment-infra)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/api/src/services/monitoring/scheduler.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/scheduler.ts)
- [apps/api/src/services/monitoring/runner.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/runner.ts)
- [apps/api/src/services/monitoring/store.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/store.ts)
- [apps/api/src/services/monitoring/diff.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/diff.ts)
- [apps/api/src/services/webhook/delivery.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/webhook/delivery.ts)
- [apps/api/src/services/webhook/queue.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/webhook/queue.ts)
- [apps/api/src/services/ab-test-comparison.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/ab-test-comparison.ts)
</details>

# 监控与Webhook

## 概述

Firecrawl 的监控（Monitoring）与Webhook系统为用户提供了持续追踪网站变化和接收实时事件通知的能力。监控服务通过定期检查网页内容，自动检测新增、移除、修改的页面以及抓取错误，并通过邮件或Webhook渠道向用户推送变更摘要。该系统由多个子模块组成，包括调度器（Scheduler）、执行器（Runner）、存储层（Store）、差异检测（Diff）、Webhook投递（Delivery）和Webhook队列（Queue），它们协同工作以实现可靠的变化检测与通知投递。资料来源：[apps/api/src/services/notification/monitoring_email.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/notification/monitoring_email.ts)

## 监控模块架构

### 整体流程

```mermaid
graph TD
    A[调度器 Scheduler] --> B[执行器 Runner]
    B --> C[存储层 Store]
    C --> D[差异检测 Diff]
    D --> E[变更汇总]
    E --> F[通知发送]
    F --> G[邮件通知]
    F --> H[Webhook投递]
    
    B --> I[抓取目标网页]
    I --> J[当前快照]
    C --> K[历史快照]
    D --> J
    D --> K
```

### 调度器（Scheduler）

调度器负责管理监控任务的定时触发。系统会根据用户配置的检查间隔自动执行监控检查，确保在设定的时间周期内持续追踪目标网站的变化。调度器需要处理并发调度、避免重复执行、以及处理任务超时等场景。资料来源：[apps/api/src/services/monitoring/scheduler.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/scheduler.ts)

### 执行器（Runner）

执行器是监控任务的核心执行单元，负责实际执行网页抓取和内容采集。当调度器触发检查任务时，执行器会启动浏览器实例或发送抓取请求，获取目标页面的当前内容。执行器还需要处理抓取过程中的异常情况，如网络超时、页面加载失败、反爬虫机制等，并将错误信息记录到监控结果中。资料来源：[apps/api/src/services/monitoring/runner.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/runner.ts)

### 存储层（Store）

存储层负责持久化管理监控相关的所有数据，包括监控配置、快照历史、检查记录和变更汇总。Store模块提供了数据的读写接口，确保即使在服务重启后也能恢复监控状态。存储的数据模型通常包含以下核心实体：

| 实体名称 | 描述 | 主要字段 |
|---------|------|---------|
| Monitor | 监控配置 | ID、URL、轮询间隔、通知设置、API密钥 |
| MonitorCheck | 单次检查记录 | ID、监控ID、执行时间、状态、变更统计 |
| PageSnapshot | 页面快照 | ID、检查ID、页面URL、内容哈希、原始内容 |
| MonitoringEmailPage | 变更页面详情 | URL、标题、变更类型 |

资料来源：[apps/api/src/services/monitoring/store.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/store.ts)

### 差异检测（Diff）

差异检测模块负责对比当前快照与历史快照，识别页面内容的实际变化。该模块采用内容哈希比对和结构化解析相结合的方式，能够区分真正的内容变更与动态元素（如时间戳、广告）的随机变化。Diff模块的输出包括变更类型（新增/移除/修改）、变更位置、以及变更的详细摘要，便于用户快速理解网站发生的变化。资料来源：[apps/api/src/services/monitoring/diff.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/monitoring/diff.ts)

## 变更统计模型

监控系统的变更统计采用四维计数模型，全面覆盖网站变化的各个方面：

| 统计类型 | 字段名 | 描述 |
|---------|--------|------|
| 新增页面 | `new_count` | 在本次检查中新发现的页面 |
| 移除页面 | `removed_count` | 在本次检查中消失的页面 |
| 内容变更 | `changed_count` | 内容发生变化的现有页面 |
| 抓取错误 | `error_count` | 抓取失败的页面数量 |

当所有统计值均为零时，系统会跳过邮件通知发送，以减少不必要的通知骚扰。资料来源：[apps/api/src/services/notification/monitoring_email.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/notification/monitoring_email.ts)

## Webhook系统架构

### Webhook事件类型

Firecrawl的Webhook系统支持多种事件类型，覆盖异步任务的完整生命周期：

| 事件类型 | 触发时机 | 用途 |
|---------|---------|------|
| `started` | 任务开始执行时 | 通知任务已启动 |
| `action` | 中间操作发生时 | 报告任务进度或关键步骤 |
| `completed` | 任务成功完成时 | 传递成功结果数据 |
| `failed` | 任务执行失败时 | 返回错误信息和原因 |
| `cancelled` | 任务被取消时 | 通知任务终止状态 |

资料来源：[apps/api/src/controllers/v2/types.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/controllers/v2/types.ts)

### Webhook投递流程

```mermaid
graph LR
    A[事件触发] --> B[Webhook队列]
    B --> C{重试次数检查}
    C -->|未超过限制| D[投递请求]
    D --> E{HTTP响应}
    E -->|2xx成功| F[完成]
    E -->|失败| G[指数退避]
    G --> B
    C -->|超过限制| H[标记失败]
```

### 投递服务（Delivery）

Webhook投递服务负责将事件负载发送到用户配置的端点。投递服务需要处理HTTPS连接、TLS证书验证、请求签名（用于安全验证）等技术细节。投递服务支持自定义请求头、请求体格式配置，以及不同类型事件的差异化负载结构。资料来源：[apps/api/src/services/webhook/delivery.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/webhook/delivery.ts)

### 队列管理（Queue）

Webhook队列提供了可靠投递的保障机制。当投递失败时（如网络错误或目标服务器返回非2xx状态码），队列系统会执行指数退避重试策略，在预设的最大重试次数内持续尝试投递。队列还负责管理不同优先级的事件，确保高优先级事件优先处理。资料来源：[apps/api/src/services/webhook/queue.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/webhook/queue.ts)

## 邮件通知系统

### 通知内容结构

邮件通知采用HTML模板格式，包含以下核心信息：

- **变更汇总**：新增页面数、移除页面数、错误页面数、总检查页面数
- **变更详情列表**：列出发生变化的页面URL和标题
- **检查标识**：用于追踪本次检查的检查ID
- **资源消耗**：本次检查使用的积分数量

邮件内容会对特殊字符进行HTML转义处理，防止XSS攻击。资料来源：[apps/api/src/services/notification/monitoring_email.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/notification/monitoring_email.ts)

### 发送条件

邮件通知仅在以下条件同时满足时发送：

1. 监控配置中已启用邮件通知（`notification.email.enabled === true`）
2. 本次检查检测到至少一个变更（任意统计值大于0）

```typescript
if (
  params.check.changed_count +
    params.check.new_count +
    params.check.removed_count +
    params.check.error_count <= 0
) {
  // 跳过无变更的邮件通知
  return { attempted: false, success: true, recipients: [] };
}
```

资料来源：[apps/api/src/services/notification/monitoring_email.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/notification/monitoring_email.ts)

## A/B测试对比功能

除了基础的变更检测，Firecrawl还提供了A/B测试对比功能，允许用户对比两个不同版本或不同来源的抓取结果。该功能支持并行执行两个抓取任务，并对结果进行差异分析，适用于SEO对比、竞品分析、版本验证等场景。资料来源：[apps/api/src/services/ab-test-comparison.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/services/ab-test-comparison.ts)

## 配置选项

### 监控配置参数

| 参数名 | 类型 | 必填 | 描述 |
|-------|------|------|------|
| url | string | 是 | 要监控的目标URL |
| pollInterval | number | 否 | 轮询间隔（秒），默认根据订阅计划确定 |
| notification.email.enabled | boolean | 否 | 是否启用邮件通知 |
| notification.webhook.url | string | 否 | Webhook回调URL |
| notification.webhook.events | string[] | 否 | 订阅的事件类型列表 |
| scrapeOptions | object | 否 | 抓取选项（formats、onlyMainContent等） |

### Webhook配置参数

| 参数名 | 类型 | 描述 |
|-------|------|------|
| maxRetries | number | 最大重试次数，默认3次 |
| backoffFactor | number | 指数退避因子（秒），默认0.5 |
| timeout | number | 单次投递超时（毫秒） |

## 错误处理机制

### 监控错误分类

| 错误类型 | 处理方式 | 影响范围 |
|---------|---------|---------|
| 网络超时 | 记录错误、重试 | 单次检查标记为失败 |
| 页面加载失败 | 记录错误、跳过内容对比 | 计入error_count统计 |
| 解析异常 | 记录错误、保留原始内容 | 可能导致Diff不准确 |

### Webhook投递错误

Webhook投递失败时，系统会根据HTTP响应状态码采取不同策略：

| 状态码范围 | 处理策略 |
|-----------|---------|
| 2xx | 投递成功，任务完成 |
| 4xx（除429） | 永久失败，不重试 |
| 429/5xx | 指数退避重试，直到达到最大次数 |

## 安全考虑

### Webhook安全

- **请求签名**：Webhook请求包含签名头，用于验证消息来源
- **HTTPS强制**：仅支持HTTPS端点，确保传输安全
- **幂等性设计**：Webhook投递设计为幂等操作，允许安全重放

### 数据保护

- **敏感信息过滤**：邮件通知中的敏感数据经过适当处理
- **HTML转义**：所有用户提供的URL和标题在邮件中经过HTML转义

## 最佳实践

1. **合理设置轮询间隔**：根据网站更新频率调整，避免过度抓取
2. **配置多个通知渠道**：同时启用邮件和Webhook，确保重要变更不被遗漏
3. **设置Webhook重试机制**：利用指数退避策略提高投递可靠性
4. **利用A/B对比功能**：在重要更新前后进行结果对比验证
5. **监控积分消耗**：定期检查creditsUsed字段，合理规划监控规模

## 相关文档

- [Python SDK文档](../sdks/python.md)
- [Node.js SDK文档](../sdks/node.md)
- [API v2参考](../api-reference/v2.md)
- [认证与授权](../guides/authentication.md)

---

<a id='multi-language-sdks'></a>

## 多语言SDK

### 相关页面

相关主题：[项目概览](#project-overview), [API路由与版本控制](#api-routes)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [apps/python-sdk/firecrawl/__init__.py](https://github.com/firecrawl/firecrawl/blob/main/apps/python-sdk/firecrawl/__init__.py)
- [apps/python-sdk/firecrawl/v2/client.py](https://github.com/firecrawl/firecrawl/blob/main/apps/python-sdk/firecrawl/v2/client.py)
- [apps/js-sdk/firecrawl/src/index.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/js-sdk/firecrawl/src/index.ts)
- [apps/js-sdk/firecrawl/src/v2/client.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/js-sdk/firecrawl/src/v2/client.ts)
- [apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java](https://github.com/firecrawl/firecrawl/blob/main/apps/java-sdk/src/main/java/com/firecrawl/client/FirecrawlClient.java)
- [apps/go-sdk/firecrawl.go](https://github.com/firecrawl/firecrawl/blob/main/apps/go-sdk/firecrawl.go)
- [apps/rust-sdk/src/client.rs](https://github.com/firecrawl/firecrawl/blob/main/apps/rust-sdk/src/client.rs)
- [apps/dotnet-sdk/Firecrawl/FirecrawlClient.cs](https://github.com/firecrawl/firecrawl/blob/main/apps/dotnet-sdk/Firecrawl/FirecrawlClient.cs)
</details>

# 多语言SDK

## 概述

Firecrawl 多语言SDK是一组官方支持的客户端库，旨在为开发者提供跨编程语言的统一接口，以便轻松访问Firecrawl的网页搜索、抓取和交互功能。这些SDK自动处理HTTP请求、身份验证、响应解析以及异步操作的轮询机制，使开发者能够在Python、JavaScript、Java、Go、Rust、.NET、Ruby等多种主流编程语言中使用Firecrawl服务。

## 支持的编程语言

Firecrawl目前官方支持以下编程语言的SDK：

| 编程语言 | 包名称 | 安装命令 | 主要类/客户端 |
|---------|--------|---------|--------------|
| Python | `firecrawl-py` | `pip install firecrawl-py` | `Firecrawl` |
| JavaScript/TypeScript | `@mendable/firecrawl-js` | `npm install @mendable/firecrawl-js` | `Firecrawl` |
| Java | `firecrawl-java` | Maven/Gradle依赖 | `FirecrawlClient` |
| Go | `firecrawl-sdk` | `go get` | `Firecrawl` |
| Rust | `firecrawl` | Cargo.toml | `Client` |
| .NET | `firecrawl-sdk` | `dotnet add package firecrawl-sdk` | `FirecrawlClient` |
| Ruby | `firecrawl-sdk` | `gem install firecrawl-sdk` | `Client` |

## 核心功能

所有SDK都提供一致的核心功能集，确保开发者无论使用何种编程语言都能获得相同的能力：

```mermaid
graph TD
    A[Firecrawl SDK] --> B[Search 搜索]
    A --> C[Scrape 网页抓取]
    A --> D[Crawl 网站爬取]
    A --> E[Parse 文件解析]
    A --> F[Map 站点地图]
    A --> G[Interact 页面交互]
    A --> H[Extract 结构化提取]
    
    B --> I[返回搜索结果]
    C --> J[返回文档内容]
    D --> K[批量页面抓取]
    E --> L[支持HTML/PDF/DOCX]
    F --> M[URL列表生成]
    G --> N[浏览器自动化]
    H --> O[JSON Schema提取]
```

## 客户端初始化

### 认证方式

所有SDK支持两种API密钥配置方式：

**方式一：通过构造函数直接传入**

```python
# Python
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")
```

```javascript
// JavaScript/TypeScript
import Firecrawl from '@mendable/firecrawl-js';
const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });
```

```java
// Java
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();
```

```csharp
// .NET
var client = new FirecrawlClient("fc-your-api-key");
```

**方式二：通过环境变量自动加载**

各SDK会优先读取环境变量`FIRECRAWL_API_KEY`：

```python
# Python - 无需传入API key，自动从环境变量读取
app = Firecrawl.from_env()
```

```java
// Java - 默认从FIRECRAWL_API_KEY环境变量读取
FirecrawlClient client = FirecrawlClient.fromEnv();
```

```ruby
# Ruby
client = Firecrawl::Client.from_env
```

```go
// Go
client := firecrawl.NewClient(os.Getenv("FIRECRAWL_API_KEY"), "")
```

### 自定义API端点

对于自托管的Firecrawl实例，部分SDK支持自定义API URL：

```csharp
// .NET - 自定义API URL
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com");
```

```javascript
// JavaScript/TypeScript - 可在初始化时配置
const app = new Firecrawl({ 
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com"
});
```

## 核心API

### Search 搜索

在网络上搜索相关内容，返回与查询匹配的URL和摘要：

```python
# Python
results = app.search("best AI data tools 2024", limit=10)
```

```javascript
// JavaScript
const results = await app.search('firecrawl', { limit: 5 });
```

```rust
// Rust
let response = client.search("best web scraping tools 2024", None).await?;
```

### Scrape 网页抓取

从单个URL提取内容，支持多种输出格式：

| 参数 | 类型 | 说明 |
|-----|------|------|
| `url` | string | 目标网页URL |
| `formats` | array | 输出格式：`markdown`, `html`, `json`, `screenshot`等 |
| `onlyMainContent` | boolean | 仅提取主要内容 |
| `waitFor` | number | 等待渲染的毫秒数 |

```python
# Python
doc = app.scrape('https://firecrawl.dev', formats=['markdown', 'html'])
print(doc.markdown)
```

```java
// Java
Document doc = client.scrape("https://example.com",
    ScrapeOptions.builder()
        .formats(List.of("markdown"))
        .build());
```

```csharp
// .NET
var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });
```

### Crawl 网站爬取

批量爬取网站页面，支持自动轮询等待完成：

```python
# Python - 自动等待爬取完成
docs = app.crawl('https://docs.firecrawl.dev', limit=50)
for doc in docs.data:
    print(doc.metadata.source_url)
```

```ruby
# Ruby - 自动轮询模式
job = client.crawl("https://example.com",
  Firecrawl::Models::CrawlOptions.new(limit: 50))
job.data.each { |doc| puts doc.markdown }
```

```rust
// Rust
let options = CrawlOptions {
    limit: Some(50),
    ..Default::default()
};
let result = client.crawl("https://docs.firecrawl.dev", options).await?;
```

### Map 站点地图

生成网站的URL列表，用于了解站点结构：

```javascript
// JavaScript
const mapResult = await app.map('https://example.com');
console.log(mapResult);
```

### Interact 页面交互

在抓取页面后执行浏览器自动化操作：

```python
# Python
result = app.scrape("https://amazon.com")
scrape_id = result.metadata.scrape_id
app.interact(scrape_id, prompt="Search for 'mechanical keyboard'")
```

```java
// Java
Document doc = client.scrape("https://example.com");
String scrapeId = String.valueOf(doc.getMetadata().get("scrapeId"));
BrowserExecuteResponse exec = client.interact(scrapeId, "console.log(await page.title());");
```

### Extract 结构化提取

根据prompt和schema从页面提取结构化数据：

```javascript
// JavaScript - 支持Zod schema
const schema = z.object({
  title: z.string(),
});
const result = await app.extract({
  urls: ['https://firecrawl.dev'],
  prompt: 'Extract the page title',
  schema,
});
```

### Batch Scrape 批量抓取

一次性抓取多个URL：

```python
# Python
job = app.batch_scrape([
    "https://firecrawl.dev",
    "https://docs.firecrawl.dev",
], formats=["markdown"])
for doc in job.data:
    print(doc.metadata.source_url)
```

### Parse 文件解析

解析上传的本地文件（HTML、PDF、DOCX等）：

```python
# Python
doc = firecrawl.parse(
  b"<!DOCTYPE html><html><body><h1>Content</h1></body></html>",
  filename="upload.html",
  content_type="text/html",
  options=ParseOptions(formats=["markdown"]),
)
```

```java
// Java
ParseFile file = ParseFile.builder()
    .filename("upload.html")
    .content("<!DOCTYPE html>...".getBytes())
    .contentType("text/html")
    .build();
Document parsed = client.parse(file,
    ParseOptions.builder()
        .formats(List.of("markdown"))
        .build());
```

## 异步操作

### 异步爬取工作流

```mermaid
sequenceDiagram
    participant 客户端
    participant Firecrawl API
    participant 用户
    
    客户端->>Firecrawl API: start_crawl/startCrawl
    Firecrawl API-->>客户端: 返回job_id
    客户端->>Firecrawl API: get_crawl_status(job_id)
    Firecrawl API-->>客户端: status: in_progress
    客户端->>Firecrawl API: get_crawl_status(job_id)
    Firecrawl API-->>客户端: status: completed, data: [...]
```

### 异步爬取示例

```javascript
// JavaScript/TypeScript - 开始异步爬取
const start = await app.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

// 检查爬取状态
const status = await app.getCrawlStatus(start.id);
console.log(status.status);
```

```ruby
# Ruby - 异步爬取
response = client.start_crawl("https://example.com",
  Firecrawl::Models::CrawlOptions.new(limit: 10))
puts response.id

# 检查状态
status = client.get_crawl_status(response.id)
puts status.status

# 取消爬取
client.cancel_crawl(response.id)
```

## 数据模型

### Document 文档对象

SDK返回的文档对象通常包含以下属性：

| 属性 | 类型 | 说明 |
|-----|------|------|
| `markdown` | string | 页面内容的Markdown格式 |
| `html` | string | 原始HTML内容 |
| `metadata` | object | 元数据（标题、描述、来源URL等） |
| `raw` | object | 原始响应数据 |
| `json` | object | 提取的JSON数据（当使用json格式时） |

```python
# Python - 访问文档属性
doc = app.scrape('https://example.com')
print(doc.markdown)       # Markdown内容
print(doc.metadata.title) # 页面标题
print(doc.metadata.source_url) # 来源URL
```

### ScrapeOptions 抓取选项

| 选项 | 类型 | 说明 |
|-----|------|------|
| `formats` | array | 输出格式列表 |
| `onlyMainContent` | boolean | 仅提取主要内容，移除噪音 |
| `waitFor` | number | 等待JavaScript渲染的毫秒数 |
| `headers` | object | 自定义HTTP头 |
| `proxy` | string | 代理设置 |

## 错误处理

各SDK使用各自语言的原生错误处理机制：

```python
# Python - 使用异常处理
try:
    doc = app.scrape('https://example.com')
except Exception as e:
    print(f"抓取失败: {e}")
```

```rust
// Rust - 使用Result类型
match scrape_result {
    Ok(data) => println!("{}", data.markdown),
    Err(e) => eprintln!("抓取失败: {}", e),
}
```

```java
// Java - 异常处理
try {
    Document doc = client.scrape("https://example.com", options);
} catch (FirecrawlException e) {
    System.err.println("API错误: " + e.getMessage());
}
```

## SDK架构对比

```mermaid
graph LR
    subgraph Python
        P1[Firecrawl类]
        P2[v2.Client]
    end
    
    subgraph JavaScript
        J1[Firecrawl类]
        J2[v2.Client]
    end
    
    subgraph Java
        K1[FirecrawlClient]
        K2[Builder模式]
    end
    
    subgraph Rust
        R1[Client结构体]
        R2[异步方法]
    end
    
    P1 --> P2
    J1 --> J2
    K1 --> K2
    R1 --> R2
```

## 依赖要求

| SDK | 最低版本要求 | 额外依赖 |
|-----|------------|---------|
| Python | Python 3.8+ | `requests` |
| JavaScript | Node.js兼容 | - |
| Java | JDK 11+ | - |
| Go | Go 1.16+ | - |
| Rust | Rust最新稳定版 | `tokio` (异步运行时) |
| .NET | .NET Core 6.0+ | - |
| Ruby | Ruby 3.0+ | - |

## 最佳实践

### 1. 环境变量管理

建议在生产环境中使用环境变量存储API密钥：

```bash
# 设置环境变量
export FIRECRAWL_API_KEY="fc-your-api-key"
```

### 2. 异步操作处理

对于大量页面的爬取任务，使用异步方法并实现适当的重试机制：

```python
# Python - 配置重试和超时
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR_API_KEY")
docs = app.crawl('https://example.com', limit=100, poll_interval=30)
```

### 3. 错误重试

```python
# Python - 实现重试逻辑
import time
def scrape_with_retry(url, max_retries=3):
    for i in range(max_retries):
        try:
            return app.scrape(url)
        except Exception as e:
            if i == max_retries - 1:
                raise
            time.sleep(2 ** i)
```

## 相关资源

- Python SDK源码：[apps/python-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/python-sdk)
- JavaScript SDK源码：[apps/js-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/js-sdk)
- Java SDK源码：[apps/java-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/java-sdk)
- Go SDK源码：[apps/go-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/go-sdk)
- Rust SDK源码：[apps/rust-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/rust-sdk)
- .NET SDK源码：[apps/dotnet-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/dotnet-sdk)
- Ruby SDK源码：[apps/ruby-sdk/](https://github.com/firecrawl/firecrawl/tree/main/apps/ruby-sdk)

---

<a id='deployment-infra'></a>

## 部署与基础设施

### 相关页面

相关主题：[系统架构](#system-architecture), [项目概览](#project-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/firecrawl/firecrawl/blob/main/README.md)
- [examples/kubernetes/firecrawl-helm/README.md](https://github.com/firecrawl/firecrawl/blob/main/examples/kubernetes/firecrawl-helm/README.md)
- [apps/python-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/python-sdk/README.md)
- [apps/js-sdk/firecrawl/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/js-sdk/firecrawl/README.md)
- [apps/api/src/lib/branding/prompt.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/branding/prompt.ts)
</details>

# 部署与基础设施

## 概述

Firecrawl 的部署与基础设施体系支持多种部署模式，包括本地开发、Docker 容器化部署、Kubernetes 集群部署以及云原生架构。该项目采用微服务架构，主要包含 API 服务、Playwright 渲染服务、Redis 缓存层和数据库存储层等核心组件。通过 Helm Chart 和 Docker Compose 两种主流编排工具，开发者可以灵活选择适合自身环境的部署方案。

Firecrawl 的基础设施设计遵循以下核心原则：可扩展性支持水平扩展以应对高并发场景；多架构支持涵盖 x86 和 ARM64 平台；环境隔离通过容器化实现开发与生产环境的统一；可观测性内置日志、监控和追踪能力。

## 系统架构

### 整体架构图

```mermaid
graph TD
    A[客户端请求] --> B[API 网关 / 负载均衡]
    B --> C[Firecrawl API 服务]
    C --> D[Redis 缓存层]
    C --> E[PostgreSQL 数据库]
    C --> F[Playwright 服务]
    F --> G[浏览器实例池]
    G --> H[渲染后的页面内容]
    H --> C
    C --> I[返回 LLM 可用的数据格式]
```

### 核心组件

| 组件名称 | 技术栈 | 功能描述 |
|---------|--------|---------|
| Firecrawl API | Node.js/TypeScript | 核心 REST API 服务，处理爬取、搜索、交互请求 |
| Playwright 服务 | TypeScript + Playwright | 浏览器自动化渲染，支持截图和 JavaScript 执行 |
| Redis | Redis | 任务队列、缓存、会话存储 |
| PostgreSQL | PostgreSQL | 持久化存储爬取任务、文档数据、用户信息 |
| 多语言 SDK | Python/JS/Ruby/PHP/Go/Rust/.NET/Java | 官方客户端库，简化 API 集成 |

资料来源：[README.md:1-50]()

## Docker 容器化部署

### 多架构镜像构建

Firecrawl 支持同时构建适用于 x86_64 (amd64) 和 ARM64 (arm64) 架构的 Docker 镜像。这对于在 Apple Silicon Mac 或基于 ARM 的云服务器上运行的场景尤为重要。

```bash
# 创建并使用 docker buildx 构建器
docker buildx create --name multiarch --use --bootstrap

# 构建并推送多架构镜像
docker buildx build --platform linux/amd64,linux/arm64 --push \
  -t docker.io/winkkgmbh/firecrawl:latest \
  ../../../apps/api
```

资料来源：[examples/kubernetes/firecrawl-helm/README.md:45-55]()

### 官方镜像仓库

Firecrawl 维护以下官方容器镜像：

| 镜像名称 | 用途 | 仓库地址 |
|---------|------|---------|
| firecrawl | 主 API 服务 | ghcr.io/firecrawl/firecrawl |
| playwright-service | 浏览器渲染服务 | ghcr.io/firecrawl/playwright-service |
| nuq-postgres | 数据库服务 | ghcr.io/firecrawl/nuq-postgres |

开发者可以使用这些官方镜像快速部署，或通过 docker-compose.yaml 进行本地开发环境搭建。

## Kubernetes 部署

### Helm Chart 架构

Firecrawl 提供完整的 Helm Chart 用于 Kubernetes 集群部署，支持通过 values.yaml 进行灵活配置。Chart 遵循 Kubernetes 最佳实践，包括健康检查探针、资源限制、环境变量配置和持久化存储。

```bash
# 基础部署命令
HELM_NO_PLUGINS=1 helm upgrade firecrawl . \
  -f values.yaml \
  -f overlays/prod/values.yaml \
  -n firecrawl \
  --install \
  --create-namespace
```

资料来源：[examples/kubernetes/firecrawl-helm/README.md:25-35]()

### 生产环境配置

生产环境部署通常需要合并多层配置文件：

```yaml
# 生产环境覆盖配置示例
replicaCount: 3
image:
  repository: ghcr.io/firecrawl/firecrawl
resources:
  requests:
    memory: "512Mi"
    cpu: "250m"
  limits:
    memory: "2Gi"
    cpu: "1000m"
```

### 使用官方镜像

对于纯 x86 架构的集群，可以直接使用官方预构建镜像：

```bash
HELM_NO_PLUGINS=1 helm upgrade firecrawl . \
  -f values.yaml \
  --set image.repository=ghcr.io/firecrawl/firecrawl \
  --set playwright.repository=ghcr.io/firecrawl/playwright-service \
  --set nuqPostgres.image.repository=ghcr.io/firecrawl/nuq-postgres \
  -n firecrawl \
  --install \
  --create-namespace
```

资料来源：[examples/kubernetes/firecrawl-helm/README.md:36-48]()

## 环境变量配置

### 必需配置项

| 环境变量 | 说明 | 示例值 |
|---------|------|--------|
| `FIRECRAWL_API_KEY` | API 认证密钥 | `fc-your-api-key-here` |
| `DATABASE_URL` | PostgreSQL 连接字符串 | `postgresql://user:pass@host:5432/db` |
| `REDIS_URL` | Redis 连接字符串 | `redis://localhost:6379` |

### SDK 环境配置

各语言 SDK 均支持从环境变量自动读取配置：

```python
# Python SDK
from firecrawl import Firecrawl
app = Firecrawl()  # 自动读取 FIRECRAWL_API_KEY

# JavaScript SDK
const app = new Firecrawl({ apiKey: process.env.FIRECRAWL_API_KEY });

# Ruby SDK
client = Firecrawl::Client.from_env  # 读取 FIRECRAWL_API_KEY

# PHP SDK
$client = FirecrawlClient::fromEnv();
```

```bash
# Shell 环境配置
export FIRECRAWL_API_KEY="fc-your-api-key-here"
# 可选：自定义 API URL（用于自托管实例）
export FIRECRAWL_API_URL="http://localhost:3002"
```

资料来源：[apps/python-sdk/README.md:1-30](), [apps/js-sdk/firecrawl/README.md:1-25](), [apps/ruby-sdk/README.md:1-20](), [apps/php-sdk/README.md:1-20]()

## 服务发现与网络

### 服务间通信

```mermaid
graph LR
    A[SDK 客户端] -->|HTTPS| B[API 服务 :3000]
    B -->|内部通信| C[Playwright 服务 :3001]
    B -->|TCP| D[Redis :6379]
    B -->|TCP| E[PostgreSQL :5432]
```

API 服务默认监听 3000 端口，Playwright 渲染服务默认监听 3001 端口。服务间通过内部网络通信，无需对外暴露。

### 自托管实例配置

对于自托管部署，可以通过环境变量指定自定义 API 地址：

```csharp
// .NET SDK
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    apiUrl: "https://your-firecrawl-instance.com"
);
```

```java
// Java SDK
FirecrawlClient client = FirecrawlClient.builder()
    .apiUrl("https://your-firecrawl-instance.com")
    .apiKey("fc-your-api-key")
    .build();
```

## 资源规划

### 推荐资源配置

| 环境规模 | API副本 | Playwright副本 | Redis | PostgreSQL |
|---------|--------|---------------|-------|-----------|
| 开发/测试 | 1 | 1 | 1GB | 10GB |
| 小规模生产 | 2 | 2 | 4GB | 50GB |
| 中等规模 | 5 | 5 | 8GB | 200GB |
| 大规模 | 10+ | 10+ | 16GB+ | 500GB+ |

### 健康检查配置

Kubernetes 部署中包含以下健康检查：

- **存活探针 (Liveness Probe)**：检测服务是否存活，失败时重启容器
- **就绪探针 (Readiness Probe)**：检测服务是否就绪，失败时停止接收流量
- **启动探针 (Startup Probe)**：给予服务足够时间完成初始化

## 安全考虑

### 网络策略

生产环境建议配置 Kubernetes NetworkPolicy，限制以下流量：

- API 服务仅接收来自负载均衡器的流量
- Playwright 服务仅接收来自 API 服务的内部流量
- 数据库仅接收来自 API 服务的流量
- Redis 仅接收来自 API 服务的流量

### 密钥管理

API 密钥应通过 Kubernetes Secret 或外部密钥管理服务（如 AWS Secrets Manager、HashiCorp Vault）存储，避免在 values.yaml 中明文配置。

## 监控与日志

### 日志聚合

Firecrawl API 服务输出结构化日志，建议通过以下方式收集：

- **标准输出/标准错误**：Kubernetes 默认收集方式
- **日志聚合器**：如 Fluentd、Filebeat 收集到 Elasticsearch/Loki
- **云原生方案**：CloudWatch Logs、Azure Monitor、Google Cloud Logging

### 关键指标

| 指标名称 | 说明 | 告警阈值建议 |
|---------|------|-------------|
| 请求延迟 P99 | API 响应时间 | > 10s |
| 错误率 | 5xx 错误占比 | > 5% |
| 队列深度 | Redis 待处理任务数 | > 1000 |
| 浏览器实例数 | Playwright 活跃实例 | < 2（表示可能泄漏） |

## 备份与恢复

### 数据库备份

PostgreSQL 数据库应配置以下备份策略：

- **自动全量备份**：每日执行，保留 30 天
- **增量备份**：每 6 小时执行
- **点时间恢复 (PITR)**：启用 Write-Ahead Log (WAL) 归档

### 灾难恢复

灾难恢复计划应包含：

1. **RTO（恢复时间目标）**：< 4 小时
2. **RPO（恢复点目标）**：< 1 小时
3. **恢复流程文档化**：包含步骤验证清单
4. **定期演练**：每季度执行恢复演练

## 部署最佳实践

### CI/CD 集成

```yaml
# 示例 GitHub Actions 部署流程
deploy:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Build and push images
      run: |
        docker buildx build \
          --platform linux/amd64,linux/arm64 \
          --push \
          -t ${{ env.REGISTRY }}/firecrawl:${{ github.sha }} .
    - name: Deploy to Kubernetes
      run: |
        helm upgrade firecrawl ./charts/firecrawl \
          --set image.tag=${{ github.sha }}
```

### 滚动更新策略

建议使用 `RollingUpdate` 策略配置蓝绿部署或滚动更新：

```yaml
strategy:
  type: RollingUpdate
  rollingUpdate:
    maxSurge: 1
    maxUnavailable: 0
```

## 相关文档

- [SDK 文档](../sdks/overview.md)
- [API 参考](../api-reference/overview.md)
- [自托管指南](./self-hosting.md)

---

<a id='development-guide'></a>

## 开发指南

### 相关页面

相关主题：[系统架构](#system-architecture), [项目概览](#project-overview)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [CONTRIBUTING.md](https://github.com/firecrawl/firecrawl/blob/main/CONTRIBUTING.md)
- [apps/api/jest.config.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/jest.config.ts)
- [apps/api/knip.config.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/knip.config.ts)
- [apps/api/src/scraper/scrapeURL/scrapeURL.test.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/scraper/scrapeURL/scrapeURL.test.ts)
- [apps/api/src/lib/validateUrl.test.ts](https://github.com/firecrawl/firecrawl/blob/main/apps/api/src/lib/validateUrl.test.ts)
- [apps/test-suite/jest.config.js](https://github.com/firecrawl/firecrawl/blob/main/apps/test-suite/jest.config.js)
- [apps/python-sdk/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/python-sdk/README.md)
- [apps/js-sdk/firecrawl/README.md](https://github.com/firecrawl/firecrawl/blob/main/apps/js-sdk/firecrawl/README.md)
</details>

# 开发指南

本文档为 Firecrawl 项目提供全面的开发指南，涵盖开发环境配置、代码规范、测试策略、多语言 SDK 开发等内容。

## 项目概述

Firecrawl 是一个用于搜索、抓取网页内容并将其转换为 LLM 可用格式的 web scraping 工具。项目采用多语言 SDK 架构，核心 API 服务使用 TypeScript/Node.js 开发，同时提供 Python、JavaScript/TypeScript、Rust、Go、Java、Ruby、.NET 等多语言 SDK。

```mermaid
graph TB
    subgraph 核心服务
        A[API Server<br/>TypeScript/Node.js]
        B[Playwright Service]
        C[数据库服务]
    end
    
    subgraph SDK层
        D[Python SDK]
        E[JS/TS SDK]
        F[Rust SDK]
        G[Go SDK]
        H[Java SDK]
        I[Ruby SDK]
        J[.NET SDK]
    end
    
    K[外部用户]
    
    A --> B
    A --> C
    K --> D
    K --> E
    K --> F
    K --> G
    K --> H
    K --> I
    K --> J
    D --> A
    E --> A
    F --> A
    G --> A
```

## 开发环境配置

### 环境要求

根据不同开发任务，需要安装以下环境：

| 组件 | 版本要求 | 用途 |
|------|----------|------|
| Node.js | 18+ | API 服务开发 |
| Python | 3.9+ | Python SDK 开发 |
| Rust | 1.70+ | Rust SDK 开发 |
| Java | 11+ | Java SDK 开发 |
| Go | 1.20+ | Go SDK 开发 |
| Ruby | 3.0+ | Ruby SDK 开发 |
| .NET | 6.0+ | .NET SDK 开发 |
| Gradle | 8+ | Java SDK 构建 |

### 项目结构

```
firecrawl/
├── apps/
│   ├── api/                    # 核心 API 服务 (TypeScript)
│   ├── playwright-service-ts/   # Playwright 浏览器服务
│   ├── python-sdk/              # Python SDK
│   ├── js-sdk/                  # JavaScript/TypeScript SDK
│   ├── rust-sdk/                # Rust SDK
│   ├── go-sdk/                  # Go SDK
│   ├── java-sdk/                # Java SDK
│   ├── ruby-sdk/                # Ruby SDK
│   ├── dot-net-sdk/             # .NET SDK
│   └── test-suite/              # 测试套件
├── examples/                    # 使用示例
│   └── kubernetes/              # Kubernetes 部署配置
└── sharedLibs/                  # 共享库
    └── go-html-to-md/           # Go HTML 转 Markdown 库
```

## 代码规范与工具链

### 代码质量工具

Firecrawl 项目使用 Knip 进行代码质量检查和未使用依赖分析。配置文件位于 `apps/api/knip.config.ts`：

```typescript
// apps/api/knip.config.ts
import type { KnipConfig } from "knip";
const config: KnipConfig = {
  // 入口文件和项目结构配置
  project: ["**/*.{ts,tsx,js,jsx}"],
  // 忽略的文件
  ignore: ["**/*.test.ts", "**/node_modules/**"],
};
export default config;
```

### 代码检查命令

```bash
# 运行 Knip 检查
npx knip

# 或添加自定义配置
npx knip --config knip.config.ts
```

### Linting 配置

项目采用标准的 ESLint 配置，建议在提交前运行 lint 检查确保代码风格一致。

## 测试策略

### 测试框架

Firecrawl 使用 Jest 作为主要的测试框架。API 服务和测试套件分别有不同的配置文件。

#### API 服务测试配置

```typescript
// apps/api/jest.config.ts
import type { Config } from "jest";

const config: Config = {
  preset: "ts-jest",
  testEnvironment: "node",
  roots: ["<rootDir>/src"],
  testMatch: ["**/*.test.ts"],
  transform: {
    "^.+\\.tsx?$": ["ts-jest", {
      tsconfig: "tsconfig.json",
    }],
  },
  moduleNameMapper: {
    "^@/(.*)$": "<rootDir>/src/$1",
  },
};

export default config;
```

#### 测试套件配置

```javascript
// apps/test-suite/jest.config.js
module.exports = {
  testEnvironment: "node",
  testMatch: ["**/*.test.{js,ts}"],
  // 测试超时设置
  testTimeout: 30000,
};
```

### 编写测试用例

#### URL 验证测试示例

```typescript
// apps/api/src/lib/validateUrl.test.ts
import { validateUrl } from "./validateUrl";

describe("URL Validation", () => {
  it("should validate correct URLs", () => {
    expect(validateUrl("https://example.com")).toBe(true);
    expect(validateUrl("http://test.org/path")).toBe(true);
  });

  it("should reject invalid URLs", () => {
    expect(validateUrl("not-a-url")).toBe(false);
    expect(validateUrl("ftp://invalid-protocol.com")).toBe(false);
  });
});
```

#### 抓取功能测试示例

```typescript
// apps/api/src/scraper/scrapeURL/scrapeURL.test.ts
import { scrapeURL } from "./scrapeURL";
import { FirecrawlDocument } from "../../../models/firecrawl-document";

describe("scrapeURL", () => {
  const mockUrl = "https://example.com";
  const mockOptions = {
    formats: ["markdown", "html"] as const,
    onlyMainContent: true,
  };

  it("should scrape a URL and return markdown", async () => {
    const result: FirecrawlDocument = await scrapeURL(mockUrl, mockOptions);
    
    expect(result.markdown).toBeDefined();
    expect(result.markdown).not.toBeEmpty();
  });

  it("should respect onlyMainContent option", async () => {
    const result = await scrapeURL(mockUrl, mockOptions);
    
    expect(result.markdown).not.toContain("<nav>");
    expect(result.markdown).not.toContain("<header>");
  });
});
```

### 运行测试

```bash
# 运行所有测试
npm test

# 运行特定测试文件
npm test -- validateUrl.test.ts

# 运行测试并生成覆盖率报告
npm test -- --coverage

# 运行测试套件
cd apps/test-suite && npm test
```

### 测试最佳实践

| 实践 | 说明 | 资料来源 |
|------|------|----------|
| 测试文件命名 | 使用 `.test.ts` 后缀 | `apps/api/jest.config.ts:6` |
| 测试环境隔离 | 每个测试独立运行 | `apps/api/jest.config.ts:5` |
| 模拟外部依赖 | 使用 Jest mocks | `apps/api/src/scraper/scrapeURL/scrapeURL.test.ts` |
| 异步测试 | 使用 async/await | `apps/api/src/scraper/scrapeURL/scrapeURL.test.ts:12` |
| 超时配置 | 复杂测试设置超时 | `apps/test-suite/jest.config.js:6` |

## 多语言 SDK 开发

### Python SDK

#### 环境配置

```python
# 使用虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
.\venv\Scripts\activate   # Windows

# 安装依赖
pip install firecrawl
```

#### 快速开始

```python
# apps/python-sdk/README.md
from firecrawl import Firecrawl

# 创建客户端
firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# 抓取网页
scrape_result = firecrawl.scrape(
    'https://firecrawl.dev', 
    formats=['markdown', 'html']
)
print(scrape_result)

# 爬取网站
crawl_status = firecrawl.crawl(
    'https://firecrawl.dev', 
    limit=100, 
    scrape_options=ScrapeOptions(formats=['markdown', 'html']),
    poll_interval=30
)
```

#### SDK 包结构

| 模块 | 功能 |
|------|------|
| `firecrawl` | 主客户端类 |
| `firecrawl.v2.types` | 类型定义 (ParseOptions, ScrapeOptions) |

### JavaScript/TypeScript SDK

#### 环境配置

```bash
npm install @mendable/firecrawl-js
```

#### 快速开始

```typescript
// apps/js-sdk/firecrawl/README.md
import Firecrawl from '@mendable/firecrawl-js';

const app = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

// 搜索
const searchResult = await app.search("firecrawl", { limit: 5 });

// 抓取
const scrapeResult = await app.scrape('https://example.com', {
  formats: ['markdown', 'html'],
  onlyMainContent: true,
});

// 爬取
const crawlResult = await app.crawl('https://firecrawl.dev', {
  limit: 100,
  scrapeOptions: { formats: ['markdown', 'html'] },
});
```

#### 异步爬取

```typescript
// 启动异步爬取任务
const start = await app.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

// 检查爬取状态
const status = await app.getCrawlStatus(start.jobId);
```

### Rust SDK

#### 环境配置

```toml
# apps/rust-sdk/README.md
[dependencies]
firecrawl = "2.1.0"
tokio = { version = "^1", features = ["full"] }
```

#### 快速开始

```rust
use firecrawl::{Client, ScrapeOptions, Format, CrawlOptions};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("fc-YOUR_API_KEY")?;

    // 抓取 URL
    let document = client.scrape("https://firecrawl.dev", None).await?;
    println!("{:?}", document.markdown);

    // 爬取网站
    let options = CrawlOptions {
        limit: Some(50),
        ..Default::default()
    };
    let result = client.crawl("https://docs.firecrawl.dev", options).await?;

    // 搜索
    let response = client.search("best web scraping tools 2024", None).await?;

    Ok(())
}
```

### Java SDK

#### 环境配置

```groovy
// apps/java-sdk/README.md
repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.firecrawl:firecrawl-java:1.1.1'
}
```

#### 快速开始

```java
import com.firecrawl.client.FirecrawlClient;
import com.firecrawl.models.*;
import java.util.List;

// 创建客户端
FirecrawlClient client = FirecrawlClient.builder()
    .apiKey("fc-your-api-key")
    .build();

// 抓取网页
Document doc = client.scrape("https://example.com",
    ScrapeOptions.builder()
        .formats(List.of("markdown"))
        .build());

System.out.println(doc.getMarkdown());
```

### .NET SDK

#### 环境配置

```bash
dotnet add package firecrawl-sdk
```

#### 快速开始

```csharp
// apps/dotnet-sdk/README.md
using Firecrawl;
using Firecrawl.Models;

var client = new FirecrawlClient("fc-your-api-key");

// 抓取单个页面
var doc = await client.ScrapeAsync("https://example.com",
    new ScrapeOptions { Formats = new List<object> { "markdown" } });

Console.WriteLine(doc.Markdown);
```

### Go SDK

Go SDK 位于 `apps/go-sdk`，提供与 Firecrawl API 交互的 Go 语言接口。

### Ruby SDK

#### 环境配置

```ruby
# apps/ruby-sdk/README.md
gem "firecrawl-sdk", "~> 1.0"
```

#### 快速开始

```ruby
require "firecrawl"

# 创建客户端
client = Firecrawl::Client.new(api_key: "fc-your-api-key")

# 抓取单个页面
doc = client.scrape("https://example.com")
puts doc.markdown
```

## 贡献指南

### 提交流程

1. **Fork 仓库** - 从主仓库创建个人分支
2. **创建分支** - 使用描述性的分支名称
   ```bash
   git checkout -b feature/your-feature-name
   ```
3. **编写代码** - 遵循项目的代码规范
4. **添加测试** - 确保新功能有对应的测试用例
5. **运行测试** - 提交前确保所有测试通过
6. **提交更改** - 编写清晰的提交信息
7. **创建 Pull Request** - 描述更改内容和动机

### 代码审查要点

| 审查项 | 要求 | 资料来源 |
|--------|------|----------|
| 代码风格 | 通过 lint 检查 | `apps/api/knip.config.ts` |
| 测试覆盖 | 新功能必须包含测试 | `apps/api/jest.config.ts` |
| 文档更新 | 更新相关 README | `CONTRIBUTING.md` |
| 向后兼容 | 不破坏现有 API | 多语言 SDK 文档 |

### 开发工作流

```mermaid
graph LR
    A[创建分支] --> B[编写代码]
    B --> C[添加测试]
    C --> D[运行测试]
    D --> E{测试通过?}
    E -->|否| F[修复问题]
    F --> D
    E -->|是| G[提交代码]
    G --> H[创建 PR]
    H --> I[代码审查]
    I --> J{审查通过?}
    J -->|否| K[修改代码]
    K --> I
    J -->|是| L[合并到主分支]
```

## 调试与问题排查

### 常见问题

#### 1. 测试失败

```bash
# 查看详细错误信息
npm test -- --verbose

# 运行单个测试
npm test -- validateUrl.test.ts --verbose

# 调试模式
npm test -- --inspect-brk
```

#### 2. API 连接问题

检查以下配置：
- `FIRECRAWL_API_KEY` 环境变量是否设置
- API 端点是否可访问
- 网络代理配置是否正确

#### 3. SDK 导入错误

确保安装了正确版本的 SDK：

| SDK | 最低版本 |
|-----|----------|
| Python | firecrawl 2.x |
| JavaScript | @mendable/firecrawl-js 0.x |
| Rust | firecrawl 2.1.0 |
| Java | firecrawl-java 1.1.1 |

## 高级配置

### 自定义 API 端点

对于自托管实例，可以指定自定义 API URL：

```typescript
// JavaScript SDK
const app = new Firecrawl({ 
  apiKey: "fc-your-key",
  apiUrl: "https://your-firecrawl-instance.com"
});
```

```python
# Python SDK
firecrawl = Firecrawl(
    api_key="fc-your-key",
    api_url="https://your-firecrawl-instance.com"
)
```

```csharp
// .NET SDK
var client = new FirecrawlClient(
    apiKey: "fc-your-key",
    apiUrl: "https://your-firecrawl-instance.com"
);
```

### 自定义 HTTP 客户端

```csharp
// .NET SDK - 自定义 HttpClient
var httpClient = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
var client = new FirecrawlClient(
    apiKey: "fc-your-api-key",
    httpClient: httpClient);
```

### 环境变量配置

| 变量名 | 说明 | 用途 |
|--------|------|------|
| `FIRECRAWL_API_KEY` | API 密钥 | 认证 |
| `FIRECRAWL_API_URL` | API 端点 (可选) | 自托管实例 |
| `FIRECRAWL_RATE_LIMIT` | 请求限速 | 避免 API 限流 |

## 相关资源

- [官方文档](https://docs.firecrawl.dev)
- [API 参考](https://docs.firecrawl.dev/api-reference)
- [GitHub 仓库](https://github.com/firecrawl/firecrawl)
- [Firecrawl 官网](https://firecrawl.dev)

---

---

## Doramagic 踩坑日志

项目：firecrawl/firecrawl

摘要：发现 21 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows。

## 1. 安全/权限坑 · 来源证据：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：RFC: Lightweight External Memory Capsule Pattern for Firecrawl Agent Workflows
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0bf31b0e8c3b45fb8da04cebb259c8a4 | https://github.com/firecrawl/firecrawl/issues/3500 | 来源类型 github_issue 暴露的待验证使用条件。

## 2. 安装坑 · 来源证据：v2.4.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v2.4.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e1e417d6cea44fb79118e4daeac083a0 | https://github.com/firecrawl/firecrawl/releases/tag/v2.4.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 配置坑 · 来源证据：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] /interact with language="python" flakily fails with TargetClosedError on scrape-bound sessions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_aa487261676d400197da5f3646baff2f | https://github.com/firecrawl/firecrawl/issues/3498 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 4. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:787076358 | https://github.com/firecrawl/firecrawl | README/documentation is current enough for a first validation pass.

## 5. 运行坑 · 来源证据：[Feat] Emit batch scrape failures of each page to webhook

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[Feat] Emit batch scrape failures of each page to webhook
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_80c638d597cc432b9a74e7e336b043ee | https://github.com/firecrawl/firecrawl/issues/2576 | 来源类型 github_issue 暴露的待验证使用条件。

## 6. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | last_activity_observed missing

## 7. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:787076358 | https://github.com/firecrawl/firecrawl | no_demo; severity=medium

## 8. 安全/权限坑 · 存在安全注意事项

- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:787076358 | https://github.com/firecrawl/firecrawl | No sandbox install has been executed yet; downstream must verify before user use.

## 9. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:787076358 | https://github.com/firecrawl/firecrawl | no_demo; severity=medium

## 10. 安全/权限坑 · 来源证据：[Feat] Support custom HTTP headers in Node.js SDK for self-hosted instances behind reverse proxies

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feat] Support custom HTTP headers in Node.js SDK for self-hosted instances behind reverse proxies
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ef6deffa53c147b29e617225612e55b0 | https://github.com/firecrawl/firecrawl/issues/2814 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 安全/权限坑 · 来源证据：v2.0.1

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.0.1
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_0334c6a4c3284763a02c66ac96ce9c0c | https://github.com/firecrawl/firecrawl/releases/tag/v2.0.1 | 来源类型 github_release 暴露的待验证使用条件。

## 12. 安全/权限坑 · 来源证据：v2.1.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.1.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_360eac170b12452583bb9b7072acc4e3 | https://github.com/firecrawl/firecrawl/releases/tag/v2.1.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 13. 安全/权限坑 · 来源证据：v2.2.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.2.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_749e0e1b86ba455585d343764588f00e | https://github.com/firecrawl/firecrawl/releases/tag/v2.2.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 14. 安全/权限坑 · 来源证据：v2.3.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.3.0
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_e6f1735e34a34eacb7b77e7bb21644a6 | https://github.com/firecrawl/firecrawl/releases/tag/v2.3.0 | 来源讨论提到 npm 相关条件，需在安装/试用前复核。

## 15. 安全/权限坑 · 来源证据：v2.5.0 - The World's Best Web Data API

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.5.0 - The World's Best Web Data API
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4f928a2f370b4186ba4031bc4830020c | https://github.com/firecrawl/firecrawl/releases/tag/v2.5.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 16. 安全/权限坑 · 来源证据：v2.6.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.6.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_38343ea51e374e86a5081e46c837468c | https://github.com/firecrawl/firecrawl/releases/tag/v2.6.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 17. 安全/权限坑 · 来源证据：v2.7.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.7.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4e1fdfc9cb714147a228b5ae01d273f2 | https://github.com/firecrawl/firecrawl/releases/tag/v2.7.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 18. 安全/权限坑 · 来源证据：v2.8.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.8.0
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_dd78eff5694c40cba109ef1230e1dc77 | https://github.com/firecrawl/firecrawl/releases/tag/v2.8.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 19. 安全/权限坑 · 来源证据：v2.9.0

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v2.9.0
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_a6219f53b7de4f31bb8ca1c7109fd49d | https://github.com/firecrawl/firecrawl/releases/tag/v2.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 20. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | issue_or_pr_quality=unknown

## 21. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:787076358 | https://github.com/firecrawl/firecrawl | release_recency=unknown

<!-- canonical_name: firecrawl/firecrawl; human_manual_source: deepwiki_human_wiki -->