browser-harness

browser-harness

AI 直连 Chrome 的薄 CDP 层。给 AI 一个 WebSocket，就能控制真实浏览器，AI 自己写辅助代码适应任何网站。

核心原则

• AI 是用户，不是人 — 框架为 AI 设计，不是为人设计的 UI
• 缺失即创造 — 遇到不会的，AI 自己写 agent_helpers.py 学会
• CDP 是接口 — 直接给模型 Chrome DevTools Protocol，不抽象掉

快速开始

安装

# clone 到持久目录
git clone https://github.com/browser-use/browser-harness ~/Developer/browser-harness
cd ~/Developer/browser-harness

# 创建虚拟环境
uv venv .venv && source .venv/bin/activate
uv pip install -e .

# 连接到 Chrome（方式一：已有的 Chrome 开了 remote-debugging）
BU_CDP_URL=http://127.0.0.1:9222 browser-harness -c 'print(page_info())'

# 方式二：让 harness 启动云浏览器（需 BROWSER_USE_API_KEY）
start_remote_daemon("work")

连接 Chrome

方式 1 — 已有 Chrome 开 remote debugging（推荐）： Chrome 菜单 → chrome://inspect/#remote-debugging → 勾选 "Allow remote debugging"

BU_CDP_URL=http://127.0.0.1:9222 browser-harness -c 'print(page_info())'

方式 2 — 隔离 profile：

google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-harness
BU_CDP_URL=http://127.0.0.1:9222 browser-harness -c '...'

常用命令

browser-harness -c 'new_tab("https://example.com"); wait_for_load(); print(page_info())'
browser-harness -c 'capture_screenshot()'
browser-harness -c 'new_tab("https://example.com"); wait_for_load(); js("document.title")'

核心 API

函数	作用
new_tab(url)	新标签页打开 URL（不干扰当前页面）
goto_url(url)	在当前标签页导航
wait_for_load()	等待页面加载完成
page_info()	返回 {url, title, w, h, sx, sy, pw, ph}
capture_screenshot()	截图，返回文件路径 /tmp/shot.png
js(expr)	在页面执行 JS 表达式
click_at_xy(x, y)	坐标点击（穿透 iframe/shadow DOM）
scroll(dx, dy)	滚动页面
cdp(domain, method, **params)	直调 CDP
list_tabs()	列出所有标签页

表单填写

# 方式：js() 直接操作 DOM
browser-harness -c 'js(\'document.querySelector("input[name=custname]").value = "测试用户"\')'
# 验证
browser-harness -c 'js("return document.querySelector(\'input[name=custname]\').value")'

CDP 直调

# 任何 helper 没覆盖的，用 cdp()
cdp("Runtime.evaluate", expression="1+1", returnByValue=True)
# → {'result': {'type': 'number', 'value': 2}}