browser-harness

browser-harness - 自我修复的 LLM 浏览器自动化

关键词：browser-harness · self-healing browser · llm browser automation · cdp agent

通过 Chrome DevTools Protocol，在 LLM Agent 与 Chrome 之间建立直接 WebSocket 连接。Agent 可以检查页面、编写辅助代码、复用领域技能，并在不增加额外浏览器抽象层的情况下验证任务。

Browser Harness 是此目录中已移除的 agent-browser 技能的官方替代品。可将其用于干净的浏览器验证、自主浏览器任务，以及在 Claude Code、Codex、Antigravity、Gemini CLI 和 OpenCode 上可移植的 CDP 控制。

何时使用此技能

• 用户需要 LLM Agent 完成多步骤浏览器工作流：登录、导航、填写表单、提取数据、下载或验证。
• 工作流需要干净的浏览器配置文件或可重复的 CDP 验证，而不是使用用户已打开浏览器的当前状态。
• 用户通过 Codex CLI 或 Antigravity 运行，需要 Agent 能通过 shell/Python 命令操作本地浏览器工具。
• 写入、调整大小或重新打开浏览器截图时，Claude 报告图像/截图/工具错误。
• 目标 DOM 发生变化，Agent 应在 agent-workspace/agent_helpers.py 中添加或修复辅助函数。
• 任务适合使用 agent-workspace/domain-skills/ 中针对特定网站的领域技能。
• 对于允许的目标，并发浏览器、代理或验证码求解使 Browser Use Cloud 成为合理选择。

何时不要使用此技能

• 任务只需提取简单 HTML，不涉及浏览器状态或 JS 交互 -> 转到 scrapling。
• 任务需要对精确的人类 UI 进行标注，或指向渲染后的问题 -> 转到 agentation。
• 任务必须复用用户已打开且已通过身份验证的 Chrome 配置文件 -> 转到 playwriter。
• 任务需要捕获 React 组件源码 -> 转到 react-grab。
• 任务是编写普通的 Playwright/Puppeteer 脚本，不需要 Agent 自主运行 -> 直接使用相应技术栈。

说明

第 1 步：选择执行方案包

编写命令前，选择一个主要方案包：

• local-cdp：使用带有 --remote-debugging-port=9222 的本地 Chrome/Chromium。
• codex-cdp：Codex CLI 控制同一个本地检出目录和 CDP 端点。
• antigravity-cdp：Antigravity（agy）使用同一个工作区和 Chrome 调试端点。
• claude-vision-safe：截图捕获必须使用下方的安全图像处理流程。
• domain-skill：在 agent-workspace/domain-skills/ 中添加或修复针对特定网站的辅助函数。
• cloud-browser：需要使用 Browser Use Cloud，且符合使用条件。

第 2 步：安装 browser-harness

任何能够运行 shell 命令的平台都可以通过 Agent 设置 Browser Harness：

git clone https://github.com/browser-use/browser-harness.git
cd browser-harness
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Claude Code 也可以使用项目原生的设置提示词：

Set up https://github.com/browser-use/browser-harness for me

要求：

• Python 3.10+
• Chrome 或 Chromium
• Agent 运行环境可访问 http://localhost:9222/json

第 3 步：启用 Chrome 远程调试

使用单独的配置文件，以便工具安全地创建干净的会话：

# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Linux
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Windows PowerShell
& "C:\Program Files\Google\Chrome\Application\chrome.exe" `
  --remote-debugging-port=9222 --user-data-dir="$env:TEMP\chrome-debug"

验证：

curl -s http://localhost:9222/json

第 4 步：平台专属说明

平台	何时使用 browser-harness	设置说明
Claude Code	需要自主浏览器操作或 Claude 安全截图时	在处理大量图像前应用截图补丁
Codex CLI	需要从仓库任务中执行本地 CDP 自动化时	将 .venv 保留在检出目录中，并从该 shell 运行命令
Antigravity（agy）	需要在 Antigravity 工作流中使用同一浏览器工具时	确保 agy 可以访问检出目录和 localhost:9222
Gemini CLI / OpenCode	需要不依赖特定平台 MCP 配置的可移植浏览器自动化时	使用相同的本地 CDP 和 Python 工作区

对于 Codex 和 Antigravity，不要假定 Claude Code 插件命令可用。优先使用明确的本地命令：

cd ~/browser-harness
source .venv/bin/activate
python -c "import browser_harness; print('browser-harness OK')"
curl -s http://localhost:9222/json

步骤 5：应用 Claude 安全截图补丁

如果 Claude 在处理截图时出现图像识别、图像上传、PNG 读取或工具错误，请修改 src/browser_harness/helpers.py，使截图在内存中解码和调整大小，并在保存叠加层前关闭 PIL 文件句柄。

所需更改：

diff --git a/src/browser_harness/helpers.py b/src/browser_harness/helpers.py
--- a/src/browser_harness/helpers.py
+++ b/src/browser_harness/helpers.py
@@
-import base64, importlib.util, json, math, os, sys, time, urllib.request
+import base64, importlib.util, io, json, math, os, sys, time, urllib.request
@@
-            img = Image.open(path)
+            with Image.open(path) as src:
+                img = src.copy()
@@
-    open(path, "wb").write(base64.b64decode(r["data"]))
+    data = base64.b64decode(r["data"])
     if max_dim:
         from PIL import Image
-        img = Image.open(path)
+        img = Image.open(io.BytesIO(data))
         if max(img.size) > max_dim:
             img.thumbnail((max_dim, max_dim))
-            img.save(path)
+            buf = io.BytesIO()
+            img.save(buf, format="PNG")
+            data = buf.getvalue()
+    with open(path, "wb") as f:
+        f.write(data)

原因：

• Image.open(path) 会保留延迟文件句柄，除非对图像进行复制或关闭。
• 如果 PNG 被打开、重写，然后又被 Agent 快速重新打开，Claude 图像/工具处理流程更容易失败。
• 通过 io.BytesIO 在内存中调整大小，可以避免写入—读取—写入循环。
• 使用 with open(path, "wb") 写入一次，可生成稳定的文件，供 Claude 视觉上传。

Claude 推荐的截图调用：

path = capture_screenshot(max_dim=1800)

在高 DPI 显示器上使用 max_dim=1800，以确保图像边长低于常见的 2000px 限制。

步骤 6：运行浏览器任务

向 Agent 提供自然语言任务：

Open the local app, complete the signup form, and verify that the dashboard appears.
Navigate to GitHub, open the first open issue, and summarize the acceptance criteria.
Fill in the contact form at example.com and confirm the success message.

Agent 应：

1. 通过 CDP 连接到 Chrome。
2. 检查标签页和页面状态。
3. 复用 agent-workspace/agent_helpers.py 中现有的辅助工具。
4. 在 agent-workspace/agent_helpers.py 或 agent-workspace/domain-skills/ 中添加缺失的辅助工具。
5. 使用文本、URL、DOM 状态、截图或下载的文件作为证据，验证任务是否完成。

步骤 7：通过领域技能扩展

领域技能是针对特定网站的操作指南。保持内容精简且可复用：

agent-workspace/domain-skills/
├── github.py
├── linkedin.py
└── your-site.py

示例：

def login(page, username: str, password: str):
    """Log into mysite.com."""
    page.goto("https://mysite.com/login")
    page.fill("#username", username)
    page.fill("#password", password)
    page.click("button[type=submit]")
    page.wait_for_url("**/dashboard")

步骤 8：升级到 Browser Use Cloud

仅当本地 Chrome 无法满足需求且目标网站允许自动化时，才使用 Browser Use Cloud：

from browser_harness import BrowserUseCloud

client = BrowserUseCloud(api_key="YOUR_API_KEY")
result = client.run("Extract the dashboard data and return a CSV summary")
print(result)

最佳实践

1. 从 local-cdp 开始；只有当本地 CDP 端点无法满足任务需求时才升级。
2. 尽量减少对核心包的修改。将常规工作流逻辑放入 agent_helpers.py 或领域技能中。
3. 在运行图像密集型 Claude Code 任务前，应用 Claude 安全截图补丁。
4. 对于 Codex 和 Antigravity，优先使用明确的 Shell/Python 命令，而不是仅适用于 Claude 的插件说明。
5. 在 Agent 记录最终证据之前，始终将浏览器任务视为未完成。
6. 使用 scrapling 进行无状态抓取，使用 playwriter 复用已打开且经过身份验证的浏览器。
7. 不要违反网站条款、robots 规则、速率限制或授权边界。

快速验证

cd ~/browser-harness
source .venv/bin/activate
python -c "import browser_harness; print('browser-harness OK')"
curl -s http://localhost:9222/json

参考资料

• browser-use/browser-harness GitHub
• scrapling — 无需 Agent 管理浏览器状态的无状态 HTML/JS 抓取
• playwriter — 在现有登录/会话状态很重要时复用正在运行的浏览器
• agentation — 渲染 UI 反馈和人工标注数据包