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

package/local-browser-executor.js

@@ -3,10 +3,13 @@
  * 本地浏览器测试执行器 - CLI 入口
  *
  * 用法：
+ *   node local-browser-executor.js --action observe --output /tmp/observe.json
+ *   node local-browser-executor.js --action act --index 1 --observe-after
  *   node local-browser-executor.js --plan '<JSON>' --output /tmp/result.json
  *   node local-browser-executor.js --plan-file /path/to/plan.json --output /tmp/result.json
  *
  * 参数：
+ *   --action     直接执行动作，当前支持 observe/act/assert
  *   --plan       测试计划 JSON 字符串
  *   --plan-file  测试计划 JSON 文件路径（与 --plan 二选一）
  *   --output     结果输出文件路径（默认 stdout）
@@ -36,6 +39,9 @@ function parseArgs() {
 
     for (let i = 0; i < args.length; i++) {
         switch (args[i]) {
+            case "--action":
+                parsed.action = args[++i];
+                break;
             case "--plan":
                 parsed.planJson = args[++i];
                 break;
@@ -51,9 +57,66 @@ function parseArgs() {
             case "--page-url":
                 parsed.pageUrl = args[++i];
                 break;
+            case "--url-contains":
+                parsed.urlContains = args[++i];
+                break;
+            case "--frame-url-contains":
+                parsed.frameUrlContains = args[++i];
+                break;
+            case "--frame-content-contains":
+                parsed.frameContentContains = args[++i];
+                break;
+            case "--frame-index":
+                parsed.frameIndex = args[++i];
+                break;
+            case "--selector":
+                parsed.selector = args[++i];
+                break;
+            case "--depth":
+                parsed.depth = args[++i];
+                break;
+            case "--max-interactive-elements":
+                parsed.maxInteractiveElements = args[++i];
+                break;
+            case "--index":
+                parsed.index = args[++i];
+                break;
+            case "--click":
+                parsed.click = args[++i];
+                break;
+            case "--type":
+                parsed.typeText = args[++i];
+                break;
+            case "--clear":
+                parsed.clear = true;
+                break;
+            case "--hover":
+                parsed.hover = args[++i];
+                break;
+            case "--observe-after":
+                parsed.observeAfter = true;
+                break;
+            case "--url-contains-assert":
+                parsed.urlContainsAssert = args[++i];
+                break;
+            case "--text-contains":
+                parsed.textContains = args[++i];
+                break;
+            case "--expect-visible":
+                parsed.expectVisible = true;
+                break;
+            case "--min-count":
+                parsed.minCount = args[++i];
+                break;
+            case "--has-text":
+                parsed.hasText = args[++i];
+                break;
             case "--base-url":
                 parsed.baseUrl = args[++i];
                 break;
+            case "--allow-launch":
+                parsed.allowLaunch = true;
+                break;
             case "--help":
             case "-h":
                 printHelp();
@@ -68,17 +131,40 @@ function printHelp() {
 本地浏览器测试执行器
 
 用法:
+  node local-browser-executor.js --action observe [options]
+  node local-browser-executor.js --action act --index 1 --observe-after [options]
+  node local-browser-executor.js --action assert --selector ".ant-table" --expect-visible [options]
   node local-browser-executor.js --plan '<JSON>' [options]
   node local-browser-executor.js --plan-file <path> [options]
 
 选项:
-  --plan <json>       测试计划 JSON 字符串
-  --plan-file <path>  测试计划 JSON 文件路径
-  --output <path>     结果输出文件路径（默认 stdout）
-  --cdp-url <url>     Chrome DevTools Protocol URL（默认 http://localhost:9222）
-  --page-url <url>    目标页面 URL（connect 模式时匹配标签页）
-  --base-url <url>    基础 URL，替换计划中的 {{baseUrl}} 占位符
-  -h, --help          显示帮助
+  --action <name>                    直接执行动作，当前支持 observe/act/assert
+  --plan <json>                      测试计划 JSON 字符串
+  --plan-file <path>                 测试计划 JSON 文件路径
+  --output <path>                    结果输出文件路径（默认 stdout）
+  --cdp-url <url>                    Chrome DevTools Protocol URL（默认 http://localhost:9222）
+  --page-url <url>                   目标页面 URL（connect 模式时匹配标签页）
+  --url-contains <text>              按 URL 片段匹配已打开标签页
+  --frame-url-contains <text>        按 URL 片段匹配 iframe
+  --frame-content-contains <text>    按文本内容匹配 iframe
+  --frame-index <n>                  按 frame 下标选择 iframe
+  --selector <css>                   observe/assert 根节点或目标元素（observe 默认 body）
+  --depth <n>                        observe 的 DOM 树深度（默认 5）
+  --max-interactive-elements <n>     observe 的交互元素上限（默认 200）
+  --index <n>                        act 时按 observe 的 interactiveElements[index] 操作
+  --click <selector>                 act 时点击 selector/text=/role=/~ 目标
+  --type <text>                      act 时输入文本
+  --clear                            act 输入前清空目标
+  --hover <selector>                 act 时悬停 selector/text=/role=/~ 目标
+  --observe-after                    act 后再次 observe，返回 before/act/after 闭环结果
+  --url-contains-assert <text>       assert 当前 URL 包含文本
+  --text-contains <text>             assert 页面文本包含内容
+  --expect-visible                   assert selector 可见
+  --min-count <n>                    assert selector 数量下限
+  --has-text <text>                  assert selector 文本包含内容
+  --allow-launch                     action 模式允许无 CDP 时启动 headless Chrome
+  --base-url <url>                   基础 URL，替换计划中的 {{baseUrl}} 占位符
+  -h, --help                         显示帮助
 `);
 }
 
@@ -183,9 +269,110 @@ async function executePlan(plan, options) {
 
 // ==================== 主流程 ====================
 
+async function executeAction(args) {
+    const engine = new BrowserEngine();
+    const startedAt = new Date().toISOString();
+    try {
+        const cdpUrl = args.cdpUrl || "http://localhost:9222";
+        const debuggerAvailable = await engine.isDebuggerAvailable(cdpUrl);
+        if (!debuggerAvailable && !args.allowLaunch) {
+            return {
+                error: `无法连接到 Chrome 调试端口: ${cdpUrl}`,
+                errorCode: "CDP_UNAVAILABLE",
+                guide: "请先以 --remote-debugging-port=9222 启动用户真实浏览器；如确需启动 headless 回退，追加 --allow-launch。",
+                startTime: startedAt,
+                endTime: new Date().toISOString(),
+            };
+        }
+
+        const initResult = await engine.init({
+            cdpUrl,
+            pageUrl: args.pageUrl || args.urlContains,
+        });
+
+        switch (args.action) {
+            case "observe": {
+                const result = await engine.observe({
+                    selector: args.selector,
+                    depth: args.depth,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                    maxInteractiveElements: args.maxInteractiveElements,
+                });
+                return { ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "act": {
+                const actResult = await engine.act({
+                    index: args.index,
+                    selector: args.selector,
+                    click: args.click,
+                    hover: args.hover,
+                    typeText: args.typeText,
+                    clear: args.clear,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                });
+                if (!args.observeAfter) {
+                    return { type: "act", ...actResult, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+                }
+                const after = await engine.observe({
+                    depth: args.depth,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                    maxInteractiveElements: args.maxInteractiveElements,
+                });
+                return { type: "actObserve", act: actResult, after, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            case "assert": {
+                const expect = {};
+                if (args.expectVisible) expect.visible = true;
+                if (args.minCount !== undefined) expect.minCount = Number.parseInt(args.minCount, 10);
+                if (args.hasText !== undefined) expect.hasText = args.hasText;
+                const result = await engine.assert({
+                    selector: args.selector,
+                    expect,
+                    urlContains: args.urlContainsAssert,
+                    textContains: args.textContains,
+                    frameUrlContains: args.frameUrlContains,
+                    frameContentContains: args.frameContentContains,
+                    frameIndex: args.frameIndex,
+                });
+                return { type: "assert", ...result, browserInfo: initResult, startTime: startedAt, endTime: new Date().toISOString() };
+            }
+            default:
+                return {
+                    error: `未知 action: ${args.action}`,
+                    errorCode: "UNKNOWN_ACTION",
+                    supportedActions: ["observe", "act", "assert"],
+                    startTime: startedAt,
+                    endTime: new Date().toISOString(),
+                };
+        }
+    } catch (err) {
+        return {
+            error: err.message,
+            errorCode: err.code || "ACTION_FAILED",
+            installGuide: err.code === "CHROME_NOT_FOUND" || err.code === "DEPENDENCY_MISSING" ? err.message : undefined,
+            startTime: startedAt,
+            endTime: new Date().toISOString(),
+        };
+    } finally {
+        await engine.close();
+    }
+}
+
 async function main() {
     const args = parseArgs();
 
+    if (args.action) {
+        const results = await executeAction(args);
+        outputResult(results, args.output);
+        process.exit(results.error ? 2 : 0);
+    }
+
     let plan;
     try {
         plan = loadPlan(args);

package/opencode-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/opencode-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
 ```
 
 ## 结果解读