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

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,19 @@ AI 直接构造测试计划 JSON：
 
 | type | 功能 | 参数 | 返回 |
 |------|------|------|------|
+| observe | 结构化观察 | `selector`, `depth`, `frameContentContains`, `maxInteractiveElements` | `{ frames, tree, interactiveElements[] }` |
+| act | 按 index/selector/menuPath 交互 | `index` 或 `selector/click/hover` 或 `menuPath`, `typeText`, `clear`, `frameContentContains` | `{ acted, action, element/steps }` |
+| assert | 轻量断言 | `selector`, `expect`, `urlContains`, `textContains` | `{ passed, checks }` |
+| apiCapture | API 请求/响应捕获 | `wait`, `urlPattern`, `method`, `includeResponseBody`, `frameContentContains` | `{ targets, requests, summary }` |
+| assertApi | API 捕获结果断言 | `maxFailed`, `requiredUrls`, `forbidStatusGte`, `minTotal` | `{ passed, checks, summary }` |
 | 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 +164,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 +215,81 @@ 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
+```
+
+### 左侧菜单路径稳定点击
+```bash
+node {client_path}/local-browser-executor.js \
+  --action act \
+  --url-contains "platform.aicityos.com" \
+  --menu-path "目录管理/数据集目录" \
+  --observe-after \
+  --output /tmp/browser-menu-act.json
+```
+
+`--menu-path` 会按路径逐级匹配菜单项，非末级优先执行展开，末级执行点击；匹配优先考虑 `role=menuitem`、`.ant-menu-item`、`.ant-menu-submenu-title` 和文本精确/包含匹配。
+
+### 轻量 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
+```
+
+### API 请求/响应捕获（真实浏览器 + 微前端）
+```bash
+node {client_path}/local-browser-executor.js \
+  --action api-capture \
+  --url-contains "platform.aicityos.com" \
+  --frame-content-contains "数据集目录" \
+  --url-pattern "/api/" \
+  --wait 15000 \
+  --include-response-body \
+  --reload \
+  --output /tmp/browser-api-capture.json
+```
+
+`api-capture` 使用 CDP `Network.*` 事件监听主页面和可 attach 的 page/iframe target，不使用 `setRequestInterception`，避免阻断真实请求。wujie/qiankun 场景优先传 `--frame-content-contains` 锁定业务 iframe；如需监听全部 target，追加 `--include-all-targets`。
+
+### API 捕获结果断言
+```bash
+node {client_path}/local-browser-executor.js \
+  --action assert-api \
+  --capture-file /tmp/browser-api-capture.json \
+  --max-failed 0 \
+  --forbid-status-gte 400 \
+  --required-url "/list" \
+  --output /tmp/browser-api-assert.json
+```
+
+计划内可直接在 `apiCapture` 后追加 `{ "type": "assertApi", "maxFailed": 0, "forbidStatusGte": 400 }`，会自动读取上一步捕获结果。
+
+### 快速诊断（过渡兼容）
 ```bash
 NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
   --action diagnose \
@@ -232,16 +329,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 +447,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
 ```
 
 ## 结果解读

package/qwen-extension/skills/local-browser-test/local-browser-executor-old.cjs

