firecrawl-developer-index

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Firecrawl Developer Index

Firecrawl Developer 索引

Answer a developer question from the primary source: the issue where the bug was reported, the merged pull request that fixed it, the README or documentation page that states the contract. A blog post that describes a behaviour is a weaker answer than the passage that defines it, so reach for the index first and the open web second.

There is no fixed recipe. Read the question, decide what kind it is, and choose the approach below. A literal error string wants a different move than "how do I do X". Don't run machinery a question doesn't call for.

从一手资料中回答开发者问题：报告bug的工单、修复bug的已合并Pull Request、定义契约的README或文档页面。描述行为的博客文章不如明确定义行为的内容权威，因此优先使用本索引，其次才考虑开放网页。

没有固定的操作流程。先阅读问题，判断问题类型，再选择以下方法。字面错误字符串和“如何实现X”的处理方式不同，不要用不必要的流程处理问题。

The tools, and what each is uniquely good at

各工具及其独特优势

HTTP: GET|POST https://api.firecrawl.dev/v2/search/developer
MCP: firecrawl_developer_search(query, k?, skills?)
CLI: firecrawl developer <query> [--limit <n>] [--skills-only]
Ranked results over the whole index. Each carries
```
id
```
(
```
issue:owner/repo#123
```
),
```
type
```
(
```
doc
```
|
```
issue
```
|
```
pull_request
```
|
```
readme
```
),
```
url
```
,
```
title
```
, and the matched passages in markdown, so tables and code blocks survive. The default first move for a developer question. It is the only surface that returns the passages, which is what lets you answer instead of pointing at a page.
```
k
```
/
```
--limit
```
is 1–100 and defaults to 10.
```
skills="only"
```
/
```
--skills-only
```
restricts the search to agent-skill files. Keyless; send
```
Authorization: Bearer $FIRECRAWL_API_KEY
```
for higher rate limits.
MCP: firecrawl_search(query, categories: ["developer"])
CLI: firecrawl search <query> --categories developer
Developer hits in a
```
developer
```
group beside
```
web
```
, each with
```
url
```
,
```
title
```
,
```
description
```
(the matched passage),
```
position
```
, and
```
category: "developer"
```
— web results carry no
```
category
```
, so that is the field to key on when merging. Use this when you are already running a web search and want developer sources weighed in the same call. It exposes none of the filters and no passage control.
MCP: firecrawl_scrape(url)
/
firecrawl_search(query)
CLI: firecrawl scrape <url>
/
firecrawl search <query>
General web fetch and search, for what no primary source states: a comparison between two libraries, an outage, a migration write-up, a project with no public repository or indexed docs. Also the follow-through when a hit is the right page but you need all of it —
```
scrape
```
the result's
```
url
```
.

HTTP：GET|POST https://api.firecrawl.dev/v2/search/developer
MCP：firecrawl_developer_search(query, k?, skills?)
CLI：firecrawl developer <query> [--limit <n>] [--skills-only]
对整个索引的结果进行排序。每个结果包含
```
id
```
（格式如
```
issue:owner/repo#123
```
）、
```
type
```
（可选值：
```
doc
```
|
```
issue
```
|
```
pull_request
```
|
```
readme
```
）、
```
url
```
、
```
title
```
，以及匹配到的Markdown格式片段，因此表格和代码块会被保留。这是处理开发者问题的默认首选方式。它是唯一能返回内容片段的工具，而这些片段正是你用来回答问题而非仅指向页面的关键。
```
k
```
/
```
--limit
```
的取值范围是1–100，默认值为10。
```
skills="only"
```
/
```
--skills-only
```
参数会将搜索范围限制在Agent技能文件内。无需密钥即可使用；若发送
```
Authorization: Bearer $FIRECRAWL_API_KEY
```
请求头，可获得更高的速率限制。
MCP：firecrawl_search(query, categories: ["developer"])
CLI：firecrawl search <query> --categories developer
开发者相关结果会被归为
```
developer
```
组，与
```
web
```
组并列。每个结果包含
```
url
```
、
```
title
```
、
```
description
```
（匹配到的片段）、
```
position
```
和
```
category: "developer"
```
——网页结果没有
```
category
```
字段，因此合并结果时可通过该字段区分来源。当你已经在进行网页搜索，且希望在同一请求中纳入开发者来源时使用此方法。它不支持任何筛选器，也无法控制返回的内容片段。
MCP：firecrawl_scrape(url)
/
firecrawl_search(query)
CLI：firecrawl scrape <url>
/
firecrawl search <query>
通用网页抓取和搜索工具，适用于一手资料未覆盖的场景：两个库的对比、服务中断情况、迁移指南、无公开仓库或未被索引文档的项目。当搜索结果中的页面是正确来源，但你需要完整内容时，也可使用此工具——抓取结果中的
```
url
```
即可。

