@szc-ft/mcp-szcd-client 0.19.1 → 0.20.0

package/qwen-extension/commands/szcd-mcp-coding-config.md

@@ -1,6 +1,6 @@
 ---
-description: 管理CODING Issue工具的默认配置（baseUrl/projectId/account）
-argument-hint: <get|set|clear> [--baseUrl=xxx] [--projectId=yyy] [--account=zzz]
+description: 管理CODING Issue工具的默认配置（baseUrl/account）
+argument-hint: <get|set|clear> [--baseUrl=xxx] [--account=yyy]
 ---
 
 请帮我管理 szcd MCP 的 CODING 默认配置。
@@ -18,11 +18,10 @@ argument-hint: <get|set|clear> [--baseUrl=xxx] [--projectId=yyy] [--account=zzz]
 
    - **设置配置**：逐项向用户询问以下参数，选项中提供当前值作为默认，用户也可自由输入新值：
      - CODING_BASE_URL — CODING 基础地址，如 `http://e-kjr1wok.coding.smartcitysz.work`
-     - CODING_DEFAULT_PROJECT_ID — 默认项目 ID，如 `907`
      - CODING_ACCOUNT — 默认账号（邮箱）
      收集完参数后执行：
      ```bash
-     npx szcd-mcp-coding-config set --baseUrl="<baseUrl>" --projectId="<projectId>" --account="<account>"
+     npx szcd-mcp-coding-config set --baseUrl="<baseUrl>" --account="<account>"
      ```
 
    - **清除配置**：确认后执行 `npx szcd-mcp-coding-config clear`
@@ -33,10 +32,9 @@ argument-hint: <get|set|clear> [--baseUrl=xxx] [--projectId=yyy] [--account=zzz]
 
 **配置字段说明**：
 - `CODING_BASE_URL` — CODING 基础地址
-- `CODING_DEFAULT_PROJECT_ID` — 默认项目 ID
 - `CODING_ACCOUNT` — 默认账号（邮箱）
 
-配置保存在 `~/.szcd-mcp-config.json` 中，设置后 `coding_fetch_issue` 工具可省略 `baseUrl` 和 `projectId` 参数。
+配置保存在 `~/.szcd-mcp-config.json` 中，设置后 `coding_fetch_issue` 工具可省略 `baseUrl` 参数。
 
 当前配置:
 !`cat ~/.szcd-mcp-config.json 2>/dev/null | grep -E "CODING|MCP_SERVER" || echo "配置文件不存在或无 CODING 配置"`

package/qwen-extension/qwen-extension.json

@@ -1,6 +1,6 @@
 {
     "name": "szcd-component-helper",
-    "version": "0.19.1",
+    "version": "0.20.0",
     "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
     "mcpServers": {
         "szcd-component-helper": {

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

@@ -68,6 +68,10 @@ AI 直接构造测试计划 JSON：
 | waitFor | 等待条件 | `selector` 或 `url`, `timeout` | `{ matched, waited }` |
 | evaluate | 执行 JS | `expression` | `{ result }` |
 | 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 }` |
+| aiAssert | 语义断言（截图+审查） | `assertion`, `filename` | `{ screenshotPath, assertion, needsVisualReview }` |
 
 ### 场景选择策略
 
@@ -85,6 +89,11 @@ AI 直接构造测试计划 JSON：
 **场景 D：仅页面检查**
 `navigate → waitFor → screenshot → evaluate(JS错误检查)`
 
+**场景 E：微前端 + SSO 登录（最常见生产场景）**
+`findPage(按路径发现标签页) → findFrame(按内容发现iframe) → 在 iframe 内执行功能步骤`
+
+> 微前端场景端口可变，优先用 `findPage` + `findFrame` 发现页面，而非硬编码 URL 导航。
+
 ### 构造步骤的指导原则
 
 1. **selector 必须从用户代码中读取，不要猜测**
@@ -96,19 +105,80 @@ AI 直接构造测试计划 JSON：
    - dataSource 有数据 → `expect: { minCount: 1 }`（检查行数）
 4. **compare 的 regions 从设计稿分析结果或组件布局推断**
 
+## 微前端测试指南（实战经验）
+
+项目多使用 wujie/qiankun 微前端，测试时需注意：
+
+### 端口可变问题（重点）
+微前端主应用和子应用的端口会变化，**不要在计划中硬编码 URL**。两种方案：
+
+**方案 A：`findPage` 发现已打开的标签页（推荐，connect 模式）**
+用户已在浏览器中打开了目标页面，按路径或标题发现：
+```json
+{ "type": "findPage", "urlIncludes": "knowledge-main" }
+{ "type": "findPage", "titleIncludes": "知识库" }
+```
+
+**方案 B：URL 模板变量 + `--base-url` 运行时传入**
+计划中使用占位符，运行时替换：
+```json
+{ "type": "navigate", "url": "{{baseUrl}}/knowledge-main/", "allowRedirects": true }
+```
+执行时传入：`--base-url http://localhost:9090`
+
+### SSO 登录重定向链
+主应用访问时会重定向到登录服务，登录后再跳回。
+
+```json
+{ "type": "navigate", "url": "{{baseUrl}}/app/", "allowRedirects": true, "redirectWait": 5000 }
+{ "type": "loginWait", "timeout": 120000, "loginSelector": "input[type='password']" }
+```
+
+- `allowRedirects: true` 使用 `domcontentloaded` 避免重定向链导致 page 对象销毁
+- `loginWait` 轮询检测登录页是否消失（用户手动登录）
+
+### iframe 内操作
+wujie 微前端子应用渲染在 blob URL iframe 中，**坐标点击无法到达 iframe 内容**。
+
+```json
+{ "type": "findFrame", "contentIncludes": "知识采编" }
+{ "type": "click", "selector": "a.edit-btn" }
+{ "type": "checkElement", "selector": "~.editKnowledge", "expect": { "minCount": 1 } }
+```
+
+- `findFrame` 支持 `urlIncludes`、`titleIncludes`、`contentIncludes` 多种发现方式
+- 优先用 `contentIncludes`（按页面文字内容查找），不依赖 URL/端口
+- `findFrame` 后，后续所有步骤自动在 iframe 内执行
+- iframe 内的 click 使用 `evaluate()` 触发 DOM click，不依赖坐标
+
+### CSS Modules 哈希类名
+项目使用 CSS Modules，类名会被哈希化（如 `editKnowledge___ynQgI`）。
+
+选择器语法：
+- `~.editKnowledge` → 自动转为 `[class*="editKnowledge"]`（模糊匹配）
+- `~#myId` → 自动转为 `[id*="myId"]`
+- 普通选择器（如 `.my-class`）保持精确匹配
+
+### puppeteer-core v22 注意事项
+- `page.$x()` 已移除，用 `evaluate` + `querySelectorAll` 替代
+- SVG 元素的 `className` 是 `SVGAnimatedString` 对象而非字符串，需先检查 `typeof`
+- 所有 `evaluate` 调用内部使用 `safeEval` 包装，自动处理 context destroyed 错误
+
 ## 执行命令
 
 ```bash
 node {client_install_path}/local-browser-executor.js \
   --plan '<测试计划JSON>' \
-  --output /tmp/browser-test-result.json
+  --output /tmp/browser-test-result.json \
+  --base-url http://localhost:8088
 ```
 
 也支持从文件读取计划：
 ```bash
 node {client_install_path}/local-browser-executor.js \
   --plan-file /tmp/test-plan.json \
-  --output /tmp/browser-test-result.json
+  --output /tmp/browser-test-result.json \
+  --base-url http://localhost:8088
 ```
 
 ### 可选参数
@@ -116,11 +186,37 @@ node {client_install_path}/local-browser-executor.js \
 - `--cdp-url http://localhost:9223`：指定非默认的 CDP 端口
 - `--page-url http://xxx/page`：connect 模式下指定目标页面
 
-## 依赖检查
+## AI 语义断言（aiAssert）
+
+`aiAssert` 截图后需要视觉审查，三级降级路由：
+
+### Level 1：你能读取图片
+直接读取截图文件，用你的视觉能力判断是否满足断言。
+
+### Level 2：你无法读图，但 MCP 服务器可用
+1. 调用 `get_upload_endpoint` 获取上传地址
+2. 用 curl 上传截图
+3. 调用 `assert_page_screenshot` 工具，传入 `upload_id` + 断言描述
+4. 工具返回 `{ passed, confidence, reasoning, details }`
+
+### Level 3：都没有
+降级为 `checkElement` 步骤，用 DOM 选择器做替代验证。
+
+**构造 aiAssert 步骤示例**：
+```json
+{ "type": "aiAssert", "assertion": "页面显示三栏布局，右侧有滚动条", "filename": "assert-layout.png" }
+{ "type": "aiAssert", "assertion": "表格至少有 5 行数据，包含姓名、手机号列" }
+{ "type": "aiAssert", "assertion": "表单包含必填标记和提交按钮" }
+```
+
+## 依赖管理
 
-如果执行报错依赖缺失，引导用户安装：
+浏览器测试依赖（puppeteer-core, pixelmatch, pngjs, sharp）采用**共享缓存**方案：
+- 首次使用时自动安装到 `~/.szcd-mcp/deps/`
+- 后续所有项目共享复用，无需重复安装
+- 如果自动安装失败，引导用户手动执行：
 ```bash
-npm install puppeteer-core pixelmatch pngjs sharp
+cd ~/.szcd-mcp/deps && npm install puppeteer-core pixelmatch pngjs sharp --registry=https://npmmirror.com
 ```
 
 ## 结果解读