项目概览
Browser Harness 是由 browser-use 团队开发的一个自愈式浏览器控制框架，总计约 592 行 Python 代码，直接基于 Chrome DevTools Protocol（CDP）构建。它让 LLM Agent 能够通过一个 Unix Socket 连接到用户已运行的 Chrome 浏览器，实现完全自由地完成任何浏览器任务。其核心定义是：最简单、最轻量的自愈式浏览器控制装置——Agent 在任务执行过程中发现缺少什么功能，就当场写出来补上，无需重启、无需框架更新。该项目旨在解决 LLM Agent 如何以最少的前置代码、最大的灵活性控制真实浏览器的问题。传统方案要么依赖重量级框架（如 Playwright、Selenium），要么把所有交互逻辑预先编码。Browser Harness 反其道而行，只提供一个极薄的 CDP 桥接层（daemon + helpers），剩下的能力由 Agent 在任务执行中即时编写。
解决什么问题
Browser Harness 解决的核心问题是：LLM Agent 如何以最少的前置代码、最大的灵活性控制真实浏览器。传统方案存在五大困境：
- 框架臃肿，学习曲线陡：Playwright、Selenium 等框架需要安装完整的浏览器二进制文件（数百 MB），API 层级深，每次交互都要经过框架的抽象层，无法直接利用底层 CDP 能力。
- 选择器脆弱性：传统自动化依赖 CSS 选择器或 XPath，但现代 Web 应用使用 CSS Modules / CSS-in-JS 生成随机类名、Shadow DOM 隔离内部元素、iframe 嵌套造成跨域访问限制、SPA 框架的虚拟 DOM 导致元素频繁重建。
- 预编码思维局限：传统方案要求开发者提前设想所有交互场景并编码，但 Agent 面对的场景千变万化——弹出对话框、验证码、新页面布局、Shadow DOM、跨域 iframe——不可能全部预编码。
- 框架层与 AI 推理层的割裂：LLM 推理一次操作到调用框架 API 再到框架翻译成底层协议，中间层越多，延迟越高、调试越难、能力越受限。
- 会话状态管理困难：浏览器的登录态、Cookie、Profile 数据如何在本地和云端之间同步、如何在多个 Agent 之间隔离，传统方案缺乏原生支持。
工作方式
Browser Harness 采用三层架构：
- 第一层：运行入口（run.py，36 行）：从 stdin 读取 Python 代码，预导入所有 helpers 和 admin 函数，自动启动 daemon。
- 第二层：工具集（helpers.py，约 195 行）：提供给 Agent 的浏览器操作函数，包括导航（goto、new_tab、page_info）、输入（click、type_text、press_key、scroll、upload_file）、视觉（screenshot）、标签页（list_tabs、switch_tab、ensure_real_tab）、DOM（js、dispatch_key）、网络（http_get）和原始 CDP 命令（cdp）。
- 第三层：Daemon 桥接（daemon.py + admin.py，约 361 行）：daemon.py 负责连接 Chrome 的 CDP WebSocket、自动附加到第一个真实页面、监听 Unix Socket 上的请求、转发 CDP 命令和响应、缓冲事件（deque(maxlen=500)）、处理 session 过期自动重连。admin.py 负责 ensure_daemon() 幂等启动 daemon、start_remote_daemon() 创建 Browser Use 云浏览器、restart_daemon() / stop_remote_daemon() 停止 daemon、list_cloud_profiles() / list_local_profiles() Profile 管理、sync_local_profile() 本地 Profile Cookie 同步到云端。
通信协议极简——一行 JSON 一请求，通过 Unix Socket 双向通信。
核心能力
- 极简主义：整个项目只有约 592 行 Python，核心运行时文件精简
- 自愈优先：Agent 发现缺少功能时直接编辑 helpers.py 写出该功能，无需重启、无需框架更新
- 坐标点击默认：使用 Input.dispatchMouseEvent 在 compositor 层执行，能穿透 iframe、Shadow DOM、跨域边界
- 连接用户浏览器：连接到用户已运行的 Chrome，登录态、Cookie、扩展全部可用
