核心功能与用法
agent-browser 是一款基于 Playwright 引擎的浏览器自动化工具，提供完整的浏览器控制能力。核心工作流遵循"导航 → 快照 → 交互"模式：先通过 open 打开目标页面，使用 snapshot -i 获取带引用标识（如 @e1、@e2）的交互元素列表，再通过引用执行点击、填充、选择等操作。
主要功能模块包括：
1. 页面交互：点击、双击、悬停、拖拽、文件上传、滚动等完整鼠标键盘操作
2. 表单自动化：fill/type/fill 输入、checkbox 勾选、下拉选择、文件上传
3. 信息提取：文本、HTML、属性、样式、元素计数、页面标题/URL 等
4. 截图与录屏：全页/视口截图、PDF 导出、WebM 视频录制（支持断点续录）
5. 等待机制：元素可见、文本出现、URL 匹配、网络空闲、JS 条件等多维度等待
6. 网络控制：请求拦截、响应 Mock、请求记录与过滤
7. 状态管理：Cookie/LocalStorage 读写、登录态保存与恢复、多 Session 并行
8. 语义定位：role/text/label/placeholder/alt/title/testid 等自然语言定位（替代 XPath）
9. 设备模拟：视口设置、设备预设（如 iPhone 14）、地理位置、深色模式
显著优点
- 引用机制直观：
@e1等引用标识比 XPath/CSS 选择器更稳定，自动处理 DOM 变化后的重新定位 - 会话隔离完善：
--session支持多浏览器并行，适合并发爬虫和测试矩阵 - 状态持久化：
state save/load实现登录态复用，避免重复认证 - 调试工具齐全： headed 模式、CDP 连接、trace 录制、console/errors 查看、元素高亮
- 语义定位降低门槛：自然语言描述即可定位元素，减少选择器维护成本
潜在局限与风险
| 风险点 | 说明 |
|--------|------|
| 动态内容稳定性 | 现代 SPA（React/Vue）的异步渲染可能导致 snapshot 时元素尚未挂载，需配合 wait 命令 |
| 反爬检测 | 高频自动化易被 Cloudflare/WAF 识别，需配合代理轮换、请求延迟、指纹伪装 |
| 引用失效 | 页面导航或大幅 DOM 变更后，@refs 可能失效，必须重新 snapshot |
| 视频录制限制 | 录制会创建新上下文，虽保留 cookie 但某些 JS 状态可能丢失 |
| HTTPS 证书问题 | 自签名证书需 `--ignore-https-errors`，生产环境慎用 |
适合人群
- QA 工程师：端到端测试、回归测试自动化
- 数据工程师：结构化数据爬取、定时巡检
- 产品经理/UX：用户流程录屏、竞品功能截图存档
- 运维/SRE：定时健康检查、证书过期监控
常规风险管控建议
1. 生产环境避免 --headed 和 --ignore-https-errors
2. 敏感操作前使用 snapshot -i 确认目标元素
3. 大规模爬取时启用 --proxy 并控制请求频率
4. 定期 trace start/stop 记录失败现场便于复盘
5. 多 Session 场景注意内存占用，及时 close 释放资源