@szc-ft/mcp-szcd-client 0.27.0 → 0.27.2

package/commands/szcd-mcp-browser-test.md

@@ -53,5 +53,5 @@ argument-hint: <目标页面URL> [可选：设计稿图片路径]
 
 **注意事项**：
 - 首次使用需确保 Chrome 以调试模式启动：`google-chrome --remote-debugging-port=9222`
-- 如执行器报错依赖缺失，引导用户安装：`npm install puppeteer-core pixelmatch pngjs sharp`
+- 如执行器报错依赖缺失，优先按提示安装核心依赖；仅设计稿像素对比需要额外安装 `pixelmatch pngjs sharp`
 - connect 模式下天然继承用户浏览器的登录态和微前端环境

package/lib/browser-engine.js

@@ -61,7 +61,7 @@ export class BrowserEngine {
      */
     async connect(cdpUrl, options = {}) {
         const puppeteer = await loadPuppeteer();
-        this.browser = await puppeteer.connect({ browserURL: cdpUrl });
+        this.browser = await puppeteer.connect({ browserURL: cdpUrl, defaultViewport: null });
         this.mode = "connect";
         this.ownedBrowser = false;
 
@@ -178,11 +178,441 @@ export class BrowserEngine {
         }
     }
 
+    async observe(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const selector = options.selector || "body";
+        const depth = Number.parseInt(options.depth ?? 5, 10);
+        const maxInteractiveElements = Number.parseInt(options.maxInteractiveElements ?? 200, 10);
+        const frames = await this._getFrameSummaries();
+        const tree = await this._buildDomTree(targetFrame.frame, selector, depth);
+        const interactiveElements = await this._collectInteractiveElements(
+            targetFrame.frame,
+            targetFrame.frameId,
+            maxInteractiveElements
+        );
+        const title = await this.page.title().catch(() => "");
+
+        return {
+            type: "observe",
+            url: this.page.url(),
+            title,
+            timestamp: new Date().toISOString(),
+            mode: this.mode,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            frames,
+            tree,
+            interactiveElements,
+            summary: {
+                frames: frames.length,
+                interactiveElements: interactiveElements.length,
+            },
+        };
+    }
+
+    async act(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const index = options.index !== undefined ? Number.parseInt(options.index, 10) : undefined;
+        const selector = this._resolveSelector(options.selector || options.click || options.hover);
+        const typeText = options.typeText ?? options.text;
+        const action = options.hover ? "hover" : typeText !== undefined ? "type" : "click";
+
+        const result = await targetFrame.frame.evaluate((actOptions) => {
+            function getText(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 120);
+            }
+
+            function roleOf(el) {
+                const explicit = el.getAttribute("role");
+                if (explicit) return explicit;
+                const tag = el.tagName.toLowerCase();
+                if (tag === "button") return "button";
+                if (tag === "a") return "link";
+                if (["input", "textarea"].includes(tag)) return "textbox";
+                if (tag === "select") return "combobox";
+                return "generic";
+            }
+
+            function getName(el, text) {
+                return (
+                    el.getAttribute("aria-label") ||
+                    el.getAttribute("title") ||
+                    el.getAttribute("placeholder") ||
+                    el.getAttribute("alt") ||
+                    text ||
+                    ""
+                ).slice(0, 120);
+            }
+
+            function isCandidate(el) {
+                const tag = el.tagName.toLowerCase();
+                return ["a", "button", "input", "select", "textarea", "summary"].includes(tag) ||
+                    el.getAttribute("role") ||
+                    el.getAttribute("tabindex") !== null ||
+                    el.onclick ||
+                    el.getAttribute("data-testid") ||
+                    (typeof el.className === "string" && /btn|button|menu-item|ant-btn|ant-menu|ant-select|ant-input/.test(el.className));
+            }
+
+            function interactiveElements() {
+                return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                    .filter(isCandidate);
+            }
+
+            function findBySelector(selector) {
+                if (!selector) return null;
+                if (selector.startsWith("text=")) {
+                    const expected = selector.slice(5).trim();
+                    return interactiveElements().find((el) => getText(el).includes(expected) || getName(el, getText(el)).includes(expected)) ||
+                        Array.from(document.querySelectorAll("*")).find((el) => getText(el).includes(expected));
+                }
+                if (selector.startsWith("role=")) {
+                    const match = selector.match(/^role=([^\[]+)(?:\[name="([^"]+)"\])?/);
+                    const expectedRole = match?.[1]?.trim();
+                    const expectedName = match?.[2]?.trim();
+                    return interactiveElements().find((el) => {
+                        const text = getText(el);
+                        const name = getName(el, text);
+                        return roleOf(el) === expectedRole && (!expectedName || name.includes(expectedName) || text.includes(expectedName));
+                    });
+                }
+                try {
+                    return document.querySelector(selector);
+                } catch {
+                    return null;
+                }
+            }
+
+            const el = actOptions.index !== undefined
+                ? interactiveElements()[actOptions.index - 1]
+                : findBySelector(actOptions.selector);
+
+            if (!el) {
+                return { found: false };
+            }
+
+            el.scrollIntoView({ block: "center", inline: "center" });
+            const rect = el.getBoundingClientRect();
+            const style = window.getComputedStyle(el);
+            const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+            const enabled = !el.disabled && el.getAttribute("aria-disabled") !== "true";
+            const text = getText(el);
+            const name = getName(el, text);
+            const baseResult = {
+                found: true,
+                tagName: el.tagName,
+                role: roleOf(el),
+                name,
+                text,
+                visible,
+                enabled,
+                bbox: {
+                    x: Math.round(rect.x),
+                    y: Math.round(rect.y),
+                    width: Math.round(rect.width),
+                    height: Math.round(rect.height),
+                },
+            };
+
+            if (!visible || !enabled) {
+                return { ...baseResult, performed: false };
+            }
+
+            if (actOptions.action === "hover") {
+                el.dispatchEvent(new MouseEvent("mouseover", { bubbles: true }));
+                el.dispatchEvent(new MouseEvent("mouseenter", { bubbles: true }));
+                return { ...baseResult, performed: true, action: "hover" };
+            }
+
+            if (actOptions.action === "type") {
+                el.focus();
+                if ("value" in el) {
+                    el.value = actOptions.clear ? "" : el.value;
+                    el.value += actOptions.typeText;
+                } else if (el.isContentEditable) {
+                    el.textContent = actOptions.clear ? actOptions.typeText : `${el.textContent || ""}${actOptions.typeText}`;
+                } else {
+                    return { ...baseResult, performed: false, error: "Target is not typeable" };
+                }
+                el.dispatchEvent(new InputEvent("input", { bubbles: true, inputType: "insertText", data: actOptions.typeText }));
+                el.dispatchEvent(new Event("change", { bubbles: true }));
+                return { ...baseResult, performed: true, action: "type", value: "value" in el ? el.value : el.textContent };
+            }
+
+            el.click();
+            return { ...baseResult, performed: true, action: "click" };
+        }, {
+            index,
+            selector,
+            action,
+            typeText,
+            clear: Boolean(options.clear),
+        });
+
+        if (!result.found) {
+            throw new Error(index !== undefined ? `Interactive element index not found: ${index}` : `Element not found: ${selector}`);
+        }
+        if (!result.performed) {
+            throw new Error(result.error || `Element is not actionable: ${index ?? selector}`);
+        }
+
+        return {
+            acted: true,
+            action: result.action,
+            index,
+            selector,
+            target: {
+                frameId: targetFrame.frameId,
+                frameUrl: targetFrame.frame.url(),
+                matchedBy: targetFrame.matchedBy,
+            },
+            element: result,
+        };
+    }
+
+    async assert(options = {}) {
+        const targetFrame = await this._resolveObserveFrame(options);
+        const previousFrame = this._activeFrame;
+        this._activeFrame = targetFrame.frame === this.page.mainFrame() ? null : targetFrame.frame;
+
+        try {
+            const checks = {};
+            let passed = true;
+
+            if (options.selector) {
+                const elementResult = await this._checkElement({ selector: options.selector, expect: options.expect || {} });
+                checks.element = elementResult;
+                if (!elementResult.passed) passed = false;
+            }
+
+            if (options.urlContains) {
+                const currentUrl = this.page.url();
+                checks.urlContains = { expected: options.urlContains, actual: currentUrl, passed: currentUrl.includes(options.urlContains) };
+                if (!checks.urlContains.passed) passed = false;
+            }
+
+            if (options.textContains) {
+                const textResult = await this.safeEval((text) => {
+                    const bodyText = document.body?.innerText || "";
+                    return { expected: text, passed: bodyText.includes(text) };
+                }, options.textContains);
+                checks.textContains = textResult;
+                if (!textResult.passed) passed = false;
+            }
+
+            return {
+                passed,
+                target: {
+                    frameId: targetFrame.frameId,
+                    frameUrl: targetFrame.frame.url(),
+                    matchedBy: targetFrame.matchedBy,
+                },
+                checks,
+            };
+        } finally {
+            this._activeFrame = previousFrame;
+        }
+    }
+
+    async _resolveObserveFrame(options = {}) {
+        const frames = this.page.frames();
+        const mainFrame = this.page.mainFrame();
+
+        if (options.frameIndex !== undefined) {
+            const index = Number.parseInt(options.frameIndex, 10);
+            if (frames[index]) {
+                return { frame: frames[index], frameId: index === 0 ? "main" : `frame-${index}`, matchedBy: `frameIndex ${index}` };
+            }
+        }
+
+        if (options.frameUrlContains) {
+            const index = frames.findIndex((frame) => frame.url().includes(options.frameUrlContains));
+            if (index >= 0) {
+                return { frame: frames[index], frameId: index === 0 ? "main" : `frame-${index}`, matchedBy: `url contains "${options.frameUrlContains}"` };
+            }
+        }
+
+        if (options.frameContentContains) {
+            for (let i = 0; i < frames.length; i++) {
+                const matched = await frames[i].evaluate((text) =>
+                    document.body?.innerText?.includes(text) || false,
+                    options.frameContentContains
+                ).catch(() => false);
+                if (matched) {
+                    return { frame: frames[i], frameId: i === 0 ? "main" : `frame-${i}`, matchedBy: `body contains "${options.frameContentContains}"` };
+                }
+            }
+        }
+
+        const mainIndex = frames.indexOf(mainFrame);
+        return { frame: mainFrame, frameId: mainIndex <= 0 ? "main" : `frame-${mainIndex}`, matchedBy: "main" };
+    }
+
+    async _getFrameSummaries() {
+        const frames = this.page.frames();
+        const mainFrame = this.page.mainFrame();
+        const summaries = [];
+        for (let i = 0; i < frames.length; i++) {
+            const frame = frames[i];
+            const title = await frame.evaluate(() => document.title || "").catch(() => "");
+            summaries.push({
+                frameId: frame === mainFrame ? "main" : `frame-${i}`,
+                url: frame.url(),
+                title,
+                isMain: frame === mainFrame,
+            });
+        }
+        return summaries;
+    }
+
+    async _buildDomTree(frame, selector, depth) {
+        return frame.evaluate((rootSelector, maxDepth) => {
+            function attrsOf(el) {
+                const attrs = {};
+                for (const attr of Array.from(el.attributes || [])) {
+                    if (["id", "class", "role", "aria-label", "title", "placeholder", "href", "src", "data-testid"].includes(attr.name)) {
+                        attrs[attr.name] = attr.value.slice(0, 120);
+                    }
+                }
+                return attrs;
+            }
+
+            function directTextOf(el) {
+                return Array.from(el.childNodes || [])
+                    .filter((node) => node.nodeType === Node.TEXT_NODE)
+                    .map((node) => node.textContent.trim())
+                    .filter(Boolean)
+                    .join(" ")
+                    .slice(0, 120);
+            }
+
+            function build(el, currentDepth) {
+                if (!el || currentDepth > maxDepth) return null;
+                const tag = el.tagName?.toLowerCase();
+                if (!tag || ["script", "style", "path"].includes(tag)) return null;
+                const rect = el.getBoundingClientRect();
+                const node = {
+                    tag,
+                    attrs: attrsOf(el),
+                    text: directTextOf(el),
+                    visible: rect.width > 0 && rect.height > 0,
+                    children: [],
+                };
+                for (const child of Array.from(el.children || [])) {
+                    const childNode = build(child, currentDepth + 1);
+                    if (childNode) node.children.push(childNode);
+                }
+                return node;
+            }
+
+            return build(document.querySelector(rootSelector) || document.body, 0);
+        }, selector, depth).catch((err) => ({ error: err.message, tag: "error", attrs: {}, text: "", visible: false, children: [] }));
+    }
+
+    async _collectInteractiveElements(frame, frameId, maxElements) {
+        return frame.evaluate((currentFrameId, limit) => {
+            function cssEscape(value) {
+                if (window.CSS?.escape) return window.CSS.escape(value);
+                return String(value).replace(/["'\\]/g, "\\$&");
+            }
+
+            function getText(el) {
+                return (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 120);
+            }
+
+            function getName(el, text) {
+                return (
+                    el.getAttribute("aria-label") ||
+                    el.getAttribute("title") ||
+                    el.getAttribute("placeholder") ||
+                    el.getAttribute("alt") ||
+                    text ||
+                    ""
+                ).slice(0, 120);
+            }
+
+            function roleOf(el) {
+                const explicit = el.getAttribute("role");
+                if (explicit) return explicit;
+                const tag = el.tagName.toLowerCase();
+                if (tag === "button") return "button";
+                if (tag === "a") return "link";
+                if (["input", "textarea"].includes(tag)) return "textbox";
+                if (tag === "select") return "combobox";
+                return "generic";
+            }
+
+            function selectorCandidates(el, role, name, text) {
+                const selectors = [];
+                const testId = el.getAttribute("data-testid");
+                if (testId) selectors.push(`[data-testid="${cssEscape(testId)}"]`);
+                if (el.id) selectors.push(`#${cssEscape(el.id)}`);
+                if (role && role !== "generic" && name) selectors.push(`role=${role}[name="${name.replace(/"/g, "\\\"")}"]`);
+                if (text) selectors.push(`text=${text.replace(/"/g, "\\\"")}`);
+                const tag = el.tagName.toLowerCase();
+                const className = typeof el.className === "string" ? el.className.trim().split(/\s+/).filter(Boolean)[0] : "";
+                if (className) selectors.push(`${tag}.${cssEscape(className)}`);
+                selectors.push(tag);
+                return [...new Set(selectors)].slice(0, 5);
+            }
+
+            function isCandidate(el) {
+                const tag = el.tagName.toLowerCase();
+                return ["a", "button", "input", "select", "textarea", "summary"].includes(tag) ||
+                    el.getAttribute("role") ||
+                    el.getAttribute("tabindex") !== null ||
+                    el.onclick ||
+                    el.getAttribute("data-testid") ||
+                    (typeof el.className === "string" && /btn|button|menu-item|ant-btn|ant-menu|ant-select|ant-input/.test(el.className));
+            }
+
+            const viewportWidth = window.innerWidth || document.documentElement.clientWidth;
+            const viewportHeight = window.innerHeight || document.documentElement.clientHeight;
+            return Array.from(document.querySelectorAll("a,button,input,select,textarea,summary,[role],[tabindex],[data-testid],[class*='btn'],[class*='button'],[class*='menu-item'],[class*='ant-btn'],[class*='ant-menu'],[class*='ant-select'],[class*='ant-input']"))
+                .filter(isCandidate)
+                .slice(0, limit)
+                .map((el, idx) => {
+                    const rect = el.getBoundingClientRect();
+                    const style = window.getComputedStyle(el);
+                    const text = getText(el);
+                    const role = roleOf(el);
+                    const name = getName(el, text);
+                    const visible = rect.width > 0 && rect.height > 0 && style.visibility !== "hidden" && style.display !== "none";
+                    return {
+                        index: idx + 1,
+                        frameId: currentFrameId,
+                        tag: el.tagName.toLowerCase(),
+                        role,
+                        name,
+                        text,
+                        selectorCandidates: selectorCandidates(el, role, name, text),
+                        bbox: {
+                            x: Math.round(rect.x),
+                            y: Math.round(rect.y),
+                            width: Math.round(rect.width),
+                            height: Math.round(rect.height),
+                        },
+                        state: {
+                            visible,
+                            enabled: !el.disabled && el.getAttribute("aria-disabled") !== "true",
+                            inViewport: rect.bottom >= 0 && rect.right >= 0 && rect.top <= viewportHeight && rect.left <= viewportWidth,
+                        },
+                    };
+                });
+        }, frameId, maxElements).catch(() => []);
+    }
+
     /**
      * 步骤分发
      */
     async _dispatchStep(step, context) {
         switch (step.type) {
+            case "observe":      return this.observe(step);
+            case "act":          return this.act(step);
+            case "assert":       return this.assert(step);
             case "navigate":     return this._navigate(step);
             case "screenshot":   return this._screenshot(step, context);
             case "compare":      return this._compare(step, context);
@@ -649,7 +1079,7 @@ export class BrowserEngine {
  * 动态加载 puppeteer-core，从共享缓存目录加载，缺失时自动安装
  */
 async function loadPuppeteer() {
-    const { ensureSharedDeps, loadFromShared } = await import("./shared-deps.js");
+    const { ensureCoreDeps, loadFromShared } = await import("./shared-deps.js");
 
     // 1. 尝试从项目本地 node_modules 加载（开发环境或已手动安装）
     try {
@@ -659,8 +1089,8 @@ async function loadPuppeteer() {
         // 本地未安装
     }
 
-    // 2. 确保共享缓存已安装，然后从共享目录加载
-    await ensureSharedDeps();
+    // 2. observe/act/assert 主链路只需要 puppeteer-core
+    await ensureCoreDeps();
 
     try {
         return loadFromShared("puppeteer-core");

package/lib/shared-deps.js

@@ -1,9 +1,8 @@
 /**
  * 共享依赖加载器
  *
- * 浏览器自动化依赖（puppeteer-core, pixelmatch, pngjs, sharp）
- * 安装到 ~/.szcd-mcp/deps/node_modules/，所有项目共享复用。
- * 首次使用时自动安装，后续直接加载。
+ * 浏览器自动化依赖安装到 ~/.szcd-mcp/deps/node_modules/，所有项目共享复用。
+ * 主链路 observe/act/assert 只安装 puppeteer-core；视觉对比按需安装 pixelmatch/pngjs/sharp。
  */
 
 import { createRequire } from "node:module";
@@ -14,11 +13,14 @@ import fs from "node:fs";
 /** 共享缓存目录 */
 const SHARED_DEPS_DIR = path.join(homedir(), ".szcd-mcp", "deps");
 
-/** 需要共享安装的包列表 */
-const PACKAGES = ["puppeteer-core", "pixelmatch", "pngjs", "sharp"];
+/** 核心浏览器自动化依赖 */
+const CORE_PACKAGES = ["puppeteer-core"];
 
-/** 标记文件，存在表示依赖已安装 */
-const INSTALLED_MARKER = path.join(SHARED_DEPS_DIR, ".installed");
+/** 视觉对比依赖 */
+const VISUAL_COMPARE_PACKAGES = ["pixelmatch", "pngjs", "sharp"];
+
+/** 兼容旧导出 */
+const PACKAGES = [...CORE_PACKAGES, ...VISUAL_COMPARE_PACKAGES];
 
 /**
  * 从共享缓存目录加载模块
@@ -30,27 +32,9 @@ export function loadFromShared(moduleName) {
     return require_(moduleName);
 }
 
-/**
- * 确保共享依赖已安装，未安装则自动安装
- * @returns {Promise<void>}
- */
-export async function ensureSharedDeps() {
-    // 检查标记文件
-    if (fs.existsSync(INSTALLED_MARKER)) {
-        // 快速验证：puppeteer-core 目录是否存在
-        const pcoreDir = path.join(SHARED_DEPS_DIR, "node_modules", "puppeteer-core");
-        if (fs.existsSync(pcoreDir)) {
-            return; // 已安装
-        }
-    }
-
-    process.stderr.write("[shared-deps] 首次使用浏览器测试功能，正在安装共享依赖...\n");
-    process.stderr.write(`[shared-deps] 安装目录: ${SHARED_DEPS_DIR}\n`);
-
-    // 确保目录存在
+function ensurePackageJson() {
     fs.mkdirSync(SHARED_DEPS_DIR, { recursive: true });
 
-    // 初始化 package.json（如果不存在）
     const pkgPath = path.join(SHARED_DEPS_DIR, "package.json");
     if (!fs.existsSync(pkgPath)) {
         fs.writeFileSync(pkgPath, JSON.stringify({
@@ -59,39 +43,95 @@ export async function ensureSharedDeps() {
             private: true,
         }, null, 2));
     }
+}
+
+function isPackageInstalled(packageName) {
+    try {
+        const require_ = createRequire(path.join(SHARED_DEPS_DIR, "node_modules", "_"));
+        require_.resolve(packageName);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function installPackages(packages, label) {
+    const missing = packages.filter((packageName) => !isPackageInstalled(packageName));
+    if (missing.length === 0) return;
+
+    process.stderr.write(`[shared-deps] 正在安装${label}: ${missing.join(" ")}\n`);
+    process.stderr.write(`[shared-deps] 安装目录: ${SHARED_DEPS_DIR}\n`);
+
+    ensurePackageJson();
 
-    // 安装依赖
     const { execSync } = await import("node:child_process");
-    const pkgList = PACKAGES.join(" ");
-    const mirrorFlag = "--sharp_binary_host=https://npmmirror.com/mirrors/sharp";
-    const registryFlag = "--registry=https://npmmirror.com";
+    const pkgList = missing.join(" ");
+    const registryFlags = [
+        "--registry=https://registry.npmmirror.com",
+        "--@img:registry=https://registry.npmmirror.com",
+    ];
+    const speedFlags = [
+        "--prefer-offline",
+        "--no-audit",
+        "--no-fund",
+        "--omit=dev",
+        "--package-lock=false",
+        "--loglevel=warn",
+    ];
+    const sharpFlags = missing.includes("sharp") ? [
+        "--sharp_binary_host=https://npmmirror.com/mirrors/sharp",
+        "--sharp_libvips_binary_host=https://npmmirror.com/mirrors/sharp-libvips",
+    ] : [];
+    const installFlags = [...registryFlags, ...speedFlags, ...sharpFlags].join(" ");
 
     try {
-        execSync(`npm install ${registryFlag} ${mirrorFlag} ${pkgList}`, {
+        execSync(`npm install ${installFlags} ${pkgList}`.trim(), {
             cwd: SHARED_DEPS_DIR,
             stdio: "inherit",
             timeout: 180000,
         });
     } catch (err) {
         throw new Error(
-            `浏览器测试依赖安装失败。请手动执行：\n` +
-            `  cd ${SHARED_DEPS_DIR} && npm install ${pkgList}\n` +
+            `${label}安装失败。请手动执行：\n` +
+            `  cd ${SHARED_DEPS_DIR} && npm install ${installFlags} ${pkgList}\n` +
             `原始错误：${err.message}`
         );
     }
 
-    // 写入标记文件
-    fs.writeFileSync(INSTALLED_MARKER, new Date().toISOString());
-    process.stderr.write("[shared-deps] 共享依赖安装完成！后续所有项目将复用此安装。\n");
+    process.stderr.write(`[shared-deps] ${label}安装完成。\n`);
+}
+
+export async function ensureCoreDeps() {
+    await installPackages(CORE_PACKAGES, "浏览器核心依赖");
+}
+
+export async function ensureVisualCompareDeps() {
+    await ensureCoreDeps();
+    await installPackages(VISUAL_COMPARE_PACKAGES, "视觉对比依赖");
+}
+
+/**
+ * 确保全部共享依赖已安装，保留给旧调用兼容。
+ * @returns {Promise<void>}
+ */
+export async function ensureSharedDeps() {
+    await ensureVisualCompareDeps();
+}
+
+/**
+ * 检查核心依赖是否已安装
+ * @returns {boolean}
+ */
+export function isCoreDepsInstalled() {
+    return CORE_PACKAGES.every(isPackageInstalled);
 }
 
 /**
- * 检查共享依赖是否已安装
+ * 检查全部共享依赖是否已安装
  * @returns {boolean}
  */
 export function isSharedDepsInstalled() {
-    return fs.existsSync(INSTALLED_MARKER) &&
-        fs.existsSync(path.join(SHARED_DEPS_DIR, "node_modules", "puppeteer-core"));
+    return PACKAGES.every(isPackageInstalled);
 }
 
-export { SHARED_DEPS_DIR, PACKAGES };
+export { SHARED_DEPS_DIR, PACKAGES, CORE_PACKAGES, VISUAL_COMPARE_PACKAGES };

package/lib/visual-compare.js

@@ -15,7 +15,7 @@
 
 import fs from "node:fs";
 import path from "node:path";
-import { ensureSharedDeps, loadFromShared } from "./shared-deps.js";
+import { ensureVisualCompareDeps, loadFromShared } from "./shared-deps.js";
 
 /**
  * 全局视觉对比
@@ -27,8 +27,8 @@ import { ensureSharedDeps, loadFromShared } from "./shared-deps.js";
  * @returns {Promise<object>} 对比结果
  */
 export async function compareDesign(screenshotPath, designImagePath, options = {}) {
-    // 确保共享依赖已安装，然后加载
-    await ensureSharedDeps();
+    // 视觉对比才安装 pixelmatch/pngjs/sharp，避免 observe 主链路被重依赖阻塞
+    await ensureVisualCompareDeps();
     const sharp = loadFromShared("sharp");
     const pixelmatch = loadFromShared("pixelmatch");
     const { PNG } = loadFromShared("pngjs");