@szc-ft/mcp-szcd-client 0.18.0 → 0.19.0

package/lib/browser-engine.js

@@ -0,0 +1,379 @@
+/**
+ * 浏览器控制引擎 - 双模式（connect / launch）
+ *
+ * 模式 A: connect（优先）
+ *   连接用户已启动的调试 Chrome（--remote-debugging-port=9222）
+ *   天然继承登录态/Cookie/SSO/微前端环境
+ *
+ * 模式 B: launch（回退）
+ *   启动新的 headless Chrome，需要用户提供可访问的 URL
+ *
+ * 依赖（optionalDependencies）：puppeteer-core
+ */
+
+import { findChrome, getChromeInstallGuide } from "./chrome-finder.js";
+
+export class BrowserEngine {
+    constructor() {
+        this.browser = null;
+        this.page = null;
+        this.mode = null;        // 'connect' | 'launch'
+        this.ownedBrowser = false; // launch 模式为 true，决定关闭时是否 kill
+    }
+
+    /**
+     * 初始化：自动选择 connect 或 launch 模式
+     * @param {object} options
+     * @param {string} [options.cdpUrl='http://localhost:9222'] - CDP 调试地址
+     * @param {string} [options.pageUrl] - 目标页面 URL（connect 时用于匹配标签页）
+     * @param {object} [options.viewport] - 视口尺寸 { width, height }
+     * @returns {Promise<object>} 初始化结果
+     */
+    async init(options = {}) {
+        const cdpUrl = options.cdpUrl || "http://localhost:9222";
+
+        // 优先尝试 connect 模式
+        if (await this.isDebuggerAvailable(cdpUrl)) {
+            return this.connect(cdpUrl, options);
+        }
+
+        // 回退到 launch 模式
+        return this.launch(options);
+    }
+
+    /**
+     * 检查调试端口是否可用
+     */
+    async isDebuggerAvailable(cdpUrl) {
+        try {
+            const res = await fetch(`${cdpUrl}/json/version`, {
+                signal: AbortSignal.timeout(2000),
+            });
+            return res.ok;
+        } catch {
+            return false;
+        }
+    }
+
+    /**
+     * 模式 A：连接到用户已有的 Chrome
+     */
+    async connect(cdpUrl, options = {}) {
+        const puppeteer = await loadPuppeteer();
+        this.browser = await puppeteer.connect({ browserURL: cdpUrl });
+        this.mode = "connect";
+        this.ownedBrowser = false;
+
+        // 获取页面：优先使用指定 URL 匹配的标签页
+        const pages = await this.browser.pages();
+        if (options.pageUrl) {
+            this.page = pages.find((p) => p.url().includes(options.pageUrl))
+                     || await this.browser.newPage();
+        } else {
+            // 选择第一个非 chrome:// 的页面
+            this.page = pages.find((p) => !p.url().startsWith("chrome://"))
+                     || pages[0];
+        }
+
+        if (options.viewport && this.page) {
+            await this.page.setViewport(options.viewport);
+        }
+
+        return {
+            mode: "connect",
+            cdpUrl,
+            currentUrl: this.page?.url() || null,
+            totalPages: pages.length,
+            allPageUrls: pages.map((p) => p.url()),
+        };
+    }
+
+    /**
+     * 模式 B：启动新的 Chrome
+     */
+    async launch(options = {}) {
+        const puppeteer = await loadPuppeteer();
+        const chrome = findChrome();
+
+        if (!chrome.path) {
+            const guide = getChromeInstallGuide();
+            const error = new Error(
+                `${guide.message}\n安装方式：\n${guide.installCommands.join("\n")}\n\n` +
+                `或使用 connect 模式：以 --remote-debugging-port=9222 启动 Chrome`
+            );
+            error.code = "CHROME_NOT_FOUND";
+            throw error;
+        }
+
+        this.browser = await puppeteer.launch({
+            executablePath: chrome.path,
+            headless: true,
+            args: [
+                "--no-sandbox",
+                "--disable-setuid-sandbox",
+                "--disable-dev-shm-usage",
+                "--disable-gpu",
+                "--no-first-run",
+                "--no-default-browser-check",
+            ],
+        });
+        this.page = await this.browser.newPage();
+        this.mode = "launch";
+        this.ownedBrowser = true;
+
+        if (options.viewport) {
+            await this.page.setViewport(options.viewport);
+        } else {
+            await this.page.setViewport({ width: 1440, height: 900 });
+        }
+
+        return {
+            mode: "launch",
+            browser: chrome.name,
+            chromePath: chrome.path,
+        };
+    }
+
+    /**
+     * 执行单个步骤
+     * @param {object} step - 步骤定义
+     * @param {object} context - 执行上下文 { outputDir }
+     * @returns {Promise<object>} 步骤执行结果
+     */
+    async executeStep(step, context = {}) {
+        const startTime = Date.now();
+        try {
+            const result = await this._dispatchStep(step, context);
+            return {
+                ...result,
+                step: step.type,
+                duration: Date.now() - startTime,
+                status: "PASS",
+            };
+        } catch (err) {
+            return {
+                step: step.type,
+                duration: Date.now() - startTime,
+                status: "FAIL",
+                error: err.message,
+            };
+        }
+    }
+
+    /**
+     * 步骤分发
+     */
+    async _dispatchStep(step, context) {
+        switch (step.type) {
+            case "navigate":     return this._navigate(step);
+            case "screenshot":   return this._screenshot(step, context);
+            case "compare":      return this._compare(step, context);
+            case "click":        return this._click(step);
+            case "type":         return this._type(step);
+            case "waitFor":      return this._waitFor(step);
+            case "evaluate":     return this._evaluate(step);
+            case "checkElement": return this._checkElement(step);
+            default:
+                throw new Error(`Unknown step type: ${step.type}`);
+        }
+    }
+
+    async _navigate(step) {
+        const start = Date.now();
+        await this.page.goto(step.url, {
+            waitUntil: step.waitUntil || "networkidle2",
+            timeout: step.timeout || 30000,
+        });
+        const title = await this.page.title();
+        return {
+            url: this.page.url(),
+            title,
+            loadTime: Date.now() - start,
+        };
+    }
+
+    async _screenshot(step, context) {
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const outputDir = context.outputDir || "/tmp";
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        const filename = step.filename || `screenshot-${Date.now()}.png`;
+        const filepath = path.join(outputDir, filename);
+
+        await this.page.screenshot({
+            path: filepath,
+            fullPage: step.fullPage !== false,
+            ...(step.clip ? { clip: step.clip } : {}),
+        });
+
+        const viewport = this.page.viewport();
+        return { filepath, width: viewport.width, height: viewport.height };
+    }
+
+    async _compare(step, context) {
+        const { compareDesign } = await import("./visual-compare.js");
+        const fs = await import("node:fs");
+        const path = await import("node:path");
+        const outputDir = context.outputDir || "/tmp";
+
+        // 先截图
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+        const screenshotPath = path.join(outputDir, `compare-screenshot-${Date.now()}.png`);
+        await this.page.screenshot({ path: screenshotPath, fullPage: true });
+
+        // 执行对比
+        const result = await compareDesign(screenshotPath, step.designImagePath, {
+            threshold: step.threshold,
+            outputDir,
+            regions: step.regions,
+            page: this.page,
+        });
+
+        return result;
+    }
+
+    async _click(step) {
+        const selector = step.selector;
+        await this.page.waitForSelector(selector, { timeout: step.timeout || 5000 });
+
+        if (step.waitForNavigation) {
+            await Promise.all([
+                this.page.waitForNavigation({ timeout: 10000 }),
+                this.page.click(selector),
+            ]);
+        } else {
+            await this.page.click(selector);
+        }
+
+        const tagName = await this.page.$eval(selector, (el) => el.tagName).catch(() => "unknown");
+        return { clicked: true, selector, tagName };
+    }
+
+    async _type(step) {
+        const selector = step.selector;
+        await this.page.waitForSelector(selector, { timeout: step.timeout || 5000 });
+
+        if (step.clear) {
+            await this.page.click(selector, { clickCount: 3 });
+        }
+
+        await this.page.type(selector, step.text);
+        const value = await this.page.$eval(selector, (el) => el.value).catch(() => "");
+        return { typed: true, selector, value };
+    }
+
+    async _waitFor(step) {
+        const timeout = step.timeout || 10000;
+
+        if (step.selector) {
+            await this.page.waitForSelector(step.selector, { timeout });
+            return { matched: true, type: "selector", value: step.selector };
+        }
+
+        if (step.url) {
+            await this.page.waitForResponse(
+                (r) => r.url().includes(step.url),
+                { timeout }
+            );
+            return { matched: true, type: "url", value: step.url };
+        }
+
+        throw new Error("waitFor requires either 'selector' or 'url'");
+    }
+
+    async _evaluate(step) {
+        const result = await this.page.evaluate(step.expression);
+        return { result };
+    }
+
+    async _checkElement(step) {
+        const selector = step.selector;
+        const expect = step.expect || {};
+
+        const info = await this.page.evaluate((sel) => {
+            const els = document.querySelectorAll(sel);
+            return {
+                count: els.length,
+                visible: els.length > 0 && els[0].offsetParent !== null,
+                texts: Array.from(els).slice(0, 5).map((el) =>
+                    el.textContent?.substring(0, 100) || ""
+                ),
+            };
+        }, selector);
+
+        let passed = true;
+        const checks = {};
+
+        if (expect.visible !== undefined) {
+            checks.visible = { expected: expect.visible, actual: info.visible };
+            if (info.visible !== expect.visible) passed = false;
+        }
+
+        if (expect.minCount !== undefined) {
+            checks.minCount = { expected: expect.minCount, actual: info.count };
+            if (info.count < expect.minCount) passed = false;
+        }
+
+        if (expect.maxCount !== undefined) {
+            checks.maxCount = { expected: expect.maxCount, actual: info.count };
+            if (info.count > expect.maxCount) passed = false;
+        }
+
+        if (expect.hasText !== undefined) {
+            const allText = info.texts.join(" ");
+            checks.hasText = { expected: expect.hasText, actual: allText };
+            if (!allText.includes(expect.hasText)) passed = false;
+        }
+
+        return {
+            passed,
+            selector,
+            checks,
+            elementCount: info.count,
+            visible: info.visible,
+        };
+    }
+
+    /**
+     * 关闭浏览器
+     * connect 模式: disconnect（不关闭用户浏览器）
+     * launch 模式: close（关闭我们启动的浏览器）
+     */
+    async close() {
+        if (!this.browser) return;
+        try {
+            if (this.ownedBrowser) {
+                await this.browser.close();
+            } else {
+                this.browser.disconnect();
+            }
+        } catch {
+            // ignore close errors
+        }
+        this.browser = null;
+        this.page = null;
+    }
+}
+
+/**
+ * 动态加载 puppeteer-core
+ */
+async function loadPuppeteer() {
+    try {
+        const mod = await import("puppeteer-core");
+        return mod.default || mod;
+    } catch (err) {
+        const error = new Error(
+            `puppeteer-core 未安装。请执行：npm install puppeteer-core\n原始错误：${err.message}`
+        );
+        error.code = "DEPENDENCY_MISSING";
+        throw error;
+    }
+}
+
+export default BrowserEngine;