@@ -0,0 +1,395 @@
+#!/usr/bin/env node
+/**
+ * local-browser-executor.js - 本地浏览器自动化执行器
+ *
+ * 功能：
+ *   --action diagnose    全面诊断（JS错误、网络请求、API检查、资源加载）
+ *   --action list-pages  列出所有标签页
+ *   --action screenshot  截图
+ *   --action api-check   检查 API 请求状态
+ *   --action plan        执行测试计划 JSON
+ *
+ * 连接方式：
+ *   --cdp-url http://localhost:9222  (默认自动检测 9222)
+ *   --auto-detect                    自动检测 Chrome/Edge 进程
+ *
+ * 通用参数：
+ *   --url <url>          目标页面 URL
+ *   --url-contains <s>   按关键词查找已打开的页面
+ *   --wait <ms>          额外等待时间（默认 5000）
+ *   --output <path>      结果输出文件
+ *   --output-dir <dir>   截图/产物输出目录
+ */
+
+const puppeteer = require('puppeteer-core');
+const fs = require('fs');
+const path = require('path');
+const http = require('http');
+
+// ===== 参数解析 =====
+const args = process.argv.slice(2);
+function getArg(name, defaultVal) {
+  const idx = args.indexOf(`--${name}`);
+  if (idx === -1) return defaultVal;
+  return args[idx + 1] || defaultVal;
+}
+function hasFlag(name) {
+  return args.includes(`--${name}`);
+}
+
+const ACTION = getArg('action', 'diagnose');
+const CDP_URL = getArg('cdp-url', 'http://localhost:9222');
+const TARGET_URL = getArg('url', null);
+const URL_CONTAINS = getArg('url-contains', null);
+const WAIT_MS = parseInt(getArg('wait', '5000'), 10);
+const OUTPUT = getArg('output', null);
+const OUTPUT_DIR = getArg('output-dir', '/tmp/browser-test');
+const PLAN_FILE = getArg('plan-file', null);
+
+// ===== 工具函数 =====
+function log(msg) { console.log(msg); }
+function ensureDir(dir) { fs.mkdirSync(dir, { recursive: true }); }
+
+function checkCDP(url) {
+  return new Promise((resolve) => {
+    const req = http.get(url + '/json/version', { timeout: 2000 }, (res) => {
+      let data = '';
+      res.on('data', c => data += c);
+      res.on('end', () => {
+        try { resolve(JSON.parse(data)); } catch { resolve(null); }
+      });
+    });
+    req.on('error', () => resolve(null));
+    req.on('timeout', () => { req.destroy(); resolve(null); });
+  });
+}
+
+async function findPage(browser) {
+  const pages = await browser.pages();
+  if (TARGET_URL) {
+    for (const p of pages) {
+      if (p.url().includes(TARGET_URL) || p.url() === TARGET_URL) return p;
+    }
+    // 导航到目标 URL
+    const p = pages[0] || await browser.newPage();
+    await p.goto(TARGET_URL, { waitUntil: 'domcontentloaded', timeout: 30000 });
+    return p;
+  }
+  if (URL_CONTAINS) {
+    for (const p of pages) {
+      if (p.url().includes(URL_CONTAINS)) return p;
+    }
+    log(`[WARN] 未找到包含 "${URL_CONTAINS}" 的页面，使用第一个页面`);
+  }
+  // 找到非 about:blank 的页面
+  for (const p of pages) {
+    if (!p.url().startsWith('about:') && !p.url().startsWith('devtools:')) return p;
+  }
+  return pages[0];
+}
+
+// ===== Action: list-pages =====
+async function listPages(browser) {
+  const pages = await browser.pages();
+  const result = [];
+  for (let i = 0; i < pages.length; i++) {
+    const p = pages[i];
+    let title = '';
+    try { title = await p.title(); } catch {}
+    result.push({ index: i, url: p.url(), title });
+    log(`[${i}] ${p.url()}`);
+    if (title) log(`    title: ${title}`);
+  }
+  return { pages: result, total: result.length };
+}
+
+// ===== Action: diagnose =====
+async function diagnose(browser) {
+  ensureDir(OUTPUT_DIR);
+  const page = await findPage(browser);
+  log(`[PAGE] ${page.url()}`);
+
+  // 收集数据
+  const pageErrors = [];
+  const consoleMessages = [];
+  const failedRequests = [];
+  const apiRequests = [];
+  const resourceRequests = [];
+
+  page.on('pageerror', err => {
+    pageErrors.push({ message: err.message, stack: err.stack?.split('\n').slice(0, 5).join('\n') });
+  });
+  page.on('console', msg => {
+    const type = msg.type();
+    const text = msg.text().substring(0, 500);
+    consoleMessages.push({ type, text });
+  });
+  page.on('response', resp => {
+    const url = resp.url();
+    const status = resp.status();
+    const type = resp.request().resourceType();
+    if (type === 'xhr' || type === 'fetch') {
+      apiRequests.push({ status, url, method: resp.request().method() });
+    }
+    if (type === 'stylesheet' || type === 'script') {
+      resourceRequests.push({ status, url, type });
+    }
+    if (status >= 400) {
+      failedRequests.push({ status, url, type });
+    }
+  });
+  page.on('requestfailed', req => {
+    failedRequests.push({ status: 'ABORTED', url: req.url(), error: req.failure()?.errorText });
+  });
+
+  // 刷新页面收集
+  log('[INFO] 刷新页面收集诊断数据...');
+  try {
+    await page.reload({ waitUntil: 'load', timeout: 30000 });
+  } catch (e) {
+    log(`[WARN] 刷新超时: ${e.message.substring(0, 100)}`);
+  }
+  await new Promise(r => setTimeout(r, WAIT_MS));
+
+  // 截图
+  const screenshotPath = path.join(OUTPUT_DIR, 'diagnose-screenshot.png');
+  await page.screenshot({ path: screenshotPath, fullPage: false });
+  log(`[OK] 截图: ${screenshotPath}`);
+
+  // 检查 iframe
+  const frames = page.frames();
+  const iframeInfo = [];
+  for (const frame of frames) {
+    const url = frame.url();
+    if (url === page.url() || url === 'about:blank') continue;
+    let bodyText = '';
+    let rootContent = '';
+    try {
+      const info = await frame.evaluate(() => ({
+        bodyText: document.body?.innerText?.substring(0, 200) || '',
+        rootHTML: document.getElementById('root')?.innerHTML?.substring(0, 200) || 'no root',
+        hasReactRoot: !document.getElementById('root')?.innerHTML?.includes('loading-spinner'),
+        antdElements: document.querySelectorAll('[class*="ant-"]').length,
+      }));
+      bodyText = info.bodyText;
+      rootContent = info.rootHTML;
+      iframeInfo.push({ url, ...info });
+    } catch (e) {
+      iframeInfo.push({ url, error: e.message.substring(0, 100) });
+    }
+  }
+
+  // 输出结果
+  const errors = consoleMessages.filter(m => m.type === 'error');
+  const warnings = consoleMessages.filter(m => m.type === 'warning');
+
+  const result = {
+    url: page.url(),
+    timestamp: new Date().toISOString(),
+    screenshot: screenshotPath,
+    pageErrors,
+    consoleErrors: errors,
+    consoleWarnings: warnings,
+    consoleTotal: consoleMessages.length,
+    failedRequests,
+    apiRequests,
+    resourceStatus: resourceRequests.map(r => ({
+      status: r.status, type: r.type, name: r.url.split('/').pop()
+    })),
+    iframes: iframeInfo,
+    summary: {
+      jsErrors: pageErrors.length,
+      consoleErrors: consoleMessages.filter(m => m.type === 'error').length,
+      failedNetwork: failedRequests.length,
+      totalAPI: apiRequests.length,
+      failedAPI: apiRequests.filter(r => r.status >= 400).length,
+      totalResources: resourceRequests.length,
+      failedResources: resourceRequests.filter(r => r.status >= 400).length,
+    }
+  };
+
+  // 打印摘要
+  log('\n========== 诊断结果 ==========');
+  log(`JS 异常: ${result.summary.jsErrors}`);
+  pageErrors.forEach(e => log(`  [PAGEERROR] ${e.message}`));
+  log(`Console 错误: ${errors.length}`);
+  errors.forEach(e => log(`  [ERROR] ${e.text}`));
+  log(`Console 警告: ${warnings.length}`);
+  warnings.forEach(e => log(`  [WARN] ${e.text}`));
+  log(`Console 消息总数: ${consoleMessages.length}`);
+  log(`失败网络请求: ${result.summary.failedNetwork}`);
+  failedRequests.forEach(r => log(`  [${r.status}] ${r.url}`));
+  log(`API 请求: ${result.summary.totalAPI} (失败: ${result.summary.failedAPI})`);
+  apiRequests.forEach(r => {
+    const marker = r.status >= 400 ? '❌' : '✅';
+    log(`  ${marker} [${r.status}] ${r.method} ${r.url}`);
+  });
+  log(`CSS/JS 资源: ${result.summary.totalResources} (失败: ${result.summary.failedResources})`);
+  resourceRequests.filter(r => r.status >= 400).forEach(r => log(`  ❌ [${r.status}] ${r.url}`));
+  if (iframeInfo.length > 0) {
+    log(`\niframe 信息:`);
+    iframeInfo.forEach(f => log(`  ${f.url} → ${f.error || (f.hasReactRoot ? 'React已挂载' : '未挂载')}`));
+  }
+
+  // 保存结果
+  if (OUTPUT) {
+    fs.writeFileSync(OUTPUT, JSON.stringify(result, null, 2));
+    log(`\n[OK] 结果已保存: ${OUTPUT}`);
+  }
+
+  return result;
+}
+
+// ===== Action: screenshot =====
+async function screenshot(browser) {
+  ensureDir(OUTPUT_DIR);
+  const page = await findPage(browser);
+  const filename = getArg('filename', 'screenshot.png');
+  const fullPath = path.join(OUTPUT_DIR, filename);
+  const fullPage = hasFlag('full-page');
+  await page.screenshot({ path: fullPath, fullPage });
+  log(`[OK] 截图已保存: ${fullPath}`);
+  return { filepath: fullPath };
+}
+
+// ===== Action: api-check =====
+async function apiCheck(browser) {
+  const page = await findPage(browser);
+  log(`[PAGE] ${page.url()}`);
+
+  const requests = [];
+  const failed = [];
+
+  page.on('response', resp => {
+    const type = resp.request().resourceType();
+    if (type === 'xhr' || type === 'fetch') {
+      requests.push({
+        status: resp.status(),
+        url: resp.url(),
+        method: resp.request().method(),
+        frameUrl: resp.request().frame()?.url?.() || '',
+      });
+    }
+  });
+  page.on('requestfailed', req => {
+    failed.push({ url: req.url(), error: req.failure()?.errorText });
+  });
+
+  log('[INFO] 刷新页面收集 API 请求...');
+  try { await page.reload({ waitUntil: 'load', timeout: 30000 }); } catch {}
+  await new Promise(r => setTimeout(r, WAIT_MS));
+
+  log('\n========== API 请求 ==========');
+  requests.forEach(r => {
+    const marker = r.status >= 400 ? '❌' : '✅';
+    const isIframe = r.frameUrl && r.frameUrl !== page.url() ? ' [iframe]' : '';
+    log(`${marker} [${r.status}] ${r.method} ${r.url}${isIframe}`);
+  });
+  if (failed.length > 0) {
+    log('\n========== 失败请求 ==========');
+    failed.forEach(r => log(`[FAILED] ${r.url} → ${r.error}`));
+  }
+  log(`\n总计: ${requests.length} 请求, 失败: ${requests.filter(r => r.status >= 400).length + failed.length}`);
+
+  return { requests, failed };
+}
+
+// ===== Action: plan =====
+async function executePlan(browser) {
+  const planPath = PLAN_FILE;
+  if (!planPath) { log('[ERROR] --plan-file 未指定'); return; }
+  const plan = JSON.parse(fs.readFileSync(planPath, 'utf-8'));
+  ensureDir(plan.options?.outputDir || OUTPUT_DIR);
+
+  log(`[PLAN] ${plan.description || plan.planId}`);
+  log(`[STEPS] ${plan.steps.length} 个步骤`);
+
+  const results = [];
+  let currentPage = await findPage(browser);
+
+  for (let i = 0; i < plan.steps.length; i++) {
+    const step = plan.steps[i];
+    const start = Date.now();
+    try {
+      let result = {};
+      switch (step.type) {
+        case 'navigate':
+          await currentPage.goto(step.url, { waitUntil: step.waitUntil || 'domcontentloaded', timeout: 30000 });
+          result = { url: currentPage.url() };
+          break;
+        case 'screenshot':
+          const fp = path.join(plan.options?.outputDir || OUTPUT_DIR, step.filename || `step-${i}.png`);
+          await currentPage.screenshot({ path: fp, fullPage: step.fullPage });
+          result = { filepath: fp };
+          break;
+        case 'waitFor':
+          if (step.selector) await currentPage.waitForSelector(step.selector, { timeout: step.timeout || 10000 });
+          result = { matched: true };
+          break;
+        case 'evaluate':
+          const evalResult = await currentPage.evaluate(step.expression);
+          result = { result: evalResult };
+          break;
+        case 'click':
+          await currentPage.click(step.selector);
+          result = { clicked: true };
+          break;
+        case 'checkElement':
+          const count = await currentPage.$$eval(step.selector, els => els.length).catch(() => 0);
+          const passed = step.expect?.minCount ? count >= step.expect.minCount : count > 0;
+          result = { passed, elementCount: count };
+          break;
+        default:
+          result = { skipped: true, reason: `unknown step type: ${step.type}` };
+      }
+      const duration = Date.now() - start;
+      results.push({ index: i, step: step.type, status: 'PASS', duration, ...result });
+      log(`  [${i + 1}/${plan.steps.length}] ✅ ${step.type} (${duration}ms)`);
+    } catch (e) {
+      const duration = Date.now() - start;
+      results.push({ index: i, step: step.type, status: 'FAIL', duration, error: e.message });
+      log(`  [${i + 1}/${plan.steps.length}] ❌ ${step.type} (${duration}ms) → ${e.message.substring(0, 100)}`);
+    }
+  }
+
+  const summary = {
+    total: results.length,
+    passed: results.filter(r => r.status === 'PASS').length,
+    failed: results.filter(r => r.status === 'FAIL').length,
+  };
+  log(`\n[RESULT] ${summary.passed}/${summary.total} 通过`);
+
+  if (OUTPUT) {
+    fs.writeFileSync(OUTPUT, JSON.stringify({ steps: results, summary }, null, 2));
+  }
+  return { steps: results, summary };
+}
+
+// ===== 主入口 =====
+(async () => {
+  // 检测 CDP
+  const cdpInfo = await checkCDP(CDP_URL);
+  if (!cdpInfo) {
+    log(`[ERROR] 无法连接到 CDP: ${CDP_URL}`);
+    log('请确保浏览器已启动调试端口:');
+    log('  Windows Edge: "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe" --remote-debugging-port=9222');
+    log('  Windows Chrome: "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe" --remote-debugging-port=9222');
+    process.exit(1);
+  }
+  log(`[CDP] ${cdpInfo.Browser || 'connected'} (${CDP_URL})`);
+
+  const browser = await puppeteer.connect({ browserURL: CDP_URL, defaultViewport: null });
+
+  let result;
+  switch (ACTION) {
+    case 'list-pages': result = await listPages(browser); break;
+    case 'diagnose': result = await diagnose(browser); break;
+    case 'screenshot': result = await screenshot(browser); break;
+    case 'api-check': result = await apiCheck(browser); break;
+    case 'plan': result = await executePlan(browser); break;
+    default: log(`[ERROR] 未知 action: ${ACTION}`);
+  }
+
+  browser.disconnect();
+  log('\n[DONE]');
+})();