Browser-Harness：让 LLM 直接「驾驶」真实浏览器的自愈式 CDP 工具

前言

在 AI Agent 快速发展的今天，如何让大语言模型（LLM）真正操控浏览器，完成复杂的自动化任务，是每个 AI 工程师都在思考的问题。

市面上已经有 Playwright、Selenium、browser-use 等各种工具，但它们大多以「包装层」思路为主——把底层协议封装起来，提供一套高级 API 给模型使用。然而，包装层越厚，模型被限制得越死，能力反而越弱。

browser-harness 走了一条截然不同的路：把框架拆掉，把 CDP 直接交给 LLM。

官方 GitHub：https://github.com/browser-use/browser-harness

---

一、什么是 browser-harness？

browser-harness 是 Browser Use 团队开源的一个极简 CDP（Chrome DevTools Protocol）harness，它的核心设计哲学只有一句话：

One websocket to Chrome, nothing between.

不做框架，不做抽象层，不做「智能调度」——只在 LLM 和浏览器之间架一根最细的线。

整个项目核心代码不到 600 行 Python，但它能让 AI Agent 完成：

• 页面导航与截图
• 点击、输入、滚动
• 跨域 iframe 操作
• 文件上传、下载
• Shadow DOM 访问
• 多标签页管理
• 批量 HTTP 请求
• 直接执行任意 JavaScript

更关键的是：当 Agent 发现某个能力缺失时，它会自己把代码写进去，然后继续执行。 这就是 browser-harness 的「自愈」（self-healing）能力。

---

二、核心设计哲学：不要包装 LLM，也不要包装它的工具

传统框架的问题

Playwright、Selenium 这类工具设计之初是为人类开发者服务的，提供了大量的高级封装：locator.click()、page.fill()、expect().toBeVisible() 等。

当 LLM 使用这些工具时，问题就来了：

1. 失败无反馈：封装层吞掉了底层错误，LLM 以为操作成功了，其实什么都没发生
2. 能力被锁死：框架只提供了设计者想到的功能，模型遇到边界情况就无能为力
3. 跨域限制：Playwright 的 locator 系统在跨域 iframe 面前经常失效
4. 反爬检测：高层封装往往留下大量可检测的特征指纹

browser-use 团队在 2026 年 4 月发布的文章《The Bitter Lesson of Agent Harnesses》中，深刻总结了这一教训：

「我们曾经认为把 CDP 的复杂性对模型屏蔽掉是好事。但结果恰恰相反——每一个 helper 函数都是一道枷锁。」

browser-harness 的答案

• 直接 CDP 通信：所有操作通过原生 Chrome DevTools Protocol 执行
• 坐标点击优先：默认使用像素坐标点击 click_at_xy(x, y)，在合成器层执行，天然穿透 iframe、Shadow DOM 和跨域边界
• Agent 可编辑 helper：agent-workspace/agent_helpers.py 是 Agent 可以自由修改的文件，遇到缺失能力直接往里写
• 截图驱动探索：优先用 capture_screenshot() 理解页面，而不是硬写选择器

---

三、架构解析

Chrome / Browser Use Cloud
        |
        | CDP WebSocket
        v
browser_harness.daemon     <- 常驻守护进程，持有 WS 连接
        |
        | IPC（Windows: TCP loopback；POSIX: Unix socket）
        v
browser_harness.run        <- 每次调用的执行层
        |
        v
agent_helpers.py           <- Agent 可编辑的 helper 函数

四个核心组成部分：

组件	文件	说明
安装引导	install.md	安装、连接浏览器、故障排查
核心包	src/browser_harness/	受保护的底层实现
可编辑 helper	agent-workspace/agent_helpers.py	Agent 自由扩展能力的地方
站点技巧	agent-workspace/domain-skills/	各网站的操作 playbook

守护进程机制

browser-harness 使用一个常驻的 daemon 进程持有与 Chrome 的 WebSocket 连接，避免每次调用都重新握手。

• BU_NAME：命名空间化 daemon，支持多个并发浏览器实例
• BU_CDP_WS：覆盖本地 Chrome 发现，用于远程浏览器
• BU_CDP_URL：用于 Way 2（命令行启动）模式的 DevTools HTTP 端点

---

四、快速安装

前置要求

• Python 3.11+
• uv（推荐）或 pip
• Chrome 或 Chromium 浏览器

安装步骤

# 1. 克隆到一个持久路径
git clone https://github.com/browser-use/browser-harness ~/Developer/browser-harness
cd ~/Developer/browser-harness

# 2. 以 editable 模式安装（修改 agent_helpers.py 即时生效）
uv tool install -e .

# 3. 验证安装
browser-harness --doctor

连接浏览器（推荐方式 Way 1）

在运行中的 Chrome 里访问：

chrome://inspect/#remote-debugging

勾选 “Allow remote debugging for this browser instance”，点击弹出的 Allow 确认框（Chrome 144+ 需要）。

连接成功后，--doctor 会显示：

[ok  ] chrome running
[ok  ] daemon alive
[ok  ] active browser connections — 1

对于 Claude Code 用户

在 ~/.claude/CLAUDE.md 中添加一行：

@~/Developer/browser-harness/SKILL.md

之后 Claude 就自动具备浏览器操控能力，直接用自然语言下指令即可。

---

五、基础用法示例

最简单的例子

browser-harness -c '
new_tab("https://github.com/browser-use/browser-harness")
wait_for_load()
print(page_info())
'

输出示例：

