scraper-studio

Bright Data — Scraper Studio

用自然语言构建爬虫，然后运行它。此技能包含两个命令：

• bdata scraper create <url> <description> — 用通俗的英语描述你的需求；Bright Data 的 AI Flow 会生成爬虫模板并返回一个 collector_id。
• bdata scraper run <collector_id> <url> — 使用该采集器（或 Bright Data Web UI 中的任何现有采集器）抓取 URL，并返回提取的数据。

两者之间通过 collector_id 衔接。 create 会输出它，run 会使用它。务必保存。

对于 Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit 等平台的预构建爬虫，请停止并改用 data-feeds 技能——这些爬虫已经存在，速度更快、成本更低，也更可靠。目标网站没有适用的预构建爬虫，或者用户希望为现有平台定制输出格式时，才使用 Scraper Studio。

设置检查（先运行）

if ! command -v bdata >/dev/null 2>&1; then
    echo "bdata CLI not installed — see bright-data-best-practices/references/cli-setup.md"
elif ! bdata zones >/dev/null 2>&1; then
    echo "bdata not authenticated — run: bdata login  (or: bdata login --device for SSH)"
fi

如果任一项检查失败，请停止并转到设置流程。两个命令都需要已通过身份验证的 CLI。

选择路径

情况	操作
用户描述了想从 URL 获取的数据，但尚无爬虫	bdata scraper create <url> "<description>" → 保存 collector_id
用户有 collector_id，想从一个 URL 获取数据	bdata scraper run <collector_id> <url>（默认异步运行并轮询）
用户有 collector_id，想从多个 URL 获取数据	bdata scraper run <collector_id> --urls "u1,u2,..." 或 --input-file urls.txt（单次批量调用）
页面较小，且希望快速获得反馈（≤ 约 50 秒，单个 URL）	bdata scraper run … --sync
爬虫已运行，但返回了错误、空白或不完整的数据	检查输出，然后运行 bdata scraper heal <collector_id> "<what's wrong>" → 查看预览 → 批准 → 重新运行以验证
网站是已知平台（Amazon、LinkedIn、TikTok 等）	停止——使用 data-feeds 技能
你需要的是 SERP / 发现，而非提取	使用 search 技能
你只需一次性获取原始页面	使用 scrape 技能

---

操作 1 — scraper create

根据 URL 和通俗的英语描述生成爬虫。

bdata scraper create <url> "<description>" [--name <name>] \
    [--deliver-webhook <url>] [--timeout <seconds>] \
    [--json | --pretty] [-o <path>] [--timing] [-k <api-key>]

描述是最重要的输入。好的描述会列出你需要的所有字段，以及查找这些字段时需要满足的条件。有关优质和欠佳描述的示例，请参阅 references/prompts.md。

# Minimal
bdata scraper create https://example.com/product/1 \
    "Extract title, price, currency, image URL, and availability \
     from this product page. If the price has a strike-through \
     original price, capture both as price and original_price."

# Save the full AI output for inspection
bdata scraper create https://example.com/product/1 \
    "Extract title, price, and image URL" \
    --name product-scraper-v1 \
    --pretty -o create.json

底层执行过程

create 会依次调用 Bright Data API 的三个接口——请向用户说明这一点，以便他们根据日志进行调试：

1. POST /dca/collector — 创建一个空爬虫模板，其中包含一个存根 Webhook 投递目标（默认值为 https://example.com/webhook）。返回一个类似 c_mp3tuab31lswoxvpws 的 collector_id。
2. POST /dca/collectors/{collector_id}/automate_template — 使用描述和 URL 触发 Bright Data 的 AI Flow。
3. GET .../automate_template/progress（轮询）— 等待 status: "done"。中等复杂度页面的生成通常需要 5–10 分钟。

重要：保留 collector_id

create 的所有失败情形（AI 触发失败、轮询超时、生成结束时 status: "failed"）仍会在输出的 collector_id 处留下一个部分构建的采集器。务必告知用户该 ID 可以恢复——他们可以：

