firecrawl-search

firecrawl 搜索

根据用户的实际问题进行自然语言搜索。默认搜索会返回网页结果和相关的 Alexandria 工具，并可选择抓取网页内容。

对于结构化记录、可筛选列表、文字稿或数据集，请先运行 firecrawl search alexandria '<data you need>'，查找合适的工作流或数据提供方。对于已知网站，请使用 firecrawl find-tools <url>。执行工具前，先用 firecrawl list <provider> <capability> --pretty 检查选定的调用契约；如果发现过程中已返回完整契约，请重复使用。如果没有合适的工具，则继续进行网页搜索或使用 Agent。网页研究使用普通的 search，已知页面则使用 URL scrape。

快速开始

# Basic search
firecrawl search "your query" -o .firecrawl/result.json --json

# Search and scrape full page content from results
firecrawl search "your query" --scrape -o .firecrawl/scraped.json --json

# News from the past day
firecrawl search "your query" --sources news --tbs qdr:d -o .firecrawl/news.json --json

使用 firecrawl search --help 查看搜索选项，使用 firecrawl list --help 浏览调用契约，使用 firecrawl scrape --help 查看执行选项。

--categories developer 会搜索公开代码仓库、GitHub issues、已合并的拉取请求、代码仓库 README 和精选文档网站的索引。--categories gov 会搜索美国联邦、州和地方政府的法律及监管来源，且不能与其他类别组合使用。--categories research 是网站筛选器，不是论文索引。专用技能：firecrawl-developer-index 和 firecrawl-research-index。

政府索引

要查找美国法律或监管来源，请使用 firecrawl gov "<question, jurisdiction, and date>" --limit 10。使用 --limit 设置结果数量；-k 是 API 密钥选项。search --categories gov 也使用 --limit，并会在 data.web 中返回结果；请分别运行其他类别，不要与 gov 组合使用。

使用 scrape 直接读取提供的来源 URL。引用现行有效法律前，请核实来源的发布机构、司法管辖区、颁布/生效状态和版本。法案文本、机构指南、历史版本和第三方转载也需要核实。选择规则前，如果缺少司法管辖区信息，请先询问；非美国问题或覆盖范围不足时，请使用常规搜索。没有搜索结果并不能证明不存在适用法律。

**完成标准：**已检查相关结果，已核查每次调用的错误和空结果，已附来源链接回答请求，并在时间窗口内发送反馈，除非用户选择退出。

通过 Alexandria 获取超出页面内容的信息

Alexandria 是一个收录现成网站工作流、API 提供方和专用索引的目录。根据工具不同，它可以返回结构化记录、详细列表、财务数据、公司信息、研究资料或公共记录；这些内容可能无法从搜索摘要或单个抓取页面中获取。请发现当前覆盖范围，不要假设某个提供方或功能一定存在。

• 语义发现会根据用户问题的含义匹配工具功能，即使网页搜索结果中没有相关提供方的网站也能找到。只有在明确需要工具时，才使用 firecrawl search alexandria '<data you need>'。
• 域名匹配会显示与网页搜索结果中网站相关的工具。匹配的工具可能会获取比链接页面更丰富的详情、相关记录或结构化集合。域名匹配表示相关性，并不能证明该工具覆盖所需字段或市场。
• 组合搜索默认会将这两种方式与网页结果结合使用：firecrawl search '<user question>'。结果足够时请使用网页结果；如果匹配的工具能更直接地获取所需数据，则检查该工具。

执行前先检查

默认搜索范围为 web,alexandria，并启用域名工具匹配。保留用户查询中的位置、市场和约束；不要把常规研究变成刻意的工具发现查询。检查同一响应中的 data.web 和 data.tools。

默认情况下，搜索只返回精简的工具匹配信息：provider、capability 和 description。匹配结果不是已执行的数据。选择候选项后，使用其 provider 和 capability ID 运行 firecrawl list <provider> <capability> --pretty，以查看合约的输入、覆盖范围和访问要求。

使用 --tool-detail summary --json 获取发现元数据和导航信息；执行前用 list 检查所选合约。使用 --tool-detail full --json 可直接在搜索结果中获取合约，无需再次检查。若接下来要立即使用多个相关合约，优先选择 full。显示的定价仅供参考，不会构成额外的确认步骤。

检查合约后，使用 firecrawl scrape <provider/capability> --options '<input JSON>' 执行（仍支持 --alexandria）。所有 provider 执行都通过 Scrape 进行；search --scrape 只会获取网页搜索结果内容，不会调用 provider 工具。

使用 list 浏览类别和 provider，并查看所选合约。对于已知网站，find-tools <url> 可发现相关工具，但不会执行它们。运行 firecrawl find-tools --help 查看高级目录筛选器；除非任务需要，否则避免大范围扩展。

如果没有返回的工具覆盖所需的国家/市场/细分领域或输入要求，请继续使用普通网页搜索结果。不要为了探测覆盖范围而遍历整个目录，或为相邻工具付费。--sources web 会明确排除 Alexandria；--sources web --domain-tools 则仅保留域名匹配结果。

有关针对 provider 结果或覆盖缺口向 Alexandria 提交反馈（每条反馈返还 1 个 credit；每个网站每天最多 10 个，每个团队每天最多 100 个 UTC 日），请参阅 firecrawl-alexandria。