{'url': 'https://github.com/browser-use/browser-harness', 'title': '...', 'w': 1920, 'h': 1080}

截图驱动点击（推荐模式）

# 截图 -> 找坐标 -> 点击 -> 截图验证
img = capture_screenshot()
# 从图中读取目标像素位置
click_at_xy(342, 158)
wait_for_load()
img2 = capture_screenshot()

执行 JavaScript

# 提取页面数据
count = js('return document.querySelectorAll(".item").length')

# 操作 DOM
js('document.querySelector("input#search").value = "hello"')

批量 HTTP 请求（不启动浏览器渲染）

from concurrent.futures import ThreadPoolExecutor

urls = ["https://example.com/page/1", "https://example.com/page/2"]

with ThreadPoolExecutor(max_workers=20) as pool:
    results = list(pool.map(http_get, urls))

多标签页管理

new_tab("https://github.com")
wait_for_load()

new_tab("https://google.com")
wait_for_load()

switch_tab(0)  # 切回第一个标签

---

六、自愈能力详解

这是 browser-harness 最独特的设计。

假设 Agent 在执行任务时需要上传文件，但 agent_helpers.py 里没有 upload_file 函数。传统框架会直接报错或跳过。

browser-harness 的 Agent 会：

1. 读取 agent_helpers.py 的现有代码
2. 参考 interaction-skills/uploads.md 中的文档
3. 自己写一个 upload_file() 函数追加到文件末尾
4. 重新执行任务，这次成功
5. 下次执行时，这个函数还在——能力被永久保留

Hacker News 上一个评论描述了这个「魔法时刻」：

「Agent 自己发现上传功能缺失，用原始 DOM 方法写了个 upload 函数，然后继续完成了任务——完全没有人工干预。」

这不是预设的逻辑，是 LLM 本身的推理能力在发挥作用。browser-harness 只是没有阻止它。

---

七、Domain Skills：可复用的站点操作手册

agent-workspace/domain-skills/ 目录下存放着各个网站的操作 playbook，社区已贡献了 70+ 个网站的技巧文件：

domain-skills/
├── github/         # GitHub 操作
├── linkedin/       # 领英
├── gmail/          # Gmail
├── youtube/        # YouTube
├── reddit/         # Reddit
├── weibo.com/      # 微博
├── xiaohongshu/    # 小红书
├── bilibili/       # B 站
└── ...（持续增长中）

每个 skill 文件记录稳定的 CSS 选择器、URL 规律、常见交互路径和已知坑点。

关键特点：这些 skill 文件由 Agent 在真实交互中自动生成，而非手工编写。 技能是 harness 自己积累的，不是人写的。

---

八、云端浏览器支持

browser-harness 支持通过 Browser Use Cloud 使用托管浏览器：

# 启动一个云端浏览器（需要 BROWSER_USE_API_KEY）
start_remote_daemon("work")

# 携带登录 profile（cookies）
start_remote_daemon("work", profileName="my-work-profile")

# 指定代理国家
start_remote_daemon("work", proxyCountryCode="us", timeout=120)

云端浏览器优势：

• 并行执行：多个 BU_NAME 对应多个独立浏览器，天然支持多 Agent 并发
• 无头服务器：在没有 GUI 的服务器上运行
• 内置代理 + 验证码识别
• 免费额度：3 个并发浏览器，无需信用卡

---

九、与主流工具横向对比

特性	browser-harness	Playwright	browser-use	Selenium
底层协议	原生 CDP	封装 CDP	封装 Playwright	WebDriver
核心代码量	~600 行	数万行	较大	较大
跨域 iframe	原生支持	有限制	受限	困难
Agent 可扩展	直接改 helper	不支持	部分	不支持
自愈能力	支持	不支持	不支持	不支持
截图驱动	优先推荐	辅助	辅助	不支持
云端浏览器	内置支持	需自建	部分	需自建
学习曲线	极低	中等	中等	中等

---

十、社区生态与讨论

browser-harness 发布后迅速引发广泛关注：

• Hacker News：登上首页，收获大量真实技术讨论
• GitHub：活跃的 Issue 和 PR，社区贡献持续增加
• 设计争议：部分开发者担心 Agent 自主修改代码的可审计性；支持者认为最小化 harness 配合 CDP 日志回放可以实现完整复盘
• 安全讨论：社区对 remote debugging 的 bot 检测风险和权限边界有深入讨论

---

十一、总结

browser-harness 代表了 AI Agent 工具设计的一个新方向：不是给 LLM 搭一个更复杂的脚手架，而是把脚手架拆掉，让 LLM 站在地基上。

核心优势：

• 极简：600 行核心代码，没有多余抽象
• 自愈：Agent 遇到缺失能力自己补充，永久保留
• 真实浏览器：连接你正在使用的 Chrome，携带所有登录态和扩展
• 低门槛：一行命令安装，一个 checkbox 连接完毕

如果你在用 Claude Code 或其他 AI 编程助手，强烈建议试用 browser-harness。它不是「替你操控浏览器」的工具，而是帮助 AI 成为你真正的浏览器操作员。

---

官方资源

• GitHub：https://github.com/browser-use/browser-harness
• Browser Use 官网：https://browser-use.com
• 云端浏览器：https://cloud.browser-use.com
• 设计哲学文章：https://browser-use.com/posts/bitter-lesson-agent-harnesses
• Hacker News 讨论：https://news.ycombinator.com/item?id=47890841

---

本文基于 browser-harness 官方文档、README、Hacker News 讨论及 Browser Use 官方博客整理撰写。