agent-browser 提供三类等待机制:一是 wait --load 等待页面加载阶段(domcontentloaded 或 load),支持超时;二是 wait 选择器 等待元素可见/隐藏;三是 wait --url 等待 URL 匹配通配模式。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

在用 agent-browser 自动化网页操作时,如果页面还没加载完就执行 click 或 snapshot,命令会失败或读到空白内容。
等待页面加载完成
agent-browser 提供了原生的加载等待机制,不依赖 DOM 元素是否存在,而是监听浏览器原生的加载事件。
第一步:运行 wait --load 命令,指定你期望的加载阶段:
agent-browser wait --load domcontentloaded
这会让 CLI 阻塞,直到 document.readyState 变为 【domcontentloaded】,即 HTML 解析完成、DOM 构建完毕,但图片、样式表等外部资源可能还在加载。这是大多数交互操作(如点击按钮、读取表单)的安全起点。
第二步:若需确保所有资源(含图片、字体、JS)全部就绪,改用:
agent-browser wait --load load
该状态对应 window.onload 事件触发时机,适合截图、PDF 生成、或依赖完整渲染布局的操作。注意:某些 SPA 页面可能不会触发 onload,此时应优先选 domcontentloaded。
第三步:可选——为防页面卡死,显式设置超时时间:
agent-browser wait --load domcontentloaded --timeout 15000
默认超时是 25 秒(25000 毫秒),这里缩至 15 秒。超时后命令直接报错退出,不会无限挂起。
等某个元素出现后再操作
当页面结构已知、且目标元素是关键就绪信号时,用选择器等待更精准。
方法一:等待元素可见并可交互
agent-browser wait "#submit-btn"
这条命令会等待 CSS 选择器命中的元素出现在 DOM 中,并满足 visible + attached 条件。它比单纯检查是否存在更可靠,能避开 skeleton 加载占位符。
方法二:等待元素从页面上消失(例如关闭弹窗后继续)
agent-browser wait "#consent-banner" --state hidden
【--state 只能和选择器搭配使用,不能用于 --text 或 --url 等其他模式】。这个组合常用于处理 cookie 横幅、登录模态框等遮挡层,确保它们不再覆盖目标按钮。
等 URL 变成预期地址
适用于跳转后校验是否到达正确页面,比如登录成功跳转到 /dashboard,或表单提交后重定向。
运行:
agent-browser wait --url "**/dashboard"
支持通配符 ** 匹配任意前缀,避免因协议(http/https)、端口或查询参数差异导致匹配失败。URL 匹配是字符串子串匹配,不校验 hash 或 fragment 部分。


















