browser

browser-harness

通过 CDP 直接控制浏览器。对于特定任务的编辑，请使用 agent-workspace/agent_helpers.py。对于设置、安装或连接问题，请阅读 install.md。

默认关闭域名技能（agent-workspace/domain-skills/ 下由社区贡献的各站点操作手册）。设置 BH_DOMAIN_SKILLS=1 即可启用；请参阅底部章节。

如果 BH_DOMAIN_SKILLS=1 且任务与特定网站有关，请先阅读匹配的 agent-workspace/domain-skills/<site>/ 目录中的所有文件，再着手制定方案。

用法

browser-harness <<'PY'
new_tab("https://docs.browser-use.com")
wait_for_load()
print(page_info())
PY

• 通过 browser-harness 调用——它已在 $PATH 中。无需 cd，也无需 uv run。
• 所有多行命令都使用 heredoc 格式。这样可以避免 Python 字符串和 JavaScript 代码片段中的引号被 shell 错误处理。
• 首次导航应使用 new_tab(url)，而非 goto_url(url)——goto 会在用户当前活动标签页中运行，覆盖其正在进行的操作。

工具调用格式

browser-harness <<'PY'
# any python. helpers pre-imported. daemon auto-starts.
PY

run.py 会在 exec 之前调用 ensure_daemon()——除非你有意为之，否则无需手动启动或停止。

远程浏览器

可将远程浏览器用于并行子 Agent（每个子 Agent 通过不同的 BU_NAME 使用独立的浏览器），或用于无头服务器。必须设置 BROWSER_USE_API_KEY。start_remote_daemon、list_cloud_profiles、list_local_profiles、sync_local_profile 均已预先导入。

browser-harness <<'PY'
start_remote_daemon("work")                               # default — clean browser, no profile
# start_remote_daemon("work", profileName="my-work")      # reuse a cloud profile (already logged in)
# start_remote_daemon("work", profileId="<uuid>")         # same, but by UUID
# start_remote_daemon("work", proxyCountryCode="de", timeout=120)   # DE proxy, 2-hour timeout
# start_remote_daemon("work", proxyCountryCode=None)      # disable the Browser Use proxy
PY

BU_NAME=work browser-harness <<'PY'
new_tab("https://example.com")
print(page_info())
PY

start_remote_daemon 会打印 liveUrl；如果检测到图形界面，还会在本地浏览器中自动打开该网址，以便用户同步观看。无头服务器只会打印网址——请将其分享给用户。守护进程会在关闭时 PATCH 云端浏览器以停止运行，并保留配置文件状态。远程守护进程运行期间会持续计费，直到超时。

配置文件（仅包含 Cookie 的登录状态）位于 interaction-skills/profile-sync.md 中——其中介绍了 list_cloud_profiles()、通过对话询问“使用哪个配置文件？”的模式，以及用于上传本地 Chrome 配置文件的 sync_local_profile()。

交互技能

如果在导航时遇到特定操作难题，请查看 interaction-skills/ 中的辅助工具。它们涵盖对话框、标签页、下拉菜单、iframe 和上传等可复用的界面操作。可用的交互技能包括：

• connection.md
• cookies.md
• cross-origin-iframes.md
• dialogs.md
• downloads.md
• drag-and-drop.md
• dropdowns.md
• iframes.md
• network-requests.md
• print-as-pdf.md
• profile-sync.md
• screenshots.md
• scrolling.md
• shadow-dom.md
• tabs.md
• uploads.md
• viewport.md

实际有效的方法