• 打开 https://brightdata.com/cp/scrapers/{collector_id}，在 Web UI 中完成或检查采集器。
• 以编程方式使用同一 ID 重新触发生成。
• 如果想从头开始，可以在 UI 中删除它。

如果未显示响应中的 collector_id，切勿声称“创建失败，重新开始”。

--timeout — 默认 600 s

复杂页面的 AI 生成可能需要 5–10 分钟。如果页面简单，默认值就足够。对于内容繁杂且负载较重的网站，可以调高此值：

bdata scraper create https://complex-site.com/page \
    "Extract all 30 fields …" \
    --timeout 1200

出现 Timeout after N seconds waiting for AI generation 时，仍会打印 collector_id。请在 Web UI 中重新检查进度，而不是重新运行 create（这会新建一个 collector）。

--deliver-webhook — 默认使用占位值

CLI 会设置一个存根 webhook（https://example.com/webhook）。这满足 API 契约，但不会实际发送任何内容。使用 CLI 时，请保留此存根值——你可以通过 scraper run 同步获取结果。如果用户希望在生产运行中通过 webhook 接收内容，可以在 Bright Data Web UI 中重新配置实际接收目标。

---

操作 2 — scraper run

针对一个或多个 URL 执行爬虫。

bdata scraper run <collector_id> [url] \
    [--urls "u1,u2,..." | --input-file <path>] \
    [--sync [--sync-timeout 25-50]] \
    [--timeout <seconds>] [--name <name>] [--version <version>] \
    [--json | --pretty] [-o <path>] [--timing] [-k <api-key>]

**只能选择一个输入来源：**位置参数 <url>、--urls 或 --input-file。组合使用会报错：only one input source。

多个 URL 会通过一次 API 调用，将数组作为请求体发送到 /dca/trigger。这是 Scraper Studio Node 和 Python 参考项目（triggerWithUrls / trigger_with_urls）中的标准模式。只需一个快照、一次轮询循环和一个合并后的结果数组。不要手动编写 for url in $(cat urls.txt); do bdata scraper run ... 循环——这会产生 N 次 API 调用，而本应只需一次。

选择运行模式

                ┌─────────────────────────────────────────────────┐
                │ Expected to finish in ≤ ~50 seconds?            │
                └─────────────────────────────────────────────────┘
                 yes                                       no
                  │                                         │
                  ▼                                         ▼
       ┌──────────────────────┐                ┌────────────────────────┐
       │   --sync             │                │  default (no flag)     │
       │   /dca/crawl         │                │  trigger_immediate +   │
       │   one-shot, 25–50 s  │                │  poll get_result       │
       └──────────────────────┘                └────────────────────────┘
                  │
                  │  on 202 timeout: response_id is printed —
                  │  re-run WITHOUT --sync to poll for it
                  ▼
            (cleanly fall back to async)

模式	端点	适用场景
默认（单个 URL，异步 + 轮询）	/dca/trigger_immediate → 轮询 /dca/get_result	预计耗时超过约 50 s 的任务、任何分页任务，以及不确定耗时的任务。对于单个 URL，这是安全的默认选项。
--sync（单个 URL）	/dca/crawl	预计能在 50 s 内完成的单页提取。路径更快：只需一次请求，无需轮询。与多个 URL 不兼容——/dca/crawl 只接受一个 URL。
多个 URL（--urls / --input-file）	/dca/trigger（数组请求体）→ 轮询 /dca/dataset	通过同一个 collector 处理 2 个或更多 URL。一次 API 调用、一个快照 ID、一个合并后的结果数组。批次较大时，请使用更长的 --timeout（默认 3600s）。

# Default — async + poll (recommended for most cases)
bdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW

# Pretty-printed, saved to disk
bdata scraper run c_mp3tuab31lswoxvpws https://www.amazon.com/dp/B08N5WRWNW \
    --pretty -o product.json

# Sync mode for a fast page
bdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 --sync

# Sync with a tighter server timeout
bdata scraper run c_mp3tuab31lswoxvpws https://example.com/p/1 \
    --sync --sync-timeout 30

