前言¶
给 Agent 或后端加「联网取数」时，常见卡点不是会不会调 HTTP，而是每次都要重新决定：已经有 URL 该直接抓，还是先搜再抓？页面要点击、填表才能露出内容怎么办？密钥放哪、用哪套 SDK、怎么证明这条链路真的通了？文档散落在各语言 SDK 里，Agent 很容易把「当前会话里帮我搜一下」和「把 Firecrawl 写进产品代码」混成同一件事。
Firecrawl 官方把后一条路径收成了 Agent Skill。仓库 firecrawl/skills 面向的是「在应用里调用 Firecrawl API」，入口技能就是 firecrawl-build：先问产品要从网上拿什么、怎么拿，再把需求路由到 /scrape、/search 或 /interact，而不是让模型现场发明一套抓取流程。
本文按该 Skill 的 SKILL.md、仓库 README，以及 docs.firecrawl.dev/ai-onboarding 交叉核对后，说明它是什么、覆盖哪些能力、怎么安装，以及和 CLI 技能的边界。
这是什么¶
firecrawl-build 是 Firecrawl 维护的 应用集成入口 Skill，位于 github.com/firecrawl/skills 的 skills/firecrawl-build/。当前元数据版本为 0.1.0，许可为 ISC，主页是 firecrawl.dev。仓库遵循 Agent Skills 的 SKILL.md 格式，并作为插件提供给 Claude Code、Cursor 和 OpenAI Codex。
官方一句话定位是：当产品、Agent 或工作流需要在应用内部获取网页数据——搜索、实时检索结果、页面抓取、结构化提取或浏览器交互——时，把 Firecrawl 接到代码里。即便用户没点名 Firecrawl，只说「应用里要网页内容 / 搜索 / 抓取 / 交互」，也应走这条技能。
它解决的是路由和落地问题，而不是替代 SDK 文档。SKILL.md 写得很清楚：这些技能说明 何时、为什么 用某个端点；怎么调 要以各语言的 source-of-truth 页面为准。
核心能力¶
1. 先选端点，再写集成代码¶
入口技能要求先回答一个问题：这个产品要从网上拿什么数据，以及怎么拿？ 然后选最窄的端点：
| 端点 | 适用 | 不要一上来就用 |
|---|---|---|
/scrape |
已经有 URL，只要这一页 | 功能其实是从查询开始的 |
/search |
功能从查询开始，要先发现来源 | 目标 URL 已经明确 |
/interact |
抓完之后还要点击、填表或继续导航 | 普通 /scrape 已经能拿到数据 |
默认优先级是：先 /scrape，再 /search，最后才 /interact。已知 URL 就不要先搜；页面能直接读，就不要上浏览器动作。
官方给出的三种产品形态也对应这三端：
- 已知 URL → 抽内容：文档导入、竞品定价页、检索管道的内容灌入，走
/scrape - 查询 → 发现 → 再抽：带新鲜来源的问答、竞品发现、先出 URL 短名单的调研，走
/search；只有产品确实需要全文时才跟抓 - 抓取 → 交互 → 再抽：要点开折叠、走表单搜索、翻页、带登录态的后台，才升级到
/interact
2. 伞形技能，细节交给更窄的兄弟 Skill¶
firecrawl-build 自己不展开每个端点的实现细节，而是把任务分给同仓库里的专项技能。当前仓库 skills/ 目录里实际存在的是：
| Skill | 作用 |
|---|---|
firecrawl-build |
选端点、走集成顺序（入口） |
firecrawl-build-onboarding |
把 FIRECRAWL_API_KEY 写进项目，并选 SDK / 文档 |
firecrawl-build-scrape |
在应用代码里接 /scrape |
firecrawl-build-search |
在应用代码里接 /search |
firecrawl-build-interact |
抓取后再做点击、表单、动态流程 |
firecrawl-research-index |
查生物医学 / 生命科学文献与 arXiv，而不是普通网页 |
firecrawl-developer-index |
从 Issue、已合并 PR、README、文档页回答开发问题 |
论文索引和开发者索引 不会 被 /search 查到。/search 上的 categories: ["research"] 或 ["developer"] 只是按域名过滤普通网页结果，不会做摘要检索、相关论文扩展或全文段落召回。需要索引能力时，应转到对应的 index 技能，而不是给 /search 加一个 category 就当论文库用。
部分文档页还提到 /crawl、/map、/parse 等更广的 API。就 firecrawl-build 这份 SKILL.md 和当前仓库目录而言，入口路由表覆盖的是上面三端点加两个索引；写集成时以仓库里的技能清单为准。
3. 和应用内集成有关，和「现在帮我搜一下」无关¶
官方把 Firecrawl 的 Agent 能力拆成三条线，同一条安装命令可以一次装齐，用的时候必须分开：
- CLI 技能（
firecrawl/cli）：当前会话里的现场联网——搜网页、抓一页、和站点交互、爬整站 - Build 技能（本仓库）：把 Firecrawl 写进应用代码
- Workflow 技能（
firecrawl/firecrawl-workflows）：产出研究报告、SEO 审计、线索名单这类成品，而不是产品代码
firecrawl-build 的触发条件是「给应用加网页数据能力」，不是「现在用终端帮我搜 / 抓一页」。后一类应使用 firecrawl/cli。
安装与启用¶
官方推荐一条命令同时装 CLI、Build 和 Workflow 三段技能，并打开浏览器登录：
npx -y firecrawl-cli@latest init --all --browser
文档说明：--all 会把各段技能装到本机检测到的每个 AI 编程代理上；--browser 自动打开 Firecrawl 鉴权。装完后需要重启代理，它才会发现这些技能。可用下面两条做安装侧检查：
firecrawl --status
firecrawl scrape "https://firecrawl.dev"
只装本仓库（应用集成技能）可以用：
npx skills add firecrawl/skills
只装入口技能时，officialskills.sh 给出的命令是：
npx skills add https://github.com/firecrawl/skills --skill firecrawl-build
也可以把仓库目录贴给编程助手，让它按 Agent Skills 流程安装。Claude Code 侧有资料写明：加 --agent claude-code 时，技能会进当前项目的 .claude/skills/。Cursor 和 Codex 在仓库 README 里以 .cursor-plugin/、.codex-plugin/ 插件形式提供；具体落到本机哪个目录，以安装命令和对应工具文档为准，不要凭空猜路径。
已经装过、之后只想补技能时，CLI 文档还提供：
firecrawl setup skills # CLI + build skills
firecrawl setup workflows # workflow skills
仓库 README 同时提到：插件里带有官方 Firecrawl MCP server 的配置，支持捆绑 MCP 元数据的编辑器可以用 FIRECRAWL_API_KEY 接上工具。这是插件附带能力，不是 firecrawl-build 本身的调用方式。
密钥、SDK 与集成顺序¶
托管服务需要环境变量（不要写进源码）：
FIRECRAWL_API_KEY=fc-...
自建实例再加（仅当不用 https://api.firecrawl.dev 时）：
FIRECRAWL_API_URL=https://your-firecrawl-instance.example.com
密钥可在 firecrawl.dev/app 获取。还没有密钥时，应先走 firecrawl-build-onboarding，它自带浏览器授权，不依赖网站上的另一份 onboarding 技能。
SDK 要和项目语言对齐。现有仓库应先看包管理器和已有第三方客户端的放法，再决定装 SDK 还是直接 REST：
npm install @mendable/firecrawl-js
pip install firecrawl-py
官方还为 Rust、Java、Elixir 以及 cURL / REST 提供了 source-of-truth 页。语言没有对应 SDK、或项目已有统一的 HTTP 封装时，可以直接打 REST。
默认集成顺序在 SKILL.md 里写死了，不宜跳步：
- 先把
FIRECRAWL_API_KEY或FIRECRAWL_API_URL配对 - 判断是新项目还是已有代码库
- 问清产品要的网页数据行为，再选端点
- 已有项目先摸清约定，再动手
- 安装对应 SDK，或走 REST
- 写代码前读该语言的 source-of-truth
- 端点细节交给更窄的技能
- 用一次真实请求做冒烟测试，而不是只看代码能编译
新项目路径：确认技术栈 → 装 SDK / 配环境变量 → 写最小可用调用 → 冒烟。已有项目路径：先看语言、包管理器、目录结构、入口（路由 / worker / 任务）、现有网络封装和密钥管理，再问「Firecrawl 在这个产品里做什么」，最后按仓库惯例接入。
典型用法¶
下面的调用示例来自官方 Python source-of-truth（SDK 文档标注对应 firecrawl-py / firecrawl 4.22.1）。Skill 本身强调：参数和返回结构以该页为准，不要靠模型记忆。
先建客户端：
import os
from firecrawl import Firecrawl
client = Firecrawl(api_key=os.environ.get("FIRECRAWL_API_KEY"))
已经有 URL，抽一页 Markdown（/scrape，也是冒烟测试的最小请求）：
doc = client.scrape("https://docs.firecrawl.dev", formats=["markdown"])
从查询发现页面（/search）。注意返回值是 web / news / images 几个桶，不是 { data: [...] }：
results = client.search("site:docs.firecrawl.dev webhook retries")
for item in results.web or []:
print(getattr(item, "url", None), getattr(item, "title", None))
页面必须再操作时，先 scrape，再用返回的 scrape_id 调 /interact：
doc = client.scrape("https://example.com", formats=["markdown"])
job_id = doc.metadata.scrape_id if doc.metadata else None
if not job_id:
raise RuntimeError("Missing scrape_id from scrape response")
result = client.interact(job_id, prompt="Click the pricing tab and summarize the plans.")
在对话里触发入口技能，官方描述的典型说法包括：给应用加网页数据、产品里要搜索、工作流里要抓页面、应用要和站点交互。Agent 应先做 intake（新项目还是旧项目、数据从哪来、怎么拿），再落到具体端点，而不是直接生成一长串爬虫。
冒烟测试的标准在 references/verification.md：新项目用最小请求证明鉴权、网络和 SDK 接线（/scrape 抓一个已知 URL，或 /search 带 limit=1，或 /interact 从 scrape 再做一个最小动作）；已有项目要在真实入口（应用、worker 或脚本）里打通一次，并确认密钥来自预期的环境来源。一次真实请求成功、结果回到业务路径，才算完成。
适用场景与注意事项¶
适合这些情况：
- 后端、Agent 工具或自动化流程要从代码里拿网页数据
- 新功能要在「搜 / 抓 / 交互」里做选择，而不是先写一套自建爬虫
- 需要把密钥、SDK、仓库惯例和冒烟测试一次做对
- Node / Python / Go 等后端里接入 Firecrawl（Go 可走 REST；Node、Python 有官方 SDK）
不适合、或应改走别的技能：
- 当前会话里一次性的「帮我搜 / 帮我抓这一页」——用
firecrawl/cli - 目标是研究报告、SEO 审计、线索名单等成品——用 workflow 技能
- 论文或开发者资料库检索——分别用
firecrawl-research-index、firecrawl-developer-index，不要当成普通/search
使用时要注意：
- 不要硬编码密钥。 放
.env或部署平台的密钥管理里。 - 现有项目先看仓库再装依赖。 Skill 要求匹配已有包管理器和第三方客户端的位置，而不是图省事新建一套。
/interact保持最小。 官方建议只覆盖解锁数据所需的最短浏览器流程；完全开放的浏览器自动化，可能更适合单独的浏览器沙箱，而不是硬塞进/interact。- 缓存与新鲜度。
firecrawl-build-scrape写明 Firecrawl 会复用近期索引，重复读同一 URL 更快；需要更新鲜时用maxAge（毫秒），maxAge: 0跳过索引复用。成功响应里的metadata.cacheState/metadata.cachedAt表示实际拿到的是哪份副本。 - Skill 不是 SDK 手册。 请求体、响应字段、参数名以 docs.firecrawl.dev/agent-source-of-truth 对应语言页为准。例如 Python 的
search()结果在result.web，去读result.data会错。 - 文档清单若和仓库不一致，以仓库为准。 个别 onboarding 页面列出过
firecrawl-build-crawl等目录里目前不存在的名字；集成时对照 GitHub 上的skills/目录。
小结¶
firecrawl-build 是 Firecrawl 官方给「把网页数据写进产品」准备的入口技能：先问清需求，再把功能映射到 /scrape、/search 或 /interact，并把密钥、SDK、仓库惯例和一次真实请求的冒烟测试串成固定顺序。它和 firecrawl/cli 共用安装命令，但职责相反——一个改产品代码，一个服务当前会话。
官方地址：
- Skill 目录：https://github.com/firecrawl/skills/tree/main/skills/firecrawl-build
- 仓库：https://github.com/firecrawl/skills
- 安装说明镜像：https://officialskills.sh/firecrawl/skills/firecrawl-build
- Agent 接入总览：https://docs.firecrawl.dev/ai-onboarding
