@skrillex1224/playwright-toolkit 2.0.0

package/README.md

@@ -0,0 +1,208 @@
+# Visitor Tools - Tools
+
+> **类型**: Tools (通用工具库)
+> **用途**: 面向 Apify/Crawlee Actor 开发者的实用工具库。
+
+
+一个面向 Apify/Crawlee Actor 开发者的实用工具库，提供实时截图展示（Live View）、健壮的步骤执行封装、以及常用的 Playwright 优化工具。
+
+## 📦 安装
+
+```bash
+npm install @skrillex1224/visitor-tools
+```
+
+## ✨ 功能特性
+
+### 1. Live View (实时截图展示)
+
+启动一个本地 Express 服务器，在 Apify 平台的 "Live View" 选项卡中实时查看浏览器当前状态。
+
+```javascript
+import { useLiveView } from '@skrillex1224/visitor-tools';
+
+const liveView = useLiveView();
+
+// 启动 Live View 服务器
+await liveView.startLiveViewServer();
+
+// 在循环或步骤中捕获截图
+await liveView.takeLiveScreenshot(page, "正在处理步骤 1...");
+```
+
+**工作原理**：
+- 截图保存到 Apify Key-Value Store
+- Express 服务器从 Store 读取最新截图
+- 页面每 1 秒自动刷新，展示实时状态
+
+### 2. 健壮的步骤执行 (`runStep`)
+
+将你的逻辑包装在 `runStep` 中，自动处理日志记录和失败截图。如果步骤失败，会自动捕获全页截图并将错误详情推送到 Dataset。
+
+```javascript
+import { Utils } from '@skrillex1224/visitor-tools';
+
+await Utils.runStep('登录步骤', page, async () => {
+    await page.click('#login');
+    await page.fill('#username', 'user');
+});
+```
+
+**失败输出示例**：
+```json
+{
+  "status": "FAILED",
+  "failedStep": "登录步骤",
+  "errorMessage": "Timeout 30000ms exceeded",
+  "errorStack": "...",
+  "screenshotBase64": "data:image/jpeg;base64,...",
+  "timestamp": "2025-12-15T03:00:00.000Z"
+}
+```
+
+### 3. Playwright 优化工具
+
+#### 资源拦截 - 加速页面加载
+
+通过屏蔽字体、图片、媒体等资源来加快爬取速度：
+
+```javascript
+// 默认屏蔽 font, image, media
+await Utils.setupBlockingResources(page);
+
+// 自定义屏蔽类型
+await Utils.setupBlockingResources(page, ['stylesheet', 'font', 'image']);
+```
+
+#### 视口设置
+
+```javascript
+await Utils.setupViewport(page, 1920, 1080);
+```
+
+### 4. SSE 解析工具
+
+解析 Server-Sent Events (SSE) 流式数据的辅助函数：
+
+```javascript
+const events = Utils.parseSseStream(responseText);
+// 返回一个数组，包含所有解析后的 JSON 对象
+```
+
+### 5. 失败键包装 (Failed Key Wrapping)
+
+为步骤名称添加自定义的失败标识符，方便在失败时进行分类和追踪：
+
+```javascript
+import { wrapStepNameWithFailedKey, unwrapStepName, ErrorKeygen } from '@skrillex1224/visitor-tools';
+
+// 包装步骤名称
+const wrappedName = wrapStepNameWithFailedKey(ErrorKeygen.NotLogin, '等待登录');
+
+// 解包
+const [failedKey, stepName] = unwrapStepName(wrappedName);
+// failedKey: 30000001
+// stepName: '等待登录'
+```
+
+## 📚 完整示例
+
+```javascript
+import { Actor } from 'apify';
+import { PlaywrightCrawler } from 'crawlee';
+import { useLiveView, Utils } from '@skrillex1224/visitor-tools';
+
+await Actor.init();
+
+const { startLiveViewServer, takeLiveScreenshot } = useLiveView();
+
+const crawler = new PlaywrightCrawler({
+    preNavigationHooks: [
+        async ({ page }) => {
+            await Utils.setupViewport(page);
+            await Utils.setupBlockingResources(page);
+        },
+    ],
+    requestHandler: async ({ page }) => {
+        await takeLiveScreenshot(page, '页面加载完成');
+        
+        await Utils.runStep('点击登录按钮', page, async () => {
+            await page.click('#login-btn');
+        });
+        
+        await takeLiveScreenshot(page, '登录成功');
+    },
+});
+
+await startLiveViewServer();
+await crawler.run(['https://example.com']);
+await Actor.exit();
+```
+
+## 🛠️ API 文档
+
+### `useLiveView(liveViewKey?)`
+
+创建 Live View 实例。
+
+- **参数**：
+  - `liveViewKey` (可选): Key-Value Store 中的键名，默认为 `'LIVE_VIEW_SCREENSHOT'`
+  
+- **返回对象**：
+  - `startLiveViewServer()`: 启动 Express 服务器
+  - `takeLiveScreenshot(page, logMessage?)`: 捕获截图并保存
+
+### `Utils.runStep(stepName, page, actionFn)`
+
+执行一个步骤并自动处理失败。## 模块文档
+
+详细文档请参阅 `docs/` 目录：
+
+- [ApifyKit](./docs/apify-kit.md): Apify Actor 流程控制与数据全
+- [Stealth](./docs/stealth.md): 反爬虫与指纹隐身
+- [Humanize](./docs/humanize.md): 拟人化操作模拟
+- [LiveView](./docs/live-view.md): 实时屏幕截图预览
+- [Launch](./docs/launch.md): 浏览器启动配置
+- [Utils](./docs/utils.md): 通用工具函数
+- [Constants](./docs/constants.md): 常量定义
+
+- **参数**：
+  - `stepName`: 步骤名称 (支持使用 `wrapStepNameWithFailedKey` 包装)
+  - `page`: Playwright Page 对象
+  - `actionFn`: 要执行的异步函数
+
+### `Utils.setupBlockingResources(page, resourceTypes?)`
+
+设置资源拦截器。
+
+- **参数**：
+  - `page`: Playwright Page 对象
+  - `resourceTypes` (可选): 要屏蔽的资源类型数组，默认为 `['font', 'image', 'media']`
+
+### `Utils.setupViewport(page, width?, height?)`
+
+设置浏览器视口大小。
+
+- **参数**：
+  - `page`: Playwright Page 对象
+  - `width` (可选): 宽度，默认 1920
+  - `height` (可选): 高度，默认 1080
+
+### `Utils.parseSseStream(sseStreamText)`
+
+解析 SSE 流文本为 JSON 对象数组。
+
+- **参数**：
+  - `sseStreamText`: SSE 格式的文本
+  
+- **返回**: JSON 对象数组
+
+## 📝 注意事项
+
+- Live View 仅在 Apify 平台运行时可见（通过 Live View 选项卡）
+- `runStep` 捕获的截图是全页截图（JPEG 格式，质量 60），用于减少数据量
+- 资源拦截会显著提升加载速度，但可能影响需要图片/样式的页面
+
+## 📄 License
+
+ISC

