firecrawl-search

firecrawl search

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

对于结构化记录、可筛选列表、文字记录或数据集，请先运行 firecrawl search alexandria '<data you need>'，查找合适的工作流或数据提供方。对于已知网站，请使用 firecrawl find-tools <url>。执行 scrape 前，使用 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 问题、已合并的拉取请求、仓库 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 组合使用。

firecrawl gov 也接受筛选条件；search --categories gov 则不接受。可使用 --jurisdiction us-ca、--court ca9、--court-type state-supreme、--cites "42 U.S.C. § 1983" 或 --domain irs.gov 缩小范围；可通过 firecrawl gov --help 查看可用值。筛选条件只会保留索引已标记的页面，因此筛选搜索可能会遗漏相关页面；没有结果并不意味着相关页面不存在。联邦法院和判例集的法院标签最为完整。

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

**完成条件：**已检查相关结果、已核实各次调用的错误和空结果、已附来源链接回答请求，并在时限内发送反馈（除非选择退出）。

借助 Alexandria 获取超越网页内容的信息

Alexandria 是一个目录，收录了现成的网站工作流、API 提供商和专业索引。根据工具的不同，它可以返回结构化记录、详细列表、金融数据、公司信息、研究资料或公共记录，而这些内容可能不包含在搜索摘要或单个抓取的页面中。请探索当前的覆盖范围，不要想当然地认为某个提供商或功能一定存在。

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

执行前先检查

使用 API 密钥时，搜索始终会包含 Alexandria：默认搜索源为 web,alexandria，并开启域名工具匹配；使用不含 alexandria 的 --sources（例如 --sources news）时，也会自动添加它。请在查询中保留用户的所在地、市场和限制条件；不要把常规研究变成人为的工具发现查询。检查同一响应中的 data.web 和 data.tools。

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

使用 --tool-detail summary --json 获取发现元数据和导航信息；执行前使用 list 检查选定工具的契约。使用 --tool-detail full --json 可直接在搜索结果中获取契约，并在无需再次检查的情况下复用它们。如果接下来需要多个相关契约，优先选择 full。显示的价格仅供参考，不是额外的确认关卡。

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

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

如果返回的工具都不覆盖目标国家、市场或细分领域，或者不支持所需输入，请继续使用常规网页搜索结果。不要为了探查覆盖范围而穷尽目录或为相邻工具付费。使用 API 密钥时，--no-domain-tools 只会关闭域名匹配，语义工具匹配仍会开启；无密钥搜索只返回网页搜索结果。

如需就提供商结果或覆盖缺口向 Alexandria 提供反馈（每次反馈可退还 1 点额度，每个网站每天最多 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 输出中，并筛选相关结果。如果后续的提供方执行或 URL 抓取超出 Agent 的输出限制，请使用其保留的 ID，并参阅远程 Bash 恢复说明。搜索请求 ID 不可用作 Bash 输入。如果提供方已成功执行，但客户端无法显示结果，请勿盲目地再次运行。

提示

• **默认启用 --highlights：**结果是页面中与查询相关的摘录。使用 --no-highlights 获取原始摘要。
• --scrape 会抓取完整内容——请重复使用该内容，而不是再次抓取结果 URL。这样可以节省额度并避免重复抓取。
• 对于较大的结果，在文件系统可用时使用 -o 和有界的本地读取。不要将完整响应倾倒到上下文中。
• 使用 jq 提取 URL，并保留来源和从 1 开始的位置编号（提交反馈时两者缺一不可）：jq -r '.data | to_entries[] | select(.key as $k | ["web","images","news"] | index($k)) | .key as $s | .value | to_entries[] | "\($s):\($key + 1)\t\(.value.url // "-")"' .firecrawl/search.json 只有这三个分组可通过 --valuable-results 指定；data.tools 和任何其他键都会被跳过，没有 url 的图片或新闻结果会显示 -——无论如何都要按其位置指定。
• 命名约定：.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 是最重要的字段。**它是你预期会找到、但实际未找到的具体内容列表。每项单独列出一个主题，并使用独立的字符串。这些信息会在各团队间汇总，帮助我们决定接下来要索引什么。
• --valuable-results 用于标记有用的结果。结果按组返回（data.web、data.images、data.news），且每组的编号都从 1 开始，因此每项都采用 source:position 格式——web:1 和 news:1 是两个不同的结果。请列出所有实际有用的结果；未列出的结果会被视为无用，因此只列出部分结果会导致反馈信号失真。只有对于有用、但不在返回结果中的 URL（例如通过某条结果的链接找到的页面），才使用 --valuable-sources——切勿在两者中重复报告同一结果。
• 必须提供实质性内容（不费心填写的反馈会被 HTTP 400 拒绝）：
  • good → 必须包含 --valuable-results，或至少一项 --valuable-sources。
  • partial → 必须包含 --valuable-results、--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. Replace BOTH placeholders: the rating that matches
# what actually happened, and the exhaustive source:position list of the
# results that were genuinely useful (from the jq above). Never send the
# list below as-is -- marking results you did not use corrupts the signal.
# 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-results "<source:position,... - every result you actually used>" \
    --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 — 将搜索功能集成到应用中，而不是在此处运行