@szc-ft/mcp-szcd-client 0.35.0 → 0.39.0

package/agents/build.js

@@ -346,6 +346,11 @@ function build() {
             const srcSkillPath = path.join(srcSkillDir, "SKILL.md");
             const destSkillDir = path.join(qwenExtDir, "skills", skillDir);
             if (fs.existsSync(srcSkillPath)) {
+                // PR #0 v3: 先 rm 旧副本，避免脏数据残留（cjs 等已废弃文件）
+                if (fs.existsSync(destSkillDir)) {
+                    fs.rmSync(destSkillDir, { recursive: true, force: true });
+                    console.log(`    ✓ Cleaned stale ${skillDir}/`);
+                }
                 copyDirRecursive(srcSkillDir, destSkillDir);
                 console.log(`    ✓ Synced skill to qwen-extension/skills/${skillDir}/`);
             }
@@ -376,6 +381,10 @@ function build() {
             const srcSkillPath = path.join(srcSkillDir, "SKILL.md");
             const destSkillDir = path.join(opencodeExtDir, "skills", skillDir);
             if (fs.existsSync(srcSkillPath)) {
+                // PR #0 v3: 先 rm 旧副本（与 5a 同步逻辑保持一致）
+                if (fs.existsSync(destSkillDir)) {
+                    fs.rmSync(destSkillDir, { recursive: true, force: true });
+                }
                 copyDirRecursive(srcSkillDir, destSkillDir);
             }
         }
@@ -496,8 +505,57 @@ function build() {
     console.log("\n✅ Agent build complete!");
 }
 
+// ★ PR #0 v3 修复：build 锁（防止并发 build 时 ENOTEMPTY）
+//   跨进程互斥：第一个 build 写 .build.lock，后续 build 等到锁释放
+const lockFile = path.join(process.cwd(), ".build.lock");
+const lockMaxWait = 30000; // 30s 超时
+const lockPollInterval = 100; // 100ms 检查一次
+const lockStaleAge = 60000; // 60s 视为 stale 锁
+async function acquireBuildLock() {
+    const start = Date.now();
+    while (Date.now() - start < lockMaxWait) {
+        try {
+            const fd = fs.openSync(lockFile, "wx");  // 独占创建（原子操作）
+            fs.writeSync(fd, String(process.pid));
+            return fd;
+        } catch (e) {
+            if (e.code === "EEXIST") {
+                // 锁存在 → 检查是否 stale
+                try {
+                    const stat = fs.statSync(lockFile);
+                    if (Date.now() - stat.mtimeMs > lockStaleAge) {
+                        console.log(`  ⚠ 锁文件陈旧 (>${lockStaleAge/1000}s)，强制删除`);
+                        try { fs.unlinkSync(lockFile); } catch {}
+                        continue;
+                    }
+                } catch {}
+                // 等待
+                await new Promise((r) => setTimeout(r, lockPollInterval));
+            } else {
+                throw e;
+            }
+        }
+    }
+    return null;  // 超时
+}
+function releaseBuildLock(fd) {
+    if (fd) {
+        try { fs.closeSync(fd); } catch {}
+        try { fs.unlinkSync(lockFile); } catch {}
+    }
+}
+
 try {
-    build();
+    const lockFd = await acquireBuildLock();
+    if (!lockFd) {
+        process.stderr.write(`❌ build 锁获取超时 (${lockMaxWait}ms)\n`);
+        process.exit(2);
+    }
+    try {
+        build();
+    } finally {
+        releaseBuildLock(lockFd);
+    }
 } catch (error) {
     console.error("❌ Build failed:", error.message);
     console.error(error.stack);

package/agents/platforms.json

@@ -6,6 +6,13 @@
             "type": "stdio",
             "command": "sketch-mcp-server",
             "args": []
+        },
+        {
+            "name": "shadcn",
+            "type": "stdio",
+            "command": "npx",
+            "args": ["-y", "shadcn@latest", "mcp"],
+            "description": "shadcn/ui 官方 stdio MCP（registry 搜索/查看/add 命令）。需项目根目录有 components.json，否则调 list_items_in_registries 报 'No registries are configured'。"
         }
     ],
     "platforms": {

package/agents/szcd-component-expert.qoder.md

@@ -15,12 +15,14 @@ tools:
 skills:
   - local-api-tool
   - local-browser-test
+  - shadcn-design-to-code
   - szcd-component-helper
   - szcd-design-to-code
   - szcd-upload-zip
 mcpServers:
   - szcd-component-helper
   - sketch-mcp-server
+  - shadcn
 ---
 
 # szcd-component-expert: szcd 组件库专家

package/opencode-extension/opencode.json

@@ -10,6 +10,15 @@
             "command": [
                 "sketch-mcp-server"
             ]
+        },
+        "shadcn": {
+            "type": "local",
+            "command": [
+                "npx",
+                "-y",
+                "shadcn@latest",
+                "mcp"
+            ]
         }
     }
 }

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

