L5-20：开源浏览器自动化 —— 在自己的服务器上部署浏览器机器人

🎯 学什么：用 Python 接入 browser-use 开源库，编写能自主浏览网页的 AI Agent。你可以自定义浏览器行为、添加自己的工具、选择不同的 AI 模型——构建属于你自己的浏览器自动化系统，完全在你的控制之下。核心洞察：(1) 四个核心组件像交响乐团——Agent（指挥）、BrowserSession（乐器管理员）、Tools（乐谱）、DomService（灯光师）——LLM Integration 是"乐团的大脑"；(2) uv pip install 而非 pip install——用 pip 在 Windows 上装 browser-use 90% 会报奇怪的依赖错误；(3) use_vision 是奢侈品不是必需品——打开视觉成本飙升 5-10 倍，只在 CAPTCHA 和视觉理解场景才用。 💡 难易度：⭐⭐⭐⭐ | ⏱️ 预计时间：45 分钟

---

1. 课程概览

💡 白话小课堂：L5-18 是"遥控器"（CLI 命令操控浏览器），L5-19 是"云厨房"（浏览器跑在云端）。L5-20 是"自己造机器人"——你用 Python 代码定义这个机器人会什么、用什么 AI 模型驱动、能连接哪些外部工具。三个层次：CLI（CLI：命令行接口，快速上手）→ Cloud（免运维）→ Python SDK（完全定制）。

来源：browser-use 团队 / https://github.com/browser-use/browser-use

---

2. 开源库架构：四个核心组件

2.1 组件地图

browser-use 是一个异步 Python >= 3.11 库，核心架构是事件驱动的：

组件 1：Agent（browser_use/agent/service.py）—— 指挥
  → 主协调器：接收任务、管理浏览器会话、执行 LLM 驱动的动作循环
  → 职责：理解任务意图 → 决定每一步做什么 → 调用 Tools
  → 关键配置：max_steps（最大步数限制）、use_vision（是否开启视觉）

组件 2：BrowserSession（browser_use/browser/session.py）—— 乐器管理员
  → 管理浏览器生命周期：启动、维持、关闭
  → 维护 CDP（Chrome DevTools Protocol）连接
  → 通过事件总线（bubus）协调多个看门狗服务
  → 职责：确保浏览器一直"能用"

组件 3：Tools（browser_use/tools/service.py）—— 乐谱
  → 动作注册表：将 LLM 决策映射到浏览器操作
  → 内置操作：navigate, click, type, scroll, screenshot, extract...
  → 可扩展：通过 @controller.action() 注册自定义操作
  → 职责：定义"机器人能做什么"

组件 4：DomService（browser_use/dom/service.py）—— 灯光师
  → 提取和解析页面 DOM 内容
  → 生成元素的可访问性树（Accessibility Tree）
  → 高亮可交互元素供 Agent 选择
  → 职责：让 Agent "看清"页面上有什么

LLM Integration（browser_use/llm/）—— 乐团的大脑
  → 抽象层：支持 OpenAI、Anthropic、Google、Groq 等
  → Agent 不直接操作浏览器——它通过 LLM "理解"页面并"决定"动作
  → LLM 的推理质量直接决定 Agent 的"智商"

2.2 最小可行 Agent

import asyncio
from browser_use import Agent, Browser

async def main():
    browser = Browser()
    
    agent = Agent(
        task="打开淘宝，搜索'蓝牙耳机'，点击第三个商品，截图保存",
        browser=browser,
        # LLM 由环境变量自动选择（ANTHROPIC_API_KEY, OPENAI_API_KEY 等）
    )
    
    result = await agent.run()
    print(result)

asyncio.run(main())

---

3. 关键配置与陷阱

3.1 use_vision：奢侈品不是必需品

use_vision 的代价：

关闭视觉（use_vision=False，默认）：
  → Agent 通过 DOM/Accessibility Tree 理解页面
  → 每次决策的输入：页面的结构化文本表示（几百 token）
  → 速度快、成本低
  → 适合 >90% 的场景

