> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# 搜索 Developer Index

搜索公开代码仓库中的 issue、已合并的拉取请求和 README，以及精选文档站点。结果按相关性排序，并以 Markdown 格式提供匹配段落。

如需将数组筛选条件作为 JSON 传递，可在同一路径使用 `POST`。

可重复指定的筛选条件在 `GET` 中支持以下任一形式：重复的查询参数，例如 `types=issue&types=pull_request`，或以逗号分隔的单个值，例如 `types=issue,pull_request`。

<div id="how-repos-and-sources-scope-a-search">
  ## `repos` 和 `sources` 如何限定搜索范围
</div>

索引分为两部分，这两个筛选条件分别限定各自部分的搜索范围：

* `repos` 限定仓库部分，即 `issue`、`pull_request` 和 `readme` 类型
* `sources` 限定文档部分，即 `doc` 类型
* 同时传入两者会合并这两部分，而非取交集，因此会返回任一部分中的匹配结果

由于每个筛选条件仅适用于其中一部分，无法匹配任何请求类型的筛选条件会被拒绝，而不会静默地返回空结果：

* 当 `types` 中不包含仓库类型时，`repos` 会返回 `400`，提示 `repos` 无法匹配任何请求类型，且应添加仓库类型或移除 `repos`
* 当 `types` 中不包含 `doc` 时，`sources` 会返回 `400`，并提示 `sources cannot match any requested type; add doc or drop sources`

<div id="how-the-repository-filters-scope-a-search">
  ## 仓库筛选条件如何限定搜索范围
</div>

七个仓库筛选条件——`language` (如 `Rust`) 、`topic` (如 `async`) 、`license` (如 `MIT`) 、`min_stars`、`max_stars`、`archived` 和 `fork`——用于描述代码仓库。索引中的大多数文档页面来自已爬取的网站，并不对应任何仓库，因此无法通过仓库属性将这类页面纳入或排除。

因此，请求中使用任一此类筛选条件但未通过 `sources` 限定范围时，不会返回 `doc` 结果。响应中只包含仓库证据：`issue`、`pull_request` 和 `readme` 类型。由于索引的文档部分根本不会执行，`coverage` 映射会将 `doc` 标记为 `unavailable`。这是预期设计，并非索引故障。

如需保留文档结果，请移除仓库筛选条件。你也可以通过 `sources` 限定文档部分的范围，然后查看 `coverage`，确认 `doc` 类型是否返回了答案。

<CodeGroup>
  ```bash cURL theme={null}
  # 无需 API 密钥即可开始使用；如需更高的限流额度，请添加 -H "Authorization: Bearer $FIRECRAWL_API_KEY"：
  curl -s "https://api.firecrawl.dev/v2/search/developer?query=how%20do%20I%20configure%20retries&k=10&language=Rust&license=MIT"
  ```

  ```bash cURL (POST) theme={null}
  curl -X POST https://api.firecrawl.dev/v2/search/developer \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "how do I configure retries",
      "k": 10,
      "types": ["issue", "pull_request"],
      "language": "Rust",
      "license": "MIT"
    }'
  ```
</CodeGroup>

<div id="which-values-sources-accepts">
  ## `sources` 可接受的值
</div>

`sources` 不是固定的枚举类型。它接受文档来源 ID；每个 ID 都是长度不超过 512 个字符的非空字符串，且每个请求最多可传入 20 个。这些 ID 对应索引中的文档站点，集合会随时间不断扩展。

要确认某个 ID 是否有效，请传入该 ID，然后查看响应中新增的 `sources` 数组。该数组仅在你传入 `sources` 时出现，并会按请求中的原样返回每个 ID 及其是否已被索引：

```json theme={null}
{
  "success": true,
  "results": [],
  "sources": [
    { "source": "some-docs-site", "indexed": true },
    { "source": "unknown-docs-site", "indexed": false }
  ]
}
```

`indexed: true` 表示该 source 存在已发布的 generation，因此可能会出现来自该 source 的文档证据。`indexed: false` 表示该 id 中没有任何内容可以匹配，这可区分不在索引中的 id 与仅仅未找到结果的 query。

`repos` 也会以相同方式返回，作为一个 `repos` Array，其中包含 `indexed`，并在 `types` 下提供按 Type 划分的明细：

```json theme={null}
{
  "success": true,
  "results": [],
  "repos": [
    {
      "repo": "firecrawl/firecrawl",
      "indexed": true,
      "types": { "issue": true, "pullRequest": true, "readme": true }
    }
  ]
}
```

