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

package/opencode-extension/skills/szcd-design-to-code/SKILL.md

@@ -125,8 +125,9 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 | 优先级 | 来源 | 适用判定 | 渲染产物 |
 |---|---|---|---|
 | **P0** | **sketch 自带 bitmap** | 节点是 `type=bitmap` | `extractBitmaps` 返回的 `siblingsAfterMe + position + nodeSize` 三维判定渲染产物：区域背景图 / 行内图标 / 独立装饰插图（详见下方表 6） |
-| **P1** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
-| **P2** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
+| **P1** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
+| **P2** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
+
 | **P3** | **antd 图标语义匹配** | 上面三级都失败：shapeGroup 无法直出、节点名无 iconfont 匹配 | `<XxxOutlined />` 按 contextTable 选语义最近的 antd 图标 |
 | **P4** | **纯 CSS / div 渲染** | 上面四级全部失败，且元素是几何/色块（非图标语义） | `<div style={{...}}>` |
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.27.0",
+    "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.0",
+    "version": "0.27.2",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {

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

@@ -12,11 +12,29 @@ 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`）。
@@ -159,32 +180,205 @@ wujie 微前端子应用渲染在 blob URL iframe 中，**坐标点击无法到
 - `~#myId` → 自动转为 `[id*="myId"]`
 - 普通选择器（如 `.my-class`）保持精确匹配
 
-### puppeteer-core v22 注意事项
+## 实战经验补充
+
+### wujie 微前端诊断要点
+
+1. **子应用渲染在 blob URL iframe 中**，puppeteer 的 `page.frames()` 可以访问
+2. **iframe 内的 console 监听**：不要用 `frame.page().on()`（puppeteer-core 无此方法），改用 `page.on('console')` + `msg.frame().url()` 判断来源
+3. **生产环境 console 被屏蔽**：代码中 `console.log = () => {}` 导致 0 条消息。需提前注入 `localStorage.setItem('showConsoleLog', 'true')`
+4. **pageerror 事件是关键**：未捕获的 JS 异常不会出现在 console 中，必须监听 `page.on('pageerror')`
+5. **API 404/403 检查**：刷新页面后监听 `page.on('response')`，过滤 `resourceType === 'xhr'` 检查后端接口状态
+
+### 常见诊断流程
+
+```
+1. --action list-pages     确认目标页面存在
+2. --action diagnose       全面诊断（JS错误 + 网络 + 资源 + iframe）
+3. --action api-check      专门检查 API 请求（含 iframe 内的请求）
+4. 根据结果定位问题
+```
+
+### puppeteer-core 注意事项
+- **连接时必须设 `defaultViewport: null`**，否则浏览器窗口会被强制缩放到指定尺寸：
+  ```js
+  // 正确：保持浏览器原始窗口大小
+  puppeteer.connect({ browserURL: 'http://localhost:9222', defaultViewport: null })
+  // 错误：会把浏览器视口改成 1440x900
+  puppeteer.connect({ browserURL: '...', defaultViewport: { width: 1440, height: 900 } })
+  ```
 - `page.$x()` 已移除，用 `evaluate` + `querySelectorAll` 替代
 - SVG 元素的 `className` 是 `SVGAnimatedString` 对象而非字符串，需先检查 `typeof`
 - 所有 `evaluate` 调用内部使用 `safeEval` 包装，自动处理 context destroyed 错误
 
 ## 执行命令
 
+### 结构化观察（主链路起点）
+```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 \
+  --url-contains "platform.aicityos.com" \
+  --wait 15000 \
+  --output-dir /tmp/browser-test-diagnose
+```
+
+### 列出所有标签页
 ```bash
-node {client_install_path}/local-browser-executor.js \
-  --plan '<测试计划JSON>' \
-  --output /tmp/browser-test-result.json \
-  --base-url http://localhost:8088
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action list-pages
 ```
 
-也支持从文件读取计划：
+### 检查 API 请求状态
 ```bash
-node {client_install_path}/local-browser-executor.js \
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action api-check \
+  --url-contains "platform.aicityos.com" \
+  --wait 15000
+```
+
+### 截图
+```bash
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action screenshot \
+  --url-contains "platform.aicityos.com" \
+  --filename current-page.png \
+  --output-dir /tmp/browser-test
+```
+
+### 执行测试计划 JSON
+```bash
+NODE_PATH=~/.szcd-mcp/deps/node_modules node {skill_path}/local-browser-executor.cjs \
+  --action plan \
   --plan-file /tmp/test-plan.json \
-  --output /tmp/browser-test-result.json \
-  --base-url http://localhost:8088
+  --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:9223`：指定非默认的 CDP 端口
-- `--page-url http://xxx/page`：connect 模式下指定目标页面
+- `--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）
 
@@ -211,12 +405,17 @@ node {client_install_path}/local-browser-executor.js \
 
 ## 依赖管理
 
-浏览器测试依赖（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://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
 ```
 
 ## 结果解读