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

package/opencode-extension/commands/szcd-mcp-auth.md

@@ -0,0 +1,39 @@
+---
+description: 管理MCP服务器鉴权密钥（get/set/clear API Key）
+argument-hint: <get|set|clear> [--apiKey=xxx]
+---
+
+请帮我管理 szcd MCP 的鉴权配置。
+
+**交互流程**：
+
+1. **向用户询问要执行的操作**，提供以下选项：
+   - "查看鉴权配置" -> 执行 get
+   - "设置 API Key" -> 执行 set（需进一步追问参数）
+   - "清除 API Key" -> 执行 clear
+
+2. **根据用户选择执行**：
+
+   - **查看鉴权配置**：直接执行 `npx szcd-mcp-auth get`
+
+   - **设置 API Key**：向用户询问 API Key（由 MCP 服务端管理员提供），收集后执行：
+     ```bash
+     npx szcd-mcp-auth set --apiKey="<apiKey>"
+     ```
+
+   - **清除 API Key**：确认后执行 `npx szcd-mcp-auth clear`
+
+3. **命令回退**：如果 npx 不可用，依次尝试：
+   - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-auth.js <args>`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-auth.js <args>`
+
+**配置字段说明**：
+- `MCP_API_KEY` — MCP 服务器鉴权密钥（敏感）
+  - 设置后，客户端连接时自动通过 `X-API-Key` 请求头传递
+  - 服务端需配置相同的 `MCP_API_KEY` 环境变量才会校验
+  - 未设置时，若服务端也未开启鉴权，客户端可正常连接
+
+配置保存在 `~/.szcd-mcp-config.json` 中，设置后重启 IDE/CLI 生效。
+
+当前配置:
+!`cat ~/.szcd-mcp-config.json 2>/dev/null | grep -E "MCP_API_KEY|MCP_SERVER" || echo "配置文件不存在"`

package/opencode-extension/commands/szcd-mcp-browser-test.md

