Visual Browser Agent

一款本地优先的浏览器自动化工具，为 AI 智能体提供网页交互的“眼睛和双手”。Visual Browser Agent 就是 Playwright 加上一个智能体控制平面：Playwright 负责执行浏览器操作，而本项目在此基础上增加了 MCP 工具、可视化证据、审批机制、Chrome 身份处理、安全控制，以及面向编码智能体和日常浏览器任务的工作流。

安装后会发生什么

你无需了解 Chromium、CDP、远程调试或 Chrome 内部配置文件名称。

技术安装程序会将 Visual Browser Agent 注册到你使用的编码智能体中，并安装 Playwright 浏览器运行时。之后，你的日常工作流就在编码智能体的对话中完成。你可以这样说：

Use the browser to open this website and check the layout.

智能体首先检查是否已有可用的 Chrome 会话。如果找到，就使用该会话；否则会启动一个由 Playwright 管理的全新 Chromium 会话。你也可以用自然语言明确指定：

Use my Work Chrome account and check the dashboard.

智能体会发现友好的 Chrome 身份，例如“工作 — work@example.com”和“个人 — personal@example.com”。如果存在多个可能的身份，它会在对话中请你选择。你不需要运行配置文件命令，也不需要选择 Profile 3。

Visual Browser Agent 还包含一个可选的本地控制面板。技术用户可以通过 npx visual-browser-agent dashboard 启动它，但正常使用并不需要控制面板。它会在 http://127.0.0.1:8787/ 显示连接健康状态、当前标签页、可用的 Chrome 身份以及最近的证据。

在智能体登录、发送消息、发布、购买、删除、提交或更改外部数据之前，它会暂停并请求批准。只读检查、截图、视觉审计和证据采集可以自动进行。

Related MCP server: websight

工作原理

这里有两种浏览器和两种连接方式：

安装

方式一：请你的编码智能体安装

在 Claude Code、Cursor、Copilot、Codex、Gemini、Windsurf、Cline、Roo、Kiro、Goose、OpenCode、Antigravity 或其他支持 MCP 的编码智能体中，直接询问：

Install Visual Browser Agent, set it up for this coding agent, and check that the browser runtime is ready. Ask me before installing software or changing browser settings.

智能体应检查安装状态，在安装 Playwright Chromium 前请求确认，注册 MCP 服务器，并报告任何缺失的权限或扩展步骤。之后你只需说“用浏览器……”即可。

方式二：从 GitHub 安装（推荐用于测试）

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install dependencies
npm install

# Build
npm run build

# Initialize (installs Chromium + MCP + skills)
npx visual-browser-agent init

或者直接通过 npx 使用：

npx github:Akakaui/visual-browser-agent init

方式三：从 npm 安装（发布后）

# Install globally
npm install -g visual-browser-agent

# Or use directly with npx
npx visual-browser-agent init

方式四：本地开发

# Clone the repo
git clone https://github.com/Akakaui/visual-browser-agent.git
cd visual-browser-agent

# Install in development mode
npm install

# Build
npm run build

# Link for global use
npm link

# Now you can use it anywhere
visual-browser-agent init

快速开始

1. 初始化

npx visual-browser-agent init

这将：

• 安装 Chromium（Playwright 浏览器）

• 配置 MCP

• 安装 Agent Skills

• 自动检测你的编码智能体并安装包装器

2. 开始使用

# Start MCP server with Chromium (default)
npx visual-browser-agent mcp

# Or start with Chrome extension
npx visual-browser-agent mcp --extension

3. 在你的 AI 智能体中使用

向你的智能体提问：“研究这个网站的设计”

智能体将使用 Visual Browser Agent 来控制浏览器。

使用你现有的 Chrome（扩展方式）

关于配置文件切换、验证和故障排除的完整普通用户指南，请参阅 EXTENSION_INSTALLATION.md。

如果你需要智能体使用你现有的 Chrome（包含你的登录状态、Cookie、会话）：

1. 安装扩展

1. 打开 Chrome → chrome://extensions/

2. 启用开发者模式

3. 点击加载已解压的扩展程序

4. 选择：node_modules/visual-browser-agent/browser-extension

2. 启动智能体

npx visual-browser-agent mcp --extension

3. 在你的 AI 智能体中使用

向你的智能体提问：“登录我的 Gmail 并总结我的邮件”

智能体会连接到你的 Chrome，所有登录状态完好保留。

与 AI 智能体的集成

自动检测（推荐）

当你运行 npx visual-browser-agent init 时，它会自动：

• 检测你正在使用的编码智能体

• 安装相应的包装器

• 配置 MCP

手动安装

如果自动检测不起作用，你可以手动安装：

# Install for specific agent
npx visual-browser-agent host <agent-name>

支持的智能体：

• claude-code

• cursor

• gemini