Filters, and what each one costs you

筛选器及其影响

Only the HTTP surface takes these. On

GET

, pass

types=issue,pull_request

or repeat the parameter; on

POST

, pass arrays. All are optional.

```
types
```
— which of
```
doc
```
,
```
issue
```
,
```
pull_request
```
,
```
readme
```
to search. Defaults to all four. Narrowing here is the cheapest way to sharpen a query.
```
repos
```
(
```
owner/name
```
) scopes the repository half, meaning
```
issue
```
,
```
pull_request
```
, and
```
readme
```
;
```
sources
```
(documentation source ids, at most 20) scopes the documentation half, meaning
```
doc
```
. Passing both unions the halves rather than intersecting them. Both echo back in the response with
```
indexed: true|false
```
— that is how you tell "not in the index" from "found nothing".
A filter that cannot match any requested
```
type
```
is a
```
400
```
, not an empty list:
```
repos
```
with no repository type in
```
types
```
, or
```
sources
```
without
```
doc
```
.
```
passages
```
(1–5, default 1) is the maximum passages per result, not a guarantee. Raise it when one page is clearly the right page but the first passage is the wrong part of it.
```
language
```
,
```
topic
```
,
```
license
```
,
```
min_stars
```
,
```
max_stars
```
,
```
archived
```
,
```
fork
```
describe a repository. Most documentation pages in the index have no repository behind them, so no repository fact can admit or exclude one. Send any of these without a
```
sources
```
scope and the response holds repository evidence only —
```
issue
```
,
```
pull_request
```
,
```
readme
```
— with
```
coverage
```
reporting
```
doc
```
as
```
unavailable
```
. That is the design, not an index fault: do not retry it and do not report the index broken. To keep documentation, drop the repository filters, or scope the documentation half with
```
sources
```
and read
```
coverage
```
to confirm
```
doc
```
answered.

仅HTTP接口支持以下筛选器。使用

GET

请求时，可传递

types=issue,pull_request

或重复该参数；使用

POST

请求时，可传递数组参数。所有筛选器均为可选。

```
types
```
——指定搜索的内容类型，可选值为
```
doc
```
、
```
issue
```
、
```
pull_request
```
、
```
readme
```
，默认搜索全部四种类型。缩小类型范围是优化查询成本最低的方式。
```
repos
```
（格式为
```
owner/name
```
）用于限定仓库相关内容，即
```
issue
```
、
```
pull_request
```
和
```
readme
```
；
```
sources
```
（文档源ID，最多20个）用于限定文档相关内容，即
```
doc
```
。同时传递两者会合并两个范围而非取交集。响应中会返回
```
indexed: true|false
```
字段来反馈参数有效性——通过该字段可判断是“不在索引中”还是“未找到匹配内容”。
若筛选器与请求的
```
type
```
不匹配，会返回
```
400
```
错误而非空列表：例如
```
types
```
中无仓库类型时传递
```
repos
```
，或
```
types
```
中无
```
doc
```
时传递
```
sources
```
。
```
passages
```
（取值范围1–5，默认1）是每个结果返回的最大片段数，而非保证值。当确定某页面是正确来源但第一个片段不是所需内容时，可提高该参数值。
```
language
```
、
```
topic
```
、
```
license
```
、
```
min_stars
```
、
```
max_stars
```
、
```
archived
```
、
```
fork
```
用于描述仓库。索引中的大部分文档页面没有对应的仓库，因此仓库相关条件无法筛选文档内容。若未指定
```
sources
```
范围而传递上述参数，响应将仅包含仓库相关内容——
```
issue
```
、
```
pull_request
```
、
```
readme
```
——且
```
coverage
```
字段会显示
```
doc
```
为
```
unavailable
```
。这是设计预期而非索引故障：无需重试，也无需报告索引损坏。若要保留文档内容，请移除仓库筛选器，或通过
```
sources
```
限定文档范围并查看
```
coverage
```
字段确认
```
doc
```
是否有结果。