package/docs/apify-kit.md

@@ -0,0 +1,59 @@
+# ApifyKit
+
+`ApifyKit` 提供了一组用于简化 Apify Actor 开发的实用函数，核心是 `runStep` 机制和数据推送。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { ApifyKit } = usePlaywrightToolKit();
+```
+
+## 方法
+
+### `runStep(stepName, page, stepFunction)`
+
+执行一个封装的步骤。会自动记录开始日志、执行函数，并捕获错误。
+如果步骤失败，会自动：
+1. 打印带颜色的错误日志。
+2. 拍摄错误截图。
+3. 将错误信息和截图保存到 Default Dataset 中。
+
+**参数:**
+- `stepName` (string): 步骤名称，用于日志和错误报告。
+- `page` (Page): Playwright Page 对象，用于截图。
+- `stepFunction` (function): 包含实际逻辑的异步函数。
+
+**示例:**
+```javascript
+await ApifyKit.runStep('填写登录表单', page, async () => {
+    await page.fill('#username', 'user');
+    await page.fill('#password', 'pass');
+    await page.click('#login');
+});
+```
+
+### `pushSuccess(data)`
+
+将成功的数据推送到 Default Dataset。会自动添加 `status: 'SUCCESS'` 和时间戳。
+
+**参数:**
+- `data` (object): 要推送的数据对象。
+
+**示例:**
+```javascript
+await ApifyKit.pushSuccess({
+    title: 'Product A',
+    price: 99.9
+});
+```
+
+### `pushFailed(stepName, errorMessage, screenshotBase64, kvStoreKey)`
+
+(通常由 `runStep` 内部调用) 将失败信息推送到 Default Dataset。
+
+### `wrapStepNameWithFailedKey(failedKey, stepName)`
+将错误 Key (例如错误码) 绑定到步骤名称上，用于在失败时提取该 Key。
+
+### `unwrapStepName(stepName)`
+解包步骤名称，获取绑定的 Key (如果有)。

package/docs/constants.md

@@ -0,0 +1,25 @@
+# Constants
+
+`Constants` 模块定义了项目中共用的常量、枚举和键名映射。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { Constants } = usePlaywrightToolKit();
+```
+
+## 导出
+
+### `ErrorKeygen`
+
+常用的错误代码 Key 枚举，用于 standardized error handling。
+
+- `NotLogin`: 'not_login'
+- `CaptchaDetected`: 'captcha_detected'
+- `RegionRestricted`: 'region_restricted'
+- `RateLimited`: 'rate_limited'
+
+### `FAILED_KEY_SEPARATOR`
+
+用于 `ApifyKit.wrapStepNameWithFailedKey` 的分隔符。

