browser-harness 把真实 Chrome 变成 Agent 可操作的环境——薄 CDP 层、可编辑 helper 与 domain skills，让模型能观察、行动并复用站点经验。
browser-harness 是什么？
browser-use/browser-harness 是一个面向 AI Agent 的浏览器控制工具。它把大模型连接到真实 Chrome 或 Chromium，通过 CDP 完成浏览、点击、截图、下载、上传和表单操作，让 Agent 能处理更接近真实工作的网页任务。
项目与文档：
核心设计
browser-harness 更像给 Agent 使用的浏览器运行时，而不是给普通用户手动点击的浏览器插件。
核心思路包括：
- 直接连接 Chrome 或 Chromium。
- 通过 CDP WebSocket 操作页面。
- 让 Agent 结合截图、坐标点击、DOM、网络请求和原始 CDP 完成任务。
- 把任务中补出来的 helper 放进
agent-workspace/agent_helpers.py。 - 把站点级经验沉淀到
agent-workspace/domain-skills/。 - 保持核心很薄，避免做成庞大的自动化平台。
该项目强调薄 CDP harness、可编辑 helper 和 domain skills。重点不是内置所有网站能力，而是给 Agent 一个足够贴近真实浏览器的操作层，让它在任务中补齐缺失能力。
和传统浏览器自动化有什么不同
传统浏览器自动化通常围绕 Playwright、Selenium 或 Puppeteer 这类测试框架展开。它们适合写确定性脚本：打开页面、定位元素、点击、断言结果。
browser-harness 面向的是另一类任务：用户给出目标后，Agent 自己观察页面、判断状态、处理弹窗、补 helper，并复用站点经验。
| 维度 | Playwright / Selenium / Puppeteer | browser-harness |
|---|---|---|
| 主要用户 | 人写脚本，机器执行 | Agent 边观察边行动 |
| 任务形态 | 固定流程、稳定测试 | 开放目标、动态页面 |
| 常用依据 | selector、断言、测试步骤 | 截图、DOM、CDP、网络状态 |
| 优势 | 成熟、稳定、适合 E2E 测试 | 更贴近 Agent 自主操作网页 |
| 局限 | 需要人先写清楚流程 | 权限和误操作风险更高 |
它不是 Playwright 的替代品。稳定端到端测试继续用 Playwright 更合适；browser-harness 的价值在于把真实网页变成 Agent 可操作的环境。
为什么强调真实 Chrome
很多浏览器 Agent 工具使用隔离或无头浏览器，部署更简单，但不一定能复用用户真实工作里的登录态、扩展、书签和浏览器环境。
browser-harness 支持连接本机 Chrome，也支持 Browser Use cloud browser。连接本机浏览器常见方式包括：
- 通过
chrome://inspect/#remote-debugging允许当前 Chrome 实例被连接。 - 使用
--remote-debugging-port=9222 --user-data-dir=...启动隔离 profile。
取舍可以这样理解：
- 复用当前 Chrome：更贴近真实用户工作流，可复用登录态、扩展和书签，但权限边界更敏感。
- 隔离 profile：更适合无人值守或长期自动化，环境更可控，但需要重新登录和配置。
- 云浏览器：便于隔离和托管，适合自动化任务，但和用户本机环境的贴合度较低。
真实浏览器很强，但也意味着 Agent 可能触达邮箱、支付后台、云控制台、CRM、公司系统和个人账号。连接方式需要按风险选择。
可编辑 helper 和 domain skills
browser-harness 把「Agent 学到的经验」设计进项目结构里。
agent_helpers.py
agent-workspace/agent_helpers.py 用于放任务中临时补出来的 helper。例如文件上传、下载等待、表格读取、弹窗处理等逻辑，如果在某次任务中发现现有能力不够，Agent 可以补一个更稳定的函数，下次复用。
domain-skills/
agent-workspace/domain-skills/ 用于保存站点级经验。它适合沉淀某个网站或后台系统的操作知识，例如：
- 登录后页面如何跳转。
- 哪些弹窗会挡住主流程。
- 哪些 selector 稳定，哪些只是临时样式名。
- 上传、下载、iframe、shadow DOM、跨域组件如何处理。
- 某个后台系统有哪些隐藏等待和异步状态。
网页自动化的难点往往不是「点击按钮」本身，而是处理这些真实页面细节。把经验沉淀成 domain skills，能让 Agent 下一次少走弯路。
适合哪些场景
browser-harness 更适合：
- 帮用户操作真实网页后台。
- 在没有 API 的系统里完成重复流程。
- 处理登录态依赖强的个人或企业网页任务。
- 需要截图判断页面状态的复杂交互。
- 让 Agent 在执行中补工具、补站点经验。
- 多个子 Agent 各自使用独立浏览器执行任务。
- 研究浏览器 Agent 的运行时设计。
具体例子包括：
- 整理网页表格。
- 提交内部系统表单。
- 下载账单或报告。
- 上传文件。
- 处理报销流程。
- 检查订单状态。
- 在 SaaS 控制台配置资源。
- 从登录后的网页提取信息。
如果任务只是抓取静态网页，不一定需要浏览器。静态页面通常可以直接用 HTTP 批量获取；浏览器应该留给需要页面状态、登录态和交互的场景。
需要注意的风险
让 AI Agent 接管真实 Chrome 很强，也很敏感。
权限边界
真实 Chrome 里可能有邮箱、支付后台、云控制台、公司系统和个人账号。Agent 能操作浏览器，就相当于获得了这些网页权限的一部分。
凭据处理
不要把密码、验证码、支付信息或二次验证交给模型。遇到敏感登录和确认步骤，Agent 可以等待用户完成，但不应该读取、保存或输入敏感凭据。
不可逆操作
自动化不等于可以托管。网页任务中可能出现风控、误点击、数据删除、批量提交和不可逆操作。建议先从只读、低风险、可回滚流程开始。
domain skills 隐私
站点经验可以沉淀，但不要把账号、内部 URL、客户数据、一次性任务细节或敏感坐标流水账写进去。
连接方式选择
需要复用日常登录态时，当前 Chrome 很方便；长期自动化或无人值守任务更适合隔离 profile 或云浏览器。
对 AI Agent 工具的意义
browser-harness 代表一种务实的 Agent 工具路线：少做平台，多给模型一个能触达真实环境的接口。
过去很多 Agent 卡在两端：
- 模型能推理，但摸不到真实页面状态。
- 自动化框架很强，但需要人先把流程写死。
browser-harness 试图连接这两端：浏览器负责真实世界状态，Agent 负责观察、判断、行动和补工具。
「自我改进 harness」的意义不在于 Agent 会突然变聪明，而在于可复用操作经验会被保存到项目结构里。下一次遇到类似站点或流程时，Agent 不必从零开始。
使用建议
- 先从低风险任务开始，比如读页面、截图、提取信息。
- 确认页面状态识别稳定后，再尝试点击、上传和提交。
- 涉及账号、支付、删除、发送、发布等动作时，保留人工确认。
- 把长期自动化放在隔离 profile 或云浏览器中运行。
- 给 domain skills 做脱敏，避免保存个人或公司敏感信息。
- 对稳定测试场景继续使用 Playwright、Selenium 或 Puppeteer。
总结
browser-use/browser-harness 值得关注，不是因为它包装了很多高级功能，而是因为它把浏览器 Agent 的几个关键问题放到同一套设计里：真实 Chrome、CDP、截图驱动、可编辑 helper、站点技能沉淀和用户权限边界。
如果目标是稳定 E2E 测试，传统浏览器自动化仍然更成熟。如果目标是让 Codex、Claude Code 等 Agent 直接处理真实网页任务，browser-harness 提供了一个更贴近 Agent 工作方式的入口。