@@ -0,0 +1,57 @@
+---
+description: 在本地浏览器中执行自动化测试（设计稿还原度对比/功能验证/页面检查）
+argument-hint: <目标页面URL> [可选：设计稿图片路径]
+---
+
+请帮我在本地浏览器中执行测试。
+
+**执行流程**：
+
+1. **收集测试信息**：
+
+   - **目标页面 URL**（必需）：如果用户在命令参数中已提供，直接使用；否则向用户询问要测试的页面地址
+   - **设计稿图片**（可选）：如果用户在命令参数中提供了图片路径，用于还原度对比；否则跳过视觉对比
+   - **测试范围**：向用户提供选项：
+     - "设计稿还原度对比"（需提供设计稿）
+     - "功能验证"（点击/输入/导航等交互测试）
+     - "页面检查"（JS 错误检测 + 页面截图）
+     - "全部测试"（以上全部）
+
+2. **读取 `local-browser-test` skill 文档**，了解 Plan Schema 和执行命令格式：
+   - 按 skill 中定义的步骤类型构造测试计划 JSON
+   - selector 从用户项目代码中读取（`id`/`className`/`data-testid`），不要猜测
+   - 根据用户选择的测试范围选择对应场景（A/B/C/D）
+
+3. **构造测试计划 JSON** 并写入临时文件（避免命令行参数过长）：
+   ```bash
+   cat > /tmp/browser-test-plan.json << 'EOF'
+   {测试计划 JSON}
+   EOF
+   ```
+
+4. **执行测试**：
+   ```bash
+   node {client_install_path}/local-browser-executor.js \
+     --plan-file /tmp/browser-test-plan.json \
+     --output /tmp/browser-test-result.json
+   ```
+
+   命令回退（如果上面的路径不可用）：
+   - `npx szcd-mcp-browser-test --plan-file /tmp/browser-test-plan.json --output /tmp/browser-test-result.json`
+   - `node $(npm root -g)/@szc-ft/mcp-szcd-client/local-browser-executor.js --plan-file /tmp/browser-test-plan.json --output /tmp/browser-test-result.json`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/local-browser-executor.js --plan-file /tmp/browser-test-plan.json --output /tmp/browser-test-result.json`
+
+5. **读取并解读结果**：
+   读取 `/tmp/browser-test-result.json`，按以下标准解读：
+   - **还原度**：fidelity >= 95% 优秀 / 90-95% 良好 / < 90% 不足
+   - **功能测试**：passed = total 全部通过，否则列出失败步骤及原因
+   - **diff 图**：如有 diffImagePath，展示 diff 图路径供用户查看
+
+6. **闭环建议**：
+   - 如有问题，给出具体的修复建议
+   - 询问用户是否需要重新测试
+
+**注意事项**：
+- 首次使用需确保 Chrome 以调试模式启动：`google-chrome --remote-debugging-port=9222`
+- 如执行器报错依赖缺失，引导用户安装：`npm install puppeteer-core pixelmatch pngjs sharp`
+- connect 模式下天然继承用户浏览器的登录态和微前端环境

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

@@ -0,0 +1,40 @@
+---
+description: 管理CODING Issue工具的默认配置（baseUrl/account）
+argument-hint: <get|set|clear> [--baseUrl=xxx] [--account=yyy]
+---
+
+请帮我管理 szcd MCP 的 CODING 默认配置。
+
+**交互流程**：
+
+1. **向用户询问要执行的操作**，提供以下选项：
+   - "查看配置" → 执行 get
+   - "设置配置" → 执行 set（需进一步追问参数）
+   - "清除配置" → 执行 clear
+
+2. **根据用户选择执行**：
+
+   - **查看配置**：直接执行 `npx szcd-mcp-coding-config get`
+
+   - **设置配置**：逐项向用户询问以下参数，选项中提供当前值作为默认，用户也可自由输入新值：
+     - CODING_BASE_URL — CODING 基础地址，如 `http://e-kjr1wok.coding.smartcitysz.work`
+     - CODING_ACCOUNT — 默认账号（邮箱）
+     收集完参数后执行：
+     ```bash
+     npx szcd-mcp-coding-config set --baseUrl="<baseUrl>" --account="<account>"
+     ```
+
+   - **清除配置**：确认后执行 `npx szcd-mcp-coding-config clear`
+
+3. **命令回退**：如果 npx 不可用，依次尝试：
+   - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-coding-config.js <args>`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-coding-config.js <args>`
+
+**配置字段说明**：
+- `CODING_BASE_URL` — CODING 基础地址
+- `CODING_ACCOUNT` — 默认账号（邮箱）
+
+配置保存在 `~/.szcd-mcp-config.json` 中，设置后 `coding_fetch_issue` 工具可省略 `baseUrl` 参数。
+
+当前配置:
+!`cat ~/.szcd-mcp-config.json 2>/dev/null | grep -E "CODING|MCP_SERVER" || echo "配置文件不存在或无 CODING 配置"`

package/opencode-extension/commands/szcd-mcp-feedback.md

