@szc-ft/mcp-szcd-client 0.27.1 → 0.27.3

package/opencode-extension/skills/local-browser-test/local-browser-executor.cjs

@@ -1,24 +1,41 @@
 #!/usr/bin/env node
 /**
- * local-browser-executor.js - 本地浏览器自动化执行器
+ * local-browser-executor.cjs - 本地浏览器自动化执行器
  *
  * 功能：
- *   --action diagnose    全面诊断（JS错误、网络请求、API检查、资源加载）
- *   --action list-pages  列出所有标签页
- *   --action screenshot  截图
- *   --action api-check   检查 API 请求状态
- *   --action plan        执行测试计划 JSON
+ *   --action diagnose       全面诊断（JS错误、网络请求、API检查、资源加载）
+ *   --action list-pages     列出所有标签页
+ *   --action screenshot     截图（支持 --full-page 滚动截图）
+ *   --action api-check      检查 API 请求状态
+ *   --action snapshot       结构化 DOM 快照（类似 browser-use take_snapshot）
+ *   --action interact       智能交互（支持 text=/role= 选择器，类似 Playwright）
+ *   --action perf           性能指标采集（FCP/LCP/CLS/TBT）
+ *   --action watch          持续监控模式（定时截图+错误检测）
+ *   --action plan           执行测试计划 JSON
  *
  * 连接方式：
- *   --cdp-url http://localhost:9222  (默认自动检测 9222)
- *   --auto-detect                    自动检测 Chrome/Edge 进程
+ *   --cdp-url http://localhost:9222  (默认 9222)
  *
  * 通用参数：
- *   --url <url>          目标页面 URL
- *   --url-contains <s>   按关键词查找已打开的页面
- *   --wait <ms>          额外等待时间（默认 5000）
- *   --output <path>      结果输出文件
- *   --output-dir <dir>   截图/产物输出目录
+ *   --url <url>             目标页面 URL
+ *   --url-contains <s>      按关键词查找已打开的页面
+ *   --wait <ms>             额外等待时间（默认 5000）
+ *   --output <path>         结果输出文件
+ *   --output-dir <dir>      截图/产物输出目录
+ *
+ * snapshot 参数：
+ *   --selector <css>        快照根元素（默认 body）
+ *   --depth <n>             DOM 深度（默认 5）
+ *
+ * interact 参数：
+ *   --click <selector>      点击元素（支持 text=、role=、CSS）
+ *   --type <text>           输入文本（配合 --click 定位输入框）
+ *   --hover <selector>      悬停元素
+ *   --scroll <direction>    滚动（up/down/left/right，配合 --scroll-amount）
+ *
+ * watch 参数：
+ *   --interval <ms>         监控间隔（默认 5000）
+ *   --max-rounds <n>        最大轮数（默认 60）
  */
 
 const puppeteer = require('puppeteer-core');