• opencode

• antigravity

• windsurf

• cline

• roo

• kiro

• copilot

• codex

• goose

Claude Code

添加到 .claude/settings.json：

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

Cursor

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp"]
    }
  }
}

用于 Chrome 扩展模式

{
  "mcpServers": {
    "visual-browser": {
      "command": "npx",
      "args": ["visual-browser-agent", "mcp", "--extension"]
    }
  }
}

AI 智能体如何使用本工具

场景一：研究公开网站

智能体判断：“这是一个公开网站，无需登录。”

智能体操作：使用 Chromium（默认）

npx visual-browser-agent mcp

场景二：访问用户的私有数据

智能体判断：“这需要用户的登录状态。”

智能体操作：通过扩展使用 Chrome

npx visual-browser-agent mcp --extension

场景三：用户指定浏览器

用户说：“使用我已登录的工作 Chrome 账户”

智能体操作：

npx visual-browser-agent mcp --choose-profile

命令参考

普通用户控制面板

对于非技术用户，浏览器智能体应由管理员或编码智能体安装程序一次性安装并注册。之后用户只需在编码智能体中通过自然语言说“用浏览器打开这个网站”“使用我的工作账户”或“检查页面并给我看截图”。智能体通过 MCP 处理连接、身份发现、证据和审批。

可选的本地控制面板用于查看连接状态和恢复连接。技术用户可以通过 npx visual-browser-agent dashboard 启动它；它会在 http://127.0.0.1:8787/ 打开，显示连接健康状态、友好的 Chrome 身份、当前标签页和最近的证据。该面板仅限本地使用，不会取代编码智能体的对话。

Playwright 2.0 兼容层

Visual Browser Agent 为智能体工作流提供基于 Playwright 的 MCP 接口。除了导航、表单、上传、下载、截图、录制、响应式审计和视觉研究之外，智能体还可以使用标签页/页面、历史记录、拖放、定位器引用、Web 优先断言、框架检查、对话框策略、Cookie、经批准的存储状态导出、最近的控制台消息、最近的网络请求、URL 路由模拟、追踪、媒体模拟、PDF 证据以及需确认的页面求值。

兼容层有意将敏感操作保持为显式操作。清除 Cookie 需要 confirm=true；页面求值需要 confirmDangerous=true；公开提交和工件删除仍由审批服务管理。网络模拟和存储工件仅限于当前智能体会话和经批准的目录。

配置文件

如果你有多个 Chrome 配置文件，请选择要与扩展一起使用的已登录账户：

# Choose an account interactively
npx visual-browser-agent mcp --choose-profile

# Advanced: use a known technical profile name
npx visual-browser-agent mcp --profile "Profile 3"

故障排除

Chromium 无法工作

npx playwright install chromium

Chrome 扩展无法连接

1. 确保 Chrome 已打开

2. 检查扩展图标是否显示“ON”

3. 尝试：npx visual-browser-agent doctor

MCP 服务器无法启动

# Check environment
npx visual-browser-agent doctor

# Reinstall
npx visual-browser-agent init

架构

User's AI Agent (Claude Code, Cursor, etc.)
                    |
                    | MCP Protocol
                    |
        Visual Browser Agent MCP Server
                    |
        +-----------+-----------+
        |                       |
    Chromium                  Chrome
    (Playwright)            (Extension)
        |                       |
        v                       v
  Agent controls           Agent connects
  fresh browser            to existing browser

许可证

MIT

非技术用户的日常使用

Visual Browser Agent 可以通过两种简单模式使用：

非技术用户不需要理解 MCP。完成一次设置后，他们就可以用自然语言告诉编码智能体他们想要什么，例如：“打开工作 Chrome 配置文件，检查这个 URL 的结账页面，并保存截图”，或“使用全新的 Chromium 会话在桌面端和移动端对比这个网站”。包装器会指示编码智能体检查浏览器连接、选择合适的模式、在身份验证或重大操作前询问，并返回带有证据的简明结论。

Chrome 配置文件：扩展方式与远程调试

Chrome 扩展是按每个 Chrome 配置文件安装的，而不是每个浏览器窗口安装一次。如果一个人想通过扩展模式使用三个独立的 Chrome 配置文件，他们应该打开每个配置文件，进入 chrome://extensions/，启用开发者模式，并在每个配置文件中加载一次已解压的 browser-extension/ 目录。同一个扩展源可以加载到每个配置文件中，但每个配置文件都必须授予自己的权限，并在选择该配置文件时保持打开状态。

远程调试则不同。它连接到以特定 --profile-directory 和调试端口启动的 Chrome 实例。大多数人应该运行 visual-browser-agent mcp --choose-profile；该工具会从 Chrome 读取友好的账户标签，并让用户按编号选择。技术性的 --profile 选项仍可用于脚本和高级设置。已被另一个 Chrome 进程占用的配置文件可能会拒绝第二次启动；请先关闭该配置文件，或使用单独的调试配置文件和端口。

