前言¶
做竞品监控、价目表同步或联系人补全时，常见做法是写固定选择器抓单页，或自己拼多步脚本翻分页。站点结构一变、要跨多个入口汇总时，维护成本会明显上升。Firecrawl CLI 里的 firecrawl-agent Skill 教编码 Agent 在终端里跑 firecrawl agent：由 AI 自主导航网站，把结果写成 JSON；需要稳定字段时可用 JSON Schema 约束输出。官方说明单次任务大约需要 2–5 分钟，比单页 scrape 慢、也更耗 credits，但适合「没有现成工作流、又要跨页推理」的采集任务。
这是什么¶
firecrawl-agent 是 Firecrawl CLI 仓库 skills/firecrawl-agent 下的一份 SKILL.md 说明，由 Firecrawl 维护。Skill 元数据中的描述是：在任务需要导航网站、或没有合适的现成工作流 / 数据提供方时，自主浏览并跨页提取结构化数据。
它不替代 Firecrawl 服务本身，而是约束 Agent 何时该用 Agent、何时该先用 Alexandria 现成能力，以及如何传参、等结果、控成本。Skill 声明允许的工具为 Bash(firecrawl *) 与 Bash(npx firecrawl-cli *)。
核心功能¶
自主提取与自然语言任务¶
Agent 根据自然语言指令在网站上导航并抽取数据，例如「提取所有定价档位」「提取产品列表」。输出可以是自由形态，也可通过 --schema 绑定 JSON Schema，得到可预测的结构（如 name、price 等字段）。
指定起始 URL¶
可用 --urls 把任务限定在特定页面，减少无关跳转，例如只在某产品页上提取功能列表。
与 Alexandria 的配合¶
在启动自主 Agent 之前，Skill 要求先查是否有现成工作流或数据提供方：
firecrawl search alexandria '<你需要的数据>'
若匹配，用 firecrawl list <provider> <capability> --pretty 查看契约，再用 firecrawl scrape --alexandria <provider>/<capability> --options '<input JSON>' 执行；字段须与契约一致。只有无合适工具或任务必须自主导航时，才继续用 firecrawl agent。
Agent 运行本身也可挂载 Alexandria toolkits（例如 apollo、crunchbase），通过 --toolkits（最多 5 个 slug）、--alexandria、--max-calls 等标志启用；同一线程的后续对话会保留这些设置。
异步任务与轮询¶
省略 --wait 时返回 job ID。可用 UUID 作为位置参数查询状态，或 --wait 配合 --poll-interval、--timeout 等待完成；--cancel 可取消进行中的任务。
花费与审批¶
Skill 注明 Agent 比简单 scrape 消耗更多 credits，可用 --max-credits 封顶。在 --require-approval（且 --mode chat）下，运行可能在付费调用前以 pendingApproval 结束，需在同一线程用 --approve 或 --decline 响应；涉及数据源条款时，组织管理员需在 Firecrawl 控制台接受条款（Skill 给出设置页链接）。
安装与启用¶
CLI 全局安装：
npm install -g firecrawl-cli
或一条命令完成安装、认证，并向检测到的编码编辑器安装 skills（含 Cursor）：
npx -y firecrawl-cli@latest init -y --browser
-y 为非交互；--browser 自动打开浏览器完成 Firecrawl 认证。也可只装核心 CLI skills（含 agent 相关能力）：
firecrawl setup core
单独安装某个 skill 时，firecrawl- 前缀可省略。仅面向 Cursor 时可加 --agent cursor，例如：
firecrawl init --agent cursor
firecrawl setup skills --agent cursor
首次无 API key 时，CLI 会提示浏览器登录或手动输入；也可设置环境变量 FIRECRAWL_API_KEY，或执行 firecrawl login --api-key fc-your-api-key。自托管实例可用 --api-url 或 FIRECRAWL_API_URL（非默认 https://api.firecrawl.dev 时可无需 API key，以官方 CLI 文档为准）。
Skill 文件位置：https://github.com/firecrawl/cli/tree/main/skills/firecrawl-agent。社区索引（如 awesome-agent-skills）把此类条目归类为教 Agent 按需加载的 SKILL.md 说明，与 Claude Code、Cursor、Codex 等 harness 兼容；具体加载方式因平台而异，Firecrawl 侧以 init / setup 写入检测到的编辑器为主。
典型用法¶
下面示例均来自官方 Skill 文档，可直接在已认证的环境中复现。
基础：等待完成并写入 JSON 文件¶
firecrawl agent "extract all pricing tiers" --wait --json -o .firecrawl/pricing.json
--wait 表示在当前终端等到结果；-o 指定输出路径。完成标准：输出文件为能回答请求的合法 JSON，或你刻意省略 --wait 而只拿 job ID 供后续轮询。
用 JSON Schema 约束结构¶
firecrawl agent "extract products" --schema '{"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}' --wait --json -o .firecrawl/products.json
未提供 --schema 时，Agent 返回自由形态数据，下游解析成本更高。
限定页面¶
firecrawl agent "get feature list" --urls "<url>" --wait --json -o .firecrawl/features.json
将 <url> 换成目标地址。
结合 Alexandria toolkits¶
firecrawl agent "find the head of sales at <company>" --toolkits apollo,crunchbase --wait --json -o .firecrawl/contacts.json
异步与状态查询¶
firecrawl agent "<job-id>"
firecrawl agent "<job-id>" --wait --poll-interval 10 --timeout 300
firecrawl agent "<job-id>" --cancel
完整选项列表以 firecrawl agent --help 为准。
适用场景与注意¶
更适合：
- 需要跨页点击、汇总列表或详情，且没有 Alexandria 契约可覆盖的任务。
- 希望 Agent 在编码会话里直接产出 JSON，接入 RAG、ETL 或内部工具链。
- 字段形状已知，用
--schema固定输出，便于校验与入库。
应先考虑其他 Skill / 命令：
- 单页、静态内容：官方建议优先
firecrawl scrape（更快、更便宜），对应 Skill firecrawl-scrape。 - 需要人工式页面交互： firecrawl-interact。
- 大批量、无 AI 的站点遍历： firecrawl-crawl。
- 把结构化抽取写进应用代码： firecrawl-build-scrape。
限制与成本：
- 单次 Agent 通常 2–5 分钟，不适合亚秒级实时接口。
- Credits 消耗高于 scrape，务必用
--max-credits设上限。 - 有现成 provider/capability 时，先 Alexandria 再 Agent，可避免重复造轮子。
结尾¶
firecrawl-agent 把「自主导航 + 结构化抽取」收敛成 Agent 可执行的终端流程：先搜 Alexandria，再决定是否开 Agent，并用 Schema、URL 限定和 credits 上限控制风险。要在 Cursor 等环境里启用，安装 Firecrawl CLI 后执行 init 或 setup core，并保证 API 认证就绪。官方 Skill 路径：https://github.com/firecrawl/cli/tree/main/skills/firecrawl-agent。
