browser-harness 网络请求观测指南用 CDP Network 事件推断模糊页面状态提交、下载与 SPA 流程【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址: https://gitcode.com/gh_mirrors/br/browser-harness导读本文是 browser-harness 交互技能系列中 network-requests.md 的完整展开核心解决一类典型问题页面状态模糊——表单提交、文件下载、SPA 路由跳转等操作成功后DOM 可能没有任何明显变化单靠截图和wait_for_load()无法判断操作是否真正成功。读完本文你将掌握 browser-harness 基于 CDPNetwork.*事件构建的两层能力开箱即用的wait_for_network_idle()等待原语以及通过drain_events()直接观测、推断网络活动的底层手段并能在真实任务中判断操作是否真的完成了。为什么需要观测网络活动browser-harness 的交互哲学是坐标点击 定向校验见 SKILL.md 的 Page Workflow通过无障碍树定位元素 → 计算坐标 →click_at_xy(x, y)点击 → 再用js(...)/page_info()做针对性校验。这套流程在页面产生可见变化时行之有效但存在三类无感成功场景表单提交提交按钮触发 XHR/fetch服务器接受请求但页面原地不动没有跳转也没有成功提示下载触发点击后浏览器直接进入下载流程页面 DOM 无任何变化SPA 异步动作React/Vue 应用的路由过渡或数据拉取完全由前端 fetch 完成document.readyState早已是completewait_for_load()完全失灵。network-requests.md 给出的指导原则正是watch or infer network activity when page state is ambiguous——把网络事件本身当作状态信号而不是只盯着 DOM。这也是 browser-harness 在守护进程层面默认启用 CDPNetwork域的原因没有它一切网络观测手段都会静默失效。核心原语wait_for_network_idle()用法与参数wait_for_network_idle()是 browser-harness 对页面网络安静下来的直接封装预导入于所有browser-harnessheredoc 会话中定义在 helpers.pywait_for_network_idle(timeout10.0, idle_ms500)参数默认值含义timeout10.0秒最长等待窗口超时返回Falseidle_ms500毫秒在途请求全部结束且再无Network.*事件到达的连续静默时长达到即判定空闲返回值空闲窗口达成返回True超时返回False。该函数基于事件队列实现Builds ondrain_events()— no daemon changes即纯客户端逻辑不要求新建守护进程。典型调用序列browser-harness PY # 假设已通过 AX 树定位并点击了提交按钮 click_at_xy(x, y) # 提交后页面可能原地不动——用网络空闲作为成功信号 if wait_for_network_idle(timeout10.0, idle_ms500): print(网络已空闲提交流程已完成) else: print(10 秒内网络一直未安静可能仍在持续请求或已失败) PY它与wait_for_load()轮询document.readyState complete见 helpers.py和wait_for_element()轮询querySelector存在性见 helpers.py形成互补前两者看 DOM后者看网络。对 SPA 路由过渡、表单提交这类文档早已加载完成、只有 XHR 在跑的场景wait_for_network_idle()是唯一可靠的那个。源码级原理wait_for_network_idle()的实现揭示了一个值得注意的细节它不只要求事件静默还要求没有在途请求。核心状态机如下helpers.pydeadline time.time() timeout last_activity time.time() inflight set() # 在途请求集合 active_session _send({meta: session}).get(session_id) while time.time() deadline: for e in drain_events(): if e.get(session_id) ! active_session: # 只统计当前标签页 continue method e.get(method, ) params e.get(params, {}) if method Network.requestWillBeSent: inflight.add(params.get(requestId)) # 新请求 → 计入在途 last_activity time.time() elif method in (Network.loadingFinished, Network.loadingFailed): inflight.discard(params.get(requestId)) # 完成/失败 → 移除 last_activity time.time() elif method.startswith(Network.): last_activity time.time() # 任何网络事件都算活动 if not inflight and (time.time() - last_activity) * 1000 idle_ms: return True time.sleep(0.1) return False关键设计有三点在途集合inflightrequestWillBeSent时加入loadingFinished/loadingFailed时移除。这意味着即便请求事件之间出现 idle_ms的静默只要还有未结束的请求函数也不会误判空闲session_id过滤事件按当前附加标签页的 CDP session 过滤。你在后台标签页停留过的轮询/SSE 页面仍在不断产生网络事件若不过滤会把当前标签页的空闲判定毒化轮询节奏每次循环仅sleep(0.1)对事件缓冲的消费是增量、非破坏性的——drain_events()取走缓冲区全部事件后清空由 daemon 端维护。测试用例佐证单元测试 test_helpers.py 用伪造的事件序列精确锁定了这些语义test_wait_for_network_idle_waits_for_inflight_requestrequestWillBeSent之后即便静默超过idle_ms也不得返回True必须等到对应的loadingFinishedtest_wait_for_network_idle_returns_false_on_timeout持续的requestWillBeSent让在途集合始终非空最终超时返回Falsetest_wait_for_network_idle_filters_events_to_active_session后台 session 的请求事件必须被忽略只统计{meta: session}返回的当前 session。这些测试直接对应上文源码中的三条设计是理解wait_for_network_idle()行为边界的最快途径。底层事件基础设施Network 域如何被自动启用观测网络的前提是 CDPNetwork域已开启。browser-harness 的守护进程在两类时机自动完成启用见 daemon.py 的_enable_default_domains初始 attach连接标签页时每次switch_tab()/new_tab()之后每个新建的 CDP session 默认所有域都是禁用状态若不禁用wait_for_network_idle()等依赖Network.*事件的助手会在切换标签页后静默收不到事件。实现上对Page、DOM、Runtime、Network四个域用asyncio.gather并行下发.enable最坏耗时被限制在单次 CDP 往返内——这对set_session路径尤其重要因为该路径的 IPC socket 有 5 秒读超时。配套的还有一道防御性清理set_session切换标签页时守护进程会对旧 session下发Network.disabledaemon.py把后台标签页的流量挡在全局事件缓冲之外。不过正如源码注释所写这道清理只是defense in depth真正的正确性闸门仍是wait_for_network_idle()消费端的session_id过滤。tests/unit/test_daemon.py中多处断言如 test_daemon.py验证了新建 session 后Network.enable必然出现在启用集合中。事件缓冲本身由drain_events()消费helper 发送{meta: drain_events}helpers.pydaemon 端一次性取出全部事件并清空缓冲区daemon.py。所有 CDP 事件含Network.*在 daemon 的_record_event钩子中被记录进缓冲见 daemon.py。主动观测直接消费 Network.* 事件流wait_for_network_idle()只回答网络是否安静这一个问题。当需要看具体发生了什么时可以直接在 heredoc 中消费drain_events()返回的事件browser-harness PY import time # 清空旧事件避免混入点击前的流量 drain_events() click_at_xy(x, y) # 触发一次 XHR 提交 collected [] deadline time.time() 10 while time.time() deadline: for e in drain_events(): m e.get(method, ) if m in (Network.requestWillBeSent, Network.loadingFinished, Network.loadingFailed): collected.append((m, e.get(params, {}).get(requestId))) if collected and Network.loadingFinished in {c[0] for c in collected}: break time.sleep(0.1) for m, rid in collected: print(m, rid) PYdrain_events()返回的每条事件都带method、params与session_id你可以按需筛选Network.requestWillBeSent含request.url、request.method、request.postData等字段、Network.responseReceived、Network.loadingFinished/Network.loadingFailed据此判断请求是否真的发出、发给哪个 URL是成功了loadingFinished还是失败了loadingFailedparams.errorText带失败原因提交的数据内容request.postData。此外 browser-harness 通过cdp(Domain.method, ...)暴露完整 CDP 通道helpers.pySKILL.md 的 Page Workflow 亦明确 Raw CDP is available withcdp(Domain.method, ...)。基于这一通用原语你可以按需调用Network域的其他方法做进一步取证例如获取某个请求 ID 的响应体。注意这类原始 CDP 调用依赖requestId取自上文事件流且属于Network域的标准协议能力需自行处理协议细节。三种典型场景的观测策略1. 表单提交无跳转、无提示click_at_xy(x, y) # 点击提交 ok wait_for_network_idle(10, 500) # 等待提交请求结束 if ok: # 再结合 DOM 定向校验确认成功状态被渲染 print(js(document.body.innerText.slice(0, 200)))2. SPA 路由过渡文档已完成只有 fetch 在跑wait_for_load()对 SPA 完全无效readyState早就complete。改用网络信号js(history.pushState({}, , /detail/123)) # 或点击路由链接 wait_for_network_idle(15, 500) # 等待数据拉取完成 wait_for_element(.detail-content, 10) # 再等新内容渲染3. 下载触发页面不动流量发生下载本身不改变 DOM且下载流通常不经过页面 JS 可见的 fetch。观测策略是点击后观察Network.requestWillBeSent中目标 URL 的出现drain_events() click_at_xy(x, y) target_urls [] deadline time.time() 8 while time.time() deadline: for e in drain_events(): if e.get(method) Network.requestWillBeSent: url e.get(params, {}).get(request, {}).get(url, ) if download in url or export in url: target_urls.append(url) time.sleep(0.1) print(触发的下载请求:, target_urls)需要说明的是完整下载行为的判定还涉及Browser.setDownloadBehavior等下载域知识可进一步参考同目录下的 downloads.md。何时不该用浏览器观测网络network-requests.md 所在的技能体系强调先判断是否需要浏览器。browser-harness 的 SKILL.md 明确划出边界纯 HTTP 能拿到的公开内容直接用curl或 fetch 工具不要动用浏览器。仓库为此提供了http_get(url, headersNone, timeout20.0)helpers.py走纯urllib设置了BROWSER_USE_API_KEY时可路由到带反爬处理的 fetch-use 代理适合静态页面与 API。只有需要交互点击、输入、导航、登录态、JS 渲染或反爬页面时才升级到浏览器观测手段。实践要点与易错项先drain_events()清空缓冲再触发动作否则会把点击前页面自身加载的流量算进来wait_for_network_idle()返回False不等于操作失败只代表 10 秒内网络未安静——长轮询、SSE、持续心跳的页面会一直不空闲此时应改用带超时的定向事件匹配或直接看 DOM 断言切换标签页后网络事件不会自动跟随daemon 对每个新 session 自动执行Network.enabledaemon.py但你手动消费事件时仍要按session_id过滤否则后台标签页的流量会干扰判断不要用wait_for_network_idle()替代必要的 DOM 校验网络空闲是请求完成的证据不是业务成功的证据两者结合才是可靠的完成判定整个观测过程基于后台 CDP 操作不需要把 Chrome 切到前台聚焦型页面如需临时模拟焦点按 SKILL.md 的建议用Emulation.setFocusEmulationEnabled并在finally中关闭。小结browser-harness 把 CDPNetwork域打造成了随时可用的状态观测通道守护进程在 attach 与每次切页时自动启用Network.enable并维护全局事件缓冲drain_events()供客户端按需消费wait_for_network_idle()提供带在途请求跟踪与session_id隔离的空闲判定。对提交无跳转、下载无 DOM 变化、SPA 异步渲染这类页面状态模糊的任务这套机制给出了不依赖界面快照的、可编程、可验证的完成信号。相关源码入口wait_for_network_idle 实现、Network 域自动启用、事件缓冲与清理、空闲语义测试。【免费下载链接】browser-harnessBrowser Harness | Self-healing harness that enables LLMs to complete any task.项目地址: https://gitcode.com/gh_mirrors/br/browser-harness创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
