openloaf 浏览器操作指南
工具清单
| 工具 | 职责 | 只读 |
|---|---|---|
OpenUrl |
打开网页（headless / tab / window 三模式） | 是 |
BrowserSnapshot |
一次拿到页面文本 + 交互元素列表 + 截图 + rawHtml | 是 |
BrowserAct |
页面交互（点击 / 输入 / 滚动 / 按键） | 否 |
BrowserWait |
等待页面状态（load / networkidle / url / text / timeout） | 是 |
BrowserDownloadImage |
下载页面中的图片到本地 | 否 |
加载：全部为 deferred 工具，调用前须先
ToolSearch(names: "OpenUrl,BrowserSnapshot,BrowserAct,BrowserWait,BrowserDownloadImage")激活 schema。
核心心智模型
浏览器操作 = 观察-行动-验证 循环。每次操作后必须 snapshot 确认状态，因为网页是有状态的——点击可能触发导航、弹窗、AJAX 加载，你无法预测结果。盲目连续操作是最常见的失败原因。
OpenUrl → BrowserSnapshot → 分析 → BrowserAct → BrowserWait → BrowserSnapshot → ...
OpenUrl 打开模式
headless— 纯自动化首选。无 UI，适合抓取、后台 Agent、批量操作。tab（默认） — 用户需要看到/操作页面时用。内嵌面板。window— 用户需要独立窗口深度交互时用。
速记：用户不需要看 → headless；用户要看 → tab；用户要独立窗口 → window。
BrowserSnapshot 说明
BrowserSnapshot 一次调用返回：
- 页面信息：URL、标题、readyState
- 全量文本：body.innerText（截断 32KB）
- 交互元素列表：最多 120 个可点击/可输入元素及其 selector
- iframe 内容：同源 iframe 的文本和元素
- 截图：默认截取完整页面（fullPage），保存到会话资源目录
- rawHtmlPath：完整 outerHTML 存盘路径
文本超 32KB 怎么办？ 用 Read/Grep 读 rawHtmlPath 获取完整 DOM，不要反复调 BrowserSnapshot 重抓。
截图控制：fullPage: false 仅截取当前可视区域。
三大核心工作流
工作流 1：信息提取
OpenUrl → BrowserWait { type: "load" } → BrowserSnapshot
直接从返回的文本中提取所需信息。
翻页抓取：BrowserSnapshot → BrowserAct { action: "click-text", text: "下一页" } → BrowserWait { type: "networkidle" } → 循环。每页都要 snapshot。
工作流 2：表单填写与登录
OpenUrl→BrowserSnapshot看表单结构和 selector- 对每个字段
BrowserAct { action: "fill", selector: "...", text: "..." } - 提交：
BrowserAct { action: "click-css", selector: "button[type=submit]" } BrowserWait { type: "urlIncludes", url: "/success" }确认成功BrowserSnapshot最终确认
fill vs type：fill 原子性地清空+输入，适合表单；type 在当前焦点追加字符，适合搜索框。
登录注意：Cookie 在会话期间持久，登录一次后续自动带认证。不要 snapshot 密码字段。
工作流 3：截图与图片下载
BrowserSnapshot— 快照 + 完整页面截图（默认 fullPage）BrowserSnapshot { fullPage: false }— 仅可视区域BrowserDownloadImage { selector: ".product-image" }— 下载页面中的图片
截图是调试利器：文本看不出问题时，看截图一目了然。
Selector 选择策略
从 BrowserSnapshot 返回的元素列表中选择 selector，不要自己猜。
优先级：#id > [data-testid] > input[name] > .class > click-text
等待策略
load：传统页面导航后用networkidle：SPA/AJAX 页面首选，最安全但最慢urlIncludes：表单提交后等待跳转textIncludes：等待异步加载的内容timeout：最后手段
错误诊断
元素未找到？ → BrowserSnapshot 确认页面状态 → 可能已导航到别处 → 可能在视口下方（scroll 后再试）→ 可能在 iframe 中（不支持跨 iframe）
页面加载超时？ → BrowserSnapshot 看加载到哪了，可能内容已够用
操作没反应？ → 页面没加载完（加 BrowserWait）→ selector 匹配了错误元素（snapshot 检查）→ 弹窗遮挡（先关闭）
SPA 内容为空？ → BrowserWait { type: "networkidle" } 后再 snapshot → 还是空则 textIncludes 等具体内容
CAPTCHA 与反爬
遇到验证码、403/429、反机器人页面时立即停止并告知用户，不要盲目重试。
铁律
- 每次操作后 BrowserSnapshot 验证状态
- 先 snapshot 再行动，不要猜 selector
- 等待页面就绪后再操作
- 文本不够看截图
- 不要暴露敏感信息（密码填写后不要 snapshot）
- 遇到反爬立即停止