scrape

Bright Data — 抓取

通过 Bright Data CLI 从一个或多个 URL 获取干净的内容（markdown、HTML、JSON、截图）。此技能负责“获取原始或经过轻度结构化的内容”。对于特定平台的结构化数据（Amazon、LinkedIn、TikTok 等），请停止并改用 data-feeds——这样你就能获得干净的 JSON，无需编写选择器逻辑。

设置检查（先运行）

开始任何抓取前，请确认 CLI 已安装并完成身份验证：

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

如果任一检查失败，请停止操作，并引导用户查看 skills/bright-data-best-practices/references/cli-setup.md。不要擅自尝试旧版 curl 备用方案——应先询问用户。

选择路径

情况	操作
单个 URL	bdata scrape <url> -f markdown
较短列表（≤ 约 20 个 URL）	使用 shell 循环，每次处理 1 个（参见 references/patterns.md）
较长列表（数十个以上）	使用 xargs -P 4 并限制并行度（参见 references/patterns.md）
分页列表	抓取第 1 页 → 提取下一页 URL → 追加 → 重复（参见 references/examples.md）
JS 密集型／需要登录／需要交互	升级到 bdata browser（参见 brightdata-cli 技能）
Amazon、LinkedIn、TikTok、Instagram、YouTube、Reddit 等	停止——转交给 data-feeds
还没有 URL，只有主题	转交给 search

操作

核心命令：

# Clean markdown (default)
bdata scrape "https://example.com/article" -f markdown -o article.md

# Raw HTML (when you need the DOM)
bdata scrape "https://example.com" -f html -o page.html

# Structured JSON (when the Unlocker returns parsed fields)
bdata scrape "https://example.com" -f json --pretty -o page.json

# Visual snapshot (saves PNG)
bdata scrape "https://example.com" -f screenshot -o page.png

# Geo-targeted (override the exit country)
bdata scrape "https://example.com" --country de -f markdown

完整的标志参考： references/flags.md。

验证检查（声明成功前运行）

1. **输出非空：**运行 test -s "$out_path"；若输出到 stdout，则内容至少应有 200 字节。
2. 不是拦截页面——使用 grep 检查输出中是否包含以下任一特征（不区分大小写）：
   • Access Denied
   • Just a moment
   • Attention Required
   • Checking your browser
   • captcha
   • cf-browser-verification
   • cloudflare （正文总计小于 2KB）
3. 包含预期标记：根据任务检查，例如，商品页面应包含价格格式（\$\d）；文章应至少包含一个 <h1> 或 # 标题。
4. 失败时的升级步骤：
   • 使用其他 --country 重试（例如，来源网站位于美国时使用 --country de）
   • 升级到 bdata browser，进行完整的 JS 渲染（转交给 brightdata-cli 技能）

通过以上所有检查后，才能报告成功。

危险信号

• 未检查输出就声称成功。
• 使用 2>/dev/null 隐藏错误——这样会漏掉身份验证失败和速率限制错误。
• 对 Amazon／LinkedIn／TikTok／Instagram／YouTube／Reddit URL 运行 bdata scrape——data-feeds 支持这些平台，并会直接返回结构化数据。抓取会丢失结构。
• 在同一任务中重复抓取同一个 URL——缓存首次结果。
• 对较长列表依次运行 bdata scrape，而不使用 xargs -P 4（或类似方式）限制并行度。
• 直接对 api.brightdata.com 使用 curl——这是旧版方式；仅在 CLI 不可用时使用。

参考资料

• references/flags.md — 每个标志及其使用说明。
• references/patterns.md — shell 循环批处理、xargs 并行处理、分页流程、重试／退避、拦截页面恢复流程、旧版 curl 备用方案。
• references/examples.md — (1) 单页 → markdown；(2) 对 URL 列表进行批处理并限制并行度；(3) 分页列表；(4) 拦截页面恢复。