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

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.2",
     "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.2",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {

package/qwen-extension/skills/local-browser-test/SKILL.md

@@ -17,6 +17,24 @@ compatibility:
 - "功能测试"、"能不能正常用"
 - "检查页面"、"页面渲染"
 
+## 主链路定位
+
+local-browser-test 的长期主链路是：
+
+```
+Agent / SKILL.md
+  → szcd-mcp-client/local-browser-executor.js
+  → lib/browser-engine.js
+  → puppeteer-core + CDP
+  → 用户真实 Chrome / Edge
+```
+
+目标是在用户真实登录态/真实微前端环境中形成 browser-use + Playwright 结合体：
+- browser-use 侧：`observe → act → observe`，通过结构化页面观察和交互元素 index 支持自主任务执行。
+- Playwright 侧：locator、actionability、assert、plan 报告逐步收敛到 `BrowserEngine`。
+
+`standard-skill/local-browser-test/local-browser-executor.cjs` 是过渡兼容执行器；新增稳定能力优先进入 `szcd-mcp-client/lib/browser-engine.js` 和根目录 `local-browser-executor.js`。
+
 ## 浏览器模式
 
 支持两种模式，执行器自动检测优先使用 connect：
@@ -60,14 +78,17 @@ AI 直接构造测试计划 JSON：
 
 | type | 功能 | 参数 | 返回 |
 |------|------|------|------|
+| observe | 结构化观察 | `selector`, `depth`, `frameContentContains`, `maxInteractiveElements` | `{ frames, tree, interactiveElements[] }` |
+| act | 按 index/selector 交互 | `index` 或 `selector/click/hover`, `typeText`, `clear`, `frameContentContains` | `{ acted, action, element }` |
+| assert | 轻量断言 | `selector`, `expect`, `urlContains`, `textContains` | `{ passed, checks }` |
 | navigate | 导航到 URL | `url`, `waitUntil` | `{ url, title, loadTime }` |
 | screenshot | 页面截图 | `fullPage`, `clip`, `filename` | `{ filepath, width, height }` |
 | compare | 设计稿对比 | `designImagePath`, `threshold`, `regions[]` | `{ fidelity, diffPixels, diffImagePath, regions[] }` |
-| click | 点击元素 | `selector`, `waitForNavigation` | `{ clicked, tagName }` |
-| type | 输入文本 | `selector`, `text`, `clear` | `{ typed, value }` |
+| click | 点击元素（兼容） | `selector`, `waitForNavigation` | `{ clicked, tagName }` |
+| type | 输入文本（兼容） | `selector`, `text`, `clear` | `{ typed, value }` |
 | waitFor | 等待条件 | `selector` 或 `url`, `timeout` | `{ matched, waited }` |
 | evaluate | 执行 JS | `expression` | `{ result }` |
-| checkElement | 元素断言 | `selector`, `expect: {visible, minCount, maxCount, hasText}` | `{ passed, checks, elementCount }` |
+| checkElement | 元素断言（兼容） | `selector`, `expect: {visible, minCount, maxCount, hasText}` | `{ passed, checks, elementCount }` |
 | findPage | 查找已打开的标签页 | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` | `{ found, url, title, totalPages }` |
 | findFrame | 查找微前端 iframe | `urlIncludes` 或 `urlRegex` 或 `titleIncludes` 或 `contentIncludes` 或 `frameIndex` | `{ found, frameUrl, matchedBy, totalFrames }` |
 | loginWait | 等待 SSO 登录完成 | `loginSelector`, `timeout`, `interval` | `{ loggedIn, elapsed, currentUrl }` |
@@ -141,15 +162,15 @@ AI 直接构造测试计划 JSON：
 wujie 微前端子应用渲染在 blob URL iframe 中，**坐标点击无法到达 iframe 内容**。
 
 ```json
-{ "type": "findFrame", "contentIncludes": "知识采编" }
-{ "type": "click", "selector": "a.edit-btn" }
-{ "type": "checkElement", "selector": "~.editKnowledge", "expect": { "minCount": 1 } }
+{ "type": "observe", "frameContentContains": "知识采编", "depth": 5, "maxInteractiveElements": 80 }
+{ "type": "act", "index": 3, "frameContentContains": "知识采编" }
+{ "type": "assert", "selector": "~.editKnowledge", "expect": { "minCount": 1 } }
 ```
 
-- `findFrame` 支持 `urlIncludes`、`titleIncludes`、`contentIncludes` 多种发现方式
-- 优先用 `contentIncludes`（按页面文字内容查找），不依赖 URL/端口
-- `findFrame` 后，后续所有步骤自动在 iframe 内执行
-- iframe 内的 click 使用 `evaluate()` 触发 DOM click，不依赖坐标
+- 优先用 `observe` 发现 iframe 内的 `interactiveElements[index]`，再用 `act.index` 操作，不要重新猜 selector
+- `observe/act` 支持 `frameUrlContains`、`frameContentContains`、`frameIndex` 多种发现方式
+- 优先用 `frameContentContains`（按页面文字内容查找），不依赖 URL/端口
+- iframe 内的 act 使用 DOM 事件触发，不依赖坐标
 
 ### CSS Modules 哈希类名
 项目使用 CSS Modules，类名会被哈希化（如 `editKnowledge___ynQgI`）。
@@ -192,7 +213,41 @@ wujie 微前端子应用渲染在 blob URL iframe 中，**坐标点击无法到
 
 ## 执行命令
 
-### 快速诊断（最常用）
+### 结构化观察（主链路起点）
+```bash
+node {client_path}/local-browser-executor.js \
+  --action observe \
+  --url-contains "platform.aicityos.com" \
+  --frame-content-contains "数据集目录" \
+  --depth 5 \
+  --output /tmp/browser-observe.json
+```
+
+`observe` 输出 `frames`、`tree`、`interactiveElements[index]`、`selectorCandidates`、`bbox`、`state`。Agent 后续应优先使用 `index` 调用 `act`，不要从 DOM 树重新猜 selector。直接 `--action observe` 默认只连接用户已启动的真实浏览器 CDP；如确需无 CDP 时启动 headless 回退，追加 `--allow-launch`。
+
+### 观察后按 index 交互（主链路闭环）
+```bash
+node {client_path}/local-browser-executor.js \
+  --action act \
+  --url-contains "platform.aicityos.com" \
+  --frame-content-contains "数据集目录" \
+  --index 3 \
+  --observe-after \
+  --output /tmp/browser-act-observe.json
+```
+
+### 轻量 DOM 断言
+```bash
+node {client_path}/local-browser-executor.js \
+  --action assert \
+  --url-contains "platform.aicityos.com" \
+  --selector ".ant-table" \
+  --expect-visible \
+  --min-count 1 \
+  --output /tmp/browser-assert.json
+```
+
+### 快速诊断（过渡兼容）
 ```bash
 NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
   --action diagnose \
@@ -232,16 +287,98 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
   --output /tmp/browser-test-result.json
 ```
 
+### DOM 快照（结构化页面树，类似 browser-use take_snapshot）
+```bash
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action snapshot \
+  --url-contains "platform.aicityos.com" \
+  --depth 4 \
+  --selector ".page-container"
+```
+输出示例：
+```
+<div.page-container>
+  <section.page-layout>
+    <header.page-header>
+      <div.page-header-left> <div.logo>
+    <section.h-box>
+      <aside.ant-layout-sider> 🔗
+      <main.ant-layout-content>
+        <div.layout-wrap>
+```
+
+### 智能交互（支持 text=、role=、~ 选择器，类似 Playwright）
+```bash
+# 点击包含“构建”文本的按钮
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action interact \
+  --url-contains "jenkins" \
+  --click "text=Build"
+
+# 在输入框中输入文本
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action interact \
+  --click "#search-input" \
+  --type "hello world"
+
+# 悬停 + 截图
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action interact \
+  --hover "~ant-menu-item" \
+  --screenshot-after
+
+# 滚动页面
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action interact \
+  --scroll down --scroll-amount 500
+```
+选择器语法：
+- `text=Build` → 按文本内容查找（类似 Playwright text selector）
+- `role=button` → 按 ARIA role 查找
+- `~ant-menu-item` → CSS class 模糊匹配（`[class*="ant-menu-item"]`）
+- `.my-class` → 精确 CSS 选择器
+
+### 性能指标采集（FCP/TTFB/资源统计）
+```bash
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action perf \
+  --url-contains "platform.aicityos.com"
+```
+
+### 持续监控模式（定时截图 + 错误检测）
+```bash
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action watch \
+  --url-contains "platform.aicityos.com" \
+  --interval 5000 \
+  --max-rounds 60 \
+  --output-dir /tmp/browser-watch
+```
+
 ### 可选参数
 
 - `--cdp-url http://localhost:9222`：CDP 地址（默认 9222）
 - `--url <url>`：目标页面 URL（不存在则导航）
 - `--url-contains <keyword>`：按关键词查找已打开的页面
+- `--frame-url-contains <keyword>`：observe 时按 iframe URL 片段匹配目标 frame
+- `--frame-content-contains <keyword>`：observe 时按 iframe 文本内容匹配目标 frame
+- `--frame-index <n>`：observe 时按 frame 下标选择目标 frame
 - `--wait <ms>`：额外等待时间（默认 5000ms，微前端建议 15000）
 - `--output <path>`：JSON 结果输出路径
 - `--output-dir <dir>`：截图/产物目录
 - `--filename <name>`：截图文件名
 - `--full-page`：全页截图
+- `--selector <css>`：快照/observe 根元素（默认 body）
+- `--depth <n>`：DOM 深度（默认 5）
+- `--click <selector>`：点击元素（支持 text=/role=/~）
+- `--type <text>`：输入文本
+- `--hover <selector>`：悬停元素
+- `--scroll <up|down|left|right>`：滚动方向
+- `--scroll-amount <px>`：滚动距离（默认 300）
+- `--screenshot-after`：交互后自动截图
+- `--interval <ms>`：watch 模式间隔（默认 5000）
+- `--max-rounds <n>`：watch 最大轮数（默认 60）
+- `--allow-launch`：根执行器 action 模式允许无 CDP 时启动 headless Chrome；默认不启用，优先保障真实用户浏览器链路
 
 ## AI 语义断言（aiAssert）
 
@@ -268,12 +405,17 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor
 
 ## 依赖管理
 
-浏览器测试依赖（puppeteer-core, pixelmatch, pngjs, sharp）采用**共享缓存**方案：
-- 首次使用时自动安装到 `~/.szcd-mcp/deps/`
+浏览器测试依赖采用**共享缓存 + 按需安装**方案：
+- `observe/act/assert/diagnose/screenshot` 主链路只安装 `puppeteer-core` 到 `~/.szcd-mcp/deps/`
+- 只有执行设计稿像素对比 `compare` 时才安装 `pixelmatch/pngjs/sharp`
 - 后续所有项目共享复用，无需重复安装
-- 如果自动安装失败，引导用户手动执行：
+- 如果核心依赖自动安装失败，引导用户手动执行：
+```bash
+cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com puppeteer-core
+```
+- 如果视觉对比依赖自动安装失败，引导用户手动执行：
 ```bash
-cd ~/.szcd-mcp/deps && npm install puppeteer-core pixelmatch pngjs sharp --registry=https://registry.npmmirror.com
+cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@img:registry=https://registry.npmmirror.com --prefer-offline --no-audit --no-fund --omit=dev --package-lock=false --sharp_binary_host=https://npmmirror.com/mirrors/sharp --sharp_libvips_binary_host=https://npmmirror.com/mirrors/sharp-libvips pixelmatch pngjs sharp
 ```
 
 ## 结果解读