firecrawl-agent

firecrawl-agent skill 概览

firecrawl-agent 能做什么

firecrawl-agent skill 适合处理普通单页抓取不够用的自主式网页数据提取。它的设计目标是：能够在网站内自行导航、判断相关信息分布在哪些页面，并输出结构化 JSON。尤其适合价格表、产品目录、名录条目、功能清单这类任务。

最适合哪些用户

这个 firecrawl-agent skill 最适合那些需要“可直接使用的数据”而不是原始 HTML 的人：构建数据集的运营人员、收集竞品或市场信息的分析师、要把结果送入后续自动化流程的开发者，以及希望按 schema 做多页提取、而不是临时复制粘贴的 AI 用户。

真正要解决的任务是什么

大多数用户并不是在抽象地寻找“web scraping”。他们真正想解决的是一些明确问题，例如：

• 提取某个 SaaS 网站的所有价格档位
• 跨多个页面收集产品名称和价格
• 把一个目录站点整理成 JSON 记录
• 不用手动逐个映射 URL，就能收集结构化事实

这正是 firecrawl-agent for Web Scraping 与泛化 prompt 有明显区别的地方。

为什么选择 firecrawl-agent，而不是普通 prompt

普通模型 prompt 可以帮你建议 selector，或者总结页面上可见的内容，但通常不能稳定完成跨多页面的自主提取流程。firecrawl-agent 就是围绕这个场景设计的：你给它一个提取目标，可以选择性提供 schema，然后让它自己导航并返回可供机器直接使用的输出。

安装前必须知道的关键权衡

它的优势是减少逐页手工处理的工作量。代价是运行时间：agent 可能需要几分钟，而且输出质量很大程度取决于你是否把目标字段和范围定义清楚。如果你的需求只是“快速抓一页”，那它可能比你真正需要的更重。

如何使用 firecrawl-agent skill

firecrawl-agent 的安装前提

上游 skill 支持通过 Bash 调用 firecrawl，包括 firecrawl agent 和 npx firecrawl。如果你要把它安装到基于 skills 的环境中，可使用：

npx skills add https://github.com/firecrawl/cli --skill firecrawl-agent

实际使用时，你还需要在环境里能用 Firecrawl CLI，并完成该 CLI 所要求的认证或初始化配置。

先看这个文件

先从 skills/firecrawl-agent/SKILL.md 开始。在这个仓库里，这个文件几乎包含了所有实用指导。这个 skill 看起来没有明显的 rules/、resources/ 或辅助脚本，所以你是否要安装，主要应看其中的示例和 CLI 选项是否契合你的工作流。

理解 firecrawl-agent 的主要调用方式

核心的 firecrawl-agent usage 模式很简单：

1. 描述提取目标
2. 可选：提供 schema
3. 可选：用起始 URL 限定范围
4. 等待任务完成
5. 把 JSON 输出保存到文件

该 skill 中的典型示例：

firecrawl agent "extract all pricing tiers" --wait -o .firecrawl/pricing.json

firecrawl agent "extract products" --schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}' --wait -o .firecrawl/products.json

firecrawl agent "get feature list" --urls "<url>" --wait -o .firecrawl/features.json

这个 skill 需要什么输入

firecrawl-agent skill 在以下三点明确时效果最好：

• 提取目标
• 目标网站或起始 URLs
• 你希望得到的输出结构

较弱的输入：

• “scrape this site”

更强的输入：

• “Extract all pricing tiers from https://example.com/pricing and related plan pages. Return plan name, monthly price, annual price, included seats, and top features as JSON.”

最佳输入：

• “Starting from https://example.com/pricing, extract every current pricing tier visible on the site. Return JSON with plans[] containing name, billing_period, price, currency, seat_limit, features[], and source_url. Ignore blog pages, docs, and historical changelog content.”

什么情况下要用 schema

当你的输出需要进入代码、表格、校验流程或可重复执行的工作流时，就应该用 --schema。schema 在以下场景尤其重要：

• 字段名必须保持稳定
• 你需要 number、array 之类的类型化值
• 你希望减少含糊不清的总结式输出
• 你打算在不同运行结果或不同网站之间做比较

没有 schema，agent 仍可能工作得不错，但对后续自动化来说，结果往往没那么可预测。

如何把模糊目标改写成好 prompt

一个高质量的 firecrawl-agent guide prompt 通常会包含：

• 目标实体类型：plans、products、listings、locations
• 覆盖规则：抓取所有当前有效项目，而不是示例
• 排除项：忽略 docs、blog、careers、changelog
• 归一化要求：价格返回为数字、每个项目一条记录
• 来源追踪：包含 source_url
• 边界情况策略：字段缺失时返回 null

示例：

firecrawl agent "Extract all products from the site. Return JSON with products[] containing name, price, currency, short_description, category, availability, and source_url. Only include live product pages. Ignore blog, support, and policy pages. If price is missing, use null." --urls "https://example.com" --wait -o .firecrawl/products.json

用起始 URL 减少结果漂移

如果你不提供 URL，agent 在决定去哪里探索时会有更大自由度。这在某些情况下有帮助，但也会明显增加无效导航的概率。为了获得更高精度，建议优先提供高概率入口页面，例如：

• pricing pages
• product category pages
• company directories
• marketplace listings

在真实工作中，这往往是决定 firecrawl-agent install 成败的最高杠杆改进之一。

提高提取稳定性的推荐工作流

一个实用流程是：

1. 先在一个高概率源页面上做小范围测试
2. 检查 JSON 是否有字段缺失或字段被混合合并
3. 加上 schema 和排除规则
4. 再扩展到更广的起始 URLs
5. 将输出保存到专用目录，例如 .firecrawl/
6. 校验数量，并抽样核对源页面

