前言¶

給應用接網頁數據時，很容易把「搜」和「抓」混成同一步。用戶問的是「競品最近改了什麼定價」「這個庫現在怎麼配 retries」，手裏並沒有現成 URL。這時如果直接調抓取接口，流程會卡在「還沒有地址」；反過來，如果只拿搜索摘要就生成答案，引用往往對不上正文。

搜索和抓取是兩條不同的數據管道。前者從查詢出發，負責發現、排序和挑源；後者從已知 URL 出發，負責把頁面變成 Markdown 或結構化字段。Firecrawl 官方把這條分界寫進了一組 Agent Skill：總入口是 firecrawl-build，專門處理「查詢優先」的窄技能則是 firecrawl-build-search。

這是什麼¶

一句話定位：firecrawl-build-search 指導 AI 編程助手把 Firecrawl 的 /search 接到產品代碼裏——功能從查詢開始，而不是從 URL 開始；需要時可以在同一次調用裏給結果補上頁面正文（官方文檔把這叫通過 scrapeOptions 抓取搜索結果，Skill 文案裏對應「optional hydrate」）。

它由 Firecrawl 維護，源碼在 firecrawl/skills 倉庫的 skills/firecrawl-build-search。SKILL.md 的 frontmatter 寫明：

name：firecrawl-build-search
version：0.1.0
license：ISC
author：firecrawl
homepage：https://www.firecrawl.dev

目錄裏目前只有這一份 SKILL.md，沒有附帶腳本或 references/。它不替代 API 手冊，而是告訴 Agent：什麼時候該用 /search，什麼時候不該用，集成時該去讀哪份語言文檔。

需要先分清同一生態裏的幾套技能，避免裝錯、用錯：

倉庫 / Skill	解決什麼
`firecrawl/cli` 的 CLI skills	當前會話裏搜網頁、抓頁面（終端一次性任務）
`firecrawl-build`	把 Firecrawl 寫進應用的傘形技能：選型、鑑權、路由到具體端點
`firecrawl-build-search`（本文）	已經確定產品行爲是「先發現再抽取」時，專門接 `/search`
`firecrawl-build-scrape`	已經有 URL，做單頁抽取
`firecrawl-build-interact`	抓完之後還要點擊、填表、多步導航

官方 README 寫得很直：任務是「現在幫我搜一下 / 抓一下」走 CLI skills；任務是「把 Firecrawl 加進這個代碼庫」走 build skills。firecrawl-build-search 屬於後者。

核心功能與亮點¶

根據官方 SKILL.md、倉庫 README，以及作爲調用事實源的 Search 文檔和 Node 源文檔，能力可以收成下面幾條。

1. 觸發條件：起點是查詢，不是 URL¶

Skill 要求在這些情況下使用 /search：

用戶提出問題，產品必須先發現來源
功能需要當前網頁結果
要把搜索詞變成一份後續可抓取的頁面短名單

一句話：URL discovery 是產品行爲的一部分時，先 /search。已經拿到具體地址，就不要繞這一步，改走 firecrawl-build-scrape。

2. 搜索與抽取默認分開，水合是可選項¶

默認建議有三條：

URL 發現屬於產品行爲時，先調 /search
概念上把搜索和抽取分開，除非明確需要把搜索結果頁本身也抓下來
成本和延遲敏感時，優先「先挑 URL，再選擇性抽取」，而不是對全部命中做寬泛水合

對應到 API：不帶 scrapeOptions 時，/search 返回標題、描述和 URL；加上 scrapeOptions（例如 formats: ["markdown"]）纔會在同一次調用裏帶上正文。官方 Search 文檔把這兩種做法寫成：

一步：搜索請求裏帶 scrapeOptions，適合「每個結果都要正文」
兩步：先 search，過濾後再對選中的 URL 調 /scrape，適合要篩選、排序、控制費用的場景

Skill 明確偏向後者，除非產品真的需要全量正文。

3. 把 `/search` 當成發現、排序和選源¶

實現備註要求 Agent：

把 /search 當作 discovery、ranking 和 source selection
寫清楚產品要的是 snippet、URL 列表，還是完整頁面內容
保持查詢契約穩定，這樣後面的 scrape 邏輯纔可預期

常見產品形態（均來自 Skill，不是自行編的案例）包括：帶引用的回答生成、公司 / 競品 / 主題發現、先產出網頁短名單再深挖的調研流、查詢到 URL 再交給 /scrape 或 /interact 的管道。這裏的「research workflow」指的是發現網頁；搜論文是另一條面，見下文升級規則。

4. 升級規則寫死，避免用錯索引¶

Skill 把幾條容易混的路標寫進了 escalation：

