[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"similar-vercel-labs--agent-browser":3,"tool-vercel-labs--agent-browser":61},[4,18,26,36,44,53],{"id":5,"name":6,"github_repo":7,"description_zh":8,"stars":9,"difficulty_score":10,"last_commit_at":11,"category_tags":12,"status":17},4358,"openclaw","openclaw\u002Fopenclaw","OpenClaw 是一款专为个人打造的本地化 AI 助手，旨在让你在自己的设备上拥有完全可控的智能伙伴。它打破了传统 AI 助手局限于特定网页或应用的束缚，能够直接接入你日常使用的各类通讯渠道，包括微信、WhatsApp、Telegram、Discord、iMessage 等数十种平台。无论你在哪个聊天软件中发送消息，OpenClaw 都能即时响应，甚至支持在 macOS、iOS 和 Android 设备上进行语音交互，并提供实时的画布渲染功能供你操控。\n\n这款工具主要解决了用户对数据隐私、响应速度以及“始终在线”体验的需求。通过将 AI 部署在本地，用户无需依赖云端服务即可享受快速、私密的智能辅助，真正实现了“你的数据，你做主”。其独特的技术亮点在于强大的网关架构，将控制平面与核心助手分离，确保跨平台通信的流畅性与扩展性。\n\nOpenClaw 非常适合希望构建个性化工作流的技术爱好者、开发者，以及注重隐私保护且不愿被单一生态绑定的普通用户。只要具备基础的终端操作能力（支持 macOS、Linux 及 Windows WSL2），即可通过简单的命令行引导完成部署。如果你渴望拥有一个懂你",349277,3,"2026-04-06T06:32:30",[13,14,15,16],"Agent","开发框架","图像","数据工具","ready",{"id":19,"name":20,"github_repo":21,"description_zh":22,"stars":23,"difficulty_score":10,"last_commit_at":24,"category_tags":25,"status":17},3808,"stable-diffusion-webui","AUTOMATIC1111\u002Fstable-diffusion-webui","stable-diffusion-webui 是一个基于 Gradio 构建的网页版操作界面，旨在让用户能够轻松地在本地运行和使用强大的 Stable Diffusion 图像生成模型。它解决了原始模型依赖命令行、操作门槛高且功能分散的痛点，将复杂的 AI 绘图流程整合进一个直观易用的图形化平台。\n\n无论是希望快速上手的普通创作者、需要精细控制画面细节的设计师，还是想要深入探索模型潜力的开发者与研究人员，都能从中获益。其核心亮点在于极高的功能丰富度：不仅支持文生图、图生图、局部重绘（Inpainting）和外绘（Outpainting）等基础模式，还独创了注意力机制调整、提示词矩阵、负向提示词以及“高清修复”等高级功能。此外，它内置了 GFPGAN 和 CodeFormer 等人脸修复工具，支持多种神经网络放大算法，并允许用户通过插件系统无限扩展能力。即使是显存有限的设备，stable-diffusion-webui 也提供了相应的优化选项，让高质量的 AI 艺术创作变得触手可及。",162132,"2026-04-05T11:01:52",[14,15,13],{"id":27,"name":28,"github_repo":29,"description_zh":30,"stars":31,"difficulty_score":32,"last_commit_at":33,"category_tags":34,"status":17},1381,"everything-claude-code","affaan-m\u002Feverything-claude-code","everything-claude-code 是一套专为 AI 编程助手（如 Claude Code、Codex、Cursor 等）打造的高性能优化系统。它不仅仅是一组配置文件，而是一个经过长期实战打磨的完整框架，旨在解决 AI 代理在实际开发中面临的效率低下、记忆丢失、安全隐患及缺乏持续学习能力等核心痛点。\n\n通过引入技能模块化、直觉增强、记忆持久化机制以及内置的安全扫描功能，everything-claude-code 能显著提升 AI 在复杂任务中的表现，帮助开发者构建更稳定、更智能的生产级 AI 代理。其独特的“研究优先”开发理念和针对 Token 消耗的优化策略，使得模型响应更快、成本更低，同时有效防御潜在的攻击向量。\n\n这套工具特别适合软件开发者、AI 研究人员以及希望深度定制 AI 工作流的技术团队使用。无论您是在构建大型代码库，还是需要 AI 协助进行安全审计与自动化测试，everything-claude-code 都能提供强大的底层支持。作为一个曾荣获 Anthropic 黑客大奖的开源项目，它融合了多语言支持与丰富的实战钩子（hooks），让 AI 真正成长为懂上",150720,2,"2026-04-11T11:33:10",[14,13,35],"语言模型",{"id":37,"name":38,"github_repo":39,"description_zh":40,"stars":41,"difficulty_score":32,"last_commit_at":42,"category_tags":43,"status":17},2271,"ComfyUI","Comfy-Org\u002FComfyUI","ComfyUI 是一款功能强大且高度模块化的视觉 AI 引擎，专为设计和执行复杂的 Stable Diffusion 图像生成流程而打造。它摒弃了传统的代码编写模式，采用直观的节点式流程图界面，让用户通过连接不同的功能模块即可构建个性化的生成管线。\n\n这一设计巧妙解决了高级 AI 绘图工作流配置复杂、灵活性不足的痛点。用户无需具备编程背景，也能自由组合模型、调整参数并实时预览效果，轻松实现从基础文生图到多步骤高清修复等各类复杂任务。ComfyUI 拥有极佳的兼容性，不仅支持 Windows、macOS 和 Linux 全平台，还广泛适配 NVIDIA、AMD、Intel 及苹果 Silicon 等多种硬件架构，并率先支持 SDXL、Flux、SD3 等前沿模型。\n\n无论是希望深入探索算法潜力的研究人员和开发者，还是追求极致创作自由度的设计师与资深 AI 绘画爱好者，ComfyUI 都能提供强大的支持。其独特的模块化架构允许社区不断扩展新功能，使其成为当前最灵活、生态最丰富的开源扩散模型工具之一，帮助用户将创意高效转化为现实。",108322,"2026-04-10T11:39:34",[14,15,13],{"id":45,"name":46,"github_repo":47,"description_zh":48,"stars":49,"difficulty_score":32,"last_commit_at":50,"category_tags":51,"status":17},6121,"gemini-cli","google-gemini\u002Fgemini-cli","gemini-cli 是一款由谷歌推出的开源 AI 命令行工具，它将强大的 Gemini 大模型能力直接集成到用户的终端环境中。对于习惯在命令行工作的开发者而言，它提供了一条从输入提示词到获取模型响应的最短路径，无需切换窗口即可享受智能辅助。\n\n这款工具主要解决了开发过程中频繁上下文切换的痛点，让用户能在熟悉的终端界面内直接完成代码理解、生成、调试以及自动化运维任务。无论是查询大型代码库、根据草图生成应用，还是执行复杂的 Git 操作，gemini-cli 都能通过自然语言指令高效处理。\n\n它特别适合广大软件工程师、DevOps 人员及技术研究人员使用。其核心亮点包括支持高达 100 万 token 的超长上下文窗口，具备出色的逻辑推理能力；内置 Google 搜索、文件操作及 Shell 命令执行等实用工具；更独特的是，它支持 MCP（模型上下文协议），允许用户灵活扩展自定义集成，连接如图像生成等外部能力。此外，个人谷歌账号即可享受免费的额度支持，且项目基于 Apache 2.0 协议完全开源，是提升终端工作效率的理想助手。",100752,"2026-04-10T01:20:03",[52,13,15,14],"插件",{"id":54,"name":55,"github_repo":56,"description_zh":57,"stars":58,"difficulty_score":32,"last_commit_at":59,"category_tags":60,"status":17},4721,"markitdown","microsoft\u002Fmarkitdown","MarkItDown 是一款由微软 AutoGen 团队打造的轻量级 Python 工具，专为将各类文件高效转换为 Markdown 格式而设计。它支持 PDF、Word、Excel、PPT、图片（含 OCR）、音频（含语音转录）、HTML 乃至 YouTube 链接等多种格式的解析，能够精准提取文档中的标题、列表、表格和链接等关键结构信息。\n\n在人工智能应用日益普及的今天，大语言模型（LLM）虽擅长处理文本，却难以直接读取复杂的二进制办公文档。MarkItDown 恰好解决了这一痛点，它将非结构化或半结构化的文件转化为模型“原生理解”且 Token 效率极高的 Markdown 格式，成为连接本地文件与 AI 分析 pipeline 的理想桥梁。此外，它还提供了 MCP（模型上下文协议）服务器，可无缝集成到 Claude Desktop 等 LLM 应用中。\n\n这款工具特别适合开发者、数据科学家及 AI 研究人员使用，尤其是那些需要构建文档检索增强生成（RAG）系统、进行批量文本分析或希望让 AI 助手直接“阅读”本地文件的用户。虽然生成的内容也具备一定可读性，但其核心优势在于为机器",93400,"2026-04-06T19:52:38",[52,14],{"id":62,"github_repo":63,"name":64,"description_en":65,"description_zh":66,"ai_summary_zh":67,"readme_en":68,"readme_zh":69,"quickstart_zh":70,"use_case_zh":71,"hero_image_url":72,"owner_login":73,"owner_name":74,"owner_avatar_url":75,"owner_bio":76,"owner_company":77,"owner_location":77,"owner_email":78,"owner_twitter":79,"owner_website":80,"owner_url":81,"languages":82,"stars":107,"forks":108,"last_commit_at":109,"license":110,"difficulty_score":32,"env_os":111,"env_gpu":112,"env_ram":112,"env_deps":113,"category_tags":120,"github_topics":77,"view_count":32,"oss_zip_url":77,"oss_zip_packed_at":77,"status":17,"created_at":121,"updated_at":122,"faqs":123,"releases":124},6635,"vercel-labs\u002Fagent-browser","agent-browser","Browser automation CLI for AI agents","agent-browser 是一款专为 AI 智能体打造的高性能浏览器自动化命令行工具。它旨在解决 AI 代理在网页交互中难以精准操控浏览器、执行复杂任务流的痛点，让机器能够像人类一样浏览网页、点击按钮、填写表单并获取数据。\n\n这款工具特别适合开发者、AI 研究人员以及需要构建自动化工作流的技术团队使用。无论是测试网页功能、抓取动态内容，还是训练 AI 模型进行网页操作，agent-browser 都能提供稳定可靠的支持。\n\n其核心技术亮点在于采用 Rust 语言原生开发，确保了极快的运行速度和低资源占用。与传统依赖 Node.js 的方案不同，agent-browser 无需安装 Playwright 或 Node.js 环境即可独立运行守护进程。它创新地支持基于“可访问性树引用”的操作模式，用户可以先获取页面元素的结构化快照，再通过唯一的引用 ID 精准定位并操作元素，这比传统的 CSS 选择器更稳定且对 AI 更友好。当然，它也兼容传统的选择器语法和语义化查找（如按角色和名称查找按钮），并内置了自动下载和管理 Chrome 浏览器的功能，极大简化了环境配置流程，让开发者能专注于逻","agent-browser 是一款专为 AI 智能体打造的高性能浏览器自动化命令行工具。它旨在解决 AI 代理在网页交互中难以精准操控浏览器、执行复杂任务流的痛点，让机器能够像人类一样浏览网页、点击按钮、填写表单并获取数据。\n\n这款工具特别适合开发者、AI 研究人员以及需要构建自动化工作流的技术团队使用。无论是测试网页功能、抓取动态内容，还是训练 AI 模型进行网页操作，agent-browser 都能提供稳定可靠的支持。\n\n其核心技术亮点在于采用 Rust 语言原生开发，确保了极快的运行速度和低资源占用。与传统依赖 Node.js 的方案不同，agent-browser 无需安装 Playwright 或 Node.js 环境即可独立运行守护进程。它创新地支持基于“可访问性树引用”的操作模式，用户可以先获取页面元素的结构化快照，再通过唯一的引用 ID 精准定位并操作元素，这比传统的 CSS 选择器更稳定且对 AI 更友好。当然，它也兼容传统的选择器语法和语义化查找（如按角色和名称查找按钮），并内置了自动下载和管理 Chrome 浏览器的功能，极大简化了环境配置流程，让开发者能专注于逻辑实现而非环境调试。","# agent-browser\n\nBrowser automation CLI for AI agents. Fast native Rust CLI.\n\n## Installation\n\n### Global Installation (recommended)\n\nInstalls the native Rust binary:\n\n```bash\nnpm install -g agent-browser\nagent-browser install  # Download Chrome from Chrome for Testing (first time only)\n```\n\n### Project Installation (local dependency)\n\nFor projects that want to pin the version in `package.json`:\n\n```bash\nnpm install agent-browser\nagent-browser install\n```\n\nThen use via `package.json` scripts or by invoking `agent-browser` directly.\n\n### Homebrew (macOS)\n\n```bash\nbrew install agent-browser\nagent-browser install  # Download Chrome from Chrome for Testing (first time only)\n```\n\n### Cargo (Rust)\n\n```bash\ncargo install agent-browser\nagent-browser install  # Download Chrome from Chrome for Testing (first time only)\n```\n\n### From Source\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\ncd agent-browser\npnpm install\npnpm build\npnpm build:native   # Requires Rust (https:\u002F\u002Frustup.rs)\npnpm link --global  # Makes agent-browser available globally\nagent-browser install\n```\n\n### Linux Dependencies\n\nOn Linux, install system dependencies:\n\n```bash\nagent-browser install --with-deps\n```\n\n### Updating\n\nUpgrade to the latest version:\n\n```bash\nagent-browser upgrade\n```\n\nDetects your installation method (npm, Homebrew, or Cargo) and runs the appropriate update command automatically.\n\n### Requirements\n\n- **Chrome** - Run `agent-browser install` to download Chrome from [Chrome for Testing](https:\u002F\u002Fdeveloper.chrome.com\u002Fblog\u002Fchrome-for-testing\u002F) (Google's official automation channel). Existing Chrome, Brave, Playwright, and Puppeteer installations are detected automatically. No Playwright or Node.js required for the daemon.\n- **Rust** - Only needed when building from source (see From Source above).\n\n## Quick Start\n\n```bash\nagent-browser open example.com\nagent-browser snapshot                    # Get accessibility tree with refs\nagent-browser click @e2                   # Click by ref from snapshot\nagent-browser fill @e3 \"test@example.com\" # Fill by ref\nagent-browser get text @e1                # Get text by ref\nagent-browser screenshot page.png\nagent-browser close\n```\n\n### Traditional Selectors (also supported)\n\n```bash\nagent-browser click \"#submit\"\nagent-browser fill \"#email\" \"test@example.com\"\nagent-browser find role button click --name \"Submit\"\n```\n\n## Commands\n\n### Core Commands\n\n```bash\nagent-browser open \u003Curl>              # Navigate to URL (aliases: goto, navigate)\nagent-browser click \u003Csel>             # Click element (--new-tab to open in new tab)\nagent-browser dblclick \u003Csel>          # Double-click element\nagent-browser focus \u003Csel>             # Focus element\nagent-browser type \u003Csel> \u003Ctext>       # Type into element\nagent-browser fill \u003Csel> \u003Ctext>       # Clear and fill\nagent-browser press \u003Ckey>             # Press key (Enter, Tab, Control+a) (alias: key)\nagent-browser keyboard type \u003Ctext>    # Type with real keystrokes (no selector, current focus)\nagent-browser keyboard inserttext \u003Ctext>  # Insert text without key events (no selector)\nagent-browser keydown \u003Ckey>           # Hold key down\nagent-browser keyup \u003Ckey>             # Release key\nagent-browser hover \u003Csel>             # Hover element\nagent-browser select \u003Csel> \u003Cval>      # Select dropdown option\nagent-browser check \u003Csel>             # Check checkbox\nagent-browser uncheck \u003Csel>           # Uncheck checkbox\nagent-browser scroll \u003Cdir> [px]       # Scroll (up\u002Fdown\u002Fleft\u002Fright, --selector \u003Csel>)\nagent-browser scrollintoview \u003Csel>    # Scroll element into view (alias: scrollinto)\nagent-browser drag \u003Csrc> \u003Ctgt>        # Drag and drop\nagent-browser upload \u003Csel> \u003Cfiles>    # Upload files\nagent-browser screenshot [path]       # Take screenshot (--full for full page, saves to a temporary directory if no path)\nagent-browser screenshot --annotate   # Annotated screenshot with numbered element labels\nagent-browser screenshot --screenshot-dir .\u002Fshots    # Save to custom directory\nagent-browser screenshot --screenshot-format jpeg --screenshot-quality 80\nagent-browser pdf \u003Cpath>              # Save as PDF\nagent-browser snapshot                # Accessibility tree with refs (best for AI)\nagent-browser eval \u003Cjs>               # Run JavaScript (-b for base64, --stdin for piped input)\nagent-browser connect \u003Cport>          # Connect to browser via CDP\nagent-browser stream enable [--port \u003Cport>]  # Start runtime WebSocket streaming\nagent-browser stream status           # Show runtime streaming state and bound port\nagent-browser stream disable          # Stop runtime WebSocket streaming\nagent-browser close                   # Close browser (aliases: quit, exit)\nagent-browser close --all             # Close all active sessions\nagent-browser chat \"\u003Cinstruction>\"    # AI chat: natural language browser control (single-shot)\nagent-browser chat                    # AI chat: interactive REPL mode\n```\n\n### Get Info\n\n```bash\nagent-browser get text \u003Csel>          # Get text content\nagent-browser get html \u003Csel>          # Get innerHTML\nagent-browser get value \u003Csel>         # Get input value\nagent-browser get attr \u003Csel> \u003Cattr>   # Get attribute\nagent-browser get title               # Get page title\nagent-browser get url                 # Get current URL\nagent-browser get cdp-url             # Get CDP WebSocket URL (for DevTools, debugging)\nagent-browser get count \u003Csel>         # Count matching elements\nagent-browser get box \u003Csel>           # Get bounding box\nagent-browser get styles \u003Csel>        # Get computed styles\n```\n\n### Check State\n\n```bash\nagent-browser is visible \u003Csel>        # Check if visible\nagent-browser is enabled \u003Csel>        # Check if enabled\nagent-browser is checked \u003Csel>        # Check if checked\n```\n\n### Find Elements (Semantic Locators)\n\n```bash\nagent-browser find role \u003Crole> \u003Caction> [value]       # By ARIA role\nagent-browser find text \u003Ctext> \u003Caction>               # By text content\nagent-browser find label \u003Clabel> \u003Caction> [value]     # By label\nagent-browser find placeholder \u003Cph> \u003Caction> [value]  # By placeholder\nagent-browser find alt \u003Ctext> \u003Caction>                # By alt text\nagent-browser find title \u003Ctext> \u003Caction>              # By title attr\nagent-browser find testid \u003Cid> \u003Caction> [value]       # By data-testid\nagent-browser find first \u003Csel> \u003Caction> [value]       # First match\nagent-browser find last \u003Csel> \u003Caction> [value]        # Last match\nagent-browser find nth \u003Cn> \u003Csel> \u003Caction> [value]     # Nth match\n```\n\n**Actions:** `click`, `fill`, `type`, `hover`, `focus`, `check`, `uncheck`, `text`\n\n**Options:** `--name \u003Cname>` (filter role by accessible name), `--exact` (require exact text match)\n\n**Examples:**\n\n```bash\nagent-browser find role button click --name \"Submit\"\nagent-browser find text \"Sign In\" click\nagent-browser find label \"Email\" fill \"test@test.com\"\nagent-browser find first \".item\" click\nagent-browser find nth 2 \"a\" text\n```\n\n### Wait\n\n```bash\nagent-browser wait \u003Cselector>         # Wait for element to be visible\nagent-browser wait \u003Cms>               # Wait for time (milliseconds)\nagent-browser wait --text \"Welcome\"   # Wait for text to appear (substring match)\nagent-browser wait --url \"**\u002Fdash\"    # Wait for URL pattern\nagent-browser wait --load networkidle # Wait for load state\nagent-browser wait --fn \"window.ready === true\"  # Wait for JS condition\n\n# Wait for text\u002Felement to disappear\nagent-browser wait --fn \"!document.body.innerText.includes('Loading...')\"\nagent-browser wait \"#spinner\" --state hidden\n```\n\n**Load states:** `load`, `domcontentloaded`, `networkidle`\n\n### Batch Execution\n\nExecute multiple commands in a single invocation. Commands can be passed as\nquoted arguments or piped as JSON via stdin. This avoids per-command process\nstartup overhead when running multi-step workflows.\n\n```bash\n# Argument mode: each quoted argument is a full command\nagent-browser batch \"open https:\u002F\u002Fexample.com\" \"snapshot -i\" \"screenshot\"\n\n# With --bail to stop on first error\nagent-browser batch --bail \"open https:\u002F\u002Fexample.com\" \"click @e1\" \"screenshot\"\n\n# Stdin mode: pipe commands as JSON\necho '[\n  [\"open\", \"https:\u002F\u002Fexample.com\"],\n  [\"snapshot\", \"-i\"],\n  [\"click\", \"@e1\"],\n  [\"screenshot\", \"result.png\"]\n]' | agent-browser batch --json\n```\n\n### Clipboard\n\n```bash\nagent-browser clipboard read                      # Read text from clipboard\nagent-browser clipboard write \"Hello, World!\"     # Write text to clipboard\nagent-browser clipboard copy                      # Copy current selection (Ctrl+C)\nagent-browser clipboard paste                     # Paste from clipboard (Ctrl+V)\n```\n\n### Mouse Control\n\n```bash\nagent-browser mouse move \u003Cx> \u003Cy>      # Move mouse\nagent-browser mouse down [button]     # Press button (left\u002Fright\u002Fmiddle)\nagent-browser mouse up [button]       # Release button\nagent-browser mouse wheel \u003Cdy> [dx]   # Scroll wheel\n```\n\n### Browser Settings\n\n```bash\nagent-browser set viewport \u003Cw> \u003Ch> [scale]  # Set viewport size (scale for retina, e.g. 2)\nagent-browser set device \u003Cname>       # Emulate device (\"iPhone 14\")\nagent-browser set geo \u003Clat> \u003Clng>     # Set geolocation\nagent-browser set offline [on|off]    # Toggle offline mode\nagent-browser set headers \u003Cjson>      # Extra HTTP headers\nagent-browser set credentials \u003Cu> \u003Cp> # HTTP basic auth\nagent-browser set media [dark|light]  # Emulate color scheme\n```\n\n### Cookies & Storage\n\n```bash\nagent-browser cookies                 # Get all cookies\nagent-browser cookies set \u003Cname> \u003Cval> # Set cookie\nagent-browser cookies clear           # Clear cookies\n\nagent-browser storage local           # Get all localStorage\nagent-browser storage local \u003Ckey>     # Get specific key\nagent-browser storage local set \u003Ck> \u003Cv>  # Set value\nagent-browser storage local clear     # Clear all\n\nagent-browser storage session         # Same for sessionStorage\n```\n\n### Network\n\n```bash\nagent-browser network route \u003Curl>              # Intercept requests\nagent-browser network route \u003Curl> --abort      # Block requests\nagent-browser network route \u003Curl> --body \u003Cjson>  # Mock response\nagent-browser network unroute [url]            # Remove routes\nagent-browser network requests                 # View tracked requests\nagent-browser network requests --filter api    # Filter requests\nagent-browser network requests --type xhr,fetch  # Filter by resource type\nagent-browser network requests --method POST   # Filter by HTTP method\nagent-browser network requests --status 2xx    # Filter by status (200, 2xx, 400-499)\nagent-browser network request \u003CrequestId>      # View full request\u002Fresponse detail\nagent-browser network har start                # Start HAR recording\nagent-browser network har stop [output.har]    # Stop and save HAR (temp path if omitted)\n```\n\n### Tabs & Windows\n\n```bash\nagent-browser tab                     # List tabs\nagent-browser tab new [url]           # New tab (optionally with URL)\nagent-browser tab \u003Cn>                 # Switch to tab n\nagent-browser tab close [n]           # Close tab\nagent-browser window new              # New window\n```\n\n### Frames\n\n```bash\nagent-browser frame \u003Csel>             # Switch to iframe\nagent-browser frame main              # Back to main frame\n```\n\n### Dialogs\n\n```bash\nagent-browser dialog accept [text]    # Accept (with optional prompt text)\nagent-browser dialog dismiss          # Dismiss\nagent-browser dialog status           # Check if a dialog is currently open\n```\n\nBy default, `alert` and `beforeunload` dialogs are automatically accepted so they never block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` (or `AGENT_BROWSER_NO_AUTO_DIALOG=1`) to disable automatic handling.\n\nWhen a JavaScript dialog is pending, all command responses include a `warning` field with the dialog type and message.\n\n### Diff\n\n```bash\nagent-browser diff snapshot                              # Compare current vs last snapshot\nagent-browser diff snapshot --baseline before.txt        # Compare current vs saved snapshot file\nagent-browser diff snapshot --selector \"#main\" --compact # Scoped snapshot diff\nagent-browser diff screenshot --baseline before.png      # Visual pixel diff against baseline\nagent-browser diff screenshot --baseline b.png -o d.png  # Save diff image to custom path\nagent-browser diff screenshot --baseline b.png -t 0.2    # Adjust color threshold (0-1)\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com     # Compare two URLs (snapshot diff)\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com --screenshot  # Also visual diff\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com --wait-until networkidle  # Custom wait strategy\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com --selector \"#main\"  # Scope to element\n```\n\n### Debug\n\n```bash\nagent-browser trace start [path]      # Start recording trace\nagent-browser trace stop [path]       # Stop and save trace\nagent-browser profiler start          # Start Chrome DevTools profiling\nagent-browser profiler stop [path]    # Stop and save profile (.json)\nagent-browser console                 # View console messages (log, error, warn, info)\nagent-browser console --json          # JSON output with raw CDP args for programmatic access\nagent-browser console --clear         # Clear console\nagent-browser errors                  # View page errors (uncaught JavaScript exceptions)\nagent-browser errors --clear          # Clear errors\nagent-browser highlight \u003Csel>         # Highlight element\nagent-browser inspect                 # Open Chrome DevTools for the active page\nagent-browser state save \u003Cpath>       # Save auth state\nagent-browser state load \u003Cpath>       # Load auth state\nagent-browser state list              # List saved state files\nagent-browser state show \u003Cfile>       # Show state summary\nagent-browser state rename \u003Cold> \u003Cnew> # Rename state file\nagent-browser state clear [name]      # Clear states for session\nagent-browser state clear --all       # Clear all saved states\nagent-browser state clean --older-than \u003Cdays>  # Delete old states\n```\n\n### Navigation\n\n```bash\nagent-browser back                    # Go back\nagent-browser forward                 # Go forward\nagent-browser reload                  # Reload page\n```\n\n### Setup\n\n```bash\nagent-browser install                 # Download Chrome from Chrome for Testing (Google's official automation channel)\nagent-browser install --with-deps     # Also install system deps (Linux)\nagent-browser upgrade                 # Upgrade agent-browser to the latest version\n```\n\n## Authentication\n\nagent-browser provides multiple ways to persist login sessions so you don't re-authenticate every run.\n\n### Quick summary\n\n| Approach | Best for | Flag \u002F Env |\n|----------|----------|------------|\n| **Chrome profile reuse** | Reuse your existing Chrome login state (cookies, sessions) with zero setup | `--profile \u003Cname>` \u002F `AGENT_BROWSER_PROFILE` |\n| **Persistent profile** | Full browser state (cookies, IndexedDB, service workers, cache) across restarts | `--profile \u003Cpath>` \u002F `AGENT_BROWSER_PROFILE` |\n| **Session persistence** | Auto-save\u002Frestore cookies + localStorage by name | `--session-name \u003Cname>` \u002F `AGENT_BROWSER_SESSION_NAME` |\n| **Import from your browser** | Grab auth from a Chrome session you already logged into | `--auto-connect` + `state save` |\n| **State file** | Load a previously saved state JSON on launch | `--state \u003Cpath>` \u002F `AGENT_BROWSER_STATE` |\n| **Auth vault** | Store credentials locally (encrypted), login by name | `auth save` \u002F `auth login` |\n\n### Import auth from your browser\n\nIf you are already logged in to a site in Chrome, you can grab that auth state and reuse it:\n\n```bash\n# 1. Launch Chrome with remote debugging enabled\n#    macOS:\n\"\u002FApplications\u002FGoogle Chrome.app\u002FContents\u002FMacOS\u002FGoogle Chrome\" --remote-debugging-port=9222\n#    Or use --auto-connect to discover an already-running Chrome\n\n# 2. Connect and save the authenticated state\nagent-browser --auto-connect state save .\u002Fmy-auth.json\n\n# 3. Use the saved auth in future sessions\nagent-browser --state .\u002Fmy-auth.json open https:\u002F\u002Fapp.example.com\u002Fdashboard\n\n# 4. Or use --session-name for automatic persistence\nagent-browser --session-name myapp state load .\u002Fmy-auth.json\n# From now on, --session-name myapp auto-saves\u002Frestores this state\n```\n\n> **Security notes:**\n> - `--remote-debugging-port` exposes full browser control on localhost. Any local process can connect. Only use on trusted machines and close Chrome when done.\n> - State files contain session tokens in plaintext. Add them to `.gitignore` and delete when no longer needed. For encryption at rest, set `AGENT_BROWSER_ENCRYPTION_KEY` (see [State Encryption](#state-encryption)).\n\nFor full details on login flows, OAuth, 2FA, cookie-based auth, and the auth vault, see the [Authentication](docs\u002Fsrc\u002Fapp\u002Fsessions\u002Fpage.mdx) docs.\n\n## Sessions\n\nRun multiple isolated browser instances:\n\n```bash\n# Different sessions\nagent-browser --session agent1 open site-a.com\nagent-browser --session agent2 open site-b.com\n\n# Or via environment variable\nAGENT_BROWSER_SESSION=agent1 agent-browser click \"#btn\"\n\n# List active sessions\nagent-browser session list\n# Output:\n# Active sessions:\n# -> default\n#    agent1\n\n# Show current session\nagent-browser session\n```\n\nEach session has its own:\n\n- Browser instance\n- Cookies and storage\n- Navigation history\n- Authentication state\n\n## Chrome Profile Reuse\n\nThe fastest way to use your existing login state: pass a Chrome profile name to `--profile`:\n\n```bash\n# List available Chrome profiles\nagent-browser profiles\n\n# Reuse your default Chrome profile's login state\nagent-browser --profile Default open https:\u002F\u002Fgmail.com\n\n# Use a named profile (by display name or directory name)\nagent-browser --profile \"Work\" open https:\u002F\u002Fapp.example.com\n\n# Or via environment variable\nAGENT_BROWSER_PROFILE=Default agent-browser open https:\u002F\u002Fgmail.com\n```\n\nThis copies your Chrome profile to a temp directory (read-only snapshot, no changes to your original profile), so the browser launches with your existing cookies and sessions.\n\n> **Note:** On Windows, close Chrome before using `--profile \u003Cname>` if Chrome is running, as some profile files may be locked.\n\n## Persistent Profiles\n\nFor a persistent custom profile directory that stores state across browser restarts, pass a path to `--profile`:\n\n```bash\n# Use a persistent profile directory\nagent-browser --profile ~\u002F.myapp-profile open myapp.com\n\n# Login once, then reuse the authenticated session\nagent-browser --profile ~\u002F.myapp-profile open myapp.com\u002Fdashboard\n\n# Or via environment variable\nAGENT_BROWSER_PROFILE=~\u002F.myapp-profile agent-browser open myapp.com\n```\n\nThe profile directory stores:\n\n- Cookies and localStorage\n- IndexedDB data\n- Service workers\n- Browser cache\n- Login sessions\n\n**Tip**: Use different profile paths for different projects to keep their browser state isolated.\n\n## Session Persistence\n\nAlternatively, use `--session-name` to automatically save and restore cookies and localStorage across browser restarts:\n\n```bash\n# Auto-save\u002Fload state for \"twitter\" session\nagent-browser --session-name twitter open twitter.com\n\n# Login once, then state persists automatically\n# State files stored in ~\u002F.agent-browser\u002Fsessions\u002F\n\n# Or via environment variable\nexport AGENT_BROWSER_SESSION_NAME=twitter\nagent-browser open twitter.com\n```\n\n### State Encryption\n\nEncrypt saved session data at rest with AES-256-GCM:\n\n```bash\n# Generate key: openssl rand -hex 32\nexport AGENT_BROWSER_ENCRYPTION_KEY=\u003C64-char-hex-key>\n\n# State files are now encrypted automatically\nagent-browser --session-name secure open example.com\n```\n\n| Variable                          | Description                                        |\n| --------------------------------- | -------------------------------------------------- |\n| `AGENT_BROWSER_SESSION_NAME`      | Auto-save\u002Fload state persistence name              |\n| `AGENT_BROWSER_ENCRYPTION_KEY`    | 64-char hex key for AES-256-GCM encryption         |\n| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | Auto-delete states older than N days (default: 30) |\n\n## Security\n\nagent-browser includes security features for safe AI agent deployments. All features are opt-in -- existing workflows are unaffected until you explicitly enable a feature:\n\n- **Authentication Vault** -- Store credentials locally (always encrypted), reference by name. The LLM never sees passwords. `auth login` navigates with `load` and then waits for login form selectors to appear (SPA-friendly, timeout follows the default action timeout). A key is auto-generated at `~\u002F.agent-browser\u002F.encryption-key` if `AGENT_BROWSER_ENCRYPTION_KEY` is not set: `echo \"pass\" | agent-browser auth save github --url https:\u002F\u002Fgithub.com\u002Flogin --username user --password-stdin` then `agent-browser auth login github`\n- **Content Boundary Markers** -- Wrap page output in delimiters so LLMs can distinguish tool output from untrusted content: `--content-boundaries`\n- **Domain Allowlist** -- Restrict navigation to trusted domains (wildcards like `*.example.com` also match the bare domain): `--allowed-domains \"example.com,*.example.com\"`. Sub-resource requests (scripts, images, fetch) and WebSocket\u002FEventSource connections to non-allowed domains are also blocked. Include any CDN domains your target pages depend on (e.g., `*.cdn.example.com`).\n- **Action Policy** -- Gate destructive actions with a static policy file: `--action-policy .\u002Fpolicy.json`\n- **Action Confirmation** -- Require explicit approval for sensitive action categories: `--confirm-actions eval,download`\n- **Output Length Limits** -- Prevent context flooding: `--max-output 50000`\n\n| Variable                            | Description                              |\n| ----------------------------------- | ---------------------------------------- |\n| `AGENT_BROWSER_CONTENT_BOUNDARIES`  | Wrap page output in boundary markers     |\n| `AGENT_BROWSER_MAX_OUTPUT`          | Max characters for page output           |\n| `AGENT_BROWSER_ALLOWED_DOMAINS`     | Comma-separated allowed domain patterns  |\n| `AGENT_BROWSER_ACTION_POLICY`       | Path to action policy JSON file          |\n| `AGENT_BROWSER_CONFIRM_ACTIONS`     | Action categories requiring confirmation |\n| `AGENT_BROWSER_CONFIRM_INTERACTIVE` | Enable interactive confirmation prompts  |\n\nSee [Security documentation](https:\u002F\u002Fagent-browser.dev\u002Fsecurity) for details.\n\n## Snapshot Options\n\nThe `snapshot` command supports filtering to reduce output size:\n\n```bash\nagent-browser snapshot                    # Full accessibility tree\nagent-browser snapshot -i                 # Interactive elements only (buttons, inputs, links)\nagent-browser snapshot -i --urls          # Interactive elements with link URLs\nagent-browser snapshot -c                 # Compact (remove empty structural elements)\nagent-browser snapshot -d 3               # Limit depth to 3 levels\nagent-browser snapshot -s \"#main\"         # Scope to CSS selector\nagent-browser snapshot -i -c -d 5         # Combine options\n```\n\n| Option                 | Description                                                             |\n| ---------------------- | ----------------------------------------------------------------------- |\n| `-i, --interactive`    | Only show interactive elements (buttons, links, inputs)                 |\n| `-u, --urls`           | Include href URLs for link elements                                     |\n| `-c, --compact`        | Remove empty structural elements                                        |\n| `-d, --depth \u003Cn>`      | Limit tree depth                                                        |\n| `-s, --selector \u003Csel>` | Scope to CSS selector                                                   |\n\n## Annotated Screenshots\n\nThe `--annotate` flag overlays numbered labels on interactive elements in the screenshot. Each label `[N]` corresponds to ref `@eN`, so the same refs work for both visual and text-based workflows.\n\nAnnotated screenshots are supported on the CDP-backed browser path (Chrome\u002FLightpanda). The Safari\u002FWebDriver backend does not yet support `--annotate`.\n\n```bash\nagent-browser screenshot --annotate\n# -> Screenshot saved to \u002Ftmp\u002Fscreenshot-2026-02-17T12-00-00-abc123.png\n#    [1] @e1 button \"Submit\"\n#    [2] @e2 link \"Home\"\n#    [3] @e3 textbox \"Email\"\n```\n\nAfter an annotated screenshot, refs are cached so you can immediately interact with elements:\n\n```bash\nagent-browser screenshot --annotate .\u002Fpage.png\nagent-browser click @e2     # Click the \"Home\" link labeled [2]\n```\n\nThis is useful for multimodal AI models that can reason about visual layout, unlabeled icon buttons, canvas elements, or visual state that the text accessibility tree cannot capture.\n\n## Options\n\n| Option | Description |\n|--------|-------------|\n| `--session \u003Cname>` | Use isolated session (or `AGENT_BROWSER_SESSION` env) |\n| `--session-name \u003Cname>` | Auto-save\u002Frestore session state (or `AGENT_BROWSER_SESSION_NAME` env) |\n| `--profile \u003Cname\\|path>` | Chrome profile name or persistent directory path (or `AGENT_BROWSER_PROFILE` env) |\n| `--state \u003Cpath>` | Load storage state from JSON file (or `AGENT_BROWSER_STATE` env) |\n| `--headers \u003Cjson>` | Set HTTP headers scoped to the URL's origin |\n| `--executable-path \u003Cpath>` | Custom browser executable (or `AGENT_BROWSER_EXECUTABLE_PATH` env) |\n| `--extension \u003Cpath>` | Load browser extension (repeatable; or `AGENT_BROWSER_EXTENSIONS` env) |\n| `--args \u003Cargs>` | Browser launch args, comma or newline separated (or `AGENT_BROWSER_ARGS` env) |\n| `--user-agent \u003Cua>` | Custom User-Agent string (or `AGENT_BROWSER_USER_AGENT` env) |\n| `--proxy \u003Curl>` | Proxy server URL with optional auth (or `AGENT_BROWSER_PROXY` env) |\n| `--proxy-bypass \u003Chosts>` | Hosts to bypass proxy (or `AGENT_BROWSER_PROXY_BYPASS` env) |\n| `--ignore-https-errors` | Ignore HTTPS certificate errors (useful for self-signed certs) |\n| `--allow-file-access` | Allow file:\u002F\u002F URLs to access local files (Chromium only) |\n| `-p, --provider \u003Cname>` | Cloud browser provider (or `AGENT_BROWSER_PROVIDER` env) |\n| `--device \u003Cname>` | iOS device name, e.g. \"iPhone 15 Pro\" (or `AGENT_BROWSER_IOS_DEVICE` env) |\n| `--json` | JSON output (for agents) |\n| `--annotate` | Annotated screenshot with numbered element labels (or `AGENT_BROWSER_ANNOTATE` env) |\n| `--screenshot-dir \u003Cpath>` | Default screenshot output directory (or `AGENT_BROWSER_SCREENSHOT_DIR` env) |\n| `--screenshot-quality \u003Cn>` | JPEG quality 0-100 (or `AGENT_BROWSER_SCREENSHOT_QUALITY` env) |\n| `--screenshot-format \u003Cfmt>` | Screenshot format: `png`, `jpeg` (or `AGENT_BROWSER_SCREENSHOT_FORMAT` env) |\n| `--headed` | Show browser window (not headless) (or `AGENT_BROWSER_HEADED` env) |\n| `--cdp \u003Cport\\|url>` | Connect via Chrome DevTools Protocol (port or WebSocket URL) |\n| `--auto-connect` | Auto-discover and connect to running Chrome (or `AGENT_BROWSER_AUTO_CONNECT` env) |\n| `--color-scheme \u003Cscheme>` | Color scheme: `dark`, `light`, `no-preference` (or `AGENT_BROWSER_COLOR_SCHEME` env) |\n| `--download-path \u003Cpath>` | Default download directory (or `AGENT_BROWSER_DOWNLOAD_PATH` env) |\n| `--content-boundaries` | Wrap page output in boundary markers for LLM safety (or `AGENT_BROWSER_CONTENT_BOUNDARIES` env) |\n| `--max-output \u003Cchars>` | Truncate page output to N characters (or `AGENT_BROWSER_MAX_OUTPUT` env) |\n| `--allowed-domains \u003Clist>` | Comma-separated allowed domain patterns (or `AGENT_BROWSER_ALLOWED_DOMAINS` env) |\n| `--action-policy \u003Cpath>` | Path to action policy JSON file (or `AGENT_BROWSER_ACTION_POLICY` env) |\n| `--confirm-actions \u003Clist>` | Action categories requiring confirmation (or `AGENT_BROWSER_CONFIRM_ACTIONS` env) |\n| `--confirm-interactive` | Interactive confirmation prompts; auto-denies if stdin is not a TTY (or `AGENT_BROWSER_CONFIRM_INTERACTIVE` env) |\n| `--engine \u003Cname>` | Browser engine: `chrome` (default), `lightpanda` (or `AGENT_BROWSER_ENGINE` env) |\n| `--no-auto-dialog` | Disable automatic dismissal of `alert`\u002F`beforeunload` dialogs (or `AGENT_BROWSER_NO_AUTO_DIALOG` env) |\n| `--model \u003Cname>` | AI model for chat command (or `AI_GATEWAY_MODEL` env) |\n| `-v`, `--verbose` | Show tool commands and their raw output (chat) |\n| `-q`, `--quiet` | Show only AI text responses, hide tool calls (chat) |\n| `--config \u003Cpath>` | Use a custom config file (or `AGENT_BROWSER_CONFIG` env) |\n| `--debug` | Debug output |\n\n## Observability Dashboard\n\nMonitor agent-browser sessions in real time with a local web dashboard showing a live viewport and command activity feed.\n\n```bash\n# Start the dashboard server (runs in background on port 4848)\nagent-browser dashboard start\nagent-browser dashboard start --port 8080   # Custom port\n\n# All sessions are automatically visible in the dashboard\nagent-browser open example.com\n\n# Stop the dashboard\nagent-browser dashboard stop\n```\n\nThe dashboard runs as a standalone background process on port 4848, independent of browser sessions. It stays available even when no sessions are running. All sessions automatically stream to the dashboard.\n\nThe dashboard displays:\n- **Live viewport** -- real-time JPEG frames from the browser\n- **Activity feed** -- chronological command\u002Fresult stream with timing and expandable details\n- **Console output** -- browser console messages (log, warn, error)\n- **Session creation** -- create new sessions from the UI with local engines (Chrome, Lightpanda) or cloud providers (AgentCore, Browserbase, Browserless, Browser Use, Kernel)\n- **AI Chat** -- chat with an AI assistant directly in the dashboard (requires Vercel AI Gateway configuration)\n\n### AI Chat\n\nThe dashboard includes an optional AI chat panel powered by the Vercel AI Gateway. The same functionality is available directly from the CLI via the `chat` command. Set these environment variables to enable AI chat:\n\n```bash\nexport AI_GATEWAY_API_KEY=gw_your_key_here\nexport AI_GATEWAY_MODEL=anthropic\u002Fclaude-sonnet-4.6           # optional, this is the default\nexport AI_GATEWAY_URL=https:\u002F\u002Fai-gateway.vercel.sh           # optional, this is the default\n```\n\n**CLI usage:**\n\n```bash\nagent-browser chat \"open google.com and search for cats\"     # Single-shot\nagent-browser chat                                           # Interactive REPL\nagent-browser -q chat \"summarize this page\"                  # Quiet mode (text only)\nagent-browser -v chat \"fill in the login form\"               # Verbose (show command output)\nagent-browser --model openai\u002Fgpt-4o chat \"take a screenshot\" # Override model\n```\n\nThe `chat` command translates natural language instructions into agent-browser commands, executes them, and streams the AI response. In interactive mode, type `quit` to exit. Use `--json` for structured output suitable for agent consumption.\n\n**Dashboard usage:**\n\nThe Chat tab is always visible in the dashboard. When `AI_GATEWAY_API_KEY` is set, the Rust server proxies requests to the gateway and streams responses back using the Vercel AI SDK's UI Message Stream protocol. Without the key, sending a message shows an error inline.\n\n## Configuration\n\nCreate an `agent-browser.json` file to set persistent defaults instead of repeating flags on every command.\n\n**Locations (lowest to highest priority):**\n\n1. `~\u002F.agent-browser\u002Fconfig.json` -- user-level defaults\n2. `.\u002Fagent-browser.json` -- project-level overrides (in working directory)\n3. `AGENT_BROWSER_*` environment variables override config file values\n4. CLI flags override everything\n\n**Example `agent-browser.json`:**\n\n```json\n{\n  \"headed\": true,\n  \"proxy\": \"http:\u002F\u002Flocalhost:8080\",\n  \"profile\": \".\u002Fbrowser-data\",\n  \"userAgent\": \"my-agent\u002F1.0\",\n  \"ignoreHttpsErrors\": true\n}\n```\n\nUse `--config \u003Cpath>` or `AGENT_BROWSER_CONFIG` to load a specific config file instead of the defaults:\n\n```bash\nagent-browser --config .\u002Fci-config.json open example.com\nAGENT_BROWSER_CONFIG=.\u002Fci-config.json agent-browser open example.com\n```\n\nAll options from the table above can be set in the config file using camelCase keys (e.g., `--executable-path` becomes `\"executablePath\"`, `--proxy-bypass` becomes `\"proxyBypass\"`). Unknown keys are ignored for forward compatibility.\n\nBoolean flags accept an optional `true`\u002F`false` value to override config settings. For example, `--headed false` disables `\"headed\": true` from config. A bare `--headed` is equivalent to `--headed true`.\n\nAuto-discovered config files that are missing are silently ignored. If `--config \u003Cpath>` points to a missing or invalid file, agent-browser exits with an error. Extensions from user and project configs are merged (concatenated), not replaced.\n\n> **Tip:** If your project-level `agent-browser.json` contains environment-specific values (paths, proxies), consider adding it to `.gitignore`.\n\n## Default Timeout\n\nThe default timeout for standard operations (clicks, waits, fills, etc.) is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout so that the daemon returns a proper error instead of the CLI timing out with EAGAIN.\n\nOverride the default timeout via environment variable:\n\n```bash\n# Set a longer timeout for slow pages (in milliseconds)\nexport AGENT_BROWSER_DEFAULT_TIMEOUT=45000\n```\n\n> **Note:** Setting this above 30000 (30s) may cause EAGAIN errors on slow operations because the CLI's read timeout will expire before the daemon responds. The CLI retries transient errors automatically, but response times will increase.\n\n| Variable                        | Description                              |\n| ------------------------------- | ---------------------------------------- |\n| `AGENT_BROWSER_DEFAULT_TIMEOUT` | Default operation timeout in ms (default: 25000) |\n\n## Selectors\n\n### Refs (Recommended for AI)\n\nRefs provide deterministic element selection from snapshots:\n\n```bash\n# 1. Get snapshot with refs\nagent-browser snapshot\n# Output:\n# - heading \"Example Domain\" [ref=e1] [level=1]\n# - button \"Submit\" [ref=e2]\n# - textbox \"Email\" [ref=e3]\n# - link \"Learn more\" [ref=e4]\n\n# 2. Use refs to interact\nagent-browser click @e2                   # Click the button\nagent-browser fill @e3 \"test@example.com\" # Fill the textbox\nagent-browser get text @e1                # Get heading text\nagent-browser hover @e4                   # Hover the link\n```\n\n**Why use refs?**\n\n- **Deterministic**: Ref points to exact element from snapshot\n- **Fast**: No DOM re-query needed\n- **AI-friendly**: Snapshot + ref workflow is optimal for LLMs\n\n### CSS Selectors\n\n```bash\nagent-browser click \"#id\"\nagent-browser click \".class\"\nagent-browser click \"div > button\"\n```\n\n### Text & XPath\n\n```bash\nagent-browser click \"text=Submit\"\nagent-browser click \"xpath=\u002F\u002Fbutton\"\n```\n\n### Semantic Locators\n\n```bash\nagent-browser find role button click --name \"Submit\"\nagent-browser find label \"Email\" fill \"test@test.com\"\n```\n\n## Agent Mode\n\nUse `--json` for machine-readable output:\n\n```bash\nagent-browser snapshot --json\n# Returns: {\"success\":true,\"data\":{\"snapshot\":\"...\",\"refs\":{\"e1\":{\"role\":\"heading\",\"name\":\"Title\"},...}}}\n\nagent-browser get text @e1 --json\nagent-browser is visible @e2 --json\n```\n\n### Optimal AI Workflow\n\n```bash\n# 1. Navigate and get snapshot\nagent-browser open example.com\nagent-browser snapshot -i --json   # AI parses tree and refs\n\n# 2. AI identifies target refs from snapshot\n# 3. Execute actions using refs\nagent-browser click @e2\nagent-browser fill @e3 \"input text\"\n\n# 4. Get new snapshot if page changed\nagent-browser snapshot -i --json\n```\n\n### Command Chaining\n\nCommands can be chained with `&&` in a single shell invocation. The browser persists via a background daemon, so chaining is safe and more efficient:\n\n```bash\n# Open, wait for load, and snapshot in one call\nagent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i\n\n# Chain multiple interactions\nagent-browser fill @e1 \"user@example.com\" && agent-browser fill @e2 \"pass\" && agent-browser click @e3\n\n# Navigate and screenshot\nagent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png\n```\n\nUse `&&` when you don't need intermediate output. Run commands separately when you need to parse output first (e.g., snapshot to discover refs before interacting).\n\n## Headed Mode\n\nShow the browser window for debugging:\n\n```bash\nagent-browser open example.com --headed\n```\n\nThis opens a visible browser window instead of running headless.\n\n> **Note:** Browser extensions work in both headed and headless mode (Chrome's `--headless=new`).\n\n## Authenticated Sessions\n\nUse `--headers` to set HTTP headers for a specific origin, enabling authentication without login flows:\n\n```bash\n# Headers are scoped to api.example.com only\nagent-browser open api.example.com --headers '{\"Authorization\": \"Bearer \u003Ctoken>\"}'\n\n# Requests to api.example.com include the auth header\nagent-browser snapshot -i --json\nagent-browser click @e2\n\n# Navigate to another domain - headers are NOT sent (safe!)\nagent-browser open other-site.com\n```\n\nThis is useful for:\n\n- **Skipping login flows** - Authenticate via headers instead of UI\n- **Switching users** - Start new sessions with different auth tokens\n- **API testing** - Access protected endpoints directly\n- **Security** - Headers are scoped to the origin, not leaked to other domains\n\nTo set headers for multiple origins, use `--headers` with each `open` command:\n\n```bash\nagent-browser open api.example.com --headers '{\"Authorization\": \"Bearer token1\"}'\nagent-browser open api.acme.com --headers '{\"Authorization\": \"Bearer token2\"}'\n```\n\nFor global headers (all domains), use `set headers`:\n\n```bash\nagent-browser set headers '{\"X-Custom-Header\": \"value\"}'\n```\n\n## Custom Browser Executable\n\nUse a custom browser executable instead of the bundled Chromium. This is useful for:\n\n- **Serverless deployment**: Use lightweight Chromium builds like `@sparticuz\u002Fchromium` (~50MB vs ~684MB)\n- **System browsers**: Use an existing Chrome\u002FChromium installation\n- **Custom builds**: Use modified browser builds\n\n### CLI Usage\n\n```bash\n# Via flag\nagent-browser --executable-path \u002Fpath\u002Fto\u002Fchromium open example.com\n\n# Via environment variable\nAGENT_BROWSER_EXECUTABLE_PATH=\u002Fpath\u002Fto\u002Fchromium agent-browser open example.com\n```\n\n### Serverless (Vercel)\n\nRun agent-browser + Chrome in an ephemeral Vercel Sandbox microVM. No external server needed:\n\n```typescript\nimport { Sandbox } from \"@vercel\u002Fsandbox\";\n\nconst sandbox = await Sandbox.create({ runtime: \"node24\" });\nawait sandbox.runCommand(\"agent-browser\", [\"open\", \"https:\u002F\u002Fexample.com\"]);\nconst result = await sandbox.runCommand(\"agent-browser\", [\"screenshot\", \"--json\"]);\nawait sandbox.stop();\n```\n\nSee the [environments example](examples\u002Fenvironments\u002F) for a working demo with a UI and deploy-to-Vercel button.\n\n### Serverless (AWS Lambda)\n\n```typescript\nimport chromium from '@sparticuz\u002Fchromium';\nimport { execSync } from 'child_process';\n\nexport async function handler() {\n  const executablePath = await chromium.executablePath();\n  const result = execSync(\n    `AGENT_BROWSER_EXECUTABLE_PATH=${executablePath} agent-browser open https:\u002F\u002Fexample.com && agent-browser snapshot -i --json`,\n    { encoding: 'utf-8' }\n  );\n  return JSON.parse(result);\n}\n```\n\n## Local Files\n\nOpen and interact with local files (PDFs, HTML, etc.) using `file:\u002F\u002F` URLs:\n\n```bash\n# Enable file access (required for JavaScript to access local files)\nagent-browser --allow-file-access open file:\u002F\u002F\u002Fpath\u002Fto\u002Fdocument.pdf\nagent-browser --allow-file-access open file:\u002F\u002F\u002Fpath\u002Fto\u002Fpage.html\n\n# Take screenshot of a local PDF\nagent-browser --allow-file-access open file:\u002F\u002F\u002FUsers\u002Fme\u002Freport.pdf\nagent-browser screenshot report.png\n```\n\nThe `--allow-file-access` flag adds Chromium flags (`--allow-file-access-from-files`, `--allow-file-access`) that allow `file:\u002F\u002F` URLs to:\n\n- Load and render local files\n- Access other local files via JavaScript (XHR, fetch)\n- Load local resources (images, scripts, stylesheets)\n\n**Note:** This flag only works with Chromium. For security, it's disabled by default.\n\n## CDP Mode\n\nConnect to an existing browser via Chrome DevTools Protocol:\n\n```bash\n# Start Chrome with: google-chrome --remote-debugging-port=9222\n\n# Connect once, then run commands without --cdp\nagent-browser connect 9222\nagent-browser snapshot\nagent-browser tab\nagent-browser close\n\n# Or pass --cdp on each command\nagent-browser --cdp 9222 snapshot\n\n# Connect to remote browser via WebSocket URL\nagent-browser --cdp \"wss:\u002F\u002Fyour-browser-service.com\u002Fcdp?token=...\" snapshot\n```\n\nThe `--cdp` flag accepts either:\n\n- A port number (e.g., `9222`) for local connections via `http:\u002F\u002Flocalhost:{port}`\n- A full WebSocket URL (e.g., `wss:\u002F\u002F...` or `ws:\u002F\u002F...`) for remote browser services\n\nThis enables control of:\n\n- Electron apps\n- Chrome\u002FChromium instances with remote debugging\n- WebView2 applications\n- Any browser exposing a CDP endpoint\n\n### Auto-Connect\n\nUse `--auto-connect` to automatically discover and connect to a running Chrome instance without specifying a port:\n\n```bash\n# Auto-discover running Chrome with remote debugging\nagent-browser --auto-connect open example.com\nagent-browser --auto-connect snapshot\n\n# Or via environment variable\nAGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot\n```\n\nAuto-connect discovers Chrome by:\n\n1. Reading Chrome's `DevToolsActivePort` file from the default user data directory\n2. Falling back to probing common debugging ports (9222, 9229)\n3. If HTTP-based discovery (`\u002Fjson\u002Fversion`, `\u002Fjson\u002Flist`) fails, falling back to a direct WebSocket connection\n\nThis is useful when:\n\n- Chrome 144+ has remote debugging enabled via `chrome:\u002F\u002Finspect\u002F#remote-debugging` (which uses a dynamic port)\n- You want a zero-configuration connection to your existing browser\n- You don't want to track which port Chrome is using\n\n## Streaming (Browser Preview)\n\nStream the browser viewport via WebSocket for live preview or \"pair browsing\" where a human can watch and interact alongside an AI agent.\n\n### Streaming\n\nEvery session automatically starts a WebSocket stream server on an OS-assigned port. Use `stream status` to see the bound port and connection state:\n\n```bash\nagent-browser stream status\n```\n\nTo bind to a specific port, set `AGENT_BROWSER_STREAM_PORT`:\n\n```bash\nAGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com\n```\n\nYou can also manage streaming at runtime with `stream enable`, `stream disable`, and `stream status`:\n\n```bash\nagent-browser stream enable --port 9223   # Re-enable on a specific port\nagent-browser stream disable              # Stop streaming for the session\n```\n\nThe WebSocket server streams the browser viewport and accepts input events.\n\n### WebSocket Protocol\n\nConnect to `ws:\u002F\u002Flocalhost:9223` to receive frames and send input:\n\n**Receive frames:**\n\n```json\n{\n  \"type\": \"frame\",\n  \"data\": \"\u003Cbase64-encoded-jpeg>\",\n  \"metadata\": {\n    \"deviceWidth\": 1280,\n    \"deviceHeight\": 720,\n    \"pageScaleFactor\": 1,\n    \"offsetTop\": 0,\n    \"scrollOffsetX\": 0,\n    \"scrollOffsetY\": 0\n  }\n}\n```\n\n**Send mouse events:**\n\n```json\n{\n  \"type\": \"input_mouse\",\n  \"eventType\": \"mousePressed\",\n  \"x\": 100,\n  \"y\": 200,\n  \"button\": \"left\",\n  \"clickCount\": 1\n}\n```\n\n**Send keyboard events:**\n\n```json\n{\n  \"type\": \"input_keyboard\",\n  \"eventType\": \"keyDown\",\n  \"key\": \"Enter\",\n  \"code\": \"Enter\"\n}\n```\n\n**Send touch events:**\n\n```json\n{\n  \"type\": \"input_touch\",\n  \"eventType\": \"touchStart\",\n  \"touchPoints\": [{ \"x\": 100, \"y\": 200 }]\n}\n```\n\n## Architecture\n\nagent-browser uses a client-daemon architecture:\n\n1. **Rust CLI** - Parses commands, communicates with daemon\n2. **Rust Daemon** - Pure Rust daemon using direct CDP, no Node.js required\n\nThe daemon starts automatically on first command and persists between commands for fast subsequent operations. To auto-shutdown the daemon after a period of inactivity, set `AGENT_BROWSER_IDLE_TIMEOUT_MS` (value in milliseconds). When set, the daemon closes the browser and exits after receiving no commands for the specified duration.\n\n**Browser Engine:** Uses Chrome (from Chrome for Testing) by default. The `--engine` flag selects between `chrome` and `lightpanda`. Supported browsers: Chromium\u002FChrome (via CDP) and Safari (via WebDriver for iOS).\n\n## Platforms\n\n| Platform    | Binary      |\n| ----------- | ----------- |\n| macOS ARM64 | Native Rust |\n| macOS x64   | Native Rust |\n| Linux ARM64 | Native Rust |\n| Linux x64   | Native Rust |\n| Windows x64 | Native Rust |\n\n## Usage with AI Agents\n\n### Just ask the agent\n\nThe simplest approach -- just tell your agent to use it:\n\n```\nUse agent-browser to test the login flow. Run agent-browser --help to see available commands.\n```\n\nThe `--help` output is comprehensive and most agents can figure it out from there.\n\n### AI Coding Assistants (recommended)\n\nAdd the skill to your AI coding assistant for richer context:\n\n```bash\nnpx skills add vercel-labs\u002Fagent-browser\n```\n\nThis works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, Goose, OpenCode, and Windsurf. The skill is fetched from the repository, so it stays up to date automatically -- do not copy `SKILL.md` from `node_modules` as it will become stale.\n\n### Claude Code\n\nInstall as a Claude Code skill:\n\n```bash\nnpx skills add vercel-labs\u002Fagent-browser\n```\n\nThis adds the skill to `.claude\u002Fskills\u002Fagent-browser\u002FSKILL.md` in your project. The skill teaches Claude Code the full agent-browser workflow, including the snapshot-ref interaction pattern, session management, and timeout handling.\n\n### AGENTS.md \u002F CLAUDE.md\n\nFor more consistent results, add to your project or global instructions file:\n\n```markdown\n## Browser Automation\n\nUse `agent-browser` for web automation. Run `agent-browser --help` for all commands.\n\nCore workflow:\n\n1. `agent-browser open \u003Curl>` - Navigate to page\n2. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)\n3. `agent-browser click @e1` \u002F `fill @e2 \"text\"` - Interact using refs\n4. Re-snapshot after page changes\n```\n\n## Integrations\n\n### iOS Simulator\n\nControl real Mobile Safari in the iOS Simulator for authentic mobile web testing. Requires macOS with Xcode.\n\n**Setup:**\n\n```bash\n# Install Appium and XCUITest driver\nnpm install -g appium\nappium driver install xcuitest\n```\n\n**Usage:**\n\n```bash\n# List available iOS simulators\nagent-browser device list\n\n# Launch Safari on a specific device\nagent-browser -p ios --device \"iPhone 16 Pro\" open https:\u002F\u002Fexample.com\n\n# Same commands as desktop\nagent-browser -p ios snapshot -i\nagent-browser -p ios tap @e1\nagent-browser -p ios fill @e2 \"text\"\nagent-browser -p ios screenshot mobile.png\n\n# Mobile-specific commands\nagent-browser -p ios swipe up\nagent-browser -p ios swipe down 500\n\n# Close session\nagent-browser -p ios close\n```\n\nOr use environment variables:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=ios\nexport AGENT_BROWSER_IOS_DEVICE=\"iPhone 16 Pro\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n| Variable                   | Description                                     |\n| -------------------------- | ----------------------------------------------- |\n| `AGENT_BROWSER_PROVIDER`   | Set to `ios` to enable iOS mode                 |\n| `AGENT_BROWSER_IOS_DEVICE` | Device name (e.g., \"iPhone 16 Pro\", \"iPad Pro\") |\n| `AGENT_BROWSER_IOS_UDID`   | Device UDID (alternative to device name)        |\n\n**Supported devices:** All iOS Simulators available in Xcode (iPhones, iPads), plus real iOS devices.\n\n**Note:** The iOS provider boots the simulator, starts Appium, and controls Safari. First launch takes ~30-60 seconds; subsequent commands are fast.\n\n#### Real Device Support\n\nAppium also supports real iOS devices connected via USB. This requires additional one-time setup:\n\n**1. Get your device UDID:**\n\n```bash\nxcrun xctrace list devices\n# or\nsystem_profiler SPUSBDataType | grep -A 5 \"iPhone\\|iPad\"\n```\n\n**2. Sign WebDriverAgent (one-time):**\n\n```bash\n# Open the WebDriverAgent Xcode project\ncd ~\u002F.appium\u002Fnode_modules\u002Fappium-xcuitest-driver\u002Fnode_modules\u002Fappium-webdriveragent\nopen WebDriverAgent.xcodeproj\n```\n\nIn Xcode:\n\n- Select the `WebDriverAgentRunner` target\n- Go to Signing & Capabilities\n- Select your Team (requires Apple Developer account, free tier works)\n- Let Xcode manage signing automatically\n\n**3. Use with agent-browser:**\n\n```bash\n# Connect device via USB, then:\nagent-browser -p ios --device \"\u003CDEVICE_UDID>\" open https:\u002F\u002Fexample.com\n\n# Or use the device name if unique\nagent-browser -p ios --device \"John's iPhone\" open https:\u002F\u002Fexample.com\n```\n\n**Real device notes:**\n\n- First run installs WebDriverAgent to the device (may require Trust prompt)\n- Device must be unlocked and connected via USB\n- Slightly slower initial connection than simulator\n- Tests against real Safari performance and behavior\n\n### Browserless\n\n[Browserless](https:\u002F\u002Fbrowserless.io) provides cloud browser infrastructure with a Sessions API. Use it when running agent-browser in environments where a local browser isn't available.\n\nTo enable Browserless, use the `-p` flag:\n\n```bash\nexport BROWSERLESS_API_KEY=\"your-api-token\"\nagent-browser -p browserless open https:\u002F\u002Fexample.com\n```\n\nOr use environment variables for CI\u002Fscripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browserless\nexport BROWSERLESS_API_KEY=\"your-api-token\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\nOptional configuration via environment variables:\n\n| Variable                   | Description                                      | Default                                 |\n| -------------------------- | ------------------------------------------------ | --------------------------------------- |\n| `BROWSERLESS_API_URL`      | Base API URL (for custom regions or self-hosted) | `https:\u002F\u002Fproduction-sfo.browserless.io` |\n| `BROWSERLESS_BROWSER_TYPE` | Type of browser to use (chromium or chrome)      | chromium                                |\n| `BROWSERLESS_TTL`          | Session TTL in milliseconds                      | `300000`                                |\n| `BROWSERLESS_STEALTH`      | Enable stealth mode (`true`\u002F`false`)             | `true`                                  |\n\nWhen enabled, agent-browser connects to a Browserless cloud session instead of launching a local browser. All commands work identically.\n\nGet your API token from the [Browserless Dashboard](https:\u002F\u002Fbrowserless.io).\n\n### Browserbase\n\n[Browserbase](https:\u002F\u002Fbrowserbase.com) provides remote browser infrastructure to make deployment of agentic browsing agents easy. Use it when running the agent-browser CLI in an environment where a local browser isn't feasible.\n\nTo enable Browserbase, use the `-p` flag:\n\n```bash\nexport BROWSERBASE_API_KEY=\"your-api-key\"\nagent-browser -p browserbase open https:\u002F\u002Fexample.com\n```\n\nOr use environment variables for CI\u002Fscripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browserbase\nexport BROWSERBASE_API_KEY=\"your-api-key\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\nWhen enabled, agent-browser connects to a Browserbase session instead of launching a local browser. All commands work identically.\n\nGet your API key from the [Browserbase Dashboard](https:\u002F\u002Fbrowserbase.com\u002Foverview).\n\n### Browser Use\n\n[Browser Use](https:\u002F\u002Fbrowser-use.com) provides cloud browser infrastructure for AI agents. Use it when running agent-browser in environments where a local browser isn't available (serverless, CI\u002FCD, etc.).\n\nTo enable Browser Use, use the `-p` flag:\n\n```bash\nexport BROWSER_USE_API_KEY=\"your-api-key\"\nagent-browser -p browseruse open https:\u002F\u002Fexample.com\n```\n\nOr use environment variables for CI\u002Fscripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browseruse\nexport BROWSER_USE_API_KEY=\"your-api-key\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\nWhen enabled, agent-browser connects to a Browser Use cloud session instead of launching a local browser. All commands work identically.\n\nGet your API key from the [Browser Use Cloud Dashboard](https:\u002F\u002Fcloud.browser-use.com\u002Fsettings?tab=api-keys). Free credits are available to get started, with pay-as-you-go pricing after.\n\n### Kernel\n\n[Kernel](https:\u002F\u002Fwww.kernel.sh) provides cloud browser infrastructure for AI agents with features like stealth mode and persistent profiles.\n\nTo enable Kernel, use the `-p` flag:\n\n```bash\nexport KERNEL_API_KEY=\"your-api-key\"\nagent-browser -p kernel open https:\u002F\u002Fexample.com\n```\n\nOr use environment variables for CI\u002Fscripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=kernel\nexport KERNEL_API_KEY=\"your-api-key\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\nOptional configuration via environment variables:\n\n| Variable                 | Description                                                                      | Default |\n| ------------------------ | -------------------------------------------------------------------------------- | ------- |\n| `KERNEL_HEADLESS`        | Run browser in headless mode (`true`\u002F`false`)                                    | `false` |\n| `KERNEL_STEALTH`         | Enable stealth mode to avoid bot detection (`true`\u002F`false`)                      | `true`  |\n| `KERNEL_TIMEOUT_SECONDS` | Session timeout in seconds                                                       | `300`   |\n| `KERNEL_PROFILE_NAME`    | Browser profile name for persistent cookies\u002Flogins (created if it doesn't exist) | (none)  |\n\nWhen enabled, agent-browser connects to a Kernel cloud session instead of launching a local browser. All commands work identically.\n\n**Profile Persistence:** When `KERNEL_PROFILE_NAME` is set, the profile will be created if it doesn't already exist. Cookies, logins, and session data are automatically saved back to the profile when the browser session ends, making them available for future sessions.\n\nGet your API key from the [Kernel Dashboard](https:\u002F\u002Fdashboard.onkernel.com).\n\n### AgentCore\n\n[AWS Bedrock AgentCore](https:\u002F\u002Faws.amazon.com\u002Fbedrock\u002Fagentcore\u002F) provides cloud browser sessions with SigV4 authentication.\n\nTo enable AgentCore, use the `-p` flag:\n\n```bash\nagent-browser -p agentcore open https:\u002F\u002Fexample.com\n```\n\nOr use environment variables for CI\u002Fscripts:\n\n```bash\nexport AGENT_BROWSER_PROVIDER=agentcore\nagent-browser open https:\u002F\u002Fexample.com\n```\n\nCredentials are automatically resolved from environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`) or the AWS CLI (`aws configure export-credentials`), which supports SSO, profiles, and IAM roles.\n\nOptional configuration via environment variables:\n\n| Variable                   | Description                                                          | Default          |\n| -------------------------- | -------------------------------------------------------------------- | ---------------- |\n| `AGENTCORE_REGION`         | AWS region for the AgentCore endpoint                                | `us-east-1`      |\n| `AGENTCORE_BROWSER_ID`     | Browser identifier                                                   | `aws.browser.v1` |\n| `AGENTCORE_PROFILE_ID`     | Browser profile for persistent state (cookies, localStorage)         | (none)           |\n| `AGENTCORE_SESSION_TIMEOUT`| Session timeout in seconds                                           | `3600`           |\n| `AWS_PROFILE`              | AWS CLI profile for credential resolution                            | `default`        |\n\n**Browser profiles:** When `AGENTCORE_PROFILE_ID` is set, browser state (cookies, localStorage) is persisted across sessions automatically.\n\nWhen enabled, agent-browser connects to an AgentCore cloud browser session instead of launching a local browser. All commands work identically.\n\n## License\n\nApache-2.0\n","# agent-browser\n\n用于 AI 代理的浏览器自动化命令行工具。快速的原生 Rust 命令行工具。\n\n## 安装\n\n### 全局安装（推荐）\n\n安装原生 Rust 二进制文件：\n\n```bash\nnpm install -g agent-browser\nagent-browser install  # 从 Chrome for Testing 下载 Chrome（仅首次使用）\n```\n\n### 项目安装（本地依赖）\n\n适用于希望在 `package.json` 中固定版本的项目：\n\n```bash\nnpm install agent-browser\nagent-browser install\n```\n\n然后可以通过 `package.json` 脚本或直接调用 `agent-browser` 来使用。\n\n### Homebrew（macOS）\n\n```bash\nbrew install agent-browser\nagent-browser install  # 从 Chrome for Testing 下载 Chrome（仅首次使用）\n```\n\n### Cargo（Rust）\n\n```bash\ncargo install agent-browser\nagent-browser install  # 从 Chrome for Testing 下载 Chrome（仅首次使用）\n```\n\n### 从源码安装\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\ncd agent-browser\npnpm install\npnpm build\npnpm build:native   # 需要 Rust (https:\u002F\u002Frustup.rs)\npnpm link --global  # 使 agent-browser 在全局可用\nagent-browser install\n```\n\n### Linux 依赖\n\n在 Linux 上，安装系统依赖：\n\n```bash\nagent-browser install --with-deps\n```\n\n### 更新\n\n升级到最新版本：\n\n```bash\nagent-browser upgrade\n```\n\n它会自动检测您的安装方式（npm、Homebrew 或 Cargo），并运行相应的更新命令。\n\n### 要求\n\n- **Chrome** - 运行 `agent-browser install` 以从 [Chrome for Testing](https:\u002F\u002Fdeveloper.chrome.com\u002Fblog\u002Fchrome-for-testing\u002F)（Google 的官方自动化渠道）下载 Chrome。现有的 Chrome、Brave、Playwright 和 Puppeteer 安装会被自动检测到。守护进程不需要 Playwright 或 Node.js。\n- **Rust** - 仅在从源码构建时需要（参见上方的“从源码安装”部分）。\n\n## 快速入门\n\n```bash\nagent-browser open example.com\nagent-browser snapshot                    # 获取带有引用的无障碍树\nagent-browser click @e2                   # 根据快照中的引用点击\nagent-browser fill @e3 \"test@example.com\" # 根据引用填充\nagent-browser get text @e1                # 根据引用获取文本\nagent-browser screenshot page.png\nagent-browser close\n```\n\n### 传统选择器（也支持）\n\n```bash\nagent-browser click \"#submit\"\nagent-browser fill \"#email\" \"test@example.com\"\nagent-browser find role button click --name \"Submit\"\n```\n\n## 命令\n\n### 核心命令\n\n```bash\nagent-browser open \u003Curl>              # 导航到 URL（别名：goto、navigate）\nagent-browser click \u003Csel>             # 点击元素（--new-tab 可在新标签页中打开）\nagent-browser dblclick \u003Csel>          # 双击元素\nagent-browser focus \u003Csel>             # 将焦点设置到元素\nagent-browser type \u003Csel> \u003Ctext>       # 向元素输入文本\nagent-browser fill \u003Csel> \u003Ctext>       # 清空并填充\nagent-browser press \u003Ckey>             # 按下按键（Enter、Tab、Control+a）（别名：key）\nagent-browser keyboard type \u003Ctext>    # 使用真实按键输入文本（无需选择器，作用于当前焦点）\nagent-browser keyboard inserttext \u003Ctext>  # 插入文本而不触发按键事件（无需选择器）\nagent-browser keydown \u003Ckey>           # 按住按键\nagent-browser keyup \u003Ckey>             # 释放按键\nagent-browser hover \u003Csel>             # 将鼠标悬停在元素上\nagent-browser select \u003Csel> \u003Cval>      # 选择下拉菜单选项\nagent-browser check \u003Csel>             # 勾选复选框\nagent-browser uncheck \u003Csel>           # 取消勾选复选框\nagent-browser scroll \u003Cdir> [px]       # 滚动页面（向上\u002F向下\u002F向左\u002F向右，--selector \u003Csel>）\nagent-browser scrollintoview \u003Csel>    # 将元素滚动到视图中（别名：scrollinto）\nagent-browser drag \u003Csrc> \u003Ctgt>        # 拖放\nagent-browser upload \u003Csel> \u003Cfiles>    # 上传文件\nagent-browser screenshot [path]       # 截取屏幕截图（--full 可截取整页，若未指定路径则保存到临时目录）\nagent-browser screenshot --annotate   # 带有编号元素标签的标注截图\nagent-browser screenshot --screenshot-dir .\u002Fshots    # 保存到自定义目录\nagent-browser screenshot --screenshot-format jpeg --screenshot-quality 80\nagent-browser pdf \u003Cpath>              # 保存为 PDF\nagent-browser snapshot                # 带有引用的无障碍树（最适合 AI 使用）\nagent-browser eval \u003Cjs>               # 执行 JavaScript（-b 表示 base64 编码，--stdin 表示通过管道输入）\nagent-browser connect \u003Cport>          # 通过 CDP 连接到浏览器\nagent-browser stream enable [--port \u003Cport>]  # 启动运行时 WebSocket 流媒体\nagent-browser stream status           # 显示运行时流媒体状态和绑定端口\nagent-browser stream disable          # 停止运行时 WebSocket 流媒体\nagent-browser close                   # 关闭浏览器（别名：quit、exit）\nagent-browser close --all             # 关闭所有活动会话\nagent-browser chat \"\u003Cinstruction>\"    # AI 聊天：自然语言浏览器控制（一次性操作）\nagent-browser chat                    # AI 聊天：交互式 REPL 模式\n```\n\n### 获取信息\n\n```bash\nagent-browser get text \u003Csel>          # 获取文本内容\nagent-browser get html \u003Csel>          # 获取 innerHTML\nagent-browser get value \u003Csel>         # 获取输入值\nagent-browser get attr \u003Csel> \u003Cattr>   # 获取属性\nagent-browser get title               # 获取页面标题\nagent-browser get url                 # 获取当前 URL\nagent-browser get cdp-url             # 获取 CDP WebSocket URL（用于 DevTools、调试）\nagent-browser get count \u003Csel>         # 统计匹配元素的数量\nagent-browser get box \u003Csel>           # 获取边界框\nagent-browser get styles \u003Csel>        # 获取计算后的样式\n```\n\n### 检查状态\n\n```bash\nagent-browser is visible \u003Csel>        # 检查是否可见\nagent-browser is enabled \u003Csel>        # 检查是否启用\nagent-browser is checked \u003Csel>        # 检查是否被勾选\n```\n\n### 查找元素（语义定位器）\n\n```bash\nagent-browser find role \u003Crole> \u003Caction> [value]       # 按 ARIA 角色查找\nagent-browser find text \u003Ctext> \u003Caction>               # 按文本内容查找\nagent-browser find label \u003Clabel> \u003Caction> [value]     # 按标签查找\nagent-browser find placeholder \u003Cph> \u003Caction> [value]  # 按占位符查找\nagent-browser find alt \u003Ctext> \u003Caction>                # 按替代文本查找\nagent-browser find title \u003Ctext> \u003Caction>              # 按 title 属性查找\nagent-browser find testid \u003Cid> \u003Caction> [value]       # 按 data-testid 查找\nagent-browser find first \u003Csel> \u003Caction> [value]       # 查找第一个匹配项\nagent-browser find last \u003Csel> \u003Caction> [value]        # 查找最后一个匹配项\nagent-browser find nth \u003Cn> \u003Csel> \u003Caction> [value]     # 查找第 n 个匹配项\n```\n\n**动作：** `click`、`fill`、`type`、`hover`、`focus`、`check`、`uncheck`、`text`\n\n**选项：** `--name \u003Cname>`（按可访问名称筛选角色）、`--exact`（要求完全匹配文本）\n\n**示例：**\n\n```bash\nagent-browser find role button click --name \"Submit\"\nagent-browser find text \"Sign In\" click\nagent-browser find label \"Email\" fill \"test@test.com\"\nagent-browser find first \".item\" click\nagent-browser find nth 2 \"a\" text\n```\n\n### 等待\n\n```bash\nagent-browser wait \u003Cselector>         # 等待元素可见\nagent-browser wait \u003Cms>               # 等待指定时间（毫秒）\nagent-browser wait --text \"Welcome\"   # 等待文本出现（子字符串匹配）\nagent-browser wait --url \"**\u002Fdash\"    # 等待 URL 模式匹配\nagent-browser wait --load networkidle # 等待页面加载状态\nagent-browser wait --fn \"window.ready === true\"  # 等待 JavaScript 条件满足\n\n# 等待文本或元素消失\nagent-browser wait --fn \"!document.body.innerText.includes('Loading...')\"\nagent-browser wait \"#spinner\" --state hidden\n```\n\n**加载状态：** `load`、`domcontentloaded`、`networkidle`\n\n### 批量执行\n\n在一次调用中执行多个命令。命令可以作为带引号的参数传递，也可以通过标准输入以 JSON 格式管道传输。这样可以在运行多步骤工作流时避免每次执行命令时启动进程的开销。\n\n```bash\n# 参数模式：每个带引号的参数代表一个完整命令\nagent-browser batch \"open https:\u002F\u002Fexample.com\" \"snapshot -i\" \"screenshot\"\n\n# 使用 --bail 在遇到第一个错误时停止\nagent-browser batch --bail \"open https:\u002F\u002Fexample.com\" \"click @e1\" \"screenshot\"\n\n# 标准输入模式：将命令以 JSON 格式管道传输\necho '[\n  [\"open\", \"https:\u002F\u002Fexample.com\"],\n  [\"snapshot\", \"-i\"],\n  [\"click\", \"@e1\"],\n  [\"screenshot\", \"result.png\"]\n]' | agent-browser batch --json\n```\n\n### 剪贴板\n\n```bash\nagent-browser clipboard read                      # 从剪贴板读取文本\nagent-browser clipboard write \"Hello, World!\"     # 将文本写入剪贴板\nagent-browser clipboard copy                      # 复制当前选中内容（Ctrl+C）\nagent-browser clipboard paste                     # 从剪贴板粘贴内容（Ctrl+V）\n```\n\n### 鼠标控制\n\n```bash\nagent-browser mouse move \u003Cx> \u003Cy>      # 移动鼠标\nagent-browser mouse down [button]     # 按下鼠标按钮（左\u002F右\u002F中）\nagent-browser mouse up [button]       # 释放鼠标按钮\nagent-browser mouse wheel \u003Cdy> [dx]   # 滚动鼠标滚轮\n```\n\n### 浏览器设置\n\n```bash\nagent-browser set viewport \u003Cw> \u003Ch> [scale]  # 设置视口大小（scale 用于 Retina 显示屏，例如 2）\nagent-browser set device \u003Cname>       # 模拟设备（“iPhone 14”）\nagent-browser set geo \u003Clat> \u003Clng>     # 设置地理位置\nagent-browser set offline [on|off]    # 切换离线模式\nagent-browser set headers \u003Cjson>      # 添加额外的 HTTP 头\nagent-browser set credentials \u003Cu> \u003Cp> # 设置 HTTP 基本认证\nagent-browser set media [dark|light]  # 模拟颜色方案\n```\n\n### Cookie 和存储\n\n```bash\nagent-browser cookies                 # 获取所有 Cookie\nagent-browser cookies set \u003Cname> \u003Cval> # 设置 Cookie\nagent-browser cookies clear           # 清除所有 Cookie\n\nagent-browser storage local           # 获取所有 localStorage 数据\nagent-browser storage local \u003Ckey>     # 获取特定键的值\nagent-browser storage local set \u003Ck> \u003Cv>  # 设置值\nagent-browser storage local clear     # 清空所有数据\n\nagent-browser storage session         # 对 sessionStorage 的操作类似\n```\n\n### 网络\n\n```bash\nagent-browser network route \u003Curl>              # 拦截请求\nagent-browser network route \u003Curl> --abort      # 阻止请求\nagent-browser network route \u003Curl> --body \u003Cjson>  # 模拟响应\nagent-browser network unroute [url]            # 移除路由规则\nagent-browser network requests                 # 查看跟踪的请求\nagent-browser network requests --filter api    # 过滤 API 请求\nagent-browser network requests --type xhr,fetch  # 按资源类型过滤\nagent-browser network requests --method POST   # 按 HTTP 方法过滤\nagent-browser network requests --status 2xx    # 按状态码过滤（200、2xx、400-499）\nagent-browser network request \u003CrequestId>      # 查看完整的请求\u002F响应详情\nagent-browser network har start                # 开始记录 HAR 日志\nagent-browser network har stop [output.har]    # 停止并保存 HAR 日志（未指定路径时使用临时路径）\n```\n\n### 标签页和窗口\n\n```bash\nagent-browser tab                     # 列出所有标签页\nagent-browser tab new [url]           # 新建标签页（可选指定 URL）\nagent-browser tab \u003Cn>                 # 切换到第 n 个标签页\nagent-browser tab close [n]           # 关闭标签页\nagent-browser window new              # 新建窗口\n```\n\n### 框架\n\n```bash\nagent-browser frame \u003Csel>             # 切换到 iframe\nagent-browser frame main              # 返回主框架\n```\n\n### 对话框\n\n```bash\nagent-browser dialog accept [text]    # 接受对话框（可选提示文本）\nagent-browser dialog dismiss          # 关闭对话框\nagent-browser dialog status           # 检查是否有对话框正在打开\n```\n\n默认情况下，`alert` 和 `beforeunload` 对话框会自动被接受，因此不会阻塞代理程序。而 `confirm` 和 `prompt` 对话框仍需显式处理。可以使用 `--no-auto-dialog`（或设置 `AGENT_BROWSER_NO_AUTO_DIALOG=1`）来禁用自动处理功能。\n\n当有 JavaScript 对话框待处理时，所有命令响应都会包含一个 `warning` 字段，其中显示对话框的类型和消息。\n\n### 差异比较\n\n```bash\nagent-browser diff snapshot                              # 比较当前快照与上次快照\nagent-browser diff snapshot --baseline before.txt        # 比较当前快照与保存的基准文件\nagent-browser diff snapshot --selector \"#main\" --compact # 局部快照差异\nagent-browser diff screenshot --baseline before.png      # 与基准图像的像素级视觉差异\nagent-browser diff screenshot --baseline b.png -o d.png  # 将差异图像保存到自定义路径\nagent-browser diff screenshot --baseline b.png -t 0.2    # 调整颜色阈值（0-1）\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com     # 比较两个 URL 的快照差异\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com --screenshot  # 同时进行视觉差异比较\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com --wait-until networkidle  # 自定义等待策略\nagent-browser diff url https:\u002F\u002Fv1.com https:\u002F\u002Fv2.com --selector \"#main\"  # 限定到特定元素\n```\n\n### 调试\n\n```bash\nagent-browser trace start [路径]      # 开始记录跟踪信息\nagent-browser trace stop [路径]       # 停止并保存跟踪信息\nagent-browser profiler start          # 开始 Chrome DevTools 性能分析\nagent-browser profiler stop [路径]    # 停止并保存性能分析文件 (.json)\nagent-browser console                 # 查看控制台消息（日志、错误、警告、信息）\nagent-browser console --json          # 以 JSON 格式输出原始 CDP 参数，便于程序化访问\nagent-browser console --clear         # 清空控制台\nagent-browser errors                  # 查看页面错误（未捕获的 JavaScript 异常）\nagent-browser errors --clear          # 清除错误\nagent-browser highlight \u003C选择器>     # 高亮显示元素\nagent-browser inspect                 # 打开当前页面的 Chrome DevTools\nagent-browser state save \u003C路径>       # 保存认证状态\nagent-browser state load \u003C路径>       # 加载认证状态\nagent-browser state list              # 列出已保存的状态文件\nagent-browser state show \u003C文件>       # 显示状态摘要\nagent-browser state rename \u003C旧名> \u003C新名> # 重命名状态文件\nagent-browser state clear [名称]      # 清除指定会话的状态\nagent-browser state clear --all       # 清除所有已保存的状态\nagent-browser state clean --older-than \u003C天数>  # 删除过期的状态\n```\n\n### 导航\n\n```bash\nagent-browser back                    # 后退\nagent-browser forward                 # 前进\nagent-browser reload                  # 重新加载页面\n```\n\n### 设置\n\n```bash\nagent-browser install                 # 从 Chrome for Testing（Google 官方自动化渠道）下载 Chrome 浏览器\nagent-browser install --with-deps     # 同时安装系统依赖项（Linux）\nagent-browser upgrade                 # 将 agent-browser 升级到最新版本\n```\n\n## 认证\n\nagent-browser 提供多种方式来持久化登录会话，从而避免每次运行时都重新认证。\n\n### 快速总结\n\n| 方法 | 适用场景 | 标志\u002F环境变量 |\n|----------|----------|------------|\n| **复用 Chrome 配置文件** | 复用您现有的 Chrome 登录状态（Cookie、会话），无需任何设置 | `--profile \u003C名称>` \u002F `AGENT_BROWSER_PROFILE` |\n| **持久化配置文件** | 在浏览器重启后仍保留完整状态（Cookie、IndexedDB、Service Worker、缓存） | `--profile \u003C路径>` \u002F `AGENT_BROWSER_PROFILE` |\n| **会话持久化** | 按名称自动保存和恢复 Cookie 和 localStorage | `--session-name \u003C名称>` \u002F `AGENT_BROWSER_SESSION_NAME` |\n| **从您的浏览器导入** | 直接从已登录的 Chrome 会话中获取认证信息 | `--auto-connect` + `state save` |\n| **状态文件** | 在启动时加载之前保存的状态 JSON 文件 | `--state \u003C路径>` \u002F `AGENT_BROWSER_STATE` |\n| **认证保险库** | 在本地加密存储凭据，并通过名称登录 | `auth save` \u002F `auth login` |\n\n### 从您的浏览器导入认证信息\n\n如果您已经在 Chrome 中登录了某个网站，可以直接提取该认证状态并重复使用：\n\n```bash\n# 1. 启动启用远程调试功能的 Chrome 浏览器\n#    macOS:\n\"\u002FApplications\u002FGoogle Chrome.app\u002FContents\u002FMacOS\u002FGoogle Chrome\" --remote-debugging-port=9222\n#    或者使用 --auto-connect 自动发现正在运行的 Chrome 浏览器\n\n# 2. 连接并保存认证状态\nagent-browser --auto-connect state save .\u002Fmy-auth.json\n\n# 3. 在未来的会话中使用保存的认证信息\nagent-browser --state .\u002Fmy-auth.json open https:\u002F\u002Fapp.example.com\u002Fdashboard\n\n# 4. 或者使用 --session-name 实现自动持久化\nagent-browser --session-name myapp state load .\u002Fmy-auth.json\n# 从此以后，--session-name myapp 会自动保存和恢复此状态\n```\n\n> **安全提示：**\n> - `--remote-debugging-port` 会在本地主机上暴露完整的浏览器控制权限。任何本地进程都可以连接。请仅在受信任的机器上使用，并在完成后关闭 Chrome。\n> - 状态文件以明文形式存储会话令牌。请将其添加到 `.gitignore` 文件中，并在不再需要时删除。如需静态加密，请设置 `AGENT_BROWSER_ENCRYPTION_KEY`（参见 [状态加密](#状态加密)）。\n\n有关登录流程、OAuth、双因素认证、基于 Cookie 的认证以及认证保险库的详细信息，请参阅 [认证](docs\u002Fsrc\u002Fapp\u002Fsessions\u002Fpage.mdx) 文档。\n\n## 会话\n\n运行多个隔离的浏览器实例：\n\n```bash\n# 不同的会话\nagent-browser --session agent1 open site-a.com\nagent-browser --session agent2 open site-b.com\n\n# 或通过环境变量\nAGENT_BROWSER_SESSION=agent1 agent-browser click \"#btn\"\n\n# 列出活动会话\nagent-browser session list\n# 输出：\n# 活动会话：\n# -> default\n#    agent1\n\n# 显示当前会话\nagent-browser session\n```\n\n每个会话都有自己的：\n\n- 浏览器实例\n- Cookie 和存储\n- 导航历史\n- 认证状态\n\n## 复用 Chrome 配置文件\n\n最快捷地使用现有登录状态的方法是将 Chrome 配置文件名称传递给 `--profile`：\n\n```bash\n# 列出可用的 Chrome 配置文件\nagent-browser profiles\n\n# 复用默认 Chrome 配置文件的登录状态\nagent-browser --profile Default open https:\u002F\u002Fgmail.com\n\n# 使用命名配置文件（按显示名称或目录名称）\nagent-browser --profile \"Work\" open https:\u002F\u002Fapp.example.com\n\n# 或通过环境变量\nAGENT_BROWSER_PROFILE=Default agent-browser open https:\u002F\u002Fgmail.com\n```\n\n此操作会将您的 Chrome 配置文件复制到一个临时目录中（只读快照，不会修改原始配置文件），从而使浏览器在启动时带有您现有的 Cookie 和会话。\n\n> **注意：** 在 Windows 系统上，如果 Chrome 正在运行，请先关闭后再使用 `--profile \u003C名称>`，因为某些配置文件可能被锁定。\n\n## 持久化配置文件\n\n若需创建一个持久化的自定义配置文件目录，在浏览器重启后仍能保留状态，可将路径传递给 `--profile`：\n\n```bash\n# 使用持久化配置文件目录\nagent-browser --profile ~\u002F.myapp-profile open myapp.com\n\n# 登录一次后即可重复使用该认证会话\nagent-browser --profile ~\u002F.myapp-profile open myapp.com\u002Fdashboard\n\n# 或通过环境变量\nAGENT_BROWSER_PROFILE=~\u002F.myapp-profile agent-browser open myapp.com\n```\n\n该配置文件目录会存储：\n\n- Cookie 和 localStorage\n- IndexedDB 数据\n- Service Worker\n- 浏览器缓存\n- 登录会话\n\n**提示**：为不同项目使用不同的配置文件路径，以保持它们的浏览器状态相互隔离。\n\n## 会话持久化\n\n或者，可以使用 `--session-name` 来自动保存和恢复 Cookie 以及 localStorage，即使浏览器重启也能保持状态：\n\n```bash\n# 自动保存\u002F加载“twitter”会话的状态\nagent-browser --session-name twitter open twitter.com\n\n# 登录一次后，状态将自动持久化\n# 状态文件存储在 ~\u002F.agent-browser\u002Fsessions\u002F\n\n# 或通过环境变量\nexport AGENT_BROWSER_SESSION_NAME=twitter\nagent-browser open twitter.com\n```\n\n### 状态加密\n\n使用 AES-256-GCM 对保存的会话数据进行静态加密：\n\n```bash\n# 生成密钥：openssl rand -hex 32\nexport AGENT_BROWSER_ENCRYPTION_KEY=\u003C64位十六进制密钥>\n\n# 状态文件现在会自动加密\nagent-browser --session-name secure open example.com\n```\n\n| 变量                          | 描述                                        |\n| ----------------------------- | ------------------------------------------- |\n| `AGENT_BROWSER_SESSION_NAME`  | 自动保存\u002F加载状态的持久化名称              |\n| `AGENT_BROWSER_ENCRYPTION_KEY`    | 用于 AES-256-GCM 加密的 64 位十六进制密钥         |\n| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | 自动删除超过 N 天的状态（默认：30） |\n\n## 安全性\n\nagent-browser 包含用于安全部署 AI 代理的安全功能。所有功能均为可选——在您显式启用某项功能之前，现有工作流不会受到影响：\n\n- **认证保险库** —— 在本地存储凭据（始终加密），并通过名称引用。LLM 永远不会看到密码。`auth login` 命令会先加载凭据，然后等待登录表单选择器出现（适用于单页应用，超时时间遵循默认操作超时）。如果未设置 `AGENT_BROWSER_ENCRYPTION_KEY`，将在 `~\u002F.agent-browser\u002F.encryption-key` 自动生成密钥：`echo \"pass\" | agent-browser auth save github --url https:\u002F\u002Fgithub.com\u002Flogin --username user --password-stdin` 然后执行 `agent-browser auth login github`。\n- **内容边界标记** —— 将页面输出包裹在分隔符中，以便 LLM 能够区分工具输出与不可信内容：`--content-boundaries`。\n- **域名白名单** —— 限制导航仅限于受信任的域名（通配符如 `*.example.com` 也会匹配基础域名）：`--allowed-domains \"example.com,*.example.com\"`。对非允许域名的子资源请求（脚本、图片、fetch）以及 WebSocket\u002FEventSource 连接也会被阻止。请包含目标页面所依赖的所有 CDN 域名（例如 `*.cdn.example.com`）。\n- **动作策略** —— 使用静态策略文件控制破坏性动作：`--action-policy .\u002Fpolicy.json`。\n- **动作确认** —— 对敏感动作类别要求明确批准：`--confirm-actions eval,download`。\n- **输出长度限制** —— 防止上下文过载：`--max-output 50000`。\n\n| 变量                            | 描述                              |\n| ------------------------------- | --------------------------------- |\n| `AGENT_BROWSER_CONTENT_BOUNDARIES`  | 将页面输出包裹在边界标记中     |\n| `AGENT_BROWSER_MAX_OUTPUT`          | 页面输出的最大字符数           |\n| `AGENT_BROWSER_ALLOWED_DOMAINS`     | 逗号分隔的允许域名模式         |\n| `AGENT_BROWSER_ACTION_POLICY`       | 动作策略 JSON 文件路径         |\n| `AGENT_BROWSER_CONFIRM_ACTIONS`     | 需要确认的动作类别             |\n| `AGENT_BROWSER_CONFIRM_INTERACTIVE` | 启用交互式确认提示             |\n\n详细信息请参阅 [安全文档](https:\u002F\u002Fagent-browser.dev\u002Fsecurity)。\n\n## 快照选项\n\n`snapshot` 命令支持过滤以减少输出大小：\n\n```bash\nagent-browser snapshot                    # 完整的无障碍树\nagent-browser snapshot -i                 # 仅显示交互元素（按钮、输入框、链接）\nagent-browser snapshot -i --urls          # 显示带有链接 URL 的交互元素\nagent-browser snapshot -c                 # 紧凑模式（移除空的结构元素）\nagent-browser snapshot -d 3               # 限制深度为 3 层\nagent-browser snapshot -s \"#main\"         # 限定到 CSS 选择器范围\nagent-browser snapshot -i -c -d 5         # 组合使用多个选项\n```\n\n| 选项                 | 描述                                                             |\n| ---------------------- | ----------------------------------------------------------------------- |\n| `-i, --interactive`    | 仅显示交互元素（按钮、链接、输入框）                 |\n| `-u, --urls`           | 包含链接元素的 href URL                                     |\n| `-c, --compact`        | 移除空的结构元素                                        |\n| `-d, --depth \u003Cn>`      | 限制树的深度                                                        |\n| `-s, --selector \u003Csel>` | 限定到 CSS 选择器                                                   |\n\n## 带标注的截图\n\n`--annotate` 标志会在截图中的交互元素上叠加编号标签。每个标签 `[N]` 对应引用 `@eN`，因此相同的引用既可用于视觉工作流，也可用于基于文本的工作流。\n\n带标注的截图仅在基于 CDP 的浏览器路径（Chrome\u002FLightpanda）上受支持。Safari\u002FWebDriver 后端目前尚不支持 `--annotate`。\n\n```bash\nagent-browser screenshot --annotate\n# -> 截图已保存到 \u002Ftmp\u002Fscreenshot-2026-02-17T12-00-00-abc123.png\n#    [1] @e1 按钮“提交”\n#    [2] @e2 链接“首页”\n#    [3] @e3 文本框“邮箱”\n```\n\n生成带标注的截图后，引用会被缓存，您可以立即与元素交互：\n\n```bash\nagent-browser screenshot --annotate .\u002Fpage.png\nagent-browser click @e2     # 点击标有 [2] 的“首页”链接\n```\n\n这对于能够推理视觉布局、未标注的图标按钮、画布元素或文本无障碍树无法捕捉的视觉状态的多模态 AI 模型非常有用。\n\n## 选项\n\n| 选项 | 描述 |\n|--------|-------------|\n| `--session \u003Cname>` | 使用隔离会话（或 `AGENT_BROWSER_SESSION` 环境变量） |\n| `--session-name \u003Cname>` | 自动保存\u002F恢复会话状态（或 `AGENT_BROWSER_SESSION_NAME` 环境变量） |\n| `--profile \u003Cname\\|path>` | Chrome 配置文件名称或持久化目录路径（或 `AGENT_BROWSER_PROFILE` 环境变量） |\n| `--state \u003Cpath>` | 从 JSON 文件加载存储状态（或 `AGENT_BROWSER_STATE` 环境变量） |\n| `--headers \u003Cjson>` | 设置作用于 URL 源的 HTTP 头 |\n| `--executable-path \u003Cpath>` | 自定义浏览器可执行文件（或 `AGENT_BROWSER_EXECUTABLE_PATH` 环境变量） |\n| `--extension \u003Cpath>` | 加载浏览器扩展（可重复；或 `AGENT_BROWSER_EXTENSIONS` 环境变量） |\n| `--args \u003Cargs>` | 浏览器启动参数，以逗号或换行分隔（或 `AGENT_BROWSER_ARGS` 环境变量） |\n| `--user-agent \u003Cua>` | 自定义 User-Agent 字符串（或 `AGENT_BROWSER_USER_AGENT` 环境变量） |\n| `--proxy \u003Curl>` | 带有可选认证的代理服务器 URL（或 `AGENT_BROWSER_PROXY` 环境变量） |\n| `--proxy-bypass \u003Chosts>` | 绕过代理的主机列表（或 `AGENT_BROWSER_PROXY_BYPASS` 环境变量） |\n| `--ignore-https-errors` | 忽略 HTTPS 证书错误（适用于自签名证书） |\n| `--allow-file-access` | 允许 file:\u002F\u002F URL 访问本地文件（仅限 Chromium） |\n| `-p, --provider \u003Cname>` | 云浏览器提供商（或 `AGENT_BROWSER_PROVIDER` 环境变量） |\n| `--device \u003Cname>` | iOS 设备名称，例如“iPhone 15 Pro”（或 `AGENT_BROWSER_IOS_DEVICE` 环境变量） |\n| `--json` | JSON 格式输出（用于代理） |\n| `--annotate` | 带有序号元素标签的标注截图（或 `AGENT_BROWSER_ANNOTATE` 环境变量） |\n| `--screenshot-dir \u003Cpath>` | 默认截图输出目录（或 `AGENT_BROWSER_SCREENSHOT_DIR` 环境变量） |\n| `--screenshot-quality \u003Cn>` | JPEG 质量，范围 0–100（或 `AGENT_BROWSER_SCREENSHOT_QUALITY` 环境变量） |\n| `--screenshot-format \u003Cfmt>` | 截图格式：`png`、`jpeg`（或 `AGENT_BROWSER_SCREENSHOT_FORMAT` 环境变量） |\n| `--headed` | 显示浏览器窗口（非无头模式）（或 `AGENT_BROWSER_HEADED` 环境变量） |\n| `--cdp \u003Cport\\|url>` | 通过 Chrome 开发者工具协议连接（端口或 WebSocket URL） |\n| `--auto-connect` | 自动发现并连接到正在运行的 Chrome 浏览器（或 `AGENT_BROWSER_AUTO_CONNECT` 环境变量） |\n| `--color-scheme \u003Cscheme>` | 颜色方案：`dark`、`light`、`no-preference`（或 `AGENT_BROWSER_COLOR_SCHEME` 环境变量） |\n| `--download-path \u003Cpath>` | 默认下载目录（或 `AGENT_BROWSER_DOWNLOAD_PATH` 环境变量） |\n| `--content-boundaries` | 用边界标记包裹页面内容，以确保 LLM 安全（或 `AGENT_BROWSER_CONTENT_BOUNDARIES` 环境变量） |\n| `--max-output \u003Cchars>` | 将页面内容截断至 N 个字符（或 `AGENT_BROWSER_MAX_OUTPUT` 环境变量） |\n| `--allowed-domains \u003Clist>` | 逗号分隔的允许域名模式（或 `AGENT_BROWSER_ALLOWED_DOMAINS` 环境变量） |\n| `--action-policy \u003Cpath>` | 动作策略 JSON 文件路径（或 `AGENT_BROWSER_ACTION_POLICY` 环境变量） |\n| `--confirm-actions \u003Clist>` | 需要确认的动作类别（或 `AGENT_BROWSER_CONFIRM_ACTIONS` 环境变量） |\n| `--confirm-interactive` | 交互式确认提示；若标准输入不是 TTY，则自动拒绝（或 `AGENT_BROWSER_CONFIRM_INTERACTIVE` 环境变量） |\n| `--engine \u003Cname>` | 浏览器引擎：`chrome`（默认）、`lightpanda`（或 `AGENT_BROWSER_ENGINE` 环境变量） |\n| `--no-auto-dialog` | 禁用自动关闭 `alert`\u002F`beforeunload` 对话框（或 `AGENT_BROWSER_NO_AUTO_DIALOG` 环境变量） |\n| `--model \u003Cname>` | 用于聊天命令的 AI 模型（或 `AI_GATEWAY_MODEL` 环境变量） |\n| `-v`, `--verbose` | 显示工具命令及其原始输出（聊天） |\n| `-q`, `--quiet` | 仅显示 AI 文本回复，隐藏工具调用（聊天） |\n| `--config \u003Cpath>` | 使用自定义配置文件（或 `AGENT_BROWSER_CONFIG` 环境变量） |\n| `--debug` | 调试输出 |\n\n## 可观测性仪表板\n\n使用本地 Web 仪表板实时监控 agent-browser 会话，该仪表板显示实时视口和命令活动信息流。\n\n```bash\n# 启动仪表板服务器（在后台端口 4848 上运行）\nagent-browser dashboard start\nagent-browser dashboard start --port 8080   # 自定义端口\n\n# 所有会话都会自动显示在仪表板上\nagent-browser open example.com\n\n# 停止仪表板\nagent-browser dashboard stop\n```\n\n仪表板作为一个独立的后台进程在端口 4848 上运行，与浏览器会话无关。即使没有会话运行，它仍然可用。所有会话会自动流式传输到仪表板。\n\n仪表板显示：\n- **实时视口** -- 来自浏览器的实时 JPEG 帧\n- **活动信息流** -- 按时间顺序排列的命令\u002F结果流，包含时间戳和可展开的详细信息\n- **控制台输出** -- 浏览器控制台消息（log、warn、error）\n- **会话创建** -- 可通过 UI 创建新会话，支持本地引擎（Chrome、Lightpanda）或云提供商（AgentCore、Browserbase、Browserless、Browser Use、Kernel）\n- **AI 聊天** -- 直接在仪表板中与 AI 助手聊天（需配置 Vercel AI Gateway）\n\n### AI 聊天\n\n仪表板包含一个可选的 AI 聊天面板，由 Vercel AI Gateway 提供支持。相同的功能也可通过 CLI 中的 `chat` 命令直接使用。设置以下环境变量以启用 AI 聊天：\n\n```bash\nexport AI_GATEWAY_API_KEY=gw_your_key_here\nexport AI_GATEWAY_MODEL=anthropic\u002Fclaude-sonnet-4.6           # 可选，默认为该值\nexport AI_GATEWAY_URL=https:\u002F\u002Fai-gateway.vercel.sh           # 可选，默认为该值\n```\n\n**CLI 使用方法：**\n\n```bash\nagent-browser chat \"打开 google.com 并搜索猫\"     # 单次指令\nagent-browser chat                                           # 交互式 REPL\nagent-browser -q chat \"总结此页面\"                  # 静默模式（仅文本）\nagent-browser -v chat \"填写登录表单\"               # 详细模式（显示命令输出）\nagent-browser --model openai\u002Fgpt-4o chat \"拍摄截图\" # 替换模型\n```\n\n`chat` 命令会将自然语言指令转换为 agent-browser 命令，执行这些命令，并流式传输 AI 回复。在交互模式下，输入 `quit` 即可退出。使用 `--json` 可获得适合代理消费的结构化输出。\n\n**仪表板使用方法：**\n\n聊天选项卡始终在仪表板上可见。当设置了 `AI_GATEWAY_API_KEY` 时，Rust 服务器会将请求代理到网关，并使用 Vercel AI SDK 的 UI 消息流协议将响应流式传输回来。如果没有设置密钥，发送消息时会直接显示错误。\n\n## 配置\n\n创建一个 `agent-browser.json` 文件来设置持久的默认值，而不是在每个命令中重复指定标志。\n\n**配置文件加载顺序（优先级从低到高）：**\n\n1. `~\u002F.agent-browser\u002Fconfig.json` -- 用户级默认值\n2. `.\u002Fagent-browser.json` -- 项目级覆盖配置（位于工作目录）\n3. `AGENT_BROWSER_*` 环境变量会覆盖配置文件中的值\n4. CLI 标志会覆盖所有其他设置\n\n**`agent-browser.json` 示例：**\n\n```json\n{\n  \"headed\": true,\n  \"proxy\": \"http:\u002F\u002Flocalhost:8080\",\n  \"profile\": \".\u002Fbrowser-data\",\n  \"userAgent\": \"my-agent\u002F1.0\",\n  \"ignoreHttpsErrors\": true\n}\n```\n\n使用 `--config \u003Cpath>` 或 `AGENT_BROWSER_CONFIG` 来加载特定的配置文件，而不是默认的配置：\n\n```bash\nagent-browser --config .\u002Fci-config.json open example.com\nAGENT_BROWSER_CONFIG=.\u002Fci-config.json agent-browser open example.com\n```\n\n上表中的所有选项都可以在配置文件中以驼峰命名法的键来设置（例如，`--executable-path` 变为 `\"executablePath\"`，`--proxy-bypass` 变为 `\"proxyBypass\"`）。未知的键会被忽略，以确保向前兼容性。\n\n布尔类型的标志可以接受可选的 `true`\u002F`false` 值来覆盖配置文件中的设置。例如，`--headed false` 会禁用配置文件中的 `\"headed\": true`。单独使用 `--headed` 相当于 `--headed true`。\n\n自动发现的配置文件如果不存在，则会被静默忽略。如果 `--config \u003Cpath>` 指向一个不存在或无效的文件，`agent-browser` 将退出并显示错误信息。用户和项目配置中的扩展部分会被合并（串联），而不是替换。\n\n> **提示：** 如果你的项目级 `agent-browser.json` 包含环境相关的值（路径、代理等），建议将其添加到 `.gitignore` 中。\n\n## 默认超时时间\n\n标准操作（点击、等待、填写等）的默认超时时间为 25 秒。这个值特意低于 CLI 的 30 秒 IPC 读取超时，以便守护进程能够返回正确的错误信息，而不是让 CLI 因 EAGAIN 超时而中断。\n\n可以通过环境变量覆盖默认超时时间：\n\n```bash\n# 为慢速页面设置更长的超时时间（单位：毫秒）\nexport AGENT_BROWSER_DEFAULT_TIMEOUT=45000\n```\n\n> **注意：** 如果将此值设置为超过 30000 毫秒（30 秒），可能会导致在执行缓慢操作时出现 EAGAIN 错误，因为 CLI 的读取超时会在守护进程响应之前到期。CLI 会自动重试临时性错误，但响应时间会增加。\n\n| 变量                        | 描述                              |\n| ------------------------------- | ---------------------------------------- |\n| `AGENT_BROWSER_DEFAULT_TIMEOUT` | 默认操作超时时间，单位为毫秒（默认：25000） |\n\n## 选择器\n\n### 引用（推荐用于 AI）\n\n引用可以从快照中提供确定性的元素选择：\n\n```bash\n# 1. 获取包含引用的快照\nagent-browser snapshot\n# 输出：\n# - 标题“Example Domain” [ref=e1] [level=1]\n# - 按钮“Submit” [ref=e2]\n# - 文本框“Email” [ref=e3]\n# - 链接“Learn more” [ref=e4]\n\n# 2. 使用引用进行交互\nagent-browser click @e2                   # 点击按钮\nagent-browser fill @e3 \"test@example.com\" # 填写文本框\nagent-browser get text @e1                # 获取标题文本\nagent-browser hover @e4                   # 鼠标悬停链接\n```\n\n**为什么使用引用？**\n\n- **确定性**：引用指向快照中的确切元素\n- **快速**：无需重新查询 DOM\n- **适合 AI**：快照加引用的工作流对大型语言模型来说是最优的\n\n### CSS 选择器\n\n```bash\nagent-browser click \"#id\"\nagent-browser click \".class\"\nagent-browser click \"div > button\"\n```\n\n### 文本与 XPath\n\n```bash\nagent-browser click \"text=Submit\"\nagent-browser click \"xpath=\u002F\u002Fbutton\"\n```\n\n### 语义定位器\n\n```bash\nagent-browser find role button click --name \"Submit\"\nagent-browser find label \"Email\" fill \"test@test.com\"\n```\n\n## 代理模式\n\n使用 `--json` 以获得机器可读的输出：\n\n```bash\nagent-browser snapshot --json\n# 返回：{\"success\":true,\"data\":{\"snapshot\":\"...\",\"refs\":{\"e1\":{\"role\":\"heading\",\"name\":\"Title\"},...}}}\n\nagent-browser get text @e1 --json\nagent-browser is visible @e2 --json\n```\n\n### 最优的 AI 工作流程\n\n```bash\n# 1. 导航并获取快照\nagent-browser open example.com\nagent-browser snapshot -i --json   # AI 解析树结构和引用\n\n# 2. AI 从快照中识别目标引用\n# 3. 使用引用执行操作\nagent-browser click @e2\nagent-browser fill @e3 \"input text\"\n\n# 4. 如果页面发生变化，再次获取快照\nagent-browser snapshot -i --json\n```\n\n### 命令链式调用\n\n可以在单个 shell 调用中使用 `&&` 将多个命令串联起来。浏览器通过后台守护进程保持运行状态，因此链式调用既安全又高效：\n\n```bash\n# 一次调用即可打开页面、等待加载完成并生成快照\nagent-browser open example.com && agent-browser wait --load networkidle && agent-browser snapshot -i\n\n# 链式执行多个交互操作\nagent-browser fill @e1 \"user@example.com\" && agent-browser fill @e2 \"pass\" && agent-browser click @e3\n\n# 导航并截屏\nagent-browser open example.com && agent-browser wait --load networkidle && agent-browser screenshot page.png\n```\n\n当你不需要中间输出时，可以使用 `&&`。如果你需要先解析输出（例如，通过快照发现引用后再进行交互），则应分别运行各个命令。\n\n## 带界面模式\n\n显示浏览器窗口以便调试：\n\n```bash\nagent-browser open example.com --headed\n```\n\n这将打开一个可见的浏览器窗口，而不是以无头模式运行。\n\n> **注意：** 浏览器扩展程序在带界面和无头模式下均可正常工作（Chrome 的 `--headless=new`）。\n\n## 已认证的会话\n\n使用 `--headers` 可以为特定的源设置 HTTP 头部，从而实现无需登录流程的认证：\n\n```bash\n# 头部仅适用于 api.example.com\nagent-browser open api.example.com --headers '{\"Authorization\": \"Bearer \u003Ctoken>\"}'\n\n# 对 api.example.com 的请求会包含认证头部\nagent-browser snapshot -i --json\nagent-browser click @e2\n\n# 导航到另一个域名 - 不会发送这些头部（安全性更高！）\nagent-browser open other-site.com\n```\n\n这在以下场景中非常有用：\n\n- **跳过登录流程**：通过 HTTP 头部直接认证，无需通过 UI 登录\n- **切换用户**：使用不同的认证令牌启动新的会话\n- **API 测试**：直接访问受保护的端点\n- **安全性**：头部仅限于特定的源，不会泄露到其他域\n\n如果需要为多个源设置头部，可以在每次 `open` 命令中使用 `--headers`：\n\n```bash\nagent-browser open api.example.com --headers '{\"Authorization\": \"Bearer token1\"}'\nagent-browser open api.acme.com --headers '{\"Authorization\": \"Bearer token2\"}'\n```\n\n如果需要为所有域设置全局头部，可以使用 `set headers`：\n\n```bash\nagent-browser set headers '{\"X-Custom-Header\": \"value\"}'\n```\n\n## 自定义浏览器可执行文件\n\n使用自定义的浏览器可执行文件代替内置的 Chromium。这在以下情况下很有用：\n\n- **无服务器部署**：使用轻量级的 Chromium 构建，如 `@sparticuz\u002Fchromium`（约 50MB，而原版约为 684MB）\n- **系统浏览器**：使用已安装的 Chrome\u002FChromium\n- **定制构建**：使用经过修改的浏览器版本\n\n### CLI 使用方法\n\n```bash\nagent-browser --executable \u002Fpath\u002Fto\u002Fcustom-chromium open example.com\n```\n\n请注意，使用自定义浏览器可执行文件可能会影响某些功能的兼容性，因此请确保所选的浏览器版本与工具兼容。\n\n# 通过标志位\nagent-browser --executable-path \u002Fpath\u002Fto\u002Fchromium open example.com\n\n# 通过环境变量\nAGENT_BROWSER_EXECUTABLE_PATH=\u002Fpath\u002Fto\u002Fchromium agent-browser open example.com\n```\n\n### 无服务器（Vercel）\n\n在临时的 Vercel Sandbox 微型虚拟机中运行 agent-browser + Chrome。无需外部服务器：\n\n```typescript\nimport { Sandbox } from \"@vercel\u002Fsandbox\";\n\nconst sandbox = await Sandbox.create({ runtime: \"node24\" });\nawait sandbox.runCommand(\"agent-browser\", [\"open\", \"https:\u002F\u002Fexample.com\"]);\nconst result = await sandbox.runCommand(\"agent-browser\", [\"screenshot\", \"--json\"]);\nawait sandbox.stop();\n```\n\n请参阅 [environments 示例](examples\u002Fenvironments\u002F) 以获取带有 UI 和部署到 Vercel 按钮的可运行演示。\n\n### 无服务器（AWS Lambda）\n\n```typescript\nimport chromium from '@sparticuz\u002Fchromium';\nimport { execSync } from 'child_process';\n\nexport async function handler() {\n  const executablePath = await chromium.executablePath();\n  const result = execSync(\n    `AGENT_BROWSER_EXECUTABLE_PATH=${executablePath} agent-browser open https:\u002F\u002Fexample.com && agent-browser snapshot -i --json`,\n    { encoding: 'utf-8' }\n  );\n  return JSON.parse(result);\n}\n```\n\n## 本地文件\n\n使用 `file:\u002F\u002F` URL 打开并操作本地文件（PDF、HTML 等）：\n\n```bash\n# 启用文件访问权限（JavaScript 需要此权限才能访问本地文件）\nagent-browser --allow-file-access open file:\u002F\u002F\u002Fpath\u002Fto\u002Fdocument.pdf\nagent-browser --allow-file-access open file:\u002F\u002F\u002Fpath\u002Fto\u002Fpage.html\n\n# 截取本地 PDF 的屏幕截图\nagent-browser --allow-file-access open file:\u002F\u002F\u002FUsers\u002Fme\u002Freport.pdf\nagent-browser screenshot report.png\n```\n\n`--allow-file-access` 标志会添加 Chromium 标志（`--allow-file-access-from-files`、`--allow-file-access`），使 `file:\u002F\u002F` URL 能够：\n\n- 加载和渲染本地文件\n- 通过 JavaScript（XHR、fetch）访问其他本地文件\n- 加载本地资源（图片、脚本、样式表）\n\n**注意：** 此标志仅适用于 Chromium。出于安全考虑，默认情况下已禁用。\n\n## CDP 模式\n\n通过 Chrome DevTools 协议连接到现有浏览器：\n\n```bash\n# 使用以下命令启动 Chrome：google-chrome --remote-debugging-port=9222\n\n# 首次连接后，后续命令无需使用 --cdp\nagent-browser connect 9222\nagent-browser snapshot\nagent-browser tab\nagent-browser close\n\n# 或者在每个命令中都指定 --cdp\nagent-browser --cdp 9222 snapshot\n\n# 通过 WebSocket URL 连接到远程浏览器\nagent-browser --cdp \"wss:\u002F\u002Fyour-browser-service.com\u002Fcdp?token=...\" snapshot\n```\n\n`--cdp` 标志可以接受：\n\n- 一个端口号（例如 `9222`），用于通过 `http:\u002F\u002Flocalhost:{port}` 进行本地连接\n- 一个完整的 WebSocket URL（例如 `wss:\u002F\u002F...` 或 `ws:\u002F\u002F...`），用于连接到远程浏览器服务\n\n这使得能够控制以下内容：\n\n- Electron 应用程序\n- 具有远程调试功能的 Chrome\u002FChromium 实例\n- WebView2 应用程序\n- 任何公开 CDP 端点的浏览器\n\n### 自动连接\n\n使用 `--auto-connect` 可自动发现并连接到正在运行的 Chrome 实例，而无需指定端口：\n\n```bash\n# 自动发现启用了远程调试的 Chrome 浏览器\nagent-browser --auto-connect open example.com\nagent-browser --auto-connect snapshot\n\n# 或者通过环境变量\nAGENT_BROWSER_AUTO_CONNECT=1 agent-browser snapshot\n```\n\n自动连接通过以下方式发现 Chrome：\n\n1. 读取默认用户数据目录中的 Chrome `DevToolsActivePort` 文件\n2. 回退到探测常见调试端口（9222、9229）\n3. 如果基于 HTTP 的发现方法（`\u002Fjson\u002Fversion`、`\u002Fjson\u002Flist`）失败，则回退到直接的 WebSocket 连接\n\n这在以下情况下非常有用：\n\n- 当 Chrome 144+ 版本通过 `chrome:\u002F\u002Finspect\u002F#remote-debugging` 启用了远程调试功能时（该功能使用动态端口）\n- 当您希望与现有浏览器建立零配置连接时\n- 当您不想跟踪 Chrome 正在使用的端口时\n\n## 流媒体（浏览器预览）\n\n通过 WebSocket 流传输浏览器视口，以实现实时预览或“配对浏览”，让人类与 AI 代理同时观看并交互。\n\n### 流媒体\n\n每次会话都会自动在操作系统分配的端口上启动一个 WebSocket 流媒体服务器。使用 `stream status` 命令查看绑定的端口和连接状态：\n\n```bash\nagent-browser stream status\n```\n\n若要绑定到特定端口，可设置 `AGENT_BROWSER_STREAM_PORT`：\n\n```bash\nAGENT_BROWSER_STREAM_PORT=9223 agent-browser open example.com\n```\n\n您还可以在运行时使用 `stream enable`、`stream disable` 和 `stream status` 命令来管理流媒体：\n\n```bash\nagent-browser stream enable --port 9223   # 在特定端口重新启用流媒体\nagent-browser stream disable              # 停止当前会话的流媒体\n```\n\nWebSocket 服务器会流式传输浏览器视口，并接受输入事件。\n\n### WebSocket 协议\n\n连接到 `ws:\u002F\u002Flocalhost:9223` 以接收帧并发送输入：\n\n**接收帧：**\n\n```json\n{\n  \"type\": \"frame\",\n  \"data\": \"\u003Cbase64 编码的 JPEG>\",\n  \"metadata\": {\n    \"deviceWidth\": 1280,\n    \"deviceHeight\": 720,\n    \"pageScaleFactor\": 1,\n    \"offsetTop\": 0,\n    \"scrollOffsetX\": 0,\n    \"scrollOffsetY\": 0\n  }\n}\n```\n\n**发送鼠标事件：**\n\n```json\n{\n  \"type\": \"input_mouse\",\n  \"eventType\": \"mousePressed\",\n  \"x\": 100,\n  \"y\": 200,\n  \"button\": \"left\",\n  \"clickCount\": 1\n}\n```\n\n**发送键盘事件：**\n\n```json\n{\n  \"type\": \"input_keyboard\",\n  \"eventType\": \"keyDown\",\n  \"key\": \"Enter\",\n  \"code\": \"Enter\"\n}\n```\n\n**发送触摸事件：**\n\n```json\n{\n  \"type\": \"input_touch\",\n  \"eventType\": \"touchStart\",\n  \"touchPoints\": [{ \"x\": 100, \"y\": 200 }]\n}\n```\n\n## 架构\n\nagent-browser 采用客户端-守护进程架构：\n\n1. **Rust CLI** - 解析命令，与守护进程通信\n2. **Rust 守护进程** - 纯 Rust 守护进程，直接使用 CDP，无需 Node.js\n\n守护进程会在首次执行命令时自动启动，并在后续命令之间保持运行，以提高效率。若希望在一段时间内无活动后自动关闭守护进程，可设置 `AGENT_BROWSER_IDLE_TIMEOUT_MS`（单位为毫秒）。设置后，守护进程将在指定时间内未收到任何命令后关闭浏览器并退出。\n\n**浏览器引擎：** 默认使用 Chrome（来自 Chrome for Testing）。`--engine` 标志可在 `chrome` 和 `lightpanda` 之间选择。支持的浏览器：Chromium\u002FChrome（通过 CDP）和 Safari（通过 WebDriver for iOS）。\n\n## 平台\n\n| 平台    | 二进制      |\n| ----------- | ----------- |\n| macOS ARM64 | 原生 Rust |\n| macOS x64   | 原生 Rust |\n| Linux ARM64 | 原生 Rust |\n| Linux x64   | 原生 Rust |\n| Windows x64 | 原生 Rust |\n\n## 与 AI 代理一起使用\n\n### 直接让代理使用\n\n最简单的方法——只需告诉您的代理使用它：\n\n```\n使用 agent-browser 测试登录流程。运行 agent-browser --help 查看可用命令。\n```\n\n`--help` 输出内容全面，大多数代理都可以从中理解如何使用。\n\n### AI 编码助手（推荐）\n\n将该技能添加到您的 AI 编码助手中，以获得更丰富的上下文：\n\n```bash\nnpx skills add vercel-labs\u002Fagent-browser\n```\n\n此技能适用于 Claude Code、Codex、Cursor、Gemini CLI、GitHub Copilot、Goose、OpenCode 和 Windsurf。该技能是从仓库中获取的，因此会自动保持最新状态——请勿从 `node_modules` 中复制 `SKILL.md`，因为它会过时。\n\n### Claude Code\n\n作为 Claude Code 技能进行安装：\n\n```bash\nnpx skills add vercel-labs\u002Fagent-browser\n```\n\n这会将该技能添加到您项目的 `.claude\u002Fskills\u002Fagent-browser\u002FSKILL.md` 文件中。该技能会向 Claude Code 介绍完整的 agent-browser 工作流程，包括快照引用交互模式、会话管理和超时处理。\n\n### AGENTS.md \u002F CLAUDE.md\n\n为了获得更一致的结果，请将其添加到您的项目或全局指令文件中：\n\n```markdown\n## 浏览器自动化\n\n使用 `agent-browser` 进行网页自动化。运行 `agent-browser --help` 查看所有命令。\n\n核心工作流程：\n\n1. `agent-browser open \u003Curl>` - 导航到页面\n2. `agent-browser snapshot -i` - 获取带有引用的可交互元素（@e1、@e2）\n3. `agent-browser click @e1` \u002F `fill @e2 \"text\"` - 使用引用进行交互\n4. 页面变化后重新截图\n```\n\n## 集成\n\n### iOS 模拟器\n\n在 iOS 模拟器中控制真实的 Mobile Safari，以进行真实的移动网页测试。需要 macOS 系统并安装 Xcode。\n\n**设置：**\n\n```bash\n# 安装 Appium 和 XCUITest 驱动程序\nnpm install -g appium\nappium driver install xcuitest\n```\n\n**使用：**\n\n```bash\n# 列出可用的 iOS 模拟器\nagent-browser device list\n\n# 在特定设备上启动 Safari\nagent-browser -p ios --device \"iPhone 16 Pro\" open https:\u002F\u002Fexample.com\n\n# 命令与桌面版相同\nagent-browser -p ios snapshot -i\nagent-browser -p ios tap @e1\nagent-browser -p ios fill @e2 \"text\"\nagent-browser -p ios screenshot mobile.png\n\n# 移动端专用命令\nagent-browser -p ios swipe up\nagent-browser -p ios swipe down 500\n\n# 关闭会话\nagent-browser -p ios close\n```\n\n或者使用环境变量：\n\n```bash\nexport AGENT_BROWSER_PROVIDER=ios\nexport AGENT_BROWSER_IOS_DEVICE=\"iPhone 16 Pro\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n| 变量                   | 描述                                     |\n| -------------------------- | ----------------------------------------------- |\n| `AGENT_BROWSER_PROVIDER`   | 设置为 `ios` 以启用 iOS 模式                 |\n| `AGENT_BROWSER_IOS_DEVICE` | 设备名称（例如，“iPhone 16 Pro”、“iPad Pro”） |\n| `AGENT_BROWSER_IOS_UDID`   | 设备 UDID（替代设备名称）        |\n\n**支持的设备：** Xcode 中所有可用的 iOS 模拟器（iPhone、iPad），以及真实的 iOS 设备。\n\n**注意：** iOS 提供者会启动模拟器、运行 Appium 并控制 Safari 浏览器。首次启动大约需要 30–60 秒；后续命令则非常迅速。\n\n#### 实际设备支持\n\nAppium 也支持通过 USB 连接的真实 iOS 设备。这需要额外的一次性设置：\n\n**1. 获取您的设备 UDID：**\n\n```bash\nxcrun xctrace list devices\n# 或\nsystem_profiler SPUSBDataType | grep -A 5 \"iPhone\\|iPad\"\n```\n\n**2. 签名 WebDriverAgent（一次性）：**\n\n```bash\n# 打开 WebDriverAgent Xcode 项目\ncd ~\u002F.appium\u002Fnode_modules\u002Fappium-xcuitest-driver\u002Fnode_modules\u002Fappium-webdriveragent\nopen WebDriverAgent.xcodeproj\n```\n\n在 Xcode 中：\n\n- 选择 `WebDriverAgentRunner` 目标\n- 转到“签名与功能”\n- 选择您的团队（需要 Apple 开发者账户，免费层级即可）\n- 让 Xcode 自动管理签名\n\n**3. 与 agent-browser 一起使用：**\n\n```bash\n# 通过 USB 连接设备后：\nagent-browser -p ios --device \"\u003CDEVICE_UDID>\" open https:\u002F\u002Fexample.com\n\n# 或者如果设备名称唯一，也可以直接使用设备名称\nagent-browser -p ios --device \"John's iPhone\" open https:\u002F\u002Fexample.com\n```\n\n**真实设备注意事项：**\n\n- 首次运行会将 WebDriverAgent 安装到设备上（可能需要信任提示）\n- 设备必须解锁并连接到 USB\n- 初始连接速度略慢于模拟器\n- 测试结果反映了真实 Safari 的性能和行为\n\n### Browserless\n\n[Browserless](https:\u002F\u002Fbrowserless.io) 提供基于云的浏览器基础设施，并配备 Sessions API。当您在无法使用本地浏览器的环境中运行 agent-browser 时，可以使用它。\n\n要启用 Browserless，请使用 `-p` 标志：\n\n```bash\nexport BROWSERLESS_API_KEY=\"your-api-token\"\nagent-browser -p browserless open https:\u002F\u002Fexample.com\n```\n\n或者使用环境变量用于 CI\u002F脚本：\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browserless\nexport BROWSERLESS_API_KEY=\"your-api-token\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n可通过环境变量进行可选配置：\n\n| 变量                   | 描述                                      | 默认                                 |\n| -------------------------- | ------------------------------------------------ | --------------------------------------- |\n| `BROWSERLESS_API_URL`      | 基础 API 地址（用于自定义区域或自托管） | `https:\u002F\u002Fproduction-sfo.browserless.io` |\n| `BROWSERLESS_BROWSER_TYPE` | 使用的浏览器类型（chromium 或 chrome）      | chromium                                |\n| `BROWSERLESS_TTL`          | 会话存活时间（毫秒）                      | `300000`                                |\n| `BROWSERLESS_STEALTH`      | 启用隐身模式（`true`\u002F`false`）             | `true`                                  |\n\n启用后，agent-browser 将连接到 Browserless 的云会话，而不是启动本地浏览器。所有命令的功能完全相同。\n\n请从 [Browserless 控制面板](https:\u002F\u002Fbrowserless.io) 获取您的 API 令牌。\n\n### Browserbase\n\n[Browserbase](https:\u002F\u002Fbrowserbase.com) 提供远程浏览器基础设施，使部署代理式浏览代理变得容易。当您在无法使用本地浏览器的环境中运行 agent-browser CLI 时，可以使用它。\n\n要启用 Browserbase，请使用 `-p` 标志：\n\n```bash\nexport BROWSERBASE_API_KEY=\"your-api-key\"\nagent-browser -p browserbase open https:\u002F\u002Fexample.com\n```\n\n或者使用环境变量用于 CI\u002F脚本：\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browserbase\nexport BROWSERBASE_API_KEY=\"your-api-key\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n启用后，agent-browser 会连接到 Browserbase 会话，而不是启动本地浏览器。所有命令的功能完全相同。\n\n请从 [Browserbase 控制面板](https:\u002F\u002Fbrowserbase.com\u002Foverview) 获取您的 API 密钥。\n\n### Browser Use\n\n[Browser Use](https:\u002F\u002Fbrowser-use.com) 为 AI 代理提供云浏览器基础设施。当在无法使用本地浏览器的环境中运行 agent-browser（例如无服务器环境、CI\u002FCD 等）时，可以使用它。\n\n要启用 Browser Use，请使用 `-p` 标志：\n\n```bash\nexport BROWSER_USE_API_KEY=\"your-api-key\"\nagent-browser -p browseruse open https:\u002F\u002Fexample.com\n```\n\n或者在 CI\u002F脚本中使用环境变量：\n\n```bash\nexport AGENT_BROWSER_PROVIDER=browseruse\nexport BROWSER_USE_API_KEY=\"your-api-key\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n启用后，agent-browser 将连接到 Browser Use 的云会话，而不是启动本地浏览器。所有命令的功能完全相同。\n\n您可以在 [Browser Use 云控制台](https:\u002F\u002Fcloud.browser-use.com\u002Fsettings?tab=api-keys) 获取 API 密钥。开始使用时可享受免费额度，之后按使用量付费。\n\n### Kernel\n\n[Kernel](https:\u002F\u002Fwww.kernel.sh) 为 AI 代理提供云浏览器基础设施，具备隐身模式和持久化配置文件等功能。\n\n要启用 Kernel，请使用 `-p` 标志：\n\n```bash\nexport KERNEL_API_KEY=\"your-api-key\"\nagent-browser -p kernel open https:\u002F\u002Fexample.com\n```\n\n或者在 CI\u002F脚本中使用环境变量：\n\n```bash\nexport AGENT_BROWSER_PROVIDER=kernel\nexport KERNEL_API_KEY=\"your-api-key\"\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n可通过环境变量进行可选配置：\n\n| 变量                 | 描述                                                                      | 默认值 |\n| ------------------------ | -------------------------------------------------------------------------------- | ------- |\n| `KERNEL_HEADLESS`        | 以无头模式运行浏览器（`true`\u002F`false`）                                    | `false` |\n| `KERNEL_STEALTH`         | 启用隐身模式以避免被检测为机器人（`true`\u002F`false`）                      | `true`  |\n| `KERNEL_TIMEOUT_SECONDS` | 会话超时时间（秒）                                                       | `300`   |\n| `KERNEL_PROFILE_NAME`    | 浏览器配置文件名称，用于保存持久化的 Cookie 和登录信息（如果不存在则创建） | （无）  |\n\n启用后，agent-browser 将连接到 Kernel 的云会话，而不是启动本地浏览器。所有命令的功能完全相同。\n\n**配置文件持久化：** 当设置了 `KERNEL_PROFILE_NAME` 时，如果该配置文件尚不存在，系统将自动创建。浏览器会话结束时，Cookie、登录状态等会话数据会自动保存回该配置文件，以便在后续会话中继续使用。\n\n您可以在 [Kernel 控制台](https:\u002F\u002Fdashboard.onkernel.com) 获取 API 密钥。\n\n### AgentCore\n\n[AWS Bedrock AgentCore](https:\u002F\u002Faws.amazon.com\u002Fbedrock\u002Fagentcore\u002F) 提供支持 SigV4 认证的云浏览器会话。\n\n要启用 AgentCore，请使用 `-p` 标志：\n\n```bash\nagent-browser -p agentcore open https:\u002F\u002Fexample.com\n```\n\n或者在 CI\u002F脚本中使用环境变量：\n\n```bash\nexport AGENT_BROWSER_PROVIDER=agentcore\nagent-browser open https:\u002F\u002Fexample.com\n```\n\n凭据会自动从环境变量（`AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`）或 AWS CLI（`aws configure export-credentials`）中解析，支持 SSO、配置文件和 IAM 角色。\n\n可通过环境变量进行可选配置：\n\n| 变量                   | 描述                                                          | 默认值          |\n| -------------------------- | -------------------------------------------------------------- | --------------- |\n| `AGENTCORE_REGION`         | AgentCore 终端节点所在的 AWS 区域                              | `us-east-1`     |\n| `AGENTCORE_BROWSER_ID`     | 浏览器标识符                                                 | `aws.browser.v1` |\n| `AGENTCORE_PROFILE_ID`     | 用于保存持久化状态（Cookie、localStorage）的浏览器配置文件   | （无）           |\n| `AGENTCORE_SESSION_TIMEOUT`| 会话超时时间（秒）                                           | `3600`          |\n| `AWS_PROFILE`              | 用于解析凭据的 AWS CLI 配置文件                              | `default`       |\n\n**浏览器配置文件：** 当设置了 `AGENTCORE_PROFILE_ID` 时，浏览器状态（Cookie、localStorage）将在不同会话之间自动保持一致。\n\n启用后，agent-browser 将连接到 AgentCore 的云浏览器会话，而不是启动本地浏览器。所有命令的功能完全相同。\n\n## 许可证\n\nApache-2.0","# agent-browser 快速上手指南\n\n`agent-browser` 是一款专为 AI Agent 设计的高性能浏览器自动化命令行工具，基于 Rust 原生开发。它支持通过自然语言或语义化选择器控制浏览器，无需 Node.js 运行时即可运行守护进程。\n\n## 环境准备\n\n### 系统要求\n- **操作系统**：macOS, Linux, Windows\n- **浏览器内核**：工具会自动下载专用的 Chrome for Testing 版本，也支持自动检测系统中已安装的 Chrome、Brave、Playwright 或 Puppeteer。\n- **Rust**：仅当你需要从源码构建时才需要安装（普通用户无需安装）。\n\n### Linux 用户特别提示\n在 Linux 系统上首次使用时，需安装系统级依赖库：\n```bash\nagent-browser install --with-deps\n```\n\n## 安装步骤\n\n推荐根据你的使用场景选择以下一种安装方式：\n\n### 方式一：全局安装（推荐）\n适用于直接在终端使用命令。\n\n**通过 npm 安装：**\n```bash\nnpm install -g agent-browser\nagent-browser install  # 首次运行需下载 Chrome\n```\n\n**通过 Homebrew (macOS)：**\n```bash\nbrew install agent-browser\nagent-browser install\n```\n\n**通过 Cargo (Rust)：**\n```bash\ncargo install agent-browser\nagent-browser install\n```\n\n### 方式二：项目局部安装\n适用于需要在 `package.json` 中锁定版本的工程项目。\n\n```bash\nnpm install agent-browser\nagent-browser install\n# 使用时可通过 npx agent-browser 或在 package.json scripts 中调用\n```\n\n### 升级工具\n无论通过何种方式安装，均可使用以下命令自动检测并升级到最新版本：\n```bash\nagent-browser upgrade\n```\n\n## 基本使用\n\n### 1. 启动与导航\n打开指定网址：\n```bash\nagent-browser open example.com\n```\n\n### 2. 获取页面状态（AI 友好）\n获取带有引用 ID 的无障碍树（Accessibility Tree），这是让 AI 理解页面结构的关键步骤：\n```bash\nagent-browser snapshot\n```\n\n### 3. 元素操作\n利用 `snapshot` 生成的引用 ID（如 `@e2`）进行精准操作：\n\n- **点击元素**：\n  ```bash\n  agent-browser click @e2\n  ```\n- **填充表单**：\n  ```bash\n  agent-browser fill @e3 \"test@example.com\"\n  ```\n- **获取文本**：\n  ```bash\n  agent-browser get text @e1\n  ```\n- **截图保存**：\n  ```bash\n  agent-browser screenshot page.png\n  ```\n\n### 4. 传统选择器支持\n如果不使用快照引用，也支持标准的 CSS 选择器和语义化查找：\n\n```bash\n# CSS 选择器\nagent-browser click \"#submit\"\nagent-browser fill \"#email\" \"test@example.com\"\n\n# 语义化查找 (推荐用于动态页面)\nagent-browser find role button click --name \"Submit\"\nagent-browser find text \"Sign In\" click\n```\n\n### 5. 结束会话\n操作完成后关闭浏览器：\n```bash\nagent-browser close\n```\n\n### 进阶：AI 自然语言控制\n直接使用自然语言指令让 AI 代理执行操作（单条指令模式）：\n```bash\nagent-browser chat \"登录网站并截图首页\"\n```","某电商测试团队需要每日对数百个商品详情页进行自动化回归测试，验证价格显示、库存状态及“加入购物车”功能是否正常。\n\n### 没有 agent-browser 时\n- 测试脚本严重依赖 Node.js 环境和 Playwright\u002FPuppeteer 库，配置繁琐且在不同 CI 节点上常因依赖版本冲突导致运行失败。\n- 元素定位必须编写复杂的 CSS 或 XPath 选择器，一旦页面微调（如 class 名变更），脚本立即报错，维护成本极高。\n- 调试过程痛苦，失败时缺乏直观的现场快照，工程师需反复本地复现才能定位是网络问题还是元素未加载。\n- 执行速度受限于 JavaScript 运行时开销，在大规模并发测试场景下资源占用高，整体反馈周期长。\n\n### 使用 agent-browser 后\n- 直接利用基于 Rust 的原生二进制文件运行，无需安装 Node.js 或额外浏览器驱动，开箱即用且跨平台一致性极佳。\n- 通过 `snapshot` 命令快速获取带引用编号的无障碍树，直接使用 `click @e2` 等语义化指令操作元素，彻底摆脱脆弱的选择器维护。\n- 内置一键截图与标注功能（`screenshot --annotate`），失败时自动输出带元素编号的现场图，问题定位从小时级缩短至分钟级。\n- 凭借 Rust 的高性能优势，浏览器启动与指令执行速度显著提升，大幅压缩了每日回归测试的总耗时。\n\nagent-browser 通过将浏览器自动化简化为高效的 CLI 指令流，让 AI 代理和测试人员能以最低门槛实现稳定、高速的网页交互验证。","https:\u002F\u002Foss.gittoolsai.com\u002Fimages\u002Fvercel-labs_agent-browser_bae4884e.png","vercel-labs","Vercel Labs","https:\u002F\u002Foss.gittoolsai.com\u002Favatars\u002Fvercel-labs_7a3dc422.png","Develop. Preview. Ship. Creators of Next.js.",null,"support@vercel.com","vercel","https:\u002F\u002Fvercel.com","https:\u002F\u002Fgithub.com\u002Fvercel-labs",[83,87,91,95,99,103],{"name":84,"color":85,"percentage":86},"Rust","#dea584",84.4,{"name":88,"color":89,"percentage":90},"TypeScript","#3178c6",12.6,{"name":92,"color":93,"percentage":94},"Shell","#89e051",1.2,{"name":96,"color":97,"percentage":98},"JavaScript","#f1e05a",1,{"name":100,"color":101,"percentage":102},"HTML","#e34c26",0.5,{"name":104,"color":105,"percentage":106},"CSS","#663399",0.3,28590,1734,"2026-04-11T09:48:39","Apache-2.0","Linux, macOS, Windows","未说明",{"notes":114,"python":115,"dependencies":116},"该工具是基于 Rust 编写的原生 CLI，无需 Python 环境。首次运行需执行 'agent-browser install' 下载 Chrome 浏览器（或使用系统已有的 Chrome\u002FBrave\u002FPlaywright\u002FPuppeteer 实例）。在 Linux 系统上可能需要安装额外的系统依赖库（可通过 'agent-browser install --with-deps' 自动安装）。支持通过 npm、Homebrew、Cargo 或源码安装。","不需要",[117,118,119],"Rust (仅源码编译时需要)","Chrome\u002FChromium (自动下载或通过系统现有安装检测)","Node.js\u002Fnpm (仅用于安装管理，运行时非必需)",[13,52],"2026-03-27T02:49:30.150509","2026-04-11T23:22:53.431317",[],[125,130,135,140,145,150,155,160,165,170,175,180,185,190,195,200,205,210,215,220],{"id":126,"version":127,"summary_zh":128,"released_at":129},206558,"v0.25.3","### Bug 修复\n\n- 修复了当 `\u003Clabel>` 包裹一个 `display:none` 的 `\u003Cinput type=\"radio\">` 或 `\u003Cinput type=\"checkbox\">` 时，**快照引用中缺少隐藏的单选\u002F复选框输入**的问题。Chrome 会完全将这些输入排除在无障碍树之外，导致 AI 助手无法通过引用识别单选按钮和复选框。现在，在光标交互式扫描过程中会检测到元素内部的隐藏输入，并将其父节点提升为正确的角色，同时正确设置名称和选中状态（#1085）。\n\n### 文档\n\n- 在文档站点中添加了**可点击的标题锚点**，方便直接链接到任意章节（#1175）。\n\n### 贡献者\n\n- @ctate\n- @jin-2-kakaoent\n- @hyunjinee\n","2026-04-07T02:11:22",{"id":131,"version":132,"summary_zh":133,"released_at":134},206559,"v0.25.2","### Bug 修复\n\n- 修复了在 Linux 上 Chrome 空闲约 10 秒后被杀死的问题，该问题是由 `PR_SET_PDEATHSIG` 跟踪的是启动 Chrome 的阻塞线程，而非守护进程所致。当 Tokio 回收空闲线程时，内核会向 Chrome 发送 SIGKILL 信号，尽管守护进程仍然存活。孤儿进程的清理工作已由 `ChromeProcess::kill()` 中现有的进程组杀戮机制处理。（#1157、#1173）\n\n### 贡献者\n\n- @ctate\n","2026-04-07T00:02:55",{"id":136,"version":137,"summary_zh":138,"released_at":139},206560,"v0.25.1","### 改进\n\n- **嵌入式仪表盘** - 现在使用 `rust-embed` 将可观测性仪表盘直接打包到 CLI 二进制文件中，从而无需再执行 `dashboard install` 命令。安装 `agent-browser` 后，仪表盘即可立即使用 (#1169)\n\n### 贡献者\n\n- @ctate\n","2026-04-06T16:00:43",{"id":141,"version":142,"summary_zh":143,"released_at":144},206561,"v0.25.0","### 新特性\n\n- **AI 聊天命令** - 新增 `chat` 命令，用于基于 AI 的浏览器自动化。支持单次执行模式（`chat \"open google.com\"`）和交互式 REPL。AI 代理可通过工具调用执行任何 agent-browser 命令。需设置 `AI_GATEWAY_API_KEY`。可使用 `--model` 或 `AI_GATEWAY_MODEL` 配置模型版本 (#1160, #1163)\n- **仪表板 AI 聊天** - 可观测性仪表板现新增内置 AI 聊天界面，支持对话式浏览器控制，并与实时会话视图并存 (#1160, #1163)\n- **`snapshot --urls`** - 新增 `-u`\u002F`--urls` 标志，可在截图输出中包含链接元素的 `href` URL，使代理无需额外查询即可直接访问链接目标 (#1160)\n- **批处理参数模式** - `batch` 命令现不仅可从标准输入读取命令，还支持将命令作为内联参数直接传入，从而简化一次性调用的多命令工作流 (#1160)\n\n### Bug 修复\n\n- 修复了 **`getByRole`** 匹配错误元素的问题（例如将 `\u003Clink>` 样式表元素误认为 `\u003Ca>` 链接锚点），通过重写实现方式，改用 CDP 辅助功能树结合基于引用的元素解析，而非 CSS 选择器 (#1145)\n- 修复了 **`upload` 命令** 不支持使用辅助功能树引用（`@eN`）来选择文件上传元素的问题 (#1156)\n- 修复了 **`AGENT_BROWSER_DEFAULT_TIMEOUT`** 未应用于 `wait` 命令的问题。该环境变量现已传播至所有等待变体（`wait`、`wait --url`、`wait --text`、`wait --load`、`wait --fn`、`wait --download`）(#1153)\n- 修复了 **仪表板下载** 的错误处理问题，优化了重试逻辑，以提升仪表板安装的可靠性 (#1154)\n\n### 测试\n\n- 修复了 Windows 环境下及端到端测试中的 CI 测试失败问题 (#1165)\n\n### 贡献者\n\n- @ctate\n- @jin-2-kakaoent\n- @hyunjinee\n","2026-04-06T15:27:59",{"id":146,"version":147,"summary_zh":148,"released_at":149},206562,"v0.24.1","### 新特性\n\n- **Chrome 配置文件登录状态复用** - `--profile \u003Cname>` 现在可以解析 Chrome 配置文件名称（例如 `Default`、`Profile 1`），并将该配置文件复制到临时目录，以便在不修改原始配置的情况下复用登录状态、Cookie 和扩展程序。新增了 `profiles` 命令，用于列出可用的 Chrome 配置文件，并支持 `--json` 格式输出（#1131）\n\n### Bug 修复\n\n- 修复了 **`--ignore-https-errors`** 未将 `--ignore-certificate-errors` 作为 Chrome 启动参数传递的问题，导致 TLS 错误（如 `ERR_SSL_PROTOCOL_ERROR`）在网络层就被拦截，CDP 无法介入（#1132）\n- 通过将 Chrome 放入独立的进程组，并在守护进程退出时杀死整个进程组，修复了守护进程退出时出现的 **孤立 Chrome 进程** 问题。在 Linux 上，使用 `PR_SET_PDEATHSIG` 可确保即使守护进程被 OOM 杀死，Chrome 也会被强制终止（#1137）\n- 修复了在连接真实浏览器会话时，**CDP attach 在 Chrome 144+ 版本上卡住** 的问题。现在，attach 后处于等待调试器暂停的目标将通过 `Runtime.runIfWaitingForDebugger` 被恢复执行（#1133）\n- 修复了 **升级后残留的旧版守护进程** 会静默复用，导致 CDP 行为异常的问题。守护进程现在会写入一个 `.version` 旁路文件，并在版本不匹配时自动重启（#1134）\n- 修复了 **残留守护进程和套接字恢复** 时，`close --all` 无法清理僵尸守护进程和过期文件的问题。现在，无法访问的守护进程会被强制终止，孤立的套接字和 PID 文件也会被移除（#1136）\n- 修复了 **空闲超时未生效** 的问题，原因是每次 `select` 循环迭代时都会重新创建睡眠未来，从而阻止截止时间到达（#1110）\n- 修复了当启动选项发生变化时（例如在连续的启动命令之间向 `config.json` 添加扩展程序），**浏览器未能重新启动** 的问题（#996）\n- 修复了 **`auto_launch()`** 未遵循 `AGENT_BROWSER_PROVIDER` 设置以使用云服务商提供的浏览器，导致非启动命令回退到本地 Chrome 而不是通过提供商 API 连接的问题（#1126）\n- 通过将 CDP 广播缓冲区从 256 增加至 4096 个事件、将轮询间隔从 500 毫秒缩短至 100 毫秒，并在跨域 iframe 中启用网络跟踪，修复了 **HAR 抓取遗漏 API 请求** 的问题，尤其是在高流量情况下（#1135）\n\n### 测试\n\n- 修复了 **`e2e_relaunch_on_options_change`** 测试在 CI 环境中无显示设备时仍启动有头 Chrome 的问题。该测试现在保持无头模式，仅通过更改扩展程序来触发重新启动（#996）\n- 通过将 SPA 渲染延迟从 1200 毫秒缩短至 800 毫秒，为较慢的 CI 运行器在选择器等待时间内留出更多余地，修复了 **`e2e_auth_login`** 测试偶发失败的问题。\n\n### 贡献者\n\n- @ctate\n- @desenmeng\n- @jin-2-kakaoent\n- @snese","2026-04-04T17:56:26",{"id":151,"version":152,"summary_zh":153,"released_at":154},206563,"v0.24.0","### 新功能\n\n- **AWS Bedrock AgentCore 提供者** - 新增 AWS Bedrock AgentCore 作为云浏览器提供者。可通过 `--provider agentcore` 或 `AGENT_BROWSER_PROVIDER=agentcore` 进行连接。采用轻量级的手动 SigV4 签名进行身份验证，支持完整的 AWS 凭证提供链（环境变量、AWS CLI、SSO、IAM 角色）。可通过 `AGENTCORE_REGION`、`AGENTCORE_PROFILE_ID` 和 `AGENTCORE_BROWSER_ID` 环境变量进行配置。在启动响应中返回会话 ID 和 Live View URL (#397)\n\n### 文档\n\n- 在文档站点、README 选项表、SKILL.md 以及仪表板提供者图标中新增了 AgentCore 提供者页面 (#1120)\n\n### 贡献者\n\n- @ctate\n- @pahud","2026-04-03T01:48:47",{"id":156,"version":157,"summary_zh":158,"released_at":159},206564,"v0.23.4","### Bug修复\n\n- 修复了**Linux 上的守护进程挂起**问题，该问题是由 SIGCHLD 信号处理程序中的 `waitpid(-1)` 竞态条件引起的。此竞态条件会从 Rust 的 `Child` 句柄中窃取退出状态，导致守护进程处于损坏状态。现已将全局信号处理程序替换为通过现有排水间隔进行的定向崩溃检测 (#1098)。\n\n### 贡献者\n\n- @ctate\n","2026-03-31T07:32:26",{"id":161,"version":162,"summary_zh":163,"released_at":164},206565,"v0.23.3","### 错误修复\n\n- 修复了**拖放**功能无法正常工作的问题：在拖动过程中，`mouseMoved` 事件会省略 `buttons` 位掩码，导致浏览器认为 `event.buttons === 0`，从而始终不会触发 `dragstart`、`dragover` 和 `drop` 事件（#1087）\n\n### 贡献者\n\n- @ctate\n- @juniper929\n","2026-03-31T01:36:21",{"id":166,"version":167,"summary_zh":168,"released_at":169},206566,"agent-browser@0.23.2","### 补丁变更\n\n-   3c942e2: ### 新功能\n\n    -   **仪表板会话创建** - 现在可以直接从仪表板界面创建会话。新增的会话对话框提供了一个统一的选择网格，用于本地引擎（Chrome、Lightpanda）和云服务商（Browserbase、Browserless、Browser Use、Kernel），支持异步创建、加载状态显示及错误提示（#1092）\n    -   **仪表板提供商图标** - 会话侧边栏现在会显示每个会话对应的提供商或引擎图标，便于快速识别会话所使用的后端服务（#1092）\n\n    ### 错误修复\n\n    -   修复了 **Browser Use** 提供商使用中间 API 调用而非直接通过 WSS (`wss:\u002F\u002Fconnect.browser-use.com`) 连接的问题，该问题曾导致连接失败（#1092）\n    -   修复了 **Browserbase** 提供商未发送明确的 JSON 请求体和 `Content-Type` 头部，从而导致会话创建失败的问题（#1092）\n    -   修复了 **提供商导航** 卡住的问题，原因是 `wait_for_lifecycle` 会等待页面加载事件，而远程提供商可能不会发出这些事件。现在使用 `--provider` 进行导航时，会自动设置 `waitUntil=none`（#1092）\n    -   修复了 **远程 CDP 连接** 超时的问题，将云服务商的 CDP 连接超时时间由 10 秒延长至 25 秒（#1092）\n    -   修复了 **僵尸守护进程** 在仪表板创建会话时因提供商连接失败而未能被清理的问题（#1092）","2026-03-31T00:20:31",{"id":171,"version":172,"summary_zh":173,"released_at":174},206567,"v0.23.2","### 新功能\n\n- **仪表板会话创建** - 现在可以直接从仪表板界面创建会话。新的会话对话框提供了一个统一的选择网格，用于本地引擎（Chrome、Lightpanda）和云服务商（Browserbase、Browserless、Browser Use、Kernel），支持异步创建、加载状态显示以及错误提示 (#1092)\n- **仪表板提供商图标** - 会话侧边栏现在会显示每个会话对应的提供商或引擎图标，便于快速识别会话所使用的后端 (#1092)\n\n### Bug 修复\n\n- 修复了 **Browser Use** 提供商使用中间 API 调用而非直接通过 WSS 连接的问题，该问题曾导致连接失败 (#1092)\n- 修复了 **Browserbase** 提供商未发送明确的 JSON 请求体和 `Content-Type` 头部，从而导致会话创建失败的问题 (#1092)\n- 修复了 **提供商导航** 卡死的问题，原因是 `wait_for_lifecycle` 会等待远程提供商可能不会发出的页面加载事件。现在使用 `--provider` 进行导航时，会自动设置 `waitUntil=none` (#1092)\n- 通过将云服务商的 CDP 连接超时时间由 10 秒增加至 25 秒，修复了 **远程 CDP 连接** 超时的问题 (#1092)\n- 修复了在仪表板创建会话时，如果提供商连接失败，会导致 **僵尸守护进程** 无法被清理的问题 (#1092)\n\n### 贡献者\n\n- @ctate\n","2026-03-31T00:21:08",{"id":176,"version":177,"summary_zh":178,"released_at":179},206568,"agent-browser@0.23.1","### Patch Changes\n\n-   fbcab37: ### New Features\n\n    -   **Auto-dismissal for alert and beforeunload dialogs** - JavaScript `alert()` and `beforeunload` dialogs are now automatically accepted to prevent the agent from blocking indefinitely. `confirm` and `prompt` dialogs still require explicit `dialog accept\u002Fdismiss` commands. Disable with `--no-auto-dialog` flag or `AGENT_BROWSER_NO_AUTO_DIALOG` environment variable (#1075)\n    -   **Puppeteer browser cache fallback** - Chrome discovery now searches `~\u002F.cache\u002Fpuppeteer\u002Fchrome\u002F` (or `PUPPETEER_CACHE_DIR`) for Chrome binaries, so users with an existing Puppeteer installation can use agent-browser without a separate install step (#1088)\n    -   **Console output improvements** - `console.log` of objects now shows the actual object preview (e.g. `{userId: \"abc\", count: 42}`) instead of `\"Object\"`. JSON output includes a raw `args` array for programmatic access (#1040)\n\n    ### Bug Fixes\n\n    -   Fixed **same-document navigation** (e.g. SPA hash routing) hanging forever because `wait_for_lifecycle` waited for a `Page.loadEventFired` that never fires on same-document navigations (#1059)\n    -   Fixed **save_state** only capturing cookies and localStorage for the current origin, silently dropping cross-domain data (e.g. SSO\u002FCAS auth cookies). Now uses `Network.getAllCookies` and collects localStorage from all visited origins (#1064)\n    -   Fixed **externally opened tabs** not appearing in `tab list` when using `--cdp` mode. Tabs opened by the user or another CDP client are now detected and tracked (#1042)\n    -   Fixed **dashboard server** not picking up installed files without a restart. `dashboard install` now takes effect immediately on a running server (#1066)\n    -   Fixed **Windows Chrome extraction** failing because zip path normalization used forward slashes while the extraction code expected backslashes (#1088)\n","2026-03-30T18:38:34",{"id":181,"version":182,"summary_zh":183,"released_at":184},206569,"v0.23.1","## What's Changed\n* chore: version packages by @github-actions[bot] in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1029\n* dashboard by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1034\n* fix: use TCP instead of Unix socket on Windows in dashboard relay by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1038\n* fix(windows): fall back to OS-assigned port when Hyper-V blocks daemon TCP bind by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1041\n* fix lightpanda by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1050\n* chore: add minor changeset for v0.23.0 release by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1052\n* fix: include root package in pnpm workspace for changesets by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1053\n* chore: version packages by @github-actions[bot] in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1054\n* fix: save_state captures cross-domain cookies and localStorage by @jin-2-kakaoent in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1064\n* fix: detect externally opened tabs in --cdp mode by @jin-2-kakaoent in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1042\n* fix: dashboard server picks up installed files without restart by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1066\n* Add auto-dismissal for alert and beforeunload dialogs by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1075\n* fix: expose raw CDP args in console output and use preview for formatting by @jin-2-kakaoent in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1040\n* fix: skip wait_for_lifecycle on same-document navigation by @hechang27-sprt in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1059\n* fix: Windows Chrome extraction and debugging environment by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1088\n* chore: prepare v0.23.1 release by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1089\n* chore: version packages by @github-actions[bot] in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1090\n\n## New Contributors\n* @hechang27-sprt made their first contribution in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1059\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fcompare\u002Fv0.22.3...v0.23.1","2026-03-30T18:39:14",{"id":186,"version":187,"summary_zh":188,"released_at":189},206570,"agent-browser@0.23.0","### Minor Changes\n\n-   0f0f300: ### New Features\n\n    -   **Observability dashboard** - Added a local web UI (`dashboard`) that shows live browser viewports, command activity feeds, console output, network requests, storage, and extensions for all sessions. Manage it with `dashboard start`, `dashboard stop`, and `dashboard install`. The dashboard runs as a standalone background process and all sessions stream to it automatically (#1034)\n    -   **Runtime stream management** - Added `stream enable`, `stream disable`, and `stream status` commands to control WebSocket streaming at runtime. Streaming is now always enabled by default; `AGENT_BROWSER_STREAM_PORT` overrides the port instead of toggling the feature (#951)\n    -   **Close all sessions** - Added `close --all` flag to close every active browser session at once\n\n    ### Bug Fixes\n\n    -   Fixed **Lightpanda engine** compatibility (#1050)\n    -   Fixed **Windows daemon TCP bind** failing when Hyper-V reserves the port by falling back to an OS-assigned port and writing it to a `.port` file (#1041)\n    -   Fixed **Windows dashboard relay** using Unix socket instead of TCP (#1038)\n    -   Fixed **radio\u002Fcheckbox elements** being dropped from compact snapshot tree because the `ref=` check required a leading `[` that those elements lack (#1008)\n","2026-03-27T17:36:27",{"id":191,"version":192,"summary_zh":193,"released_at":194},206571,"v0.23.0","## What's Changed\n* chore: version packages by @github-actions[bot] in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1029\n* dashboard by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1034\n* fix: use TCP instead of Unix socket on Windows in dashboard relay by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1038\n* fix(windows): fall back to OS-assigned port when Hyper-V blocks daemon TCP bind by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1041\n* fix lightpanda by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1050\n* chore: add minor changeset for v0.23.0 release by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1052\n* fix: include root package in pnpm workspace for changesets by @ctate in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1053\n* chore: version packages by @github-actions[bot] in https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fpull\u002F1054\n\n\n**Full Changelog**: https:\u002F\u002Fgithub.com\u002Fvercel-labs\u002Fagent-browser\u002Fcompare\u002Fv0.22.3...v0.23.0","2026-03-27T17:37:04",{"id":196,"version":197,"summary_zh":198,"released_at":199},206572,"v0.22.3","### Patch Changes\n\n-   eb64ca4: ### Bug Fixes\n\n    -   **Re-apply download behavior on recording context** - Fixed an issue where downloads were silently dropped in recording contexts because `Browser.setDownloadBehavior` set at launch only applied to the default context. The download behavior is now re-applied when a new recording context is created (#1019)\n    -   **Reap zombie Chrome process and fast-detect crash for auto-restart** - Added a non-blocking process-exit check before attempting CDP connection checks. This prevents a 3-second CDP timeout when Chrome has already crashed or exited, enabling faster detection and auto-restart of the browser (#1023)\n    -   **Route keyboard `type` through text input** - Fixed keyboard `type` subaction to correctly route through the text input handler, and added support for an `insertText` subaction using `Input.insertText` (#1014)\n    -   **Handle `--clear` flag in `console` command** - Fixed the `console` command to accept and process a `clear` parameter, allowing console event history to be cleared (#1015)\n","2026-03-25T18:56:57",{"id":201,"version":202,"summary_zh":203,"released_at":204},206573,"v0.22.2","### Patch Changes\n\n-   a098197: ### New Features\n\n    -   **Dialog status command** - Added `dialog status` command to check whether a JavaScript dialog is currently open (#999)\n    -   **Dialog warning field** - Command responses now include a `warning` field when a JavaScript dialog is pending, indicating the dialog type and message (#999)\n\n    ### Improvements\n\n    -   **Standard proxy environment variables** - The proxy setting now automatically falls back to standard environment variables (`HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`, and their lowercase variants), with `NO_PROXY`\u002F`no_proxy` respected for bypass rules (#1000)\n    -   **Font packages for `--with-deps`** - Installing with `--with-deps` now includes CJK and emoji font packages on Linux (Debian, RPM, and yum-based distros) to prevent missing glyphs when rendering international content (#1002)\n\n    ### Bug Fixes\n\n    -   Fixed `state show` always failing with \"Missing 'path' parameter\" due to a mismatched JSON field name (`filename` → `path`) (#994)\n    -   Fixed `console` command returning only `Done` due to a JSON field name mismatch in the response (#986)\n    -   Fixed browser-domain CDP events being dropped during downloads due to a `sessionId` mismatch (#998)\n    -   Fixed proxy authentication by handling credentials via the CDP `Fetch.authRequired` event rather than passing them inline (#1000)\n","2026-03-24T22:27:11",{"id":206,"version":207,"summary_zh":208,"released_at":209},206574,"v0.22.1","### Patch Changes\n\n-   3a3317b: ### Bug Fixes\n\n    -   Fixed **modifier key chords** (e.g. `Control+a`, `Shift+Enter`, `Control+Shift+a`) not being handled correctly when using `press`. Modifier keys (`Alt`, `Control`\u002F`Ctrl`, `Meta`\u002F`Cmd`, `Shift`) are now parsed and forwarded as CDP modifier bitmasks rather than treated as part of the key name (#980)\n    -   Fixed **query parameters being dropped** from `--cdp` HTTP URLs (e.g. `http:\u002F\u002Fhost:9222?mode=Hello`). Query strings are now preserved and forwarded to the remote CDP endpoint (#982)\n","2026-03-24T13:02:28",{"id":211,"version":212,"summary_zh":213,"released_at":214},206575,"v0.22.0","### Minor Changes\n\n-   be30bc9: ### New Features\n\n    -   **Cross-origin iframe support** - Added support for snapshots and interactions within cross-origin iframes via `Target.setAutoAttach` (#949)\n    -   **Network request detail and filtering** - Added `network request \u003CrequestId>` command to view full request\u002Fresponse detail, and new filtering options for `network requests` including `--type` (e.g. `xhr,fetch`), `--method` (e.g. `POST`), and `--status` (e.g. `2xx`, `400-499`) (#935)\n\n    ### Improvements\n\n    -   **Snapshot usability** - Reduced AI cognitive load by filtering semantic noise from snapshot output; cursor-interactive elements are now included by default, making the `-C` flag unnecessary (#968)\n    -   **Upgrade command** - Improved robustness of installation method detection in the upgrade command (#960)\n    -   **Target tracking** - Enhanced target tracking and page information handling for more reliable browser session management (#969)\n\n    ### Bug Fixes\n\n    -   Fixed **viewport dimensions** being reported incorrectly in streaming status messages and screencast (#952)\n    -   Fixed **`find` command** flags such as `--exact` and `--name` leaking into fill values when used with fill actions (#955)\n    -   Fixed **state commands** incorrectly starting the daemon when no `session_name` is provided (#677, #964)\n    -   Fixed **auto-connect** triggering when the daemon is already running, preventing duplicate connections (#971)\n    -   Fixed **Enter key press** not working by adding a text field to `keyDown` events (#972)\n    -   Fixed **download command** to properly handle absolute paths and correctly click target elements (#970)\n\n    ### Breaking Changes\n\n    -   The `-C` \u002F `--cursor` flag for `snapshot` is deprecated; cursor-interactive elements are now included by default and the flag has no additional effect (#968)\n\n    ### Documentation\n\n    -   Updated `README.md` with new `network requests` filtering options and `network request \u003CrequestId>` command usage\n    -   Removed references to the deprecated `-C` \u002F `--cursor` snapshot flag from docs and command reference\n","2026-03-23T17:26:43",{"id":216,"version":217,"summary_zh":218,"released_at":219},206576,"v0.21.4","### Patch Changes\n\n-   aed466b: ### Bug Fixes\n\n    -   **Auth login readiness** - `agent-browser auth login` now navigates with `load`, waits for usable login form selectors, and uses staged username detection (targeted email\u002Fusername selectors first, then broad text-input fallback). This reduces SPA timing failures, avoids false matches on unrelated text fields, and prevents `networkidle` hangs on pages with continuous background requests.\n","2026-03-20T14:18:41",{"id":221,"version":222,"summary_zh":223,"released_at":224},206577,"v0.21.3","### Patch Changes\n\n-   6daad22: ### Bug Fixes\n\n    -   **WebSocket keepalive for remote browsers** - Added WebSocket Ping frames and TCP `SO_KEEPALIVE` to prevent CDP connections from being silently dropped by intermediate proxies (reverse proxies, load balancers, service meshes) during idle periods (#936)\n    -   **XPath selector support** - Fixed element resolution to correctly handle the `xpath=` selector prefix (#908)\n\n    ### Performance\n\n    -   **Fast-path for identical snapshots** - Short-circuits the Myers diff algorithm when comparing a snapshot to itself, avoiding unnecessary computation in retry and loop workloads where repeated identical snapshots are common (#922)\n\n    ### Documentation\n\n    -   Migrated page metadata from MDX files to `layout.tsx` (#904)\n    -   Added search functionality and color improvements to docs (#927)\n    -   Fixed desktop browser list in the iOS comparison table (#926)\n    -   Created a new `providers\u002F` section with dedicated provider pages (#928)\n","2026-03-20T13:59:38"]