Match the approach to the question

根据问题类型选择对应方法

Literal error message or stack-trace string → search the string itself plus the library name, with
```
types=["issue","pull_request"]
```
. Whoever hit it filed it. If nothing matches, strip the volatile parts (paths, line numbers, ids, addresses) and retry — the invariant middle of the message is what is indexed.
Conceptual "how do I do X" → the full question in natural language, all four types. The answer is usually a
```
doc
```
or a
```
readme
```
; raise
```
passages
```
before raising
```
k
```
.
Known bug → the issue reports it, the merged pull request fixes it, and the fix is what you want. Search
```
types=["issue","pull_request"]
```
, then re-query the issue's own terms scoped to its repo with
```
types=["pull_request"]
```
. A merged PR's passages tell you what changed and in which direction.
API contract ("what does X return", "is Y required", "what is the default") →
```
readme
```
and
```
doc
```
are authoritative and a blog post is not. Use
```
types=["readme","doc"]
```
. If the contract looks like it moved, follow up with
```
pull_request
```
for the change that moved it.
Version-specific behaviour → an issue's opening report describes the broken version; its resolution supersedes it. Raise
```
passages
```
to see further into the thread, and read the resolution and the linked pull request before answering. Never answer from an opening report alone.
Scoped to one library →
```
repos=["owner/name"]
```
when you know the slug, plus
```
sources
```
if you want its docs in the same call. If a scoped search comes back empty, read the echoed
```
indexed
```
flag first:
```
false
```
means nothing from that repo or source can ever match and no rephrasing will help — drop the scope and search the whole index, or go to the web.
Ecosystem-wide ("which libraries do X", "who else hit this") → no scope. Use
```
language
```
/
```
topic
```
/
```
min_stars
```
to keep to maintained repositories, accepting that this gives up all
```
doc
```
results.
Agent skills and tooling conventions →
```
skills="only"
```
/
```
--skills-only
```
.
Comparison, opinion, news, or an unindexed project → the open web.
```
firecrawl_search
```
, then
```
firecrawl_scrape
```
whatever deserves a full read. Combining is often right: take the contract from the index and the trade-off from the web.

