Developer Index：一行指令，讓 coding agent 查得到最新文件與 PR

瀏覽次數: 1

你的 coding agent 每天花最多工具呼叫在做什麼？不是寫 code，是找東西。找那個「做這件事的函式庫叫什麼」、找「這個 API 的預設值到底是多少」、找「我這個錯誤訊息別人是不是早就修掉了」。

而它現在拿的工具，多半是給人用的網頁搜尋。搜回來十條連結，agent 挑兩三條 scrape 整頁，導覽列、Cookie 橫幅、下面三十則留言一起塞進 context——最後拿到的還常常是一篇二手部落格，而不是真正把 bug 修掉的那個 merged PR。

Firecrawl 在 2026 年 8 月 20 日推出的 Developer Index，就是衝著這件事來的。它不是又一個 web search，而是一層「artifact 檢索層」：你問一句自然語言，它直接回你 issue、PR、README、文件頁，而且附上命中的段落，agent 不用再抓第二次。

更重要的是，接上它只要一行指令。這篇就把「怎麼裝、怎麼問、什麼時候別用」講完。

本文大綱

一、它到底在解決什麼問題

Firecrawl 的 Neha Patil 與 Karan Lokchandani 在發布文裡寫得很直接：coding agent 的搜尋需求，其實只有三種形狀。

找 repo——「有沒有做增量 PDF 解析的函式庫」，但我不知道它叫什麼名字。
找文件——「在 uv 裡怎麼加 Pydantic，而不是用 pip」。
找 issue／PR——「scikit-learn 的 LogisticRegression random_state 沒作用」，這在哪裡被討論、被修掉。

這三種東西散在 GitHub、各家文件站、討論串裡。用一般搜尋 API 去撈，問題有兩層：一是檢索是字面比對而非語意的，你把一整串 stack trace 貼進去，通常什麼也搜不到；二是回傳的單位是網頁不是 artifact，你想要「這個 README 加上它的相關 issue 加上最近的 PR」，得自己拼一堆 API 呼叫。

Firecrawl 自己說得很老實：連他們原本的通用 search 和 scrape，對這種形狀的查詢結果也普通，因為「coding agent 要的不是一個網頁，是一個 artifact」。

二、運作原理：索引裡有什麼、回傳長什麼樣

索引內容

官方數字是 7,000 萬以上的 artifact，涵蓋：

公開 repo 的 README
熱門 repo 的 issue 與 merged PR（含彼此連結的關係）
外部文件站（Stripe 這種形狀的官方文件）
OpenAPI spec，以及被收錄的 agent skill 檔案
每個 artifact 都帶 metadata：star 數、license、artifact 類型

大部分來源每日更新。

有兩件事它明說「不做」，非常關鍵：它不存 code，而且它不是通用網頁搜尋。這決定了後面所有的取捨。

回傳的形狀

每一筆結果有三個欄位：id、url、passages。

id 是穩定識別碼，而且前綴就告訴你這是什麼東西：doc:、issue:、pull_request:、readme:。例如 pull_request:encode/httpx#1196。

passages 是命中的段落，以 markdown 回傳，所以表格和程式碼區塊不會被壓成一團純文字。這是整個設計裡最實用的一點：agent 拿到的直接是可以引用的證據，不必為了看內文再 scrape 一次。

我用 keyless 實際打了幾次，有兩個文件沒寫清楚、但你會撞到的細節：

title 在 doc: 結果上常常是空的（官方文件有提醒），要 fallback 到 url。
我跑 httpx retry 那題時，第三筆結果的 id 前綴是 web:，不在官方列出的四種裡面。所以如果你要在程式裡用前綴分流，別寫死那四個 case，留一個 default 分支。

兩個入口

# 入口一：只要 developer 來源，回傳 ranked 結果 + 命中段落
curl -s "https://api.firecrawl.dev/v2/search/developer?query=how%20do%20I%20configure%20retries&k=10"

# 入口二：把 developer 結果混進一般 web search
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -d '{"query":"how do I configure retries","categories":["developer"],"limit":10}'

差別要記住：只有 /search/developer 會回 passages 和過濾器。/search 加 categories: ["developer"] 回的是一般 web result 的形狀（url / title / description / position，多一個 category: "developer"），適合你本來就在跑 web search、只是想把開發者來源一起權衡進去。

還有一點對「先試再說」很友善：不用 API key 就能打。上面那行 curl 我直接跑，回 HTTP 200。加 key 只是拿更高的 rate limit。

過濾器，以及它們的坑

