@skrillex1224/playwright-toolkit 2.1.36 → 2.1.38

package/dist/index.js

@@ -154,38 +154,87 @@ async function createApifyKit() {
   const { Actor: Actor2 } = apify;
   return {
     /**
-     * 核心封装：执行步骤，带自动日志确认和失败截图处理
+     * 核心封装：执行步骤，带自动日志确认、失败截图处理和重试机制
+     * 
+     * @param {string} step - 步骤名称
+     * @param {import('playwright').Page} page - Playwright page 对象
+     * @param {Function} actionFn - 执行的异步操作
+     * @param {Object} [options] - 配置选项
+     * @param {boolean} [options.failActor=true] - 失败时是否调用 Actor.fail
+     * @param {Object} [options.retry] - 重试配置
+     * @param {number} [options.retry.times=0] - 重试次数
+     * @param {'direct'|'refresh'} [options.retry.mode='direct'] - 重试模式
+     * @param {Function} [options.retry.before] - 重试前钩子，可覆盖默认等待行为
      */
     async runStep(step, page, actionFn, options = {}) {
-      const { failActor = true } = options;
-      logger.start(`[Step] ${step}`);
-      try {
-        const result = await actionFn();
-        logger.success(`[Step] ${step}`);
-        return result;
-      } catch (error) {
-        logger.fail(`[Step] ${step}`, error);
-        if (failActor) {
-          let base64 = "\u622A\u56FE\u5931\u8D25";
-          try {
-            if (page) {
-              const buffer = await page.screenshot({ fullPage: true, type: "jpeg", quality: 60 });
-              base64 = `data:image/jpeg;base64,${buffer.toString("base64")}`;
-            }
-          } catch (snapErr) {
-            logger.warn(`\u622A\u56FE\u751F\u6210\u5931\u8D25: ${snapErr.message}`);
-          }
-          await this.pushFailed(error, {
-            step,
-            page,
-            options,
-            base64
-          });
-          await Actor2.fail(`Run Step ${step} \u5931\u8D25: ${error.message}`);
+      const { failActor = true, retry = {} } = options;
+      const { times: retryTimes = 0, mode: retryMode = "direct", before: beforeRetry } = retry;
+      const executeAction = async (attemptNumber) => {
+        const attemptLabel = attemptNumber > 0 ? ` (\u91CD\u8BD5 #${attemptNumber})` : "";
+        logger.start(`[Step] ${step}${attemptLabel}`);
+        try {
+          const result = await actionFn();
+          logger.success(`[Step] ${step}${attemptLabel}`);
+          return { success: true, result };
+        } catch (error) {
+          logger.fail(`[Step] ${step}${attemptLabel}`, error);
+          return { success: false, error };
+        }
+      };
+      const prepareForRetry = async (attemptNumber) => {
+        if (typeof beforeRetry === "function") {
+          logger.start(`[RetryStep] \u6267\u884C\u81EA\u5B9A\u4E49 before \u94A9\u5B50 (\u7B2C ${attemptNumber} \u6B21\u91CD\u8BD5)`);
+          await beforeRetry(page, attemptNumber);
+          logger.success(`[RetryStep] before \u94A9\u5B50\u5B8C\u6210`);
+        } else if (retryMode === "refresh") {
+          logger.start(`[RetryStep] \u5237\u65B0\u9875\u9762 (\u7B2C ${attemptNumber} \u6B21\u91CD\u8BD5)`);
+          await page.reload({ waitUntil: "domcontentloaded" });
+          logger.success(`[RetryStep] \u9875\u9762\u5237\u65B0\u5B8C\u6210`);
         } else {
-          throw error;
+          logger.start(`[RetryStep] \u7B49\u5F85 3 \u79D2 (\u7B2C ${attemptNumber} \u6B21\u91CD\u8BD5)`);
+          await new Promise((resolve) => setTimeout(resolve, 3e3));
+          logger.success(`[RetryStep] \u7B49\u5F85\u5B8C\u6210`);
+        }
+      };
+      let lastResult = await executeAction(0);
+      if (lastResult.success) {
+        return lastResult.result;
+      }
+      for (let attempt = 1; attempt <= retryTimes; attempt++) {
+        logger.start(`[RetryStep] \u51C6\u5907\u7B2C ${attempt}/${retryTimes} \u6B21\u91CD\u8BD5: ${step}`);
+        try {
+          await prepareForRetry(attempt);
+        } catch (prepareError) {
+          logger.warn(`[RetryStep] \u91CD\u8BD5\u51C6\u5907\u5931\u8D25: ${prepareError.message}`);
+          continue;
+        }
+        lastResult = await executeAction(attempt);
+        if (lastResult.success) {
+          return lastResult.result;
         }
       }
+      const finalError = lastResult.error;
+      if (failActor) {
+        let base64 = "\u622A\u56FE\u5931\u8D25";
+        try {
+          if (page) {
+            const buffer = await page.screenshot({ fullPage: true, type: "jpeg", quality: 60 });
+            base64 = `data:image/jpeg;base64,${buffer.toString("base64")}`;
+          }
+        } catch (snapErr) {
+          logger.warn(`\u622A\u56FE\u751F\u6210\u5931\u8D25: ${snapErr.message}`);
+        }
+        await this.pushFailed(finalError, {
+          step,
+          page,
+          options,
+          base64,
+          retryAttempts: retryTimes
+        });
+        await Actor2.fail(`Run Step ${step} \u5931\u8D25 (\u5DF2\u91CD\u8BD5 ${retryTimes} \u6B21): ${finalError.message}`);
+      } else {
+        throw finalError;
+      }
     },
     /**
      * 宽松版runStep：失败时不调用Actor.fail，只抛出异常
@@ -279,6 +328,8 @@ var Utils = {
    * @param {import('playwright').Page} page - Playwright page 对象
    * @param {Object} [options] - 配置选项
    * @param {number} [options.buffer] - 额外缓冲高度 (默认: 视口高度的一半)
+   * @param {boolean} [options.restore] - 截图后是否恢复页面高度和样式 (默认: false)
+   * @param {number} [options.maxHeight] - 最大截图高度 (默认: 8000px)
    * @returns {Promise<string>} - base64 编码的 PNG 图片
    */
   async fullPageScreenshot(page, options = {}) {
@@ -286,15 +337,17 @@ var Utils = {
     const originalViewport = page.viewportSize();
     const defaultBuffer = Math.round((originalViewport?.height || 1080) / 2);
     const buffer = options.buffer ?? defaultBuffer;
+    const restore = options.restore ?? false;
+    const maxHeight = options.maxHeight ?? 8e3;
     try {
       const maxScrollHeight = await page.evaluate(() => {
-        let maxHeight = document.body.scrollHeight;
+        let maxHeight2 = document.body.scrollHeight;
         document.querySelectorAll("*").forEach((el) => {
           const style = window.getComputedStyle(el);
           const overflowY = style.overflowY;
           if ((overflowY === "auto" || overflowY === "scroll") && el.scrollHeight > el.clientHeight) {
-            if (el.scrollHeight > maxHeight) {
-              maxHeight = el.scrollHeight;
+            if (el.scrollHeight > maxHeight2) {
+              maxHeight2 = el.scrollHeight;
             }
             el.dataset.pkOrigOverflow = el.style.overflow;
             el.dataset.pkOrigHeight = el.style.height;
@@ -305,11 +358,12 @@ var Utils = {
             el.style.maxHeight = "none";
           }
         });
-        return maxHeight;
+        return maxHeight2;
       });
+      const targetHeight = Math.min(maxScrollHeight + buffer, maxHeight);
       await page.setViewportSize({
         width: originalViewport?.width || 1280,
-        height: maxScrollHeight + buffer
+        height: targetHeight
       });
       await delay(1e3);
       const buffer_ = await page.screenshot({
@@ -319,19 +373,21 @@ var Utils = {
       logger2.success("fullPageScreenshot", `captured ${Math.round(buffer_.length / 1024)} KB`);
       return buffer_.toString("base64");
     } finally {
-      await page.evaluate(() => {
-        document.querySelectorAll(".__pk_expanded__").forEach((el) => {
-          el.style.overflow = el.dataset.pkOrigOverflow || "";
-          el.style.height = el.dataset.pkOrigHeight || "";
-          el.style.maxHeight = el.dataset.pkOrigMaxHeight || "";
-          delete el.dataset.pkOrigOverflow;
-          delete el.dataset.pkOrigHeight;
-          delete el.dataset.pkOrigMaxHeight;
-          el.classList.remove("__pk_expanded__");
+      if (restore) {
+        await page.evaluate(() => {
+          document.querySelectorAll(".__pk_expanded__").forEach((el) => {
+            el.style.overflow = el.dataset.pkOrigOverflow || "";
+            el.style.height = el.dataset.pkOrigHeight || "";
+            el.style.maxHeight = el.dataset.pkOrigMaxHeight || "";
+            delete el.dataset.pkOrigOverflow;
+            delete el.dataset.pkOrigHeight;
+            delete el.dataset.pkOrigMaxHeight;
+            el.classList.remove("__pk_expanded__");
+          });
         });
-      });
-      if (originalViewport) {
-        await page.setViewportSize(originalViewport);
+        if (originalViewport) {
+          await page.setViewportSize(originalViewport);
+        }
       }
     }
   }
@@ -347,25 +403,12 @@ var BASE_CONFIG = Object.freeze({
   geolocation: null
 });
 var DEFAULT_LAUNCH_ARGS = [
-  "--disable-blink-features=AutomationControlled",
+  // '--disable-blink-features=AutomationControlled', // Crawlee 可能会自动处理，过多干预反而会被识别
   "--no-sandbox",
   "--disable-setuid-sandbox",
   "--window-position=0,0",
   `--lang=${BASE_CONFIG.locale}`
 ];
-var ADVANCED_LAUNCH_ARGS = [
-  ...DEFAULT_LAUNCH_ARGS,
-  "--disable-dev-shm-usage",
-  "--disable-background-networking",
-  "--disable-default-apps",
-  "--disable-extensions",
-  "--disable-sync",
-  "--disable-translate",
-  "--metrics-recording-only",
-  "--mute-audio",
-  "--no-first-run"
-];
-var CONTEXT_CONFIG_CACHE = /* @__PURE__ */ new WeakMap();
 function buildFingerprintOptions(locale) {
   return {
     browsers: [{ name: "chrome", minVersion: 110 }],
@@ -374,95 +417,9 @@ function buildFingerprintOptions(locale) {
     locales: [locale]
   };
 }
-function parseAcceptLanguage(acceptLanguage) {
-  if (!acceptLanguage) return [];
-  return acceptLanguage.split(",").map((part) => part.trim().split(";")[0]).filter(Boolean);
-}
-function normalizeLanguages(acceptLanguage, fallbackLocale) {
-  const languages = parseAcceptLanguage(acceptLanguage);
-  if (languages.length === 0) return [fallbackLocale];
-  if (!languages.includes(fallbackLocale)) {
-    return [fallbackLocale, ...languages];
-  }
-  return languages;
-}
-function getOperatingSystemsFromUserAgent(userAgent) {
-  const lowerUA = userAgent.toLowerCase();
-  if (lowerUA.includes("windows")) return ["windows"];
-  if (lowerUA.includes("mac os") || lowerUA.includes("macintosh")) return ["macos"];
-  if (lowerUA.includes("linux")) return ["linux"];
-  return [];
-}
-function buildContextConfigKey(config) {
-  return JSON.stringify({
-    locale: config.locale,
-    acceptLanguage: config.acceptLanguage,
-    timezoneId: config.timezoneId,
-    timezoneOffset: config.timezoneOffset
-  });
-}
-async function applyContextSettings(context, config, languages, permissions, injectLocaleTimezone) {
-  const contextKey = buildContextConfigKey(config);
-  const cached = CONTEXT_CONFIG_CACHE.get(context);
-  const isFirstInit = !cached;
-  const effectiveConfig = cached?.config || config;
-  const effectiveLanguages = cached?.languages || languages;
-  if (isFirstInit) {
-    CONTEXT_CONFIG_CACHE.set(context, {
-      key: contextKey,
-      config,
-      languages
-    });
-  } else if (cached.key !== contextKey) {
-    logger3.warn("applyContext", "Context already initialized; ignore conflicting locale/timezone.");
-  }
-  await context.setExtraHTTPHeaders({
-    "accept-language": effectiveConfig.acceptLanguage
-  });
-  if (isFirstInit) {
-    await context.addInitScript(({ locale, timezoneId, timezoneOffset, languages: languages2, applyLocaleTimezone }) => {
-      const originalDateTimeFormat = Intl.DateTimeFormat;
-      if (applyLocaleTimezone) {
-        Intl.DateTimeFormat = function(locales, initOptions) {
-          const nextLocales = locales || locale;
-          const nextOptions = initOptions ? { ...initOptions } : {};
-          nextOptions.timeZone = nextOptions.timeZone || timezoneId;
-          return new originalDateTimeFormat(nextLocales, nextOptions);
-        };
-        Intl.DateTimeFormat.prototype = originalDateTimeFormat.prototype;
-        Date.prototype.getTimezoneOffset = function() {
-          return timezoneOffset;
-        };
-        Object.defineProperty(navigator, "language", { get: () => languages2[0] });
-        Object.defineProperty(navigator, "languages", { get: () => languages2 });
-      }
-      Object.defineProperty(navigator, "webdriver", { get: () => void 0 });
-    }, {
-      locale: effectiveConfig.locale,
-      timezoneId: effectiveConfig.timezoneId,
-      timezoneOffset: effectiveConfig.timezoneOffset,
-      languages: effectiveLanguages,
-      applyLocaleTimezone: injectLocaleTimezone
-    });
-  }
-  if (effectiveConfig.geolocation) {
-    await context.setGeolocation(effectiveConfig.geolocation);
-    await context.grantPermissions(["geolocation"]);
-  }
-  if (permissions?.length) {
-    await context.grantPermissions(permissions);
-  }
-}
-function resolveConfig(overrides = {}) {
-  return {
-    ...BASE_CONFIG,
-    ...overrides,
-    geolocation: overrides.geolocation === null ? null : overrides.geolocation || BASE_CONFIG.geolocation
-  };
-}
 var AntiCheat = {
   /**
-   * 获取统一的基础配置（中国、桌面端、中文语言）。
+   * 获取统一的基础配置
    */
   getBaseConfig() {
     return { ...BASE_CONFIG };
@@ -479,100 +436,18 @@ var AntiCheat = {
   getLaunchArgs() {
     return [...DEFAULT_LAUNCH_ARGS];
   },
-  /**
-   * 获取增强启动参数（高风险场景）。
-   */
-  getAdvancedLaunchArgs() {
-    return [...ADVANCED_LAUNCH_ARGS];
-  },
-  /**
-   * 统一应用到 BrowserContext（时区/语言/权限/地理位置）。
-   *
-   * @param {import('playwright').BrowserContext} context
-   * @param {Object} [options]
-   * @param {string} [options.locale]
-   * @param {string} [options.acceptLanguage]
-   * @param {string} [options.timezoneId]
-   * @param {number} [options.timezoneOffset]
-   * @param {import('playwright').Geolocation|null} [options.geolocation]
-   * @param {string[]} [options.permissions]
-   */
-  async applyContext(context, options = {}) {
-    const config = resolveConfig(options);
-    const languages = normalizeLanguages(config.acceptLanguage, config.locale);
-    const permissions = Array.isArray(options.permissions) ? options.permissions : [];
-    await applyContextSettings(context, config, languages, permissions, true);
-    logger3.success("applyContext", `${config.locale} | ${config.timezoneId}`);
-  },
-  /**
-   * 统一应用到 Page（Context + 视口同步）。
-   *
-   * @param {import('playwright').Page} page
-   * @param {Object} [options] - 传递给 applyContext 的选项
-   */
-  async applyPage(page, options = {}) {
-    const config = resolveConfig(options);
-    const languages = normalizeLanguages(config.acceptLanguage, config.locale);
-    const permissions = Array.isArray(options.permissions) ? options.permissions : [];
-    let injectLocaleTimezone = true;
-    try {
-      const env = await page.evaluate(() => ({
-        language: navigator.language,
-        languages: Array.isArray(navigator.languages) ? navigator.languages : [],
-        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
-        tzOffset: (/* @__PURE__ */ new Date()).getTimezoneOffset()
-      }));
-      const languageMatch = env.language === languages[0];
-      const timeZoneMatch = env.timeZone === config.timezoneId && env.tzOffset === config.timezoneOffset;
-      injectLocaleTimezone = !(languageMatch && timeZoneMatch);
-    } catch (e) {
-      injectLocaleTimezone = true;
-    }
-    await applyContextSettings(page.context(), config, languages, permissions, injectLocaleTimezone);
-    await this.syncViewportWithScreen(page);
-  },
-  /**
-   * 同步 Page 视口到 window.screen，避免视口/屏幕不一致检测。
-   */
-  async syncViewportWithScreen(page) {
-    try {
-      const screen = await page.evaluate(() => ({
-        width: window.screen.width,
-        height: window.screen.height
-      }));
-      await page.setViewportSize({
-        width: screen.width,
-        height: screen.height
-      });
-      logger3.success("syncViewport", `size=${screen.width}x${screen.height}`);
-    } catch (e) {
-      logger3.warn(`syncViewport \u5931\u8D25: ${e.message}\uFF0C\u56DE\u9000\u5230 1920x1080`);
-      await page.setViewportSize({ width: 1920, height: 1080 });
-    }
-  },
   /**
    * 为 got-scraping 生成与浏览器一致的 TLS 指纹配置（桌面端）。
-   *
-   * @param {string} [userAgent]
    */
   getTlsFingerprintOptions(userAgent = "", acceptLanguage = "") {
-    const primaryLocale = parseAcceptLanguage(acceptLanguage || BASE_CONFIG.acceptLanguage)[0] || BASE_CONFIG.locale;
-    const fingerprint = buildFingerprintOptions(primaryLocale);
-    const os = getOperatingSystemsFromUserAgent(userAgent);
-    if (os.length > 0) fingerprint.operatingSystems = os;
-    return fingerprint;
+    return buildFingerprintOptions(BASE_CONFIG.locale);
   },
   /**
-   * 规范化请求头，确保语言与浏览器一致。
-   *
-   * @param {Record<string, string>} headers
-   * @returns {Record<string, string>}
+   * 规范化请求头
    */
   applyLocaleHeaders(headers, acceptLanguage = "") {
-    if (acceptLanguage) {
-      headers["accept-language"] = acceptLanguage;
-    } else if (!headers["accept-language"]) {
-      headers["accept-language"] = BASE_CONFIG.acceptLanguage;
+    if (!headers["accept-language"]) {
+      headers["accept-language"] = acceptLanguage || BASE_CONFIG.acceptLanguage;
     }
     return headers;
   }
@@ -1008,18 +883,6 @@ var Launch = {
       ignoreDefaultArgs: ["--enable-automation"]
     };
   },
-  /**
-   * 获取增强版启动选项（用于高风险反爬场景）
-   */
-  getAdvancedLaunchOptions(customArgs = []) {
-    return {
-      args: [
-        ...AntiCheat.getAdvancedLaunchArgs(),
-        ...customArgs
-      ],
-      ignoreDefaultArgs: ["--enable-automation"]
-    };
-  },
   /**
    * 推荐的 Fingerprint Generator 选项
    * 确保生成的是桌面端、较新的 Chrome，以匹配我们的脚本逻辑
@@ -1553,8 +1416,6 @@ var Interception = {
           try {
             const reqHeaders = await request.allHeaders();
             delete reqHeaders["host"];
-            const currentAcceptLanguage = reqHeaders["accept-language"] || "";
-            AntiCheat.applyLocaleHeaders(reqHeaders, currentAcceptLanguage);
             const resolvedAcceptLanguage = reqHeaders["accept-language"] || "";
             const userAgent = reqHeaders["user-agent"] || "";
             const method = request.method();
@@ -1568,8 +1429,8 @@ var Interception = {
               body: postData,
               responseType: "buffer",
               // 强制获取 Buffer
-              // 模拟浏览器 TLS 指纹
-              headerGeneratorOptions: AntiCheat.getTlsFingerprintOptions(userAgent, resolvedAcceptLanguage),
+              // 移除手动 TLS 指纹配置，使用 got-scraping 默认的高质量指纹
+              // headerGeneratorOptions: ... 
               // 使用共享的 Agent 单例（keepAlive: false，不会池化连接）
               agent: {
                 http: SHARED_HTTP_AGENT,
@@ -1649,6 +1510,181 @@ function isIgnorableError(error) {
   return msg.includes("already handled") || msg.includes("Target closed") || msg.includes("closed");
 }
 
+// src/mutation.js
+import { v4 as uuidv42 } from "uuid";
+var logger9 = createLogger("Mutation");
+function generateKey(prefix) {
+  return `__${prefix}_${uuidv42().replace(/-/g, "_")}`;
+}
+var Mutation = {
+  /**
+   * 等待 DOM 元素稳定（无变化）
+   * 使用 MutationObserver 监控指定元素，当元素持续一段时间无变化时 resolve
+   * 
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器，单个或多个
+   * @param {Object} [options] - 配置选项
+   * @param {number} [options.stableTime] - 无变化持续时间后 resolve (毫秒, 默认: 5000)
+   * @param {number} [options.timeout] - 整体超时时间 (毫秒, 默认: 60000)
+   * @param {Function} [options.onMutation] - 变化时的回调钩子 (mutationCount: number) => void
+   * @returns {Promise<{ mutationCount: number, stableTime: number }>} - 返回变化次数和稳定时长
+   */
+  async waitForStable(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const stableTime = options.stableTime ?? 5e3;
+    const timeout = options.timeout ?? 6e4;
+    const onMutation = options.onMutation;
+    logger9.start("waitForStable", `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668, \u7A33\u5B9A\u65F6\u95F4=${stableTime}ms`);
+    const eventName = generateKey("pk_mut_evt");
+    const callbackName = generateKey("pk_mut_cb");
+    if (onMutation) {
+      try {
+        await page.exposeFunction(callbackName, (count) => {
+          try {
+            onMutation(count);
+          } catch (e) {
+          }
+        });
+      } catch (e) {
+      }
+    }
+    const result = await page.evaluate(
+      async ({ selectorList: selectorList2, stableTime: stableTime2, timeout: timeout2, eventName: eventName2, callbackName: callbackName2, hasCallback }) => {
+        return new Promise((resolve, reject) => {
+          let mutationCount = 0;
+          let stableTimer = null;
+          let timeoutTimer = null;
+          const observers = [];
+          const cleanup = () => {
+            observers.forEach((obs) => obs.disconnect());
+            if (stableTimer) clearTimeout(stableTimer);
+            if (timeoutTimer) clearTimeout(timeoutTimer);
+          };
+          const resetStableTimer = () => {
+            if (stableTimer) clearTimeout(stableTimer);
+            stableTimer = setTimeout(() => {
+              cleanup();
+              resolve({ mutationCount, stableTime: stableTime2 });
+            }, stableTime2);
+          };
+          timeoutTimer = setTimeout(() => {
+            cleanup();
+            reject(new Error(`waitForStable \u8D85\u65F6 (${timeout2}ms), \u5DF2\u68C0\u6D4B\u5230 ${mutationCount} \u6B21\u53D8\u5316`));
+          }, timeout2);
+          selectorList2.forEach((selector) => {
+            const elements = document.querySelectorAll(selector);
+            elements.forEach((element) => {
+              const observer = new MutationObserver((mutations) => {
+                mutationCount += mutations.length;
+                if (hasCallback && window[callbackName2]) {
+                  window[callbackName2](mutationCount);
+                }
+                resetStableTimer();
+              });
+              observer.observe(element, {
+                childList: true,
+                subtree: true,
+                characterData: true,
+                attributes: true
+              });
+              observers.push(observer);
+            });
+          });
+          if (observers.length === 0) {
+            cleanup();
+            resolve({ mutationCount: 0, stableTime: 0 });
+            return;
+          }
+          resetStableTimer();
+        });
+      },
+      { selectorList, stableTime, timeout, eventName, callbackName, hasCallback: !!onMutation }
+    );
+    logger9.success("waitForStable", `DOM \u7A33\u5B9A, \u603B\u5171 ${result.mutationCount} \u6B21\u53D8\u5316`);
+    return result;
+  },
+  /**
+   * 创建一个持续监控 DOM 变化的监控器
+   * 
+   * @param {import('playwright').Page} page - Playwright page 对象
+   * @param {string | string[]} selectors - 要监控的 CSS 选择器
+   * @param {Object} [options] - 配置选项
+   * @param {Function} [options.onMutation] - 变化时的回调 (mutationCount: number) => void
+   * @returns {Promise<{ stop: () => Promise<{ totalMutations: number }> }>} - 返回停止函数
+   */
+  async createMonitor(page, selectors, options = {}) {
+    const selectorList = Array.isArray(selectors) ? selectors : [selectors];
+    const onMutation = options.onMutation;
+    logger9.start("createMonitor", `\u76D1\u63A7 ${selectorList.length} \u4E2A\u9009\u62E9\u5668`);
+    const monitorKey = generateKey("pk_mon");
+    const callbackName = generateKey("pk_mon_cb");
+    const cleanerName = generateKey("pk_mon_clean");
+    if (onMutation) {
+      try {
+        await page.exposeFunction(callbackName, (count) => {
+          try {
+            onMutation(count);
+          } catch (e) {
+          }
+        });
+      } catch (e) {
+      }
+    }
+    await page.evaluate(({ selectorList: selectorList2, monitorKey: monitorKey2, callbackName: callbackName2, cleanerName: cleanerName2, hasCallback }) => {
+      const monitor = {
+        observers: [],
+        totalMutations: 0,
+        running: true
+      };
+      selectorList2.forEach((selector) => {
+        const elements = document.querySelectorAll(selector);
+        elements.forEach((element) => {
+          const observer = new MutationObserver((mutations) => {
+            if (!monitor.running) return;
+            monitor.totalMutations += mutations.length;
+            if (hasCallback && window[callbackName2]) {
+              window[callbackName2](monitor.totalMutations);
+            }
+          });
+          observer.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true
+          });
+          monitor.observers.push(observer);
+        });
+      });
+      window[monitorKey2] = monitor;
+      window[cleanerName2] = () => {
+        monitor.running = false;
+        monitor.observers.forEach((obs) => obs.disconnect());
+        const total = monitor.totalMutations;
+        delete window[monitorKey2];
+        delete window[cleanerName2];
+        return total;
+      };
+    }, { selectorList, monitorKey, callbackName, cleanerName, hasCallback: !!onMutation });
+    logger9.success("createMonitor", "\u76D1\u63A7\u5668\u5DF2\u542F\u52A8");
+    return {
+      stop: async () => {
+        let totalMutations = 0;
+        try {
+          totalMutations = await page.evaluate((cleanerName2) => {
+            if (window[cleanerName2]) {
+              return window[cleanerName2]();
+            }
+            return 0;
+          }, cleanerName);
+        } catch (e) {
+        }
+        logger9.success("createMonitor.stop", `\u76D1\u63A7\u5DF2\u505C\u6B62, \u5171 ${totalMutations} \u6B21\u53D8\u5316`);
+        return { totalMutations };
+      }
+    };
+  }
+};
+
 // index.js
 var usePlaywrightToolKit = () => {
   return {
@@ -1662,7 +1698,8 @@ var usePlaywrightToolKit = () => {
     Captcha,
     Sse,
     Errors: errors_exports,
-    Interception
+    Interception,
+    Mutation
   };
 };
 export {