源码教程：等待条件与 JavaScript 执行

    put("wait", (svc, id, a) -> svc.waitSeconds(id, reqInt(a, "seconds")));

  public RespBodyVo waitSeconds(Long browserId, Integer seconds) {
    if (!INSTANCES.containsKey(browserId)) {
      return notFound(browserId);
    }
    if (seconds == null || seconds <= 0) {
      return RespBodyVo.fail("wait 的 seconds 必须是正整数");
    }
    try {
      Thread.sleep(seconds * 1_000L);
    } catch (InterruptedException e) {
      Thread.currentThread().interrupt();
      return RespBodyVo.fail("等待被中断");
    }
    return RespBodyVo.ok();
  }

    put("wait_for_element",
        (svc, id, a) -> svc.waitForElement(id, reqStr(a, "selector"), a.getDouble("timeoutSeconds"),
            optStr(a, "frame")));

  public RespBodyVo waitForElement(Long browserId, String selector, Double timeoutSeconds, String frame) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    Locator target;
    try {
      target = locatorIn(inst, frame, selector);
    } catch (IllegalArgumentException e) {
      return RespBodyVo.fail("wait_for_element 失败：" + e.getMessage());
    }
    try {
      target.waitFor(new Locator.WaitForOptions().setTimeout(timeoutMillis(timeoutSeconds)));
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(waitFailure("wait_for_element", e));
    }
    return RespBodyVo.ok();
  }

    put("wait_for_text", (svc, id, a) -> svc.waitForText(id, reqStr(a, "text"), a.getDouble("timeoutSeconds")));

  public RespBodyVo waitForText(Long browserId, String text, Double timeoutSeconds) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    try {
      inst.page.getByText(text).first().waitFor(new Locator.WaitForOptions().setTimeout(timeoutMillis(timeoutSeconds)));
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(waitFailure("wait_for_text", e));
    }
    return RespBodyVo.ok();
  }

    put("wait_for_url", (svc, id, a) -> svc.waitForUrl(id, reqStr(a, "url"), a.getDouble("timeoutSeconds")));

  public RespBodyVo waitForUrl(Long browserId, String url, Double timeoutSeconds) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    try {
      inst.page.waitForURL(url, new Page.WaitForURLOptions().setTimeout(timeoutMillis(timeoutSeconds)));
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(waitFailure("wait_for_url", e));
    }
    return RespBodyVo.ok(Kv.by("url", inst.page.url()));
  }

    put("wait_for_load", (svc, id, a) -> svc.waitForLoad(id, optStr(a, "state"), a.getDouble("timeoutSeconds")));

  public RespBodyVo waitForLoad(Long browserId, String state, Double timeoutSeconds) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    LoadState loadState = "networkidle".equalsIgnoreCase(state) ? LoadState.NETWORKIDLE
        : "domcontentloaded".equalsIgnoreCase(state) ? LoadState.DOMCONTENTLOADED : LoadState.LOAD;
    try {
      inst.page.waitForLoadState(loadState,
          new Page.WaitForLoadStateOptions().setTimeout(timeoutMillis(timeoutSeconds)));
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(waitFailure("wait_for_load", e));
    }
    return RespBodyVo.ok();
  }

    put("wait_for_function",
        (svc, id, a) -> svc.waitForFunction(id, reqStr(a, "expression"), a.getDouble("timeoutSeconds")));

  public RespBodyVo waitForFunction(Long browserId, String expression, Double timeoutSeconds) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    try {
      inst.page.waitForFunction(expression, null,
          new Page.WaitForFunctionOptions().setTimeout(timeoutMillis(timeoutSeconds)));
    } catch (PlaywrightException e) {
      return RespBodyVo.fail(waitFailure("wait_for_function", e));
    }
    return RespBodyVo.ok();
  }

    put("wait_for_idle", (svc, id, a) -> svc.waitForIdle(id, a.getInteger("quietMs"), a.getDouble("timeoutSeconds"),
        optStr(a, "selector"), optStr(a, "text")));

  public RespBodyVo waitForIdle(Long browserId, Integer quietMs, Double timeoutSeconds, String selector, String text) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    long quiet = quietMs == null || quietMs < 0 ? 500 : quietMs;
    long timeout = (long) timeoutMillis(timeoutSeconds);
    long startedAt = System.currentTimeMillis();
    long deadline = startedAt + timeout;
    int mutations = -1;
    long stableSince = startedAt;
    int inflight = 0;
    while (true) {
      long now = System.currentTimeMillis();
      int current = readMutationCount(inst);
      inflight = inst.inflight.get();
      boolean extra = (selector == null || selector.isBlank() || countOf(inst, selector) > 0)
          && (text == null || text.isBlank() || bodyContains(inst, text));
      if (current != mutations) {
        mutations = current;
        stableSince = now;
      }
      if (extra && inflight == 0 && now - stableSince >= quiet) {
        return RespBodyVo.ok(Kv.by("idle", true).set("waitedMs", now - startedAt).set("mutations", mutations)
            .set("inflight", 0).set("quietMs", quiet).set("timeoutSeconds", timeout / 1000.0)
            .set("url", safeUrl(inst.page)));
      }
      if (now >= deadline) {
        Kv data = Kv.by("idle", false).set("waitedMs", now - startedAt).set("mutations", mutations)
            .set("inflight", inflight).set("quietMs", quiet).set("url", safeUrl(inst.page))
            .set("selectorMatched", selector == null || selector.isBlank() || countOf(inst, selector) > 0)
            .set("textMatched", text == null || text.isBlank() || bodyContains(inst, text));
        RespBodyVo failure = RespBodyVo.fail("wait_for_idle 失败：" + (timeout / 1000.0) + " 秒内页面没有安静下来"
            + "（在途请求 " + inflight + " 个，DOM 变更累计 " + mutations + " 次）");
        failure.setData(data);
        return failure;
      }
      inst.page.waitForTimeout(100);
    }
  }

    put("wait_for_stable", (svc, id, a) -> svc.waitForStable(id, optStr(a, "selector"), a.getInteger("quietMs"),
        a.getDouble("timeoutSeconds")));

  public RespBodyVo waitForStable(Long browserId, String selector, Integer quietMs, Double timeoutSeconds) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    long quiet = quietMs == null || quietMs < 0 ? 800 : quietMs;
    long timeout = (long) timeoutMillis(timeoutSeconds);
    long startedAt = System.currentTimeMillis();
    long deadline = startedAt + timeout;
    String last = null;
    long stableSince = startedAt;
    int changes = 0;
    int length = 0;
    while (true) {
      long now = System.currentTimeMillis();
      Kv probe = contentProbe(inst, selector);
      if (probe == null) {
        RespBodyVo failure = RespBodyVo.fail("wait_for_stable 失败：读不到内容指纹"
            + (selector == null || selector.isBlank() ? "" : "（选择器 " + selector + " 没有命中元素）"));
        failure.setData(Kv.by("stable", false).set("selector", selector).set("url", safeUrl(inst.page)));
        return failure;
      }
      String fingerprint = probe.getStr("fingerprint");
      length = asInt(probe.get("length"));
      if (!Objects.equals(fingerprint, last)) {
        last = fingerprint;
        stableSince = now;
        changes++;
      }
      if (now - stableSince >= quiet) {
        return RespBodyVo.ok(Kv.by("stable", true).set("waitedMs", now - startedAt).set("quietMs", quiet)
            .set("changes", changes).set("length", length).set("fingerprint", fingerprint)
            .set("text", probe.get("text")).set("selector", selector).set("url", safeUrl(inst.page)));
      }
      if (now >= deadline) {
        RespBodyVo failure = RespBodyVo.fail("wait_for_stable 失败：" + (timeout / 1000.0)
            + " 秒内内容一直没稳定下来（已变化 " + changes + " 次，最近一次变化在 " + (now - stableSince) + " ms 前）");
        failure.setData(Kv.by("stable", false).set("waitedMs", now - startedAt).set("changes", changes)
            .set("quietMs", quiet).set("msSinceLastChange", now - stableSince).set("url", safeUrl(inst.page)));
        return failure;
      }
      inst.page.waitForTimeout(150);
    }
  }

    put("wait_for_count", (svc, id, a) -> svc.waitForCount(id, reqStr(a, "selector"), a.getInteger("min"),
        a.getInteger("max"), a.getInteger("equals"), a.getDouble("timeoutSeconds")));

  public RespBodyVo waitForCount(Long browserId, String selector, Integer min, Integer max, Integer equals,
      Double timeoutSeconds) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return notFound(browserId);
    }
    if (min == null && max == null && equals == null) {
      return RespBodyVo.fail("wait_for_count 需要 min / max / equals 里至少一个条件");
    }
    long timeout = (long) timeoutMillis(timeoutSeconds);
    long startedAt = System.currentTimeMillis();
    long deadline = startedAt + timeout;
    int count = 0;
    while (true) {
      count = countOf(inst, selector);
      if ((min == null || count >= min) && (max == null || count <= max) && (equals == null || count == equals)) {
        return RespBodyVo.ok(Kv.by("matched", true).set("count", count).set("waitedMs",
            System.currentTimeMillis() - startedAt).set("selector", selector).set("url", safeUrl(inst.page)));
      }
      long now = System.currentTimeMillis();
      if (now >= deadline) {
        RespBodyVo failure = RespBodyVo.fail("wait_for_count 失败：" + (timeout / 1000.0) + " 秒内 " + selector
            + " 的命中数没达到条件（实际 " + count + describeCountCondition(min, max, equals) + "）");
        failure.setData(Kv.by("matched", false).set("count", count).set("waitedMs", now - startedAt)
            .set("selector", selector).set("url", safeUrl(inst.page)));
        return failure;
      }
      inst.page.waitForTimeout(120);
    }
  }

    put("execute_js", (svc, id, a) -> {
      if (optStr(a, "body") == null && optStr(a, "bodyFile") == null) {
        // 两个都没给:报「缺少参数 body」,与老版本的行为一致(老版本只认 body)
        throw new IllegalArgumentException("缺少参数 body");
      }
      return svc.executeJs(id, a.getString("body"), optStr(a, "bodyFile"), a.getJSONObject("vars"),
          optStr(a, "frame"));
    });

  public RespBodyVo executeJs(Long browserId, String body, String bodyFile, JSONObject vars, String frame) {
    BrowserInstance inst = INSTANCES.get(browserId);
    if (inst == null) {
      return RespBodyVo.fail("没有找到对应的浏览器实例：" + browserId);
    }
    Frame target;
    try {
      target = frameOf(inst, frame);
    } catch (IllegalArgumentException e) {
      return RespBodyVo.fail("execute_js 失败：" + e.getMessage());
    }
    String raw = body;
    if ((raw == null || raw.isBlank()) && bodyFile != null && !bodyFile.isBlank()) {
      String fromFile = readScriptFile(bodyFile);
      if (fromFile == null) {
        return RespBodyVo.fail("execute_js 失败：读不到脚本文件 " + bodyFile
            + "（只允许读脚本目录下的文件,见 get_config 的 jsDir）");
      }
      raw = fromFile;
    }
    if (raw == null || raw.isBlank()) {
      return RespBodyVo.fail("execute_js 需要 body 或 bodyFile");
    }
    String script = normalizeScript(applyVars(raw, vars));
    try {
      Object result = target.evaluate(script);
      Kv data = Kv.by("result", result);
      if (vars != null && !vars.isEmpty()) {
        data.set("varsApplied", new ArrayList<>(vars.keySet()));
      }
      if (frame != null && !frame.isBlank()) {
        data.set("frame", frame).set("frameUrl", safeFrameUrl(target));
      }
      // 「到底等没等 Promise」以前只能靠猜,于是有人退回同步 XHR 来规避。这里如实回报
      data.set("awaited", true);
      return RespBodyVo.ok(data);
    } catch (PlaywrightException e) {
      String message = briefMessage(e.getMessage());
      log.error("execute_js 执行失败,id:{},script:{},error:{}", browserId, script, message, e);
      RespBodyVo failure = RespBodyVo.fail("执行 JavaScript 失败：" + message);
      Kv detail = Kv.by("error", scriptError(e)).set("scriptPreview", truncate(script, 400))
          .set("scriptLength", script.length());
      // 「脚本被截断」是 Windows 上最常见的一类假故障:多行脚本经 cmd/PowerShell 传参时被吃掉,
      // 到服务端的只剩第一行,报错却是语法级的 "Unexpected end of input" —— 只说语法,人根本想不到
      // 是传输层把脚本切了。这里直接说破,并给出传文件的写法
      if (looksTruncatedScript(message)) {
        detail.set("hint", "脚本像是被截断了(报的是 " + message + "):多行脚本走命令行时可能只到了第一行。"
            + "改用文件传:服务端把脚本放进 scripts/js 目录后传 bodyFile,或客户端用 js @脚本.js");
      }
      failure.setData(detail);
      return failure;
    }
  }