已經有 URL → firecrawl-build-scrape
結果頁還要點擊或填表 → firecrawl-build-interact
要搜的是已發表論文（生物醫學 / 臨牀 / 生命科學文獻，PubMed、bioRxiv、medRxiv，或 arXiv 預印本）→ firecrawl-research-index。給 /search 傳 categories: ["research"] 不會打到論文索引，它只是把普通網頁搜索限制到研究類站點（列表裏包含 PubMed、bioRxiv、medRxiv、arXiv 和出版商站點），返回的是頁面結果，沒有摘要檢索、相關論文擴展或全文段落
要從 Issue、PR、README 或文檔頁回答開發問題 → firecrawl-developer-index。categories: ["developer"] 同樣有上述「不是專用索引」的限制

Search 功能文檔與這條規則一致：research 是網站過濾器，不是論文庫。

5. 具體怎麼調 API，以語言文檔爲準¶

Skill 不內嵌 SDK 參數表，而是要求寫集成代碼前先讀對應語言的 source-of-truth 頁：

Node / TypeScript：https://docs.firecrawl.dev/agent-source-of-truth/node
Python：https://docs.firecrawl.dev/agent-source-of-truth/python
Rust / Java / Elixir / cURL：同一路徑下替換語言名

這些頁面纔是方法名、參數和返回值的權威來源。Skill 負責「何時、爲何」；「如何調用」以文檔爲準。

安裝與啓用¶

倉庫 README 說明：這套 build skills 遵循 Agent Skills 格式，並作爲插件提供給 Claude Code（.claude-plugin/）、Cursor（.cursor-plugin/）和 OpenAI Codex（.codex-plugin/）。通用 SKILL.md 格式下，其他能發現技能目錄的編程助手也可以使用；各工具具體落盤路徑以安裝器輸出爲準，這裏不另行猜測。

官方給出的安裝方式有三種，由寬到窄。

1. 一次裝上 CLI skills + build skills（含本 Skill）

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

--all 會裝 CLI、build 兩段技能；--browser 打開瀏覽器完成 Firecrawl 登錄。裝完後需要重啓 Agent，它纔會發現新 Skill。

2. 只裝 build skills 這一倉庫

npx skills add firecrawl/skills

3. 只裝 firecrawl-build-search 這一條

officialskills.sh 上的命令是：

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

也可以把該 GitHub 目錄地址貼給編程助手，讓它按 Agent Skills 流程安裝。

產品側鑑權，Skill 的 inputs 寫了兩項：

FIRECRAWL_API_KEY（必填）：託管服務請求用。可在 firecrawl.dev/app 獲取，寫入 .env 或運行時環境
FIRECRAWL_API_URL（可選）：自建 Firecrawl 的 base URL；只有不用託管的 api.firecrawl.dev 時才設

沒有 Key 時，官方建議先走同倉庫的 firecrawl-build-onboarding，它帶瀏覽器授權流程。需要說明的是：Search 文檔寫過「不帶 Key 也能試用，加上 Key 提高限流」；但 build Skill 把 Key 標成產品集成的必填項，按產品代碼場景應以 Skill 爲準。

SDK 安裝以語言文檔爲準，例如：

npm install firecrawl

pip install firecrawl-py

Node 文檔裏的鑑權寫法：

import { Firecrawl } from "firecrawl";

const client = new Firecrawl({
  apiKey: process.env.FIRECRAWL_API_KEY,
  // apiUrl: "https://api.firecrawl.dev" // 可選；也可讀 FIRECRAWL_API_URL
});

Python 文檔對應爲 Firecrawl(api_key=os.environ.get("FIRECRAWL_API_KEY"))，自建時再傳 api_url。

典型用法示例¶

下面提示詞和代碼均來自官方 Skill 或 source-of-truth / Search 文檔，可按項目語言復現。先讓 Agent 讀對文檔，再寫集成。

1. 在 Cursor / Claude Code / Codex 裏觸發這條 Skill

用接近官方 description 的說法即可，例如：

這個功能從用戶的自然語言問題開始，沒有現成 URL。
請用 firecrawl-build-search，把 Firecrawl /search 接到現有後端：
先按查詢發現來源，產出頁面短名單；
不要一上來對全部結果做全文水合，成本和延遲敏感，挑完 URL 再選擇性 scrape。

如果已經有明確地址，應改口「用 firecrawl-build-scrape 抓這一頁」，避免 Agent 誤走搜索。

2. 只發現：標題、摘要、URL

Node（source-of-truth）：

const results = await client.search("site:docs.firecrawl.dev webhook retries");
for (const item of results.web ?? []) {
  console.log(item.url, item.title);
}

Python：

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

REST（Search 文檔，POST /v2/search）：

curl -s -X POST "https://api.firecrawl.dev/v2/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -d '{
    "query": "firecrawl",
    "limit": 3
  }'

官方反覆提醒：SDK 的 search() 不返回 { data: [...] }。 網頁結果在 result.web，新聞在 result.news，圖片在 result.images。不要去讀 result.data。cURL 的完整 JSON 裏，未水合時 data 是按 web / news / images 分組的對象。

3. 同一次調用裏給結果補正文（水合）

適合「每個命中都要 Markdown」的場景。Python Search 文檔示例：

results = firecrawl.search(
    "firecrawl web scraping",
    limit=3,
    scrape_options={
        "formats": ["markdown", "links"]
    }
)