打开视觉（use_vision=True）：
  → Agent 每次决策都截图发给 LLM
  → 每次决策的输入：一张截图（几千到几万 token）
  → 速度慢、成本飙升 5-10 倍
  → 只在必要场景打开

什么时候必须打开视觉？
  1. CAPTCHA 验证码——需要"看懂"图片中的文字/图形
  2. 理解页面视觉布局——"判断这个广告是否在页面第一屏"
  3. DOM 无法描述的视觉信息——图表的颜色、图片的内容

什么时候应该关闭？
  → 所有通过 DOM 就能完成的操作——点击、输入、提取文字
  → 规则：视觉是奢侈品，不是默认配置

3.2 max_steps：步数预算的艺术

max_steps 控制 Agent 在一个任务中的最大操作步数：

太低（如 5 步 vs 需要 12 步）：
  → Agent 在完成全部操作前被强制停止
  → 任务未完成——表单只填了一半
  → 但有一个好处：Agent 被逼着走最短路径

太高（如 100 步 vs 只需 8 步）：
  → Agent 完成 8 步后还有 92 步"配额"
  → 可能开始做不必要的事情——过度探索、重复操作、无意义验证
  → 浪费 token 和时间

最佳实践：
  → 预估需要的步数 → 上浮 30-50%
  → 复杂表单（10 个字段）：约 15-20 步
  → 简单页面浏览（打开+截图）：约 3-5 步

3.3 uv 安装：不是建议是要求

browser-use 官方强烈推荐 uv：
  → uv pip install browser-use（不是 pip install）
  → uv 快 10-100 倍
  → 自动处理 Python >= 3.11 的版本管理
  → 如果在 Windows 上用 pip 安装后报各种奇怪的依赖错误
    → 90% 是因为没用 uv

开发规范强制要求：
  ✓ 使用 uv（绝不用 pip）
  ✓ 异步 Python >= 3.11
  ✓ 测试使用 pytest-httpserver（不用真实远程 URL）
  ✓ Pydantic v2 模型 extra='forbid'
  ✓ 使用 runtime assertions

---

4. 自定义工具：@controller.action()

4.1 扩展 Agent 的能力

@controller.action("描述") 装饰器的作用：
  → 将一个 Python 函数注册为 Agent 可调用的操作
  → Agent 通过函数的描述判断"什么时候该调用这个操作"
  → 参数自动暴露给 Agent

电商场景的自定义 Action 示例：

@controller.action("Reply to buyer question on e-commerce platform")
async def reply_buyer_question(order_id: str, message: str):
    """回复买家在电商平台的咨询"""
    # 在买家咨询页面找到对应订单
    # 输入自动回复内容
    # 点击发送
    return f"Replied to order {order_id} with: {message}"

@controller.action("Extract product prices from current search results page")
async def extract_prices():
    """提取当前搜索结果页所有产品的价格"""
    # 解析页面 DOM
    # 提取价格列表
    # 返回结构化数据
    return [{"name": "xx", "price": 99.9}, ...]

4.2 MCP Server 模式 vs @sandbox 模式

两种部署模式的选择：

MCP Server 模式：
  → 将 browser-use 暴露为 MCP 服务器工具集
  → Claude Desktop、Claude Code 等 MCP 客户端可以直接调用
  → 命令：uvx browser-use[cli] --mcp
  → 适合：想把浏览器能力集成到 AI 助手中

@sandbox 模式：
  → 将 Agent 打包为独立的生产部署服务
  → 依赖管理、环境隔离、一键部署
  → 适合：需要独立运行、有固定 API 接口的场景

---

5. 结构拆解：开源浏览器 Agent Skill 模板

---

6. 电商案例：自有服务器竞品数据采集 Agent

某自有品牌的电商公司（主营健身器材——哑铃/瑜伽垫/筋膜枪，有独立的技术团队和自有服务器）需要从京东、天猫采集竞品的价格、销量、评价数据，用于定价策略分析。第三方数据工具（如生意参谋）只提供类目级别数据，无法精确到竞品单 SKU 级别的每日价格波动。

