浏览器自动化

使用 @eN ref 驱动 Chromium — 导航、点击、填写、标签页、网络、登录、验证码。

omniscout browser 通过 Patchright 驱动本地 Chromium。核心循环永远不变：

omniscout browser navigate https://example.com   # 1. open a page
omniscout browser snapshot --refs-only           # 2. list @eN element refs
omniscout browser click '@e3'                    # 3. act on a ref
omniscout browser screenshot --out /tmp/out.png  # 4. capture state

`@eN` ref 模型

snapshot 返回页面的无障碍树，元素带有稳定的 ref（@e1、@e2……）。所有交互都针对 ref — 不用 CSS 选择器，也不猜像素坐标。两条规则：

每次导航或 DOM 大变后重新 snapshot — 页面变化后 ref 会失效。
优先用 --refs-only 获取扁平可操作列表；需要层级结构时去掉该参数获取完整树。

omniscout browser snapshot --refs-only
omniscout browser snapshot --overlay   # draw @e labels on the page (debugging/demos)

导航与历史

omniscout browser navigate https://example.com --wait-until domcontentloaded
omniscout browser open https://example.com      # alias of navigate
omniscout browser back
omniscout browser forward
omniscout browser reload
omniscout browser get url                       # current URL
omniscout browser get title                     # page title

navigate 支持 --profile（持久登录上下文）、--session（标签页组）、--new-tab、--headful/--headless、--auto-captcha 与 --wait-until。profile 与 session 的区别见 Daemon 与会话。

点击、输入、选择

操作	命令	说明
点击	`browser click '@e3'`	vision agent 可用 `--button`、`--clicks`、`--mod` 或 `--coord x y`
填写（替换）	`browser fill '@e5' "text"`	替换已有内容
输入（追加）	`browser type '@e5' "text"`	追加；按键间隔用 `--delay-ms`
粘贴	`browser paste '@e5' "text"`	在光标处插入不清屏
选择	`browser select '@e5' "option"`	原生 `<select>` 元素
按键	`browser key Enter`	`cmd+s`、`ctrl+c` 等组合键
悬停	`browser hover '@e7'`	或 `--coord x y`
上传	`browser upload '@e9' file.pdf`	为 `<input type=file>` 附加文件
滚动	`browser scroll down`	页面或元素，配合 `--amount`
检查状态	`browser is '@e3' visible`	可见性、可用、勾选等

fill、type、paste 的区别：fill 先清空（表单），type 像真人一样追加（聊天、编辑器），paste 在光标处直接粘贴大段文本。

读取页面

omniscout browser get text              # visible body text
omniscout browser get html              # page HTML (truncated ~500KB)
omniscout browser eval "document.title" # run JavaScript, return the value
omniscout browser extract-visible       # visible text, optional --schema shaping

等待

不要盲目 sleep — 等待你真正需要的条件：

omniscout browser wait text "Order confirmed"
omniscout browser wait selector "#results"
omniscout browser wait networkidle
omniscout browser wait url "*checkout*"
omniscout browser wait --ms 2000 --timeout-ms 30000

wait 还支持 --ref、--url（对当前 URL 的正则）、--idle 与 --mutation-quiet-ms（等待 DOM 停止变化）。

标签页

omniscout browser navigate https://a.com --session multi
omniscout browser navigate https://b.com --new-tab --session multi
omniscout browser tab list --session multi
omniscout browser tab switch 0 --session multi
omniscout browser tab close 1 --session multi

网络与控制台捕获

omniscout browser network start
omniscout browser navigate https://vercel.com/pricing
omniscout browser scroll down --amount 10
omniscout browser network stop
omniscout browser network list --filter "stripe|payment"
omniscout browser network detail 3          # full payload for one entry
omniscout browser network tail              # only entries since last tail

omniscout browser console start
omniscout browser console tail              # JS errors and console messages
omniscout browser console list
omniscout browser console stop

自然语言操作

对模糊目标，让 daemon 来解析：

omniscout browser observe "the search box"        # find candidate refs
omniscout browser act "click the top story"       # resolve + act
omniscout browser act "search box" --value "local-first agents"
omniscout browser act "submit" --dry-run          # resolve without acting

事后用 snapshot 验证 — act 方便，但 ref 是确定性的。

截图、PDF、鼠标

omniscout browser screenshot --out /tmp/page.png
omniscout browser screenshot --full-page --out /tmp/full.png   # top-to-bottom
omniscout browser screenshot --ref '@e3' --out /tmp/el.png     # one element
omniscout browser screenshot --delay 2.5 --out /tmp/late.png  # wait for animations
omniscout browser pdf --out /tmp/page.pdf --paper letter
omniscout browser mouse move 400 300
omniscout browser mouse scroll 400 300

登录与验证码

某些站点需要人工登录一次。打开有界面窗口完成认证，再从另一个 shell 发完成信号 — profile 会保留 cookie 供复用：

# Terminal A (blocks):
omniscout browser login https://github.com/login --profile work

# Terminal B (after you log in):
omniscout browser login --done

# Reuse later:
omniscout browser navigate https://github.com/notifications --profile work

--success-pattern（URL 正则）可自动判定登录完成；--timeout-ms 默认 5 分钟。验证码：

omniscout browser captcha --detect-only                    # just report
omniscout browser captcha --solver 2captcha                # none | 2captcha | capsolver | manual
export CAPTCHA_API_KEY=...                                 # or --api-key

navigate 也支持 --auto-captcha，在加载后直接处理验证挑战。

清理

omniscout browser close                # close the default session
omniscout browser close --all          # close everything

Agent 技巧

操作前务必 snapshot；绝不在导航间复用 ref。
每次运行结束执行 browser close --all，让下一次运行从干净状态开始。
用 --session 隔离共享同一 daemon 的并行工作流。
在 --json 下用 jq 处理 snapshot：omniscout browser snapshot | jq '.refs[] | select(.role == "button")'。

浏览器自动化

On this page