# Multi-URL via comma-separated list — one batch call
bdata scraper run c_mp3tuab31lswoxvpws \
    --urls "https://example.com/p/1,https://example.com/p/2,https://example.com/p/3" \
    --pretty -o products.json

# Multi-URL via file (one URL per line; # comments and blanks ignored)
bdata scraper run c_mp3tuab31lswoxvpws --input-file urls.txt -o products.json

# Multi-URL via JSON array
echo '["https://example.com/p/1","https://example.com/p/2"]' > urls.json
bdata scraper run c_mp3tuab31lswoxvpws --input-file urls.json

--sync-timeout 的取值范围为 25–50

超出此范围会退出并显示 --sync-timeout must be between 25 and 50 seconds。默认值为 50。仅当你希望快速失败并在慢速页面上回退到异步模式时，才使用小于 50 的值。

--sync 超时后的恢复

如果 /dca/crawl 在服务器端超时，会返回 202，并附带 {"error":"crawl_results_timeout","response_id":"r_late_..."}。CLI 会显示 response_id，并以“Re-run without --sync”消息退出。请照此操作——移除 --sync，重新运行相同的命令；默认的异步路径会针对现有的 response_id 轮询 /dca/get_result。不要将同步超时视为彻底失败。

自动静默回退到批处理（分页页面 / 大型页面）

当单个 URL 展开的页面数量超过实时任务限制时（例如分页列表、无限滚动、“所有评价”页面等），实时端点会返回类似以下错误：

Request generated 501 pages and exceeded realtime job limit of 51 pages

CLI 会检测到此情况，并自动回退到批处理流程（/dca/trigger → 轮询 /dca/dataset）。CLI 会打印一行提示。无需设置任何标志。批处理任务使用更长的轮询间隔（10 s）和更长的默认超时时间（1 小时）。

如果用户只看到提示并需要等待很久，这是正常的——大型任务需要时间。不要通过切换 API 或重构爬虫来“修复”回退；让任务继续运行。

--name 和 --version

• --name <name> — 在 Bright Data 控制面板中为此次运行添加标签。适合在脚本中运行多次并希望日后找到某次运行的场景。
• --version <version> — 固定使用特定版本的抓取器（在 Web 界面中迭代时通常使用 dev）。省略则使用最新发布的版本。

---

操作 3 — scraper heal

当现有抓取器运行后返回了错误、空白或部分数据时，可原地修复它。抓取器的 collector_id 保持不变——它会得到改进，而不是被替换。

bdata scraper heal <collector_id> "<what's wrong>" [--url <verify-url>] \
    [--timeout <seconds>] [--max-retries <n>] [--no-retry] \
    [--json | --pretty] [-o <path>] [--timing] [-k <api-key>]

你负责判断。 CLI 不会自行判断抓取器是否损坏——你需要检查运行输出并作出判断。修复耗时较长且会产生费用，因此只有在数据确实有误时才修复，而不是在数据确实为空时修复。

<prompt> 为必填项，也是最重要的输入。请准确指出错误之处以及正确的输出应是什么：“价格字段返回 null——选择器已移到 <span data-testid=...> 中。请重新抓取价格和货币。”模糊的提示词（例如“修一下”）会导致修复结果也很模糊。提示词最多 1000 个字符。

底层工作原理

1. 使用 {prompt, custom_input: []} 调用 POST /dca/collectors/{collector_id}/refactor_template——触发 AI 自我修复任务。
2. 轮询 GET .../refactor_template/progress——等待 status: "done"，任务结构和耗时与 automate_template 相同。

输出与验证循环

不带 --auto-approve 的 heal 通常会停在审批关卡，而不是立即完成。响应中会包含 status: "awaiting_approval" 和以下两个关键字段：

• preview_result — 修复后的抓取器将生成的样例行，供你在提交前判断修复是否正确。
• diff_summary — 模板变更内容的摘要。
• next_step — 指向 bdata scraper approve <collector_id> 以提交修复（或使用 --reject 将其丢弃）。

{
  "collector_id": "c_mp3tuab31lswoxvpws",
  "status": "awaiting_approval",
  "preview_result": [{"price": "29.99", "currency": "USD"}],
  "diff_summary": "Updated price selector from .price to span[data-testid='price']",
  "next_step": "bdata scraper approve c_mp3tuab31lswoxvpws"
}

