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

package/opencode-extension/skills/local-api-tool/SKILL.md

@@ -0,0 +1,246 @@
+---
+name: local-api-tool
+description: 本地网络 API 工具，专门处理 10.x.x.x 网段的 Swagger/YApi 文档拉取和联调测试。当服务端 api_tool 因 LOCAL_NETWORK_UNREACHABLE 无法访问时，此技能在用户本地环境执行 curl，再将结果交给服务端解析。适用于内网开发环境、VPN 场景。**仅限 10.x.x.x 网段**，172.16-31.x.x 和 192.168.x.x 服务端可直连，不要使用本技能。
+compatibility:
+  tools:
+    - run_command
+    - web_search
+    - web_fetch
+---
+
+# 本地网络 API 工具（local-api-tool）
+
+## 概述
+
+当 MCP 服务端 `api_tool` 遇到 `10.x.x.x` 网段地址时，因服务器无法直连用户内网，会返回 `reason: "LOCAL_NETWORK_UNREACHABLE"` 及 `action` 字段指引。此技能指导 AI 自动在用户本地终端通过 `run_command` 执行 curl 命令获取数据，再调用服务端的 `parse_swagger_json` 进行解析，全程无需用户手动操作。
+
+## 适用场景
+
+- Swagger URL 主机为 `10.x.x.x` 网段（如 `http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/index.html`）
+- API 联调测试目标为 `10.x.x.x` 网段
+- 用户在 VPN 或内网开发环境中，本地可访问但远程服务器不可达
+
+## ⚠️ 网段区分（重要）
+
+**仅 `10.x.x.x` 网段需要走本地解析，其他私有网段服务端均可直连，切勿误用本技能：**
+
+| 网段 | 是否需要本地解析 | 原因 | 处理方式 |
+|------|:---:|------|------|
+| `10.x.x.x` | **是** | 用户本地可达，服务端不可达 | 使用本技能在本地 curl |
+| `172.16-31.x.x` | **否** | 服务端可直接访问 | 直接调用 api_tool，无需本技能 |
+| `192.168.x.x` | **否** | 服务端通过弹性 IP 映射访问 | 直接调用 api_tool，无需本技能 |
+| 公网 IP | **否** | 服务端可直接访问 | 直接调用 api_tool，无需本技能 |
+
+**禁止对 172.16-31.x.x 和 192.168.x.x 使用本技能！** 这些地址虽然也是 RFC 1918 私有地址，但服务端网络环境可以直达，不需要在用户本地执行 curl。
+
+## 工作流
+
+### 流程 A：拉取 Swagger API 文档（fetch）
+
+```
+用户请求 fetch Swagger URL (10.x.x.x)
+    │
+    ▼
+调用 api_tool(action="fetch", url=...)
+    │
+    ▼
+服务端返回 { reason: "LOCAL_NETWORK_UNREACHABLE", action: "请使用 local-api-tool ...", swaggerEndpoints: {...} }
+    │
+    ▼
+AI 识别 LOCAL_NETWORK_UNREACHABLE，读取 swaggerEndpoints 和 authInfo
+    │
+    ▼
+AI 通过 run_command 在本地执行 curl：
+  步骤1: 鉴权获取 Cookie（如 authInfo.hasPassword 为 true）
+  步骤2: 获取完整 API 文档 JSON
+    │
+    ▼
+AI 调用 api_tool(action="parse_swagger_json", swaggerJson=..., swaggerSourceUrl=...)
+    │
+    ▼
+返回解析后的 API 文档给用户
+```
+
+### 流程 B：联调测试（test）
+
+```
+用户请求 test API (10.x.x.x)
+    │
+    ▼
+调用 api_tool(action="test", url=..., method=..., data=..., headers=...)
+    │
+    ▼
+服务端返回 { reason: "LOCAL_NETWORK_UNREACHABLE", action: "请使用 local-api-tool ...", method, data, headers }
+    │
+    ▼
+AI 识别 LOCAL_NETWORK_UNREACHABLE，读取 method/data/headers
+    │
+    ▼
+AI 通过 run_command 在本地执行对应 curl 命令
+    │
+    ▼
+将响应结果返回给用户
+```
+
+## 详细执行步骤
+
+### 一、拉取 Swagger 文档（action=fetch）
+
+**步骤 1：调用服务端 api_tool**
+
+```
+api_tool(action="fetch", url="http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/index.html", username="admin", password="xxx")
+```
+
+**步骤 2：检测 LOCAL_NETWORK_UNREACHABLE**
+
+如果返回结果中包含 `reason: "LOCAL_NETWORK_UNREACHABLE"`，则自动进入本地执行流程。
+
+返回结构示例：
+```json
+{
+  "reason": "LOCAL_NETWORK_UNREACHABLE",
+  "hostname": "10.2.7.60",
+  "swaggerUrl": "http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/index.html",
+  "authInfo": { "username": "admin", "hasPassword": true },
+  "swaggerEndpoints": {
+    "basePath": "http://10.2.7.60:30194/ikmp-knowledge",
+    "apiDocsUrl": "http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs"
+  },
+  "action": "请使用 local-api-tool 技能处理此请求..."
+}
+```
+
+**步骤 3：AI 通过 run_command 在本地执行 curl**
+
+根据返回数据中的 `authInfo` 和 `swaggerEndpoints`，AI 自行构造 curl 命令并通过 `run_command` 在本地执行：
+
+3a. **鉴权（如 authInfo.hasPassword 为 true）**：
+
+```bash
+curl -s -D - -X GET 'http://10.2.7.60:30194/ikmp-knowledge/swagger-resources/configuration/ui' \
+  -H 'Authorization: Basic <base64(username:password)>' \
+  -H 'Accept: application/json'
+```
+
+从输出的 `Set-Cookie:` 行提取 Cookie 值（分号前的部分）。
+
+3b. **获取 API 文档 JSON**：直接使用 `swaggerEndpoints.apiDocsUrl`：
+
+```bash
+curl -s -X GET 'http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs' \
+  -H 'Accept: application/json' \
+  -H 'Cookie: <步骤3a获取的Cookie>'
+```
+
+如果 authInfo.hasPassword 为 false，省略 Cookie 头。
+
+**步骤 4：调用服务端解析**
+
+```
+api_tool(action="parse_swagger_json", swaggerJson="<步骤3b获取的JSON字符串>", swaggerSourceUrl="http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/index.html")
+```
+
+**步骤 5：返回解析结果**
+
+将 `parse_swagger_json` 返回的解析结果直接返回给用户，格式与正常 fetch 完全一致。
+
+### 二、联调测试（action=test）
+
+**步骤 1：调用服务端 api_tool**
+
+```
+api_tool(action="test", url="http://10.2.7.60:30194/ikmp-knowledge/api/xxx", method="POST", data={...}, headers={...})
+```
+
+**步骤 2：检测 LOCAL_NETWORK_UNREACHABLE**
+
+如果返回结果中包含 `reason: "LOCAL_NETWORK_UNREACHABLE"`，则自动进入本地执行流程。
+
+返回结构示例：
+```json
+{
+  "success": false,
+  "reason": "LOCAL_NETWORK_UNREACHABLE",
+  "hostname": "10.2.7.60",
+  "targetUrl": "http://10.2.7.60:30194/ikmp-knowledge/api/xxx",
+  "method": "POST",
+  "data": { "key": "value" },
+  "headers": {},
+  "action": "请使用 local-api-tool 技能处理此请求...",
+  "timestamp": "..."
+}
+```
+
+**步骤 3：AI 通过 run_command 在本地执行 curl**
+
+AI 根据返回数据中的 `method`、`data`、`headers`、`targetUrl` 自行构造 curl 命令：
+
+GET 请求示例：
+```bash
+curl -s -X GET 'http://10.2.7.60:30194/ikmp-knowledge/api/xxx?key=value' \
+  -H 'Accept: application/json'
+```
+
+POST 请求示例：
+```bash
+curl -s -X POST 'http://10.2.7.60:30194/ikmp-knowledge/api/xxx' \
+  -H 'Accept: application/json' \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"value"}'
+```
+
+如有自定义 headers，添加对应的 `-H` 参数。
+
+**步骤 4：返回测试结果**
+
+将 curl 的响应内容返回给用户。如果是 JSON 格式，尽量格式化输出。
+
+## 快捷方式：AI 直接识别 10 段地址
+
+如果 AI 能识别出用户请求的 URL 中包含 `10.x.x.x` 主机地址，可以**直接跳过首次 api_tool 调用**，在本地执行 curl，再调用 `parse_swagger_json`，减少一次无用的服务端请求：
+
+1. 从 Swagger URL 推导鉴权地址、文档地址
+2. 通过 `run_command` 在本地依次 curl
+3. 调用 `api_tool(action="parse_swagger_json")` 解析
+
+### URL 推导规则
+
+对于 Swagger URL 如 `http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/index.html`：
+
+| 推导项 | 规则 | 示例 |
+|--------|------|------|
+| basePath | `protocol + host + 第一个路径段` | `http://10.2.7.60:30194/ikmp-knowledge` |
+| authUrl | `basePath + /swagger-resources/configuration/ui` | `http://10.2.7.60:30194/ikmp-knowledge/swagger-resources/configuration/ui` |
+| apiDocsUrl | `basePath + /v2/api-docs` | `http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs` |
+
+### curl 执行模板
+
+**鉴权（带密码时）：**
+```bash
+curl -s -D - -X GET '<authUrl>' \
+  -H 'Authorization: Basic <base64(username:password)>' \
+  -H 'Accept: application/json'
+```
+
+**获取文档（带 Cookie 时）：**
+```bash
+curl -s -X GET '<apiDocsUrl>' \
+  -H 'Accept: application/json' \
+  -H 'Cookie: <鉴权获取的Cookie>'
+```
+
+**获取文档（无密码时）：**
+```bash
+curl -s -X GET '<apiDocsUrl>' \
+  -H 'Accept: application/json'
+```
+
+## 注意事项
+
+1. **Cookie 传递**：鉴权步骤获取的 Cookie 需要在后续步骤中通过 `-H 'Cookie: xxx'` 传递
+2. **无密码场景**：如果用户未提供密码，跳过鉴权步骤，直接获取文档
+3. **JSON 格式**：curl 获取的 API 文档必须是有效的 Swagger JSON，否则 `parse_swagger_json` 会报错
+4. **超时处理**：本地 curl 可能因网络原因超时，建议添加 `--connect-timeout 10 --max-time 30` 参数
+5. **错误处理**：如果某步骤 curl 失败，将错误信息返回给用户，不要继续后续步骤
+6. **自动执行**：AI 识别 `reason: "LOCAL_NETWORK_UNREACHABLE"` 后应**自动**通过 `run_command` 执行 curl，无需让用户手动复制粘贴命令

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