package/docs/humanize.md

@@ -0,0 +1,40 @@
+# Humanize
+
+`Humanize` 模块用于模拟人类操作行为，如随机延迟和鼠标移动。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { Humanize } = usePlaywrightToolKit();
+```
+
+## 方法
+
+### `randomSleep(min, max)`
+
+随机等待一段毫秒数。基于 `delay` 库。
+
+**参数:**
+- `min` (number): 最小延迟 (ms)。
+- `max` (number): (可选) 最大延迟 (ms)。如果未提供，则等待固定的 `min` 时间。
+
+**示例:**
+```javascript
+await Humanize.randomSleep(1000, 3000); // 等待 1-3 秒
+```
+
+### `simulateGaze(cursor, durationMs)`
+
+模拟人类“注视”或“阅读”行为：控制鼠标在页面上进行随机的小幅度移动。需要配合 `ghost-cursor` 使用。
+
+**参数:**
+- `cursor` (GhostCursor): `ghost-cursor` 对象。
+- `durationMs` (number): 持续时间 (ms)，默认为 2000。
+
+**示例:**
+```javascript
+import { createCursor } from 'ghost-cursor-playwright';
+const cursor = await createCursor(page);
+await Humanize.simulateGaze(cursor, 5000);
+```

package/docs/launch.md

@@ -0,0 +1,32 @@
+# Launch
+
+`Launch` 模块提供与浏览器启动和指纹生成相关的辅助配置。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { Launch } = usePlaywrightToolKit();
+```
+
+## 方法
+
+### `getFingerprintGeneratorOptions(options)`
+
+返回配置好的能够通过检测的指纹生成器选项。
+
+**参数:**
+- `options` (object): (可选) 覆盖默认配置。
+
+**默认配置:**
+- `devices`: ['desktop']
+- `operatingSystems`: ['windows', 'macos']
+- `browsers`: ['chrome', 'edge']
+- `locales`: ['zh-CN', 'en-US']
+
+### `getLaunchOptions(extraArgs)`
+
+返回合并了 Stealth 参数的 Playwright 启动选项。
+
+**参数:**
+- `extraArgs` (string[]): (可选) 额外的启动参数。

package/docs/live-view.md