@@ -1,6 +1,6 @@
 ---
 name: local-browser-test
-description: 在用户真实 Chrome 中执行自动化测试，覆盖 P0 用例批量执行、深度表单填写、微前端测试、长任务生命周期、设计稿对比、JS 错误诊断。通过 puppeteer-core 连接 CDP，天然继承登录态/微前端环境。
+description: 在用户真实 Chrome 中执行自动化测试，覆盖测试用例批量执行、深度表单填写、微前端测试、长任务生命周期、设计稿对比、JS 错误诊断。通过 puppeteer-core 连接 CDP，天然继承登录态/微前端环境。
 compatibility:
   tools:
     - run_command
@@ -72,7 +72,7 @@ export EXECUTOR="$SKILL_DIR/local-browser-executor.js"
 
 ## 🎯 三种典型任务（场景驱动）
 
-### 任务 A：P0 用例批量执行（首选）
+### 任务 A：测试用例批量执行（首选）
 
 用户说"执行 P0 用例 / 批量测试 / 生命周期测试"时，**不要写 ad-hoc puppeteer 脚本**，构造 testCase JSON：
 
@@ -144,7 +144,7 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action api-capture --
 
 ```
 Agent / SKILL.md
-  → testCase JSON  ←  P0 用例首选入口
+  → testCase JSON  ←  测试用例首选入口
   → $SKILL_DIR/local-browser-executor.js  ($EXECUTOR)
   → $SKILL_DIR/lib/browser-engine.js  (executeTestCase + Ant 适配 + expect)
   → $SKILL_DIR/lib/ant-adapter.js     (Select/TreeSelect/Input/Radio/...)
@@ -672,14 +672,32 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
 - `--expect-result-contains <text>`：结果 JSON 包含指定文本
 
 ### 执行测试计划 JSON（ES Module 版）
+
+**⚠️ 禁用 `--action plan`（该分支提前 `process.exit`，不会生成 HTML 报告）**
+直接用 `--plan-file`：
+
 ```bash
 NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
-  --action plan \
   --plan-file /tmp/test-plan.json \
-  --output /tmp/browser-test-result.json
+  --config /path/to/config.yaml
+```
+
+工作区默认在 CWD 的 `.lbt/`，无需手动传 `--workspace`：
+
+```
+.lbt/
+├── config.yaml          ← 项目配置
+├── reports/             ← HTML 报告（趋势图 + 过滤 + 详情页 + 截图）
+│   ├── index.html
+│   └── runs/<id>/
+├── tmp/                 ← 执行过程临时文件（截图等）
+├── auth/                ← 保存的登录态
+└── plans/               ← 回归脚本
 ```
 
-`--action plan` 使用 ES Module 执行器运行测试计划 JSON，支持全部步骤类型（包括 evaluate、antSelect 等）。与 `--action test-case` 的区别：plan 不走 dataset 循环，适合单次执行。
+不传 `--workspace` 时默认 `cwd/.lbt`，也可用 `--workspace <dir>` 指定其他目录。
+
+与 `--action test-case` 的区别：plan 不走 dataset 循环，适合单次执行。
 
 ### 快速诊断（JS错误 + 网络 + 资源 + iframe）
 ```bash
@@ -726,12 +744,15 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
 ### 可选参数
 
 - `--cdp-url http://localhost:9222`：CDP 地址（默认 9222）