@@ -0,0 +1,42 @@
+---
+description: 提交本次会话的代码生成反馈，用于优化 szcd MCP 服务质量
+argument-hint: [可选：评分1-5] [可选：采纳/不采纳]
+---
+
+请帮我提交本次会话的反馈。
+
+**执行流程**：
+
+1. **自动收集上下文**：从当前会话历史中提取以下信息，**不要重复询问用户已经说过的内容**：
+   - `userQuery`：用户最初的原始需求描述（从会话开头的消息中提取）
+   - `toolsUsed`：本次会话中实际调用过的 MCP 工具名称列表（从工具调用记录中提取）
+   - `generatedCodeSummary`：最近一次生成的代码摘要或关键组件列表（从生成的代码中提取前几行或核心结构，不超过 500 字）
+   - `toolType`：当前使用的 IDE 类型（根据运行环境判断：Qoder → "qoder"，Trae → "trae"，Claude → "claude"，Qwen → "qwen"，Cursor → "cursor"，VS Code → "vscode"，其他 → "generic"）
+
+2. **向用户确认或补充**（仅询问缺失的信息）：
+   - **准确性评分**：请用户评分 1-5 分（5 分最准确）。如果用户在命令参数中已提供，直接使用
+   - **是否采纳**：用户是否计划采纳生成的代码。如果用户在命令参数中已提供（"采纳"/"不采纳"），直接使用
+   - **如不采纳**：询问具体原因（组件不匹配、API 错误、缺少功能、不符合设计稿等）
+
+3. **调用 MCP 工具提交反馈**：
+   调用 `submit_feedback` 工具，参数如下：
+   ```
+   sessionId: "<当前会话 ID 或时间戳>"
+   toolsUsed: [自动提取的工具列表]
+   userQuery: "<自动提取的用户需求>"
+   generatedCodeSummary: "<自动提取的代码摘要>"
+   accuracyRating: <用户评分 1-5>
+   adopted: <true/false>
+   rejectionReason: "<不采纳原因，采纳则为空>"
+   contextSnapshot: {
+     可选：从会话中提取的组件方案信息
+   }
+   toolType: "<自动判断的 IDE 类型>"
+   ```
+
+4. **输出结果**：告知用户反馈是否提交成功，显示 feedbackId
+
+**注意事项**：
+- 如果当前会话中没有代码生成记录，提示用户"当前会话中没有代码生成记录，反馈提交需要有生成代码的上下文"
+- 尽可能从会话历史自动提取信息，减少用户手动输入
+- 反馈提交失败不影响已生成的代码

package/opencode-extension/commands/szcd-mcp-url.md

@@ -0,0 +1,37 @@
+---
+description: 更新szcd MCP服务器地址并同步Trae/Claude配置
+argument-hint: <new-mcp-server-url>
+---
+
+请帮我更新 szcd MCP 服务器地址。
+
+**交互流程**：
+
+1. **向用户询问要执行的操作**，提供以下选项：
+   - "更新服务器地址" → 输入新 URL 并同步所有 IDE 配置
+   - "同步现有配置" → 用 `~/.szcd-mcp-config.json` 中已有的 MCP_SERVER_URL 重新同步 IDE 配置
+   - "查看当前配置" → 显示当前 MCP 服务器地址
+
+2. **根据用户选择执行**：
+
+   - **更新服务器地址**：向用户询问新的 MCP 服务器 URL，可提供常用地址选项，用户也可自由输入。收集到 URL 后执行：
+     ```bash
+     npx szcd-mcp-update-url "<newUrl>"
+     ```
+
+   - **同步现有配置**：直接执行（不带参数）：
+     ```bash
+     npx szcd-mcp-update-url
+     ```
+
+   - **查看当前配置**：显示 `~/.szcd-mcp-config.json` 中的 MCP_SERVER_URL
+
+3. **命令回退**：如果 npx 不可用，依次尝试：
+   - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-mcp-url.js "<newUrl>"`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-mcp-url.js "<newUrl>"`
+   - 手动步骤：编辑 `~/.szcd-mcp-config.json`，再逐个 IDE 同步：
+     - trae-cli: `trae-cli mcp remove szcd-component-helper && trae-cli mcp add-json szcd-component-helper '{"type":"http","url":"<URL>/mcp"}'`
+     - claude: `claude mcp remove --scope user szcd-component-helper && claude mcp add --transport http --scope user szcd-component-helper <URL>/mcp`
+
+当前配置:
+!`cat ~/.szcd-mcp-config.json 2>/dev/null || echo "配置文件不存在"`

package/opencode-extension/opencode.json

@@ -0,0 +1,15 @@
+{
+    "$schema": "https://opencode.ai/config.json",
+    "mcp": {
+        "szcd-component-helper": {
+            "type": "remote",
+            "url": "http://localhost:3456/mcp"
+        },
+        "sketch-mcp-server": {
+            "type": "local",
+            "command": [
+                "sketch-mcp-server"
+            ]
+        }
+    }
+}

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，无需让用户手动复制粘贴命令