@szc-ft/mcp-szcd-client 0.14.0 → 0.16.0

package/agents/build.js

@@ -252,27 +252,7 @@ function build() {
         console.log(`    ✓ Written: ${path.relative(AGENTS_DIR, outputPath)}`);
     }
 
-    // 3. 同步到 mcp-server/agents/（同级 mcp/szcd-mcp-server 目录）
-    const mcpServerAgentsDir = path.join(AGENTS_DIR, "..", "..", "szcd-mcp-server", "agents");
-    if (fs.existsSync(path.dirname(mcpServerAgentsDir))) {
-        if (!fs.existsSync(mcpServerAgentsDir)) {
-            fs.mkdirSync(mcpServerAgentsDir, { recursive: true });
-        }
-
-        const outputFiles = [
-            "szcd-component-expert.md",
-            "szcd-component-expert.trae.md",
-            "szcd-component-expert.qoder.md",
-        ];
-        for (const file of outputFiles) {
-            const src = path.join(AGENTS_DIR, file);
-            const dest = path.join(mcpServerAgentsDir, file);
-            if (fs.existsSync(src)) {
-                fs.copyFileSync(src, dest);
-                console.log(`    ✓ Synced to mcp-server: ${file}`);
-            }
-        }
-    }
+    // 3. 不再同步到 szcd-mcp-server（服务端不消费 agents 目录，由客户端独立维护）
 
     // 4. 同步到 qwen-extension/agents/（供 Qwen Code 扩展安装使用）
     const qwenExtDir = path.join(AGENTS_DIR, "..", "qwen-extension");
