name: agent-browser description: 用于AI代理的浏览器自动化CLI。当用户需要与网站交互时使用，包括导航页面、填写表单、点击按钮、截图、提取数据、测试web应用或自动化任何浏览器任务。触发包括请求"打开网站"、“填写表单”、“点击按钮”、“截图”、“从页面抓取数据”、“测试此web应用”、“登录到网站”、“自动化浏览器操作”，或任何需要程序化网页交互的任务。 allowed-tools: Bash(agent-browser:*) metadata: internal: true

使用agent-browser进行浏览器自动化

核心工作流

每个浏览器自动化遵循此模式：

导航: agent-browser open <url>
快照: agent-browser snapshot -i (获取元素引用如 @e1, @e2)
交互: 使用引用来点击、填写、选择
重新快照: 导航或DOM变化后，获取新的引用

agent-browser open https://example.com/form
agent-browser snapshot -i
# 输出: @e1 [input type="email"], @e2 [input type="password"], @e3 [button] "提交"

agent-browser fill @e1 "user@example.com"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait --load networkidle
agent-browser snapshot -i  # 检查结果

基本命令

# 导航
agent-browser open <url>              # 导航 (别名: goto, navigate)
agent-browser close                   # 关闭浏览器

# 快照
agent-browser snapshot -i             # 交互元素带引用 (推荐)
agent-browser snapshot -s "#selector" # 限制到CSS选择器

# 交互 (使用快照中的@引用)
agent-browser click @e1               # 点击元素
agent-browser fill @e2 "text"         # 清除并输入文本
agent-browser type @e2 "text"         # 输入而不清除
agent-browser select @e1 "option"     # 选择下拉选项
agent-browser check @e1               # 选中复选框
agent-browser press Enter             # 按下键
agent-browser scroll down 500         # 滚动页面

# 获取信息
agent-browser get text @e1            # 获取元素文本
agent-browser get url                 # 获取当前URL
agent-browser get title               # 获取页面标题

# 等待
agent-browser wait @e1                # 等待元素
agent-browser wait --load networkidle # 等待网络空闲
agent-browser wait --url "**/page"    # 等待URL模式
agent-browser wait 2000               # 等待毫秒

# 捕获
agent-browser screenshot              # 截图到临时目录
agent-browser screenshot --full       # 全页截图
agent-browser pdf output.pdf          # 保存为PDF

常见模式

表单提交

agent-browser open https://example.com/signup
agent-browser snapshot -i
agent-browser fill @e1 "Jane Doe"
agent-browser fill @e2 "jane@example.com"
agent-browser select @e3 "California"
agent-browser check @e4
agent-browser click @e5
agent-browser wait --load networkidle

认证与状态持久化

# 登录一次并保存状态
agent-browser open https://app.example.com/login
agent-browser snapshot -i
agent-browser fill @e1 "$USERNAME"
agent-browser fill @e2 "$PASSWORD"
agent-browser click @e3
agent-browser wait --url "**/dashboard"
agent-browser state save auth.json

# 在将来会话中重用
agent-browser state load auth.json
agent-browser open https://app.example.com/dashboard

数据提取

agent-browser open https://example.com/products
agent-browser snapshot -i
agent-browser get text @e5           # 获取特定元素文本
agent-browser get text body > page.txt  # 获取所有页面文本

# JSON输出用于解析
agent-browser snapshot -i --json
agent-browser get text @e1 --json

并行会话

agent-browser --session site1 open https://site-a.com
agent-browser --session site2 open https://site-b.com

agent-browser --session site1 snapshot -i
agent-browser --session site2 snapshot -i

agent-browser session list

可视化浏览器（调试）

agent-browser --headed open https://example.com
agent-browser highlight @e1          # 高亮元素
agent-browser record start demo.webm # 录制会话

iOS模拟器（移动Safari）

# 列出可用的iOS模拟器
agent-browser device list

# 在特定设备上启动Safari
agent-browser -p ios --device "iPhone 16 Pro" open https://example.com

# 与桌面相同的工作流 - 快照、交互、重新快照
agent-browser -p ios snapshot -i
agent-browser -p ios tap @e1          # 点击（点击别名）
agent-browser -p ios fill @e2 "text"
agent-browser -p ios swipe up         # 移动特定手势

# 截图
agent-browser -p ios screenshot mobile.png

# 关闭会话（关闭模拟器）
agent-browser -p ios close

要求: macOS with Xcode, Appium (npm install -g appium && appium driver install xcuitest)

真实设备: 如果预配置，适用于物理iOS设备。使用 --device "<UDID>" 其中UDID来自 xcrun xctrace list devices。

引用生命周期（重要）

引用 (@e1, @e2, 等) 在页面变化时失效。始终在以下情况后重新快照：

点击导航的链接或按钮
表单提交
动态内容加载（下拉菜单、模态框）

agent-browser click @e5              # 导航到新页面
agent-browser snapshot -i            # 必须重新快照
agent-browser click @e1              # 使用新引用

语义定位器（引用替代）

当引用不可用或不可靠时，使用语义定位器：

agent-browser find text "登录" click
agent-browser find label "邮箱" fill "user@test.com"
agent-browser find role button click --name "提交"
agent-browser find placeholder "搜索" type "查询"
agent-browser find testid "submit-btn" click

深入文档

参考	何时使用
references/commands.md	完整命令参考，包含所有选项
references/snapshot-refs.md	引用生命周期、失效规则、故障排除
references/session-management.md	并行会话、状态持久化、并发抓取
references/authentication.md	登录流程、OAuth、2FA处理、状态重用
references/video-recording.md	录制工作流用于调试和文档
references/proxy-support.md	代理配置、地理测试、旋转代理

即用模板

模板	描述
templates/form-automation.sh	表单填写带验证
templates/authenticated-session.sh	登录一次，重用状态
templates/capture-workflow.sh	内容提取带截图

./templates/form-automation.sh https://example.com/form
./templates/authenticated-session.sh https://app.example.com/login
./templates/capture-workflow.sh https://example.com ./output