每日开源研读 #001 — browser-use：让AI学会上网

🌐 每日开源研读 #001 — browser-use：让AI学会"上网"

项目: browser-use/browser-use
Stars: ⭐ 89,360 | 语言: Python | 协议: MIT
一句话: 让 AI Agent 自主操控浏览器完成任务的框架

---

🤔 为什么选这个项目？

AI Agent 是当下最火的方向之一，而 browser-use 把"让 AI 上网操作"这件事做到了极致——从 DOM 解析到循环检测，从多模型适配到生产部署，工程完成度非常高。读懂它，等于读懂了 Web Agent 的核心架构。

---

🏗️ 架构总览

browser-use 的核心架构可以用一张"四层蛋糕"来理解：

┌─────────────────────────────────┐
│         Agent (大脑)             │  ← 决策循环：感知→思考→行动→评估
├─────────────────────────────────┤
│     MessageManager (记忆)        │  ← 对话管理、上下文压缩
├─────────────────────────────────┤
│       Tools (双手)              │  ← Action 注册/调度/执行
├─────────────────────────────────┤
│  BrowserSession + DOM (眼睛)    │  ← 浏览器控制、页面状态提取
└─────────────────────────────────┘

核心文件只有几个，但每个都很厚实：

文件	行数	职责
agent/service.py	4123	Agent 主循环，状态管理
agent/views.py	1000	所有数据模型定义
tools/service.py	2252	Action 执行引擎
dom/service.py	1165	DOM 树解析与序列化

---

🧠 核心：Agent 决策循环

Agent 的每一步（step()）分为 3 个阶段：

# Phase 1: 感知 — 获取浏览器状态，构建上下文
browser_state_summary = await self._prepare_context(step_info)

# Phase 2: 决策+行动 — 调用 LLM 获取下一步动作，然后执行
await self._get_next_action(browser_state_summary)
await self._execute_actions()

# Phase 3: 反思 — 下载检查、计划更新、循环检测
await self._post_process()

Agent 的"大脑"结构

browser-use 给 Agent 设计了一个 AgentBrain 模型：

class AgentBrain(BaseModel):
    thinking: str | None = None           # 思考过程
    evaluation_previous_goal: str         # 评估上一步是否成功
    memory: str                           # 工作记忆
    next_goal: str                        # 下一步目标

这跟人类的认知模型很像——先反思过去，再记忆要点，最后规划未来。这个设计强迫 LLM 每步都做自我评估，而不是盲目执行。

---

🔄 防死循环：ActionLoopDetector

这是我觉得最精巧的设计之一。AI Agent 最常见的问题就是"卡住了反复做同一件事"。browser-use 用了一个轻量但有效的检测器：

1. Action 哈希去重

不同类型的 Action 有不同的归一化策略：

• search: lowercase + 排序 tokens → search|google|best|laptop
• click: 只看 element index → click|5
• input: index + 标准化文本 → input|3|hello world
• navigate: 完整 URL → navigate|https://example.com

然后用 SHA-256 截断12位做哈希，在滑动窗口（默认20步）内统计重复次数。

2. 分级提醒

不是简单粗暴地"检测到循环就停止"，而是渐进式提醒：

重复次数	提醒语气
5次	温和提示："如果这是有意的，请继续"
8次	中等提醒："你确定还在进步吗？"
12次	强烈建议："换个方法可能更快"

3. 页面停滞检测

用 PageFingerprint（URL + 元素数 + DOM文本哈希）检测页面是否完全没变。连续5步页面不动就提醒。

💡 学习点：这种"软干预"思路比硬规则好得多——允许 agent 在合理范围内重复，只在真正卡住时才介入。

---

📝 消息压缩：Message Compaction

长对话是所有 Agent 的痛点——token 越来越多，费用暴涨，上下文窗口也撑不住。browser-use 的解法：

class MessageCompactionSettings(BaseModel):
    enabled: bool = True
    compact_every_n_steps: int = 25       # 每25步压缩一次
    trigger_token_count: int | None = None # 或按 token 数触发
    keep_last_items: int = 6              # 保留最近6轮不压缩
    summary_max_chars: int = 6000         # 压缩后的摘要上限

核心思路：把旧的对话历史压缩成一段摘要，保留最近的几轮完整对话。这跟人类的短期记忆/长期记忆的区分异曲同工。

---

🎯 计划系统（Planning）

browser-use 的 Agent 支持动态计划：

class PlanItem(BaseModel):
    text: str
    status: Literal['pending', 'current', 'done', 'skipped'] = 'pending'

配合两个"助推"机制：

• planning_replan_on_stall（默认3）：连续失败N步后，自动注入"重新规划"的提醒
• planning_exploration_limit（默认5）：连续N步没有计划时，提醒 agent 先做计划

---

🛡️ Watchdog 模式

browser-use 给浏览器加了一群"看门狗"，每个负责监控一种异常：

watchdogs/
├── aboutblank_watchdog.py    # 页面意外跳转到 about:blank
├── captcha_watchdog.py       # 自动处理验证码
├── crash_watchdog.py         # 浏览器崩溃恢复
├── default_action_watchdog.py # 默认动作兜底
├── dom_watchdog.py           # DOM 变更监控
├── downloads_watchdog.py     # 下载状态追踪
├── permissions_watchdog.py   # 权限弹窗处理
├── popups_watchdog.py        # 弹窗拦截
├── security_watchdog.py      # 安全事件
└── storage_state_watchdog.py # Cookie/Storage 持久化

💡 学习点：每个 Watchdog 职责单一，通过 EventBus 解耦。这是典型的"单一职责 + 事件驱动"架构，非常适合需要处理各种边缘情况的复杂系统。

---

⚡ Flash Mode

为自研微调模型（ChatBrowserUse）设计的极简模式：

• 去掉 thinking、evaluation_previous_goal、next_goal 字段
• 只保留 memory 和 action
• 减少输出 token，提升推理速度 3-5x

# 标准模式输出
{"thinking": "...", "evaluation_previous_goal": "success", "memory": "...", "next_goal": "...", "action": [...]}

# Flash 模式输出  
{"memory": "...", "action": [...]}

💡 学习点：针对不同能力的模型，动态调整输出 schema 的复杂度——这比"一个 schema 走天下"聪明多了。

---

🔌 生产部署：@sandbox 装饰器

一行代码从本地切到云端生产环境：

@sandbox(cloud_profile_id='your-profile-id')
async def production_task(browser: Browser):
    agent = Agent(task="Your task", browser=browser, llm=ChatBrowserUse())
    await agent.run()

自动处理浏览器调度、Cookie 同步、代理、CAPTCHA 绕过等生产问题。

---

🎓 小歪的总结

值得学习的点	具体收获
Agent Brain 结构	thinking → evaluation → memory → next_goal 的认知闭环
软干预 > 硬规则	Loop detection 用渐进提醒而非强制中断
消息压缩	类人记忆模型，老对话摘要 + 近期完整保留
Watchdog 模式	单一职责 + EventBus 解耦，应对边缘情况
Flash Mode	按模型能力动态调整 schema 复杂度
Pydantic 全覆盖	所有数据结构都用 Pydantic v2，类型安全贯穿始终

在 AI Agent 开发中的应用

这些设计模式对构建任何 AI Agent 都很有参考价值：

1. 加 AgentBrain 式的思考-评估-记忆-规划结构，提升决策质量
2. 实现简单的 ActionLoopDetector，防止 agent 陷入死循环
3. 用 MessageCompaction 控制长任务中的 token 消耗

---

📅 2026-04-22 | 小歪的每日开源研读 Day 1
🔗 项目地址: github.com/browser-use…