• 人工智能
• AI Agent
• 浏览器控制
• GUI 自动化
• MCP 服务

导读

本文基于开源仓库browser-use的 CLAUDE.md 开发指南展开，系统讲解这一异步 AI 浏览器驱动库的整体架构：Agent 如何编排任务、BrowserSession 如何通过事件总线协调各类 Watchdog、DOM 服务如何为 LLM 生成可理解的页面快照，以及 Tools 注册表如何把模型决策映射为真实浏览器操作。同时完整覆盖仓库的开发命令、代码风格、CDP-Use 封装方式、测试规范与 MCP 集成方式，帮助读者既能在源码级理解其事件驱动设计，也能直接上手贡献代码或二次开发。

项目定位与运行环境

Browser-Use 是一个异步 Python（>= 3.11）库，核心能力是"用 LLM + CDP（Chrome DevTools Protocol）实现 AI 浏览器驱动"。它的工作方式不是模拟鼠标键盘做脚本化录制，而是：读取页面 HTML/DOM 结构 → 交给 LLM 推理 → 由 LLM 决定下一步动作 → 通过 CDP 执行点击、输入、滚动等操作 → 循环直至任务完成。

从 pyproject.toml 可以看到其运行前提与依赖特征：

• 语言要求：requires-python = ">=3.11,<4.0"；
• 依赖管理统一使用uv（而非 pip）；
• 关键依赖包括bubus（事件总线）、cdp-use（类型化 CDP 封装）、pydantic（v2 数据模型）、httpx/aiohttp（异步 HTTP）以及多家 LLM 的官方 SDK（openai、anthropic、groq、ollama、google-genai等）；
• 通过project.scripts注册了browser-use、browseruse、bu、browser四个 CLI 入口，全部指向browser_use.cli:main。

高层架构：事件驱动 + 职责分离

根据 CLAUDE.md 的"High-Level Architecture"章节，库采用事件驱动架构，核心组件包括四个service.py文件（对应仓库中统一的 Service Pattern）：

Agent：LLM 驱动的主循环

Agent 是整个系统的"大脑调度层"。从 browser_use/agent/service.py 的导入关系可以看出它的编排对象：

• 通过MessageManager（browser_use/agent/message_manager/service.py）维护与 LLM 的多轮对话历史，并支持消息压缩（compacted_memory前缀机制），避免长任务中上下文爆炸；
• 通过Tools注册表（browser_use/tools/service.py）拿到当前可执行的动作集合，动作模型如ClickElementAction、NavigateAction、InputTextAction、ScrollAction、DoneAction等定义在 browser_use/tools/views.py；
• 使用SystemPrompt（browser_use/agent/prompts.py）加载系统提示词，实际提示词文本存放在 browser_use/agent/system_prompts/ 下的多个.md文件中；
• 通过BrowserSession与浏览器交互，动作最终转化为浏览器事件（如ClickElementEvent、NavigateToUrlEvent），由 BrowserSession 消费执行。

BrowserSession：双层架构与事件总线

BrowserSession 的类注释明确描述了两层架构：

1. 高层事件处理层：面向 Agent 和 Tools，接收高层语义事件（导航、点击、滚动、下载等）；
2. 底层 CDP/Playwright 调用层：直接执行浏览器操作。

它同时支持事件驱动和命令式两种调用风格：

# 直接传参（推荐大多数用户使用） session = BrowserSession(headless=True, user_data_dir='./profile') # 或者使用 BrowserProfile（高级用法） session = BrowserSession(browser_profile=BrowserProfile(...)) # 会话字段可直接访问，浏览器设置通过 profile 或属性获取 print(session.id)

BrowserSession 还内置了ResilientEventBus——继承自bubus.EventBus的事件总线实现，其step()/wait_until_idle()在总线被销毁后不再断言而是静默返回，以保证keep_alive会话（例如 Lambda 冷启动恢复场景）的健壮性。

事件驱动的 Watchdog 体系

