前言¶

給 Agent 或後端加「聯網取數」時，常見卡點不是會不會調 HTTP，而是每次都要重新決定：已經有 URL 該直接抓，還是先搜再抓？頁面要點擊、填表才能露出內容怎麼辦？密鑰放哪、用哪套 SDK、怎麼證明這條鏈路真的通了？文檔散落在各語言 SDK 裏，Agent 很容易把「當前會話裏幫我搜一下」和「把 Firecrawl 寫進產品代碼」混成同一件事。

Firecrawl 官方把後一條路徑收成了 Agent Skill。倉庫 firecrawl/skills 面向的是「在應用裏調用 Firecrawl API」，入口技能就是 firecrawl-build：先問產品要從網上拿什麼、怎麼拿，再把需求路由到 /scrape、/search 或 /interact，而不是讓模型現場發明一套抓取流程。

本文按該 Skill 的 SKILL.md、倉庫 README，以及 docs.firecrawl.dev/ai-onboarding 交叉覈對後，說明它是什麼、覆蓋哪些能力、怎麼安裝，以及和 CLI 技能的邊界。

這是什麼¶

firecrawl-build 是 Firecrawl 維護的 應用集成入口 Skill，位於 github.com/firecrawl/skills 的 skills/firecrawl-build/。當前元數據版本爲 0.1.0，許可爲 ISC，主頁是 firecrawl.dev。倉庫遵循 Agent Skills 的 SKILL.md 格式，並作爲插件提供給 Claude Code、Cursor 和 OpenAI Codex。

官方一句話定位是：當產品、Agent 或工作流需要在應用內部獲取網頁數據——搜索、即時檢索結果、頁面抓取、結構化提取或瀏覽器交互——時，把 Firecrawl 接到代碼裏。即便用戶沒點名 Firecrawl，只說「應用裏要網頁內容 / 搜索 / 抓取 / 交互」，也應走這條技能。

它解決的是路由和落地問題，而不是替代 SDK 文檔。SKILL.md 寫得很清楚：這些技能說明 何時、爲什麼 用某個端點；怎麼調 要以各語言的 source-of-truth 頁面爲準。

核心能力¶

1. 先選端點，再寫集成代碼¶

入口技能要求先回答一個問題：這個產品要從網上拿什麼數據，以及怎麼拿？ 然後選最窄的端點：

默認優先級是：先 /scrape，再 /search，最後才 /interact。已知 URL 就不要先搜；頁面能直接讀，就不要上瀏覽器動作。

官方給出的三種產品形態也對應這三端：

• 已知 URL → 抽內容：文檔導入、競品定價頁、檢索管道的內容灌入，走 /scrape
• 查詢 → 發現 → 再抽：帶新鮮來源的問答、競品發現、先出 URL 短名單的調研，走 /search；只有產品確實需要全文時纔跟抓
• 抓取 → 交互 → 再抽：要點開摺疊、走表單搜索、翻頁、帶登錄態的後臺，才升級到 /interact

2. 傘形技能，細節交給更窄的兄弟 Skill¶

firecrawl-build 自己不展開每個端點的實現細節，而是把任務分給同倉庫裏的專項技能。當前倉庫 skills/ 目錄裏實際存在的是：

論文索引和開發者索引 不會 被 /search 查到。/search 上的 categories: ["research"] 或 ["developer"] 只是按域名過濾普通網頁結果，不會做摘要檢索、相關論文擴展或全文段落召回。需要索引能力時，應轉到對應的 index 技能，而不是給 /search 加一個 category 就當論文庫用。

部分文檔頁還提到 /crawl、/map、/parse 等更廣的 API。就 firecrawl-build 這份 SKILL.md 和當前倉庫目錄而言，入口路由表覆蓋的是上面三端點加兩個索引；寫集成時以倉庫裏的技能清單爲準。

3. 和應用內集成有關，和「現在幫我搜一下」無關¶

官方把 Firecrawl 的 Agent 能力拆成三條線，同一條安裝命令可以一次裝齊，用的時候必須分開：

• CLI 技能（firecrawl/cli）：當前會話裏的現場聯網——搜網頁、抓一頁、和站點交互、爬整站
• Build 技能（本倉庫）：把 Firecrawl 寫進應用代碼
• Workflow 技能（firecrawl/firecrawl-workflows）：產出研究報告、SEO 審計、線索名單這類成品，而不是產品代碼