用 browser-use Python SDK 在自有服务器上构建数据采集 Agent。

用 Python SDK 构建：

import asyncio
from browser_use import Agent, Browser, Controller

controller = Controller()

@controller.action("Extract product prices, sales volume, and review count from search results")
async def extract_product_data():
    """从当前搜索结果页提取所有商品的价格/销量/评价数"""
    # 解析页面 DOM 中各商品的 data-price、data-sales、data-review-count 属性
    products = await page.evaluate('''() => {
        return Array.from(document.querySelectorAll('.product-item')).map(el => ({
            name: el.querySelector('.product-title').innerText,
            price: parseFloat(el.dataset.price),
            sales: parseInt(el.dataset.sales) || 0,
            reviews: parseInt(el.dataset.reviews) || 0,
            shop: el.querySelector('.shop-name').innerText
        }))
    }''')
    return products

@controller.action("Handle pagination: click next page and wait for load")
async def go_next_page():
    """点击搜索结果下一页并等待新页面加载"""
    # 找到「下一页」按钮（如果不是最后一页）
    pass

@controller.action("Detect and bypass anti-crawl measure (retry with delay)")
async def handle_anti_crawl():
    """检测反爬验证码或频率限制，延迟 3-5 秒后重试"""
    import random, asyncio
    delay = random.uniform(3, 5)
    await asyncio.sleep(delay)
    return f"Anti-crawl detected, retrying after {delay:.1f}s"

async def crawl_competitor_sku(keyword: str, pages: int = 10):
    """采集指定关键词的竞品数据"""
    browser = Browser()
    agent = Agent(
        task=f"""
        在京东搜索「{keyword}」，按销量排序，
        从第 1 页开始逐页提取所有商品的：商品名/价格/店铺名/销量/评价数，
        翻页 {pages} 次，
        每翻 3 页暂停 5 秒（模拟人类浏览行为防止反爬），
        将采集到的数据保存为 JSON 文件
        """,
        browser=browser,
        controller=controller,
        max_steps=pages * 3 + 5,  # 每页约 3 步（extract + next_page + 可能的 wait）
        use_vision=False  # 不需要视觉——DOM 提取即可
    )
    result = await agent.run()
    return result

# 批量采集：每天采集 15 个核心关键词
async def main():
    keywords = [
        "可调节哑铃", "瑜伽垫加厚", "筋膜枪迷你",
        "弹力带套装", "仰卧起坐板", "动感单车家用",
        # ... 共 15 个关键词
    ]
    for kw in keywords:
        data = await crawl_competitor_sku(kw, pages=5)  # 每关键词翻 5 页
        save_to_db(kw, data)
        await asyncio.sleep(10)  # 关键词间间隔 10 秒，降低反爬风险

asyncio.run(main())

部署方案：

• 运行在自有服务器上（阿里云 ECS，无 GUI Linux）
• 默认无头 Chromium 模式
• cron job 每天 6:00 执行（凌晨流量低，反爬策略通常较宽松）
• 采集结果写入公司内部 PostgreSQL，对接 BI 看板

效果：

• 每日数据采集量：15 个关键词 × 5 页 × 60 个商品/页 ≈ 4,500 条 SKU/天
• 全自动化后的定价决策案例：发现竞品 A 的「可调节哑铃 20kg」从 ¥299 持续 5 天降至 ¥259，我方从 ¥289 跟进调至 ¥249（保毛利 18%），7 天内该 SKU 日销从 12 件提升至 38 件（+217%）
• use_vision=False 确保 Agent 每步只消耗几百 token（DOM 文本），而非常见的几万 token（截图）——每日采集成本控制在 $0.80 以内

🔑 启示：自有服务器上构建竞品数据采集，与第三方工具的核心差异不在「能不能采」——在于「能按自己的业务逻辑定制采集频率和存储」。定制化：关键词列表、翻页深度、数据存储格式都是你的，不依赖第三方工具的数据模型。反爬设计的关键：每 3 页暂停 + 关键词间间隔 + 凌晨执行——模拟人类浏览节奏而非高频机器行为。