@@ -0,0 +1,38 @@
+# LiveView
+
+`LiveView` 模块使得在 Apify 平台上运行 Playwright 爬虫（尤其是有头模式）时，能够实时查看浏览器的屏幕截图。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { LiveView } = usePlaywrightToolKit();
+const { startLiveViewServer, takeLiveScreenshot } = LiveView.useLiveView();
+```
+
+## 方法
+
+### `startLiveViewServer()`
+
+启动一个轻量级的 Express 服务器，用于展示最新的屏幕截图。
+通常在 Actor 启动时调用。
+
+**注意:** 仅在 Apify 平台上且需要 Live View 功能时调用。
+
+### `takeLiveScreenshot(page, logMessage)`
+
+拍摄当前页面的截图，并将其保存到 Key-Value Store 中供 Live Server 展示。
+
+**参数:**
+- `page` (Page): Playwright Page 对象。
+- `logMessage` (string): (可选) 日志消息。
+
+**示例:**
+```javascript
+// 定时截图
+setInterval(() => takeLiveScreenshot(page), 5000);
+```
+
+## 配置
+
+默认使用的 Key 为 `LIVE_VIEW_SCREENSHOT`。可以通过 `useLiveView(customKey)` 自定义。

package/docs/stealth.md

@@ -0,0 +1,55 @@
+# Stealth
+
+`Stealth` 模块提供了一组反爬虫和隐身技术，旨在提高爬虫的存活率和稳定性。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { Stealth } = usePlaywrightToolKit();
+```
+
+## 方法
+
+### `syncViewportWithScreen(page)`
+
+**关键功能**。将 Playwright 的 Page 视口大小调整为与浏览器指纹 (window.screen) 一致。
+这可以有效防止 "Viewport Mismatch" 类型的反爬检测（例如 Akamai, Datadome 等）。
+
+**参数:**
+- `page` (Page): Playwright Page 对象。
+
+**示例:**
+```javascript
+// 在 preNavigationHooks 中使用
+preNavigationHooks: [
+    async ({ page }) => {
+        await Stealth.syncViewportWithScreen(page);
+    }
+]
+```
+
+### `hideWebdriver(page)`
+
+确保 `navigator.webdriver` 属性被隐藏或设置为 false。虽然 `puppeteer-extra-plugin-stealth` 已经做了这个，但这是一个双重保险。
+
+### `setupBlockingResources(page, resourceTypes)`
+
+拦截并屏蔽指定类型的资源请求，以加速页面加载并节省带宽。
+
+**参数:**
+- `page` (Page): Playwright Page 对象。
+- `resourceTypes` (string[]): (可选) 默认为 `['font', 'image', 'media']`。
+
+### `getStealthLaunchArgs()`
+
+返回一组推荐的 Chrome 启动参数，用于隐藏自动化特征。
+
+**示例:**
+```javascript
+launchContext: {
+    launchOptions: {
+        args: Stealth.getStealthLaunchArgs()
+    }
+}
+```

package/docs/utils.md

@@ -0,0 +1,28 @@
+# Utils
+
+`Utils` 模块包含通用的工具函数，不依赖于 Apify 或特定的爬虫逻辑。
+
+## 引入
+
+```javascript
+import { usePlaywrightToolKit } from '@skrillex1224/playwright-toolkit';
+const { Utils } = usePlaywrightToolKit();
+```
+
+## 方法
+
+### `parseSseStream(sseStreamText)`
+
+解析 Server-Sent Events (SSE) 格式的文本流。常用于处理 AI 模型的流式响应。
+
+**参数:**
+- `sseStreamText` (string): 完整的 SSE 文本。
+
+**返回:**
+- `Array<Object>`: 解析后的 JSON 对象数组。会自动过滤掉非 JSON 行和空行。
+
+**示例:**
+```javascript
+const events = Utils.parseSseStream(responseText);
+console.log(events[0].data);
+```

package/index.js

@@ -0,0 +1,21 @@
+import { ApifyKit } from './src/apify-kit.js';
+import { Utils } from './src/utils.js';
+import { Stealth } from './src/stealth.js';
+import { Humanize } from './src/humanize.js';
+import { Launch } from './src/launch.js';
+import { LiveView } from './src/live-view.js';
+import * as Constants from './src/constants.js';
+
+// Unified Entry Point
+export const usePlaywrightToolKit = () => {
+    return {
+        ApifyKit,
+
+        Stealth,
+        Humanize,
+        Launch,
+        LiveView,
+        Constants,
+        Utils
+    };
+};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@skrillex1224/playwright-toolkit",
+  "version": "2.0.0",
+  "description": "一个在 Apify/Crawlee Actor 中启用实时截图视图的实用工具库。",
+  "main": "index.js",
+  "type": "module",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "apify",
+    "crawlee",
+    "live-view",
+    "screenshot",
+    "playwright"
+  ],
+  "author": "FJH",
+  "license": "ISC",
+  "dependencies": {
+    "delay": "^7.0.0",
+    "express": "^4.18.2"
+  },
+  "peerDependencies": {
+    "apify": "*",
+    "crawlee": "*",
+    "playwright": "*"
+  }
+}

package/src/apify-kit.js