firecrawl-build 的觸發條件是「給應用加網頁數據能力」，不是「現在用終端幫我搜 / 抓一頁」。後一類應使用 firecrawl/cli。

安裝與啓用¶

官方推薦一條命令同時裝 CLI、Build 和 Workflow 三段技能，並打開瀏覽器登錄：

npx -y firecrawl-cli@latest init --all --browser

文檔說明：--all 會把各段技能裝到本機檢測到的每個 AI 編程代理上；--browser 自動打開 Firecrawl 鑑權。裝完後需要重啓代理，它纔會發現這些技能。可用下面兩條做安裝側檢查：

firecrawl --status
firecrawl scrape "https://firecrawl.dev"

只裝本倉庫（應用集成技能）可以用：

npx skills add firecrawl/skills

只裝入口技能時，officialskills.sh 給出的命令是：

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

也可以把倉庫目錄貼給編程助手，讓它按 Agent Skills 流程安裝。Claude Code 側有資料寫明：加 --agent claude-code 時，技能會進當前項目的 .claude/skills/。Cursor 和 Codex 在倉庫 README 裏以 .cursor-plugin/、.codex-plugin/ 插件形式提供；具體落到本機哪個目錄，以安裝命令和對應工具文檔爲準，不要憑空猜路徑。

已經裝過、之後只想補技能時，CLI 文檔還提供：

firecrawl setup skills      # CLI + build skills
firecrawl setup workflows   # workflow skills

倉庫 README 同時提到：插件裏帶有官方 Firecrawl MCP server 的配置，支持捆綁 MCP 元數據的編輯器可以用 FIRECRAWL_API_KEY 接上工具。這是插件附帶能力，不是 firecrawl-build 本身的調用方式。

密鑰、SDK 與集成順序¶

託管服務需要環境變量（不要寫進源碼）：

FIRECRAWL_API_KEY=fc-...

自建實例再加（僅當不用 https://api.firecrawl.dev 時）：

FIRECRAWL_API_URL=https://your-firecrawl-instance.example.com

密鑰可在 firecrawl.dev/app 獲取。還沒有密鑰時，應先走 firecrawl-build-onboarding，它自帶瀏覽器授權，不依賴網站上的另一份 onboarding 技能。

SDK 要和項目語言對齊。現有倉庫應先看包管理器和已有第三方客戶端的放法，再決定裝 SDK 還是直接 REST：

npm install @mendable/firecrawl-js

pip install firecrawl-py

官方還爲 Rust、Java、Elixir 以及 cURL / REST 提供了 source-of-truth 頁。語言沒有對應 SDK、或項目已有統一的 HTTP 封裝時，可以直接打 REST。

默認集成順序在 SKILL.md 裏寫死了，不宜跳步：

1. 先把 FIRECRAWL_API_KEY 或 FIRECRAWL_API_URL 配對
2. 判斷是新項目還是已有代碼庫
3. 問清產品要的網頁數據行爲，再選端點
4. 已有項目先摸清約定，再動手
5. 安裝對應 SDK，或走 REST
6. 寫代碼前讀該語言的 source-of-truth
7. 端點細節交給更窄的技能
8. 用一次真實請求做冒煙測試，而不是隻看代碼能編譯

新項目路徑：確認技術棧 → 裝 SDK / 配環境變量 → 寫最小可用調用 → 冒煙。已有項目路徑：先看語言、包管理器、目錄結構、入口（路由 / worker / 任務）、現有網絡封裝和密鑰管理，再問「Firecrawl 在這個產品裏做什麼」，最後按倉庫慣例接入。

典型用法¶

下面的調用示例來自官方 Python source-of-truth（SDK 文檔標註對應 firecrawl-py / firecrawl 4.22.1）。Skill 本身強調：參數和返回結構以該頁爲準，不要靠模型記憶。

先建客戶端：

import os
from firecrawl import Firecrawl

client = Firecrawl(api_key=os.environ.get("FIRECRAWL_API_KEY"))

已經有 URL，抽一頁 Markdown（/scrape，也是冒煙測試的最小請求）：

doc = client.scrape("https://docs.firecrawl.dev", formats=["markdown"])