---

7. 掌握检验

Q1：browser-use 开源库的四个核心组件中，哪个是"主协调器"——接收任务、管理浏览器会话、执行 LLM 驱动的动作循环？

• A) BrowserSession
• B) Tools
• C) Agent
• D) DomService

Q2：为什么 browser-use 推荐使用 uv pip install 而非 pip install？

• A) uv 是 Anthropic 的官方工具
• B) uv 快 10-100 倍且自动处理 Python 版本管理，用 pip 会导致奇怪的依赖错误
• C) pip 不支持 Python 3.11
• D) uv 是免费的，pip 是付费的

Q3：use_vision 是一个容易误用的选项。在什么场景下应该打开视觉？为什么打开会导致成本飙升？

Q4：自定义工具（Custom Action）的 @controller.action() 装饰器有什么作用？

Q5：以下哪项是 browser-use 的正确开发规范？

• A) 使用 pip 安装、同步 Python、所有测试使用真实远程 URL
• B) 使用 uv 安装、异步 Python >= 3.11、所有测试使用 pytest-httpserver
• C) 使用 conda 安装、Python 3.9、没有测试要求
• D) 使用 npm 安装、JavaScript 运行时、测试可选

Q6：Agent 配置中的 max_steps 参数控制什么？如果设置太低或太高各有什么后果？

Q7：@sandbox 部署模式和 MCP（MCP：模型上下文协议）Server 模式分别适用于什么场景？想把 browser-use 集成到 Claude Desktop 中应该用哪种？

Q8：用"乐团比喻"描述四个核心组件各自的角色和协作关系。

---

8. 答案

点击查看答案

Q1：C — Agent（主协调器）。BrowserSession 管理浏览器生命周期；Tools 是动作注册表；DomService 提取和处理 DOM 内容。

Q2：B — browser-use 官方强烈推荐 uv。uv 快 10-100 倍，自动处理 Python >= 3.11 版本管理。用 pip 在 Windows 上安装 90% 会报奇怪的依赖错误。

Q3：参考答案 — 应该打开视觉的场景：(1) CAPTCHA 验证码；(2) 需要理解页面视觉内容的任务。关闭的场景：大多数通过 DOM 就能完成的操作。打开视觉意味着每次决策都截图发给 LLM，输入 token 暴涨，成本飙升 5-10 倍。

Q4：参考答案 — @controller.action("描述") 装饰器将一个 Python 函数注册为 Agent 可调用的自定义操作。Agent 通过函数的描述判断"什么时候该调用这个操作"。参数自动暴露给 Agent。

Q5：B — 官方开发规范明确要求：使用 uv（绝不用 pip）、异步 Python >= 3.11、测试使用 pytest-httpserver。

Q6：参考答案 — max_steps 控制 Agent 在一个任务中的最大操作步数。太低：Agent 被强制停止，任务未完成；太高：完成必要步骤后 Agent 可能过度探索，浪费 token 和时间。最佳实践：预估步数 × 1.3-1.5。

Q7：参考答案 — @sandbox 模式：将 Agent 打包为独立部署服务（适合独立运行、有固定 API 接口）。MCP Server 模式：暴露为 MCP 工具集（适合集成到 Claude Desktop 等 MCP 客户端）。集成到 Claude Desktop 用 MCP Server 模式：uvx browser-use[cli] --mcp。

Q8：参考答案 — Agent（指挥）：总协调——接收任务，决定每一步做什么；BrowserSession（乐器管理员）：管理浏览器生命周期——确保浏览器能用；Tools（乐谱）：定义每种操作——Agent 可以调用哪些操作；DomService（灯光师）：看清舞台——提取 DOM、高亮可交互元素。

（6/8 通过）

---

9. 延伸阅读

• [[L5-19-云端浏览器自动化|上一课：云端浏览器自动化]]
• [[L5-21-远程浏览器操控|下一课：远程浏览器操控]]