为什么一次点击要等那么久:可靠性设计比功能清单更值得看

原创2026-11-14 12:22:431,436 阅读
文章标签:AI 应用MCP 服务浏览器控制GUI 自动化开发工具调试器AI 技能性能测试

为什么一次点击要等那么久:可靠性设计比功能清单更值得看

很多人第一次用 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; // 导航完成的上限

一次动作的完整顺序是:

  1. 动作开始前先挂上 page.waitForNavigation({timeout: 0, signal, ignoreSameDocumentNavigation: true})。源码注释写得很直白:必须提前启动,才能捕获动作之前的 loader ID;如果等动作触发导航后再调,可能记录到新的 loader ID,然后一直挂到超时。
  2. 同时监听 CDP 的 Page.frameStartedNavigating 与 Page.frameRequestedNavigation,只认主 frame,并显式忽略 sameDocument / historySameDocument 类型的软导航。
  3. 执行动作本身(locator.click() 内含可见性、可点击性、稳定性等前置校验)。
  4. 动作返回后,最多观察 #expectNavigationIn(默认 100ms,受 CPU 倍率放大)来判断这次动作到底有没有引发导航。
  5. 如果确实发生了导航,才去 await navigationFinished,上限是 #navigationTimeout(默认 3000ms × 网络倍率)。
  6. 最后等 DOM 稳定:注入一个 MutationObserver,观察 document.body 的 childList / subtree / attributes,连续 #stableDomFor 毫秒没有变更才算"静下来",整体不超过 #stableDomTimeout。
  7. 过程中任何时刻弹出 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 秒以上,按顺序自查:

  1. 是不是在排队?同一页面上的并发调用会串行,多开页面或 isolatedContext 往往比调大超时更有效。
  2. 是不是有对话框?blockedByDialog 的预检会给出 A dialog is open (type: message),先 handle_dialog 再继续。
  3. 是不是页面一直在动?看响应里是否带 Emulating CPU throttling: Nx slowdown,以及是否开着网络节流——两者会同时放大等待预算。
  4. 是不是导航根本没发生?响应中的 Page navigated to ... 与 ## Opened pages 是判断动作是否真的生效的第一手证据,比截图更可靠。

反过来说,当它准确地告诉你"元素在超时内没有变成可交互"、"页面导航到了某个 URL"、"点击打开了一个对话框"、"点开了一个新标签页"时,这些确定性正是那几百毫秒换来的东西。功能清单决定一个工具能做什么,而这些等待、竞态处理和失败路径,决定它能不能被放心地放进一个无人值守的循环里。

登录后查看全文
chrome-devtools-mcp