從查詢發現頁面（/search）。注意返回值是 web / news / images 幾個桶，不是 { data: [...] }：

results = client.search("site:docs.firecrawl.dev webhook retries")
for item in results.web or []:
    print(getattr(item, "url", None), getattr(item, "title", None))

頁面必須再操作時，先 scrape，再用返回的 scrape_id 調 /interact：

doc = client.scrape("https://example.com", formats=["markdown"])
job_id = doc.metadata.scrape_id if doc.metadata else None
if not job_id:
    raise RuntimeError("Missing scrape_id from scrape response")

result = client.interact(job_id, prompt="Click the pricing tab and summarize the plans.")

在對話裏觸發入口技能，官方描述的典型說法包括：給應用加網頁數據、產品裏要搜索、工作流裏要抓頁面、應用要和站點交互。Agent 應先做 intake（新項目還是舊項目、數據從哪來、怎麼拿），再落到具體端點，而不是直接生成一長串爬蟲。

冒煙測試的標準在 references/verification.md：新項目用最小請求證明鑑權、網絡和 SDK 接線（/scrape 抓一個已知 URL，或 /search 帶 limit=1，或 /interact 從 scrape 再做一個最小動作）；已有項目要在真實入口（應用、worker 或腳本）裏打通一次，並確認密鑰來自預期的環境來源。一次真實請求成功、結果回到業務路徑，纔算完成。

適用場景與注意事項¶

適合這些情況：

• 後端、Agent 工具或自動化流程要從代碼裏拿網頁數據
• 新功能要在「搜 / 抓 / 交互」裏做選擇，而不是先寫一套自建爬蟲
• 需要把密鑰、SDK、倉庫慣例和冒煙測試一次做對
• Node / Python / Go 等後端裏接入 Firecrawl（Go 可走 REST；Node、Python 有官方 SDK）

不適合、或應改走別的技能：

• 當前會話裏一次性的「幫我搜 / 幫我抓這一頁」——用 firecrawl/cli
• 目標是研究報告、SEO 審計、線索名單等成品——用 workflow 技能
• 論文或開發者資料庫檢索——分別用 firecrawl-research-index、firecrawl-developer-index，不要當成普通 /search

使用時要注意：

• 不要硬編碼密鑰。 放 .env 或部署平臺的密鑰管理裏。
• 現有項目先看倉庫再裝依賴。 Skill 要求匹配已有包管理器和第三方客戶端的位置，而不是圖省事新建一套。
• /interact 保持最小。 官方建議只覆蓋解鎖數據所需的最短瀏覽器流程；完全開放的瀏覽器自動化，可能更適合單獨的瀏覽器沙箱，而不是硬塞進 /interact。
• 緩存與新鮮度。 firecrawl-build-scrape 寫明 Firecrawl 會複用近期索引，重複讀同一 URL 更快；需要更新鮮時用 maxAge（毫秒），maxAge: 0 跳過索引複用。成功響應裏的 metadata.cacheState / metadata.cachedAt 表示實際拿到的是哪份副本。
• Skill 不是 SDK 手冊。 請求體、響應字段、參數名以 docs.firecrawl.dev/agent-source-of-truth 對應語言頁爲準。例如 Python 的 search() 結果在 result.web，去讀 result.data 會錯。
• 文檔清單若和倉庫不一致，以倉庫爲準。 個別 onboarding 頁面列出過 firecrawl-build-crawl 等目錄裏目前不存在的名字；集成時對照 GitHub 上的 skills/ 目錄。

小結¶

firecrawl-build 是 Firecrawl 官方給「把網頁數據寫進產品」準備的入口技能：先問清需求，再把功能映射到 /scrape、/search 或 /interact，並把密鑰、SDK、倉庫慣例和一次真實請求的冒煙測試串成固定順序。它和 firecrawl/cli 共用安裝命令，但職責相反——一個改產品代碼，一個服務當前會話。

官方地址：

• Skill 目錄：https://github.com/firecrawl/skills/tree/main/skills/firecrawl-build
• 倉庫：https://github.com/firecrawl/skills
• 安裝說明鏡像：https://officialskills.sh/firecrawl/skills/firecrawl-build
• Agent 接入總覽：https://docs.firecrawl.dev/ai-onboarding