-- `--url <url>`：目标页面 URL（不存在则导航）
+- `--page-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）
+- `--plan-file <path>`：测试计划 JSON 文件路径
+- `--config <path>`：配置文件路径（如 config.yaml）
+- `--workspace <dir>`：工作区目录，默认 `cwd/.lbt`。存放 `reports/`（HTML 报告）、`tmp/`（临时文件）、`auth/`（登录态）、`plans/`（回归脚本）
+- `--wait <ms>`：额外等待时间（默认因 action 而异：api-capture 15000，其余 5000）
 - `--output <path>`：JSON 结果输出路径
 - `--output-dir <dir>`：截图/产物目录
 - `--filename <name>`：截图文件名
@@ -741,12 +762,41 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" \
 - `--click <selector>`：点击元素（支持 text=/role=/~）
 - `--type <text>`：输入文本
 - `--hover <selector>`：悬停元素
-- `--scroll <up|down|left|right>`：滚动方向
-- `--scroll-amount <px>`：滚动距离（默认 300）
-- `--screenshot-after`：交互后自动截图
+- `--expression <js>`：evaluate 执行的 JS 表达式（需 IIFE 包裹）
+- `--fail-on-falsy`：evaluate 结果为 falsy 时标记 FAIL
+- `--expect-result-contains <text>`：evaluate 结果包含指定文本
+- `--include-response-body`：api-capture 包含响应体
+- `--include-all-targets`：api-capture 监听全部 target（含非 frame 的 worker/extension）
+- `--reload`：api-capture 前重载页面
+- `--url-pattern <pattern>`：api-capture 按 URL 过滤
+- `--method <method>`：api-capture 按 HTTP 方法过滤
+- `--capture-file <path>`：assert-api 读取的捕获结果文件
+- `--max-failed <n>`：assert-api 允许的最大失败请求数
+- `--forbid-status-gte <code>`：assert-api 禁止的状态码阈值
+- `--required-url <pattern>`：assert-api 必需出现的 URL 模式
+- `--include-request-body`：api-capture 包含请求体
+- `--no-request-body`：api-capture 排除请求体
+- `--target-url-contains <text>`：api-capture 目标 frame URL 包含
 - `--interval <ms>`：watch 模式间隔（默认 5000）
 - `--max-rounds <n>`：watch 最大轮数（默认 60）
 - `--allow-launch`：根执行器 action 模式允许无 CDP 时启动 headless Chrome；默认不启用，优先保障真实用户浏览器链路
+- `--ci`：CI 模式（自动设置 screenshot=always, video=on, trace=on, retries=2）
+- `--retries <n>`：用例级重试次数
+- `--flaky-threshold <n>`：Flaky 测试阈值
+- `--screenshot <always|only-on-failure>`：截图策略
+- `--video <on|off|only-on-failure>`：录像策略
+- `--trace <on|off>`：trace 录制
+- `--record-har`：录制 HAR
+- `--storage-state <path>`：认证存储状态文件路径（用于 global-setup）
+- `--global-setup`：全局设置模式（保存登录态）
+- `--init-force`：强制初始化工作区
+- `--project <name>`：多环境项目选择
+- `--env <name>`：环境选择
+- `--tags <tag>`：按 tag 筛选用例
+- `--exclude-tags <tag>`：排除 tag
+- `--tag-mode <any|all>`：tag 匹配模式
+- `--no-retry-actions`：禁用写操作重试
+- `--no-reload`：diagnose 跳过页面重载
 
 ## AI 语义断言（aiAssert）
 
@@ -822,24 +872,47 @@ cd ~/.szcd-mcp/deps && npm install --registry=https://registry.npmmirror.com --@
 - passed = total：全部通过
 - 有失败步骤：根据 `step` + `error` 字段定位代码问题
 
-### 结果文件结构
+### HTML 报告（推荐）
+
+传 `--workspace <dir>` 时自动生成 Playwright 风格 HTML 报告：
+
+```
+<workspace>/reports/
+├── index.html          ← 入口：趋势图 + 过滤 + 运行列表
+├── trend.json          ← 按日聚合数据
+└── runs/
+    └── <timestamp>-pid<N>/
+        ├── index.html  ← 详情页：步骤表格、截图、错误展开
+        ├── result.json ← 原始结果（脱敏）
+        └── screenshots/ ← 截图副本
+```
+
+入口支持交互过滤（状态 + 关键词搜索）、echarts 趋势图、详情页"返回列表"导航、截图展示。
+
+### 结果 JSON 结构（stdout）
 ```json
 {
     "planId": "xxx",
+    "description": "...",
     "mode": "connect",
+    "startTime": "2026-07-01T10:00:00.000Z",
+    "duration": "1583",
     "steps": [
-        { "index": 1, "step": "navigate", "status": "PASS", "duration": 1200, ... },
-        { "index": 2, "step": "screenshot", "status": "PASS", "duration": 500, ... },
-        { "index": 3, "step": "compare", "status": "PASS", "fidelity": 94.7, ... }
+        { "index": 1, "step": "navigate", "status": "PASS", "duration": "1200", ... },
+        { "index": 2, "step": "screenshot", "status": "PASS", "duration": "500",
+          "filepath": "/tmp/.../screenshot.png", ... }
     ],
     "summary": {
-        "total": 5, "passed": 4, "failed": 1,
-        "fidelity": 94.7
+        "total": "9", "passed": "9", "failed": "0",
+        "fidelity": null
     },
+    "browserInfo": { "mode": "connect", "cdpUrl": "...", "currentUrl": "...", "totalPages": 6 },
     "outputDir": "/tmp/browser-test-xxx"
 }
 ```
 
+注意：`startTime`（非 `startedAt`）、`duration`（非 `durationMs`）。HTML 报告器内部会把 `startTime` → `startedAt`、`duration` → `durationMs`、`summary.*` → `stats.*` 做字段归一化。
+
 ## 批量动态菜单扫描（runTask）
 
 适用场景：测试系统有 N 条动态路由（来自后端菜单接口），要逐条点击触发并验证接口是否返回 200。6/18 反馈中，AI 最终用 130 余条 `act --menu-path` + `api-capture` 手工组合走完 129 条菜单——`runTask` 把这套流水固化为单步骤。
@@ -966,7 +1039,7 @@ cat > /tmp/login.json <<EOF
 EOF
 
 # 3. 执行登录
-NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action plan --plan-file /tmp/login.json --url-contains "platform.aicityos.com" --wait 8000
+NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --plan-file /tmp/login.json --config /path/to/config.yaml
 ```
 
 **LLM 处理流程：**
