automating-the-browser

用途

Automating the browser 是 crawlberg 提供的一项浏览器自动化能力，用于在抓取页面之前先执行脚本化交互。当静态抓取不足以获取内容时使用它：内容位于“加载更多”按钮之后、无限滚动之后、表单提交之后，或依赖仅在交互时才运行的 JavaScript。

它通过 crawlberg interact <url> --actions '[...]' 驱动一个真实的无头浏览器，按有序的动作列表执行，然后捕获最终页面。

主要能力

按顺序执行动作列表，动作类型包括：click、type、press、scroll、wait、screenshot、executeJs、scrape。
支持在动作执行后捕获最终页面 HTML（scrape）。
支持视口截图或整页截图（screenshot，fullPage 可选）。
支持在页面上下文中执行任意 JS（executeJs，仅限可信脚本）。
支持等待固定毫秒数，或等待某个选择器出现（selector 优先）。
支持滚动页面或指定可滚动元素，方向仅 up / down。
支持连接外部 CDP 端点（ws:// 或 wss://）。

使用方式

基本命令：

crawlberg interact https://example.com \
  --actions '[{"type":"click","selector":"#load-more"},
              {"type":"wait","milliseconds":500},
              {"type":"scrape"}]'

动作按顺序执行，结果将最终页面状态包裹在 interaction 键下。

标志（Flag）

Flag	默认值	用途
--actions	—	必填。动作对象的 JSON 数组。
--format	json	json（完整结果）或 markdown（仅最终 HTML）。
--timeout	30000	每次请求超时，单位毫秒。
--browser-mode	auto	auto、always、never。交互需要浏览器。
--browser-endpoint	—	外部 CDP ws:// 或 wss:// URL。
--config	—	内联 JSON 或 @file.json，用于完整 CrawlConfig。

注意：interact 没有 --respect-robots-txt 标志，它只针对你指定的那一个 URL。

动作 schema

每个动作是一个由 type 标记的 JSON 对象（camelCase）。未知字段会被拒绝，因此需严格匹配以下结构：

type	字段	说明
click	selector	点击匹配 CSS 选择器的元素。
type	selector, text	向匹配 selector 的输入框输入文本。
press	key	按键，例如 "Enter"、"Tab"、"Escape"。
scroll	direction ("up"/"down"), selector?, amount?	滚动页面；若设置 selector 则滚动该可滚动元素。
wait	milliseconds?, selector?	等待固定时间，或等待 selector 出现（selector 优先）。
screenshot	fullPage?	捕获视口；若为 true 则捕获整个可滚动页面。
executeJs	script	在页面上下文中运行任意 JS。仅限可信脚本。
scrape	—	将当前页面 HTML 捕获到结果中。

注意：没有 select 动作，也没有 wait_for_selector 动作；要等待元素，请使用带 selector 字段的 wait。滚动方向仅 up 或 down。

限制（强制执行，超出即报错）

每次调用最多 100 个动作。
单次 wait 最长 300000 毫秒；所有 wait 动作的总等待时间最长 300 秒。
selector 最大 4096 字节；text 与 executeJs 脚本各最大 1 MB。
scroll amount 最大 100000 像素（绝对值）。

输出

JSON 模式（默认）

结果包裹在 interaction 键下，包含最终页面 HTML（interaction.final_html）以及每个动作的记录 interaction.action_results[...]，其中在适用时包含截图数据和 executeJs 返回值。

crawlberg interact https://example.com \
  --actions '[{"type":"type","selector":"#q","text":"rust"},
              {"type":"press","key":"Enter"},
              {"type":"wait","selector":".results"},
              {"type":"scrape"}]' \
  --format json | jq '.interaction.final_html | length'

Markdown 模式

直接打印 interaction.final_html——即原始最终 DOM，而非转换后的 Markdown。当你需要干净的 Markdown 时，请使用 JSON 模式并将 final_html 交给 scrape 步骤处理。

适用场景

展开懒加载内容后再捕获：

crawlberg interact https://example.com/feed \
  --actions '[{"type":"scroll","direction":"down"},
              {"type":"wait","milliseconds":800},
              {"type":"scroll","direction":"down"},
              {"type":"wait","milliseconds":800},
              {"type":"scrape"}]'

登录后捕获整页截图：

crawlberg interact https://app.example.com \
  --actions '[{"type":"type","selector":"#email","text":"me@example.com"},
              {"type":"type","selector":"#password","text":"..."},
              {"type":"click","selector":"button[type=submit]"},
              {"type":"wait","selector":".dashboard"},
              {"type":"screenshot","fullPage":true}]'

切勿硬编码凭据——请从环境变量或密钥存储中传入。

指向外部 Chrome：

crawlberg interact https://example.com \
  --browser-endpoint ws://browser.internal:9222/devtools/browser/<id> \
  --actions '[{"type":"click","selector":"#go"},{"type":"scrape"}]'

关于 CDP 端点、等待策略以及通过 --config 设置的持久浏览器配置文件，请参见 headless-fallback 技能。

何时改用 scrape 或 crawl

如果页面在普通抓取（或通过 --browser-mode always）下无需点击或输入即可产出内容，请使用 crawlberg scrape——参见 scraping-html-to-markdown。仅当内容存在之前必须先运行有序动作时，才使用 interact。