相比一开始就大范围抓取、然后再调试一堆噪声结果，这种流程通常更快。

输出处理与文件命名策略

使用 -o 把结果写入固定路径。这很重要，因为自主提取任务在做版本管理或长期对比时，更容易评估质量。好的示例包括：

• .firecrawl/pricing.json
• .firecrawl/products.json
• .firecrawl/directory.json

如果你在反复迭代，最好让文件名能直接体现本次运行目的，而不是一直覆盖一个泛泛的 output.json。

实际适配：它最擅长什么

firecrawl-agent for Web Scraping 最强的使用场景通常是：

• 目标数据分布在多个页面
• 网站结构事先并不完全清楚
• 你需要的是结构化 JSON，而不是文字总结
• 如果手写抓取规则，投入成本会高于这次提取任务本身

实际不适配：什么情况下不该用

以下情况建议跳过 firecrawl-agent：

• 你只需要总结一个页面
• 合规要求很高，必须依赖精确且确定性的 selector
• 你已经有一个针对已知页面结构、稳定可用的 scraper
• 网站高度交互、存在访问门槛，或依赖你当前环境不支持的会话型流程

firecrawl-agent skill 常见问题

firecrawl-agent 适合新手吗？

适合，前提是你已经会用 CLI，并且能按“输出字段”来思考任务。基础示例并不难。新手真正的门槛通常不在安装命令，而在于能否把提取目标说完整，而不是模糊地下指令。

firecrawl-agent 和普通 AI prompting 的区别是什么？

普通 prompt 往往停留在分析层，或者只是处理单页的临时内容。firecrawl-agent usage 的核心则是“自主网站导航 + 结构化提取”。正是这两者的组合，让它值得替代泛泛的“总结这个网站”请求。

我每次都需要 JSON schema 吗？

不需要。做探索性工作时，直接提出提取请求通常就够了。但如果你需要跨多次运行保持一致、接入自动化流程，或者希望字段类型更干净，schema 通常值得多花这一分钟。

firecrawl-agent 需要多久？

该 skill 提到，自主提取通常可能需要约 2 到 5 分钟。相比简单的单页抓取，你应预期它的任务时间更长，尤其是在目标网站包含大量相关页面时。

firecrawl-agent 能提取价格、产品或目录信息吗？

可以。这正是该 skill 的核心定位：价格档位、产品列表、目录型条目，以及分布在整个网站中的其他结构化记录。

firecrawl-agent 适合所有 scraping 任务吗？

不适合。如果任务本身很简单、规则明确，或者已经能被传统 scraper 覆盖，那么这个 skill 可能没有必要。它最有价值的地方在于：问题本身不仅是提取，还包括发现与导航。

如何进一步用好 firecrawl-agent skill

给 firecrawl-agent 一个更清晰的提取合同

质量提升最明显的一步，通常是把 prompt 从“extract data”升级为一个明确合同，包含：

• 精确字段
• 包含规则
• 排除规则
• 缺失值处理方式
• source URL 记录

这样可以减少“凭空补结构”的情况，也让结果更容易信任。

先收紧范围，再逐步扩大

很多效果差的运行，问题都出在一开始就从域名根路径出发、目标还很宽泛。更好的做法是：先从一两个高信号 URL 开始，确认字段质量，再在 schema 和 prompt 已经工作稳定后逐步扩大覆盖范围。

每条记录都要求来源信息

如果你希望后续能复核或排错，请在每条记录里要求 source_url。这个单一字段会让 firecrawl-agent guide 的整个工作流轻松很多，因为你可以迅速验证提取出的记录到底是不是来自正确页面。

统一那些最容易变化的字段

明确告诉 agent 如何处理现实网站里常见的脏差异：

• price 用数字还是字符串
• monthly 与 annual billing 如何表示
• feature list 用数组返回
• 缺失字段返回 null
• 每个 product 或 plan 只保留一条记录

这些约束会显著提升结果的机器可读性。

注意常见失败模式

典型问题包括：

• 一个数据集里混入多种页面类型
• 变体页面造成重复记录
• 功能摘要被合并成一整块文本
• 价格被抓成文本碎片，而不是数值
• 起点过宽或过弱，导致站点覆盖不完整

这些问题大多不是靠重复执行同一个模糊命令就能解决的，而是要靠更强的范围约束和 schema 设计。

基于输出缺陷迭代，而不是只盯着“量不够”

如果第一次运行结果不对，不要只想着“多抓点页面”。先明确问题属于哪一类：

• 字段错了
• 页面类别错了
• 有重复
• 缺少归一化
• 覆盖不完整

然后围绕这个具体缺陷直接修改 prompt。这通常是改进 firecrawl-agent 结果最快的方法。

一个有效的二次修订模式

很实用的第二轮 prompt 模式是：

• 保持原目标不变
• 增加排除项
• 收紧字段定义
• 要求来源追踪
• 明确缺失值处理方式

修订示例：

• first run: “extract all pricing tiers”
• second run: “Extract all current pricing tiers from pricing and plan pages only. Ignore docs, blog, changelog, and legacy pages. Return plans[] with name, price, currency, billing_period, features[], and source_url. Use null when a field is not present.”

先检查一个问题，再决定要不要安装

在采用 firecrawl-agent skill 之前，先问自己：你的真实瓶颈到底是“发现并导航到正确页面”，还是“把已知页面格式化提取出来”？如果难点在于跨多个页面做导航发现，这个 skill 就非常契合；如果不是，使用更简单的 scrape 或单页提取工具，往往会更快，也更容易维护。