CLAUDE.md 明确指出 BrowserSession 通过bubus事件总线协调多个 Watchdog 服务。各 Watchdog 位于 browser_use/browser/watchdogs/ 目录，其职责如下：

• DownloadsWatchdog（downloads_watchdog.py）：处理 PDF 自动下载与文件管理，通过DownloadWillBeginEvent、DownloadProgressEvent等 CDP 事件跟踪下载进度，并内置了网络层可下载文件扩展名集合（pdf/doc/docx/xls/zip 等）；
• PopupsWatchdog：管理 JavaScript 对话框与弹窗；
• SecurityWatchdog：执行域名限制与安全策略（与allowed_domains/prohibited_domains配置联动）；
• DOMWatchdog：处理 DOM 快照、截图与元素高亮；
• AboutBlankWatchdog：处理空页面（about:blank）重定向。

从 browser_use/browser/session.py 的初始化代码可以看到，这些 Watchdog 都以event_bus=self.event_bus, browser_session=self的方式注册到同一事件总线上，形成"浏览器会话 → 事件总线 → 多个独立服务"的松散耦合结构。这一设计同样体现在 CLAUDE.md 的架构原则中：做大规模重构时，倾向使用简单事件总线和任务队列，把系统拆解为各自管理一部分独立状态的小型服务。

DomService：为 LLM 准备页面快照

DomService 负责把原始 DOM 转化为 LLM 可以消费的结构化信息。从 browser_use/dom/service.py 可以看到它依赖三个关键序列化组件：

• ClickableElementDetector（browser_use/dom/serializer/clickable_elements.py）：识别可点击元素；
• DOMTreeSerializer（browser_use/dom/serializer/serializer.py）：DOM 树序列化；
• build_snapshot_lookup（browser_use/dom/enhanced_snapshot.py）：构建增强快照查找表，配合REQUIRED_COMPUTED_STYLES计算样式需求。

DOM 快照、可访问性树、元素高亮以及 iframe 处理（max_iframes、max_iframe_depth可配置，跨域 iframe 需满足至少 10px 尺寸才会被纳入）都在这里完成，其输出是 Agent 每步推理的"观察依据"。

CDP 集成：基于 cdp-use 的类型化协议访问

CLAUDE.md 用专门的章节说明 CDP 集成方式。库使用 cdp-use（一个第三方开源库）提供类型化的 CDP 协议访问，但所有 CDP 客户端与会话管理、其他 CDP 辅助逻辑仍保留在 browser_use/browser/session.py 中。

使用风格如下（均通过cdp_client.send调用）：

# 启用某域的 CDP 方法 cdp_client.send.DOMSnapshot.enable(session_id=session_id) # 用字典传参 cdp_client.send.Target.attachToTarget(params={'targetId': target_id, 'flatten': True}) # 更推荐：用类型化参数类传参 from cdp_use.cdp.target import ActivateTargetParameters cdp_client.send.Target.attachToTarget( params=ActivateTargetParameters(targetId=target_id, flatten=True) )

事件注册必须使用cdp_client.register而不是cdp_client.on(...)（后者在 cdp-use 中不存在）：

cdp_client.register.Browser.downloadWillBegin(callback_func_here)

此外，仓库对 CDP 超时做了封装：TimeoutWrappedCDPClient（browser_use/browser/_cdp_timeout.py）用于给 CDP 调用设置超时保护，避免个别 CDP 命令长时间挂起阻塞 Agent 循环。

浏览器配置：BrowserProfile

CLAUDE.md 的"Browser Configuration"章节指出，browser_use/browser/profile.py 包含所有浏览器启动参数、显示配置与扩展管理逻辑。关键机制与常量包括：