• 先截图：使用 capture_screenshot() 快速了解当前页面、查找可见目标，并判断是需要点击、选择器还是进一步导航。
• 点击：capture_screenshot() → 从图像中读取像素位置 → click_at_xy(x, y) → capture_screenshot() 验证。不要受 Playwright 习惯影响而“先定位，再点击”——不要使用 getBoundingClientRect，也不要查找选择器。只有在目标没有可见几何位置（隐藏输入框、尺寸为 0×0 的节点）时才查看 DOM。命中测试在 Chrome 浏览器进程中进行，因此点击会穿过 iframe、shadow DOM 和跨域边界，无需额外操作。
• 批量 HTTP：使用 http_get(url) + ThreadPoolExecutor。静态页面无需浏览器（2.8 秒处理 249 个 Netflix 页面）。
• goto 之后：调用 wait_for_load()。
• 标签页错误或过期：使用 ensure_real_tab()。当前标签页过期或为内部标签页时使用此函数；守护进程也会在下次调用时自动从过期会话中恢复。
• 验证：print(page_info()) 是最简单的“页面是否正常运行？”检查，但默认应通过截图验证可见操作是否确实生效。
• 读取 DOM：当截图表明坐标不是合适工具时，使用 js(...) 检查并提取内容。
• iframe 网站（Azure blades、Salesforce）：click_at_xy(x, y) 可穿透 iframe；只有当坐标点击不合适时，才直接操作 iframe DOM。
• 身份验证拦截：如果被重定向到登录页面，请停止并询问用户。不要根据截图输入凭据。
• 对于辅助工具未涵盖的操作，使用原始 CDP：cdp("Domain.method", params)。

设计约束

• 默认使用坐标点击。Input.dispatchMouseEvent 会在合成器层穿过 iframe、shadow DOM 和跨域边界。
• 连接到用户正在运行的 Chrome。不要启动自己的浏览器。
• cdp-use 仅用于 CDPClient.send_raw。优先使用原始 CDP 字符串，而不是类型化封装。
• run.py 保持精简。不要添加 argparse、子命令或额外的控制层。
• 核心辅助函数保持简短。特定任务的辅助函数放在 agent-workspace/agent_helpers.py 中；守护进程/引导程序和远程会话管理放在核心包中。
• 不要添加管理器层。不要添加重试框架、会话管理器、守护进程监控器、配置系统或日志框架。

注意事项（实战验证）

• Omnibox 弹出窗口是假页面目标。需要真实标签页时，请过滤掉 chrome://omnibox-popup... 和其他内部页面。
• CDP 目标顺序 ≠ Chrome 可见的标签栏顺序。用户说“我能看到的第一个/第二个标签页”时，请使用 UI 自动化；Target.activateTarget 只能显示已知目标。
• 默认守护进程会话可能变得陈旧。ensure_real_tab() 会重新连接到真实页面。
• Browser Use API 在线路上的命名方式是 camelCase。比如 cdpUrl、proxyCountryCode 等。
• 远程 cdpUrl 使用 HTTPS，而不是 ws。通过 /json/version 获取 websocket URL。
• 使用 PATCH /browsers/{id} + {"action":"stop"} 停止云浏览器。
• 每次有意义的操作后，都要重新截图，再判断操作是否成功。用图像验证状态是否发生变化、菜单是否打开、是否发生导航、是否出现可见错误，以及页面是否处于预期状态。
• 通过截图引导探索。截图通常是找到下一个点击目标、发现隐藏阻碍以及判断是否值得编写选择器的最快方式。
• 优先使用合成器层操作，而不是框架层变通方案。添加针对 DOM 的变通方案前，先尝试截图、坐标点击和原始按键输入。
• 如果需要针对特定框架的 DOM 技巧，请先查看 interaction-skills/。下拉菜单、对话框、iframe、shadow DOM 和表单的专门指导都应放在那里。

领域技能（选择启用）

仅当 BH_DOMAIN_SKILLS=1 时适用。否则请忽略——agent-workspace/domain-skills/ 处于休眠状态，goto_url 不会显示技能文件。

启用后，在自行构思方案前，先搜索 agent-workspace/domain-skills/<host>/。goto_url 会返回导航到的主机对应的最多 10 个技能文件名。

如果你发现了非显而易见的信息——私有 API、稳定选择器、框架特性、URL 模式、隐藏等待条件或站点特有陷阱——请向 agent-workspace/domain-skills/<site>/ 提交 PR。记录站点稳定可靠的特征（地图，而非日记）。不要写像素坐标（布局变化后会失效）、任务过程描述或机密信息——该目录是公开的。