Browser Harness

Browser Harness 是一个基于 CDP (Chrome DevTools Protocol) 构建的超轻量级、可自我修复的浏览器自动化框架。它摒弃了传统自动化工具中繁琐的框架、预设配方和严格护栏，通过一条直接的 WebSocket 连接，让 LLM Agent 拥有操作浏览器的完全自由。

其核心理念是：Agent 不仅是执行者，更是代码的维护者。 当遇到缺失的功能时，Agent 可以直接编辑 helpers.py 编写新函数，实现真正的“自我修复”和能力扩展。

核心特性

1. 真正的自我修复与进化

• 动态代码生成：如果 Agent 需要执行一个尚未定义的操作（如上传文件），它可以即时读取 helpers.py，编写并注入新的辅助函数（如 upload_file()），然后立即调用执行。
• 无框架束缚：没有复杂的类继承或状态机，只有纯粹的 Python 函数和 CDP 命令。Agent 可以根据任务需求灵活组合工具。

2. 极致轻量与透明

• 代码极少：核心逻辑仅约 592 行 Python 代码。
  • run.py (~36 行): 启动入口。
  • helpers.py (~195 行): 初始工具集，Agent 的主要编辑对象。
  • admin.py + daemon.py (~361 行): CDP WebSocket 桥接与守护进程。
• 直连 CDP：通过 WebSocket 直接与 Chrome 通信，中间无任何代理层或抽象层阻碍，延迟极低，控制权极高。

3. 本地与云端双模式

• 本地连接：直接连接你正在使用的真实浏览器，实时观察 Agent 的操作过程。
• 免费远程浏览器：提供免费的云端浏览器实例（3 个并发、支持代理、验证码解决），适用于隐身任务、子代理部署或无头环境。无需信用卡即可在 cloud.browser-use.com 获取 API Key。

快速开始

1. 安装与连接

首先，克隆仓库并按照 install.md 指引安装依赖，并将 Harness 连接到你的本地 Chrome 浏览器（需开启远程调试端口）。

git clone https://github.com/browser-use/browser-harness.git
cd browser-harness
pip install -r requirements.txt
# 按照 install.md 启动 Chrome 远程调试模式

2. 设置提示词 (System Prompt)

将以下提示词粘贴到 Claude Code、Codex 或其他支持代码执行的 AI Agent 中，即可完成初始化设置：

Prompt:
“为我设置 https://github.com/browser-use/browser-harness。

1. 先阅读 install.md 来安装并将此仓库连接到我的真实浏览器。
2. 然后阅读 SKILL.md 了解日常用法。
3. 始终阅读 helpers.py，因为那里是函数所在的位置。
4. 当你打开设置或验证标签页时，激活它，以便我可以看到活动的浏览器标签页。
5. 安装完成后，在我的浏览器中打开此仓库。如果我已登录 GitHub，问我是否应该为你 star 它，作为交互工作的快速演示——只有我说“是”时才点击 star。如果我没有登录，就直接访问 browser-use.com。
6. 当此页面出现时，勾选复选框，以便代理可以连接到你的浏览器。
7. 查看 domain-skills/ 了解示例任务。”

3. 日常使用

• 阅读 SKILL.md：了解如何下达指令。
• 监控 helpers.py：这是 Agent 的“工具箱”，你会看到它随着任务复杂度的增加而不断生长出新的功能函数。
• 观察浏览器：Agent 操作时，你的真实浏览器窗口会同步显示操作过程，透明可控。

工作原理示例：自我修复

假设任务是“登录并上传头像”，但初始 helpers.py 中没有上传功能：

1. Agent 分析：发现需要上传文件，但现有工具集中无对应函数。
2. 读取代码：Agent 读取 helpers.py 第 192-199 行。
3. 编写代码：Agent 编写一个新的 upload_file(selector, file_path) 函数，利用 CDP 的 DOM.setFileInputFiles 命令。
4. 注入执行：将新函数追加到 helpers.py，重新加载模块。
5. 完成任务：调用新编写的 upload_file()，成功上传。

# helpers.py (Agent 自动添加)
def upload_file(selector: str, file_path: str):
    """Uploads a file to the specified input element."""
    backend_node_id = get_backend_node_id(selector)
    client.send('DOM.setFileInputFiles', {
        'files': [file_path],
        'backendNodeId': backend_node_id
    })
    print(f"✓ File uploaded to {selector}")

适用场景

• 复杂网页自动化：处理动态加载、多步表单、验证码等传统脚本难以维护的场景。
• AI Agent 开发：为 LLM 提供一个安全、可控且可进化的浏览器操作沙箱。
• 数据抓取与测试：需要模拟真实用户行为的高级爬虫或 E2E 测试。
• 个人效率助手：让 AI 帮你自动完成 repetitive 的网页操作（如批量下载、信息填报）。