agent-browser

Agent Browser

当任务需要 直接操作网页（而不是只读 API 数据）时使用本技能。Agent Browser 基于标准的 CDP (Chrome DevTools Protocol) 协议，赋予 Agent 像人类一样浏览网页、填写表单、点击按钮以及处理复杂前端交互（如 React/Vue 渲染页面、弹窗、验证码预览）的能力。

安装

npx clawhub@latest install agent-browser

适用场景

• 打开网页并执行多步操作：登录后台管理系统、在多个页签间比对数据、提交复杂的业务表单。
• 用自然语言定位元素：无需编写复杂的 CSS Selector，直接通过“点击左上角的搜索框”或“找到包含‘加入购物车’字样的按钮”进行操作。
• 导出多媒体产出：将当前页面保存为高清截图、滚动截长图、PDF 文档，甚至录制一段操作视频。
• 执行页面内 JavaScript：直接在 Console 中注入自定义脚本，提取原本难以抓取的动态数据或模拟特定用户行为。
• 保存会话状态：支持 Cookie、LocalStorage 的持久化（retain 机制），实现跨会话的免登录访问。

使用建议

1. 先说明目标页面与预期结果：建立清晰的 Success Criteria。
2. 分阶段执行：将复杂操作拆成可验证的原子步骤（导航 → 定位 → 操作 → 校验）。
3. 涉及账号安全：优先使用隔离的浏览器 Profile，并开启最小权限模式。
4. 视觉优先：在关键操作前后进行 screenshot，既是留存证据，也方便 Agent 自我纠错。

触发条件 / When to Use

• API 缺失场景：当目标网站不提供公开 API，只能通过网页前端交互获取数据时。
• 图形化报表抓取：需要从复杂的仪表盘（Dashboard）中截取特定图表并分析。
• 自动化注册/登录流程：需要模拟用户完成一系列实人认证或偏好设置步骤。
• SEO 与前端性能测试：通过 console 读取页面报错、性能指标（LCP, FID）并进行诊断。
• 动态内容实时监控：如监控股市实时行情网页或秒杀活动的库存变动。

核心能力 / Core Capabilities

1. 语义化快照与定位 (Semantic Snapshot)

• 操作步骤：
  1. 调用 snapshot 获取辅助功能树（Accessibility Tree）。
  2. 结合 ax*（可访问性引用）和 n*（DOM 引用）理解页面层级。
  3. 通过 highlight 技能验证定位是否准确。
• 最佳实践：在复杂页面中，先进行 scroll 滚动到底部，确保懒加载（Lazy Loading）的内容完整呈现。

2. 精准动作模拟 (Action Emulation)

• 操作步骤：
  1. 调用 act 接口，执行 click, type, hover, drag 等动作。
  2. 设置 clearFirst: true 确保输入框内容干净。
  3. 对于关键步骤，开启 slowly: true 以模仿人类真实点击频率，降低被反爬引擎识别的风险。
• 最佳实践：在点击“提交”后，立即配合 wait 工具，直到特定 URL 或文字出现，确保操作已生效。

3. 会话留存与持久化 (Session Retention)

• 操作步骤：
  1. 使用 retain: true 标记重要的页签（Tab）。
  2. 被标记的页签在 Agent 会话结束后不会被自动关闭，方便后续二次访问。
• 最佳实践：在需要用户手动扫码登录时，开启 retain，等用户扫码完成后 Agent 再接管。

4. 异常捕获与诊断 (Errors & Requests)

• 操作步骤：
  1. 实时读取 errors 列表，识别 JS 执行崩溃。
  2. 监控 requests 网络请求，拦截并分析特定的 API 数据包（甚至包括 XHR/Fetch 的 Response）。

常用命令/模板 / Common Patterns

网页信息采集工作流模板 (Scraping Workflow)

### 任务目标
[目标描述：从 X 网站抓取前 10 个产品的价格和评论]

### 操作步骤 (Action Sequence)
1. **Navigate**: 访问 `https://example.com/products`。
2. **Wait**: 等待包含 `.product-list` 的元素加载完成。
3. **Scroll**: 滚动至页面底部触发分页。
4. **Snapshot**: 获取所有 `n` 级引用的文本内容。
5. **Console**: 注入脚本 `Array.from(document.querySelectorAll('.price')).map(e => e.innerText)`。
6. **Screenshot**: 截取整个列表区域存入 `output/products.png`。

### 预期结果
- 汇总 JSON 数据。
- 截图证据。