@@ -0,0 +1,108 @@
+import { log } from 'crawlee';
+import { Actor } from 'apify';
+import { Status, FAILED_KEY_SEPARATOR, StatusCode } from './constants.js';
+
+export const ApifyKit = {
+
+    /**
+     * 包装 Step Name
+     */
+    wrapStepNameWithFailedKey(key, stepName) {
+        return `${key}${FAILED_KEY_SEPARATOR}${stepName}`;
+    },
+
+    /**
+     * 解包 Step Name
+     */
+    unwrapStepName(stepName) {
+        const splitIndex = stepName.indexOf(FAILED_KEY_SEPARATOR);
+        if (splitIndex === -1) {
+            return ['-', stepName];
+        }
+        const key = stepName.substring(0, splitIndex);
+        const value = stepName.substring(splitIndex + FAILED_KEY_SEPARATOR.length);
+        return [key, value];
+    },
+
+    /**
+     * 核心封装：执行步骤，带自动日志确认和失败截图处理
+     */
+    async runStep(pendingStepName, page, actionFn, options = {}) {
+        const { failActor = true } = options;  // 默认调用 Actor.fail
+        const [failedKey, stepName] = this.unwrapStepName(pendingStepName);
+
+        log.info(`🔄 [正在执行] ${stepName}...`);
+
+        try {
+            const result = await actionFn();
+            log.info(`✅ [执行成功] ${stepName}`);
+            return result;
+        } catch (error) {
+            log.error(`❌ [执行失败] ${stepName}: ${error.message}`);
+
+            let screenshotBase64 = '截图失败';
+            try {
+                if (page) {
+                    const buffer = await page.screenshot({ fullPage: true, type: 'jpeg', quality: 60 });
+                    screenshotBase64 = `data:image/jpeg;base64,${buffer.toString('base64')}`;
+                }
+            } catch (snapErr) {
+                log.warning(`截图生成失败: ${snapErr.message}`);
+            }
+
+            // 使用 pushFailed 方法推送失败数据（私有使用）
+            await this.pushFailed(error, {
+                failedStep: stepName,
+                failedKey: failedKey,
+                errorMessage: error.message,
+                errorStack: error.stack,
+                screenshotBase64: screenshotBase64
+            });
+
+            // 根据 failActor 决定是否调用 Actor.fail
+            if (failActor) {
+                await Actor.fail(`Run Step ${stepName} 失败: ${error.message}`);
+            } else {
+                // 不调用 Actor.fail，直接抛出错误
+                throw error;
+            }
+        }
+    },
+
+    /**
+     * 宽松版runStep：失败时不调用Actor.fail，只抛出异常
+     */
+    async runStepLoose(stepName, page, fn) {
+        return await this.runStep(stepName, page, fn, { failActor: false });
+    },
+
+    /**
+     * 推送成功数据的通用方法
+     * @param {Object} data - 要推送的数据对象
+     */
+    async pushSuccess(data) {
+        await Actor.pushData({
+            code: StatusCode.Success,
+            status: Status.Success,
+            timestamp: new Date().toISOString(),
+            ...data
+        });
+    },
+
+    /**
+     * 推送失败数据的通用方法（私有方法，仅供runStep内部使用）
+     * @param {Error|Object} error - 错误对象（可包含其他的错误/或部分处理成功的额外信息）
+     * @param {Object} [meta] - 额外的数据（如failedStep, screenshotBase64等，仅runStep使用）
+     * @private
+     */
+    async pushFailed(error, meta = {}) {
+        await Actor.pushData({
+            code: StatusCode.Failed,
+            status: Status.Failed,
+            // 这里可能带其他错误信息
+            error,
+            timestamp: new Date().toISOString(),
+            ...meta
+        });
+    }
+}

package/src/constants.js

@@ -0,0 +1,18 @@
+export const ErrorKeygen = {
+    NotLogin: 30000001,
+    Chaptcha: 30000002,
+}
+
+export const Status = {
+    Success: 'SUCCESS',
+    Failed: 'FAILED'
+}
+
+export const StatusCode = {
+    Success: 0,
+    Failed: -1
+}
+
+export const FAILED_KEY_SEPARATOR = '::<@>::';
+
+export const PresetOfLiveViewKey = 'LIVE_VIEW_SCREENSHOT';

package/src/humanize.js