/search/developer 的過濾器：

參數	作用
`k`	回幾筆，1–100，預設 10
`passages`	每筆最多幾段，1–5，預設 1（是上限不是保證）
`types`	從 `doc` / `issue` / `pull_request` / `readme` 挑
`repos`	限定 repo（`owner/name`），管的是 repo 那一半
`sources`	限定文件來源 id（最多 20 個），管的是 docs 那一半
`skills: "only"`	只搜被收錄的 agent skill 檔
`language` / `topic` / `license` / `min_stars` / `max_stars` / `archived` / `fork`	repo 屬性過濾

三個真的會咬人的行為，我都實測確認過：

第一，repos 和 sources 同時給是「聯集」不是「交集」。 你以為在縮小範圍，其實是把兩半都撈進來。

第二，那七個 repo 屬性過濾器會靜默地把文件排除掉。 因為索引裡大部分文件頁背後根本沒有 repo，所以任何 repo 事實都無法納入它們。你只加一個 language=Rust，回來的就只剩 issue／pull_request／readme。skill 文件把這句寫得很重：「這是設計，不是索引壞掉，不要重試也不要回報 bug。」

第三，過濾器打架會直接 400，不是回空陣列。 我送 types: ["doc"] 配 repos: ["encode/httpx"]，拿到的是：

{"success":false,"code":"BAD_REQUEST",
 "error":"repos cannot match any requested type; add github types or drop repos"}

反過來，正常 scope 的時候，回應會把你的 scope 原樣 echo 回來並標記是否收錄，這個設計很體貼：

{"repos":[{"repo":"encode/httpx","indexed":true,
  "types":{"issue":true,"pullRequest":true,"readme":true}}]}

indexed: false 的意思是「這個 repo 根本不在索引裡，你怎麼改 query 都沒用」——直接放棄 scope 或改走 web，不要在那邊換句話重問。

最後一個設計決定值得注意：這些過濾器只在 HTTP API 上開放，CLI 和 MCP 故意不給。 Firecrawl 的理由是 agent 不加過濾器時表現更好。這其實是個蠻誠實的取捨：與其讓模型亂猜 min_stars 該設多少，不如讓它問得清楚一點。

三、手把手：三種接法

接法 A：三十秒驗證（不用註冊）

先確認這東西對你的問題有沒有用，再談安裝：

curl -s -X POST https://api.firecrawl.dev/v2/search/developer \
  -H "Content-Type: application/json" \
  -d '{"query":"retry backoff not firing on 429","k":3,"types":["issue","pull_request"],"repos":["encode/httpx"]}' \
  | jq -r '.results[] | "\(.id)\n\(.passages[0].text[0:200])\n"'

拿你上週卡住的那個真實問題去打。如果回來的是你當初翻了半小時才找到的那個 PR，那就值得裝。

接法 B：CLI + skill（推薦給 Claude Code / Codex / Cursor）

官方最推薦的路徑，就是標題那一行：

npx -y firecrawl-cli@latest setup developer-index

這行做的事是安裝 Firecrawl 官方的 firecrawl-developer-index skill（原始碼在 github.com/firecrawl/cli/tree/main/skills/firecrawl-developer-index），預設裝到所有偵測到的 coding agent。如果你只想裝到其中一個：

firecrawl setup developer-index --agent claude-code

--agent 目前支援的值：claude-code、codex、cursor、windsurf、opencode、openclaw、openhands、hermes-agent。

裝完要重啟 agent 才會被發現。之後在終端機也能直接用：

firecrawl developer "why is my retry backoff not firing on 429" --limit 10

接法 C：MCP

firecrawl setup mcp

或手動指到 hosted server：

URL: https://mcp.firecrawl.dev/v2/mcp
Authorization: Bearer <FIRECRAWL_API_KEY>

（瀏覽器登入走 https://mcp.firecrawl.dev/v2/mcp-oauth。官方特別提醒：key 放環境變數或 client 的 secret 存放區，不要塞在 MCP URL 裡。）

MCP 上的工具名是 firecrawl_developer_search(query, k?, skills?)。

四、真正該學的是那份 SKILL.md

裝完之後，多數人只會得到「多一個搜尋工具」。但那份 skill 檔裡的決策表，才是把命中率拉起來的東西——而且就算你不用 Firecrawl，這套 heuristic 也能抄進你自己的 CLAUDE.md。

它開宗明義寫著：「沒有固定食譜。讀懂問題屬於哪一類，再選招式。」以下是它的分類，我照原意整理：