字面错误信息或堆栈跟踪字符串 → 直接搜索该字符串加上库名，并设置
```
types=["issue","pull_request"]
```
。遇到该问题的开发者通常会提交工单。若无匹配结果，移除可变部分（路径、行号、ID、地址）后重试——错误信息中不变的核心部分才会被索引。
概念性问题“如何实现X” → 使用自然语言完整提问，搜索全部四种类型。答案通常来自
```
doc
```
或
```
readme
```
；优先提高
```
passages
```
参数而非
```
k
```
参数。
已知bug → 工单会报告bug，已合并的Pull Request会修复bug，而修复内容才是你需要的信息。搜索
```
types=["issue","pull_request"]
```
，然后使用工单中的术语限定对应仓库，再搜索
```
types=["pull_request"]
```
。已合并PR的片段会告诉你修改内容和方向。
API契约（如“X返回什么”、“Y是否为必填项”、“默认值是什么”） →
```
readme
```
和
```
doc
```
是权威来源，博客文章不算。使用
```
types=["readme","doc"]
```
。若契约看起来有变动，可进一步搜索
```
pull_request
```
查看变更记录。
特定版本的行为 → 工单的初始报告描述的是存在问题的版本；其解决方案会取代初始报告。提高
```
passages
```
参数以查看更多线程内容，在回答前请阅读解决方案和关联的Pull Request。绝不要仅根据初始报告回答问题。
限定单个库 → 若知道仓库slug，设置
```
repos=["owner/name"]
```
，若需要同时包含其文档可加上
```
sources
```
参数。若限定范围的搜索返回空结果，请先查看返回的
```
indexed
```
标志：
```
false
```
表示该仓库或源的内容从未被索引，重新措辞也无济于事——此时应移除范围限制搜索整个索引，或转向网页搜索。
生态系统范围的问题（如“哪些库支持X”、“还有谁遇到过这个问题”） → 不设置范围限制。使用
```
language
```
/
```
topic
```
/
```
min_stars
```
参数筛选维护中的仓库，但需注意这样会放弃所有
```
doc
```
结果。
Agent技能和工具约定 → 使用
```
skills="only"
```
/
```
--skills-only
```
参数。
对比、观点、新闻或未被索引的项目 → 使用开放网页搜索。先调用
```
firecrawl_search
```
，再对值得深入阅读的结果调用
```
firecrawl_scrape
```
。通常结合两种方式效果最佳：从索引获取契约信息，从网页获取权衡分析。

Principles

原则

Read
coverage
before concluding a source doesn't exist. Every response reports
```
ok
```
|
```
degraded
```
|
```
unavailable
```
|
```
skipped
```
per type.
```
skipped
```
means your own
```
types
```
value did not ask for that type.
```
degraded
```
or
```
unavailable
```
means the gap came from the index or from a filter you sent, not from your query — drop the filter or widen, rather than retrying the same call or reporting that nothing exists.
```
ok
```
with no hits of that type is a genuine miss: rephrase.
Quote the passage, cite the
url
. The passages are the evidence; hand them over rather than paraphrasing them into a claim the reader can't check.
```
title
```
is frequently absent on
```
doc
```
results — fall back to
```
url
```
.
A merge supersedes a report. When an issue and a pull request disagree, the merged pull request is the current behaviour. Say which one you read.
Scope last, not first. Search the whole index, then narrow with
```
types
```
,
```
repos
```
, or
```
sources
```
once you know what the hits look like. Scoping first hides the result that would have told you where to look.
Go to the web when the index has nothing to say. Trade-offs, ecosystem opinion, and anything about an unindexed project are web questions. Don't force them through the index, and don't dress a general web page up as a primary source.

在判断来源不存在前先查看
coverage
字段。每个响应会按类型报告
```
ok
```
|
```
degraded
```
|
```
unavailable
```
|
```
skipped
```
状态。
```
skipped
```
表示你的
```
types
```
参数未包含该类型。
```
degraded
```
或
```
unavailable
```
表示缺口来自索引或你设置的筛选器，而非查询语句问题——此时应移除筛选器或扩大范围，而非重试相同请求或报告无结果。
```
ok
```
状态但无对应类型的结果才是真正未命中：此时需要重新措辞查询。
引用内容片段并标注
url
。内容片段是证据；直接提供给读者，而非将其改写为无法验证的结论。
```
doc
```
结果经常没有
```
title
```
字段——此时可使用
```
url
```
替代。
合并的PR优先于报告。 当工单和Pull Request内容不一致时，已合并的Pull Request代表当前行为。请说明你参考了哪一个。
最后再设置范围限制。 先搜索整个索引，在了解结果特征后再通过
```
types
```
、
```
repos
```
或
```
sources
```
缩小范围。先设置范围会隐藏能指引你正确方向的结果。
当索引无相关内容时转向网页。 权衡分析、生态系统观点以及未被索引项目的相关问题均属于网页搜索范畴。不要强行通过索引处理这些问题，也不要将普通网页伪装成一手资料。