检查 preview_result，然后运行 bdata scraper approve <collector_id> 以提交修复；或者传入 --reject 将其丢弃，并使用更明确的提示词重新修复。approve 会轮询至 done，并返回用于验证的 next_step = bdata scraper run <id> <url>。

向 heal 传入 --url <verify-url>，即可明确指定审批和运行步骤的目标地址。 现在完整的自我修复循环如下：

run → inspect → heal → review preview → approve → run → verify

若要完全跳过审批关卡，请使用 heal --auto-approve——它会自动审批并持续轮询，直到状态变为 done。

失败不会造成破坏

如果修复失败（429 限额耗尽、超时、最终状态为 failed），现有抓取器不会改变，仍能像之前一样正常工作。CLI 会说明这一点并打印 collector_id。与 create 失败不同，不会留下未完成的半成品。

---

操作 4 — scraper approve

不带 --auto-approve 的 scraper heal 会停在审批关卡： status: "awaiting_approval"，并附带 preview_result（修复后的抓取器将生成的样例行）和 diff_summary。检查预览，然后提交修复：

bdata scraper approve <collector_id> [--reject] [--url <verify-url>] \
    [--timeout <seconds>] [--json | --pretty] [-o <path>] [-k <api-key>]

• 默认批准（发送 POST /dca/collectors/{id}/resume_automation_job {"message": true}），然后轮询至 done，并返回用于验证的 next_step = bdata scraper run <id> <url>。
• --reject 会发送 {"message": false} 以丢弃拟议的修复；使用更明确的提示词重新修复，然后重试。
• 如果修复需要多次审批，approve 可能会再次停在 awaiting_approval；只需再次运行即可。

awaiting_approval 并不表示失败——它表示修复已就绪，正在等待你的决定。

---

完整的创建后运行工作流

使用 jq 干净地提取 collector_id，然后通过多 URL 批量路径接着运行：

# 1. Create the scraper, save the AI output, extract the collector_id
bdata scraper create https://example.com/product/1 \
    "Extract title, price, currency, image URL, and availability" \
    --pretty -o create.json

# 2. Pull the collector_id (or copy from the human-readable summary)
COLLECTOR_ID=$(jq -r '.collector_id // .id' create.json)
echo "Built: $COLLECTOR_ID"

# 3. Run it on every URL in one batch — single API call, merged result array
bdata scraper run "$COLLECTOR_ID" --input-file urls.txt \
    --pretty -o out/results.json

不要将 bdata scraper run 包装在 for url in $(cat urls.txt); do ... done 循环中——那会产生 N 次 API 调用和 N 个快照。请改用 --input-file urls.txt（或 --urls "..."）；CLI 会在单个数组请求体中将所有 URL POST 到 /dca/trigger，并返回一个合并后的结果数组。

更多端到端操作方法（批量输入文件格式、错误恢复、交接到 Web UI），请参阅 references/recipes.md。

---

常见错误

1. 臆造命令名称。 命令确切地是 bdata scraper create 和 bdata scraper run。没有 bdata generate、bdata scrape-batch、bdata data 或 bdata build。如果你想使用其中某个命令，那就是在产生幻觉——运行 bdata scraper --help 进行确认。

2. 超时后重新运行 create。 每次生成都会创建一个全新的 collector。如果轮询超时，半成品 collector 仍会显示在错误输出中。在 Web UI 中继续操作，或等待后重新轮询——不要再浪费一个 collector。

3. 所有情况都默认使用 --sync。 服务端的同步模式上限为 50 s。任何分页页面或大型 SPA 都会超时。默认使用异步模式才是正确选择，除非你明确知道页面很小。

4. 对已知平台跳过 Scraper Studio。 如果目标是 Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit 等平台，data-feeds 技能提供了预构建的 scraper，它们更快、更便宜也更可靠。只有在该网站没有预构建 scraper，或用户明确需要自定义输出格式时，才构建自定义 scraper。