@@ -0,0 +1,37 @@
+import delay from 'delay';
+import { log } from 'crawlee';
+
+export const Humanize = {
+    /**
+     * 随机延迟一段毫秒数 (API Wrapper for 'delay' package)
+     * @param {number} min - 最小毫秒
+     * @param {number} max - 最大毫秒
+     */
+    async randomSleep(min, max) {
+        const ms = typeof max === 'number'
+            ? delay.range(min, max)
+            : delay(min); // 如果只传一个参数，视为固定延迟或最小延迟
+
+        // log.debug(`[Humanize] Sleeping for ${await ms} ms...`); // delay return promise acts like number somewhat but best await it
+        // The delay package returns a promise that resolves after the delay.
+        // delay.range() returns a promise too.
+
+        await ms;
+    },
+
+    /**
+     * 模拟人类“注视”或“阅读”行为：鼠标在页面上随机微动。
+     * @param {import('ghost-cursor-playwright').GhostCursor} cursor 
+     * @param {number} durationMs - 持续时间
+     */
+    async simulateGaze(cursor, durationMs = 2000) {
+        const startTime = Date.now();
+        while (Date.now() - startTime < durationMs) {
+            // 随机小幅度移动
+            const x = Math.random() * 800;
+            const y = Math.random() * 600;
+            await cursor.moveTo({ x, y });
+            await delay.range(200, 800);
+        }
+    }
+}

package/src/launch.js

@@ -0,0 +1,26 @@
+// 集中管理启动配置，暂时主要由 Stealth 模块提供 Args，这里作为扩展点
+import { Stealth } from './stealth.js';
+
+export const Launch = {
+    getLaunchOptions(customArgs = []) {
+        return {
+            args: [
+                ...Stealth.getStealthLaunchArgs(),
+                ...customArgs
+            ],
+            ignoreDefaultArgs: ['--enable-automation'],
+        };
+    },
+
+    /**
+     * 推荐的 Fingerprint Generator 选项
+     * 确保生成的是桌面端、较新的 Chrome，以匹配我们的脚本逻辑
+     */
+    getFingerprintGeneratorOptions() {
+        return {
+            browsers: [{ name: 'chrome', minVersion: 110 }],
+            devices: ['desktop'],
+            operatingSystems: ['windows', 'linux'], // 包含 Linux 兼容容器
+        };
+    }
+}

package/src/live-view.js

@@ -0,0 +1,81 @@
+import express from 'express';
+import { log } from 'crawlee';
+import { Actor } from 'apify';
+import { PresetOfLiveViewKey } from './constants';
+
+/**
+ * 启动一个 Web 服务器以在 Live View 选项卡中显示最新的屏幕截图。
+ */
+async function startLiveViewServer(liveViewKey) {
+    const app = express();
+
+    app.get('/', async (req, res) => {
+        try {
+            // 从默认的 Key-Value Store 中读取最新的屏幕截图
+            const screenshotBuffer = await Actor.getValue(liveViewKey);
+
+            if (!screenshotBuffer) {
+                // 如果还没有截图，发送一个自动刷新的占位页面
+                res.send('<html><head><meta http-equiv="refresh" content="2"></head><body>等待第一个屏幕截图...</body></html>');
+                return;
+            }
+
+            // 将 Buffer 转换为 Base64 字符串
+            const screenshotBase64 = screenshotBuffer.toString('base64');
+
+            // 发送一个 HTML 页面，该页面每 1 秒自动刷新一次，并显示截图
+            res.send(`
+                <html>
+                    <head>
+                        <title>Live View (截图)</title>
+                        <meta http-equiv="refresh" content="1">
+                    </head>
+                    <body style="margin:0; padding:0;">
+                        <img src="data:image/png;base64,${screenshotBase64}" 
+                             alt="Live View Screenshot" 
+                             style="width: 100%; height: auto;" />
+                    </body>
+                </html>
+            `);
+        } catch (error) {
+            log.error(`Live View 服务器错误: ${error.message}`);
+            res.status(500).send(`无法加载屏幕截图: ${error.message}`);
+        }
+    });
+
+    // 监听 Apify 容器端口 
+    const port = process.env.APIFY_CONTAINER_PORT || 4321;
+    app.listen(port, () => { log.info(`Live View 服务器已启动，监听端口 ${port}。请打开 "Live View" 选项卡查看。`); });
+}
+
+/**
+ * 拍摄当前页面的屏幕截图并将其保存到 Key-Value Store。
+ * @param {import('playwright').Page} page
+ * @param {string} [logMessage] - 可选的日志消息。
+ */
+async function takeLiveScreenshot(liveViewKey, page, logMessage) {
+    try {
+        const buffer = await page.screenshot({ type: 'png' });
+        await Actor.setValue(liveViewKey, buffer, { contentType: 'image/png' });
+        if (logMessage) {
+            log.info(`(截图): ${logMessage}`);
+        }
+    } catch (e) {
+        log.warning(`无法捕获 Live View 屏幕截图: ${e.message}`);
+    }
+}
+
+const useLiveView = (liveViewKey = PresetOfLiveViewKey) => {
+    return {
+        takeLiveScreenshot: async (page, logMessage) => {
+            return await takeLiveScreenshot(liveViewKey, page, logMessage)
+        },
+        startLiveViewServer: async () => {
+            return await startLiveViewServer(liveViewKey);
+        }
+    }
+}
+
+export const LiveView = {
+    useLiveView,
+};

