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

package/local-browser-executor.js

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+/**
+ * 本地浏览器测试执行器 - CLI 入口
+ *
+ * 用法：
+ *   node local-browser-executor.js --plan '<JSON>' --output /tmp/result.json
+ *   node local-browser-executor.js --plan-file /path/to/plan.json --output /tmp/result.json
+ *
+ * 参数：
+ *   --plan       测试计划 JSON 字符串
+ *   --plan-file  测试计划 JSON 文件路径（与 --plan 二选一）
+ *   --output     结果输出文件路径（默认 stdout）
+ *   --cdp-url    Chrome DevTools Protocol URL（默认自动检测 localhost:9222）
+ *   --page-url   连接已有 Chrome 时的目标页面 URL
+ *
+ * 退出码：
+ *   0 - 全部步骤执行成功
+ *   1 - 部分步骤失败
+ *   2 - 环境错误（Chrome 未安装 / 依赖缺失 / 无法连接）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { BrowserEngine } from "./lib/browser-engine.js";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+// ==================== 参数解析 ====================
+
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const parsed = {};
+
+    for (let i = 0; i < args.length; i++) {
+        switch (args[i]) {
+            case "--plan":
+                parsed.planJson = args[++i];
+                break;
+            case "--plan-file":
+                parsed.planFile = args[++i];
+                break;
+            case "--output":
+                parsed.output = args[++i];
+                break;
+            case "--cdp-url":
+                parsed.cdpUrl = args[++i];
+                break;
+            case "--page-url":
+                parsed.pageUrl = args[++i];
+                break;
+            case "--help":
+            case "-h":
+                printHelp();
+                process.exit(0);
+        }
+    }
+    return parsed;
+}
+
+function printHelp() {
+    console.log(`
+本地浏览器测试执行器
+
+用法:
+  node local-browser-executor.js --plan '<JSON>' [options]
+  node local-browser-executor.js --plan-file <path> [options]
+
+选项:
+  --plan <json>       测试计划 JSON 字符串
+  --plan-file <path>  测试计划 JSON 文件路径
+  --output <path>     结果输出文件路径（默认 stdout）
+  --cdp-url <url>     Chrome DevTools Protocol URL（默认 http://localhost:9222）
+  --page-url <url>    目标页面 URL（connect 模式时匹配标签页）
+  -h, --help          显示帮助
+`);
+}
+
+function loadPlan(args) {
+    if (args.planJson) {
+        return JSON.parse(args.planJson);
+    }
+    if (args.planFile) {
+        const content = fs.readFileSync(args.planFile, "utf8");
+        return JSON.parse(content);
+    }
+    throw new Error("必须提供 --plan 或 --plan-file 参数");
+}
+
+// ==================== 执行引擎 ====================
+
+async function executePlan(plan, options) {
+    const engine = new BrowserEngine();
+    const results = {
+        planId: plan.planId || "unknown",
+        description: plan.description || "",
+        mode: null,
+        steps: [],
+        summary: {
+            total: plan.steps.length,
+            passed: 0,
+            failed: 0,
+            fidelity: null,
+        },
+        startTime: new Date().toISOString(),
+    };
+
+    const outputDir = plan.options?.outputDir || path.join("/tmp", `browser-test-${results.planId}`);
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    try {
+        // 初始化浏览器
+        const initResult = await engine.init({
+            cdpUrl: options.cdpUrl,
+            pageUrl: options.pageUrl || plan.options?.pageUrl,
+            viewport: plan.options?.viewport,
+        });
+        results.mode = initResult.mode;
+        results.browserInfo = initResult;
+
+        // 如果计划中有 navigate 步骤且当前是 connect 模式，导航到目标页面
+        const navigateStep = plan.steps.find((s) => s.type === "navigate");
+
+        // 逐步执行
+        for (let i = 0; i < plan.steps.length; i++) {
+            const step = plan.steps[i];
+            const stepResult = await engine.executeStep(step, { outputDir });
+            stepResult.index = i + 1;
+            results.steps.push(stepResult);
+
+            if (stepResult.status === "PASS") {
+                results.summary.passed++;
+            } else {
+                results.summary.failed++;
+            }
+
+            // 提取 fidelity
+            if (step.type === "compare" && stepResult.status === "PASS" && stepResult.fidelity !== undefined) {
+                results.summary.fidelity = stepResult.fidelity;
+            }
+
+            // 输出进度
+            const status = stepResult.status === "PASS" ? "✓" : "✗";
+            process.stderr.write(
+                `  ${status} Step ${i + 1}/${plan.steps.length} ${step.type}` +
+                (step.selector ? ` (${step.selector})` : "") +
+                (stepResult.duration ? ` [${stepResult.duration}ms]` : "") +
+                "\n"
+            );
+        }
+    } catch (err) {
+        results.error = err.message;
+        results.errorCode = err.code || "UNKNOWN";
+
+        if (err.code === "CHROME_NOT_FOUND" || err.code === "DEPENDENCY_MISSING") {
+            results.installGuide = err.message;
+        }
+    } finally {
+        await engine.close();
+    }
+
+    results.endTime = new Date().toISOString();
+    results.duration = new Date(results.endTime) - new Date(results.startTime);
+    results.outputDir = outputDir;
+
+    return results;
+}
+
+// ==================== 主流程 ====================
+
+async function main() {
+    const args = parseArgs();
+
+    let plan;
+    try {
+        plan = loadPlan(args);
+    } catch (err) {
+        const errorResult = {
+            error: err.message,
+            errorCode: "INVALID_PLAN",
+        };
+        outputResult(errorResult, args.output);
+        process.exit(2);
+    }
+
+    process.stderr.write(`\n浏览器测试执行器\n`);
+    process.stderr.write(`计划: ${plan.description || plan.planId || "unnamed"}\n`);
+    process.stderr.write(`步骤: ${plan.steps?.length || 0}\n\n`);
+
+    const results = await executePlan(plan, {
+        cdpUrl: args.cdpUrl,
+        pageUrl: args.pageUrl,
+    });
+
+    // 输出结果
+    outputResult(results, args.output);
+
+    // 输出摘要
+    process.stderr.write(`\n执行完成:\n`);
+    process.stderr.write(`  模式: ${results.mode || "failed"}\n`);
+    process.stderr.write(`  通过: ${results.summary.passed}/${results.summary.total}\n`);
+    process.stderr.write(`  失败: ${results.summary.failed}/${results.summary.total}\n`);
+    if (results.summary.fidelity !== null) {
+        process.stderr.write(`  还原度: ${results.summary.fidelity}%\n`);
+    }
+    process.stderr.write(`  耗时: ${results.duration}ms\n\n`);
+
+    // 退出码
+    if (results.error) {
+        process.exit(2);
+    } else if (results.summary.failed > 0) {
+        process.exit(1);
+    } else {
+        process.exit(0);
+    }
+}
+
+function outputResult(results, outputPath) {
+    const json = JSON.stringify(results, null, 2);
+
+    if (outputPath) {
+        const dir = path.dirname(outputPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        fs.writeFileSync(outputPath, json, "utf8");
+        process.stderr.write(`结果已写入: ${outputPath}\n`);
+    } else {
+        process.stdout.write(json + "\n");
+    }
+}
+
+main().catch((err) => {
+    process.stderr.write(`Fatal error: ${err.message}\n`);
+    process.exit(2);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.18.0",
+    "version": "0.19.0",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",
@@ -29,6 +29,8 @@
     },
     "files": [
         "mcp-proxy.js",
+        "local-browser-executor.js",
+        "lib/",
         "scripts/postinstall.js",
         "scripts/update-mcp-url.js",
         "scripts/update-coding-config.js",
@@ -55,6 +57,12 @@
     "dependencies": {
         "@modelcontextprotocol/sdk": "^1.29.0"
     },
+    "optionalDependencies": {
+        "puppeteer-core": "^22.15.0",
+        "pixelmatch": "^5.3.0",
+        "pngjs": "^7.0.0",
+        "sharp": "^0.33.5"
+    },
     "repository": {
         "type": "git",
         "url": "git+https://github.com/szc-ft/mcp-szcd.git"

package/qwen-extension/agents/szcd-component-expert.md

@@ -113,6 +113,28 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 - "代码已生成，是否需要调整样式或交互细节？"
 - "是否需要补充表单校验规则？"
 - "是否需要添加批量操作功能？"
+- "是否需要进行浏览器验证？（在本地浏览器中检查还原度和功能）"
+
+
+### 步骤6.5：浏览器验证（条件执行）
+
+当用户在步骤6中选择进行浏览器验证时执行此步骤。
+
+1. **提取代码上下文**：你已经掌握生成的代码结构（组件、selector、API），直接用于构造测试计划
+2. **询问用户**：目标页面 URL（如果还不知道）和设计稿（如有）
+3. **构造测试计划 JSON**：按 `local-browser-test` skill 中定义的 Plan Schema，从代码中提取真实 selector 和 API 路径
+4. **执行测试**：在用户终端执行：
+   ```bash
+   node {client_path}/local-browser-executor.js --plan '<计划JSON>' --output /tmp/browser-test-result.json
+   ```
+5. **解读结果**：读取 /tmp/browser-test-result.json，分析还原度评分和功能测试通过情况
+6. **闭环修复**：如有问题，主动修复代码并询问是否重新测试
+
+**构造测试计划的要点**：
+- selector 从生成的代码中读取（id/className/data-testid），不要猜测
+- API 路径从代码中的接口调用读取
+- checkElement 的 expect 从代码逻辑推断（columns 数量、数据行数等）
+- 有设计稿时添加 compare 步骤，无设计稿时跳过
 
 ### 步骤7：收集用户反馈（必做，质量闭环）
 

package/qwen-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/qwen-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/qwen-extension/qwen-extension.json

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

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

@@ -1,6 +1,6 @@
 ---
 name: local-api-tool
-description: 本地网络 API 工具，专门处理 10.x.x.x 网段的 Swagger/YApi 文档拉取和联调测试。当服务端 api_tool 因 LOCAL_NETWORK_UNREACHABLE 无法访问时，此技能在用户本地环境执行 curl，再将结果交给服务端解析。适用于内网开发环境、VPN 场景。
+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
@@ -20,6 +20,19 @@ compatibility:
 - 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）

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

@@ -0,0 +1,153 @@
+---
+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 }` |
+
+### 场景选择策略
+
+根据上下文自动选择步骤组合：
+
+**场景 A：有设计稿 + 功能验证（最完整）**
+`navigate → waitFor → screenshot → compare → 功能步骤`
+
+**场景 B：无设计稿 + 功能验证**
+`navigate → waitFor → screenshot → evaluate(JS错误检查) → 功能步骤`
+
+**场景 C：仅视觉对比**
+`navigate → waitFor → screenshot → compare`
+
+**场景 D：仅页面检查**
+`navigate → waitFor → screenshot → evaluate(JS错误检查)`
+
+### 构造步骤的指导原则
+
+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 从设计稿分析结果或组件布局推断**
+
+## 执行命令
+
+```bash
+node {client_install_path}/local-browser-executor.js \
+  --plan '<测试计划JSON>' \
+  --output /tmp/browser-test-result.json
+```
+
+也支持从文件读取计划：
+```bash
+node {client_install_path}/local-browser-executor.js \
+  --plan-file /tmp/test-plan.json \
+  --output /tmp/browser-test-result.json
+```
+
+### 可选参数
+
+- `--cdp-url http://localhost:9223`：指定非默认的 CDP 端口
+- `--page-url http://xxx/page`：connect 模式下指定目标页面
+
+## 依赖检查
+
+如果执行报错依赖缺失，引导用户安装：
+```bash
+npm install puppeteer-core pixelmatch pngjs sharp
+```
+
+## 结果解读
+
+### 还原度评分
+- 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"
+}
+```

package/standard-skill/local-api-tool/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: local-api-tool
-description: 本地网络 API 工具，专门处理 10.x.x.x 网段的 Swagger/YApi 文档拉取和联调测试。当服务端 api_tool 因 LOCAL_NETWORK_UNREACHABLE 无法访问时，此技能在用户本地环境执行 curl，再将结果交给服务端解析。适用于内网开发环境、VPN 场景。
+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
@@ -20,6 +20,19 @@ compatibility:
 - 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）