Browser Harness：给 AI 编程工具装上"眼睛"的浏览器控制框架

场景引入：AI 写代码很快，但遇上"需要登录的页面"就卡住了

想象一下这个场景：你让 AI 帮你自动填报每日工作日志，AI 顺利写好了代码，但填报系统需要输入账号密码、需要滑动验证滑块、需要点选"我已阅读并同意"——这些都是传统 AI 代码工具无法完成的任务。browser-harness 解决的就是这个问题：它给 AI Agent 装上一双真正的"眼睛"，让 AI 能够像真实用户一样操作你的浏览器。

Browser Harness 是 browser-use 团队开源的一个极薄 CDP（Chrome DevTools Protocol）控制框架，代码量仅约 1000 行，核心只有 4 个文件。它不依赖 Selenium、Playwright 或 Puppeteer，而是直接通过 WebSocket 与 Chrome 通信，延迟极低，且允许 AI Agent 在运行过程中随时修改和扩展辅助代码，真正实现"边干边学"。

背景故事：从"Browser Use"主项目到"最薄的控制层"

browser-use 团队的主项目 browser-use 是一个将 AI Agent 接入浏览器的主流工具，Stars 超过 3 万。但主项目功能繁多、依赖较重。browser-harness 是他们推出的"极简版本"——没有任何 AI 逻辑，只做一件事：通过 CDP 协议控制 Chrome，让任何支持工具调用的 AI（Claude Code、Codex 等）都能直接操作真实浏览器。

作者的设计哲学是：工具越薄，AI 越自由。传统的 Playwright/Selenium 封装了一层厚厚的 API，AI 每次操作都要"查字典"；browser-harness 只提供底层 primitive（new_tab、click、type、screenshot 等），AI 可以在 agent_helpers.py 中随时编写自定义辅助函数并立即生效，无需重启 harness。

核心设计：三层架构

Chrome / Browser Use Cloud
        ↓ CDP WebSocket
browser_harness.daemon  ← 持久化后台进程
        ↓ IPC（Unix Socket / TCP）
browser_harness.run     ← 每次调用的入口

daemon 层（daemon.py）：管理 Chrome 生命周期，处理 CDP 连接复用。一个 daemon 可以服务多个并发 session。
IPC 层（_ipc.py）：daemon 与 run 之间的通信层，POSIX 用 Unix Socket，Windows 用 TCP loopback + 端口文件。
run 层（run.py）：每次用户调用的入口，自动启动 daemon，提供 Python REPL 风格的交互界面。

这种设计的好处是：daemon 启动一次，AI 可以反复连接，不像 Playwright 每次都要重新启动浏览器，速度快了一个数量级。

技术特点详解

1. 依赖极简，仅 4 个 Python 包

pyproject.toml 中明确定义了全部依赖：

cdp-use==1.4.5      # 核心 CDP 协议封装（browser-use 团队自研）
fetch-use==0.4.0    # HTTP 请求增强
pillow==12.2.0       # 图像处理
websockets==15.0.1  # WebSocket 通信

要求 Python >= 3.11，无其他运行时依赖。相比 browser-use 主项目动辄 50+ 依赖，harness 版本几乎是零负担。

2. AI 自进化机制（Self-healing Harness）

这是 browser-harness 最独特的设计理念。传统的浏览器自动化工具遇到"缺少某个 helper 函数"时，只能等待开发者更新代码。而 browser-harness 的解法是：当 AI 发现缺少某个辅助函数时，直接在 agent_helpers.py 中编写它。

● agent: wants to upload a file
│
● agent-workspace/agent_helpers.py → helper missing
│
● agent writes it                    agent_helpers.py
│                                   + custom helper
✓ file uploaded

官方文档称之为"self-healing"——AI 边用边完善工具链，每次运行都比上一次更好用。

3. 支持本地 Chrome + 云端 Browser Use Cloud

本地模式要求 Chrome 开启远程调试（chrome --remote-debugging-port=9222），AI 通过 chrome://inspect/#remote-debugging 连接。对于没有 GUI 环境的服务器或需要并行多浏览器场景，browser-harness 集成了 Browser Use Cloud：通过 API Key 启动云端 Chrome 实例，支持并行子 Agent、反爬虫代理和验证码解决服务。

4. Domain Skills：社区贡献的网站专精技能

agent-workspace/domain-skills/ 目录存放社区贡献的网站专精技能包。每个技能目录包含特定网站的操作技巧、选择器定义和工作流。AI 遇到 GitHub、LinkedIn、Amazon 等常见网站时，可以直接复用前人的经验，而不必每次都"从头发现"。

上手体验

安装（本地 Chrome 模式）

git clone https://github.com/browser-use/browser-harness
cd browser-harness
uv tool install -e .       # 全局安装
uv pip install cdp-use fetch-use pillow websockets

然后手动启动 Chrome（开启远程调试），AI 连接到 chrome://inspect/#remote-debugging 后即可使用。

使用示例（让 AI 自动完成网页任务）

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

云端浏览器模式（无需本地 Chrome）

export BROWSER_USE_API_KEY="your-key-here"
browser-harness <<'PY'
start_remote_daemon("work")
PY

局限与争议

本地 Chrome 模式配置繁琐：需要手动启动 Chrome 并开启远程调试，对非技术用户不够友好。云端模式虽然解决了这个问题，但依赖第三方服务。
没有内置 AI 逻辑：这是一个"无头"的控制框架，需要搭配 Claude Code、Codex 或其他 AI 编程工具使用，单独跑不起来。
CDP 协议本身的局限性：CDP 是 Chrome 专有协议，不支持 Firefox/Safari，生态有所局限。
安全风险：连接本地 Chrome 远程调试意味着任何本地进程都可以控制你的浏览器（虽然 Chrome 本身有权限验证），生产环境使用需谨慎。

行业意义

browser-harness 代表了一个趋势：AI Agent 的工具化。早期的 AI 编程工具（如 Copilot）只能生成代码片段；新一代的工具（Claude Code、Codex）已经能够自主执行操作；而 browser-harness 将这种能力延伸到了浏览器层面。

GitHub Stars 超过 13,800 且仍在增长，结合 browser-use 主项目的 3 万+ Stars，说明市场对"AI + 真实浏览器交互"的需求正在爆发。browser-harness 通过极简设计和 AI 自进化机制，为这个领域提供了一个优雅的开源解决方案。

项目基本信息

项目	browser-use/browser-harness
当前 Stars	13,880（持续增长中）
编程语言	Python
许可证	MIT
核心依赖	cdp-use, fetch-use, pillow, websockets
Python 版本	>= 3.11
架构	CDP + WebSocket + daemon IPC
特色功能	AI 自进化、Domain Skills、云端浏览器

Browser Harness：给 AI 编程工具装上"眼睛"的浏览器控制框架

场景引入：AI 写代码很快，但遇上"需要登录的页面"就卡住了

背景故事：从"Browser Use"主项目到"最薄的控制层"

核心设计：三层架构

Chrome / Browser Use Cloud
        ↓ CDP WebSocket
browser_harness.daemon  ← 持久化后台进程
        ↓ IPC（Unix Socket / TCP）
browser_harness.run     ← 每次调用的入口

daemon 层（daemon.py）：管理 Chrome 生命周期，处理 CDP 连接复用。一个 daemon 可以服务多个并发 session。
IPC 层（_ipc.py）：daemon 与 run 之间的通信层，POSIX 用 Unix Socket，Windows 用 TCP loopback + 端口文件。
run 层（run.py）：每次用户调用的入口，自动启动 daemon，提供 Python REPL 风格的交互界面。

这种设计的好处是：daemon 启动一次，AI 可以反复连接，不像 Playwright 每次都要重新启动浏览器，速度快了一个数量级。

技术特点详解

1. 依赖极简，仅 4 个 Python 包

pyproject.toml 中明确定义了全部依赖：

cdp-use==1.4.5      # 核心 CDP 协议封装（browser-use 团队自研）
fetch-use==0.4.0    # HTTP 请求增强
pillow==12.2.0       # 图像处理
websockets==15.0.1  # WebSocket 通信

要求 Python >= 3.11，无其他运行时依赖。相比 browser-use 主项目动辄 50+ 依赖，harness 版本几乎是零负担。

2. AI 自进化机制（Self-healing Harness）

● agent: wants to upload a file
│
● agent-workspace/agent_helpers.py → helper missing
│
● agent writes it                    agent_helpers.py
│                                   + custom helper
✓ file uploaded

官方文档称之为"self-healing"——AI 边用边完善工具链，每次运行都比上一次更好用。

3. 支持本地 Chrome + 云端 Browser Use Cloud

4. Domain Skills：社区贡献的网站专精技能

上手体验

安装（本地 Chrome 模式）

git clone https://github.com/browser-use/browser-harness
cd browser-harness
uv tool install -e .       # 全局安装
uv pip install cdp-use fetch-use pillow websockets

然后手动启动 Chrome（开启远程调试），AI 连接到 chrome://inspect/#remote-debugging 后即可使用。

使用示例（让 AI 自动完成网页任务）

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

云端浏览器模式（无需本地 Chrome）

export BROWSER_USE_API_KEY="your-key-here"
browser-harness <<'PY'
start_remote_daemon("work")
PY

局限与争议

本地 Chrome 模式配置繁琐：需要手动启动 Chrome 并开启远程调试，对非技术用户不够友好。云端模式虽然解决了这个问题，但依赖第三方服务。
没有内置 AI 逻辑：这是一个"无头"的控制框架，需要搭配 Claude Code、Codex 或其他 AI 编程工具使用，单独跑不起来。
CDP 协议本身的局限性：CDP 是 Chrome 专有协议，不支持 Firefox/Safari，生态有所局限。
安全风险：连接本地 Chrome 远程调试意味着任何本地进程都可以控制你的浏览器（虽然 Chrome 本身有权限验证），生产环境使用需谨慎。

行业意义

项目基本信息

项目	browser-use/browser-harness
当前 Stars	13,880（持续增长中）
编程语言	Python
许可证	MIT
核心依赖	cdp-use, fetch-use, pillow, websockets
Python 版本	>= 3.11
架构	CDP + WebSocket + daemon IPC
特色功能	AI 自进化、Domain Skills、云端浏览器