firecrawl-developer-index

Firecrawl 开发者索引

如需官方文档、设置、示例、迁移或兼容性信息，请参阅官方文档。如需查找文档之外的实现或错误证据，请继续查看下文。切换方法时，复用合适的证据。

从一手来源回答开发者问题：报告错误的问题、修复错误且已合并的拉取请求，或说明约定的 README 或文档页面。描述某种行为的博客文章，不如定义该行为的段落可靠，因此应先查索引，再查开放网络。索引中的仓库部分仅涵盖公开仓库。索引不包含私有或内部仓库，因此有关私有代码的问题需要另寻途径：直接阅读代码。

没有固定流程。 阅读问题，判断它属于哪类，再选择下方的方法。字面错误字符串需要采用不同的做法，而“如何执行 X”也是如此。不要运行问题用不上的工具。

各工具的独特优势

• HTTP：GET|POST https://api.firecrawl.dev/v2/search/developer MCP：firecrawl_developer_search(query, k?, skills?) CLI：firecrawl developer <query> [--limit <n>] 对整个索引进行排序后的结果。每条结果都包含 id（issue:owner/repo#123）、url 和以 markdown 格式呈现的匹配段落，因此表格和代码块都能保留。资源类型由 id 前缀标识：doc:、issue:、pull_request: 或 readme:。 这是查询开发者问题时的默认首选。它是唯一会返回段落的接口，因此你可以据此直接回答，而不只是指向某个页面。 k / --limit 的取值范围为 1–100，默认值为 10。skills="only"（仅适用于 HTTP/MCP）会将搜索范围限制为 Agent 技能文件。 无需密钥；如需更高的速率限制，请发送 Authorization: Bearer $FIRECRAWL_API_KEY。

• MCP：firecrawl_search(query, categories: ["developer"]) CLI：firecrawl search <query> --categories developer 开发者搜索结果会与 web 一起显示在 developer 分组中，每条结果都包含 url、title、description（匹配段落）、position 和 category: "developer"——网页结果不带 category，合并时应使用该字段作为依据。 如果你已经在执行网页搜索，并希望在同一次调用中纳入开发者来源，可使用此工具。它不提供任何筛选条件，也无法控制返回段落。

• MCP：firecrawl_scrape(url) / firecrawl_search(query) CLI：firecrawl scrape <url> / firecrawl search <query> 用于常规网页抓取与搜索，适用于没有一手来源说明的内容：两个库的比较、服务中断、迁移说明、没有公开仓库或索引文档的项目。 如果搜索结果中的页面正是所需页面，但你需要查看完整内容，也可以用 scrape 抓取结果的 url。

筛选条件及其代价

只有 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，或没有 doc 时传入 sources。
• passages（1–5，默认值为 1）表示每个结果的段落数上限，并非保证值。如果某个页面显然是正确的页面，但首个段落不是你要找的部分，可以调高此值。
• language、topic、license、min_stars、max_stars、archived、fork 描述的是一个仓库。索引中的大多数文档页面都没有对应的仓库，因此没有任何仓库属性能够将其纳入或排除。若不限定 sources 就发送这些筛选条件，响应将只包含仓库方面的证据——issue、pull_request、readme。这是设计如此，并非索引故障：不要重试，也不要报告索引损坏。若要保留文档结果，请移除仓库筛选条件，或使用 sources 限定文档部分，并查看回显的 sources 以确认该 ID 已编入索引。

根据问题选择合适的方法

• 字面错误消息或堆栈跟踪字符串 → 搜索该字符串本身以及库名称，并使用 types=["issue","pull_request"]。遇到问题的人通常会提交相关内容。如果没有匹配项，去掉易变部分（路径、行号、ID、地址）后重试——消息中不变的部分才是索引的内容。
• 概念性问题（“如何实现 X”） → 用自然语言输入完整问题，并搜索全部四种类型。答案通常在 doc 或 readme 中；先提高 passages，再提高 k。
• 已知 Bug → issue 会报告问题，已合并的 pull request 会_修复_问题，而你需要的是修复内容。搜索 types=["issue","pull_request"]，然后使用该 issue 中的关键词，在其所属仓库范围内以 types=["pull_request"] 再次查询。已合并 PR 的段落会说明改了什么，以及改动方向。要将其描述为用户已安装版本的行为之前，请确认某个发行版包含了这项修复。
• API 契约（“X 会返回什么”“Y 是否必填”“默认值是什么”）→ readme 和 doc 才是权威来源，博客文章则不是。使用 types=["readme","doc"]。如果契约似乎发生过变更，继续查找导致变更的 pull_request。
• 特定版本的行为 → issue 的开篇报告描述的是存在问题的版本；后续解决方案则取代了它。提高 passages，以查看讨论串的更多内容，并阅读解决方案及其关联的 pull request 后再作答。切勿只依据开篇报告作答。
• 限定在某个库内 → 如果知道仓库标识，使用 repos=["owner/name"]；如果想在同一次调用中搜索其文档，也加入 sources。如果限定范围的搜索没有结果，先查看回显的 indexed 标记：false 表示该仓库或来源中的内容都不可能匹配，换种说法也无济于事——移除范围限制，搜索整个索引，或者转到网络搜索。
• 整个生态范围（“哪些库能实现 X”“还有谁遇到过这个问题”）→ 不限定范围。使用 language / topic / min_stars，以便筛选出仍在维护的仓库，但这意味着放弃所有 doc 结果。
• Agent 技能和工具约定 → 使用 skills="only"（仅限 HTTP/MCP）。
• 比较、观点、新闻或未编入索引的项目 → 搜索开放网络。使用 firecrawl_search，然后对值得完整阅读的内容使用 firecrawl_scrape。两者结合往往更合适：从索引获取契约，从网络获取权衡信息。

原则

• 引用段落并附上 url。 段落就是证据；直接提供给读者，而不是将其改写成无法核查的论断。doc 结果往往没有 title——此时使用 url。
• 区分修复和发行版。 已合并的修复可以取代早先针对仓库代码的问题报告，但只有当某个发行版包含这次合并后，修复才会出现在用户使用的版本中。请从项目的发行说明、变更日志条目或发行标签中确认这一点（搜索这些内容，或在索引中没有时抓取发行版页面或变更日志页面），并引用相关证据。
• 先搜索，后限定范围。 先搜索整个索引，了解结果情况后，再使用 types、repos 或 sources 缩小范围。先限定范围会隐藏可能告诉你应该去哪里查找的结果。
• 索引没有相关内容时，转到网络搜索。 权衡、生态观点以及任何关于未编入索引项目的问题，都应通过网络搜索解决。不要强行通过索引查找，也不要把普通网页包装成一手来源。

另请参阅

• firecrawl-build-search — 将开发者索引集成到应用中，而不是在此处查询