• 显示尺寸自动检测：通过detect_display_configuration()（profile.py）完成——macOS 使用AppKit.NSScreen，Linux/Windows 使用screeninfo的get_monitors()；
• 扩展管理：uBlock Origin、cookie 处理类扩展，支持白名单配置；可通过环境变量BROWSER_USE_DISABLE_EXTENSIONS关闭默认扩展；
• Chrome 启动参数生成与去重：预定义了多组参数常量，包括CHROME_DEFAULT_ARGS（关闭后台节流、禁用弹窗拦截、--disable-back-forward-cache等）、CHROME_HEADLESS_ARGS（--headless=new）、CHROME_DOCKER_ARGS（--no-sandbox、--disable-dev-shm-usage等容器必需项）、CHROME_DISABLE_SECURITY_ARGS与CHROME_DETERMINISTIC_RENDERING_ARGS；
• 代理、安全设置与 headless/headful 模式：headless 默认值由BROWSER_USE_HEADLESS环境变量控制，未设置时回退到显示环境探测；调试端口固定为 9242（避免与常见的 9222 冲突）；
• 同时提供云端浏览器模式的参数入口（cloud_profile_id、cloud_proxy_country_code等，见 browser_use/browser/session.py 的__init__overload 定义），本地与云端两种模式共用同一批公共参数（allowed_domains、headless、auto_download_pdfs、highlight_elements等）。

开发环境搭建与常用命令

CLAUDE.md 给出了完整的开发命令矩阵，全部基于uv：

环境搭建：

uv venv --python 3.11 source .venv/bin/activate uv sync

测试：

# 运行 CI 测试（默认测试集） uv run pytest -vxs tests/ci # 运行全部测试 uv run pytest -vxs tests/ # 运行单个测试 uv run pytest -vxs tests/ci/test_specific_test.py

质量检查：

# 类型检查 uv run pyright # Lint 自动修复 + 格式化 uv run ruff check --fix uv run ruff format # pre-commit 钩子（提交前运行） uv run pre-commit run --all-files

从 pyproject.toml 的[tool.pytest.ini_options]可以看到 CI 侧的具体约束：timeout = 300、asyncio_mode = "auto"（无需@pytest.mark.asyncio装饰器）、testpaths = ["tests"]，且默认追加-svx --strict-markers --tb=short --dist=loadscope参数。Ruff 配置采用 tab 缩进、单引号、行长 130；Pyright 使用basic类型检查模式。

MCP Server 模式

库可以作为 MCP Server 运行，供 Claude Desktop 等 MCP 客户端集成：

uvx browser-use[cli] --mcp

从 browser_use/cli.py 的源码看，--mcp标志会启动 stdio 模式的 MCP Server（_run_mcp_stdio_server('browser_use.mcp.server')），另有--cli-mcp对应 browser_use/mcp/cli_mcp.py。

代码风格与工程规范

CLAUDE.md 对代码风格提出了明确且可执行的要求，这些规范直接影响所有贡献者提交的代码：

• 使用异步 Python；Python 代码一律使用tab 缩进，不用空格；
• 采用现代类型标注风格（Python >3.12）：用str | None替代Optional[str]，用list[str]替代List[str]，用dict[str, Any]替代Dict[str, Any]；
• 日志逻辑隔离：所有控制台日志逻辑放在以_log_...为前缀的独立方法中（例如def _log_pretty_path(path: Path) -> str），避免污染主逻辑；
• 数据模型：内部数据与可能作为 dict 出现的用户面 API 参数一律用pydantic v2 模型表示；模型配置使用model_config = ConfigDict(extra='forbid', validate_by_name=True, validate_by_alias=True, ...)按场景调参，且优先用Annotated[..., AfterValidator(...)]内联校验逻辑，而不是在模型上写辅助方法；
• 文件组织：每个子组件的主逻辑放在service.py，大部分 pydantic 模型放在views.py（除非足够长值得独立成文件）；
• 运行时断言：在函数开头与结尾使用运行时断言强制约束与假设；
• ID 字段：新 ID 字段优先使用from uuid_extensions import uuid7str+id: str = Field(default_factory=uuid7str)；
• 测试与类型检查：开发中随时运行uv run pytest -vxs tests/ci与uv run pyright。

文件组织关键模式

测试规范：真实对象优先，绝不 Mock

CLAUDE.md 对测试提出了非常具体且严格的要求，这也是仓库质量的核心保障：