5. 将同步超时视为失败。 --sync 的 202 超时会返回有效的 response_id——任务仍在后端运行。重新运行同一命令，但不加 --sync，即可继续处理。

6. 出错时丢弃 collector_id / response_id。 CLI 会特意在每种失败情况下打印它们。两者都可以通过 API 和 Web UI 恢复。务必将它们提供给用户。

7. 试图禁用批量自动回退。 没有相应的标志。当 URL 展开后超过实时页面限制时，回退是正确的处理方式。让它继续运行。

8. 手动编写 for url in $(cat urls.txt); do bdata scraper run ... 循环。 对于 API 原生视为单个批次的操作，这会产生 N 次 API 调用、N 个快照 ID 和 N 轮轮询。请使用 --input-file urls.txt 或 --urls "u1,u2,..."——CLI 会在单个请求中将整个数组 POST 到 /dca/trigger，并返回一个合并后的结果数组。这与 Scraper Studio 参考 SDK 中的标准 triggerWithUrls / trigger_with_urls 辅助函数一致。

9. 在 create 中使用含糊的描述。 像“抓取此页面”这样的描述只会生成通用 scraper。请逐一列出字段，注明条件（“如果有促销价，请同时抓取两种价格”），并说明区分方式（“标题附近的价格，而不是推荐侧栏中的价格”）。请参阅 references/prompts.md。

10. 重新运行 create 来修复损坏的 scraper。 这会构建一个新的 collector，并使旧 collector 失去后续用途。要修复现有 scraper，请使用 bdata scraper heal <collector_id> "<what's wrong>"——它会原地修改 scraper，因此你保存的 collector_id 仍可使用，并且效果会有所改善。

11. 将 awaiting_approval 视为失败。 这是 heal 的正常最终状态——修复方案已计算完成，正在等待你的决定。检查 preview_result，然后运行 bdata scraper approve <id>（或使用 --reject）。使用 heal --auto-approve 可跳过审核环节。

---

故障排除

症状	原因	修复方法
bdata: command not found	未安装 CLI	查看 brightdata-cli 了解安装方法。
Invalid or expired API key	尚未登录	运行 bdata login（SSH 环境下运行 bdata login --device）。
create 未返回 id	API 调用在模板创建前失败	检查 --timing 输出，找出失败的请求；验证网络和账号状态。
Timeout after 600 seconds waiting for AI generation	页面较复杂；已超出默认轮询时限	仍会打印 collector_id。在 Web 界面中打开它；或使用 --timeout 1200 重新运行。
进度轮询返回 status: "failed"	AI Flow 无法构建模板	改进描述，具体说明字段和选择器。使用更合适的网址（例如规范的商品页面，而非搜索结果）重试。
--sync 返回 202 和 crawl_results_timeout	页面耗时超过同步服务的上限	不使用 --sync 重新运行，并根据打印的 response_id 轮询 /dca/get_result。
--sync-timeout must be between 25 and 50 seconds	值超出范围	使用 [25, 50] 范围内的值。
Request generated N pages and exceeded realtime job limit	URL 展开过多	此问题会自动处理——等待批处理回退通知，并让它继续轮询。
未返回数据，只返回 [] 或 {}	选择器未匹配	抓取器模板已运行，但未提取到任何内容。打开 https://brightdata.com/cp/scrapers/{collector_id} 检查或编辑；也可以用更精确的描述重新构建。

---

参考文件

• references/prompts.md — 如何编写 scraper create 的描述，让 AI Flow 能够据此执行。包含优质与欠佳描述的示例、字段列举模式以及条件规则。
• references/recipes.md — 端到端操作示例：从 create 中获取 collector_id、批量运行一组 URL、处理同步→异步回退、从失败的 create 中恢复，以及从控制面板列出抓取器。
• references/api-flow.md — CLI 使用的确切 REST 端点、负载和状态标记（/dca/collector、/dca/collectors/{id}/automate_template、/dca/trigger_immediate、/dca/get_result、/dca/crawl、/dca/trigger、/dca/dataset）。调试意外的 CLI 输出或用户希望直接调用 API 时，请阅读此文件。