@szc-ft/mcp-szcd-client 0.34.2 → 0.38.0

package/package.json

@@ -1,72 +1,72 @@
 {
-    "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.34.2",
-    "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
-    "keywords": [
-        "mcp",
-        "szcd",
-        "component",
-        "ai",
-        "agent",
-        "claude",
-        "trae",
-        "qoder",
-        "qwen",
-        "skill",
-        "client"
-    ],
-    "author": "szc-ft",
-    "license": "MIT",
-    "type": "module",
-    "main": "mcp-proxy.js",
-    "bin": {
-        "szcd-mcp-proxy": "mcp-proxy.js",
-        "szcd-mcp-setup": "scripts/postinstall.js",
-        "szcd-mcp-install-shortcuts": "scripts/install-dev-shortcuts.js",
-        "szcd-mcp-update-url": "scripts/update-mcp-url.js",
-        "szcd-mcp-coding-config": "scripts/update-coding-config.js",
-        "szcd-mcp-api-config": "scripts/update-api-config.js",
-        "szcd-mcp-auth": "scripts/update-auth.js"
-    },
-    "files": [
-        "mcp-proxy.js",
-        "local-browser-executor.js",
-        "lib/",
-        "scripts/postinstall.js",
-        "scripts/install-dev-shortcuts.js",
-        "scripts/update-mcp-url.js",
-        "scripts/update-coding-config.js",
-        "scripts/update-api-config.js",
-        "scripts/update-auth.js",
-        "scripts/lib/",
-        "standard-skill/",
-        "agents/",
-        "commands/",
-        "qwen-extension/",
-        "opencode-extension/",
-        "AGENTS.md",
-        "README.md"
-    ],
-    "engines": {
-        "node": ">=18"
-    },
-    "scripts": {
-        "postinstall": "node scripts/postinstall.js",
-        "setup": "node scripts/postinstall.js",
-        "setup:quick": "node scripts/postinstall.js --quick",
-        "build:agents": "node agents/build.js",
-        "prepublishOnly": "node agents/build.js"
-    },
-    "dependencies": {
-        "@modelcontextprotocol/sdk": "^1.29.0",
-        "yaml": "^2.9.0"
-    },
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/szc-ft/mcp-szcd.git"
-    },
-    "bugs": {
-        "url": "https://github.com/szc-ft/mcp-szcd/issues"
-    },
-    "homepage": "https://github.com/szc-ft/mcp-szcd#readme"
+  "name": "@szc-ft/mcp-szcd-client",
+  "version": "0.38.0",
+  "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
+  "keywords": [
+    "mcp",
+    "szcd",
+    "component",
+    "ai",
+    "agent",
+    "claude",
+    "trae",
+    "qoder",
+    "qwen",
+    "skill",
+    "client"
+  ],
+  "author": "szc-ft",
+  "license": "MIT",
+  "type": "module",
+  "main": "mcp-proxy.js",
+  "bin": {
+    "szcd-mcp-proxy": "mcp-proxy.js",
+    "szcd-mcp-setup": "scripts/postinstall.js",
+    "szcd-mcp-install-shortcuts": "scripts/install-dev-shortcuts.js",
+    "szcd-mcp-update-url": "scripts/update-mcp-url.js",
+    "szcd-mcp-coding-config": "scripts/update-coding-config.js",
+    "szcd-mcp-api-config": "scripts/update-api-config.js",
+    "szcd-mcp-auth": "scripts/update-auth.js"
+  },
+  "files": [
+    "mcp-proxy.js",
+    "local-browser-executor.js",
+    "lib/",
+    "scripts/postinstall.js",
+    "scripts/install-dev-shortcuts.js",
+    "scripts/update-mcp-url.js",
+    "scripts/update-coding-config.js",
+    "scripts/update-api-config.js",
+    "scripts/update-auth.js",
+    "scripts/lib/",
+    "standard-skill/",
+    "agents/",
+    "commands/",
+    "qwen-extension/",
+    "opencode-extension/",
+    "AGENTS.md",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "setup": "node scripts/postinstall.js",
+    "setup:quick": "node scripts/postinstall.js --quick",
+    "build:agents": "node agents/build.js",
+    "prepublishOnly": "node agents/build.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "yaml": "^2.9.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/szc-ft/mcp-szcd.git"
+  },
+  "bugs": {
+    "url": "https://github.com/szc-ft/mcp-szcd/issues"
+  },
+  "homepage": "https://github.com/szc-ft/mcp-szcd#readme"
 }

package/qwen-extension/qwen-extension.json

@@ -1,6 +1,6 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.34.2",
+    "version": "0.38.0",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {
@@ -11,6 +11,15 @@
             "type": "stdio",
             "command": "sketch-mcp-server",
             "args": []
+        },
+        "shadcn": {
+            "type": "stdio",
+            "command": "npx",
+            "args": [
+                "-y",
+                "shadcn@latest",
+                "mcp"
+            ]
         }
     },
     "contextFileName": "QWEN.md",

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