Node：

const results = await firecrawl.search("firecrawl", {
  limit: 3,
  scrapeOptions: { formats: ["markdown"] }
});

帶上 scrapeOptions 後，命中會從輕量結果對象變成帶正文的 Document。scrape 端點上的選項大多可以通過 scrapeOptions 傳到 /search（Search 文檔說明：除 Change-Tracking 等少數能力外，scrape 選項可用於 search）。

4. 兩步：先短名單，再選擇性抓取（Skill 默認更推薦）

Search 文檔中的兩步寫法：

results = firecrawl.search("firecrawl web scraping", limit=5)

for item in results.web or []:
    page = firecrawl.scrape(item.url, formats=["markdown"])
    print(page.markdown[:200])

產品代碼裏通常會在兩步之間加過濾：按域名、標題、還是 ignoreInvalidURLs: true 丟掉後續端點無法抓的地址。Node 複雜示例裏還出現過 sources: ["web", "news"]、tbs 時間過濾、location 本地化等參數，以當前語言文檔爲準，不要從過期博客抄字段。

limit 在指定多個 sources 時是按來源類型分別封頂：limit: 5 且 sources: ["web", "news"] 最多返回 5 條網頁 + 5 條新聞。不同來源若要不同 limit 或不同 scrapeOptions，官方要求拆成多次調用。

適用場景與注意事項¶

適合

Agent 工作流裏要把「網頁搜索」做成一次工具調用，起點是用戶問題
調研、競品跟蹤、帶引用問答：先得到排序後的頁面列表，再決定抓哪幾篇
查詢到 URL 的管道，下游再接 /scrape 或 /interact
明確需要「搜索結果帶全文」時，用 scrapeOptions 一次拿回 Markdown / HTML / links

不適合，或應改走其他 Skill

當前會話裏臨時搜一下、抓一下：用 firecrawl/cli，不要往業務倉庫裏寫集成代碼
已經有 URL：firecrawl-build-scrape
頁面必須點擊、填表才能看到內容：先 scrape 再 firecrawl-build-interact
搜的是論文記錄而不是網頁：firecrawl-research-index，不要依賴 categories: ["research"]
從倉庫 Issue / PR / README 回答開發問題：firecrawl-developer-index

使用上的限制

這是集成嚮導，不是完整 API 拷貝。參數、返回值以 docs.firecrawl.dev 的語言頁爲準；Skill 版本仍是 0.1.0，倉庫 README 寫明 evals 在首輪刻意延後
寬泛水合會放大 credits 和延遲；Skill 默認建議選擇性跟進抽取
查詢字符串要保持穩定（包括 site: 這類約束），下游 scrape 纔好測、好緩存
Node SDK 文檔聲明引擎要求 Node.js >= 22；包名以當前 source-of-truth 爲準（Node 爲 firecrawl，Python 爲 firecrawl-py）
第三方目錄頁上的安裝次數、安全掃描分數不是官方數據，安裝命令以 GitHub README 和 officialskills.sh 爲準

小結¶

firecrawl-build-search 把「查詢優先的網頁發現」從抓取流程裏拆出來：/search 負責發現和選源，抽取默認另走 /scrape，只有明確需要時纔在搜索調用裏做內容水合。它和 firecrawl-build 是同一倉庫裏的總入口與窄技能關係——前者決定要不要把 Firecrawl 寫進應用、選哪個端點；本 Skill 在端點已經是 /search 時，約束集成方式和升級路徑。

當前會話裏的一次性聯網，仍然走 CLI skills。把搜索寫進產品代碼時，從這份 Skill 開始，並在寫調用前打開對應語言的官方文檔。

官方地址：
https://github.com/firecrawl/skills/tree/main/skills/firecrawl-build-search

Search 文檔：
https://docs.firecrawl.dev/features/search

目錄頁：
https://officialskills.sh/firecrawl/skills/firecrawl-build-search

用 firecrawl-build-search：從查詢出發，把網頁發現寫進產品代碼

前言¶

這是什麼¶

核心功能與亮點¶

1. 觸發條件：起點是查詢，不是 URL¶

2. 搜索與抽取默認分開，水合是可選項¶

3. 把 `/search` 當成發現、排序和選源¶

4. 升級規則寫死，避免用錯索引¶

5. 具體怎麼調 API，以語言文檔爲準¶

安裝與啓用¶

典型用法示例¶

適用場景與注意事項¶

小結¶

精选优惠券

用 firecrawl-build-search：從查詢出發，把網頁發現寫進產品代碼

前言¶

這是什麼¶

核心功能與亮點¶

1. 觸發條件：起點是查詢，不是 URL¶

2. 搜索與抽取默認分開，水合是可選項¶

3. 把 /search 當成發現、排序和選源¶

4. 升級規則寫死，避免用錯索引¶

5. 具體怎麼調 API，以語言文檔爲準¶

安裝與啓用¶

典型用法示例¶

適用場景與注意事項¶

小結¶

精选优惠券

相關文章

3. 把 `/search` 當成發現、排序和選源¶