1. 绝不 mock 任何东西，始终使用真实对象！唯一例外是 LLM——可以使用conftest.py中的 pytest fixtures 与工具预设 LLM 响应（见 tests/conftest.py）；
2. 测试中绝不使用真实远程 URL（如https://google.com或https://example.com），改用pytest-httpserver在 fixture 中起本地测试服务器，返回测试所需的 HTML（可参考 tests/ci 下的现有用例）；
3. 采用pytest-asyncio 现代写法：异步测试直接用普通async def函数，不再需要@pytest.mark.asyncio装饰器；需要事件循环时在测试内部使用loop = asyncio.get_event_loop()，不要通过函数参数传event_loop；fixture（包括异步 fixture）只需简单的@pytest.fixture装饰器且不带参数；
4. 测试文件的归位规则：测试通过后移入tests/ci/子目录，该目录是"默认测试集"，每次提交由 CI 自动发现并运行；事件相关的测试放在tests/ci/test_action_EventNameHere.py中。

作为配套策略，CLAUDE.md 的"Strategy For Making Changes"章节要求任何重要改动都按如下顺序进行：先写/找到验证现有设计的测试并确认其通过 → 为新设计先写失败测试并确认它们失败 → 实现新设计 → 跑完整tests/ci套件确认新设计与向后兼容性 → 合并去重测试逻辑 → 同步更新docs/与examples/。

MCP（Model Context Protocol）双向集成

CLAUDE.md 指出库支持两种 MCP 模式：

1. 作为 MCP Server：把浏览器自动化工具暴露给 MCP 客户端（如 Claude Desktop），即上文browser-use --mcp命令；
2. 作为 MCP 客户端：Agent 可以连接外部 MCP Server（filesystem、GitHub 等）来扩展能力。

第二种模式的连接管理位于 browser_use/mcp/client.py。其核心类MCPClient会把外部 MCP Server 的工具动态发现并注册为 browser-use 的动作：

from browser_use import Tools from browser_use.mcp.client import MCPClient tools = Tools() # 连接外部 MCP Server mcp_client = MCPClient( server_name='my-server', command='npx', args=['@mycompany/mcp-server@latest'], ) # 把所有 MCP 工具注册为 browser-use 动作 await mcp_client.register_to_tools(tools) # 之后正常使用 Agent，MCP 工具会作为动作自动可用

这种双向能力使 browser-use 既能被"调用"（作为工具服务器），也能"调用别人"（作为工具客户端），适合构建复杂的多服务 Agent 生态。

开发约束清单

CLAUDE.md 最后给出了开发时必须遵守的约束，可视为贡献者的红线：

• 依赖管理一律使用uv，不用pip；
• 不要随手创建示例文件——实现功能时如需验证，直接在终端内联测试；
• 使用真实模型名——不要把gpt-4o替换成gpt-4（它们是不同模型），避免误导；
• 动作用描述性名称与 docstring；
• 返回带结构化内容的ActionResult，帮助 Agent 更好地推理；
• 提交 PR 前运行 pre-commit 钩子。

小结

从 CLAUDE.md 这份开发指南可以完整还原 browser-use 的设计哲学：事件驱动 + 服务化拆分——Agent 负责 LLM 推理编排，BrowserSession 借助bubus事件总线把浏览器生命周期拆给一组 Watchdog，DomService 负责把页面"翻译"成模型可理解的快照，Tools 注册表充当动作映射层，而 CDP 细节则交由 cdp-use 的类型化封装与 browser_use/browser/session.py 统一管理。配合严格的测试规范（真实对象、本地测试服务器、事件归位测试文件）与统一的service.py/views.py文件模式，这一架构既保证了各子系统的独立可维护性，也为 Agent 在多轮浏览器交互中的稳定性提供了保障。对于希望理解其源码或参与贡献的开发者，上述命令、代码风格与测试流程构成了完整的上手路径。

• 人工智能
• AI Agent
• 浏览器控制
• GUI 自动化
• MCP 服务