不要把 browser-use 当成“会点网页的模型”：先给浏览器 Agent 设计执行契约

我最近越来越不愿意把浏览器 Agent 叫成“自动点网页”。这个说法太轻了。真正的风险不在于它能不能点按钮，而在于它能不能在一个真实账号、真实网页、真实失败状态里，知道什么时候继续、什么时候停、什么时候把证据交给人。

`browser-use` 值得关注，正是因为它把浏览器控制、LLM 决策、DOM 结构、历史记录和低层 CDP 能力放在同一个工程表面里。但这也意味着：如果你准备把它交给 Claude Code、Codex、Cursor 或自己的自动化宿主，第一步不应该是“让它帮我登录后台发一篇文章”，而应该是先定义一套最小执行契约。

## 1. browser-use 的核心不是点击，而是循环

从 Doramagic 的项目手册看，browser-use 的 Agent 不是一次性脚本。它的工作方式更接近：

1. 观察当前页面；
2. 把页面状态转成模型可读的结构；
3. 让 LLM 决定下一步动作；
4. 执行 `navigate`、`click`、`input`、`extract`、`screenshot` 等动作；
5. 记录历史，再进入下一轮。

这套循环里真正关键的是“状态如何被看见”。浏览器页面本身是混乱的：DOM、截图、tab、弹窗、下载、cookie banner、hover 菜单、权限弹窗都可能影响下一步。browser-use 的设计里有 `BrowserSession`、watchdogs、DOM markdown extractor、`AgentHistoryList`、judge LLM、message compaction 等组件，就是为了把这个混乱过程变成可追踪的执行流。

所以判断一个 browser-use 工作流能不能上手，不是看 demo 里点了多少按钮，而是看它是否能留下这些证据：

- 每一步为什么执行；
- 当前 URL、tab 和交互元素是什么；
- 失败后是否能复盘上一步；
- 结果是否经过 judge 或明确断言；
- 是否保存了 history、截图或 GIF 供人工审查。

没有这些证据，浏览器 Agent 就只是一个速度更快的“远程鼠标”。

## 2. CLI 2.0 和 direct CDP 很有吸引力，但不要跳过权限边界

browser-use 的 CLI 2.0 重点是 direct Chrome DevTools Protocol，也就是直接通过 CDP 和 Chromium 通信。相比传统 Playwright 编排，它的目标是降低启动和命令延迟，适合接入 AI coding agents。

这对开发者很诱人：宿主不用每次冷启动浏览器，后台 daemon 可以保留会话，命令响应更快，账号态也更容易复用。但这里有一个很实际的边界：速度越快，误操作也越快。

我的建议是第一次接入时只开放三个权限：

- 只读网页导航和截图；
- 测试账号或临时 profile；
- 临时目录里的文件读写。

不要一开始就给它主 Chrome profile、生产后台、真实支付/广告/云平台权限。browser-use 的边界卡也给出相同方向：第一次使用应从最小权限、临时目录和可回滚环境开始；生产数据、私密文件、真实 secrets、主配置目录都不应该进入首轮测试。

尤其要注意两个细节：

- 0.12.8 之后，restricted browser profile 会拒绝 `evaluate()`，这是安全收紧，不是“功能坏了”；
- daemon unix socket 只允许 owner 访问，说明本地控制通道本身就是安全面。

如果一个项目需要浏览器自动化，却没有定义“哪些页面可以碰、哪些动作必须人工确认、哪些结果需要截图证据”，那它还没准备好交给浏览器 Agent。

## 3. browser-use 的配置风险比安装命令更值得先看

`pip install browser-use` 只是开始。真正容易出问题的是模型、provider、profile 和 action surface。

手册里有几类很有代表性的坑：

