前言¶
做競品監控、價目表同步或聯繫人補全時，常見做法是寫固定選擇器抓單頁，或自己拼多步腳本翻分頁。站點結構一變、要跨多個入口彙總時，維護成本會明顯上升。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。