問題型態	招式
字面錯誤訊息／stack trace	直接搜那串字 + 函式庫名，`types=["issue","pull_request"]`。搜不到就把易變的部分拿掉（路徑、行號、id、記憶體位址），重搜訊息中間不變的那段
概念型「怎麼做 X」	完整自然語言問句，四種 type 全開。答案通常是 `doc` 或 `readme`；先調高 `passages`，再考慮調高 `k`
已知 bug	先 `types=["issue","pull_request"]`；找到 issue 後，用它自己的用語 scope 到該 repo，再搜一次 `types=["pull_request"]`。merged PR 的段落會告訴你改了什麼、往哪個方向改
API contract（回傳什麼／是不是必填／預設值）	`types=["readme","doc"]`。契約看起來變過，就再追一次 `pull_request`
版本相關行為	調高 `passages` 看進討論串深處。絕對不要只看 issue 的開頭那則報告——它描述的是壞掉的版本，結論才算數
生態系層級（誰還踩到這個／哪些函式庫做 X）	不 scope，用 `language` / `topic` / `min_stars` 篩到還在維護的 repo，代價是放棄所有文件結果
比較、意見、新聞、未收錄的專案	走一般 web search，別硬塞進索引

還有三條原則，我認為比工具本身更值得貼在團隊 wiki 上：

引用段落，附上 url。 段落才是證據，不要把它改寫成一句讀者無從查證的斷言。
merge 蓋過 report。 issue 和 PR 講的不一樣時，merged PR 才是現在的行為，而且要說清楚你讀的是哪一個。
先搜全域，再縮範圍。 一開始就 scope，會蓋掉那筆「本來會告訴你該去哪裡找」的結果。

第三條是我覺得最反直覺、也最容易做錯的。人類搜尋的習慣是先限定範圍，但對 agent 來說，先看全貌再收斂命中率更高。

五、數據：DevDex 怎麼測、數字該怎麼讀

Firecrawl 同時開源了一個 benchmark 叫 DevDex，1,179 題，分成上面說的三個賽道。這件事本身值得稱讚：一半資料集（594 題）加上評測 harness 全部公開在 github.com/firecrawl/benchmark-devdex，MIT 授權。

方法論有幾個設計得不錯的地方：

確定性計分，沒有 LLM judge。 用固定 gold reference 做正規化 URL 比對，所有公開數字都不是模型判的。
記憶檢查（memorisation gate）。 候選題目先在「關掉搜尋」的情況下跑一遍，模型光靠預訓練就答得出來的，全部踢掉。剩下的地板就是 no-tools 控制組的分數（repo 0.005、issue/PR 0.000、docs 0.034），任何人都能從自己的 run 重新驗證這道閘。
同一個 driver、同一個 harness、每輪只開一個搜尋工具。 driver 是 claude-opus-4-8。
跑掛的 run 算 miss，不是排除。 這點很誠實，很多 benchmark 會偷偷把失敗的 run 排掉。

綜合 recall@10（三個賽道平均）：Firecrawl Developer Index 0.631（95% CI [0.605, 0.657]）、Parallel 0.577、Mintlify 0.546、Exa 0.537、原生 web search 0.454、Context7 0.168、無工具 0.013。

但只看綜合分會誤導，拆開來才是重點：

找 repo：Parallel 0.819 領先，原生 web search 0.807 緊追，Developer Index 只有 0.761。這條賽道專用索引沒有優勢——Google 本來就很會找 repo。
找 issue／PR：Developer Index 0.660，領先 Parallel 的 0.629；而原生 web search 只有 0.275。這是落差最大、專用索引最值得買單的一條。
找文件：Developer Index 0.472，跟 Context7 的 0.466 差 0.006——Firecrawl 自己在發布文裡就承認這是「統計上打平」。

幾個必須講清楚的限制：

第一，這是 Firecrawl 自己出的 benchmark，測自己贏。 資料集和題目形狀都是他們定的。開源一半、公開 harness 是加分，但這不等於中立第三方評測。

第二，README 裡自己寫了：「任何單一賽道上，前二到三名在 paired bootstrap 下統計上分不出高下，領先只在綜合分才拉開。」 這句話比表格重要。

第三，Context7 的綜合分 0.168 不能當「檢索品質差」讀。 它只索引函式庫文件，repo 和 issue/PR 兩條賽道對它來說是領域外，而且兩格都超過 10% dead-run（71% 和 52%）。README 明說那個數字要「當覆蓋率讀」——三條賽道答得出一條。在它擅長的文件賽道上，它是第二名。

