{ "canonical_name": "vercel-labs/agent-browser", "compilation_id": "pack_e0027aa5427e4a5393c7a007d3e25025", "created_at": "2026-05-19T10:50:36.392626+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `npm install -g agent-browser` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "npm install -g agent-browser", "sandbox_container_image": "node:22-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "deterministic_isolated_install", "sandbox_validation_id": "sbx_ca1f498cc2c54c55b1e4598985e35bb6" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_08325e75cda09a6826e0da4b8432434a", "canonical_name": "vercel-labs/agent-browser", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/vercel-labs/agent-browser", "slug": "agent-browser", "source_packet_id": "phit_de0fa7fa46924b548afa4e51256cec61", "source_validation_id": "dval_567cd1eb369b45518f7850b5520fb183" }, "merchandising": { "best_for": "需要流程自动化能力，并使用 local_cli的用户", "github_forks": 2029, "github_stars": 32838, "one_liner_en": "Browser automation CLI for AI agents", "one_liner_zh": "Browser automation CLI for AI agents", "primary_category": { "category_id": "workflow-automation", "confidence": "high", "name_en": "Workflow Automation", "name_zh": "流程自动化", "reason": "matched_keywords:automation, agent, browser" }, "target_user": "使用 local_cli 等宿主 AI 的用户", "title_en": "agent-browser", "title_zh": "agent-browser 能力包", "visible_tags": [ { "label_en": "Browser Agents", "label_zh": "浏览器 Agent", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-browser-agents", "type": "product_domain" }, { "label_en": "Web Task Automation", "label_zh": "网页任务自动化", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-web-task-automation", "type": "user_job" }, { "label_en": "Browser Automation", "label_zh": "浏览器自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-browser-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_de0fa7fa46924b548afa4e51256cec61", "page_model": { "artifacts": { "artifact_slug": "agent-browser", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "npm install -g agent-browser", "label": "Node.js / npm · 官方安装入口", "source": "https://github.com/vercel-labs/agent-browser#readme", "verified": true } ], "display_tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "评测体系" ], "eyebrow": "流程自动化", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要流程自动化能力，并使用 local_cli的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "Browser automation CLI for AI agents" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "local_cli", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chrome 147.0 crashes with \"trap int3\" when running in docker", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_9045278ef5e043dcadccf9288477813c | https://github.com/vercel-labs/agent-browser/issues/1339 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Chrome 147.0 crashes with \"trap int3\" when running in docker", "user_impact": "可能阻塞安装或首次运行。" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Detected: Trojan:Win32/Posilod.EB!cl", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_edbde732c7a7410e96ad0fa301e4222d | https://github.com/vercel-labs/agent-browser/issues/1281 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Detected: Trojan:Win32/Posilod.EB!cl", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：snapshot -s produces duplicate elements when AX tree contains virtual nodes without backendDOMNodeId", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_ab39b89d157047e897e771d2572dfcdd | https://github.com/vercel-labs/agent-browser/issues/1338 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：snapshot -s produces duplicate elements when AX tree contains virtual nodes without backendDOMNodeId", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Feature Request: Chrome Extension-based Connection for Seamless Login State Reuse", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_0896b0b429c641f0b93ca9dcbbee6db8 | https://github.com/vercel-labs/agent-browser/issues/1319 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Feature Request: Chrome Extension-based Connection for Seamless Login State Reuse", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "Developers should check this security_permissions risk before relying on the project: Dashboard privileged POST routes should reject cross-origin requests", "category": "安全/权限坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_bc39fa851aecda51d6ae79863b570093 | https://github.com/vercel-labs/agent-browser/issues/1345 | Dashboard privileged POST routes should reject cross-origin requests" ], "severity": "high", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Dashboard privileged POST routes should reject cross-origin requests. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：security_permissions: Dashboard privileged POST routes should reject cross-origin requests", "user_impact": "Developers may expose sensitive permissions or credentials: Dashboard privileged POST routes should reject cross-origin requests" }, { "body": "Developers should check this security_permissions risk before relying on the project: `--auto-connect` fails too quickly when Chrome asks for remote debugging permission", "category": "安全/权限坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_50f6336937705c962c78ed48a466eb98 | https://github.com/vercel-labs/agent-browser/issues/1365 | `--auto-connect` fails too quickly when Chrome asks for remote debugging permission" ], "severity": "high", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: `--auto-connect` fails too quickly when Chrome asks for remote debugging permission. Context: Source discussion did not expose a precise runtime context.", "title": "失败模式：security_permissions: `--auto-connect` fails too quickly when Chrome asks for remote debugging permission", "user_impact": "Developers may expose sensitive permissions or credentials: `--auto-connect` fails too quickly when Chrome asks for remote debugging permission" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Support XDG Base Directory paths for agent-browser state, config, and installs", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_a2b8bb7035dd44e0a9e97dc78186f3b2 | https://github.com/vercel-labs/agent-browser/issues/1361 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。" ], "severity": "high", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Support XDG Base Directory paths for agent-browser state, config, and installs", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "Developers should check this installation risk before relying on the project: After failed close, subsequent open reports success but returns stale content from prior URL", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_fce1ca55e45e13ba327a52473c958037 | https://github.com/vercel-labs/agent-browser/issues/1367 | After failed close, subsequent open reports success but returns stale content from prior URL" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: After failed close, subsequent open reports success but returns stale content from prior URL. Context: Observed when using node, python, linux", "title": "失败模式：installation: After failed close, subsequent open reports success but returns stale content from prior URL", "user_impact": "Developers may fail before the first successful local run: After failed close, subsequent open reports success but returns stale content from prior URL" }, { "body": "Developers should check this installation risk before relying on the project: Chrome 147.0 crashes with \"trap int3\" when running in docker", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_de7dc45e4f45905d10cb44680cd26da5 | https://github.com/vercel-labs/agent-browser/issues/1339 | Chrome 147.0 crashes with \"trap int3\" when running in docker", "failure_mode_cluster:github_issue | fmev_e97d2c4c42c663165c2763023d5d79e3 | https://github.com/vercel-labs/agent-browser/issues/1339 | Chrome 147.0 crashes with \"trap int3\" when running in docker" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Chrome 147.0 crashes with \"trap int3\" when running in docker. Context: Observed when using docker, windows, linux", "title": "失败模式：installation: Chrome 147.0 crashes with \"trap int3\" when running in docker", "user_impact": "Developers may fail before the first successful local run: Chrome 147.0 crashes with \"trap int3\" when running in docker" }, { "body": "Developers should check this installation risk before relying on the project: Detected: Trojan:Win32/Posilod.EB!cl", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_11d6daa01783b3f8d6cc4984b34591d9 | https://github.com/vercel-labs/agent-browser/issues/1281 | Detected: Trojan:Win32/Posilod.EB!cl" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Detected: Trojan:Win32/Posilod.EB!cl. Context: Observed when using windows", "title": "失败模式：installation: Detected: Trojan:Win32/Posilod.EB!cl", "user_impact": "Developers may fail before the first successful local run: Detected: Trojan:Win32/Posilod.EB!cl" }, { "body": "Developers should check this installation risk before relying on the project: Feature: `network throttle` for emulating slow connections / per-URL delay", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_af068ec0790d0398008062aef7b5d1a5 | https://github.com/vercel-labs/agent-browser/issues/1372 | Feature: `network throttle` for emulating slow connections / per-URL delay" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Feature: `network throttle` for emulating slow connections / per-URL delay. Context: Observed during installation or first-run setup.", "title": "失败模式：installation: Feature: `network throttle` for emulating slow connections / per-URL delay", "user_impact": "Developers may fail before the first successful local run: Feature: `network throttle` for emulating slow connections / per-URL delay" }, { "body": "Developers should check this installation risk before relying on the project: High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_1ea0ed85aeff64de383d8fa15586474d | https://github.com/vercel-labs/agent-browser/issues/1351 | High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills. Context: Observed when using node, playwright, windows", "title": "失败模式：installation: High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills", "user_impact": "Developers may fail before the first successful local run: High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills" }, { "body": "Developers should check this installation risk before relying on the project: Support XDG Base Directory paths for agent-browser state, config, and installs", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_5bd8394953d7b9c8f00eade661671801 | https://github.com/vercel-labs/agent-browser/issues/1361 | Support XDG Base Directory paths for agent-browser state, config, and installs" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Support XDG Base Directory paths for agent-browser state, config, and installs. Context: Observed when using linux", "title": "失败模式：installation: Support XDG Base Directory paths for agent-browser state, config, and installs", "user_impact": "Developers may fail before the first successful local run: Support XDG Base Directory paths for agent-browser state, config, and installs" }, { "body": "Developers should check this installation risk before relying on the project: Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File via bash 2>&1)", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_issue | fmev_8b48c64a7c8bd1d363fa81928818b489 | https://github.com/vercel-labs/agent-browser/issues/1348 | Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File via bash 2>&1)" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File via bash 2>&1). Context: Observed when using node, python, windows", "title": "失败模式：installation: Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File...", "user_impact": "Developers may fail before the first successful local run: Windows 11: --headed not surfacing window when invoked from non-TTY context (PowerShell -File via bash 2>&1)" }, { "body": "Developers should check this installation risk before relying on the project: v0.27.0", "category": "安装坑", "evidence": [ "failure_mode_cluster:github_release | fmev_c5cd290a3adea233428e19624c61cbc4 | https://github.com/vercel-labs/agent-browser/releases/tag/v0.27.0 | v0.27.0" ], "severity": "medium", "suggested_check": "Before packaging this project, run the relevant install/config/quickstart check for: v0.27.0. Context: Observed when using node", "title": "失败模式：installation: v0.27.0", "user_impact": "Upgrade or migration may change expected behavior: v0.27.0" }, { "body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：After failed close, subsequent open reports success but returns stale content from prior URL", "category": "安装坑", "evidence": [ "community_evidence:github | cevd_20b2fb27e3744303957ee3b14657c6fb | https://github.com/vercel-labs/agent-browser/issues/1367 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：After failed close, subsequent open reports success but returns stale content from prior URL", "user_impact": "可能增加新用户试用和生产接入成本。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 38 个潜在踩坑项，其中 7 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chrome 147.0 crashes with \"trap int3\" when running in docker。", "title": "踩坑日志" }, "snapshot": { "contributors": 106, "forks": 2029, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": 32838 }, "source_url": "https://github.com/vercel-labs/agent-browser", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "Browser automation CLI for AI agents", "title": "agent-browser 能力包", "trial_prompt": "# agent-browser - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for vercel-labs/agent-browser.\n\nProject:\n- Name: agent-browser\n- Repository: https://github.com/vercel-labs/agent-browser\n- Summary: Browser automation CLI for AI agents\n- Host target: local_cli\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: Browser automation CLI for AI agents\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to Agent Browser. Produce one small intermediate artifact and wait for confirmation.\n2. installation-guide: Installation Guide. Produce one small intermediate artifact and wait for confirmation.\n3. element-references: Element References System. Produce one small intermediate artifact and wait for confirmation.\n4. architecture-overview: Architecture Overview. Produce one small intermediate artifact and wait for confirmation.\n5. daemon-and-cdp: Daemon and CDP Protocol. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/vercel-labs/agent-browser\n- https://github.com/vercel-labs/agent-browser#readme\n- skill-data/agentcore/SKILL.md\n- skill-data/core/SKILL.md\n- skill-data/dogfood/SKILL.md\n- skill-data/electron/SKILL.md\n- skill-data/slack/SKILL.md\n- skill-data/vercel-sandbox/SKILL.md\n- skills/agent-browser/SKILL.md\n- README.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: `--cdp` eval/open silently target a secondary execution context when Chr（https://github.com/vercel-labs/agent-browser/issues/1373）；github/github_issue: Feature: `network throttle` for emulating slow connections / per-URL del（https://github.com/vercel-labs/agent-browser/issues/1372）；github/github_issue: Orphaned headless Chrome Helpers spin at high CPU under agent-browser-ch（https://github.com/vercel-labs/agent-browser/issues/1371）；github/github_issue: snapshot -s produces duplicate elements when AX tree contains（https://github.com/vercel-labs/agent-browser/issues/1338）；github/github_issue: Support XDG Base Directory paths for agent-browser state, config, and in（https://github.com/vercel-labs/agent-browser/issues/1361）；github/github_issue: After failed close, subsequent open reports success but returns stale co（https://github.com/vercel-labs/agent-browser/issues/1367）；github/github_issue: Chrome 147.0 crashes with \"trap int3\" when running in docker（https://github.com/vercel-labs/agent-browser/issues/1339）；github/github_issue: `--auto-connect` fails too quickly when Chrome asks for remote debugging（https://github.com/vercel-labs/agent-browser/issues/1365）；github/github_issue: High LLM turn count due to frequent `snapshot` calls when using `agent-b（https://github.com/vercel-labs/agent-browser/issues/1351）；github/github_issue: Chrome 147.0 crashes with \"trap int3\" when running in docker（https://github.com/vercel-labs/agent-browser/issues/1339）；github/github_issue: Support enabling WebAuthn for passkey authentication with a virtual auth（https://github.com/vercel-labs/agent-browser/issues/688）；github/github_issue: Feature Request: Chrome Extension-based Connection for Seamless Login St（https://github.com/vercel-labs/agent-browser/issues/1319）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "`--cdp` eval/open silently target a secondary execution context when Chr", "url": "https://github.com/vercel-labs/agent-browser/issues/1373" }, { "kind": "github_issue", "source": "github", "title": "Feature: `network throttle` for emulating slow connections / per-URL del", "url": "https://github.com/vercel-labs/agent-browser/issues/1372" }, { "kind": "github_issue", "source": "github", "title": "Orphaned headless Chrome Helpers spin at high CPU under agent-browser-ch", "url": "https://github.com/vercel-labs/agent-browser/issues/1371" }, { "kind": "github_issue", "source": "github", "title": "snapshot -s produces duplicate elements when AX tree contains", "url": "https://github.com/vercel-labs/agent-browser/issues/1338" }, { "kind": "github_issue", "source": "github", "title": "Support XDG Base Directory paths for agent-browser state, config, and in", "url": "https://github.com/vercel-labs/agent-browser/issues/1361" }, { "kind": "github_issue", "source": "github", "title": "After failed close, subsequent open reports success but returns stale co", "url": "https://github.com/vercel-labs/agent-browser/issues/1367" }, { "kind": "github_issue", "source": "github", "title": "Chrome 147.0 crashes with \"trap int3\" when running in docker", "url": "https://github.com/vercel-labs/agent-browser/issues/1339" }, { "kind": "github_issue", "source": "github", "title": "`--auto-connect` fails too quickly when Chrome asks for remote debugging", "url": "https://github.com/vercel-labs/agent-browser/issues/1365" }, { "kind": "github_issue", "source": "github", "title": "High LLM turn count due to frequent `snapshot` calls when using `agent-b", "url": "https://github.com/vercel-labs/agent-browser/issues/1351" }, { "kind": "github_issue", "source": "github", "title": "Chrome 147.0 crashes with \"trap int3\" when running in docker", "url": "https://github.com/vercel-labs/agent-browser/issues/1339" }, { "kind": "github_issue", "source": "github", "title": "Support enabling WebAuthn for passkey authentication with a virtual auth", "url": "https://github.com/vercel-labs/agent-browser/issues/688" }, { "kind": "github_issue", "source": "github", "title": "Feature Request: Chrome Extension-based Connection for Seamless Login St", "url": "https://github.com/vercel-labs/agent-browser/issues/1319" } ], "status": "已收录 12 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "流程自动化", "desc": "Browser automation CLI for AI agents", "effort": "安装已验证", "forks": 2029, "icon": "bolt", "name": "agent-browser 能力包", "risk": "可发布", "slug": "agent-browser", "stars": 32838, "tags": [ "浏览器 Agent", "网页任务自动化", "浏览器自动化", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/vercel-labs/agent-browser 项目说明书\n\n生成时间：2026-05-15 11:32:46 UTC\n\n## 目录\n\n- [Introduction to Agent Browser](#introduction)\n- [Installation Guide](#installation-guide)\n- [Element References System](#element-references)\n- [Architecture Overview](#architecture-overview)\n- [Daemon and CDP Protocol](#daemon-and-cdp)\n- [Navigation Commands](#navigation-commands)\n- [Interaction Commands](#interaction-commands)\n- [State Inspection Commands](#state-inspection-commands)\n- [Browser Engine Integration](#browser-engines)\n- [Authentication and Session Persistence](#authentication)\n\n\n\n## Introduction to Agent Browser\n\n### 相关页面\n\n相关主题：[Installation Guide](#installation-guide), [Architecture Overview](#architecture-overview)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [skill-data/core/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md)\n- [skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n- [skill-data/core/references/commands.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/commands.md)\n- [skill-data/core/references/snapshot-refs.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)\n- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)\n- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n- [examples/environments/app/page.tsx](https://github.com/vercel-labs/agent-browser/blob/main/examples/environments/app/page.tsx)\n
\n\n# Introduction to Agent Browser\n\nAgent Browser is a high-performance, native Rust CLI tool designed for browser automation and AI agent integration. Unlike traditional browser automation frameworks that rely on Node.js wrappers or third-party libraries, Agent Browser communicates directly with Chrome/Chromium via the Chrome DevTools Protocol (CDP), providing a lightweight and reliable solution for web interaction tasks.\n\n## Overview\n\nAgent Browser serves as a bridge between AI agents and web browsers, enabling autonomous web navigation, interaction, and data extraction. It is compatible with a wide range of AI agent platforms including Cursor, Claude Code, Codex, Continue, and Windsurf.\n\n| Aspect | Description |\n|--------|-------------|\n| **Language** | Rust (native CLI) |\n| **Protocol** | Chrome DevTools Protocol (CDP) |\n| **Dependencies** | No Playwright or Puppeteer dependency |\n| **Platform** | Chrome/Chromium |\n| **License** | See repository LICENSE |\n\n**资料来源：** [skills/agent-browser/SKILL.md]()\n\n## Architecture\n\nAgent Browser follows a modular architecture with distinct layers for CLI handling, native browser control, and extensible skills.\n\n```mermaid\ngraph TD\n A[User / AI Agent] --> B[CLI Layer
Rust Commands]\n B --> C[Native Actions Layer
CDP Dispatcher]\n C --> D[Chrome/Chromium
via CDP]\n \n E[Skills System] --> B\n E --> F[Core Skills]\n E --> G[Specialized Skills]\n \n G --> G1[Electron Apps]\n G --> G2[Slack Workspace]\n G --> G3[Exploratory Testing]\n G --> G4[Cloud Providers]\n \n H[Session Management] --> C\n H --> H1[Auth Vault]\n H --> H2[State Persistence]\n H --> H3[Video Recording]\n```\n\n**资料来源：** [skill-data/core/SKILL.md](), [skills/agent-browser/SKILL.md]()\n\n## Core Concepts\n\n### Accessibility-Tree Snapshots\n\nAgent Browser generates accessibility-tree snapshots that provide structured, human-readable representations of web pages. Each interactive element receives a unique reference ID (e.g., `@e1`, `@e2`) that can be used for subsequent interactions.\n\nExample snapshot output:\n```\nPage: Example - Log in\nURL: https://example.com/login\n\n@e1 [heading] \"Log in\"\n@e2 [form]\n @e3 [input type=\"email\"] placeholder=\"Email\"\n @e4 [input type=\"password\"] placeholder=\"Password\"\n @e5 [button type=\"submit\"] \"Continue\"\n @e6 [link] \"Forgot password?\"\n```\n\n**资料来源：** [skill-data/core/references/snapshot-refs.md](), [skill-data/core/SKILL.md]()\n\n### Element Reference Notation\n\nElement references follow a consistent notation pattern:\n\n```\n@e1 [tag attribute=\"value\"] \"text content\" placeholder=\"hint\"\n```\n\n| Component | Description |\n|-----------|-------------|\n| `@e1` | Unique reference ID |\n| `tag` | HTML tag name |\n| `attribute=\"value\"` | Key attributes |\n| `\"text content\"` | Visible text |\n| `placeholder=\"hint\"` | Additional attributes |\n\n**资料来源：** [skill-data/core/references/snapshot-refs.md]()\n\n## Command Reference\n\n### Navigation Commands\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser open [url]` | Launch browser with optional navigation |\n| `agent-browser back` | Navigate backward |\n| `agent-browser forward` | Navigate forward |\n| `agent-browser reload` | Reload current page |\n| `agent-browser close` | Close browser |\n| `agent-browser connect ` | Connect to existing browser via CDP |\n\n**资料来源：** [skill-data/core/references/commands.md]()\n\n### Interaction Commands\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser click ` | Click an element |\n| `agent-browser fill ` | Type text into input |\n| `agent-browser select ` | Select dropdown option |\n| `agent-browser check ` | Check a checkbox |\n| `agent-browser scroll ` | Scroll page |\n\n**资料来源：** [cli/src/native/actions.rs]()\n\n### Data Retrieval Commands\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser snapshot [-i]` | Get page snapshot (interactive only with `-i`) |\n| `agent-browser screenshot [path]` | Capture screenshot |\n| `agent-browser get text ` | Get visible text |\n| `agent-browser get attr ` | Get attribute value |\n| `agent-browser get url` | Get current URL |\n| `agent-browser get title` | Get page title |\n\n**资料来源：** [cli/src/output.rs](), [cli/src/native/actions.rs]()\n\n### Network Control Commands\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser network route ` | Intercept network request |\n| `agent-browser network unroute ` | Remove interception |\n| `agent-browser network requests [--clear]` | View/clear network requests |\n| `agent-browser network har [path]` | Capture HAR file |\n\n**资料来源：** [skill-data/core/references/commands.md](), [cli/src/output.rs]()\n\n### Cookie and Storage Management\n\n```bash\nagent-browser cookies get # View all cookies\nagent-browser cookies set --url --name --value \nagent-browser cookies clear # Clear all cookies\nagent-browser storage local # Manage localStorage\nagent-browser storage session # Manage sessionStorage\n```\n\n**资料来源：** [cli/src/output.rs]()\n\n### Browser Settings Commands\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser set viewport ` | Set viewport size |\n| `agent-browser set device ` | Emulate device |\n| `agent-browser set geo ` | Set geolocation |\n| `agent-browser set offline on\\|off` | Toggle offline mode |\n| `agent-browser set headers ` | Set custom headers |\n| `agent-browser set media dark\\|light` | Set color scheme |\n\n**资料来源：** [cli/src/output.rs]()\n\n## Sessions and State Management\n\nAgent Browser supports multiple concurrent browser sessions with state persistence.\n\n```mermaid\ngraph LR\n A[Session A] --> B[State File A]\n C[Session B] --> D[State File B]\n E[Auth Vault] --> A\n E[Auth Vault] --> C\n```\n\n**Key Features:**\n\n- **Named Sessions**: `--session ` flag for multiple sessions\n- **State Persistence**: Save and restore browser state\n- **Auth Vault**: Secure credential storage\n- **Video Recording**: Capture browser activity\n\n**资料来源：** [skill-data/core/SKILL.md](), [skills/agent-browser/SKILL.md]()\n\n## Skills System\n\nAgent Browser uses an extensible skills system that provides specialized workflows for different environments.\n\n### Core Skills\n\n```bash\nagent-browser skills get core # Core workflows and common patterns\nagent-browser skills get core --full # Include full command reference\n```\n\n### Specialized Skills\n\n| Skill | Description | Command |\n|-------|-------------|---------|\n| **Electron** | Desktop app automation | `agent-browser skills get electron` |\n| **Slack** | Workspace automation | `agent-browser skills get slack` |\n| **Dogfood** | Exploratory testing/QA | `agent-browser skills get dogfood` |\n| **Vercel Sandbox** | Cloud browser in microVMs | `agent-browser skills get vercel-sandbox` |\n| **AgentCore** | AWS Bedrock cloud browsers | `agent-browser skills get agentcore` |\n\n**资料来源：** [skills/agent-browser/SKILL.md]()\n\n## React Developer Tools Integration\n\nAgent Browser includes built-in React DevTools support for debugging React applications:\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser react_tree` | View React component tree |\n| `agent-browser react_inspect` | Inspect component props/state |\n| `agent-browser react_renders_start` | Track render counts |\n| `agent-browser react_renders_stop` | Stop render tracking |\n\n**资料来源：** [cli/src/native/actions.rs](), [cli/src/react/suspense.rs]()\n\n### Suspense Boundary Analysis\n\nAgent Browser can analyze React Suspense boundaries with actionability scoring:\n\n| Blocker Kind | Weight | Actionability |\n|--------------|--------|---------------|\n| ClientHook | 7 | 90% |\n| RequestApi | 6 | 88% |\n| ServerFetch | 5 | 82% |\n| Cache | 4 | 74% |\n| Stream | 3 | 60% |\n| Unknown | 2 | 35% |\n| Framework | 1 | 18% |\n\n**资料来源：** [cli/src/react/suspense.rs]()\n\n## Dashboard Interface\n\nAgent Browser includes a web-based dashboard for visual browser management:\n\n```mermaid\ngraph TD\n A[Dashboard] --> B[Controls Panel]\n A --> C[Result Panel]\n A --> D[Network Panel]\n A --> E[Extensions Panel]\n \n B --> B1[URL Input]\n B --> B2[Mode Selector]\n B --> B3[Action Controls]\n \n C --> C1[Screenshot View]\n C --> C2[Snapshot View]\n C --> C3[Step History]\n \n D --> D1[Request List]\n D --> D2[HAR Export]\n \n E --> E1[Extension List]\n E --> E2[Extension Details]\n```\n\nThe dashboard is built with React and supports:\n\n- Resizable panels for flexible layouts\n- Theme switching (light/dark)\n- Mobile-responsive design\n- Real-time step history\n\n**资料来源：** [examples/environments/app/page.tsx](), [packages/dashboard/src/components/network-panel.tsx](), [packages/dashboard/src/components/extensions-panel.tsx]()\n\n## Best Practices\n\n### 1. Always Snapshot Before Interacting\n\n```bash\n# CORRECT - Snapshot first to get refs\nagent-browser open https://example.com\nagent-browser snapshot -i # Get refs first\nagent-browser click @e1 # Use ref\n\n# WRONG - Ref doesn't exist yet\nagent-browser open https://example.com\nagent-browser click @e1 # Will fail!\n```\n\n### 2. Re-snapshot After Navigation\n\nElement references change when the page navigates. Always take a new snapshot after clicking links or navigating to new pages.\n\n### 3. Use Sessions for Complex Workflows\n\n```bash\nagent-browser --session my-session open https://example.com\nagent-browser --session my-session snapshot -i\n# ... perform actions ...\nagent-browser --session my-session close\n```\n\n**资料来源：** [skill-data/core/references/snapshot-refs.md]()\n\n## Installation and Setup\n\n### Prerequisites\n\n- Chrome or Chromium browser installed\n- Operating system: macOS, Linux, or Windows\n\n### Installation\n\nRefer to the repository's installation instructions for your platform. Agent Browser is distributed as a native binary with no runtime dependencies.\n\n### Configuration Files\n\n| File | Purpose |\n|------|---------|\n| `~/.agent-browser/` | Default config directory |\n| Sessions | Stored in config directory |\n| Auth Vault | Encrypted credential storage |\n\n**资料来源：** [AGENTS.md]()\n\n## Summary\n\nAgent Browser provides a powerful, efficient, and AI-agent-friendly approach to browser automation. Its key differentiators include:\n\n- **Native Rust implementation** for high performance\n- **Direct CDP communication** without third-party dependencies\n- **Accessibility-tree snapshots** for reliable element targeting\n- **Session management** for complex multi-step workflows\n- **Extensible skills system** for specialized environments\n- **Built-in React DevTools** integration for debugging\n\nThese features make Agent Browser an ideal choice for AI agents, automated testing pipelines, and developer workflows requiring precise browser control.\n\n---\n\n\n\n## Installation Guide\n\n### 相关页面\n\n相关主题：[Introduction to Agent Browser](#introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/vercel-labs/agent-browser/blob/main/README.md)\n- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n- [skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n- [cli/src/flags.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)\n
\n\n# Installation Guide\n\n## Overview\n\nThe agent-browser project is a native Rust CLI tool designed for browser automation, providing AI agents with reliable web interaction capabilities. Unlike traditional browser automation tools that rely on Node.js wrappers, agent-browser delivers a fast, lightweight solution built directly in Rust with Chrome/Chromium support via Chrome DevTools Protocol (CDP). The installation process handles downloading the necessary Chrome browser binaries, setting up platform-specific binaries, and configuring dependencies for the dashboard UI.\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n## Prerequisites\n\n### System Requirements\n\nBefore installing agent-browser, ensure your system meets the following requirements:\n\n| Requirement | Details |\n|-------------|---------|\n| **Operating System** | macOS, Linux, or Windows (7 platform binaries built) |\n| **Chrome/Chromium** | Required for browser automation functionality |\n| **Rust Toolchain** | Required for building from source |\n| **Node.js/pnpm** | Required for dashboard development |\n\nThe project builds all 7 platform binaries during CI/CD, including native binaries for different architectures. Chrome is downloaded directly from Chrome for Testing during the installation process, eliminating the need for system-installed Chrome browsers.\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n### Required Dependencies\n\n| Dependency | Purpose | Installation Method |\n|------------|---------|---------------------|\n| Chrome/Chromium | Browser automation target | Auto-downloaded via `install` command |\n| Cargo/Rust | Building CLI from source | [rustup.rs](https://rustup.rs) |\n| pnpm | Dashboard package management | `npm install -g pnpm` |\n\n## Installation Methods\n\n### Method 1: npm Package Installation (Recommended)\n\nThe recommended installation method uses the npm registry for cross-platform compatibility:\n\n```bash\nnpm install -g @agent-browser/cli\n```\n\nAfter installation, you must run the setup command to download Chrome binaries:\n\n```bash\nagent-browser install\n```\n\n资料来源：[skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n\n### Method 2: Building from Source\n\nFor development or customization, build the CLI from source:\n\n```bash\n# Clone the repository\ngit clone https://github.com/vercel-labs/agent-browser.git\ncd agent-browser\n\n# Install dependencies and build\ncd cli && cargo build --release\n```\n\nThe Rust codebase architecture follows a modular structure:\n\n```graph TD\n A[cli/src/native/] --> B[daemon/]\n A --> C[actions/]\n A --> D[browser/]\n A --> E[CDP client/]\n A --> F[snapshot/]\n A --> G[state/]\n```\n\nThe `--engine` flag allows selecting between Chrome and Lightpanda browser engines, providing flexibility in automation scenarios.\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n### Method 3: Docker Installation\n\nFor containerized environments, Docker builds are supported:\n\n```bash\n# Build from the project's Dockerfile\ndocker build -t agent-browser -f docker/Dockerfile.build .\n```\n\nDocker installation is particularly useful for CI/CD pipelines and reproducible automation environments where system dependencies need to be isolated.\n\n## Post-Installation Setup\n\n### Chrome Binary Download\n\nAfter installing the CLI package, you must download the Chrome binary:\n\n```bash\nagent-browser install\n```\n\nThis command retrieves Chrome directly from Chrome for Testing, ensuring a compatible and up-to-date browser binary is available for all automation tasks. The `--download-path` flag can specify a custom location:\n\n```bash\nagent-browser --download-path /custom/path install\n```\n\n资料来源：[cli/src/flags.rs:45-49](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)\n\n### Verifying Installation\n\nVerify the installation by checking the version and available commands:\n\n```bash\nagent-browser --version\nagent-browser --help\n```\n\nThe CLI provides comprehensive command documentation through the help system:\n\n| Command | Description |\n|---------|-------------|\n| `agent-browser open ` | Open a URL in the browser |\n| `agent-browser snapshot` | Capture accessibility tree with element refs |\n| `agent-browser click @` | Click element by reference |\n| `agent-browser skills get ` | Retrieve skill documentation |\n| `agent-browser install` | Download Chrome binaries |\n\n资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n\n## Skill Documentation Loading\n\nAgent-browser uses a skill-based documentation system that loads content dynamically based on the installed version:\n\n```bash\n# Load core workflows and common patterns\nagent-browser skills get core\n\n# Include full command reference and templates\nagent-browser skills get core --full\n\n# List all available skills\nagent-browser skills list\n```\n\nAvailable specialized skills:\n\n| Skill | Purpose |\n|-------|---------|\n| `electron` | Electron desktop apps (VS Code, Slack, Discord, Figma) |\n| `slack` | Slack workspace automation |\n| `dogfood` | Exploratory testing and QA |\n| `vercel-sandbox` | Agent-browser inside Vercel Sandbox microVMs |\n| `agentcore` | AWS Bedrock AgentCore cloud browsers |\n\n资料来源：[skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n\n## Platform-Specific Considerations\n\n### macOS\n\nOn macOS, if you encounter security prompts about unsigned applications, you may need to allow the application in System Preferences > Security & Privacy, or run:\n\n```bash\nxattr -d com.apple.quarantine /path/to/agent-browser\n```\n\n### Linux\n\nLinux distributions require WebKit/GTK dependencies for Chrome. Install via your package manager:\n\n```bash\n# Debian/Ubuntu\nsudo apt-get install libgtk-3-0 libnss3\n\n# Fedora\nsudo dnf install gtk3 nss\n```\n\n### Windows\n\nWindows installations automatically configure the required runtime dependencies. Ensure Windows Subsystem for Linux (WSL) compatibility if running in hybrid environments.\n\n## Running Tests\n\nAfter installation, verify the setup by running the test suite:\n\n```bash\n# Unit tests (fast, no Chrome required)\ncd cli && cargo test\n\n# End-to-end tests (requires Chrome installed)\ncd cli && cargo test e2e -- --ignored --test-threads=1\n```\n\nThe project contains approximately 320 unit tests and 18 e2e tests. E2E tests launch real headless Chrome instances and must run serially to avoid instance contention.\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n## Troubleshooting\n\n### Chrome Download Failures\n\nIf the `install` command fails to download Chrome:\n\n1. Check network connectivity to `Chrome for Testing`\n2. Verify write permissions to the download directory\n3. Use `--download-path` to specify an alternative location with proper permissions\n\n### Permission Denied Errors\n\nEnsure the agent-browser binary has execute permissions:\n\n```bash\nchmod +x /path/to/agent-browser\n```\n\n### Engine Selection\n\nIf Chrome automation fails, try specifying the engine explicitly:\n\n```bash\nagent-browser --engine chrome open https://example.com\n```\n\nThe `--engine` flag supports Chrome (default) and Lightpanda engines for different automation scenarios.\n\n## Next Steps\n\nAfter successful installation:\n\n1. Load core skill documentation: `agent-browser skills get core --full`\n2. Open a test URL: `agent-browser open https://example.com`\n3. Capture a snapshot: `agent-browser snapshot -i`\n4. Explore specialized skills for your use case\n\n资料来源：[skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n\n---\n\n\n\n## Element References System\n\n### 相关页面\n\n相关主题：[State Inspection Commands](#state-inspection-commands), [Interaction Commands](#interaction-commands)\n\n
\nRelevant Source Files\n\n以下源码文件用于生成本页说明：\n\n- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)\n- [cli/src/commands.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/commands.rs)\n- [skill-data/core/references/snapshot-refs.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)\n- [skill-data/core/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/SKILL.md)\n
\n\n# Element References System\n\nThe Element References System is a core mechanism in agent-browser that provides stable, human-readable identifiers for DOM elements during browser automation tasks. Instead of relying on fragile CSS selectors or XPath expressions, the system assigns unique reference IDs (such as `@e1`, `@e2`) that persist across page states and can be used reliably in subsequent automation commands.\n\n## Overview\n\nElement references serve as the primary interface between automation scripts and the browser's accessibility tree. When a snapshot is taken, each interactive element receives a reference ID that can be used in commands like `click`, `fill`, `type`, and `get` without requiring re-selection.\n\n```mermaid\ngraph TD\n A[Browser Page] --> B[snapshot Command]\n B --> C[Accessibility Tree Traversal]\n C --> D[Element Identification]\n D --> E[Reference Assignment]\n E --> F[@e1 @e2 @e3 ...]\n F --> G[Automation Commands]\n G --> H[click @e1]\n G --> I[fill @e2]\n G --> J[get text @e3]\n```\n\n## Reference Notation Format\n\nElement references follow a standardized notation format that encodes element metadata:\n\n```\n@e1 [tag type=\"value\"] \"text content\" placeholder=\"hint\"\n│ │ │ │ │\n│ │ │ │ └─ Additional attributes\n│ │ │ └─ Visible text\n│ │ └─ Key attributes shown\n│ └─ HTML tag name\n└─ Unique ref ID\n```\n\n资料来源：[skill-data/core/references/snapshot-refs.md]()\n\n### Reference Components\n\n| Component | Description | Example |\n|-----------|-------------|---------|\n| `@eN` | Unique reference identifier | `@e1`, `@e42` |\n| Tag | HTML element type | `button`, `input`, `link` |\n| Type attribute | Element type classification | `type=\"email\"`, `type=\"password\"` |\n| Text content | Visible text on element | `\"Submit\"`, `\"Log in\"` |\n| Placeholder | Input placeholder text | `placeholder=\"Email\"` |\n\n## Common Reference Patterns\n\nThe snapshot system recognizes common element patterns and standardizes their reference notation:\n\n```bash\n@e1 [button] \"Submit\" # Button with text\n@e2 [input type=\"email\"] # Email input\n@e3 [input type=\"password\"] # Password input\n@e4 [a href=\"/page\"] \"Link Text\" # Anchor link\n@e5 [select] # Dropdown\n@e6 [textarea] placeholder=\"Message\" # Text area\n@e7 [div class=\"modal\"] # Container element\n@e8 [img alt=\"Logo\"] # Image with alt text\n@e9 [checkbox] checked # Checked checkbox\n@e10 [radio] selected # Selected radio button\n```\n\n资料来源：[skill-data/core/references/snapshot-refs.md]()\n\n## Snapshot Command Options\n\nThe `snapshot` command generates element references with various filtering and formatting options:\n\n```bash\nagent-browser snapshot # Full tree (verbose)\nagent-browser snapshot -i # Interactive elements only (preferred)\nagent-browser snapshot -i -u # Include href URLs on links\nagent-browser snapshot -i -c # Compact mode (no empty structural nodes)\nagent-browser snapshot -i -d 3 # Cap depth at 3 levels\nagent-browser snapshot -s \"#main\" # Scope to a CSS selector\nagent-browser snapshot -i --json # Machine-readable output\n```\n\n资料来源：[skill-data/core/SKILL.md]()\n\n### Option Reference\n\n| Option | Purpose | Use Case |\n|--------|---------|----------|\n| `-i` | Interactive elements only | Preferred for automation |\n| `-u` | Include href URLs | When link destinations matter |\n| `-c` | Compact output | Complex pages with many empty nodes |\n| `-d N` | Depth limit | Focus on specific page sections |\n| `-s SELECTOR` | CSS scope | Target specific page regions |\n| `--json` | JSON format | Programmatic processing |\n\n## Element Reference Commands\n\nElement references are used with various commands to interact with page elements:\n\n### Direct Element Commands\n\n```bash\nagent-browser click @e1 # Click element\nagent-browser click @e1 --new-tab # Click and open in new tab\nagent-browser fill @e2 \"text\" # Fill input field\nagent-browser type @e2 \"text\" # Type character by character\nagent-browser press Enter # Press key on focused element\n```\n\n### State Inspection Commands\n\n```bash\nagent-browser get text @e1 # Get visible text\nagent-browser get html @e1 # Get innerHTML\nagent-browser get attr @e1 href # Get specific attribute\nagent-browser get value @e1 # Get input value\nagent-browser get title # Get page title\nagent-browser get url # Get current URL\nagent-browser get count \".item\" # Count matching elements\n```\n\n### State Checking Commands\n\nThe `is` command verifies element states:\n\n```bash\nagent-browser is visible @e1\nagent-browser is enabled @e1\nagent-browser is checked @e1\n```\n\n资料来源：[cli/src/output.rs]()\n\n## Find Command and Locators\n\nThe `find` command provides an alternative to snapshot-based reference acquisition by locating elements using various criteria:\n\n```bash\nagent-browser find [text]\n```\n\n### Supported Locators\n\n| Locator | Description | Example |\n|---------|-------------|---------|\n| `role` | ARIA role selector | `find role button click` |\n| `text` | Text content match | `find text \"Submit\" click` |\n| `label` | Label text association | `find label \"Email\" fill` |\n| `placeholder` | Placeholder attribute | `find placeholder \"Search\"` |\n| `alt` | Alt text (images) | `find alt \"Logo\" click` |\n| `title` | Title attribute | `find title \"Help\" click` |\n| `testid` | Test identifier | `find testid \"submit-btn\" click` |\n| `first` | First matching selector | `find first button click` |\n| `last` | Last matching selector | `find last link click` |\n| `nth` | Nth matching element | `find nth 5 button click` |\n\n资料来源：[cli/src/commands.rs]()\n\n### Find Command Options\n\n| Option | Purpose |\n|--------|---------|\n| `--exact` | Perform exact string matching |\n| `--name ` | Filter by accessible name (role locator) |\n\n## Action Dispatch System\n\nElement reference commands are dispatched to handlers through the action routing system:\n\n```mermaid\ngraph LR\n A[Command Input] --> B[\"dispatch(\\\"click\\\", state)\"]\n B --> C{Match Action}\n C -->|click| D[handle_click]\n C -->|fill| E[handle_fill]\n C -->|get| F[handle_get]\n C -->|is| G[handle_is]\n C -->|find| H[handle_find]\n```\n\nThe action router maps command strings to their respective handlers in the native daemon:\n\n```rust\n\"click\" => handle_dispatch(cmd, state).await,\n\"fill\" => handle_dispatch(cmd, state).await,\n\"get\" => handle_dispatch(cmd, state).await,\n\"is\" => handle_dispatch(cmd, state).await,\n\"find\" => handle_dispatch(cmd, state).await,\n```\n\n资料来源：[cli/src/native/actions.rs]()\n\n### Available Element Actions\n\n| Action | Handler | Purpose |\n|--------|---------|---------|\n| `click` | `handle_dispatch` | Mouse click |\n| `fill` | `handle_dispatch` | Fill input with text |\n| `type` | `handle_dispatch` | Character-by-character typing |\n| `press` | `handle_dispatch` | Keyboard press |\n| `hover` | `handle_dispatch` | Mouse hover |\n| `select` | `handle_dispatch` | Select dropdown option |\n| `check` | `handle_dispatch` | Check checkbox/radio |\n| `uncheck` | `handle_dispatch` | Uncheck checkbox |\n| `focus` | `handle_dispatch` | Focus element |\n| `blur` | `handle_dispatch` | Blur element |\n\n## Iframe Support\n\nElement references automatically handle iframe content. When a snapshot is taken, iframe elements are resolved and their child accessibility trees are included inline:\n\n```bash\nagent-browser snapshot -i\n# Output:\n# @e1 [heading] \"Checkout\"\n# @e2 [Iframe] \"payment-frame\"\n# @e3 [input] \"Card number\"\n# @e4 [input] \"Expiry\"\n# @e5 [button] \"Pay\"\n# @e6 [button] \"Cancel\"\n```\n\nReferences to elements inside iframes carry frame context, allowing direct interactions without manual frame switching:\n\n```bash\nagent-browser click @e3 # Works inside iframe\nagent-browser fill @e4 \"12/25\"\n```\n\n资料来源：[skill-data/core/references/snapshot-refs.md]()\n\n## Best Practices\n\n### Always Snapshot Before Interacting\n\n```bash\n# CORRECT\nagent-browser open https://example.com\nagent-browser snapshot -i # Get refs first\nagent-browser click @e1 # Use ref\n\n# WRONG\nagent-browser open https://example.com\nagent-browser click @e1 # Ref doesn't exist yet!\n```\n\n### Re-Snapshot After Navigation\n\n```bash\nagent-browser click @e5 # Navigates to new page\nagent-browser snapshot -i # Get new refs\nagent-browser click @e1 # Use new refs\n```\n\n### Re-Snapshot After Dynamic Changes\n\n```bash\nagent-browser click @e1 # Opens dropdown\nagent-browser snapshot -i # See dropdown items\nagent-browser click @e7 # Select item\n```\n\n### Snapshot Specific Regions\n\nFor complex pages, snapshot specific areas to reduce noise:\n\n```bash\n# Snapshot just a form\nagent-browser snapshot @e9\n```\n\n## Session-Dependent References\n\nElement references are session-dependent and may vary between browser sessions. The same element on the same page might receive different reference IDs in different sessions:\n\n| Element | Typical Ref Range | How to Find |\n|---------|------------------|-------------|\n| Home tab | e10-e20 | `snapshot -i \\| grep \"Home\"` |\n| DMs tab | e10-e20 | `snapshot -i \\| grep \"DMs\"` |\n| Activity tab | e10-e20 | `snapshot -i \\| grep \"Activity\"` |\n| Search | e5-e10 | `snapshot -i \\| grep \"Search\"` |\n| More unreads | e20-e30 | `snapshot -i \\| grep \"More unreads\"` |\n| Channel refs | e30+ | `snapshot -i \\| grep \"channel-name\"` |\n\n资料来源：[skill-data/slack/references/slack-tasks.md]()\n\n## Architecture Summary\n\n```mermaid\ngraph TD\n subgraph \"CLI Layer\"\n A[User Command] --> B[commands.rs Parser]\n B --> C[Command Dispatch]\n end\n \n subgraph \"Native Daemon\"\n C --> D[actions.rs Router]\n D --> E[State Manager]\n E --> F[CDP Client]\n end\n \n subgraph \"Browser Layer\"\n F --> G[Chrome DevTools Protocol]\n G --> H[Accessibility Tree]\n end\n \n subgraph \"Reference Generation\"\n H --> I[Element ID Assignment]\n I --> J[@eN Reference Labels]\n end\n \n J --> K[Snapshot Output]\n K --> L[Automation Commands]\n```\n\nThe Element References System provides the foundation for reliable browser automation by abstracting DOM complexity behind human-readable identifiers that remain stable across page states and navigation events.\n\n---\n\n\n\n## Architecture Overview\n\n### 相关页面\n\n相关主题：[Daemon and CDP Protocol](#daemon-and-cdp), [Introduction to Agent Browser](#introduction)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [cli/src/native/mod.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/mod.rs)\n- [cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)\n- [cli/src/native/stream/websocket.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/stream/websocket.rs)\n- [cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)\n- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n- [cli/src/connection.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/connection.rs)\n
\n\n# Architecture Overview\n\nagent-browser is a Rust-based browser automation framework that provides high-performance browser control through native CDP (Chrome DevTools Protocol) communication. The system is designed for AI agent integration, enabling reliable and observable browser automation.\n\n## System Architecture\n\nThe architecture follows a layered approach with clear separation between the CLI interface, daemon process, and browser engine.\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n CLI[CLI Interface]\n Dashboard[Web Dashboard]\n end\n\n subgraph \"Daemon Layer\"\n WS[WebSocket Server]\n Dispatcher[Action Dispatcher]\n State[State Manager]\n end\n\n subgraph \"CDP Layer\"\n CDP[CDP Client]\n Protocol[Protocol Handler]\n end\n\n subgraph \"Browser Engine\"\n Chrome[Chrome/Chromium]\n Lightpanda[Lightpanda]\n end\n\n CLI --> WS\n Dashboard --> WS\n WS --> Dispatcher\n Dispatcher --> CDP\n CDP --> Chrome\n CDP --> Lightpanda\n Dispatcher --> State\n```\n\n## Core Components\n\n### Daemon Architecture\n\nThe browser automation daemon is the central coordinator that manages browser sessions and handles command dispatching. It runs as a persistent process that maintains browser state across multiple operations.\n\n**Key Responsibilities:**\n\n| Component | Responsibility |\n|-----------|----------------|\n| WebSocket Server | Accepts client connections with origin validation |\n| Action Dispatcher | Routes commands to appropriate handlers |\n| State Manager | Maintains session state and snapshots |\n| CDP Client | Manages protocol-level communication |\n\n资料来源：[cli/src/native/mod.rs]()\n\n### Action Dispatch System\n\nThe action system provides a comprehensive set of browser automation commands. Actions are dispatched based on command type and handle specific browser operations.\n\n**Action Categories:**\n\n| Category | Commands |\n|----------|----------|\n| Navigation | `goto`, `back`, `forward`, `reload`, `waitforurl`, `waitforloadstate` |\n| Interaction | `click`, `fill`, `press`, `select`, `check`, `uncheck`, `multiselect` |\n| Content | `snapshot`, `innertext`, `innerhtml`, `gettext`, `getattribute` |\n| State | `cookies_get`, `cookies_set`, `storage_get`, `storage_set` |\n| Network | `route`, `unroute`, `requests`, `har` |\n| React Debug | `react_tree`, `react_inspect`, `react_renders_start` |\n\n资料来源：[cli/src/native/actions.rs:1-50]()\n\n### CDP Client Layer\n\nThe CDP (Chrome DevTools Protocol) client handles low-level communication with the browser engine. This abstraction allows the system to work with different browser engines through a unified interface.\n\n**Supported Engines:**\n\n| Engine | Selection Flag |\n|--------|----------------|\n| Chrome/Chromium | `--engine chrome` (default) |\n| Lightpanda | `--engine lightpanda` |\n\n资料来源：[cli/src/native/mod.rs]()\n\n## Communication Protocol\n\n### WebSocket Server\n\nThe daemon exposes a WebSocket server for client communication. Security is enforced through origin validation.\n\n```mermaid\ngraph LR\n Client[Client App] -->|WebSocket| OriginCheck[Origin Check]\n OriginCheck -->|Allowed| Accept[Accept Connection]\n OriginCheck -->|Blocked| Reject[403 Forbidden]\n```\n\n**Origin Validation:**\n\nThe server validates the `Origin` header on incoming WebSocket requests. Connections from disallowed origins receive a `403 Forbidden` response before any data exchange occurs.\n\n```rust\nif !is_allowed_origin(origin.as_deref()) {\n return Err(reject); // Status: FORBIDDEN\n}\n```\n\n资料来源：[cli/src/native/stream/websocket.rs:15-30]()\n\n### Request/Response Flow\n\nAll commands follow a request-response pattern:\n\n1. Client sends JSON command via WebSocket\n2. Server validates origin\n3. Dispatcher routes to appropriate handler\n4. Handler executes CDP operation\n5. Result returned as JSON response\n\n## State Management\n\n### Session State\n\nThe daemon maintains persistent state for each browser session:\n\n| State Component | Description |\n|-----------------|-------------|\n| Tabs | Active tab list and current tab reference |\n| Frame | Current frame hierarchy |\n| Viewport | Window dimensions |\n| Recording | Video recording status |\n\n资料来源：[cli/src/native/stream/websocket.rs:5-15]()\n\n### Snapshot System\n\nThe snapshot system provides accessibility-tree based page representation with stable element references (`@e1`, `@e2`, etc.) for reliable element selection across page mutations.\n\n**Best Practice:** Always snapshot before interacting with elements, as refs change after navigation or dynamic content changes.\n\n资料来源：[skill-data/core/references/snapshot-refs.md]()\n\n## React Inspection System\n\nFor React-based applications, the daemon provides specialized inspection capabilities:\n\n### Blocker Detection\n\nThe system identifies React Suspense boundaries and classifies them by impact:\n\n| Blocker Kind | Weight | Actionability |\n|--------------|--------|---------------|\n| ClientHook | 7 | 90 |\n| RequestApi | 6 | 88 |\n| ServerFetch | 5 | 82 |\n| Cache | 4 | 74 |\n| Stream | 3 | 60 |\n| Unknown | 2 | 35 |\n| Framework | 1 | 18 |\n\n### Boundary Classification\n\n| Boundary Kind | Description |\n|---------------|-------------|\n| RouteSegment | Next.js/App Router segment boundary |\n| ExplicitSuspense | User-declared `` component |\n| Component | Implicit boundary from component structure |\n\n资料来源：[cli/src/native/react/suspense.rs:30-60]()\n\n## CLI Architecture\n\nThe CLI provides both interactive and scripted access to browser automation:\n\n### Command Structure\n\n```\nagent-browser [args]\n```\n\n**Primary Command Groups:**\n\n| Group | Purpose |\n|-------|---------|\n| `agent-browser open` | Navigate to URL |\n| `agent-browser ` | Execute automation action |\n| `agent-browser set` | Configure browser settings |\n| `agent-browser network` | Manage network interception |\n| `agent-browser state` | Save/load/restore sessions |\n| `agent-browser tab` | Manage browser tabs |\n| `agent-browser screenshot` | Capture page images |\n| `agent-browser install` | Download Chrome |\n\n资料来源：[cli/src/output.rs]()\n\n## Dashboard Architecture\n\nThe web-based dashboard provides visual monitoring and control:\n\n```mermaid\ngraph TD\n Dashboard[Dashboard App] -->|API| Daemon\n Dashboard -->|Display| Results[screenshots/snapshots]\n Dashboard -->|Controls| Form[Control Form]\n```\n\n**Dashboard Features:**\n\n- Resizable split view (controls + results)\n- Responsive layout for mobile/desktop\n- Real-time screenshot display with base64 encoding\n- Snapshot viewer with step history\n- Step-by-step playback of automation sequences\n\n资料来源：[packages/dashboard/src/components/extensions-panel.tsx]()\n\n## Installation and Dependencies\n\n### Chrome Installation\n\nThe `install` command downloads Chrome directly from Chrome for Testing:\n\n```bash\nagent-browser install\n```\n\nThis ensures the Chrome binary is available for CDP communication without requiring system-wide Chrome installation.\n\n## Testing Architecture\n\n### Unit Tests\n\nFast tests (~320) that verify individual components without Chrome dependency:\n\n```bash\ncd cli && cargo test\n```\n\n### End-to-End Tests\n\nIntegration tests that launch real headless Chrome:\n\n```bash\ncd cli && cargo test e2e -- --ignored --test-threads=1\n```\n\n**Requirements:**\n\n- Chrome must be installed\n- Tests run serially to avoid browser instance contention\n\n## Security Considerations\n\n| Aspect | Implementation |\n|--------|----------------|\n| Origin Validation | WebSocket connections validated before acceptance |\n| Session Isolation | Each session maintains separate state |\n| Credential Storage | Authentication vault for secure credential handling |\n\n## Summary\n\nagent-browser implements a clean three-tier architecture:\n\n1. **Client Layer** - CLI and dashboard provide user interfaces\n2. **Daemon Layer** - Rust-based server handles command dispatch and state\n3. **CDP Layer** - Browser-agnostic protocol client enables Chrome/Lightpanda support\n\nThe design prioritizes reliability (stable element refs), observability (snapshots, screenshots, video recording), and extensibility (skill-based system for specialized automation tasks).\n\n---\n\n\n\n## Daemon and CDP Protocol\n\n### 相关页面\n\n相关主题：[Architecture Overview](#architecture-overview), [Browser Engine Integration](#browser-engines)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [cli/src/native/cdp/client.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/cdp/client.rs)\n- [cli/src/native/cdp/chrome.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/cdp/chrome.rs)\n- [cli/src/native/stream/mod.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/stream/mod.rs)\n- [cli/src/native/stream/websocket.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/stream/websocket.rs)\n- [cli/src/native/stream/cdp_loop.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/stream/cdp_loop.rs)\n- [cli/cdp-protocol/browser_protocol.json](https://github.com/vercel-labs/agent-browser/blob/main/cli/cdp-protocol/browser_protocol.json)\n- [cli/cdp-protocol/js_protocol.json](https://github.com/vercel-labs/agent-browser/blob/main/cli/cdp-protocol/js_protocol.json)\n
\n\n# Daemon and CDP Protocol\n\n## Overview\n\nThe agent-browser project implements a native Rust-based browser automation daemon that communicates with Chrome/Chromium browsers via the Chrome DevTools Protocol (CDP). The architecture separates the automation logic from browser control through WebSocket-based CDP connections, enabling AI agents to interact with web pages through a CLI interface.\n\n**Architecture Layer Diagram:**\n\n```mermaid\ngraph TD\n A[CLI Interface] --> B[Action Dispatcher]\n B --> C[CDP Client]\n C --> D[WebSocket Stream]\n D --> E[CDP Loop Handler]\n E --> F[Chrome Browser Instance]\n \n G[CDP Protocol Files] --> F\n H[Generated CDP Types] --> C\n```\n\n## Daemon Architecture\n\n### Native Daemon Components\n\nThe daemon lives in `cli/src/native/` and handles all browser automation tasks. The main components include:\n\n| Component | Location | Purpose |\n|-----------|----------|---------|\n| Daemon | `cli/src/native/daemon/` | Process management and state coordination |\n| Actions | `cli/src/native/actions.rs` | Command handlers for browser operations |\n| Browser | `cli/src/native/browser/` | Browser instance lifecycle |\n| CDP Client | `cli/src/native/cdp/client.rs` | Protocol communication |\n| CDP Loop | `cli/src/native/stream/cdp_loop.rs` | Message processing loop |\n\n资料来源：[cli/src/native/actions.rs](cli/src/native/actions.rs)\n\n### Action Dispatch\n\nThe action handler maps command names to their implementation functions. Supported actions include:\n\n```rust\nlet result = match action {\n \"launch\" => handle_launch(cmd, state).await,\n \"navigate\" => handle_navigate(cmd, state).await,\n \"url\" => handle_url(state).await,\n \"cdp_url\" => handle_cdp_url(state),\n \"inspect\" => handle_inspect(state).await,\n \"title\" => handle_title(state).await,\n \"content\" => handle_content(state).await,\n \"evaluate\" => handle_evaluate(cmd, state).await,\n \"close\" => handle_close(state).await,\n \"snapshot\" => handle_snapshot(cmd, state).await,\n \"screenshot\" => handle_screenshot(cmd, state).await,\n \"click\" => handle_click(cmd, state).await,\n \"dblclick\" => handle_dblclick(cmd, state).await,\n \"fill\" => handle_fill(cmd, state).await,\n \"type\" => handle_type(cmd, state).await,\n \"press\" => handle_press(cmd, state).await,\n \"hover\" => handle_hover(cmd, state).await,\n \"scroll\" => handle_scroll(cmd, state).await,\n // ... additional actions\n};\n```\n\n资料来源：[cli/src/native/actions.rs:50-75](cli/src/native/actions.rs)\n\n### Browser Engine Selection\n\nThe `--engine` flag selects between Chrome and Lightpanda browsers. Chrome is downloaded from Chrome for Testing via the `install` command.\n\n## CDP Protocol Implementation\n\n### Protocol Files\n\nThe CDP protocol definitions are stored in JSON format:\n\n| File | Description |\n|------|-------------|\n| `browser_protocol.json` | Core browser domains (Page, Network, Runtime, etc.) |\n| `js_protocol.json` | JavaScript debugging domains |\n\n资料来源：[cli/cdp-protocol/browser_protocol.json](cli/cdp-protocol/browser_protocol.json)\n\n### Auto-Generated Types\n\nCDP types are auto-generated from protocol JSON files:\n\n```rust\n/// Auto-generated CDP types from protocol JSON files in `cdp-protocol/`.\n///\n/// To populate: download `browser_protocol.json` and `js_protocol.json` from\n/// (or any\n/// Chromium source) into `cli/cdp-protocol/` and rebuild.\n#[allow(clippy::upper_case_acronyms)]\npub mod generated {\n include!(concat!(env!(\"OUT_DIR\"), \"/cdp_generated.rs\"));\n}\n```\n\n资料来源：[cli/src/native/cdp/types.rs](cli/src/native/cdp/types.rs)\n\n### CDP Client Structure\n\nThe CDP client manages communication with the browser:\n\n```mermaid\ngraph LR\n A[Command] --> B[CDP Client]\n B --> C[WebSocket Writer]\n C --> D[Browser CDP Endpoint]\n \n E[Browser Events] --> F[WebSocket Reader]\n F --> G[Event Handler]\n G --> H[State Updates]\n```\n\n## WebSocket Communication\n\n### Stream Module Architecture\n\nThe WebSocket communication is handled by the stream module located in `cli/src/native/stream/`:\n\n| Module | File | Purpose |\n|--------|------|---------|\n| Stream Core | `cli/src/native/stream/mod.rs` | Stream trait definitions and utilities |\n| WebSocket | `cli/src/native/stream/websocket.rs` | WebSocket connection handling |\n| CDP Loop | `cli/src/native/stream/cdp_loop.rs` | CDP message processing loop |\n\n### WebSocket Connection\n\nThe WebSocket module establishes and maintains connections to the Chrome DevTools endpoint:\n\n```mermaid\nsequenceDiagram\n participant CLI as CLI Command\n participant Client as CDP Client\n participant WS as WebSocket\n participant Chrome as Chrome Browser\n \n CLI->>Client: connect(url)\n Client->>WS: establish_connection()\n WS->>Chrome: WebSocket Handshake\n Chrome-->>WS: 101 Switching Protocols\n WS-->>Client: Connected\n \n loop Message Exchange\n CLI->>Client: send_command()\n Client->>WS: write_message()\n WS->>Chrome: CDP JSON Message\n Chrome-->>WS: CDP Response/Event\n WS-->>Client: read_message()\n Client-->>CLI: Result\n end\n```\n\n### CDP Loop Handler\n\nThe CDP loop processes incoming messages and manages the event queue:\n\n- Handles CDP events from the browser\n- Routes responses to pending command callbacks\n- Manages connection state and reconnection logic\n\n资料来源：[cli/src/native/stream/cdp_loop.rs](cli/src/native/stream/cdp_loop.rs)\n\n## Browser Connection\n\n### Connection Methods\n\nThe daemon supports multiple connection methods:\n\n| Method | Command | Use Case |\n|--------|---------|----------|\n| Launch new browser | `agent-browser open` | Fresh browser instance |\n| Connect to existing | `agent-browser connect 9222` | Attach to running browser |\n\n```bash\n# Launch with navigation\nagent-browser open \n\n# Connect to running browser on specific port\nagent-browser connect 9222\n\n# Launch without navigation (clean slate)\nagent-browser open\n```\n\n### CDP WebSocket URL\n\nThe CDP WebSocket URL can be retrieved programmatically:\n\n```bash\nagent-browser cdp_url\n```\n\nThis returns the WebSocket debugger URL for programmatic browser attachment.\n\n### Browser Version Info\n\nThe connection retrieves browser metadata:\n\n```rust\n#[derive(Deserialize)]\n#[serde(rename_all = \"camelCase\")]\npub struct BrowserVersionInfo {\n #[serde(rename = \"webSocketDebuggerUrl\")]\n pub web_socket_debugger_url: Option,\n #[serde(rename = \"Browser\")]\n pub browser: Option,\n}\n```\n\n资料来源：[cli/src/native/cdp/types.rs](cli/src/native/cdp/types.rs)\n\n## CDP Protocol Domains\n\n### Supported Domains\n\nThe agent-browser supports CDP domains for:\n\n| Domain | Purpose | Key Commands |\n|--------|---------|--------------|\n| Page | Page navigation and loading | navigate, reload, back, forward |\n| Runtime | JavaScript execution | evaluate, callFunctionOn |\n| DOM | DOM manipulation | getDocument, describeNode |\n| Input | User input simulation | dispatchEvent, insertText |\n| Network | Network request interception | setRequestInterception, getResponseBody |\n| Target | Browser target management | createTarget, attachToTarget |\n\n### Browser Automation Actions\n\nThe following high-level actions are available via CDP:\n\n```bash\n# Navigation\nagent-browser open \nagent-browser back\nagent-browser forward\nagent-browser reload\n\n# DOM Interaction\nagent-browser click @e1\nagent-browser fill @e2 \"text\"\nagent-browser type @e3 \"input\"\nagent-browser hover @e4\nagent-browser scroll down 500\n\n# State Queries\nagent-browser snapshot\nagent-browser screenshot\nagent-browser get text @e1\nagent-browser get attr @e1 href\n\n# JavaScript\nagent-browser evaluate \"document.title\"\n```\n\n## Error Handling\n\n### WebDriver Fallback\n\nThe daemon gracefully handles unsupported actions when using WebDriver backend:\n\n```rust\nErr(anyhow::anyhow!(\n \"Action '{}' is not supported on the WebDriver backend\",\n action\n))\n```\n\n### CDP Error Propagation\n\nCDP errors are propagated through the action chain, enabling detailed error messages for debugging failed browser operations.\n\n## Performance Considerations\n\n### Session Management\n\n- Each browser session maintains a persistent CDP connection\n- Sessions can be named and persisted for multi-session workflows\n- State persistence allows resuming automation tasks\n\n### Network Idle Detection\n\nThe daemon supports waiting for network idle states:\n\n```bash\nagent-browser wait --load networkidle\n```\n\nThis is essential for SPAs and applications with dynamic content loading.\n\n## Security Model\n\n### Credential Management\n\nThe daemon provides a secure credential vault for browser authentication:\n\n```bash\nagent-browser set credentials \n```\n\n### Cookie Management\n\nCookies can be set from various formats:\n\n```bash\nagent-browser cookies set --curl [--domain ]\n```\n\nAuto-detects JSON, cURL, and Cookie-header file formats.\n\n## Extension Points\n\n### Custom CDP Scripts\n\nExecute arbitrary JavaScript in the browser context:\n\n```bash\nagent-browser addscript