- 某些 supported-models 文档片段会出现 import 路径漂移，复制前应该回到 repo 内的 `browser_use/llm/` 核验；
- Azure OpenAI 可能把正常的登录或导航 prompt 误判成内容策略问题；
- 本地 Ollama 模型如果返回空字符串，会触发 Pydantic JSON 校验失败；
- hover-only UI 目前没有一等 `hover` action，可能要走 actor mouse 或受限的 `evaluate()`；
- 0.12.5 起 `litellm` 不再是 core dependency，需要显式安装，原因还涉及供应链事件后的依赖边界收缩。

这些点说明：浏览器 Agent 的失败经常不是“模型不聪明”，而是执行环境没有被声明清楚。你需要在第一天就写下这些配置事实：

- 使用哪个 LLM provider；
- 是否使用 judge LLM；
- 是否启用 planning、loop detection、message compaction；
- 每一步 timeout 是多少；
- 是否允许真实 browser profile；
- 是否允许文件下载和读取；
- 是否允许自定义 tools；
- 失败日志保存在哪里。

这个清单比“让它完成一个炫酷任务”更重要。

## 4. 我会用三层验收来接 browser-use

如果要把 browser-use 放进一个 AI 宿主，我会分三层验收。

第一层：只读浏览。

任务可以很简单：打开一个公开页面，提取标题、主要链接和页面摘要。验收点不是摘要好不好看，而是：

- 是否能打开页面；
- 是否记录 URL；
- 是否能区分可点击元素和普通文本；
- 是否能在失败时说明是网络、DOM、模型输出还是工具执行失败。

第二层：低风险交互。

例如在测试页面里填写表单、切换 tab、触发弹窗，但不提交真实业务动作。验收点是：

- 是否在点击前说明目标元素；
- 是否在点击后检查页面变化；
- 是否能处理弹窗、cookie banner、加载延迟；
- 是否能避免重复点击。

第三层：有人工闸门的写操作。

例如草稿保存、后台配置预览、内容发布前检查。验收点是：

- 最终提交按钮前必须停下；
- 输出提交前摘要；
- 给出截图或 DOM 证据；
- 明确哪些字段会被修改；
- 允许人工确认后再继续。

这三层跑通之前，不要让它碰真实生产账号。

## 5. Doramagic 这类项目手册的价值在哪里

browser-use 本身是上游开源项目，Doramagic 不是官方文档的替代品。它更像一个“带避坑记录的使用前上下文包”。

这份 browser-use 手册把项目拆成了几个更适合 AI 宿主读取的部分：

- overview、installation、CLI；
- Agent runtime、tools、system prompts；
- BrowserSession、watchdogs、DOM、Actor；
- LLM providers、MCP、Cloud、integrations；
- pitfall log 和 boundary/risk card。

对开发者来说，它的用法不是“看完文章就信任这个项目”，而是把这些材料交给你的 AI coding host，让它在动手前先理解项目边界。例如你可以要求宿主先回答：

- 这个项目首轮需要哪些权限；
- 哪些动作必须人工确认；
- 哪些失败要立刻停；
- 如果真实安装没有跑过，哪些能力不能宣称已经验证；
- 如果要复用 Chrome profile，如何隔离测试账号。

这比直接把 GitHub README 丢给 Agent 更稳，因为 README 往往解释“怎么开始”，但不一定告诉你“什么时候别继续”。

## 6. 一个实用判断：能不能留下收据

我判断浏览器 Agent 工作流是否值得继续投入，有一个很简单的标准：它能不能留下收据。

这里的收据不是日志越多越好，而是能回答三个问题：

- 它看见了什么；
- 它为什么这么做；
- 它凭什么认为任务完成了。

browser-use 提供了不少接近这个目标的材料：AgentHistoryList、screenshots、GIF、judge、DOM markdown、step metadata、TokenCost、多 provider 结构。真正的工程工作，是把这些材料接到你自己的验收标准里。

如果你只是想体验，可以从公开网页和只读任务开始。如果你想把它放进日常工作流，就先写一份执行契约，再让它跑第一步。

Doramagic browser-use 项目页：
https://doramagic.ai/zh/projects/browser-use/

Doramagic browser-use 项目说明书：
https://doramagic.ai/zh/projects/browser-use/manual/