为什么一次点击要等那么久:可靠性设计比功能清单更值得看
为什么一次点击要等那么久:可靠性设计比功能清单更值得看
很多人第一次用 Chrome DevTools MCP 都会有一个直觉上的落差:功能列表看起来很朴素——点击、填表、导航、截图、抓 trace,没有"智能规划",也没有"自动修复"。但真正跑起来,一次 click 却往往要停顿半秒到数秒。于是问题变成:它到底在等什么?
读完仓库源码你会发现,这些"多余的时间"几乎全部花在可靠性上:等导航真的发生、等 DOM 真的静下来、等对话框被识别、等同一页面上的前一个动作真正结束。本文按代码路径把这段时间拆开算一遍,顺带说明它为什么坚持驱动一个真实 Chrome,以及这套设计在慢页面上的代价边界。
一次 click 的真实时间线
所有输入类工具(click、hover、fill、press_key、drag、fill_form)都不是直接调用 Puppeteer 的动作方法,而是统一包进 waitForEventsAfterAction。以 click 的实现 为例:
const result = await request.page.waitForEventsAfterAction(
async signal => {
if (shouldSelectNativeOption && (await selectNativeSelectOption(handle, signal))) {
return;
}
await handle.asLocator().click({count: request.params.dblClick ? 2 : 1, signal});
},
);
response.attachWaitForResult(result);
真正的时间成本在 src/utils/WaitForHelper.ts 里。构造函数先定下四个预算:
this.#stableDomTimeout = 3000 * cpuTimeoutMultiplier; // 稳定 DOM 的总上限
this.#stableDomFor = 100 * cpuTimeoutMultiplier; // 静默窗口
this.#expectNavigationIn = 100 * cpuTimeoutMultiplier; // 判定"这次动作有没有触发导航"的观察窗
this.#navigationTimeout = 3000 * networkTimeoutMultiplier; // 导航完成的上限
一次动作的完整顺序是:
- 动作开始前先挂上
page.waitForNavigation({timeout: 0, signal, ignoreSameDocumentNavigation: true})。源码注释写得很直白:必须提前启动,才能捕获动作之前的 loader ID;如果等动作触发导航后再调,可能记录到新的 loader ID,然后一直挂到超时。 - 同时监听 CDP 的
Page.frameStartedNavigating与Page.frameRequestedNavigation,只认主 frame,并显式忽略sameDocument/historySameDocument类型的软导航。 - 执行动作本身(
locator.click()内含可见性、可点击性、稳定性等前置校验)。 - 动作返回后,最多观察
#expectNavigationIn(默认 100ms,受 CPU 倍率放大)来判断这次动作到底有没有引发导航。 - 如果确实发生了导航,才去
await navigationFinished,上限是#navigationTimeout(默认 3000ms × 网络倍率)。 - 最后等 DOM 稳定:注入一个
MutationObserver,观察document.body的childList/subtree/attributes,连续#stableDomFor毫秒没有变更才算"静下来",整体不超过#stableDomTimeout。 - 过程中任何时刻弹出 JS 对话框、打开新标签页,都会被单独记录并在响应里回传。
所以"一次点击很慢"不是某一行代码慢,而是它把动作 → 导航 → 渲染收敛这三段全部等完了才交还控制权。粗略估算默认配置下的纯等待:无导航点击约 100ms(导航探测)+ 100ms(静默窗口);若发生导航则再加上导航完成时间与之后的静默窗口。
三个等待,各自在解决一个真实的竞态
导航探测:防止"动作已经跳走了,工具还在旧文档里数节点"。 只监听主 frame 且排除同文档导航,避免 SPA 的 pushState 被误判成整页跳转——测试用例 里专门覆盖了"先 pushState 再 location.href"以及"只有同文档导航"两种场景,前者仍要等到真正的整页导航,后者只需正确回报 navigatedToUrl。
稳定 DOM:用变更静默期替代固定的 sleep。 这里有一个容易被忽略的健壮性细节:注入 observer 的 evaluateHandle 本身也被 #stableDomTimeout 包住了。源码注释解释了原因——若渲染进程已被对话框暂停,这次求值会一直挂到 Puppeteer 的 protocolTimeout(默认 180 秒)并卡在上下文队列里,把整个会话冻住。超时兜底之后,Promise.race 拿不到 handle 就直接返回,不再往下等。
对话框与弹窗:不让"暂停的渲染进程"变成"卡死的工具调用"。 动作期间若出现 dialog 且调用方没有指定 handleDialog,会直接 abort 掉动作信号并报 Action interrupted by a dialog;如果指定了,则按 accept / dismiss / 自定义 prompt 文本自动处理。click 的 catch 分支还会区分这种情况——只要页面上确实有一个打开的对话框,就把它当作"动作被打断"而不是"动作失败",并输出 The element was clicked and it opened a dialog.。同时 popup 事件会被收集进 openedPages,最终在响应里以 ## Opened pages 段落交给 Agent,让下一步不需要靠猜。
这套机制的产出不只是"更准",还有更可用的错误。handleActionError 会把 Puppeteer 的 TimeoutError 翻译成一句人能读懂的话:
Failed to interact with the element with uid <uid>. The element did not become interactive within the configured timeout.
对应仓库的设计原则 docs/design-principles.md 中的 "Self-Healing Errors:返回带上下文和修复线索的可执行错误"。
这里为什么没有"重试 N 次"的循环
翻遍 src/,你几乎找不到针对动作的重试封装(唯一带 "retry" 字样的地方是源码映射加载提示和 focus 模拟的失败重置)。这是有意的取舍:在浏览器自动化里,盲目重试一个"可能已经生效"的动作,比失败更危险——重复点击可能提交两次表单、重复导航可能丢掉已建立的会话。
取而代之的是三层"快速失败"设计:
- 动作前拦截。
blockedByDialog为真的工具在 handler 执行前先跑page.throwIfDialogOpen(),直接返回A dialog is open (confirm: ...),而不是让evaluate在暂停的渲染进程上耗到协议超时。evaluate_script不是页面作用域工具,所以在自己的实现里补了同样的检查,源码注释明确写了"否则在对话框打开时启动的求值会一直等到协议超时"。 - 队列被销毁即拒绝。页面关闭时
pageTaskQueues.get(id).dispose(new Error('Page X is closed.')),所有还在排队等待的工具调用立刻收到明确原因,而不是永远挂着。 - 有界等待。
wait_for的timeout、navigate_page/new_page的timeout都通过timeoutSchema统一处理,0表示回落到默认值。
CHANGELOG.md 里这条修复路线非常连贯:stop get_network_request waiting forever for an unread no-store body、bound take_snapshot wait、fail fast on tool calls stuck after a dead browser connection、do not close a healthy browser when a tool call outlasts 60s。方向一致——宁可给一个带原因的失败,也不要给一个无法解释的挂起。
等多半不是在页面里,而是在队列里
还有一层等待经常被误认为是浏览器慢:并发。1.12.0 引入的 TaskRunner 把所有工具调用放进一条有序列表,每个任务声明自己所属的队列。规则很短但很关键:
- 同一队列上的任务串行;
- 队列与其祖先、后代之间也串行;
- 无关联队列可以并行;
- 排队中的任务同样计入阻塞,后来者不能插队,因此不会饿死。
McpContext.pageTaskQueue(pageId) 为每个页面建一个子队列,父队列是全局 taskQueue。于是 concurrency: 'page' 的工具在开启 pageId 路由后,不同页面上的操作可以真正并行,同一页面上的 click 必须等前一个 snapshot 结束——因为快照里的 uid 与 DOM 状态强绑定。
switch (tool.concurrency) {
case 'none':
return undefined;
case 'page': {
const pageId = routedPageId(tool, this.#config.resolved, rawArgs);
return pageId !== undefined ? context.pageTaskQueue(pageId) : context.taskQueue;
}
default:
return context.taskQueue;
}
这段 ToolHandler.#queueFor 解释了一个常见困惑:多 Agent 同时操作同一页面时,第二次点击"很慢",其实根本没进浏览器,它在等队列。真正该做的不是调大超时,而是给不同 Agent 分配不同页面(new_page 的 isolatedContext 还能顺带隔离 cookie)。
顺带说一个"减少等待"的正向优化:fill_form 把 N 个表单元素合并成一次 waitForEventsAfterAction,tool-reference 里对它的描述直接写着 "significantly faster, more reliable, and reduces turn count"。同理,click 遇到 <option> 时会走 selectNativeSelectOption 而不是坐标点击,用 fill 触发原生 select 的 change——少一次交互,就少一次等待与一次不确定性。
为什么坚持真实 Chrome,而不是 DOM 模拟器
从工程角度看,这个项目并没有实现一套自己的"浏览器":它通过 Puppeteer 驱动真实 Chrome,并把 Chrome DevTools 前端(third_party/devtools-frontend)的模型与 Lighthouse 直接搬进来。这个选择决定了它能观测到什么,而可靠性恰恰依赖这些真实信号:
- 导航判定用的是 CDP 的
Page.frameStartedNavigating/Page.frameRequestedNavigation,包含 loader ID、frameId、navigationType。任何自造的 DOM diff 都无法区分"同文档路由切换"和"整页重载"。 - 性能分析走的是真实 trace 与 DevTools 的 insight 管线(src/processors/PerformanceTrace.ts),不是合成指标。
- 网络与 CPU 节流通过
setDefaultTimeout/setDefaultNavigationTimeout/emulateCPUThrottling作用在真实页面上,倍率会一路传导到等待预算里。 - WebAuthn 用 CDP 的虚拟认证器、Service Worker 用独立的 target 会话(src/collectors/ServiceWorkerCollector.ts),扩展调试直接挂到扩展页面。这些都不是"模拟"能覆盖的运行时状态。
代价也写在文档里:docs/troubleshooting.md 明确说明它会强制加载所有标签页,因此不建议连接开着几百个标签的浏览器实例。真实浏览器带来的真实状态,也带来了真实的资源约束。
这套设计在慢页面上的账
把倍率代进去,结论就很清楚。#getNetworkMultiplierFromString 的映射是:Fast 4G → 1、Slow 4G → 2.5、Fast 3G → 5、Slow 3G → 10;CPU 倍率直接取 emulate 设置的 cpuThrottlingRate。
| 场景 | 静默窗口 | 稳定 DOM 上限 | 导航判定窗 | 导航等待上限 | 默认动作超时 |
|---|---|---|---|---|---|
| 默认 | 100ms | 3000ms | 100ms | 3000ms | 5000ms |
| CPU 4x | 400ms | 12000ms | 400ms | 3000ms | 20000ms |
| Slow 3G | 100ms | 3000ms | 100ms | 30000ms | 5000ms |
| CPU 4x + Slow 3G | 400ms | 12000ms | 400ms | 30000ms | 20000ms |
(默认动作超时来自 McpPage.updateTimeouts():DEFAULT_TIMEOUT = 5000 乘 CPU 倍率;页面级导航超时则是 NAVIGATION_TIMEOUT = 10000 同时乘网络与 CPU 倍率,与 WaitForHelper 内部那个 3s 上限是两套独立预算。)
由此可以推出三个实用判断:
第一,恒定动画页面是"稳定 DOM"的天然敌人。 只要 attributes 或 subtree 每 100ms 内必有一次变更(轮播、打字机、时间戳计数、CSS-in-JS 频繁改 style),observer 就永远等不到静默期,最终会吃满 3s × CPU 倍率。CPU 4x 时,单次点击的固定开销就是 12 秒。这不是 bug,是"等收敛"策略的必然上限。
第二,导航超时的两套预算会造成体感不一致。 当 goto 已经因为页面级超时抛错时,WaitForHelper 内部仍在用自己的 3s × 网络倍率等 navigationFinished。因此排查挂起时,要同时看 --log-file 里的 navigate 报错和随后的等待逻辑,而不是只盯一个数字。
第三,慢页面下最该改的不是超时,而是动作粒度。 高节流场景里,把 5 次 fill + 1 次 click 换成 1 次 fill_form + 1 次 click,省下的是 5 次导航探测窗口与 5 次静默窗口;把"先 evaluate_script 读数据再操作"的脚本显式标注 waitForStableDom: false(工具描述里就写了"如果只是读数据就传 false"),能省掉整段稳定等待;Service Worker 求值路径已经默认关闭 DOM 等待,因为那条路径本来就不碰 DOM。
还有一个诚实的细节值得记住:drag 的实现 里仍保留了一次硬编码的 setTimeout(50)——在 dragstart 与 drop 之间。这说明即便有一整套事件驱动机制,某些浏览器行为依然需要一点点"人类节奏"。可靠性工程从来不是纯理论,它是在竞态、协议超时和真实渲染管线之间反复试出来的经验值。
什么时候该怀疑它、什么时候该相信它
如果你的 Agent 在一次 click 上花了 10 秒以上,按顺序自查:
- 是不是在排队?同一页面上的并发调用会串行,多开页面或
isolatedContext往往比调大超时更有效。 - 是不是有对话框?
blockedByDialog的预检会给出A dialog is open (type: message),先handle_dialog再继续。 - 是不是页面一直在动?看响应里是否带
Emulating CPU throttling: Nx slowdown,以及是否开着网络节流——两者会同时放大等待预算。 - 是不是导航根本没发生?响应中的
Page navigated to ...与## Opened pages是判断动作是否真的生效的第一手证据,比截图更可靠。
反过来说,当它准确地告诉你"元素在超时内没有变成可交互"、"页面导航到了某个 URL"、"点击打开了一个对话框"、"点开了一个新标签页"时,这些确定性正是那几百毫秒换来的东西。功能清单决定一个工具能做什么,而这些等待、竞态处理和失败路径,决定它能不能被放心地放进一个无人值守的循环里。