@@ -1014,6 +1087,10 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action plan --plan-fi
 - ❌ **v20 格式**（生产环境，App-Bound Encryption）：需 Python `pywin32` + `cryptography` 方案
 - ⚠️ Windows 专属（DPAPI），macOS/Linux 需 Keychain/KWallet 方案
 
+## 已知技术债
+
+- **代码重复**：`normalizeForReport`（executor.js）与 `normalizeRunResult`（html-reporter.js）是相同字段归一化逻辑的两份拷贝。修改任何字段映射时必须同步两处。
+
 ## 反模式备忘（来自 6/17 + 6/18 实战反馈）
 
 | 错误做法 | 正确做法 | 原因 |
@@ -1307,3 +1384,94 @@ NODE_PATH=~/.szcd-mcp/deps/node_modules node "$EXECUTOR" --action test-case --te
 - ❌ 单元测试 / 组件级测试 → Vitest / Jest / RTL
 - ❌ 视觉回归全量对比（无 baseline 设计稿）→ Percy / Chromatic
 - ✅ 真实浏览器内的功能验证、API 时序捕获、设计稿单图对比、动态菜单批量扫描
+
+## rawScript 可用 API（PR #4 v3）
+
+`rawScript` 步骤支持两种模式：
+
+### 模式 A：inline code
+```json
+{ "type": "rawScript", "code": "return { passed: document.title.includes('登录') }" }
+```
+
+### 模式 B：codeFile（PR #4 新增）
+```json
+{ "type": "rawScript", "codeFile": ".lbt/scripts/check-title.js" }
+```
+- 相对路径相对 `process.cwd()`
+- 文件不存在 → 明确报错（指出绝对路径）
+- 文件读失败 → 明确报错
+
+### rawScript 函数签名
+
+```js
+async (page, frame, params, browser) => {
+  // page: puppeteer Page 对象
+  // frame: PuppeteerFrame（iframe 上下文）
+  // params: step.params 对象
+  // browser: puppeteer Browser 对象
+  return { passed: true, ... };  // 或 { passed: false, reason: '...' }
+}
+```
+
+### ✅ 浏览器侧可用 API
+
+| 类别 | API |
+|------|-----|
+| DOM | `document.*` / `window.*` / `frame.document` |
+| 存储 | `localStorage.*` / `sessionStorage.*` / `cookieStore` |
+| 网络 | `fetch()` / `XMLHttpRequest` / `WebSocket` |
+| JS 内置 | `JSON` / `Date` / `Math` / `Array` / `Object` / `Promise` / `async/await` |
+| 浏览器事件 | `MouseEvent` / `KeyboardEvent` / `CustomEvent` |
+| puppeteer | `page.*`（evaluate / click / type / waitForSelector 等）|
+
+### ❌ Node 侧 API 不可用（浏览器无）
+
+| 错误信息 | 原因 | 浏览器侧替代 |
+|---------|------|------------|
+| `TypeError: require is not a function` | 浏览器无 `require` | `await fetch()` / `page.evaluate(() => ...)` |
+| `ReferenceError: __dirname is not defined` | 浏览器无 Node 全局 | `window.location.origin` / `frame.url()` |
+| `ReferenceError: process is not defined` | 浏览器无 `process` | `localStorage` / `URL` 替代 |
+| `ReferenceError: Buffer is not defined` | 浏览器无 Node `Buffer` | `Uint8Array` / `TextEncoder` |
+| `TypeError: require.main is not a function` | 浏览器无 `require.main` | 不需要 |
+
+**★ PR #4 修复**：rawScript 执行器会在跑前**静态扫描**代码，发现 Node-only API 时**立即 fail**，错误信息包含"详见 SKILL.md > ## rawScript 可用 API"，避免用户踩坑。
+
+### 常见错误速查
+
+| 错误 | 修复 |
+|------|------|
+| `codeFile 不存在: /path/to/file` | 检查路径或用 inline `code` 替代 |
+| `rawScript 检测到 Node-only API: require('fs')` | 改用 `page.evaluate(() => ...)` 走浏览器 |
+| `script compile error: Unexpected token` | 检查 `code` 字段 JSON 转义（`"` → `\"`） |
+| `script execution error: ...` | 看具体堆栈；可能是 page 已 close 或网络超时 |
+
+### 示例：检查页面 title
+
+```js
+// 模式 A：inline
+{ "type": "rawScript", "code": "return { passed: document.title.includes('数据集目录'), title: document.title }" }
+
+// 模式 B：codeFile
+{ "type": "rawScript", "codeFile": ".lbt/scripts/check-dataset-title.js" }
+// .lbt/scripts/check-dataset-title.js 内容：
+//   return { passed: document.title.includes('数据集目录'), title: document.title };
+```
+
+### 示例：拿所有按钮文本
+
+```js
+{
+  "type": "rawScript",
+  "code": "return { passed: true, buttons: [...document.querySelectorAll('button')].map(b => b.textContent.trim()) }"
+}
+```
+
+### 示例：调浏览器 fetch 验证 API
+
+```js
+{
+  "type": "rawScript",
+  "code": "const r = await fetch('/api/health'); const j = await r.json(); return { passed: j.status === 'ok', data: j }"
+}
+```

