agent-browser 是一个面向 AI 智能体的浏览器自动化命令行工具（CLI），用于让智能体与网站进行交互，包括导航页面、填写表单、点击按钮、截图等操作。
核心工作流
每次浏览器自动化都遵循以下模式：
- 导航：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] "Submit"
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 # 检查结果
主要能力与常用命令
导航：open <url>（别名 goto、navigate）、close。 快照：snapshot -i（推荐，输出带引用的交互元素）、snapshot -i -C（包含光标交互元素，如带 onclick、cursor:pointer 的 div）、snapshot -s "#selector"（限定到 CSS 选择器范围）。 交互（使用快照中的 @refs）：click @e1、fill @e2 "text"（清空并输入）、type @e2 "text"（不清空输入）、select @e1 "option"、check @e1、press Enter、scroll down 500。 获取信息：get text @e1、get url、get title。 等待：wait @e1、wait --load networkidle、wait --url "**/page"、wait 2000（毫秒）。 捕获：screenshot（截图到临时目录）、screenshot --full（整页截图）、pdf output.pdf。
常见使用模式
表单提交：打开表单页，快照，填写字段，选择下拉项，勾选复选框，点击提交，等待网络空闲。 带状态持久化的认证：登录一次并保存状态（state save auth.json），后续会话加载状态复用（state load auth.json），支持登录流程、OAuth、2FA 处理和状态复用。 数据提取：打开页面，快照，用 get text 提取指定元素文本或整个页面文本（get text body > page.txt），可用 --json 输出以便解析。 并行会话：使用 --session 指定不同会话（如 site1、site2）同时操作多个站点，session list 查看会话列表。 可视化浏览器（调试）：--headed 使用有头模式，highlight @e1 高亮元素，record start demo.webm 录制会话。 本地文件：使用 file:// URL 打开本地 PDF、HTML（需 --allow-file-access），然后截图。 iOS 模拟器（移动 Safari）：device list 列出可用模拟器；-p ios --device "iPhone 16 Pro" 在指定设备启动 Safari；之后可用相同工作流进行快照、交互、重新快照，支持 tap（click 的别名）、swipe up 等移动手势，并截图；close 关闭会话（同时关闭模拟器）。要求：macOS 加 Xcode，以及 Appium（npm install -g appium && appium driver install xcuitest）。真实设备：若预先配置，可配合物理 iOS 设备使用，通过 --device "<UDID>" 指定，UDID 来自 xcrun xctrace list devices。
引用（Ref）生命周期
引用（@e1、@e2 等）在页面变化时会失效。在点击会导航的链接或按钮、提交表单、动态内容加载（下拉菜单、模态框）后，务必重新快照，再使用新的引用进行交互。
语义定位器（引用的替代方案）
当引用不可用或不可靠时，可使用语义定位器： find text "Sign In" click find label "Email" fill "user@test.com" find role button click --name "Submit" find placeholder "Search" type "query" 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（带截图的内容提取），可分别以 URL 或输出目录作为参数运行。