{ "canonical_name": "vercel-labs/agent-browser", "compilation_id": "pack_dd5fe8929e3a4fa096de4e58ed6d58b5", "created_at": "2026-05-13T13:58:04.305731+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 社区证据显示该项目存在一个运行相关的待验证问题：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": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ERR_NO_SUPPORTED_PROXIES when proxy environment variables contain trailing slash", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_32ddde976ec0445da607d0adffc5df4c | https://github.com/vercel-labs/agent-browser/issues/1349 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：ERR_NO_SUPPORTED_PROXIES when proxy environment variables contain trailing slash", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v0.25.5", "category": "配置坑", "evidence": [ "community_evidence:github | cevd_d5d23fc6d09149fbb21ee500e7a328ec | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.5 | 来源类型 github_release 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.25.5", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.25.2", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_777821422c534a2881b58523db3ac2f3 | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.2 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.25.2", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：v0.25.3", "category": "运行坑", "evidence": [ "community_evidence:github | cevd_5c7d80190d7548b6ad87152255949f2b | https://github.com/vercel-labs/agent-browser/releases/tag/v0.25.3 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。", "title": "来源证据：v0.25.3", "user_impact": "可能增加新用户试用和生产接入成本。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | github_repo:1132001614 | https://github.com/vercel-labs/agent-browser | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dashboard privileged POST routes should reject cross-origin requests", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_6acd97eb554140c28938a0eb08e44c34 | https://github.com/vercel-labs/agent-browser/issues/1345 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Dashboard privileged POST routes should reject cross-origin requests", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Harden inspect-mode DevTools WebSocket handshakes", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_ab6c062eedaf466d8f40864ca24bf8ea | https://github.com/vercel-labs/agent-browser/issues/1347 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Harden inspect-mode DevTools WebSocket handshakes", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_648ff78f18f34d51a44b9176d011738f | https://github.com/vercel-labs/agent-browser/issues/1351 | 来源讨论提到 node 相关条件，需在安装/试用前复核。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：High LLM turn count due to frequent `snapshot` calls when using `agent-browser` skills", "user_impact": "可能影响授权、密钥配置或安全边界。" }, { "body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Per-session /api/command should require same-origin or token auth", "category": "安全/权限坑", "evidence": [ "community_evidence:github | cevd_d21bab57490142daba6d89ed22776087 | https://github.com/vercel-labs/agent-browser/issues/1344 | 来源类型 github_issue 暴露的待验证使用条件。" ], "severity": "medium", "suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。", "title": "来源证据：Per-session /api/command should require same-origin or token auth", "user_impact": "可能影响授权、密钥配置或安全边界。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 23 个潜在踩坑项，其中 3 个为 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> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 agent-browser 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的流程自动化任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 多宿主安装与分发: 项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 输入：宿主 AI 工具, 插件配置, 安装命令；输出：宿主内可发现的插件/技能集合。\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. architecture-overview：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. cli-commands：CLI 命令参考。围绕“CLI 命令参考”模拟一次用户任务，不展示安装或运行结果。\n4. browser-automation：浏览器自动化核心。围绕“浏览器自动化核心”模拟一次用户任务，不展示安装或运行结果。\n5. sessions-authentication：会话与认证管理。围绕“会话与认证管理”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. architecture-overview\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. cli-commands\n输入：用户提供的“CLI 命令参考”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. browser-automation\n输入：用户提供的“浏览器自动化核心”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. sessions-authentication\n输入：用户提供的“会话与认证管理”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / architecture-overview：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / cli-commands：Step 3 必须围绕“CLI 命令参考”形成一个小中间产物，并等待用户确认。\n- Step 4 / browser-automation：Step 4 必须围绕“浏览器自动化核心”形成一个小中间产物，并等待用户确认。\n- Step 5 / sessions-authentication：Step 5 必须围绕“会话与认证管理”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\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- package.json\n- pnpm-workspace.yaml\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 agent-browser 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n", "voices": [ { "body": "来源平台：github。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）；github/github_issue: ERR_NO_SUPPORTED_PROXIES when proxy environment variables contain traili（https://github.com/vercel-labs/agent-browser/issues/1349）；github/github_issue: Windows 11: --headed not surfacing window when invoked from non-TTY cont（https://github.com/vercel-labs/agent-browser/issues/1348）；github/github_issue: Harden inspect-mode DevTools WebSocket handshakes（https://github.com/vercel-labs/agent-browser/issues/1347）；github/github_issue: Dashboard privileged POST routes should reject cross-origin requests（https://github.com/vercel-labs/agent-browser/issues/1345）；github/github_issue: Per-session /api/command should require same-origin or token auth（https://github.com/vercel-labs/agent-browser/issues/1344）；github/github_issue: Detected: Trojan:Win32/Posilod.EB!cl（https://github.com/vercel-labs/agent-browser/issues/1281）；github/github_release: v0.27.0（https://github.com/vercel-labs/agent-browser/releases/tag/v0.27.0）；github/github_release: v0.26.0（https://github.com/vercel-labs/agent-browser/releases/tag/v0.26.0）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "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" }, { "kind": "github_issue", "source": "github", "title": "ERR_NO_SUPPORTED_PROXIES when proxy environment variables contain traili", "url": "https://github.com/vercel-labs/agent-browser/issues/1349" }, { "kind": "github_issue", "source": "github", "title": "Windows 11: --headed not surfacing window when invoked from non-TTY cont", "url": "https://github.com/vercel-labs/agent-browser/issues/1348" }, { "kind": "github_issue", "source": "github", "title": "Harden inspect-mode DevTools WebSocket handshakes", "url": "https://github.com/vercel-labs/agent-browser/issues/1347" }, { "kind": "github_issue", "source": "github", "title": "Dashboard privileged POST routes should reject cross-origin requests", "url": "https://github.com/vercel-labs/agent-browser/issues/1345" }, { "kind": "github_issue", "source": "github", "title": "Per-session /api/command should require same-origin or token auth", "url": "https://github.com/vercel-labs/agent-browser/issues/1344" }, { "kind": "github_issue", "source": "github", "title": "Detected: Trojan:Win32/Posilod.EB!cl", "url": "https://github.com/vercel-labs/agent-browser/issues/1281" }, { "kind": "github_release", "source": "github", "title": "v0.27.0", "url": "https://github.com/vercel-labs/agent-browser/releases/tag/v0.27.0" }, { "kind": "github_release", "source": "github", "title": "v0.26.0", "url": "https://github.com/vercel-labs/agent-browser/releases/tag/v0.26.0" } ], "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-13 13:40:16 UTC\n\n## 目录\n\n- [项目介绍](#introduction)\n- [系统架构](#architecture-overview)\n- [CLI 命令参考](#cli-commands)\n- [浏览器自动化核心](#browser-automation)\n- [React 组件审查](#react-introspection)\n- [会话与认证管理](#sessions-authentication)\n- [网络监控与拦截](#network-monitoring)\n- [仪表板组件](#dashboard-components)\n- [文档站点](#documentation-site)\n- [安装与构建](#installation-build)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[系统架构](#architecture-overview), [CLI 命令参考](#cli-commands)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.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- [skills/agent-browser/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n- [skill-data/dogfood/SKILL.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.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- [cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)\n
\n\n# 项目介绍\n\n## 概述\n\nagent-browser 是由 Vercel Labs 开发的高性能浏览器自动化工具，采用 Rust 原生实现，不依赖 Node.js 包装层。它通过 Chrome DevTools Protocol (CDP) 直接控制 Chrome/Chromium 浏览器，提供无障碍树快照（Accessibility Tree Snapshot）技术和元素引用系统，实现可靠的浏览器交互能力。资料来源：[skill-data/core/references/snapshot-refs.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)\n\n## 核心特性\n\n### 技术架构\n\n| 特性 | 说明 |\n|------|------|\n| 实现语言 | Rust 原生代码 |\n| 浏览器引擎 | Chrome/Chromium via CDP |\n| 无依赖 | 无需 Playwright 或 Puppeteer |\n| 会话管理 | 支持多会话、状态持久化 |\n| 认证存储 | 内置认证库（Authentication Vault） |\n| 视频录制 | 支持操作过程录制 |\n| 引擎选择 | 支持 `--engine` 切换 Chrome 与 Lightpanda |\n\n资料来源：[AGENTS.md:43-46](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n### 跨平台兼容性\n\nagent-browser 可与任意 AI Agent 配合使用，包括 Cursor、Claude Code、Codex、Continue、Windsurf 等主流工具。它提供了标准化的 CLI 接口，使 AI Agent 能够通过自然语言指令控制浏览器完成复杂任务。资料来源：[skills/agent-browser/SKILL.md:15-19](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n\n## 系统架构\n\n### 架构组件\n\n```mermaid\ngraph TD\n A[AI Agent] --> B[agent-browser CLI]\n B --> C[Browser Automation Daemon]\n C --> D[CDP Client]\n D --> E[Chrome/Chromium]\n \n C --> F[Snapshot Engine]\n C --> G[State Manager]\n C --> H[React DevTools Hook]\n \n F --> I[Accessibility Tree]\n G --> J[Session Storage]\n G --> K[Auth Vault]\n \n L[Dashboard] --> C\n L --> M[Extensions Panel]\n L --> N[Network Panel]\n```\n\n### 核心模块\n\n项目的核心代码位于 `cli/src/native/` 目录下，包含以下关键模块：\n\n| 模块 | 路径 | 功能 |\n|------|------|------|\n| daemon | `cli/src/native/` | 守护进程，处理命令调度 |\n| actions | `cli/src/native/actions.rs` | 浏览器操作动作处理 |\n| browser | `cli/src/native/` | 浏览器实例管理 |\n| CDP client | `cli/src/native/` | Chrome DevTools Protocol 通信 |\n| snapshot | `cli/src/native/` | 无障碍树快照生成 |\n| state | `cli/src/native/` | 会话状态管理 |\n| react | `cli/src/native/react/` | React 开发者工具集成 |\n\n资料来源：[AGENTS.md:43](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n## 命令体系\n\n### 核心命令分类\n\nagent-browser 提供模块化的命令体系，涵盖浏览器操作的各个方面：\n\n```mermaid\ngraph TD\n A[agent-browser] --> B[导航命令]\n A --> C[元素交互]\n A --> D[浏览器设置]\n A --> E[网络控制]\n A --> F[存储管理]\n A --> G[React工具]\n \n B --> B1[open/goto]\n B --> B2[back/forward]\n B --> B3[reload/pushstate]\n \n C --> C1[click/tap]\n C --> C2[fill/setvalue]\n C --> C3[snapshot/innertext]\n C --> C4[find/highlight]\n \n D --> D1[viewport/device]\n D --> D2[timezone/locale]\n D --> D3[geolocation/permissions]\n```\n\n### 常用命令速查\n\n| 命令 | 说明 | 示例 |\n|------|------|------|\n| `open ` | 启动并导航 | `agent-browser open https://example.com` |\n| `snapshot` | 获取无障碍树快照 | `agent-browser snapshot -i` |\n| `click @e1` | 通过引用点击元素 | `agent-browser click @e1` |\n| `screenshot` | 截图 | `agent-browser screenshot --annotate output.png` |\n| `find` | 查找元素 | `agent-browser find role button Submit` |\n| `network route` | 拦截网络请求 | `agent-browser network route * --abort --resource-type script` |\n| `cookies` | 管理 Cookie | `agent-browser cookies set --curl file.curl` |\n\n资料来源：[cli/src/output.rs:1-30](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n\n## 元素引用系统\n\n### 快照与引用机制\n\nagent-browser 的核心创新在于其无障碍树快照和元素引用系统。用户必须先获取快照才能进行元素交互，确保引用始终有效：\n\n```bash\n# 正确流程\nagent-browser open https://example.com\nagent-browser snapshot -i # 先获取引用\nagent-browser click @e1 # 使用引用\n\n# 错误流程\nagent-browser open https://example.com\nagent-browser click @e1 # 引用尚未存在！\n```\n\n资料来源：[skill-data/core/references/snapshot-refs.md:1-15](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)\n\n### 引用格式\n\n引用格式清晰展示元素的关键属性：\n\n```\n@e1 [button] \"Submit\" # 按钮元素\n@e2 [input type=\"email\"] # 邮箱输入框\n@e3 [div role=\"article\"] \"标题文本\" # 文章容器\n```\n\n## 专精技能\n\n### 技能体系架构\n\n```mermaid\ngraph LR\n A[agent-browser skills] --> B[core]\n A --> C[electron]\n A --> D[slack]\n A --> E[dogfood]\n A --> F[vercel-sandbox]\n A --> G[agentcore]\n```\n\n### 技能说明\n\n| 技能 | 用途 | 使用命令 |\n|------|------|----------|\n| core | 核心工作流和通用模式 | `agent-browser skills get core` |\n| electron | Electron 桌面应用自动化 | `agent-browser skills get electron` |\n| slack | Slack 工作区自动化 | `agent-browser skills get slack` |\n| dogfood | 探索性测试 / QA / Bug 追踪 | `agent-browser skills get dogfood` |\n| vercel-sandbox | Vercel Sandbox 微虚拟机环境 | `agent-browser skills get vercel-sandbox` |\n| agentcore | AWS Bedrock AgentCore 云浏览器 | `agent-browser skills get agentcore` |\n\n资料来源：[skills/agent-browser/SKILL.md:5-25](https://github.com/vercel-labs/agent-browser/blob/main/skills/agent-browser/SKILL.md)\n\n## React 开发者工具\n\n### React 渲染分析\n\nagent-browser 集成了 React 开发者工具，能够分析 React 应用的渲染状态和性能瓶颈：\n\n```rust\n// React 挂起状态类型权重\npub enum SuspendType {\n ClientHook => 7, // 最高优先级\n RequestApi => 6,\n ServerFetch => 5,\n Cache => 4,\n Stream => 3,\n Unknown => 2,\n Framework => 1, // 最低优先级\n}\n```\n\n### 阻塞组件识别\n\n系统通过 `BoundaryKind` 分类识别阻塞渲染的组件类型：\n\n| 类型 | 说明 | 权重 |\n|------|------|------|\n| RouteSegment | 路由段边界 | 3 |\n| ExplicitSuspense | 显式 Suspense 边界 | 2 |\n| Component | 普通组件 | 1 |\n\n资料来源：[cli/src/native/react/suspense.rs:1-50](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)\n\n## 可观测性仪表板\n\n### Dashboard 功能\n\nDashboard 提供了完整的浏览器状态可视化界面：\n\n```mermaid\ngraph TD\n A[Dashboard] --> B[Extensions Panel]\n A --> C[Network Panel]\n A --> D[Snapshot Display]\n A --> E[Step Indicators]\n \n B --> B1[Extension List]\n B --> B2[Extension Details]\n \n C --> C1[Request List]\n C --> C2[HAR Export]\n C --> C3[Request Details]\n```\n\n### 面板功能\n\n| 面板 | 功能 |\n|------|------|\n| Extensions Panel | 列出已加载的 Chrome 扩展，显示描述和路径 |\n| Network Panel | 监控网络请求，支持 HAR 导出和请求详情查看 |\n| Snapshot Display | 展示无障碍树快照，支持步骤折叠展示 |\n| Step Indicators | 显示执行步骤的详细信息 |\n\n资料来源：[packages/dashboard/src/components/extensions-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/extensions-panel.tsx)\n\n## 安装与配置\n\n### 安装命令\n\n```bash\n# 安装 agent-browser\nagent-browser install\n\n# Chrome 自动下载\n# 从 Chrome for Testing 直接获取\n```\n\n### 预导航设置\n\n支持在首次导航前进行环境配置：\n\n```bash\nagent-browser batch \\\n '[\"open\"]' \\\n '[\"network\",\"route\",\"*\",\"--abort\",\"--resource-type\",\"script\"]' \\\n '[\"cookies\",\"set\",\"--curl\",\"cookies.curl\",\"--domain\",\"localhost\"]' \\\n '[\"navigate\",\"http://localhost:3000/target\"]'\n```\n\n资料来源：[skill-data/core/references/commands.md:20-35](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/commands.md)\n\n## 测试体系\n\n### 测试类型\n\n| 测试类型 | 命令 | 说明 |\n|----------|------|------|\n| 单元测试 | `cd cli && cargo test` | 快速测试，约 320 个测试用例，无需 Chrome |\n| 端到端测试 | `cd cli && cargo test e2e -- --ignored --test-threads=1` | 18 个 e2e 测试，启动真实 Chrome 实例 |\n\n### 测试要求\n\n- Chrome 必须已安装\n- e2e 测试必须串行运行 (`--test-threads=1`) 以避免 Chrome 实例冲突\n\n资料来源：[AGENTS.md:52-62](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n## 发布流程\n\n### 发布自动化\n\nCI 系统在 PR 合并后自动执行以下操作：\n\n1. 比较 `package.json` 版本与 npm 版本\n2. 构建全部 7 个平台的二进制文件\n3. 发布到 npm\n4. 自动创建 GitHub Release\n\n### 版本同步\n\n```bash\npnpm version:sync\n```\n\n此命令会同步更新 `cli/Cargo.toml`、`cli/Cargo.lock` 和 `packages/dashboard/package.json` 中的版本号。\n\n资料来源：[AGENTS.md:15-35](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n## 使用场景\n\n### 探索性测试与 QA\n\n支持完整的操作录制和问题追踪：\n\n```bash\nagent-browser --session {SESSION} record start\n# 执行测试步骤\nagent-browser --session {SESSION} screenshot --annotate issue-{NNN}.png\nagent-browser --session {SESSION} record stop\n```\n\n### Slack 工作区自动化\n\n针对 Slack 的专业技能支持消息监控、反应追踪和搜索功能：\n\n```bash\nagent-browser snapshot --json > conversation.json\nagent-browser click @e_reaction_button\nagent-browser screenshot reactions.png\n```\n\n资料来源：[skill-data/dogfood/SKILL.md:50-70](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/dogfood/SKILL.md)\n\n## 技术栈总结\n\n```mermaid\ngraph TD\n A[agent-browser] --> B[Rust Core]\n A --> C[TypeScript Dashboard]\n A --> D[React Components]\n A --> E[Node.js CLI Wrapper]\n \n B --> F[CDP Protocol]\n B --> G[Browser Automation]\n B --> H[React DevTools]\n \n C --> I[shadcn/ui]\n C --> J[Tailwind CSS]\n \n D --> K[Next.js]\n```\n\n| 层级 | 技术 | 位置 |\n|------|------|------|\n| 核心引擎 | Rust | `cli/src/native/` |\n| CLI 接口 | TypeScript | `cli/src/` |\n| 仪表板 | React + Next.js | `packages/dashboard/` |\n| UI 组件 | shadcn/ui | `packages/dashboard/src/components/` |\n| 样式 | Tailwind CSS | 项目全局 |\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目介绍](#introduction), [浏览器自动化核心](#browser-automation), [仪表板组件](#dashboard-components)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [cli/Cargo.toml](https://github.com/vercel-labs/agent-browser/blob/main/cli/Cargo.toml)\n- [cli/src/main.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/main.rs)\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/interaction.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/interaction.rs)\n- [cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)\n- [packages/dashboard/src/components/chat-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/chat-panel.tsx)\n- [packages/dashboard/src/components/extensions-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/extensions-panel.tsx)\n- [packages/dashboard/src/components/network-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/network-panel.tsx)\n- [packages/dashboard/src/components/console-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/console-panel.tsx)\n- [AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n- [cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n
\n\n# 系统架构\n\n## 概述\n\nagent-browser 是一个基于 Rust 的浏览器自动化工具，通过命令行界面和可视化仪表盘提供对浏览器的远程控制能力。该项目采用客户端-守护进程架构，支持 Chrome 和 Lightpanda 两种渲染引擎，并提供丰富的交互 API 用于网页自动化任务。\n\n架构的核心设计理念是将浏览器控制逻辑封装在 Rust 原生守护进程中，通过 CLI 命令或 Web 仪表盘与之通信，实现高效、可扩展的浏览器自动化解决方案。\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n---\n\n## 整体架构\n\nagent-browser 采用分层架构设计，主要分为以下几个层次：\n\n| 层次 | 技术栈 | 职责 |\n|------|--------|------|\n| CLI 层 | Rust | 命令行入口，解析用户命令并转发至守护进程 |\n| 守护进程层 | Rust | 浏览器实例管理、CDP 通信、状态维护 |\n| 渲染引擎层 | Chrome/Lightpanda | 实际页面渲染和执行 |\n| 仪表盘层 | React/Next.js | 可视化控制界面和结果展示 |\n| 技能数据层 | Markdown | 领域特定的操作指南和参考文档 |\n\n资料来源：[cli/src/main.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/main.rs)\n\n### 核心模块划分\n\n```mermaid\ngraph TD\n A[CLI 命令行] --> B[命令分发器]\n B --> C[Native 守护进程]\n C --> D[浏览器引擎]\n C --> E[CDP 客户端]\n C --> F[状态管理]\n \n G[Web 仪表盘] --> H[WebSocket/HTTP]\n H --> C\n \n D --> I[快照系统]\n D --> J[交互系统]\n D --> K[React 检查]\n \n style A fill:#e1f5fe\n style G fill:#fff3e0\n style D fill:#f3e5f5\n```\n\n---\n\n## 守护进程架构\n\n守护进程（Daemon）是系统的核心组件，负责管理浏览器生命周期和执行各种自动化操作。\n\n### 核心子模块\n\n| 模块 | 文件路径 | 功能描述 |\n|------|----------|----------|\n| daemon | cli/src/native/mod.rs | 主进程管理和命令路由 |\n| actions | cli/src/native/actions.rs | 具体操作实现（点击、滚动、截图等）|\n| interaction | cli/src/native/interaction.rs | 键盘和鼠标交互处理 |\n| browser | cli/src/native/ | 浏览器实例管理 |\n| CDP client | cli/src/native/ | Chrome DevTools Protocol 通信 |\n| snapshot | cli/src/native/ | 页面快照生成 |\n| state | cli/src/native/ | 会话状态维护 |\n\n资料来源：[cli/src/native/mod.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/mod.rs)\n\n### 命令处理流程\n\n守护进程接收命令后，通过分发器（Dispatcher）将请求路由到对应的处理函数：\n\n```mermaid\ngraph LR\n A[输入命令] --> B[命令解析]\n B --> C{命令类型判断}\n C -->|点击| D[handle_tap]\n C -->|滚动| E[handle_scroll]\n C -->|截图| F[handle_screenshot]\n C -->|快照| G[handle_snapshot]\n C -->|输入| H[handle_setvalue]\n C -->|键盘| I[handle_key]\n D --> J[执行结果]\n E --> J\n F --> J\n G --> J\n H --> J\n I --> J\n```\n\n支持的命令类型包括：\n\n- **导航命令**: open, close, goto, back, forward, reload\n- **交互命令**: click, tap, scroll, hover, drag, mouse, press, type\n- **查询命令**: snapshot, screenshot, get, find, count, styles, innertext, innerhtml\n- **设置命令**: set, viewport, device, timezone, locale, geolocation, permissions\n- **网络命令**: network, cookies, storage, har\n- **扩展命令**: addscript, addinitscript, removeinitscript, addstyle\n- **React 检查**: react_tree, react_inspect, react_renders_start\n\n资料来源：[cli/src/native/actions.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/actions.rs)\n\n---\n\n## 交互系统\n\n交互模块负责处理用户与浏览器页面的所有交互操作，包括鼠标、键盘和各种输入设备。\n\n### 键盘映射\n\n交互系统维护了完整的键盘映射表，支持标准键位和虚拟键码：\n\n```mermaid\ngraph TD\n A[按键输入] --> B{按键类型}\n B -->|功能键| C[特殊处理]\n B -->|方向键| D[Arrow映射]\n B -->|普通键| E[字符转换]\n \n C --> F[返回 key, code, keyCode]\n D --> F\n E --> G[char_to_key_info]\n G --> F\n```\n\n支持的键位映射：\n\n| 输入 | 键名 | 键码 |\n|------|------|------|\n| arrowup, up | ArrowUp | 38 |\n| arrowdown, down | ArrowDown | 40 |\n| arrowleft, left | ArrowLeft | 37 |\n| arrowright, right | ArrowRight | 39 |\n| home | Home | 36 |\n| end | End | 35 |\n| pageup | PageUp | 33 |\n| pagedown | PageDown | 34 |\n| space, 空格 | Space | 32 |\n\n资料来源：[cli/src/native/interaction.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/interaction.rs)\n\n### 鼠标操作\n\n鼠标操作支持以下子命令：\n\n| 操作 | 说明 |\n|------|------|\n| move \\ \\ | 移动鼠标到指定坐标 |\n| down [btn] | 按下鼠标按钮 |\n| up [btn] | 释放鼠标按钮 |\n| wheel \\ [dx] | 滚动鼠标滚轮 |\n\n---\n\n## 快照与元素引用系统\n\n快照系统是 agent-browser 的核心功能之一，用于获取页面当前状态并生成可引用元素标识符。\n\n### 快照格式\n\n快照输出包含元素引用（ref）和关键属性：\n\n```\n@e1 [button] \"Submit\" # 按钮元素\n@e2 [input type=\"email\"] # 输入框\n@e3 [div class=\"container\"] \"内容文本\" # 容器元素\n```\n\n引用格式说明：\n\n```\n@e1 [tag type=\"value\"] \"text content\" placeholder=\"hint\"\n│ │ │ │ │\n│ │ │ │ └── 额外属性\n│ │ │ └── 可见文本内容\n│ │ └── 关键属性\n│ └── HTML 标签名\n└── 唯一引用 ID\n```\n\n### 元素定位方式\n\n| 定位器 | 说明 | 示例 |\n|--------|------|------|\n| role | ARIA 角色 | role=button |\n| text | 文本内容 | text=\"Submit\" |\n| label | 表单标签 | label=\"用户名\" |\n| placeholder | 占位符 | placeholder=\"输入...\" |\n| alt | 图片替代文本 | alt=\"描述\" |\n| title | 标题属性 | title=\"提示\" |\n| testid | 测试 ID | testid=\"btn-submit\" |\n| first/last/nth | 位置选择 | first, last, nth=2 |\n\n最佳实践：\n\n```bash\n# 正确流程\nagent-browser open https://example.com\nagent-browser snapshot -i # 获取引用\nagent-browser click @e1 # 使用引用\n\n# 错误流程\nagent-browser open https://example.com\nagent-browser click @e1 # 引用不存在！\n```\n\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\n---\n\n## React 检查系统\n\nagent-browser 提供了专门的 React 应用分析功能，包括 Suspense 边界检测和组件树分析。\n\n### 阻塞器类型与权重\n\n| 阻塞器类型 | 权重 | 可操作性 |\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权重值越高表示该阻塞器对用户体验的影响越大，可操作性分数表示该类型阻塞被用户交互绕过的可能性。\n\n### 边界类型\n\n| 边界类型 | 权重 | 说明 |\n|----------|------|------|\n| RouteSegment | 3 | 路由段级别的 Suspense |\n| ExplicitSuspense | 2 | 显式声明的 Suspense 边界 |\n| Component | 1 | 组件级别的 Suspense |\n\n资料来源：[cli/src/native/react/suspense.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/native/react/suspense.rs)\n\n---\n\n## Web 仪表盘架构\n\n仪表盘是可视化控制界面，使用 Next.js 构建，提供图形化的浏览器控制能力。\n\n### 组件结构\n\n```mermaid\ngraph TD\n A[Dashboard Root] --> B[控制面板]\n A --> C[结果展示区]\n A --> D[侧边栏]\n \n B --> E[ExtensionsPanel]\n B --> F[ControlsForm]\n \n C --> G[ChatPanel]\n C --> H[ConsolePanel]\n C --> I[NetworkPanel]\n \n D --> J[ResizablePanels]\n D --> K[Header]\n```\n\n### 核心组件\n\n| 组件 | 功能 | 文件 |\n|------|------|------|\n| ChatPanel | 消息和工具调用展示 | chat-panel.tsx |\n| ConsolePanel | JavaScript 控制台输出 | console-panel.tsx |\n| NetworkPanel | 网络请求监控和 HAR 导出 | network-panel.tsx |\n| ExtensionsPanel | Chrome 扩展管理 | extensions-panel.tsx |\n| ConsolePanel | 控制台消息格式化 | console-panel.tsx |\n\n#### 控制台面板功能\n\n控制台面板支持表达式求值和结果展示：\n\n- 语法高亮显示（紫色表示输入，绿色表示输出）\n- 错误消息红色高亮\n- 时间戳记录\n- 加载状态动画\n\n#### 网络面板功能\n\n| 功能 | 说明 |\n|------|------|\n| 请求列表 | 显示所有捕获的网络请求 |\n| 请求详情 | 展开查看请求头、响应体等 |\n| HAR 导出 | 保存网络会话为 HAR 文件 |\n| 过滤功能 | 按 URL 模式过滤请求 |\n\n资料来源：[packages/dashboard/src/components/console-panel.tsx](https://github.com/vercel-labs/agent-browser/blob/main/packages/dashboard/src/components/console-panel.tsx)\n\n---\n\n## 引擎系统\n\nagent-browser 支持多种浏览器引擎，通过 `--engine` 参数选择。\n\n### 支持的引擎\n\n| 引擎 | 说明 |\n|------|------|\n| chrome | Chrome 浏览器的完整实现 |\n| lightpanda | 轻量级替代方案 |\n\n引擎安装通过 `install` 命令自动下载 Chrome from Chrome for Testing。\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n---\n\n## 标志与配置系统\n\nCLI 工具支持丰富的命令行参数配置。\n\n### 常用标志\n\n| 标志 | 说明 |\n|------|------|\n| --annotate | 启用截图注释功能 |\n| --color-scheme | 设置颜色方案（dark/light）|\n| --download-path | 设置下载文件保存路径 |\n| --content-boundaries | 显示内容边界 |\n| --max-output | 最大输出大小限制 |\n| --allowed-domains | 允许访问的域名列表 |\n| --action-policy | 操作策略配置 |\n\n配置解析采用手动参数解析方式，按顺序处理 args 数组：\n\n```rust\n\"--annotate\" => {\n let (val, consumed) = parse_bool_arg(args, i);\n flags.annotate = val;\n flags.cli_annotate = true;\n if consumed {\n i += 1;\n }\n}\n```\n\n资料来源：[cli/src/flags.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)\n\n---\n\n## 会话管理\n\nagent-browser 支持会话管理，允许用户在不同会话间切换和恢复状态。\n\n### 会话相关命令\n\n```bash\n# 连接到指定会话\nagent-browser --session {SESSION} connect 9222\n\n# 关闭会话\nagent-browser --session {SESSION} close\n\n# 录制操作\nagent-browser --session {SESSION} record start\nagent-browser --session {SESSION} record stop\n```\n\n会话持久化机制允许：\n\n- 保存和恢复浏览器状态\n- 跨会话追踪问题\n- 批量复现和调试\n\n---\n\n## 网络与存储管理\n\n### 网络监控\n\n支持完整的网络请求监控和操作：\n\n| 操作 | 说明 |\n|------|------|\n| route | 路由匹配和拦截 |\n| unroute | 取消路由规则 |\n| requests | 查看请求列表 |\n| har | 导出 HAR 文件 |\n\n### Cookie 管理\n\n```bash\n# 获取 Cookie\nagent-browser cookies get\n\n# 设置 Cookie\nagent-browser cookies set --url https://example.com --name key --value val\n\n# 清除 Cookie\nagent-browser cookies clear\n\n# 从文件导入\nagent-browser cookies set --curl cookie.txt --domain example.com\n```\n\n### 存储管理\n\n支持 Web Storage API：\n\n| 存储类型 | 说明 |\n|----------|------|\n| local | localStorage |\n| session | sessionStorage |\n\n资料来源：[cli/src/output.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/output.rs)\n\n---\n\n## 技能数据系统\n\nagent-browser 使用 Markdown 格式的技能数据（Skill Data）来定义特定领域的工作流程和参考文档。\n\n### 技能数据组织\n\n```\nskill-data/\n├── core/ # 核心通用技能\n│ └── references/ # 参考文档\n├── slack/ # Slack 特定技能\n│ ├── references/\n│ └── SKILL.md\n└── dogfood/ # 测试用技能\n```\n\n### 技能文档结构\n\n每个技能文档通常包含：\n\n1. **目标描述** - 明确要完成的任务\n2. **操作步骤** - 具体的命令序列\n3. **参考文档** - 元素定位和属性说明\n4. **最佳实践** - 推荐的工作流程\n\n---\n\n## 测试架构\n\n### 单元测试\n\n```bash\ncd cli && cargo test\n```\n\n- 运行所有单元测试（约 320 个）\n- 测试速度快，无需启动 Chrome\n- 覆盖核心业务逻辑\n\n### 端到端测试\n\n```bash\ncd cli && cargo test e2e -- --ignored --test-threads=1\n```\n\n- 18 个 E2E 测试用例\n- 启动真实 headless Chrome 实例\n- 测试完整命令管道\n- 要求串行执行避免实例冲突\n\n资料来源：[AGENTS.md](https://github.com/vercel-labs/agent-browser/blob/main/AGENTS.md)\n\n---\n\n## 发布流程架构\n\n项目使用手动发布模式，流程如下：\n\n```mermaid\ngraph TD\n A[创建发布分支] --> B[更新版本号]\n B --> C[运行版本同步]\n C --> D[编写更新日志]\n D --> E[创建 PR]\n E --> F{合并到 main}\n F -->|是| G[CI 检测版本差异]\n F -->|否| H[等待合并]\n G -->|需要发布| I[构建 7 平台二进制]\n G -->|无需发布| J[跳过构建]\n I --> K[发布到 npm]\n K --> L[创建 GitHub Release]\n```\n\n版本同步命令：`pnpm version:sync` 自动更新：\n\n- cli/Cargo.toml\n- cli/Cargo.lock\n- packages/dashboard/package.json\n\n---\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 版本管理 |\n|------|----------|----------|\n| CLI 核心 | Rust | Cargo |\n| 浏览器自动化 | CDP (Chrome DevTools Protocol) | - |\n| 仪表盘前端 | Next.js + React + TypeScript | pnpm |\n| UI 组件 | shadcn/ui + Tailwind CSS | - |\n| 构建工具 | Vite (仪表盘) | - |\n| 包管理 | pnpm workspace | - |\n\n---\n\n\n\n## CLI 命令参考\n\n### 相关页面\n\n相关主题：[浏览器自动化核心](#browser-automation), [安装与构建](#installation-build)\n\n
\n相关源码文件\n\n以下源码文件用于生成本页说明：\n\n- [cli/src/commands.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/commands.rs)\n- [cli/src/flags.rs](https://github.com/vercel-labs/agent-browser/blob/main/cli/src/flags.rs)\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- [skill-data/core/references/snapshot-refs.md](https://github.com/vercel-labs/agent-browser/blob/main/skill-data/core/references/snapshot-refs.md)\n
\n\n# CLI 命令参考\n\n## 概述\n\n`agent-browser` 是一个基于 Rust 原生构建的浏览器自动化 CLI 工具，为 AI 代理（Cursor、Claude Code、Codex、Continue、Windsurf 等）提供浏览器控制能力。CLI 命令参考涵盖了所有可通过命令行执行的原子操作，包括元素交互、状态查询、浏览器设置、网络控制等功能模块。\n\n该工具通过 Chrome DevTools Protocol (CDP) 实现浏览器控制，不依赖 Playwright 或 Puppeteer，执行效率高且资源占用低。 资料来源：[skills/agent-browser/SKILL.md]()\n\n## 命令架构\n\nCLI 命令采用统一的解析-分发架构，将用户输入转换为对应的原生处理器执行。\n\n```mermaid\ngraph TD\n A[CLI 输入] --> B[commands.rs 命令解析]\n B --> C{命令类型}\n C -->|定位命令| D[find 命令解析]\n C -->|动作命令| E[actions.rs 动作分发]\n C -->|设置命令| F[flags.rs 标志处理]\n \n D --> G[role/text/label/placeholder/alt/title/testid/first/last]\n E --> H[click/tap/fill/type/highlight 等]\n F --> I[--annotate/--color-scheme/--download-path 等]\n \n G --> J[原生 CDP 调用]\n H --> J\n I --> J\n```\n\n## 核心命令分类\n\n### 元素定位命令\n\n元素定位命令用于通过多种策略查找 DOM 元素，并可指定后续操作。\n\n| 定位器 | 命令格式 | 说明 |\n|--------|----------|------|\n| role | `find role [action] [--name ] [--exact]` | 通过 ARIA 角色定位 |\n| text | `find text [action] [--exact]` | 通过可见文本定位 |\n| label | `find label