搜索 Developer Index
POST。
可重复指定的筛选条件在 GET 中支持以下任一形式:重复的查询参数,例如 types=issue&types=pull_request,或以逗号分隔的单个值,例如 types=issue,pull_request。
repos 和 sources 如何限定搜索范围
repos限定 GitHub 部分,即issue、pull_request和readme类型sources限定文档部分,即doc类型- 同时传入两者会合并这两部分,而非取交集,因此会返回任一部分中的匹配结果
- 当
types中不包含 GitHub 类型时,repos会返回400,并提示repos cannot match any requested type; add github types or drop repos - 当
types中不包含doc时,sources会返回400,并提示sources cannot match any requested type; add doc or drop sources
仓库筛选条件如何限定搜索范围
language (如 Rust) 、topic (如 async) 、license (如 MIT) 、min_stars、max_stars、archived 和 fork——用于描述 GitHub 仓库。索引中的大多数文档页面来自已爬取的网站,并不对应任何仓库,因此无法通过仓库属性将这类页面纳入或排除。
因此,请求中使用任一此类筛选条件但未通过 sources 限定范围时,不会返回 doc 结果。响应中只包含 GitHub 证据:issue、pull_request 和 readme 类型。由于索引的文档部分根本不会执行,coverage 映射会将 doc 标记为 unavailable。这是预期设计,并非索引故障。
如需保留文档结果,请移除仓库筛选条件。你也可以通过 sources 限定文档部分的范围,然后查看 coverage,确认 doc 类型是否返回了答案。
sources 可接受的值
sources 不是固定的枚举类型。它接受文档来源 ID;每个 ID 都是长度不超过 512 个字符的非空字符串,且每个请求最多可传入 20 个。这些 ID 对应索引中的文档站点,集合会随时间不断扩展。
要确认某个 ID 是否有效,请传入该 ID,然后查看响应中新增的 sources 数组。该数组仅在你传入 sources 时出现,并会按请求中的原样返回每个 ID 及其是否已被索引:
indexed: true 表示该 source 存在已发布的 generation,因此可能会出现来自该 source 的文档证据。indexed: false 表示该 id 中没有任何内容可以匹配,这可区分不在索引中的 id 与仅仅未找到结果的 query。
repos 也会以相同方式返回,作为一个 repos Array,其中包含 indexed,并在 types 下提供按 Type 划分的明细:
解读 coverage
coverage 会报告每种结果类型的状态:ok、degraded、unavailable 或 skipped。如果缺少预期的结果类型,请检查此字段:
skipped表示你的types值未包含该类型degraded或unavailable表示缺失是由索引或筛选条件造成的,而非查询。仓库筛选条件便是原因之一,如仓库筛选条件如何限定搜索范围所述
授权
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
查询参数
自然语言问题或搜索短语。
1要返回的排序结果数量。
1 <= x <= 100要搜索的结果类型。默认值为全部四种类型。支持重复参数(types=issue&types=pull_request)或单个逗号分隔的值(types=issue,pull_request)。
doc, issue, pull_request, readme 用于限定索引中 GitHub 部分范围的仓库 slug,例如 firecrawl/firecrawl。仅适用于 issue、pull_request 和 readme 类型。与 sources 一同发送时,这两部分会合并而非取交集,因此会返回任一部分的匹配结果。当 types 中不包含 GitHub 类型时,返回 400,并附带 repos cannot match any requested type; add github types or drop repos。
用于限定文档部分范围的文档源 ID,最多 20 个。仅适用于 doc 类型。并非固定枚举:ID 对应索引中的文档站点,且该集合会随时间增长,因此请通过发送该 ID 并读取响应中的 sources 数组来确认其是否可解析。当 types 中不包含 doc 时,返回 400,并附带 sources cannot match any requested type; add doc or drop sources。
201 - 512将其设为 only,以将搜索限定为已编入索引的代理技能文件。
only 每个结果要返回的匹配段落数。
1 <= x <= 5仓库主要编程语言,例如 Rust。仅适用于 GitHub 结果;未指定 sources 范围时,发送该参数不会返回 doc 结果。请参见仓库筛选条件如何限定搜索范围。
"Rust"
仓库主题,例如 async。仅适用于 GitHub 结果;如果未指定 sources 范围,发送此参数不会返回 doc 结果。
"async"
仓库许可证,例如 MIT。仅适用于 GitHub 结果;如果未指定 sources 范围,发送此参数不会返回 doc 结果。
"MIT"
仓库星标数下限。仅适用于 GitHub 结果;如果未指定 sources 范围,发送此参数不会返回 doc 结果。
x >= 0仓库星标数上限。仅适用于 GitHub 结果;未指定 sources 范围时,传入此参数不会返回 doc 结果。
x >= 0是否包含或排除已归档的仓库。仅适用于 GitHub 结果;未指定 sources 范围时,传入此参数不会返回 doc 结果。
是否包含或排除派生仓库。仅适用于 GitHub 结果;未指定 sources 范围时,传入此参数不会返回 doc 结果。
响应
包含匹配段落的排序后开发者结果。
各结果类型的结果状态。当预期的结果类型缺失时,请检查此项:skipped 表示你的 types 值未请求该类型,而 degraded 或 unavailable 表示缺失源于索引或筛选条件,而非查询。仓库筛选条件便是其中一个原因——请参见仓库筛选条件如何限定搜索范围。
仅在传入 repos 时出现。返回每个 slug 是否已编入索引,以及 types 下按类型划分的明细。
排序列表是否经过重新排序阶段。
仅在发送了 sources 时出现。按请求原样返回每个 ID 及其是否已编入索引。indexed: true 表示该来源有已发布的生成版本,因此其中的文档证据可能会出现;indexed: false 表示该 ID 中的内容均无法匹配,这可区分不在索引中的 ID 与仅仅未找到任何结果的查询。