@@ -289,15 +269,23 @@ function build() {
     // 5. 同步 SKILL.md 和 commands 到 qwen-extension/
     const packageRoot = path.join(AGENTS_DIR, "..");
 
-    // 同步 SKILL.md
-    const skillSource = path.join(packageRoot, "skill", "SKILL.md");
-    const skillDest = path.join(qwenExtDir, "skills", "szcd-component-helper", "SKILL.md");
-    if (fs.existsSync(skillSource)) {
-        if (!fs.existsSync(path.dirname(skillDest))) {
-            fs.mkdirSync(path.dirname(skillDest), { recursive: true });
+    // 同步所有 skills（从 standard-skill 目录读取）
+    const standardSkillDir = path.join(packageRoot, "standard-skill");
+    if (fs.existsSync(standardSkillDir)) {
+        const skillDirs = fs.readdirSync(standardSkillDir).filter((name) => {
+            return fs.statSync(path.join(standardSkillDir, name)).isDirectory();
+        });
+        for (const skillDir of skillDirs) {
+            const srcSkillPath = path.join(standardSkillDir, skillDir, "SKILL.md");
+            const destSkillPath = path.join(qwenExtDir, "skills", skillDir, "SKILL.md");
+            if (fs.existsSync(srcSkillPath)) {
+                if (!fs.existsSync(path.dirname(destSkillPath))) {
+                    fs.mkdirSync(path.dirname(destSkillPath), { recursive: true });
+                }
+                fs.copyFileSync(srcSkillPath, destSkillPath);
+                console.log(`    ✓ Synced skill to qwen-extension/skills/${skillDir}/`);
+            }
         }
-        fs.copyFileSync(skillSource, skillDest);
-        console.log(`    ✓ Synced to qwen-extension/skills/`);
     }
 
     // 同步 commands

package/commands/szcd-mcp-api-config.md

@@ -32,7 +32,7 @@ argument-hint: <get|set|clear> [--baseUrl=xxx] [--account=yyy] [--password=zzz]
 
 3. **命令回退**：如果 npx 不可用，依次尝试：
    - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-api-config.js <args>`
-   - `node /scity/zengzhijie/szcd/mcp/szcd-mcp-client/scripts/update-api-config.js <args>`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-api-config.js <args>`
 
 **配置字段说明**：
 - `YAPI_BASE_URL` - YApi 基础地址

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

@@ -29,7 +29,7 @@ argument-hint: <get|set|clear> [--baseUrl=xxx] [--projectId=yyy] [--account=zzz]
 
 3. **命令回退**：如果 npx 不可用，依次尝试：
    - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-coding-config.js <args>`
-   - `node /scity/zengzhijie/szcd/mcp/szcd-mcp-client/scripts/update-coding-config.js <args>`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-coding-config.js <args>`
 
 **配置字段说明**：
 - `CODING_BASE_URL` — CODING 基础地址

package/commands/szcd-mcp-url.md

@@ -28,7 +28,7 @@ argument-hint: <new-mcp-server-url>
 
 3. **命令回退**：如果 npx 不可用，依次尝试：
    - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-mcp-url.js "<newUrl>"`
-   - `node /scity/zengzhijie/szcd/mcp/szcd-mcp-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`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@szc-ft/mcp-szcd-client",
-    "version": "0.14.0",
+    "version": "0.16.0",
     "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
     "keywords": [
         "mcp",
@@ -34,7 +34,6 @@
         "scripts/update-api-config.js",
         "scripts/lib/",
         "standard-skill/",
-        "skill/",
         "agents/",
         "commands/",
         "qwen-extension/",
@@ -56,11 +55,10 @@
     },
     "repository": {
         "type": "git",
-        "url": "git+https://github.com/szc-ft/szcd.git",
-        "directory": "mcp/szcd-mcp-client"
+        "url": "git+https://github.com/szc-ft/mcp-szcd.git"
     },
     "bugs": {
-        "url": "https://github.com/szc-ft/szcd/issues"
+        "url": "https://github.com/szc-ft/mcp-szcd/issues"
     },
-    "homepage": "https://github.com/szc-ft/szcd#readme"
+    "homepage": "https://github.com/szc-ft/mcp-szcd#readme"
 }

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

@@ -32,7 +32,7 @@ argument-hint: <get|set|clear> [--baseUrl=xxx] [--account=yyy] [--password=zzz]
 
 3. **命令回退**：如果 npx 不可用，依次尝试：
    - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-api-config.js <args>`
-   - `node /scity/zengzhijie/szcd/mcp/szcd-mcp-client/scripts/update-api-config.js <args>`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-api-config.js <args>`
 
 **配置字段说明**：
 - `YAPI_BASE_URL` - YApi 基础地址

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

@@ -29,7 +29,7 @@ argument-hint: <get|set|clear> [--baseUrl=xxx] [--projectId=yyy] [--account=zzz]
 
 3. **命令回退**：如果 npx 不可用，依次尝试：
    - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-coding-config.js <args>`
-   - `node /scity/zengzhijie/szcd/mcp/szcd-mcp-client/scripts/update-coding-config.js <args>`
+   - `node /scity/zengzhijie/mcp/szcd-mcp-client/scripts/update-coding-config.js <args>`
 
 **配置字段说明**：
 - `CODING_BASE_URL` — CODING 基础地址

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

@@ -28,7 +28,7 @@ argument-hint: <new-mcp-server-url>
 
 3. **命令回退**：如果 npx 不可用，依次尝试：
    - `node $(npm root -g)/@szc-ft/mcp-szcd-client/scripts/update-mcp-url.js "<newUrl>"`
-   - `node /scity/zengzhijie/szcd/mcp/szcd-mcp-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`

package/qwen-extension/qwen-extension.json

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

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

@@ -0,0 +1,233 @@
+---
+name: local-api-tool
+description: 本地网络 API 工具，专门处理 10.x.x.x 网段的 Swagger/YApi 文档拉取和联调测试。当服务端 api_tool 因 LOCAL_NETWORK_UNREACHABLE 无法访问时，此技能在用户本地环境执行 curl，再将结果交给服务端解析。适用于内网开发环境、VPN 场景。
+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 或内网开发环境中，本地可访问但远程服务器不可达
+
+## 工作流
+
+### 流程 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/qwen-extension/skills/szcd-component-helper/SKILL.md

@@ -19,7 +19,7 @@ compatibility:
 
 **重要说明**：这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。服务器由管理员维护，包含源码和数据。
 
-**版本**：v0.13.0 - MCP 服务器架构重构，工具精简至13个；新增语义搜索、一站式组件画像、最佳实践、反馈收集等工具；Swagger/YApi 统一为 api_tool；CODING Issue 支持URL自动解析
+**版本**：v0.16.0 - 新增 10 段网段本地网络兼容：api_tool 新增 parse_swagger_json action，客户端新增 local-api-tool 技能，遇到 10.x.x.x 网段自动在本地 curl 获取 Swagger JSON 再交由服务端解析
 
 ## 架构说明
 
@@ -58,7 +58,7 @@ compatibility:
 
 ## 推荐工作流（页面生成类任务）
 
-AI 助手在处理页面生成需求时，推荐按以下流程使用工具：
+AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 
 ### 步骤1：架构认知 + 需求理解
 - 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
@@ -178,15 +178,19 @@ AI 助手在处理页面生成需求时，推荐按以下流程使用工具：
 ### API 工具
 
 #### 9. api_tool
-**功能**：统一 API 工具，自动识别 YApi/Swagger 拉取 API 文档、联调测试、配置管理。
+**功能**：统一 API 工具，自动识别 YApi/Swagger 拉取 API 文档、联调测试、配置管理、解析本地 Swagger JSON。
 **参数**：
-- `action` (enum, required): fetch=拉取API文档, test=联调测试, config=配置管理
+- `action` (enum, required): fetch=拉取API文档, test=联调测试, config=配置管理, parse_swagger_json=解析本地curl获取的Swagger JSON
 - `url` (string, optional): API文档地址（fetch时）/ 请求地址（test时）
 - `method` (enum, optional, default: "GET"): GET/POST/PUT/DELETE/PATCH（test时）
 - `data` (object, optional, default: {}): 请求参数（test时）
 - `headers` (object, optional, default: {}): 请求头（test时）
 - `username` / `password` / `account` / `cookies` (string, optional): 鉴权信息
 - `yapiBaseUrl` / `yapiAccount` / `yapiPassword` / `yapiCookies` (string, optional): YApi 配置（config set 时生效）
+- `swaggerJson` (string, optional): 客户端本地 curl 获取的 Swagger JSON 字符串（parse_swagger_json 时必填）
+- `swaggerSourceUrl` (string, optional): 原始 Swagger URL（parse_swagger_json 时可选，用于补充元数据）
+
+**10段网段本地执行**：当 fetch/test 遇到 `10.x.x.x` 网段地址时，服务端返回 `LOCAL_NETWORK_UNREACHABLE`，此时应使用 `local-api-tool` 技能在用户本地执行 curl，再调用 `parse_swagger_json` 解析。详见 `local-api-tool` 技能。
 
 ### Repowiki 增强工具（推荐优先使用）
 
@@ -288,8 +292,6 @@ npm install @szc-ft/mcp-szcd-component-helper
 
 ### 步骤2：配置服务器地址
 
-#### 方式1：使用配置文件（推荐）
-
 编辑配置文件 `~/.szcd-mcp-config.json`：
 
 ```json
@@ -300,23 +302,9 @@ npm install @szc-ft/mcp-szcd-component-helper
 }
 ```
 
-#### 方式2：使用环境变量
-
-```bash
-# Linux/macOS
-export MCP_SERVER_URL="http://localhost:3456"
-export MCP_TIMEOUT="30000"
-export MCP_API_KEY="your-api-key"
-
-# Windows (PowerShell)
-$env:MCP_SERVER_URL="http://localhost:3456"
-$env:MCP_TIMEOUT="30000"
-$env:MCP_API_KEY="your-api-key"
-```
+### 步骤3：在 IDE 配置中设置
 
-#### 方式3：在 IDE 配置中设置
-
-**方式3a：Trae CLI Streamable HTTP 直连（推荐）**
+**Trae CLI Streamable HTTP 直连（推荐）**
 
 在 `~/.trae/trae_cli.yaml` 中配置：
 
@@ -327,7 +315,7 @@ mcp_servers:
       type: http
 ```
 
-**方式3b：本地直连 stdio（推荐，无需远程服务器）**
+**本地直连 stdio（推荐，无需远程服务器）**
 
 ```json
 {
@@ -340,7 +328,7 @@ mcp_servers:
 }
 ```
 
-**方式3c：Qwen Code / Qoder CLI Streamable HTTP 直连（推荐）**
+**Qwen Code / Qoder CLI Streamable HTTP 直连（推荐）**
 
 在 `~/.qwen/settings.json` 中配置：
 
@@ -355,7 +343,7 @@ mcp_servers:
 }
 ```
 
-**方式3d：Qwen Code / Qoder CLI 本地直连 stdio（推荐，无需远程服务器）**
+**Qwen Code / Qoder CLI 本地直连 stdio（推荐，无需远程服务器）**
 
 ```json
 {
@@ -368,7 +356,7 @@ mcp_servers:
 }
 ```
 
-**方式3e：Claude Code 配置**
+**Claude Code 配置**
 
 ```json
 {
@@ -381,45 +369,13 @@ mcp_servers:
 }
 ```
 
-### 步骤3：验证配置
-
-运行以下命令验证配置是否正确：
+### 步骤4：验证配置
 
 ```bash
-# 测试服务器连接
 curl http://localhost:3456/health
-
-# 测试代理脚本
 npx szcd-mcp-proxy --test
 ```
 
-## 配置优先级
-
-地址获取的优先级顺序：
-
-1. **环境变量**（最高优先级）
-2. **配置文件** `~/.szcd-mcp-config.json`
-3. **默认值** `http://localhost:3456`
-
-## 环境变量说明
-
-### MCP 连接配置
-
-| 变量 | 说明 | 默认值 | 示例 |
-|------|------|--------|------|
-| `MCP_SERVER_URL` | MCP 服务器地址 | `http://localhost:3456` | `http://192.168.1.100:3456` |
-| `MCP_TIMEOUT` | 请求超时时间(毫秒) | `30000` | `60000` |
-| `MCP_API_KEY` | MCP API 密钥（可选） | `` | `your-secret-key` |
-
-### 视觉模型配置（设计稿分析功能必需）
-
-| 变量 | 说明 | 默认值 | 示例 |
-|------|------|--------|------|
-| `VISION_API_KEY` | 视觉模型 API 密钥 | 读取 `ANTHROPIC_API_KEY` 或 `OPENAI_API_KEY` | `sk-ant-...` |
-| `VISION_PROVIDER` | 视觉模型提供商 | `anthropic` | `anthropic` / `openai` |
-| `VISION_MODEL` | 视觉模型名称 | `claude-sonnet-4-6` | `gpt-4o` |
-| `DESIGN_ANALYSIS_ORDER` | 分析优先级 | `vision_first` | `vision_first` / `ocr_first` / `vision_only` / `ocr_only` |
-
 ## 反馈收集（质量闭环）
 
 ### 触发时机
@@ -473,8 +429,6 @@ AI 助手应在代码输出后询问：
 - `get_component_library_overview`、`list_other_components`、`search_all_components` 等旧工具已移除，请使用 `get_architecture_overview` 和 `search_components_semantic` 替代
 - **需要确保 MCP 服务器正在运行，否则无法查询数据**
 - **设计稿分析功能需要配置视觉模型 API Key**，未配置时 analyze_design_image 工具会返回错误
-- **设计稿分析会调用外部多模态模型 API**，会产生额外费用（单张约 $0.03~0.05）
-- **设计稿分析结果会自动缓存 24 小时**，同一图片重复查询不会重复计费
 - **反馈收集是可选但强烈建议的功能**，有助于持续优化 MCP 工具质量
 
 ## 故障排除
@@ -487,9 +441,3 @@ AI 助手应在代码输出后询问：
 4. 确认 `MCP_SERVER_URL` 配置正确
 5. 检查环境变量是否正确设置
 6. 检查配置文件 `~/.szcd-mcp-config.json` 是否存在
-
-### 配置文件问题
-
-1. 检查配置文件路径：`~/.szcd-mcp-config.json`
-2. 检查 JSON 格式是否正确
-3. 检查文件权限

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

@@ -0,0 +1,233 @@
+---
+name: local-api-tool
+description: 本地网络 API 工具，专门处理 10.x.x.x 网段的 Swagger/YApi 文档拉取和联调测试。当服务端 api_tool 因 LOCAL_NETWORK_UNREACHABLE 无法访问时，此技能在用户本地环境执行 curl，再将结果交给服务端解析。适用于内网开发环境、VPN 场景。
+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 或内网开发环境中，本地可访问但远程服务器不可达
+
+## 工作流
+
+### 流程 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/standard-skill/szcd-component-helper/SKILL.md

@@ -19,7 +19,7 @@ compatibility:
 
 **重要说明**：这是一个客户端 skill，通过 MCP 协议（SSE 或 HTTP）连接到远程 MCP 服务器。服务器由管理员维护，包含源码和数据。
 
-**版本**：v0.13.0 - MCP 服务器架构重构，工具精简至13个；新增语义搜索、一站式组件画像、最佳实践、反馈收集等工具；Swagger/YApi 统一为 api_tool；CODING Issue 支持URL自动解析
+**版本**：v0.16.0 - 新增 10 段网段本地网络兼容：api_tool 新增 parse_swagger_json action，客户端新增 local-api-tool 技能，遇到 10.x.x.x 网段自动在本地 curl 获取 Swagger JSON 再交由服务端解析
 
 ## 架构说明
 
@@ -178,15 +178,19 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 ### API 工具
 
 #### 9. api_tool
-**功能**：统一 API 工具，自动识别 YApi/Swagger 拉取 API 文档、联调测试、配置管理。
+**功能**：统一 API 工具，自动识别 YApi/Swagger 拉取 API 文档、联调测试、配置管理、解析本地 Swagger JSON。
 **参数**：
-- `action` (enum, required): fetch=拉取API文档, test=联调测试, config=配置管理
+- `action` (enum, required): fetch=拉取API文档, test=联调测试, config=配置管理, parse_swagger_json=解析本地curl获取的Swagger JSON
 - `url` (string, optional): API文档地址（fetch时）/ 请求地址（test时）
 - `method` (enum, optional, default: "GET"): GET/POST/PUT/DELETE/PATCH（test时）
 - `data` (object, optional, default: {}): 请求参数（test时）
 - `headers` (object, optional, default: {}): 请求头（test时）
 - `username` / `password` / `account` / `cookies` (string, optional): 鉴权信息
 - `yapiBaseUrl` / `yapiAccount` / `yapiPassword` / `yapiCookies` (string, optional): YApi 配置（config set 时生效）
+- `swaggerJson` (string, optional): 客户端本地 curl 获取的 Swagger JSON 字符串（parse_swagger_json 时必填）
+- `swaggerSourceUrl` (string, optional): 原始 Swagger URL（parse_swagger_json 时可选，用于补充元数据）
+
+**10段网段本地执行**：当 fetch/test 遇到 `10.x.x.x` 网段地址时，服务端返回 `LOCAL_NETWORK_UNREACHABLE`，此时应使用 `local-api-tool` 技能在用户本地执行 curl，再调用 `parse_swagger_json` 解析。详见 `local-api-tool` 技能。
 
 ### Repowiki 增强工具（推荐优先使用）