@@ -1307,3 +1307,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/qwen-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 永久保留

package/qwen-extension/skills/local-browser-test/lib/api-call-executor.js

@@ -0,0 +1,251 @@
+/**
+ * apiCall step 增强执行器（PR #8 v3 走法 P）
+ *
+ * 关键设计：
+ *   - API 步骤走 Node 18+ 内置 fetch（**不通过浏览器**，但自动共享 context.cookies()）
+ *   - UI 步骤走 page（真实浏览器，CDP）
+ *   - 同一 testCase 跑（UI + API 混合），cookie 自动共享
+ *   - 首次 = 回归 = 真实行为（永远一致）
+ *   - 不引入 newman 依赖
+ *   - 不引入 axios 依赖（用 fetch 即可，Node 18+ 内置）
+ *
+ * 6 个新字段：
+ *   - assert: L1 status / L2 header / L3 body path / L4 responseTime
+ *   - captureTrace: HAR-like trace 录制（PR #5 trace-collector 集成）
+ *   - noRetry: 写操作禁重试（PR #6 retry-policy 集成）
+ *   - strategy: plan 显式（newman / browser / auto）
+ *   - headers: 自定义请求头
+ *   - tags: 用例标签（PR #7）
+ */
+
+import { redact } from './redact.js';
+
+/**
+ * apiCall step 增强 schema
+ * @typedef {object} ApiCallStep
+ * @property {'apiCall'} type
+ * @property {string} method
+ * @property {string} url
+ * @property {object} [headers]
+ * @property {object} [body]
+ * @property {object} [assert] - L1-L4 断言
+ * @property {boolean} [captureTrace] - 是否记录 trace
+ * @property {boolean} [noRetry] - 写操作禁重试（默认 true）
+ * @property {string} [strategy] - plan 显式（newman / browser / auto）
+ * @property {string[]} [tags] - 用例标签
+ */
+
+/**
+ * 共享 cookie header（PR #8 关键设计）
+ * @param {Array<{name: string, value: string, domain?: string}>} cookies
+ * @param {string} [targetOrigin]
+ * @returns {string} Cookie 头（空字符串如果无 cookie）
+ */
+export function buildCookieHeader(cookies, targetOrigin) {
+    if (!Array.isArray(cookies) || cookies.length === 0) return '';
+    const filtered = targetOrigin
+        ? cookies.filter((c) => c.domain?.endsWith(targetOrigin.replace(/^https?:\/\//, '')))
+        : cookies;
+    return filtered.map((c) => `${c.name}=${c.value}`).join('; ');
+}
+
+/**
+ * ★ axios interceptor 工厂：记录 timings（PR #5 + PR #8）
+ * @param {object} collector - { timings: Array<{name, url, method, total}> }
+ * @returns {{ request: Function, response: Function, error: Function }}
+ */
+export function createTimingsInterceptor(collector) {
+    return {
+        request(config) {
+            config.metadata = { startTime: process.hrtime.bigint() };
+            return config;
+        },
+        response(response) {
+            const ns = process.hrtime.bigint() - response.config.metadata.startTime;
+            const total = Number(ns / 1000000n);  // ms
+            collector.timings.push({
+                name: response.config.metadata.name ?? '',
+                url: response.config.url,
+                method: response.config.method?.toUpperCase(),
+                total,
+                status: response.status
+            });
+            response.config.metadata.total = total;
+            return response;
+        },
+        error(error) {
+            if (error.config?.metadata) {
+                const ns = process.hrtime.bigint() - error.config.metadata.startTime;
+                error.config.metadata.total = Number(ns / 1000000n);
+            }
+            return Promise.reject(error);
+        }
+    };
+}
+
+/**
+ * L1-L4 断言引擎
+ * @param {object} response - axios response
+ * @param {object} assertSpec - 断言规格
+ * @returns {{passed: boolean, checks: Array<{name: string, level: number, passed: boolean, actual: any, expected: any, error?: string}>}}
+ */
+export function assertApiResponse(response, assertSpec) {
+    const checks = [];
+    let allPassed = true;
+
+    // L1: status code
+    if (assertSpec.status !== undefined) {
+        const actual = response.status;
+        const expected = assertSpec.status;
+        const passed = actual === expected;
+        checks.push({ name: `Status is ${expected}`, level: 1, actual, expected, passed });
+        if (!passed) allPassed = false;
+    }
+
+    // L2: header
+    if (assertSpec.headers) {
+        for (const [key, expected] of Object.entries(assertSpec.headers)) {
+            const actual = response.headers?.[key.toLowerCase()];
+            const passed = actual === expected;
+            checks.push({ name: `Header ${key}=${expected}`, level: 2, actual, expected, passed });
+            if (!passed) allPassed = false;
+        }
+    }
+
+    // L3: body path
+    if (assertSpec.body) {
+        for (const [path, expected] of Object.entries(assertSpec.body)) {
+            const actual = getByPath(response.data, path);
+            const passed = matchValue(actual, expected);
+            checks.push({ name: `Body ${path} = ${JSON.stringify(expected)}`, level: 3, actual, expected, passed });
+            if (!passed) allPassed = false;
+        }
+    }
+
+    // L4: response time
+    if (assertSpec.responseTime !== undefined) {
+        const total = response.config?.metadata?.total ?? 0;
+        const expected = assertSpec.responseTime;
+        const passed = total < expected;
+        checks.push({ name: `Response time < ${expected}ms`, level: 4, actual: total, expected, passed });
+        if (!passed) allPassed = false;
+    }
+
+    return { passed: allPassed, checks };
+}
+
+/**
+ * 路径取值（点号访问嵌套对象）
+ */
+function getByPath(obj, path) {
+    return String(path).split('.').reduce((o, k) => o?.[k], obj);
+}
+
+/**
+ * 操作符匹配
+ * @param {any} actual
+ * @param {any} expected - 可以是值 / { $gt: n } / { $lt: n } / { $contains: 'x' } / { $regex: 'p' }
+ */
+function matchValue(actual, expected) {
+    if (expected && typeof expected === 'object' && !Array.isArray(expected)) {
+        if ('$gt' in expected && actual > expected.$gt) return true;
+        if ('$lt' in expected && actual < expected.$lt) return true;
+        if ('$gte' in expected && actual >= expected.$gte) return true;
+        if ('$lte' in expected && actual <= expected.$lte) return true;
+        if ('$contains' in expected && String(actual ?? '').includes(expected.$contains)) return true;
+        if ('$regex' in expected && new RegExp(expected.$regex).test(String(actual ?? ''))) return true;
+        if ('$in' in expected && Array.isArray(expected.$in) && expected.$in.includes(actual)) return true;
+        return false;
+    }
+    return actual === expected;
+}
+
+/**
+ * 执行 apiCall step（v3 走法 P：不通过浏览器，走 axios）
+ * @param {ApiCallStep} step
+ * @param {object} ctx - { baseURL, cookies, traceCollector? }
+ * @returns {Promise<{
+ *   name: string, status: 'passed'|'failed', duration: number,
+ *   request: object, response: object,
+ *   assertions: Array, trace: object|null, error: object|null
+ * }>}
+ */
+export async function executeApiCallStep(step, ctx = {}) {
+    const startTime = Date.now();
+    const method = (step.method || 'POST').toUpperCase();
+    const timings = [];
+    const collector = { timings };
+
+    // 1. 构造 axios request：自动共享 context.cookies()
+    const cookieHeader = buildCookieHeader(ctx.cookies ?? [], ctx.baseURL);
+    const request = axios.create({
+        baseURL: ctx.baseURL,
+        headers: {
+            Cookie: cookieHeader,
+            'Content-Type': 'application/json',
+            ...step.headers
+        },
+        // 让 axios 接受任意状态码（不抛错）
+        validateStatus: () => true
+    });
+
+    // 2. ★ axios interceptor（PR #5 + PR #8）
+    const interceptor = createTimingsInterceptor(collector);
+    request.interceptors.request.use(interceptor.request);
+    request.interceptors.response.use(interceptor.response, interceptor.error);
+
+    // 3. 发请求
+    let response;
+    let error = null;
+    try {
+        response = await request({
+            method,
+            url: step.url,
+            data: step.body
+        });
+    } catch (e) {
+        error = {
+            message: e.message ?? String(e),
+            code: e.code ?? null
+        };
+    }
+
+    const duration = Date.now() - startTime;
+    const status = response?.status ?? 0;
+
+    // 4. ★ 断言（PR #8 L1-L4）
+    let assertionResults = [];
+    let passed = error == null && status >= 200 && status < 300;  // 默认通过 = 2xx
+    if (step.assert && response) {
+        const assertResult = assertApiResponse(response, step.assert);
+        assertionResults = assertResult.checks;
+        if (!assertResult.passed) {
+            passed = false;
+        }
+    }
+
+    // 5. ★ 构造返回值（脱敏 + 统一 schema）
+    const safeResponse = response ? {
+        status: response.status,
+        statusText: response.statusText,
+        duration: response.config?.metadata?.total ?? 0,
+        headers: redact(response.headers ?? {}),
+        body: redact(response.data)
+    } : null;
+
+    return {
+        name: step.name ?? `${method} ${step.url}`,
+        status: passed ? 'passed' : 'failed',
+        duration,
+        request: {
+            method,
+            url: step.url,
+            headers: redact(step.headers ?? {}),
+            body: redact(step.body)
+        },
+        response: safeResponse,
+        assertions: assertionResults,
+        trace: step.captureTrace ? { timings: collector.timings } : null,
+        error
+    };
+}