<div id="reading-coverage">
  ## 解读 `coverage`
</div>

`coverage` 会报告每种结果类型的状态：`ok`、`degraded`、`unavailable` 或 `skipped`。如果缺少预期的结果类型，请检查此字段：

* `skipped` 表示你的 `types` 值未包含该类型
* `degraded` 或 `unavailable` 表示缺失是由索引或筛选条件造成的，而非查询。仓库筛选条件便是原因之一，如[仓库筛选条件如何限定搜索范围](#how-the-repository-filters-scope-a-search)所述

如需了解工作流概览，请参见 [Developer Index 指南](/zh/features/developer)。


## OpenAPI

````yaml zh/api-reference/v2-openapi.json GET /search/developer
openapi: 3.0.0
info:
  contact:
    email: support@firecrawl.dev
    name: Firecrawl Support
    url: https://firecrawl.dev/support
  description: 用于与 Firecrawl 服务交互，执行网页抓取和爬取任务的 API。
  title: Firecrawl API
  version: v2
servers:
  - url: https://api.firecrawl.dev/v2
security:
  - bearerAuth: []
paths:
  /search/developer:
    get:
      tags:
        - Developer
      summary: 搜索开发者索引
      operationId: developerSearch
      parameters:
        - description: 自然语言问题或搜索短语。
          in: query
          name: query
          required: true
          schema:
            minLength: 1
            type: string
        - description: 要返回的排序结果数量。
          in: query
          name: k
          required: false
          schema:
            default: 10
            maximum: 100
            minimum: 1
            type: integer
        - description: >-
            要搜索的结果类型。默认值为全部四种类型。支持重复参数（`types=issue&types=pull_request`）或单个逗号分隔的值（`types=issue,pull_request`）。
          in: query
          name: types
          required: false
          schema:
            items:
              enum:
                - doc
                - issue
                - pull_request
                - readme
              type: string
            type: array
        - description: >-
            用于限定索引中仓库部分范围的仓库 slug，例如 `firecrawl/firecrawl`。仅适用于
            `issue`、`pull_request` 和 `readme` 类型。与 `sources`
            一同发送时，这两部分会合并而非取交集，因此会返回任一部分的匹配结果。当 `types` 中不包含仓库类型时，返回 400，并报告
            `repos` 无法匹配任何请求的类型，且应添加仓库类型或移除 `repos`。
          in: query
          name: repos
          required: false
          schema:
            items:
              type: string
            type: array
        - description: >-
            用于限定文档部分范围的文档源 ID，最多 20 个。仅适用于 `doc` 类型。并非固定枚举：ID
            对应索引中的文档站点，且该集合会随时间增长，因此请通过发送该 ID 并读取响应中的 `sources` 数组来确认其是否可解析。当
            `types` 中不包含 `doc` 时，返回 400，并附带 `sources cannot match any requested
            type; add doc or drop sources`。
          in: query
          name: sources
          required: false
          schema:
            items:
              maxLength: 512
              minLength: 1
              type: string
            maxItems: 20
            type: array
        - description: 将其设为 `only`，以将搜索限定为已编入索引的代理技能文件。
          in: query
          name: skills
          required: false
          schema:
            enum:
              - only
            type: string
        - description: 每个结果要返回的匹配段落数。
          in: query
          name: passages
          required: false
          schema:
            default: 1
            maximum: 5
            minimum: 1
            type: integer
        - description: >-
            仓库主要编程语言，例如 `Rust`。仅适用于仓库结果；未指定 `sources` 范围时，发送该参数不会返回 `doc`
            结果。请参见[仓库筛选条件如何限定搜索范围](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search)。
          in: query
          name: language
          required: false
          schema:
            example: Rust
            type: string
        - description: 仓库主题，例如 `async`。仅适用于仓库结果；如果未指定 `sources` 范围，发送此参数不会返回 `doc` 结果。
          in: query
          name: topic
          required: false
          schema:
            example: async
            type: string
        - description: 仓库许可证，例如 `MIT`。仅适用于仓库结果；如果未指定 `sources` 范围，发送此参数不会返回 `doc` 结果。
          in: query
          name: license
          required: false
          schema:
            example: MIT
            type: string
        - description: 仓库星标数下限。仅适用于仓库结果；如果未指定 `sources` 范围，发送此参数不会返回 `doc` 结果。
          in: query
          name: min_stars
          required: false
          schema:
            minimum: 0
            type: integer
        - description: 仓库星标数上限。仅适用于仓库结果；未指定 `sources` 范围时，传入此参数不会返回 `doc` 结果。
          in: query
          name: max_stars
          required: false
          schema:
            minimum: 0
            type: integer
        - description: 是否包含或排除已归档的仓库。仅适用于仓库结果；未指定 `sources` 范围时，传入此参数不会返回 `doc` 结果。
          in: query
          name: archived
          required: false
          schema:
            type: boolean
        - description: 是否包含或排除派生仓库。仅适用于仓库结果；未指定 `sources` 范围时，传入此参数不会返回 `doc` 结果。
          in: query
          name: fork
          required: false
          schema:
            type: boolean
      responses:
        '200':
          content:
            application/json:
              example:
                coverage:
                  doc: ok
                  issue: ok
                  pull_request: ok
                  readme: ok
                reranked: true
                results:
                  - id: issue:firecrawl/firecrawl#1234
                    passages:
                      - text: >-
                          The client treats 429 as a terminal status, so the
                          backoff never runs.
                    title: Retries are not applied to 429 responses
                    type: issue
                    url: https://github.com/firecrawl/firecrawl/issues/1234
                success: true
              schema:
                $ref: '#/components/schemas/DeveloperSearchResponse'
          description: 包含匹配段落的排序后开发者结果。
        '400':
          description: 无效请求，包括无法匹配任何所请求类型的过滤条件
        '401':
          description: 缺少或无效的 Bearer 令牌
        '429':
          description: 超出限流
        '500':
          description: 内部服务器错误
      security:
        - bearerAuth: []
components:
  schemas:
    DeveloperSearchResponse:
      properties:
        coverage:
          description: >-
            各结果类型的结果状态。当预期的结果类型缺失时，请检查此项：`skipped` 表示你的 `types` 值未请求该类型，而
            `degraded` 或 `unavailable`
            表示缺失源于索引或筛选条件，而非查询。仓库筛选条件便是其中一个原因——请参见[仓库筛选条件如何限定搜索范围](/api-reference/endpoint/developer-search#how-the-repository-filters-scope-a-search)。
          properties:
            doc:
              enum:
                - ok
                - degraded
                - unavailable
                - skipped
              type: string
            issue:
              enum:
                - ok
                - degraded
                - unavailable
                - skipped
              type: string
            pull_request:
              enum:
                - ok
                - degraded
                - unavailable
                - skipped
              type: string
            readme:
              enum:
                - ok
                - degraded
                - unavailable
                - skipped
              type: string
          type: object
        repos:
          description: 仅在传入 `repos` 时出现。返回每个 slug 是否已编入索引，以及 `types` 下按类型划分的明细。
          example:
            - indexed: true
              repo: firecrawl/firecrawl
              types:
                issue: true
                pullRequest: true
                readme: true
          items:
            properties:
              indexed:
                type: boolean
              repo:
                type: string
              types:
                description: 此仓库中已编入索引的 GitHub 结果类型：`issue`、`pullRequest` 和 `readme`。
                properties:
                  issue:
                    type: boolean
                  pullRequest:
                    type: boolean
                  readme:
                    type: boolean
                type: object
            type: object
          type: array
        reranked:
          description: 排序列表是否经过重新排序阶段。
          type: boolean
        results:
          items:
            $ref: '#/components/schemas/DeveloperSearchResult'
          type: array
        sources:
          description: >-
            仅在发送了 `sources` 时出现。按请求原样返回每个 ID 及其是否已编入索引。`indexed: true`
            表示该来源有已发布的生成版本，因此其中的文档证据可能会出现；`indexed: false` 表示该 ID
            中的内容均无法匹配，这可区分不在索引中的 ID 与仅仅未找到任何结果的查询。
          example:
            - indexed: true
              source: some-docs-site
            - indexed: false
              source: unknown-docs-site
          items:
            properties:
              indexed:
                type: boolean
              source:
                type: string
            type: object
          type: array
        success:
          type: boolean
      type: object
    DeveloperSearchResult:
      properties:
        id:
          description: 稳定的结果 ID，例如 `issue:owner/repo#123`。
          example: issue:firecrawl/firecrawl#1234
          type: string
        passages:
          description: 以 Markdown 格式返回匹配段落，以保留表格和代码块。
          items:
            properties:
              text:
                type: string
            type: object
          type: array
        title:
          description: '`doc` 结果中通常缺少此项，因为源页面没有可用标题。请改用 `url`。'
          type: string
        type:
          description: 结果类型。
          enum:
            - doc
            - issue
            - pull_request
            - readme
          type: string
        url:
          format: uri
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      scheme: bearer
      type: http

````