渐进式发现和输出处理

# Web + domain matching + semantic tools
firecrawl search '<user question>'

# Semantic tools only
firecrawl search alexandria '<user question>'

# Categories → providers → tools → contract
firecrawl list
firecrawl list <category-id> --category
firecrawl list <provider-id>
firecrawl list <provider-id> <capability-id> --pretty

# Execute a tool
firecrawl scrape <provider-id>/<capability-id> --options '<JSON matching the selected contract>'

默认搜索会合并网页结果、域名匹配和语义工具；search alexandria 仅返回语义工具匹配结果。查看所选合约，而不是展开整个目录。工具发现不等于执行。

将大型搜索响应保存到 --json -o 输出中，并筛选相关结果。如果后续的 provider 执行或 URL 抓取结果超过 Agent 的输出限制，请使用保留的 ID，并按照远程 Bash 恢复说明操作。搜索请求 ID 不能作为 Bash 输入。如果 provider 已成功执行，但客户端无法显示结果，不要盲目重新运行。

提示

• **默认启用 --highlights：**结果是页面中与查询相关的摘录。使用 --no-highlights 获取原始摘要。
• --scrape 会获取完整内容——复用这些内容，而不是重新抓取结果 URL。这样可以节省 credits，并避免重复抓取。
• 对于大型结果，如果有文件系统可用，请使用 -o 并在本地读取有限内容。不要将完整响应全部写入上下文。
• 使用 jq 提取 URL 或标题：jq -r '.data.web[].url' .firecrawl/search.json
• 命名约定：.firecrawl/search-{query}.json 或 .firecrawl/search-{query}-scraped.json

每次搜索后发送反馈（退还 1 个积分）

搜索消耗 2 个积分。在实际使用搜索结果（或确定结果没有用）后，使用 firecrawl search-feedback <id> 发送结构化反馈。每次搜索的首次反馈会退还 1 个积分，并帮助我们提升搜索质量。每次搜索只发送一次，在处理完结果后于后台发送——不会阻塞主要任务。

**选择退出：**如果设置了 FIRECRAWL_NO_SEARCH_FEEDBACK=1（或 FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1），CLI 会静默跳过调用，且绝不会发送任何内容。请遵守此设置——不要尝试绕过它。（团队管理员也可以在服务端禁用此功能；API 会返回 feedbackErrorCode: "TEAM_OPTED_OUT"，而 CLI 会静默地以 0 退出。）

调用前须知的规则：

• **时间窗口：**必须在搜索后约 2 分钟内发送。超时反馈会被拒绝。
• **--missing-content 是最重要的字段。**它是一个列表，列出你预期会找到但实际未找到的_具体内容_。每个条目写一个主题，并单独作为一个字符串。这些内容会在各团队之间汇总，并告诉我们接下来应索引什么。
• 必须提供实质性内容（敷衍的反馈会因 HTTP 400 被拒绝）：
  • good → 必须至少包含一个 --valuable-sources 条目。
  • partial → 必须包含 --valuable-sources 或 --missing-content。
  • bad → 必须包含 --missing-content 或 --query-suggestions。
• **每日退款上限（每个团队，按 UTC 日计算，默认 100 个积分）。**团队当天获退 100 个积分后，后续提交仍会记录反馈，但不再退还积分。响应会包含 creditsRefundedToday / dailyRefundCap / dailyCapReached。当 dailyCapReached: true 时，当天剩余时间内请停止调用 search-feedback——它不会退还任何积分，只会浪费带宽。
• **幂等：**对同一个搜索 ID 重新提交会返回成功，但不会额外退款。
• --silent & 是正确的用法——即使失败也会以退出码 0 结束，因此被拒绝或过期的调用不会导致流水线崩溃。

读取搜索结果的 id 前，请先确认搜索确实返回了结果。零结果搜索不会写入输出文件，因此文件可能不存在，也可能是之前搜索遗留的文件。以下守卫会在文件不存在或没有结果时跳过反馈；只在守卫内部调用 search-feedback：

# Send once per search. Rate honestly and replace the placeholder with the
# rating that matches what actually happened. The two fields shown
# satisfy the substantive-content rule for every rating.
if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then
  firecrawl search-feedback "$SEARCH_ID" \
    --rating "<good|partial|bad>" \
    --valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]' \
    --missing-content '[{"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}]' \
    --silent &
fi

--missing-content 支持：

• {topic, description?} 对象的 JSON 数组（信息最丰富，优先使用）
• "topic: description" 字符串（简写）
• 普通的 "topic1, topic2, topic3"（仅有主题名称时使用）
• 重复使用 --missing-content 标志

--silent 用于抑制输出，& 用于在后台运行，这样反馈就不会造成阻塞。

另请参阅

• firecrawl-scrape — 抓取指定 URL
• firecrawl-map — 发现网站内的 URL
• firecrawl-crawl — 批量提取网站内容
• firecrawl-developer-index — issues、已合并的 PR、README 和文档
• firecrawl-research-index — 已发表的论文，不是 search --categories research
• firecrawl-build-search — 将搜索功能集成到应用中，而不是在此处运行