package/opencode-extension/skills/local-browser-test/config.example.yaml

@@ -0,0 +1,51 @@
+# local-browser-test 配置示例
+# 复制为 .lbt/config.yaml 后填值（config.yaml 已在 .gitignore 内）
+#
+# 占位符 ${ENV_VAR} 走 process.env，CI 推荐用：
+#   export LBT_TOKEN=xxx
+#   export LBT_PASSWORD=xxx
+
+# 应用基础配置
+app:
+  baseURL: http://10.2.7.60:30020
+  timeout: 30000
+
+# 鉴权（强烈建议用环境变量，避免明文）
+auth:
+  type: bearer             # bearer | cookie | oauth2
+  token: ${LBT_TOKEN}      # 走环境变量
+  # password: ${LBT_PASSWORD}
+  # username: ${LBT_USERNAME}
+  # verifyCode: ${LBT_VERIFY_CODE}
+  storageState: null       # 可选：复用 .lbt/auth/<project>.json
+
+# 多环境配置（配合 --project <name> 切换）
+projects:
+  - name: corpus-test
+    baseURL: http://119.0.87.158
+    auth:
+      type: bearer
+      token: ${LBT_TOKEN}
+  - name: corpus-stg
+    baseURL: http://10.2.7.60:30020
+    auth:
+      type: bearer
+      token: ${LBT_TOKEN}
+  - name: corpus-prod
+    baseURL: http://172.16.0.172:30010
+    auth:
+      type: bearer
+      token: ${LBT_TOKEN}
+
+# 重试策略
+retry:
+  maxRetries: 0              # 用例级（CI 跑 2 次）
+  maxRetriesPerStep: 2       # 步骤级（验证码过期等）
+  flakyThreshold: 5          # 5 次中 1 挂 4 过 → flaky
+  noRetryActions: true       # 写操作（删除/提交/上线）永不重试
+
+# 报告（v4 Playwright 风格）
+report:
+  retainRuns: 30             # 保留最近 30 次 run
+  retainDays: 7              # 保留最近 7 天
+  retainFailedForever: true  # 失败 run 永久保留