浏览器控制GUI 自动化AI Agent人工智能MCP 服务AI 技能【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址https://gitcode.com/gh_mirrors/br/browser-harness点击查看免费下载本指南以仓库根目录 SKILL.md同时镜像于 src/browser_harness/SKILL.md为骨架结合 src/browser_harness 源码与测试展开。browser-harness 是一个通过 Chrome DevTools ProtocolCDP直接控制真实浏览器的自愈 harness它让 LLM Agent 可以点击、输入、导航、复用登录会话、处理 JS 渲染页面与反爬页面而无需为每个任务重复实现浏览器自动化。读完本文你将掌握何时该用/不该用它、heredoc 式 CLI 的调用姿势、默认守护进程与多标签页协作模型、本地 Chrome 与远程云浏览器的连接与排障、基于可访问性树的页面操作工作流以及会话录制与视频生成。适用范围什么时候才需要浏览器SKILL.md 的第一个核心原则是不要滥用浏览器。如果一条普通的 HTTP 请求就能读到内容——公开页面、API、文档——请直接用curl或你自己的 fetch 工具让浏览器歇着。只有当任务真正需要以下能力时才升级到 browser-harness交互点击、输入、导航、表单提交登录会话复用用户已登录的 Cookie / SSO 状态JS 渲染内容由前端框架异步生成直接抓取只能拿到空壳反爬页面需要真实浏览器环境才能绕过基本拦截。反过来说如果直接 fetch 失败或只返回壳页面那就升级到浏览器。这与helpers.py中http_get()src/browser_harness/helpers.py#L628-L645的设计一致纯 HTTP 场景用urllib走普通请求只有设置了BROWSER_USE_API_KEY时才通过 fetch-use 代理增强。基础用法heredoc 风格 CLIbrowser-harness 以命令行工具形式运行多行命令使用 heredocbrowser-harness PY print(page_info()) PY关键约定以browser-harness命令调用所有 helper 函数已预导入run.py的exec(code, globals())直接面向预导入的命名空间执行见 src/browser_harness/run.py#L405-L406。run.py在exec之前会调用ensure_daemon()run.py#L400确保守护进程就绪后才执行你的脚本——这就是自愈的第一步守护进程掉了会自动重启。一个任务的首次导航用new_tab(url)而不是goto_url(url)。守护进程会跨多次 CLI 调用保留已附加的标签页所以不要在每个脚本里都重复new_tab()。每个任务/站点保持一个工作标签页。打开新标签页前先用current_tab()和list_tabs()检查现状用switch_tab()复用匹配的标签页。不要在同一 URL 上留重复标签页也不要关闭不是你创建的标签页。任务完成时关闭为该任务创建且不再需要的标签页但如果用户还需要看到它、后续任务明确需要它、或关闭会丢失未保存内容则保留。browser-harness --help会打印完整的子命令清单run.py#L35-L70常用运维命令包括命令作用browser-harness --version打印安装版本browser-harness --doctor/doctor诊断安装、守护进程与浏览器状态browser-harness doctor --json输出机器可读的运行时健康报告browser-harness doctor --fix-snap打印修复 Linux Snap Chromium 阻止 CDP 的步骤browser-harness mac-approve批准 Chrome 的 macOS 远程调试弹窗browser-harness auth login登录 Browser Use Cloud云浏览器认证browser-harness auth status/logout查看/清除云认证状态browser-harness skill打印 skill 全文browser-harness recordings [--latest\|enable\|disable]管理会话录制browser-harness video init/review/export将录制转为视频browser-harness --update [-y]拉取最新版本browser-harness --reload停止守护进程下次调用自动以新代码重启守护进程模型一个连接等于整个 Chrome 实例理解 browser-harness 的关键是它的守护进程模型。一个本地守护进程是到整个 Chrome 实例的连接而不是到某个站点、任务、卡片或 Agent 的连接。它持有一条 CDP WebSocket、一个可变的当前标签页会话并通过本地 IPCPOSIX 下为 Unix SocketWindows 下为 TCP 回环为每次 CLI 调用转发请求。核心实现见 src/browser_harness/daemon.py 的Daemon类daemon.py#L424-L808它同时扮演CDP WS 持有者 IPC 中继。因此正常顺序执行本地任务跨站点、标签页、截图、多轮对话时省略BU_NAME、复用默认守护进程即可。不要发明gmail1375、slack1371这类按任务命名的守护进程——每新建一个本地守护进程就多一条浏览器级 CDP 连接Chrome 可能因此再弹一次 Allow 授权框。一个守护进程只有一个可变的附加/当前标签页。多个 Agent 可以在串行化浏览器操作的前提下共享它把本地 Chrome 当作一条共享的浏览器车道非浏览器工作继续并行。顺序切换标签页、输入、截图都是安全的。不要仅仅因为存在多个 Agent 就再建一个本地守护进程——两个同时切标签页并操作的 Agent 会发生竞态导致一个操作到另一个的标签页上。真正需要同时交互时优先用独立的远程浏览器否则就通过默认守护进程串行化。标签页标记 标记与后台操作new_tab()和switch_tab()会把马头标记附加/移动到被控标签页标题前helpers.py中_mark_tab()的实现见 helpers.py#L388-L393JS 常量TAB_MARKER_JS见 daemon.py#L130但不改变 Chrome 的可见标签页。截图和常规 CDP 输入都在后台进行。永远不要自动调用activate_tab(target)——它会把 Chrome 带到前台。只有用户明确要求看到或切换某个标签页时才调用它也不要把它与switch_tab()配对使用。若想保持页面标题不变在启动守护进程前设置BH_TAB_MARKER0daemon.py的tab_marker_enabled()会据此关闭标记见 daemon.py#L133-L135。超时或页面在隐藏时暂停不是把 Chrome 提到前台的借口。继续使用后台 CDP 操作。对于需要焦点才能工作的页面临时调用cdp(Emulation.setFocusEmulationEnabled, enabledTrue)完成操作并验证后在finally块中关闭它。如果后台控制实在不可行如实上报限制而不是去激活标签页也不要去发明Runtime.evaluate滚动替代方案或跨 frame JS 遍历器。连接模式保持简单设计约束SKILL.md Design Constraints 一节明确要求连接模型保持简单只有四种选择默认守护进程不带BU_NAME命名守护进程BU_NAMExxxBU_CDP_URLHTTP DevTools 端点守护进程会通过/json/version把它解析成 WebSocketdaemon.py#L267-L290适合给一个专用自动化 Chrome 用非默认 profile 启动--remote-debugging-port的场景BU_CDP_WS直接的 WebSocket 端点也是云浏览器的接入方式start_remote_daemon(...)云端供给。run.py中有个值得注意的防护设置了BU_CDP_URL或BU_CDP_WS时会阻止云浏览器自动拉起_explicit_cdp_configured()run.py#L99-L100防止用户的显式端点被云 WebSocket 悄悄覆盖并产生计费。本地 Chrome诊断、自愈与 macOS 授权默认守护进程可以容纳很多标签页、访问很多站点browser-harness没有按站点、截图数或结果数限制而需要新建守护进程的限制真正的限制是 Chrome 内存与页面复杂度。标签页复用的正确姿势是list_tabs()switch_tab()。--doctor 诊断与自愈顺序守护进程变陈旧时优先使用其内置的重新附加/恢复机制。命令超时、输出截断、站点变化、标签页被关、新任务——这些都不是新建守护进程的理由。只有守护进程真的死了或无法恢复时才运行browser-harness --doctor并重启/替换默认守护进程。run_doctor()admin.py#L1404-L1456是只读诊断检查平台、Python、版本、安装模式、Chrome 是否在运行、守护进程是否存活、活动浏览器连接、云认证状态还包含 Linux Snap 检测。退出码 0 表示健康。自愈流程ensure_daemon()admin.py#L525-L708是幂等的依次处理陈旧守护进程用真实 CDP 调用探测而非仅 ping、Chrome 未运行自动拉起并重试、冷启动 Chrome、以及chrome://inspect上缺失的 Allow 授权。browser-harness --doctorChrome 完全没运行harness 自动启动它并重试。Chrome 运行中但没开远程调试harness 会打开chrome://inspect/#remote-debugging在 Chrome 的chrome://inspect/#remote-debugging页面勾选 Allow remote debugging for this browser instance见 docs/setup-remote-debugging.png浏览器会为每次新连接弹出一次授权确认docs/allow-remote-debugging.png。macOS 上的 mac-approve 握手在 macOS 上本地 Chrome 弹出 Allow remote debugging? 权限询问时保持原始浏览器命令继续运行在另一个 shell/工具调用中执行mac-approve。必须保留确切的守护进程名如果等待中的命令用了BU_NAMEr7k2则执行BU_NAMEr7k2 browser-harness mac-approve默认守护进程则省略BU_NAME前缀。helper 返回ready后原命令自动恢复执行不要重新运行它。如果 helper 报告accessibility-required请用户给启动 browser-harness 的应用如 Terminal、iTerm、Codex授予一次辅助功能权限系统设置 隐私与安全性 辅助功能然后再次调用mac-approve。这仅针对本地 ChromeBU_CDP_URL、BU_CDP_WS或 Browser Use Cloud 不需要它。实操要点当 shell 工具能让进程保持运行状态时首个本地命令用 3-5 秒的短 yield不要用 30 秒等待。如果命令以 Allow 提示 yield保持该进程运行立即在第二个工具调用中执行browser-harness mac-approve然后恢复/轮询原进程。如果用户先点了 Allow同样的握手也能完成原命令成功返回就是反馈守护进程已连接时mac-approve同样返回ready。mac-approve仅限 macOS。在 Linux 或 Windows 上保持原浏览器命令运行Chrome 弹出授权对话框时请用户点 Allow——用户点击完成同样的握手然后恢复/轮询原进程等待成功不要重跑或创建替代守护进程。远程浏览器Browser Use Cloud对于无头服务器、并行子 Agent 或需要隔离的工作使用 Browser Use Cloud。云浏览器是 Browser Use 托管的受管 Chrome 实例每个都是全新、隔离的浏览器。在以下场景应主动建议并简短解释原因用户想要多个并发任务本地 Chrome 是共享浏览器并行任务会争夺标签页和焦点每个任务一个云浏览器则完全隔离。很可能出现验证码或拦截抓取、重复自动访问、对机器人敏感的站点云浏览器使用干净的托管 IP 和 stealth 设置更不容易被验证码墙或限流同时用户的 IP 和本地浏览器不参与其中。认证与启动远程浏览器需要 Browser Use Cloud 认证。在依赖它之前先检查browser-harness auth status。auth login会把认证存储下来供后续进程使用因此 API key 无需传给每个 Agent 进程没有存储的认证或可用的BROWSER_USE_API_KEY时回到默认本地守护进程串行化工作。认证实现见 src/browser_harness/auth.py支持 OAuth 浏览器回调PKCE S256、--device-code设备码流程适合 SSH/无头环境、以及--api-key-stdin从 stdin 安全导入 keyauth.py#L508-L543。存储的凭证写入配置文件目录下的auth.json权限 600。# 交互式 OAuth 登录 browser-harness auth login # 安全导入 key避免出现在进程列表/历史里 printf %s $BROWSER_USE_API_KEY | browser-harness auth login --api-key-stdin起一个简短的自造名字r7k2只是占位符browser-harness PY start_remote_daemon(r7k2) PY BU_NAMEr7k2 browser-harness PY new_tab(https://example.com) print(page_info()) PYstart_remote_daemon(name, **kwargs)admin.py#L997-L1036向POST /browsers转发创建参数常用参数包括profileId云 profile UUID直接以已登录状态启动、profileName按名字解析、proxyCountryCodeISO2 国家代码默认us传None禁用 BU 代理、timeout分钟1..240、customProxy、browserScreenWidth/Height、allowResizing、enableRecording。它返回包含liveUrl的完整 browser dict默认会打印并在检测到 GUI 时自动打开该 URL。使用要点任务完成且云浏览器仍在运行时直接询问我现在关闭这个浏览器吗 是则执行stop_remote_daemon(name)。远程守护进程在停止或超时前会持续计费。不要启动远程守护进程后又继续用默认守护进程BU_NAME要保持与启动时同名。云 profile Cookie 同步参考 profile-sync.md。信任编排器可以在供给云守护进程时设置BH_OPEN_LIVE_URL0禁止打印/打开实时预览 URLURL 仍会被创建并由start_remote_daemon()返回调用方需避免记录该字段。已供给精确命名守护进程的信任编排器可设置BH_REQUIRE_EXISTING_DAEMON1每次 CLI 调用都健康检查并复用该守护进程失败即关闭fail closed绝不自动启动或发现另一个 Chromerun.py#L387-L391、admin.py#L711-L730。页面工作流可访问性树优先坐标点击默认SKILL.md 的Page Workflow给出了 LLM 操作页面的推荐路径其底层全部由 src/browser_harness/helpers.py 实现1. 优先用可访问性树找元素而不是截图nodes cdp(Accessibility.getFullAXTree)[nodes]该调用返回每个元素的 role、name 和backendDOMNodeId——节点可能有数千个先在 Python 里过滤再打印。得到坐标q cdp(DOM.getBoxModel, backendNodeIdn)[model][content] x, y sum(q[0::2]) / 4, sum(q[1::2]) / 4 # 视口像素坐标可直接交给 click_at_xy坐标若为负或超大说明需要先滚动。2. 点击链路AX 节点 → 盒子中心 →click_at_xy(x, y)→ 用一次有针对性的js(...)/page_info()检查验证结果。click_at_xyhelpers.py#L174-L194通过Input.dispatchMouseEvent的 mousePressed/mouseReleased 实现还支持--debug-clicks在截图上绘制点击位置十字标记。3. 回退策略只有当 AX 树缺元素canvas、奇特控件时才用js(...)回退到原始 HTML布局或图像相关的场景才截图。4. 导航与等待导航后调用wait_for_load()轮询document.readyState complete超时 15 秒见 helpers.py#L488-L494当前标签页陈旧或内部页时调用ensure_real_tab()坐标工具不适用时用js(...)做 DOM 检查/提取原始 CDP 用cdp(Domain.method, ...)。其他关键 helper均可预导入直接使用输入type_text(text)Input.insertText绕过框架事件监听fill_input(selector, text, clear_firstTrue, timeout0)面向 React/Vue/Ember 等受控输入先聚焦、全选清空、逐字符真实按键、再派发合成inputchange事件见 helpers.py#L208-L247press_key(key, modifiers)修饰键位1Alt、2Ctrl、4Meta/Cmd、8Shift按物理键码派发见 helpers.py#L295-L324。输入超长文本时避免逐字符慢速输入改用页面适配的快速输入法然后验证页面保留了精确值。滚动scroll(x, y, dy-300, dx0)鼠标滚轮事件。截图capture_screenshot(pathNone, fullFalse, max_dimNone)——在 2× 高分屏上建议max_dim1800使文件不超过某些图像模型强加的 2000px/边限制云浏览器截图走 60 秒 IPC 超时预算SCREENSHOT_IPC_RESPONSE_TIMEOUT_SECONDShelpers.py#L45。标签页list_tabs(include_chromeTrue)、current_tab()、switch_tab(target, activateFalse)、activate_tab(target)、new_tab(url)、close_tab(target)、ensure_real_tab()实现见 helpers.py#L357-L474。switch_tab默认只附加不改变可见标签页。等待wait(seconds)、wait_for_load(timeout15)、wait_for_element(selector, timeout10, visibleFalse)visibleTrue时用checkVisibility检查祖先链上的display:none/visibility:hidden/opacity:0弥补 SPA 场景下wait_for_load的盲区、wait_for_network_idle(timeout10, idle_ms500)基于drain_events()的事件流自动过滤当前会话之外后台标签页的 Network 事件。文件上传upload_file(selector, path)DOM.setFileInputFiles。登录墙的处理停下来询问。例外Chrome 已登录时自动使用可用的 SSO但密码、MFA、同意页或账号选择不明确时仍然停下询问。录制与视频新装默认不录制。用户可启用本地后台录制browser-harness recordings enable browser-harness recordings disable browser-harness recordingsBH_RECORD1或BH_RECORD0覆盖单进程的偏好recorder.py的_env_override()recorder.py#L86-L91BH_RECORD_IDLE控制自动录制 180 秒空闲滚动切换。任何自然的录制展示演示做视频意图会让该任务自动开启录制单是工作量很大不会。浏览器工作前调用start_recording(name, title...)保留其返回的确切目录验证结果后调用stop_recording()。不要用recordings --latest替换该路径。任务之后才提出的请求用browser-harness recordings --latest仅在时间戳与页面匹配时使用否则如实说明工作未被捕获。永远不要重演已完成的任务。录制的内部结构src/browser_harness/recorder.py一个录制就是一个目录位于BH_AGENT_WORKSPACE/recordings/name/包含meta.jsonname/title/started、events.jsonl每个动作一行 JSONhelper、坐标/文本、URL、视口、聚焦元素盒、帧文件名以及每动作后的0001.jpg...视口截图。只有ACTIONS集合内的动作goto_url、click_at_xy、type_text、fill_input、press_key、scroll、new_tab、switch_tab、wait_for_* 等见 recorder.py#L31-L36会产生帧只读 helperjs、page_info、capture_screenshot不产生帧避免录制膨胀。所有写入 trace 的 URL 都会经过敏感参数清洗OAuth code、token、session_state 等被替换为REDACTEDrecorder.py#L44-L53密码输入以圆点掩码记录。视频生成遵循 make-video.md若有子 Agent可让其基于确切录制路径做后期制作主 Agent 同时返回任务结果。Interaction Skills浏览器机制速查卡在某个浏览器机制上时参考 interaction-skills 目录下的专项文档connection.md、cookies.md、profile-sync.md、tabs.mdiframes.md、cross-origin-iframes.md、shadow-dom.mddialogs.md、downloads.md、uploads.mddrag-and-drop.md、dropdowns.md、scrolling.mdnetwork-requests.md、screenshots.md、viewport.mdprint-as-pdf.md、make-video.md安装与环境相关见仓库根目录 install.md 与 docs/MCP.md。设计约束与常见坑Gotchas设计约束SKILL.md Design Constraints 一节从架构上保证了这套工具的可维护性坐标点击默认CDP 鼠标事件在合成器层面穿透 iframe/shadow DOM/跨源 frame所以坐标点击天然不受 DOM 封装限制。连接模型保持简单只允许默认守护进程、BU_NAME、BU_CDP_URL、BU_CDP_WS、start_remote_daemon(...)五种方式。核心 helper 保持精简任务特定的 helper 扩充放到$BH_AGENT_WORKSPACE/agent_helpers.py——helpers.py底部的_load_agent_helpers()会把它动态加载进预导入命名空间helpers.py#L653-L668仓库中的 agent-workspace/agent_helpers.py 就是可编辑扩展点。高频坑清单本地 Chrome 控制必须启用chrome://inspect/#remote-debugging。macOS 上本地 Chrome 弹出 Allow remote debugging? 时用相同BU_NAME调用一次mac-approve原浏览器命令保持等待不要轮询或重跑浏览器命令远程/云浏览器不用这个 helper。Omnibox 弹窗不是真实的工作标签页。CDP target 顺序 ≠ Chrome 可见标签栏顺序。BU_CDP_URL是 HTTP DevTools 端点守护进程会解析为 WebSocket。离开运行中的云浏览器前先询问停止用stop_remote_daemon(name)或PATCH /browsers/{id} {action:stop}。Linux 下 Snap 打包的 Chromium 无法按 browser-harness 需要的方式暴露 DevToolsbrowser-harness doctor --fix-snap会给出安装原生 Chrome 并设置BH_CHROME_PATH的指引参考 docs/snap-linux-headless.md。Domain Skills站点专项技能Domain Skills 默认关闭BH_DOMAIN_SKILLS1时启用未启用时忽略该节。启用后在发明方案之前先搜索$BH_AGENT_WORKSPACE/domain-skills/host/目录goto_url(...)会对导航到的 host 返回最多 10 个技能文件名helpers.py#L152-L157 中该功能通过解析 hostname 定位domain-skills/site/目录并收集其中的*.md实现。仓库内置的 agent-workspace/domain-skills 覆盖了大量站点amazon、linkedin、github、youtube、reddit、x 等百余个站点目录每个站点目录下是针对该站点的操作手册。如果BH_DOMAIN_SKILLS1且任务是站点特定的在发明新方案前必须读完匹配目录下的每一个文件。源码级运行机制速览最后把 SKILL.md 描述的行为与源码对应起来便于深入阅读入口src/browser_harness/run.py 的main()/_run()分发所有子命令脚本模式先读 stdin、打更新横幅、按需拉起守护进程、安装 helper 追踪_traced记录每个 helper 调用的参数、耗时、错误供录制observe()和遥测使用run.py#L156-L178最后exec你的脚本。守护进程src/browser_harness/daemon.py 的Daemon.start()解析 WS URLget_ws_url()依次考虑BU_CDP_WS、BU_CDP_URL、DevToolsActivePort、9222/9223 探测、附加首个真实页面、启用 Page/DOM/Runtime/Network 域handle()实现 IPC 协议ping 存活探测、drain_events 事件排空、set_session 切换会话、stale-session 自动恢复。helper 层src/browser_harness/helpers.py 是全部预导入 helper 的实现覆盖导航、输入、视觉、标签页、等待与 JS 求值。诊断与运维src/browser_harness/admin.py 的ensure_daemon()、run_doctor()、start/stop_remote_daemon()、restart_daemon()。录制src/browser_harness/recorder.py。认证src/browser_harness/auth.py。测试佐证tests/unit 下的test_run.py、test_daemon.py、test_admin.py、test_ipc.py、test_recorder.py、test_auth.py等覆盖了上述各模块的行为。安装、升级与远程调试的具体步骤以 install.md 和 docs/MCP.md 为准本文所有命令与参数均以当前仓库实际实现为准。赞分享浏览器控制GUI 自动化AI Agent人工智能MCP 服务AI 技能【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址https://gitcode.com/gh_mirrors/br/browser-harness点击查看免费下载相关推荐isign命令行工具完全指南从基础到高级用法详解isign命令行工具完全指南从基础到高级用法详解 isign是一款强大的命令行工具无需依赖苹果专有软件或硬件即可为iOS应用进行代码签名。本指南将带你从基浏览器控制GUI 自动化AI Agent人工智能MCP 服务AI 技能Open Design Design Browser内嵌浏览器模块、Reference Board 与 browser-harness 任务入口实战Open Design Design Browser内嵌浏览器模块、Reference Board 与 browser harness 任务入口实战 本文以仓AI 应用人工智能AI 技能设计系统媒体生成终极AI浏览器助手WebUI实战指南让浏览器自动完成任何网页任务终极AI浏览器助手WebUI实战指南让浏览器自动完成任何网页任务 想要一个能帮你自动完成网页搜索、数据收集、在线操作的最强大脑级AI助手吗GitHub T人工智能AI 应用交互助手浏览器控制上一篇AwesomeQRCode源码阅读笔记深入理解二维码渲染核心技术下一篇为什么edgenext_x_small.in1k是移动视觉首选0.5 GMACs低算力模型性能评测创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考