给 AI Agent 喂本地 PDF 也能一站搞定:Firecrawl v2.10 文件解析与安全抓取

文件解析 · 锁定模式 · 语义提取 · v2.10 —— Firecrawl 在本版把能力边界从「网页采集」拓展到了「本地文档解析 + 安全索引查询」， AI Agent 从此能用同一个 API 同时处理离线文件和在线网页—— 数据接入的一次性对齐，远比拼凑多条 Pipeline 来得省心。

从网页采集器到全能数据管道

Firecrawl 是一个开源的 Web 数据 API 服务，专为 AI 应用设计。它将网页抓取（scrape）、站内全量爬取（crawl）、URL 发现（map）和搜索引擎（search）统一封装成一个接口，直接输出 Markdown 或结构化 JSON——AI Agent 拿来就能用，不用写正则、不用管反爬、不用处理 JS 动态渲染。

底层架构分为三个关键层：Playwright 浏览器服务处理 JS 页面渲染、 Go 编写的 HTML-to-Markdown 转换服务、以及 Redis 队列与并发控制层。 SDK 覆盖 Python、Node.js、Go、Ruby、PHP、.NET、Rust、Java 和 Elixir 九种语言，MCP 协议也原生支持。截至 v2.10， GitHub Stars 超过 121K，社区活跃度在同类工具中位居前列。

Agent 处理文档为何两头操心

构建一个能自主工作的 AI Agent，通常会遇到两个难以绕开的中间环节。

数据来源割裂。网页信息用 scrape 接口能一键获取，但用户同时上传的 PDF 报告、Word 合同或 Excel 表格，Agent 得另起炉灶——下载到本地、找解析库、再丢给 LLM。Pipeline 一旦断开，维护两套解析逻辑的成本远比看上去大。

一个 API 收编本地文件与精准提取

本地文件一键解析

新增的 POST /v2/parse 端点接受 multipart 格式上传，支持 PDF、 DOCX、DOC、ODT、RTF、XLSX、XLS 和纯 HTML，单文件上限 50 MB。上传后返回和 scrape 一致的 Document 结构：Markdown、JSON 或摘要文本。表格保留行列关系，阅读顺序无损，Zero Data Retention 模式对企业可用。

from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-xxx")
result = app.parse(file_path="/path/to/report.pdf")
print(result["markdown"])

锁定模式：零出站查询

/scrape 新增 lockdown: true 参数。开启后所有请求仅命中 Firecrawl 自有索引，不产生任何外部 HTTP 请求—— 包括 robots.txt 检查、音频下载和第三方 CDN 资源。缓存未命中返回 404，每请求 4 积分，命中仅 1 积分。这个模式适合金融、医疗等对数据出口有严格合规要求的团队。

智能问答与高亮提取

Scrape endpoint 新增两个 format 选项：

• question：传入自然语言问题，返回基于页面内容的 grounded 答案，含引用来源。每次调用对比全页面抓取可节省约 100 倍 token

• highlights：返回与查询匹配的精确句子、代码块和表格行。连续句子自动合并为段落，代码块保持原语言高亮，表格行还原为 Markdown 表格

两个格式都由托管模型链驱动，含自动回退、提示注入隔离（零宽度空格转义）和 XML 标记包装。

此外新增 video format，返回 YouTube 等平台的签名下载链接，Cookie 转发支持认证下载。

搜索增强与 SDK 矩阵补齐

/search 新增 includeDomains / excludeDomains 域名过滤，以及搜索反馈评分接口 POST /v2/search/:jobId/feedback—— 每条被采纳的评分返还 1 积分。

官方 SDK 在本版一口气补齐 Go、Ruby、PHP、.NET，并将 Rust SDK 升级为首方正式版，实现九种语言的 v2 API 全覆盖。

Elixir SDK 同步新增 parse_file/3 方法，JS SDK 增加了显式请求超时配置以防止长时间挂起。

安全性方面，v2.10 修复了涉及 axios、postcss、fast-xml-parser、 protobufjs 等多个依赖的 CVE，同时修复了 Playwright 服务忽略调用方 User-Agent 头部的问题。

多服务编排与零数据泄漏设计

/parse 的实现逻辑并不简单——上传的文件被 multer 中间件接收后，路由层校验收敛度：不允许 screenshot、actions、branding 等与文件解析不兼容的 scrape 选项（非法请求返回 PARSE_UNSUPPORTED_OPTIONS 错误）。通过校验的文件经 document converter 服务统一转为 HTML，最后走现有 html-to-markdown 管线输出。这意味着 parse 复用了主流程中经过生产验证的转换质量，而不是另起一套解析逻辑。

Lockdown 模式在请求入口处增设了一道门。授权后的 lockdown 标记沿整个请求链传递——HTTP 抓取、robots.txt 解析、音频与视频媒体下载被逐层阻止，且计费系统自动等价于 Zero Data Retention。当缓存未命中时，响应层在出口侧抛出结构化的 SCRAPE_LOCKDOWN_CACHE_MISS 错误码。

question 与 highlights 两个 format 则依赖 generic-ai.ts 中的托管模型链。该链具备自动回退能力——首选模型降级到备用模型时对调用方透明；同时通过 XML 标签隔离用户输入与系统指令，减少提示注入风险。

从 v2.9 到 v2.10 的版本过渡也值得注意：所有 /v0 和 /v1 端点已正式标记废弃（但未下线），响应头附带 Deprecation: true 和 Link; rel="successor-version"，JS 和 Python SDK 会向客户端告警。如果你的 Agent Pipeline 仍依赖旧版接口，建议在 v2.11 发布前完成迁移。