package/lib/chrome-finder.js

@@ -0,0 +1,125 @@
+/**
+ * Chrome 路径检测 - 跨平台查找 Chrome/Chromium 可执行文件
+ * 仅 launch 模式需要，connect 模式通过 CDP 连接不需要此模块
+ */
+
+import fs from "node:fs";
+import { execSync } from "node:child_process";
+import os from "node:os";
+
+/**
+ * 跨平台 Chrome 路径候选列表
+ */
+const CHROME_PATHS = {
+    linux: [
+        "/usr/bin/google-chrome",
+        "/usr/bin/google-chrome-stable",
+        "/usr/bin/chromium",
+        "/usr/bin/chromium-browser",
+        "/snap/bin/chromium",
+        "/usr/local/bin/chrome",
+    ],
+    darwin: [
+        "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+        "/Applications/Chromium.app/Contents/MacOS/Chromium",
+        "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+    ],
+    win32: [
+        "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+        "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+        `${process.env.LOCALAPPDATA || ""}\\Google\\Chrome\\Application\\chrome.exe`,
+    ],
+};
+
+/**
+ * 通过 PATH 搜索命令
+ * @param {string} cmd - 命令名
+ * @returns {string|null}
+ */
+function findInPath(cmd) {
+    try {
+        const platform = os.platform();
+        const command = platform === "win32" ? `where ${cmd}` : `which ${cmd}`;
+        const result = execSync(command, { encoding: "utf8", timeout: 5000 }).trim();
+        const firstLine = result.split("\n")[0].trim();
+        if (firstLine && fs.existsSync(firstLine)) {
+            return firstLine;
+        }
+    } catch {
+        // not found
+    }
+    return null;
+}
+
+/**
+ * 查找本地 Chrome 浏览器路径
+ * @returns {{ path: string|null, name: string, error?: string }}
+ */
+export function findChrome() {
+    const platform = os.platform();
+    const candidates = CHROME_PATHS[platform] || CHROME_PATHS.linux;
+
+    // 1. 检查已知路径
+    for (const p of candidates) {
+        if (p && fs.existsSync(p)) {
+            const name = p.includes("Chromium") ? "Chromium" :
+                         p.includes("Canary") ? "Chrome Canary" : "Google Chrome";
+            return { path: p, name };
+        }
+    }
+
+    // 2. PATH 搜索
+    const pathCmds = platform === "win32"
+        ? ["chrome", "chromium"]
+        : ["google-chrome", "google-chrome-stable", "chromium", "chromium-browser"];
+
+    for (const cmd of pathCmds) {
+        const found = findInPath(cmd);
+        if (found) {
+            const name = cmd.includes("chromium") ? "Chromium" : "Google Chrome";
+            return { path: found, name };
+        }
+    }
+
+    // 3. 未找到
+    return {
+        path: null,
+        name: "unknown",
+        error: "CHROME_NOT_FOUND",
+    };
+}
+
+/**
+ * 获取 Chrome 未找到时的安装引导信息
+ * @returns {object}
+ */
+export function getChromeInstallGuide() {
+    const platform = os.platform();
+    const guides = {
+        linux: {
+            message: "未检测到 Chrome/Chromium 浏览器",
+            installCommands: [
+                "Ubuntu/Debian: sudo apt install google-chrome-stable",
+                "Ubuntu/Debian (Chromium): sudo apt install chromium-browser",
+                "CentOS/RHEL: sudo yum install google-chrome-stable",
+            ],
+        },
+        darwin: {
+            message: "未检测到 Chrome/Chromium 浏览器",
+            installCommands: [
+                "Homebrew: brew install --cask google-chrome",
+                "或从 https://www.google.com/chrome/ 下载",
+            ],
+        },
+        win32: {
+            message: "未检测到 Chrome 浏览器",
+            installCommands: [
+                "从 https://www.google.com/chrome/ 下载安装",
+                "或 winget install Google.Chrome",
+            ],
+        },
+    };
+    return guides[platform] || guides.linux;
+}
+
+export default { findChrome, getChromeInstallGuide };

package/lib/visual-compare.js

@@ -0,0 +1,189 @@
+/**
+ * 视觉对比引擎 - pixelmatch + sharp
+ *
+ * 功能：
+ * - 全局像素对比，输出还原度评分
+ * - 分区域对比（按 CSS selector 裁剪后分别评分）
+ * - 三色 diff 图输出（红=真实差异，黄=抗锯齿，蓝=轻微色差）
+ * - 自动 resize 设计稿到截图尺寸
+ *
+ * 依赖（optionalDependencies）：
+ * - sharp: 图片处理和 resize
+ * - pixelmatch: 像素对比
+ * - pngjs: PNG 编解码
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * 全局视觉对比
+ * @param {string} screenshotPath - 截图文件路径
+ * @param {string} designImagePath - 设计稿图片路径
+ * @param {object} options
+ * @param {number} [options.threshold=0.1] - 颜色差异阈值 (0-1)
+ * @param {string} [options.outputDir] - diff 图输出目录
+ * @returns {Promise<object>} 对比结果
+ */
+export async function compareDesign(screenshotPath, designImagePath, options = {}) {
+    const sharp = (await import("sharp")).default;
+    const pixelmatch = (await import("pixelmatch")).default;
+    const { PNG } = await import("pngjs");
+
+    // 1. 读取图片元数据
+    const screenshotMeta = await sharp(screenshotPath).metadata();
+    const screenshotBuf = await sharp(screenshotPath).png().toBuffer();
+    const designBuf = await sharp(designImagePath).png().toBuffer();
+
+    // 2. 以截图尺寸为基准 resize 设计稿
+    const { width, height } = screenshotMeta;
+    const designResized = await sharp(designBuf)
+        .resize(width, height, { fit: "fill" })
+        .png()
+        .toBuffer();
+
+    // 3. 解码为像素数据
+    const img1 = PNG.sync.read(screenshotBuf);
+    const img2 = PNG.sync.read(designResized);
+    const diff = new PNG({ width, height });
+
+    // 4. pixelmatch 对比
+    const threshold = options.threshold ?? 0.1;
+    const diffPixels = pixelmatch(img1.data, img2.data, diff.data, width, height, {
+        threshold,
+        includeAA: false,
+        alpha: 0.1,
+        aaColor: [255, 255, 0],        // 黄色 = 抗锯齿差异
+        diffColor: [255, 0, 0],          // 红色 = 真实差异
+        diffColorAlt: [0, 100, 255],     // 蓝色 = 轻微色差（低于阈值）
+    });
+
+    const totalPixels = width * height;
+    const fidelity = parseFloat(((totalPixels - diffPixels) / totalPixels * 100).toFixed(2));
+
+    // 5. 保存 diff 图
+    let diffImagePath = null;
+    if (options.outputDir) {
+        if (!fs.existsSync(options.outputDir)) {
+            fs.mkdirSync(options.outputDir, { recursive: true });
+        }
+        diffImagePath = path.join(options.outputDir, `diff-global-${Date.now()}.png`);
+        fs.writeFileSync(diffImagePath, PNG.sync.write(diff));
+    }
+
+    // 6. 区域对比（如果有）
+    const regions = [];
+    if (options.regions?.length && options.page) {
+        for (const region of options.regions) {
+            try {
+                const regionResult = await compareRegion(
+                    screenshotPath, designImagePath, region, { ...options, sharp, PNG, pixelmatch }
+                );
+                regions.push(regionResult);
+            } catch (err) {
+                regions.push({
+                    name: region.name,
+                    selector: region.selector,
+                    error: err.message,
+                    fidelity: null,
+                });
+            }
+        }
+    }
+
+    return {
+        fidelity,
+        diffPixels,
+        totalPixels,
+        width,
+        height,
+        diffImagePath,
+        regions,
+    };
+}
+
+/**
+ * 区域对比 - 通过 Puppeteer 获取元素位置后裁剪对比
+ * @param {string} screenshotPath
+ * @param {string} designImagePath
+ * @param {object} region - { name, selector }
+ * @param {object} deps - { sharp, PNG, pixelmatch, page, outputDir, threshold }
+ * @returns {Promise<object>}
+ */
+async function compareRegion(screenshotPath, designImagePath, region, deps) {
+    const { sharp, PNG, pixelmatch, page, outputDir } = deps;
+    const threshold = deps.threshold ?? 0.1;
+
+    // 获取元素边界框
+    const boundingBox = await page.evaluate((sel) => {
+        const el = document.querySelector(sel);
+        if (!el) return null;
+        const rect = el.getBoundingClientRect();
+        return {
+            x: Math.round(rect.x),
+            y: Math.round(rect.y),
+            width: Math.round(rect.width),
+            height: Math.round(rect.height),
+        };
+    }, region.selector);
+
+    if (!boundingBox) {
+        return {
+            name: region.name,
+            selector: region.selector,
+            error: `Element not found: ${region.selector}`,
+            fidelity: null,
+        };
+    }
+
+    // 用 sharp 裁剪两张图的对应区域
+    const screenshotRegion = await sharp(screenshotPath)
+        .extract(boundingBox)
+        .png()
+        .toBuffer();
+
+    const designRegion = await sharp(designImagePath)
+        .resize(boundingBox.width, boundingBox.height, { fit: "fill" })
+        .extract({
+            left: 0,
+            top: 0,
+            width: boundingBox.width,
+            height: boundingBox.height,
+        })
+        .png()
+        .toBuffer();
+
+    // 像素对比
+    const img1 = PNG.sync.read(screenshotRegion);
+    const img2 = PNG.sync.read(designRegion);
+    const diff = new PNG({ width: img1.width, height: img1.height });
+
+    const diffPixels = pixelmatch(img1.data, img2.data, diff.data, img1.width, img1.height, {
+        threshold,
+        includeAA: false,
+        alpha: 0.1,
+    });
+
+    const totalPixels = img1.width * img1.height;
+    const fidelity = parseFloat(((totalPixels - diffPixels) / totalPixels * 100).toFixed(2));
+
+    // 保存区域 diff 图
+    let diffImagePath = null;
+    if (outputDir) {
+        const safeName = region.name.replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, "_");
+        diffImagePath = path.join(outputDir, `diff-region-${safeName}-${Date.now()}.png`);
+        fs.writeFileSync(diffImagePath, PNG.sync.write(diff));
+    }
+
+    return {
+        name: region.name,
+        selector: region.selector,
+        boundingBox,
+        fidelity,
+        diffPixels,
+        totalPixels,
+        diffImagePath,
+    };
+}
+
+export default { compareDesign };