package/src/stealth.js

@@ -0,0 +1,75 @@
+import { log } from 'crawlee';
+
+export const Stealth = {
+    /**
+     * 关键修复：将 Page 视口调整为与浏览器指纹 (window.screen) 一致。
+     * 防止 "Viewport Mismatch" 类型的反爬检测。
+     * @param {import('playwright').Page} page 
+     */
+    async syncViewportWithScreen(page) {
+        try {
+            // 获取指纹中的屏幕尺寸
+            const screen = await page.evaluate(() => ({
+                width: window.screen.width,
+                height: window.screen.height,
+                availWidth: window.screen.availWidth,
+                availHeight: window.screen.availHeight,
+            }));
+
+            // 调整视口
+            await page.setViewportSize({
+                width: screen.width,
+                height: screen.height
+            });
+
+            log.info(`[Stealth] Viewport synced to fingerprint: ${screen.width}x${screen.height}`);
+        } catch (e) {
+            log.warning(`[Stealth] Failed to sync viewport: ${e.message}. Fallback to 1920x1080.`);
+            await page.setViewportSize({ width: 1920, height: 1080 });
+        }
+    },
+
+    /**
+     * 确保 navigator.webdriver 隐藏 (通常 Playwright Stealth 插件已处理，但双重保险)
+     */
+    async hideWebdriver(page) {
+        await page.addInitScript(() => {
+            Object.defineProperty(navigator, 'webdriver', {
+                get: () => false,
+            });
+        });
+    },
+
+    /**
+     * 通用的 Playwright 资源拦截器，用于屏蔽不必要的资源以加速加载
+     * @param {import('playwright').Page} page
+     * @param {string[]} [resourceTypes] - 要屏蔽的资源类型，默认为 ['font', 'image', 'media']
+     */
+    async setupBlockingResources(page, resourceTypes = ['font', 'image', 'media']) {
+        await page.route('**/*', (route) => {
+            const request = route.request();
+            const type = request.resourceType();
+            if (resourceTypes.includes(type)) {
+                return route.abort();
+            }
+            return route.continue();
+        });
+    },
+
+    /**
+     * 获取推荐的 Stealth 启动参数
+     */
+    getStealthLaunchArgs() {
+        return [
+            '--disable-blink-features=AutomationControlled',
+            '--no-sandbox',
+            '--disable-setuid-sandbox',
+            '--disable-infobars',
+            '--window-position=0,0',
+            '--ignore-certificate-errors',
+            '--disable-web-security',
+            // 注意：不建议这里强制指定 window-size，让 syncViewportWithScreen 去动态调整
+            // '--window-size=1920,1080' 
+        ];
+    }
+}

package/src/utils.js

@@ -0,0 +1,22 @@
+export const Utils = {
+    /**
+    * 解析 SSE 流文本
+    */
+    parseSseStream(sseStreamText) {
+        const events = [];
+        const lines = sseStreamText.split('\n');
+        for (const line of lines) {
+            if (line.startsWith('data: ')) {
+                try {
+                    const jsonContent = line.substring(6).trim();
+                    if (jsonContent && jsonContent !== '[DONE]') {
+                        events.push(JSON.parse(jsonContent));
+                    }
+                } catch (e) {
+                    // Ignore lines that are not valid JSON
+                }
+            }
+        }
+        return events;
+    }
+}