@@ -0,0 +1,249 @@
+---
+name: local-browser-test
+description: 本地浏览器测试工具，在用户本地 Chrome 中执行自动化测试。支持设计稿还原度对比（像素级评分）、功能验证（点击/输入/导航）、DOM 结构检查、JS 错误检测。通过 puppeteer-core 连接用户真实浏览器，天然继承登录态和微前端环境。
+compatibility:
+  tools:
+    - run_command
+    - read_file
+---
+
+# 本地浏览器测试工具（local-browser-test）
+
+## 触发条件
+
+当用户说出以下关键词时启动浏览器测试：
+- "测试一下"、"帮我验证"、"浏览器测试"
+- "对比设计稿"、"还原度"、"看看效果"
+- "功能测试"、"能不能正常用"
+- "检查页面"、"页面渲染"
+
+## 浏览器模式
+
+支持两种模式，执行器自动检测优先使用 connect：
+
+### connect 模式（推荐）
+连接用户已启动的调试 Chrome，天然继承登录态/微前端环境。
+
+用户一次性配置：
+```bash
+# macOS
+open -a "Google Chrome" --args --remote-debugging-port=9222
+# Linux
+google-chrome --remote-debugging-port=9222
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222
+```
+
+### launch 模式（回退）
+启动新的 headless Chrome，需要用户提供可直接访问的 URL。
+
+执行器会自动检测 localhost:9222 是否可用，有则 connect，无则 launch。
+
+## 测试计划 Schema
+
+AI 直接构造测试计划 JSON：
+
+```json
+{
+    "planId": "<uuid>",
+    "description": "<测试描述>",
+    "steps": [ ... ],
+    "options": {
+        "viewport": { "width": 1440, "height": 900 },
+        "timeout": 120000,
+        "outputDir": "/tmp/browser-test-<planId>"
+    }
+}
+```
+
+### 支持的步骤类型
+
+| type | 功能 | 参数 | 返回 |
+|------|------|------|------|
+| 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 }` |
+| 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 }` |
+
+### 场景选择策略
+
+根据上下文自动选择步骤组合：
+
+**场景 A：有设计稿 + 功能验证（最完整）**
+`navigate → waitFor → screenshot → compare → 功能步骤`
+
+**场景 B：无设计稿 + 功能验证**
+`navigate → waitFor → screenshot → evaluate(JS错误检查) → 功能步骤`
+
+**场景 C：仅视觉对比**
+`navigate → waitFor → screenshot → compare`
+
+**场景 D：仅页面检查**
+`navigate → waitFor → screenshot → evaluate(JS错误检查)`
+
+**场景 E：微前端 + SSO 登录（最常见生产场景）**
+`findPage(按路径发现标签页) → findFrame(按内容发现iframe) → 在 iframe 内执行功能步骤`
+
+> 微前端场景端口可变，优先用 `findPage` + `findFrame` 发现页面，而非硬编码 URL 导航。
+
+### 构造步骤的指导原则
+
+1. **selector 必须从用户代码中读取，不要猜测**
+   - 读代码中的 `id`、`className`、`data-testid`
+   - szcd 组件的 class 可通过 `get_component_full_profile` 获取
+2. **API 路径从代码中的接口调用读取**
+3. **checkElement 的 expect 从代码逻辑推断**
+   - columns 定义了 N 列 → `expect: { minCount: N }`（检查 th 数量）
+   - 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 \
+  --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 \
+  --base-url http://localhost:8088
+```
+
+### 可选参数
+
+- `--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
+cd ~/.szcd-mcp/deps && npm install puppeteer-core pixelmatch pngjs sharp --registry=https://npmmirror.com
+```
+
+## 结果解读
+
+### 还原度评分
+- fidelity >= 95%：还原度优秀
+- fidelity 90-95%：还原度良好，有优化空间
+- fidelity < 90%：还原度不足，需要调整
+
+### 功能测试
+- passed = total：全部通过
+- 有失败步骤：根据 `step` + `error` 字段定位代码问题
+
+### 结果文件结构
+```json
+{
+    "planId": "xxx",
+    "mode": "connect",
+    "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, ... }
+    ],
+    "summary": {
+        "total": 5, "passed": 4, "failed": 1,
+        "fidelity": 94.7
+    },
+    "outputDir": "/tmp/browser-test-xxx"
+}
+```