第四，文件賽道全場最高只有 0.47。 換句話說，即使是冠軍，問「怎麼在 Y 裡做 X」有一半以上的機率前十筆裡沒有正確那頁。這是整份 benchmark 裡最該記住的數字——別把它當成「agent 從此不會查錯文件」。

第五，跑這個 benchmark 要花真錢。 README 標的是約每題 $0.28，一個 arm 跑完三條賽道約 $165。你想自己驗，先用 --limit 小規模試。

六、什麼時候該用、什麼時候別用

該用：

Agent 在 debug 時撞到具體錯誤訊息或已知 bug——這是 0.66 vs 0.28 的那條賽道，差距最大。
你要查 API contract（預設值、必填欄位、回傳形狀），需要的是原始出處而不是某篇 blog 的轉述。
你在做 agentic 產品（發布文點名的形狀是 Lovable、Replit、Bolt 這類），要讓 agent 自己去查修復紀錄而不是猜。
你想省 context：一次呼叫拿到 markdown 段落，比 search + scrape 兩三頁乾淨太多。

別用：

要找 code 本身。 索引不存 code。要讀實作還是得 clone 或用 GitHub 的程式碼搜尋。
要比較、要意見、要新聞。 skill 檔自己寫：這些是 web 問題，別硬塞進索引，也別把一個普通網頁包裝成「primary source」。
目標專案沒被收錄。 看 indexed flag，false 就換路，別在那邊重寫 query。
純粹找 repo。 Parallel 和一般 web search 在這條賽道就夠好了，多接一個服務不划算。
你需要精細過濾器又只想用 MCP。 過濾器只在 HTTP API，MCP 和 CLI 刻意不給。

成本怎麼算： developer search 是每 10 筆結果 2 credits，無條件進位（1–10 筆 2 credits、11–20 筆 4 credits，以此類推）。keyless 免費但依 IP 每日限流，同時卡「請求數」和「credits」兩個上限，超過任一個都回 429。免費 key 給 1,000 credits——換算大約 500 次十筆的 developer search，拿來評估綽綽有餘。

七、對工程團隊：這週可以做的三件事

1. 先用真實問題驗證，再決定要不要接。 從你們最近三個 debug 卡關的 issue 挑出來，用第三節接法 A 的 keyless curl 各打一次。命中就裝，沒命中就別裝——不要因為「聽起來很厲害」就多養一個依賴。

2. 就算不接 Firecrawl，也把那份決策表抄進你的 rules。 「錯誤訊息就去搜 issue 和 PR」「先看全域再 scope」「merged PR 蓋過 issue 開頭那則報告」「引用段落而不是改寫成斷言」——這幾條寫進 CLAUDE.md 或 AGENTS.md，對任何檢索工具都適用，成本是零。

3. 接了就把「別用」的邊界也寫進去。 這是最容易被漏掉的一步。工具裝上去以後，agent 會傾向什麼都拿它問，包括它本來就答不好的比較題和找 repo 題。在 rules 裡明寫「找 repo 和比較類問題走一般 web search」，比多接一個工具更能提升整體命中率。

最後一句實話：DevDex 那個 0.47 的文件賽道分數，提醒我們現在沒有任何檢索層能讓 agent「一定查得到對的文件」。Developer Index 買到的是在 issue／PR 這條特定路徑上明顯更高的命中率，以及少一次 scrape 的 context 效率。這兩件事都是真的、也都值錢，但它們不是「agent 從此不會用錯 API」。

來源

Firecrawl 發布文：Introducing Firecrawl Developer Index: A Specialized Index for Coding Agents — Neha Patil（Research Engineer, Firecrawl）、Karan Lokchandani（Member of Technical Staff, Firecrawl），2026/08/20
官方文件：Developer Index — Firecrawl Docs
官方 skill 原始碼：firecrawl/cli — skills/firecrawl-developer-index
Benchmark 與資料集：firecrawl/benchmark-devdex（MIT，594 題公開樣本 + 評測 harness）
CLI 與 MCP 設定：Firecrawl CLI 文件、MCP Server 文件
額度與限流：Firecrawl Rate Limits

本文中的 API 行為（keyless 回應、repos echo 格式、過濾器衝突的 400 訊息、web: 前綴）為 2026-08-22 實際呼叫 api.firecrawl.dev/v2/search/developer 所得；benchmark 數字取自 DevDex repo README，與發布文的四捨五入版本一致。