@@ -65,7 +82,41 @@ function checkCDP(url) {
 }
 
 async function findPage(browser) {
-  const pages = await browser.pages();
+  let pages;
+  try {
+    pages = await Promise.race([
+      browser.pages(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('pages() timeout')), 8000)),
+    ]);
+  } catch {
+    // browser.pages() 超时，尝试用 targets() 找到目标再 .page()
+    try {
+      const targets = browser.targets();
+      let matchTarget = null;
+      if (URL_CONTAINS) {
+        matchTarget = targets.find(t => t.type() === 'page' && t.url().includes(URL_CONTAINS));
+      }
+      if (TARGET_URL && !matchTarget) {
+        matchTarget = targets.find(t => t.type() === 'page' && t.url().includes(TARGET_URL));
+      }
+      if (!matchTarget) {
+        matchTarget = targets.find(t => t.type() === 'page' && !t.url().startsWith('about:') && !t.url().startsWith('devtools:'));
+      }
+      if (matchTarget) {
+        const page = await matchTarget.page();
+        if (page) return page;
+      }
+    } catch (e) {
+      log(`[WARN] targets() 回退失败: ${e.message}`);
+    }
+    // 最终回退
+    if (TARGET_URL) {
+      const page = await browser.newPage();
+      await page.goto(TARGET_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
+      return page;
+    }
+    return await browser.newPage();
+  }
   if (TARGET_URL) {
     for (const p of pages) {
       if (p.url().includes(TARGET_URL) || p.url() === TARGET_URL) return p;
@@ -90,7 +141,27 @@ async function findPage(browser) {
 
 // ===== Action: list-pages =====
 async function listPages(browser) {
-  const pages = await browser.pages();
+  log('[INFO] 获取标签页列表...');
+  // browser.pages() 在大量标签页时可能卡住，用 CDP 直接获取
+  let pages;
+  try {
+    pages = await Promise.race([
+      browser.pages(),
+      new Promise((_, reject) => setTimeout(() => reject(new Error('pages() timeout')), 5000)),
+    ]);
+  } catch {
+    // 回退：通过 CDP Target API 获取
+    const client = await browser.target().createCDPSession();
+    const { targetInfos } = await client.send('Target.getTargets');
+    log(`[INFO] CDP 回退: 共 ${targetInfos.filter(t => t.type === 'page').length} 个标签页`);
+    for (const t of targetInfos.filter(t => t.type === 'page')) {
+      log(`  ${t.url}`);
+      if (t.title) log(`    title: ${t.title}`);
+    }
+    try { await client.detach(); } catch {}
+    return { total: targetInfos.filter(t => t.type === 'page').length };
+  }
+  log(`[INFO] 共 ${pages.length} 个标签页`);
   const result = [];
   for (let i = 0; i < pages.length; i++) {
     const p = pages[i];
@@ -365,6 +436,246 @@ async function executePlan(browser) {
   return { steps: results, summary };
 }
 
+// ===== 智能选择器解析（融合 Playwright 风格） =====
+async function smartResolve(pageOrFrame, selector) {
+  if (!selector) return null;
+  if (selector.startsWith('text=')) {
+    const text = selector.slice(5).replace(/^["']|["']$/g, '');
+    return pageOrFrame.evaluateHandle(t => {
+      const all = document.querySelectorAll('a, button, [role="button"], input, [class*="btn"], span, div, p');
+      return Array.from(all).find(el => el.textContent?.includes(t) && el.offsetHeight > 0) || null;
+    }, text);
+  }
+  if (selector.startsWith('role=')) {
+    return pageOrFrame.$(`[role="${selector.slice(5)}"]`);
+  }
+  if (selector.startsWith('~')) {
+    return pageOrFrame.$(`[class*="${selector.slice(1).replace(/^\./, '')}"]`);
+  }
+  return pageOrFrame.$(selector);
+}
+
+// ===== Action: snapshot (结构化 DOM 快照) =====
+async function snapshot(browser) {
+  const page = await findPage(browser);
+  const selector = getArg('selector', 'body');
+  const maxDepth = parseInt(getArg('depth', '5'), 10);
+  log(`[PAGE] ${page.url()}`);
+
+  const tree = await page.evaluate((rootSel, depth) => {
+    function buildTree(el, d) {
+      if (d > depth || !el) return null;
+      const tag = el.tagName?.toLowerCase();
+      if (!tag || ['script','style','svg','path'].includes(tag)) return null;
+      const attrs = {};
+      for (const a of (el.attributes || [])) {
+        if (['id','class','href','src','role','aria-label','data-testid'].includes(a.name)) {
+          attrs[a.name] = a.value.substring(0, 100);
+        }
+      }
+      // 直接文本内容
+      let text = '';
+      for (const node of el.childNodes) {
+        if (node.nodeType === 3) text += node.textContent.trim();
+      }
+      // 子元素
+      const children = [];
+      for (const child of el.children) {
+        const childTree = buildTree(child, d + 1);
+        if (childTree) children.push(childTree);
+      }
+      // 可交互性
+      const interactive = ['a','button','input','select','textarea'].includes(tag) ||
+        el.getAttribute('role') === 'button' || el.onclick || el.style.cursor === 'pointer';
+      // 可见性
+      const rect = el.getBoundingClientRect();
+      const visible = rect.width > 0 && rect.height > 0;
+      return { tag, attrs, text: text.substring(0, 80), children, interactive, visible, depth: d };
+    }
+    const root = document.querySelector(rootSel) || document.body;
+    return buildTree(root, 0);
+  }, selector, maxDepth);
+
+  // 打印树形结构
+  function printTree(node, indent = '') {
+    if (!node) return;
+    const cls = node.attrs.class ? `.${node.attrs.class.split(' ')[0].substring(0, 30)}` : '';
+    const id = node.attrs.id ? `#${node.attrs.id}` : '';
+    const role = node.attrs.role ? `[role=${node.attrs.role}]` : '';
+    const interactive = node.interactive ? ' \u{1F517}' : '';
+    const vis = node.visible ? '' : ' [hidden]';
+    const txt = node.text ? ` "${node.text.substring(0, 40)}"` : '';
+    log(`${indent}<${node.tag}${id}${cls}${role}>${txt}${interactive}${vis}`);
+    for (const child of (node.children || [])) {
+      printTree(child, indent + '  ');
+    }
+  }
+  log('\n========== DOM 快照 ==========');
+  printTree(tree);
+
+  if (OUTPUT) {
+    fs.writeFileSync(OUTPUT, JSON.stringify(tree, null, 2));
+    log(`\n[OK] 结果已保存: ${OUTPUT}`);
+  }
+  return tree;
+}
+
+// ===== Action: interact (智能交互) =====
+async function interact(browser) {
+  const page = await findPage(browser);
+  log(`[PAGE] ${page.url()}`);
+
+  const clickSel = getArg('click', null);
+  const typeText = getArg('type', null);
+  const hoverSel = getArg('hover', null);
+  const scrollDir = getArg('scroll', null);
+  const scrollAmt = parseInt(getArg('scroll-amount', '300'), 10);
+
+  if (clickSel) {
+    const el = await smartResolve(page, clickSel);
+    if (el) {
+      await el.click();
+      log(`[OK] 点击: ${clickSel}`);
+      await new Promise(r => setTimeout(r, 1000));
+    } else {
+      log(`[FAIL] 未找到元素: ${clickSel}`);
+    }
+  }
+  if (typeText) {
+    const target = clickSel ? await smartResolve(page, clickSel) : await page.$('input:focus, textarea:focus');
+    if (target) {
+      await target.type(typeText, { delay: 50 });
+      log(`[OK] 输入: "${typeText}"`);
+    } else {
+      log(`[FAIL] 未找到输入目标`);
+    }
+  }
+  if (hoverSel) {
+    const el = await smartResolve(page, hoverSel);
+    if (el) {
+      await el.hover();
+      log(`[OK] 悬停: ${hoverSel}`);
+    }
+  }
+  if (scrollDir) {
+    const dx = scrollDir === 'left' ? -scrollAmt : scrollDir === 'right' ? scrollAmt : 0;
+    const dy = scrollDir === 'up' ? -scrollAmt : scrollDir === 'down' ? scrollAmt : 0;
+    await page.evaluate(({ dx, dy }) => window.scrollBy(dx, dy), { dx, dy });
+    log(`[OK] 滚动: ${scrollDir} ${scrollAmt}px`);
+  }
+
+  // 交互后截图
+  if (hasFlag('screenshot-after')) {
+    ensureDir(OUTPUT_DIR);
+    const fp = path.join(OUTPUT_DIR, 'after-interact.png');
+    await page.screenshot({ path: fp });
+    log(`[OK] 截图: ${fp}`);
+  }
+}
+
+// ===== Action: perf (性能指标) =====
+async function perf(browser) {
+  const page = await findPage(browser);
+  log(`[PAGE] ${page.url()}`);
+
+  // 收集性能指标
+  const perfMetrics = await page.evaluate(() => {
+    const perf = performance.getEntriesByType('navigation')[0];
+    const paint = performance.getEntriesByType('paint');
+    const fcp = paint.find(p => p.name === 'first-contentful-paint');
+    // LCP 通过 PerformanceObserver 获取
+    const resources = performance.getEntriesByType('resource');
+    return {
+      // 导航时间
+      dns: perf?.domainEnd - perf?.domainStart || 0,
+      tcp: perf?.connectEnd - perf?.connectStart || 0,
+      ttfb: perf?.responseStart - perf?.requestStart || 0,
+      domReady: perf?.domContentLoadedEventEnd - perf?.startTime || 0,
+      loadComplete: perf?.loadEventEnd - perf?.startTime || 0,
+      // 绘制
+      fcp: fcp?.startTime || null,
+      // 资源统计
+      totalResources: resources.length,
+      totalTransferSize: resources.reduce((sum, r) => sum + (r.transferSize || 0), 0),
+      slowResources: resources.filter(r => r.duration > 1000).map(r => ({
+        name: r.name.split('/').pop(), duration: Math.round(r.duration), size: r.transferSize
+      })),
+    };
+  });
+
+  // Web Vitals (通过 CDP)
+  let webVitals = {};
+  try {
+    const client = await page.target().createCDPSession();
+    await client.send('Performance.enable');
+    const metrics = await client.send('Performance.getMetrics');
+    const m = {};
+    metrics.metrics.forEach(item => { m[item.name] = item.value; });
+    webVitals = {
+      layoutCount: m.LayoutCount || 0,
+      recalcCount: m.RecalcLayoutCount || 0,
+      jsHeapUsed: Math.round((m.JSHeapUsedSize || 0) / 1024 / 1024) + 'MB',
+      jsHeapTotal: Math.round((m.JSHeapTotalSize || 0) / 1024 / 1024) + 'MB',
+      taskDuration: (m.TaskDuration || 0).toFixed(2) + 's',
+    };
+    await client.send('Performance.disable');
+    client.detach();
+  } catch {}
+
+  log('\n========== 性能指标 ==========');
+  log(`DNS: ${Math.round(perfMetrics.dns)}ms`);
+  log(`TCP: ${Math.round(perfMetrics.tcp)}ms`);
+  log(`TTFB: ${Math.round(perfMetrics.ttfb)}ms`);
+  log(`DOM Ready: ${Math.round(perfMetrics.domReady)}ms`);
+  log(`Load Complete: ${Math.round(perfMetrics.loadComplete)}ms`);
+  log(`FCP: ${perfMetrics.fcp ? Math.round(perfMetrics.fcp) + 'ms' : 'N/A'}`);
+  log(`\n资源总数: ${perfMetrics.totalResources}`);
+  log(`传输总量: ${Math.round(perfMetrics.totalTransferSize / 1024)}KB`);
+  if (perfMetrics.slowResources.length > 0) {
+    log(`\n慢资源 (>1s):`);
+    perfMetrics.slowResources.forEach(r => log(`  ${r.duration}ms ${r.name} (${Math.round((r.size||0)/1024)}KB)`));
+  }
+  if (Object.keys(webVitals).length > 0) {
+    log('\n========== Chrome 内部指标 ==========');
+    Object.entries(webVitals).forEach(([k, v]) => log(`  ${k}: ${v}`));
+  }
+
+  return { perfMetrics, webVitals };
+}
+
+// ===== Action: watch (持续监控) =====
+async function watch(browser) {
+  const page = await findPage(browser);
+  const interval = parseInt(getArg('interval', '5000'), 10);
+  const maxRounds = parseInt(getArg('max-rounds', '60'), 10);
+  ensureDir(OUTPUT_DIR);
+  log(`[PAGE] ${page.url()}`);
+  log(`[WATCH] 间隔=${interval}ms, 最大轮数=${maxRounds}`);
+
+  const errors = [];
+  page.on('pageerror', err => errors.push({ time: new Date().toISOString(), error: err.message }));
+  page.on('console', msg => {
+    if (msg.type() === 'error') errors.push({ time: new Date().toISOString(), type: 'console', text: msg.text() });
+  });
+
+  for (let i = 1; i <= maxRounds; i++) {
+    const ts = new Date().toISOString().replace(/[:.]/g, '-');
+    const fp = path.join(OUTPUT_DIR, `watch-${String(i).padStart(3, '0')}-${ts}.png`);
+    await page.screenshot({ path: fp });
+    const errCount = errors.length;
+    log(`[${i}/${maxRounds}] 截图 | 累计错误: ${errCount}`);
+    if (errCount > 0 && i === 1) {
+      errors.forEach(e => log(`  [ERROR] ${e.error || e.text}`));
+    }
+    await new Promise(r => setTimeout(r, interval));
+  }
+
+  log(`\n========== 监控结束 ==========`);
+  log(`总轮数: ${maxRounds}, 累计错误: ${errors.length}`);
+  errors.forEach(e => log(`  [${e.time}] ${e.error || e.text}`));
+  return { rounds: maxRounds, errors };
+}
+
 // ===== 主入口 =====
 (async () => {
   // 检测 CDP
@@ -378,7 +689,23 @@ async function executePlan(browser) {
   }
   log(`[CDP] ${cdpInfo.Browser || 'connected'} (${CDP_URL})`);
 
-  const browser = await puppeteer.connect({ browserURL: CDP_URL, defaultViewport: null });
+  // 获取 WebSocket URL
+  let wsUrl;
+  try {
+    const versionData = await new Promise((resolve, reject) => {
+      const req = http.get(CDP_URL + '/json/version', { timeout: 3000 }, res => {
+        let d = ''; res.on('data', c => d += c); res.on('end', () => resolve(JSON.parse(d)));
+      });
+      req.on('error', reject);
+    });
+    wsUrl = versionData.webSocketDebuggerUrl;
+  } catch {}
+
+  const browser = await Promise.race([
+    puppeteer.connect({ browserWSEndpoint: wsUrl || CDP_URL, defaultViewport: null }),
+    new Promise((_, reject) => setTimeout(() => reject(new Error('CDP WebSocket 连接超时 (10s)')), 10000)),
+  ]);
+  log('[OK] 浏览器已连接');
 
   let result;
   switch (ACTION) {
@@ -386,10 +713,15 @@ async function executePlan(browser) {
     case 'diagnose': result = await diagnose(browser); break;
     case 'screenshot': result = await screenshot(browser); break;
     case 'api-check': result = await apiCheck(browser); break;
+    case 'snapshot': result = await snapshot(browser); break;
+    case 'interact': result = await interact(browser); break;
+    case 'perf': result = await perf(browser); break;
+    case 'watch': result = await watch(browser); break;
     case 'plan': result = await executePlan(browser); break;
     default: log(`[ERROR] 未知 action: ${ACTION}`);
   }
 
   browser.disconnect();
   log('\n[DONE]');
+  process.exit(0);
 })();

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.27.1",
+    "version": "0.27.3",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",

package/qwen-extension/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/qwen-extension/qwen-extension.json

@@ -1,6 +1,6 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.27.1",
+    "version": "0.27.3",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {