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

package/scripts/postinstall.js

@@ -82,7 +82,7 @@ function createConfigTemplate() {
 
 // ==================== 成功信息 ====================
 
-function showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult) {
+function showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult, openCodeResult) {
     const configPath = common.getConfigFilePath();
     const projectRoot = common.PROJECT_ROOT;
 
@@ -97,6 +97,7 @@ function showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult) {
     console.log(`   Claude Code:  ${path.join(claudeResult.skillsDirectory, common.getMcpServerName(), "SKILL.md")}`);
     console.log(`   Qwen Code:    ${path.join(qwenResult.skillsDirectory, common.getMcpServerName(), "SKILL.md")}`);
     console.log(`   Qoder CLI:    ${path.join(qoderResult.skillsDirectory, common.getMcpServerName(), "SKILL.md")}`);
+    console.log(`   OpenCode:     ${path.join(openCodeResult.skillsDirectory, common.getMcpServerName(), "SKILL.md")}`);
     if (traeResult.traeProjectInstalled) {
         console.log(`   Trae Project: ${path.join(projectRoot, ".trae", "skills", common.getMcpServerName(), "SKILL.md")}`);
     }
@@ -109,6 +110,12 @@ function showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult) {
     if (qoderResult.qoderProjectInstalled) {
         console.log(`   Qoder Project: ${path.join(projectRoot, ".qoder", "skills", common.getMcpServerName(), "SKILL.md")}`);
     }
+    // 项目级配置暂不启用
+    /*
+    if (openCodeResult.openCodeProjectInstalled) {
+        console.log(`   OpenCode Project: ${path.join(projectRoot, ".opencode", "skills", common.getMcpServerName(), "SKILL.md")}`);
+    }
+    */
 
     console.log("\n⚙️  Configuration Files:");
     console.log(`   1. Config file:         ${configPath}`);
@@ -116,6 +123,7 @@ function showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult) {
     console.log(`   3. Claude Code:         via 'claude mcp add'`);
     console.log(`   4. Qwen Code:           via 'qwen extensions install'`);
     console.log(`   5. Qoder CLI:           via 'qoder mcp add'`);
+    console.log(`   6. OpenCode:            via 'opencode mcp add'`);
 
     console.log("\n📝 Edit the config file to set your MCP server URL:");
     console.log(`      "MCP_SERVER_URL": "http://YOUR_SERVER_IP:3456"`);
@@ -131,6 +139,8 @@ function showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult) {
     console.log(`     qwen mcp add --transport http --scope user ${common.getMcpServerName()} ${common.getMcpServerUrl()}/mcp`);
     console.log("\n   For Qoder CLI (via CLI):");
     console.log(`     qoder mcp add ${common.getMcpServerName()} -s user -- ${common.getMcpServerUrl()}/mcp`);
+    console.log("\n   For OpenCode (via CLI):");
+    console.log(`     opencode mcp add ${common.getMcpServerName()} --scope user --url ${common.getMcpServerUrl()}/mcp`);
 
     console.log("\n💡 Configuration Priority:");
     console.log("   1. Environment variables (highest priority)");
@@ -169,7 +179,8 @@ function main() {
 
         // ---- 配置文件 ----
         createConfigTemplate();
-        setupOpenCode(deps);
+        console.log("\n🔧 Setting up OpenCode compatibility...\n");
+        const openCodeResult = setupOpenCode(deps);
 
         // ---- Trae CLI ----
         console.log("\n🔧 Setting up Trae CLI compatibility...\n");
@@ -187,7 +198,7 @@ function main() {
         console.log("\n🔧 Setting up Qoder CLI compatibility...\n");
         const qoderResult = setupQoder(deps);
 
-        showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult);
+        showSuccessMessage(traeResult, claudeResult, qwenResult, qoderResult, openCodeResult);
     } catch (error) {
         console.error("\n❌ Error during installation:", error.message);
         console.error("Please report this issue at: https://github.com/szc-ft/szcd/issues");

package/scripts/update-mcp-url.js

@@ -32,6 +32,7 @@ import { syncMcpUrl as syncTraeIde } from "./lib/trae-ide.js";
 import { syncMcpUrl as syncClaudeCode } from "./lib/claude-code.js";
 import { syncMcpUrl as syncQwenCode } from "./lib/qwen-code.js";
 import { syncMcpUrl as syncQoder } from "./lib/qoder.js";
+import { syncMcpUrl as syncOpenCode } from "./lib/opencode.js";
 
 const DEFAULT_MCP_SERVER_NAME = "szcd-component-helper";
 const DEFAULT_MCP_SERVER_URL = "http://localhost:3456";
@@ -183,6 +184,7 @@ function main() {
     syncClaudeCode(targetUrl, serverName);
     syncQwenCode(targetUrl, serverName);
     syncQoder(targetUrl, serverName);
+    syncOpenCode(targetUrl, serverName);
 
     console.log(`\n✅ Done! MCP_SERVER_URL = ${targetUrl}`);
     console.log(`\n📋 Updated configuration files:`);
@@ -192,6 +194,7 @@ function main() {
     console.log(`   ${path.join(getHomeDir(), ".claude.json")}`);
     console.log(`   ${path.join(getHomeDir(), ".qwen", "settings.json")}`);
     console.log(`   ${path.join(getHomeDir(), ".qoder", "settings.json")}`);
+    console.log(`   ${path.join(getHomeDir(), ".config", "opencode", "opencode.jsonc")}`);
     console.log(`\n💡 Restart your IDE/CLI for changes to take effect.\n`);
 }
 

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