对于需要现有登录 Cookie 的用户，扩展方式通常最简单。对于需要可重复的全新浏览器的用户，Chromium 更安全。远程调试应视为高级选项，因为它会将选定的浏览器会话暴露给本地智能体进程。

通过提示选择浏览器智能体

用户通常选择任务，而不是浏览器模式或专家模型。在 Claude、Cursor、Copilot、Codex、Gemini、Windsurf、Cline、Roo、Kiro、Goose、OpenCode、Antigravity 或其他支持 MCP 的编码代理中说“使用浏览器来……”。包装器会告诉代理使用自动浏览器选择，在必要时发现可见的 Chrome 身份，并在没有现有会话可用时回退到托管的 Chromium。编码代理在安装集成后选择 Visual Browser Agent MCP 工具。提示词应在重要时指明会话要求：

Use a clean Chromium browser. Audit this public website at desktop and mobile widths and save visual evidence.

Use the Work account I choose from Chrome. Open the internal dashboard, inspect the layout, and ask me before making any changes.

Use the current browser session. Do not submit forms, publish, purchase, delete, or send messages without asking for approval first.

如果团队想要一个命名的浏览器专家，请为编码客户端运行 visual-browser-agent host <agent-name>，并将生成的 MCP 配置和包装器保留在该项目中。该包包含适用于 Claude Code、Cursor、Gemini、Windsurf、Cline、Roo、Kiro、Copilot、Codex、Goose、OpenCode 和 Antigravity 的适配器，并为没有专用包装器的主机使用通用包装器。新主机可以使用相同的标准 MCP 配置：启动命令 visual-browser-agent mcp --managed 并将其注册为名为 visual-browser 的 MCP 服务器。

推荐的首次设置

npm install
npm run build
npx visual-browser-agent init --mode chromium
npx visual-browser-agent host <your-coding-agent>

然后重启编码代理并要求它使用可视化浏览器工具。对于干净的日常 Chromium 工作流，请使用 visual-browser-agent mcp --managed。对于现有的 Chrome 身份，请在将扩展加载到所需配置文件后使用 visual-browser-agent mcp --choose-profile。仅对高级脚本使用 --profile。

代理在审查网站时应始终自动使用只读检查和截图。在发布、发布、购买、删除、提交或更改外部数据之前，应请求明确批准。身份验证和私人个人信息应由用户直接在浏览器中提供，而不是放在提示词或配置文件中。

代理工件、工件面板、问题和批准

有关完整的普通用户和技术工作流，请阅读 Visual Browser Agent 1.0 用户指南。简而言之，编码代理通过 MCP 与 Visual Browser Agent 交互：它发现可用的浏览器工具，选择与用户请求匹配的工具，并接收文本、结构化 JSON、截图和证据元数据。

Visual Browser Agent 专为基于 UI 的编码代理和基于 CLI 的代理而设计。诸如 Claude Code 或 Antigravity 之类的 UI 主机可以将其截图/图像内容和生成的 HTML 或 Markdown 证据报告放入其工件面板中。CLI 主机或通用 MCP 客户端可以通过嵌入式图像块、结构化元数据、本地证据路径或 http://127.0.0.1:8787/ 上的本地仪表板使用相同的结果。代理绝不应假设主机可以打开任意的沙盒路径；它应返回可移植的结果和回退方案。

一个好的浏览器代理结果包含任务目标、URL 和来源、选定的浏览器身份、执行的操作、断言、截图、控制台/网络发现、运行 ID、时间戳和下一步。这使人们可以直观地验证工作，而不是阅读原始工具日志。需要时明确向代理请求这些内容：

Create a host-renderable visual report with screenshots, assertions, console errors, and a concise conclusion. Also provide a local fallback.

有三种人工交互类型。问题用于解决缺失的信息，例如使用哪个 Chrome 身份或标签页。人工接管要求用户在出现密码、MFA 提示、CAPTCHA 或一次性代码时直接操作浏览器。批准用于授权诸如发送、发布、购买、删除或提交之类的重大操作。它们有意分开：问题不是执行操作的许可，截图也不是交易成功的证明。

回退的 ask_human 工具支持问题和简单的结构化选择。request_approval 和 submit_public_action 工具保留用于明确授权。代理应在请求批准之前显示确切站点、目标、操作和相关数据，并应将拒绝视为用户的最终决定，而不是静默重试。切勿将密码、API 密钥、访问令牌、支付详情或一次性代码粘贴到代理对话中。有关完整的安全模型，请参阅 docs/user-guide-1.0.md，有关每个配置文件的 Chrome 扩展设置，请参阅 EXTENSION_INSTALLATION.md。