@szc-ft/mcp-szcd-client 0.24.0 → 0.25.0

package/qwen-extension/skills/szcd-design-to-code/SKILL.md

@@ -55,29 +55,32 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
 
-**核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。`getMultipleNodeInfo` 支持任意数量 ID（内部自动分片），比逐个 `getNodeInfo` 快 10 倍以上。
+**核心原则**：写代码之前必须拿到所有 `text`、`rectangle`、`group` 节点的完整样式 Token + 父子层级，禁止凭节点名猜测颜色/字号/背景色，禁止用 x 坐标平面判定元素归属。`queryNodes.type` 接受数组、`getMultipleNodeInfo` 内部自动分片，比逐个 `getNodeInfo` 快 10 倍以上。
 
-**工具调用顺序（优化后，4 次主调用）**：
+**工具调用顺序（sketch-mcp-server ≥ v1.5.0，4 次主调用）**：
 
 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件（内部自动解压并保存目录，供后续 extractBitmaps 使用）
 2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
 3. `mcp__sketch-mcp-server__queryNodes`（pageId, type="artboard"）— 获取画板列表，确定目标画板
-4. `mcp__sketch-mcp-server__getPageStructure`（pageId, mode="ids"）**替代旧的 getPageStructure + getNodesSummary 组合**
-   - 一次返回按类型分组的全量 ID：`{ text: [...], rectangle: [...], bitmap: [...], shapePath: [...] }`
-   - 可选 `typeFilter` 参数限制返回类型
+4. `mcp__sketch-mcp-server__getPageStructure`（pageId, mode="tree"）— **先看完整层级关系**，识别顶层 group 分区（如 LeftTree 区/Query+Table 区/信息栏区/标题栏区）
+   - 再用 `mode="ids"` 拿到按类型分组的全量 ID：`{ text: [...], rectangle: [...], group: [...], bitmap: [...], shapePath: [...] }`
    - 同时返回 `summary`（各类型统计）和 `totalIds`（总数）
-5. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[所有 text + rectangle ID]）— **支持任意数量 ID，内部自动分批处理**
-   - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
+5. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[**所有 text + rectangle + group ID 同批提交**]）— **支持任意数量 ID，内部自动分批处理**
+   - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`、`style.borders[0]`、`style.shadows`
+   - **`parent: { id, name, type }`**（v1.5.0+ 新增）— 元素归属判定的核心字段，**始终用 parent 走 group 父子关系，禁止用 x/y 坐标判定归属**
+   - **禁止只取 text 类型**：会遗漏 rectangle/group 容器的渐变背景、边框、阴影；信息栏/卡片类区块必须连容器一起拉
    - 无需手动分批，传入全部 ID 即可（内部按 100 个一批自动处理）
 
-**与旧策略的差异**：
-- 旧策略：`getPageStructure`(可能截断) + `getNodesSummary` + 手动分批 `getMultipleNodeInfo`
-- 新策略：`getPageStructure(mode="ids")`(轻量全量 ID) + `getMultipleNodeInfo`(自动分片)
-- 调用次数：旧 6 次 → 新 4 次（含 loadSketch + listPages 合并）
+**替代方案（更短，3 次主调用）**：当只关心特定类型节点时，可用 `queryNodes` 一次性拿数组类型：
+```
+queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
+→ 返回这三类节点的 ID 列表，跳过 getPageStructure(mode="ids") 步骤
+```
+适用场景：已通过 `getPageStructure(mode="tree")` 看清分区，只想批量获取关键 token 节点时。
 
 **步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
 - 按类型分组的全量节点 ID 列表
-- text/rectangle 节点的完整样式 Token
+- text/rectangle/group 节点的完整样式 Token + parent 父子关系
 - bitmap ID 列表（传给步骤 2.5.1）
 - shapePath 节点名列表（传给步骤 2.5.1）
 
@@ -92,21 +95,55 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
    - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
    - 位图资源用于 CSS `background-image` 引用
-2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库
-   - 输入 shapePath 节点名列表（如 `["表 icon", "文件 icon"]`）
-   - 匹配策略：节点名关键词 → 拼音匹配图标列表
+2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库（v1.5.0+ 评分制）
+   - 输入 shapePath 节点名列表（如 `["表 icon", "新建文件夹", "编组11备份"]`）
+   - **评分机制**：compoundIcons 强映射 +100、keyword 精确 +20、keyword 包含 +10、semanticTag +3
+   - 每个 nodeName 返回 **Top-3 候选**（按分数降序），让你做最终选择
    - 返回格式：
      ```json
      {
-       "matchedIcons": [
-         { "nodeName": "表 icon", "iconType": "icon-biao", "library": "newFont" }
+       "results": [
+         {
+           "nodeName": "新建文件夹",
+           "top3": [
+             { "source": "compound", "score": 104, "antdIcon": "FolderAddOutlined", "matchedBy": "文件夹|目录|folder + 新增|添加|add|plus|新建|create", "rationale": "..." },
+             { "source": "compound", "score": 104, "antdIcon": "FileAddOutlined" },
+             { "source": "compound", "score": 102, "antdIcon": "FolderOutlined" }
+           ],
+           "bestMatch": { "source": "compound", "antdIcon": "FolderAddOutlined" }
+         }
        ],
-       "unmatched": ["菜单icon"],
-       "recommendFallback": { "菜单icon": "antd MenuOutlined" },
-       "matchRate": "80.0%"
+       "matchedIcons": [...],  // Top-1 兼容旧字段
+       "unmatched": ["编组11备份"],  // 无关键词信号的节点
+       "recommendFallback": { "编组11备份": "antd QuestionOutlined" },
+       "matchRate": "66.7%"
      }
      ```
 
+**⚠️ 图标语义优先级（v1.5.0 已内置 compoundIcons，多数场景自动命中）**：
+
+实战教训：Sketch 中"编组11备份"实际是 folder-plus 图标，旧版被误判为通用 PlusOutlined（优先命中"新增"关键词吃掉了 folder 语义）。v1.5.0 评分制 + compoundIcons 强映射已修复该类问题。
+
+**判定流程**：
+1. **优先看 `bestMatch.source`**：`compound` 表示触发了复合词强映射，可直接采用 `antdIcon`
+2. **看 Top-3 是否有合适的候选**：分数接近的候选都值得考虑
+3. **`unmatched` 节点（如"编组11备份"无关键词信号）**：必须看节点 `parent.name` 和兄弟节点上下文兜底
+   - 例：parent 是 LeftTree 标题区 → 多半是文件夹/分类操作图标 → `FolderAddOutlined` / `FolderOpenOutlined`
+   - 例：parent 是 Query 操作栏 → 多半是表单动作图标 → `SearchOutlined` / `PlusOutlined`
+
+**参考表（内置 compoundIcons 已覆盖；列出供 unmatched 兜底参考）**：
+
+| Sketch 节点上下文 | 期望 antd 图标 | 反例（不要选） |
+|---|---|---|
+| 文件夹+新增/添加 | `FolderAddOutlined` | PlusOutlined |
+| 文件+新增 | `FileAddOutlined` | PlusOutlined |
+| 用户+新增 | `UserAddOutlined` | PlusOutlined |
+| 文件夹+打开 | `FolderOpenOutlined` | FolderOutlined |
+| 编辑+笔 | `EditOutlined` | FormOutlined |
+| 设置+齿轮 | `SettingOutlined` | ToolOutlined |
+
+**操作流程**：matchIconFromName 返回 unmatched 或 fallback 为通用 `PlusOutlined/EditOutlined` 时，**先看节点 parent group 的名称/兄弟节点**，按上表选语义更精确的复合图标。
+
 **步骤 2.5.1 产出物**：
 - bitmap base64 资源列表 → 用于代码中的 CSS background-image
 - IconfontWapper 代码片段（`<IconfontWapper assets="newFont" type="icon-biao" />`）
@@ -128,15 +165,36 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 - 新做法：直接传入全部 ID（如 200 个）→ 内部自动按 100 个一批处理 → 返回合并结果
 - 返回结构不变：`{ nodes: [...], total, requested, batches }`
 
-**经验3：text 节点是颜色/DOM 映射的两级索引**
+**经验3：元素归属必须走 group 父子关系，禁止 x 坐标平面判定**
+
+实战教训：`'主题'text(x=272,y=149)` 被错误识别为内容区块标题，实际是左侧树标题（与树节点同 x=272 列）。同列坐标不代表同区域。
+
+正确做法：
+- 步骤 2.5 第 4 步先 `mode="tree"` 看顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
+- `getMultipleNodeInfo`/`getNodeInfo` v1.5.0+ **自动返回** `parent: { id, name, type }` 字段，按 parent 归属到具体分区即可
+- "主题"这类标题文本，先看 `parent.name` 是否带 "LeftTree" / "树" 等容器关键字，不要看 x 坐标
+- 坐标仅作为同 parent 内子元素排序兜底使用
+
+**经验4：信息栏/卡片容器必须先取 group 再取子元素**
+
+实战教训：步骤 2.5 仅提取 text 节点导致信息栏容器样式遗漏（渐变背景 #f3faff→#f8fdff、边框 #e9f5ff、图标编组）。
+
+正确做法：
+- 看到画板里有 `编组N`/`infoCard`/`statBox` 等 group 节点，必须连 group 自身和内部 rectangle 一起拉 `getMultipleNodeInfo`
+- group 节点的 `style.fills` 才是渐变背景、`style.borders` 才是边框
+- 子图标若为 group(rectangle + shapePath)，rectangle 是圆形/方形背景，shapePath 是矢量图标
+
+**经验5：text 节点是颜色/DOM 映射的两级索引**
 每个 text 节点同时关联两种上下文，**必须同批拉取**：
 - 自身样式：`fontSize`、`fontWeight`、`text.color`
 - 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
 
 错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
-正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
+正确做法：
+- 用 `queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })` 一次拿三类节点的 ID
+- 再用 `getMultipleNodeInfo([...全部ID])` 同批提交，每个节点返回的 `parent` 字段直接告诉你归属关系，无需二次查询
 
-**经验4：图表区样式提取有规律可循**
+**经验6：图表区样式提取有规律可循**
 
 | 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
 |---|---|---|
@@ -151,7 +209,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
 
-**经验5：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
+**经验7：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
 - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
 - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
 - bitmap 用 `extractBitmaps(bitmapIds)` 自动提取 PNG 资源
@@ -206,6 +264,19 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 柱状对比图 | `Bar` |
 | 饼图/环形图 | `Pie` |
 
+### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
+
+**LeftContent / Query / PageContent 三个槽位都接收单个 ReactNode，禁止传数组**：
+
+| ❌ 错误 | ✅ 正确 | 后果 |
+|---|---|---|
+| `LeftContent={[<LeftTree/>]}` | `LeftContent={<LeftTree/>}` | 数组会触发多余 tab 渲染 |
+| `LeftContent={[<LeftTree/>, <Filter/>]}` | `LeftContent={<><LeftTree/><Filter/></>}` 或包一层 div | 同上 |
+| `Query={[<Query/>]}` | `Query={<Query/>}` | 同上 |
+| `PageContent={[<TableOrList/>]}` | `PageContent={<TableOrList/>}` | 同上 |
+
+**判定方法**：Sketch 中只要某个分区是"单棵树/单个查询面板/单个表格"，对应槽位就传单个组件实例。需要多个并列时用 Fragment `<>...</>` 或容器 div 包裹，**不要用数组**。
+
 **长尾场景走语义搜索**（不进文档，避免膨胀）：
 - 数据可视化长尾：`Radar` / `Gauge` / `Funnel`（用 `Line/Bar/Pie` 之外的图表）
 - 表格子类型长尾：`DragSortTable`（拖拽排序）、`steps` 步骤条表单

package/scripts/lib/claude-code.js

@@ -152,7 +152,7 @@ function copySkillToClaudeCode(deps, isProjectLevel = false) {
         try {
             deps.ensureDirectory(skillDir);
             const skillDest = path.join(skillDir, "SKILL.md");
-            deps.copyFile(skill.sourcePath, skillDest);
+            deps.copySkill(skill.sourcePath, skillDest);
             console.log(`✓ Copied skill "${skill.name}" to Claude Code ${isProjectLevel ? 'project' : 'user'} directory: ${skillDir}`);
         } catch (error) {
             console.log(`⚠️  Failed to copy skill "${skill.name}" to Claude Code ${isProjectLevel ? 'project' : 'user'} directory: ${error.message}`);

package/scripts/lib/common.js

@@ -140,6 +140,50 @@ export function copyFile(source, destination) {
     }
 }
 
+/**
+ * 递归复制目录（用于 skill 目录这种含子文件/子目录的场景）
+ * 不存在的源直接抛错；目标会被创建。
+ */
+export function copyDirRecursive(source, destination) {
+    if (!fs.existsSync(source)) {
+        throw new Error(`Source directory not found: ${source}`);
+    }
+    if (!fs.existsSync(destination)) {
+        fs.mkdirSync(destination, { recursive: true });
+    }
+    for (const entry of fs.readdirSync(source, { withFileTypes: true })) {
+        const src = path.join(source, entry.name);
+        const dest = path.join(destination, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(src, dest);
+        } else {
+            fs.copyFileSync(src, dest);
+        }
+    }
+}
+
+/**
+ * 复制 skill：以 SKILL.md 所在目录为单位，递归复制整个目录到目标 skill 目录。
+ * 这样 standard-skill/<skill>/scripts/ 等附属内容会一并带走。
+ *
+ * @param {string} skillSourceFile - SKILL.md 的绝对路径（discoverSkills() 返回的 sourcePath）
+ * @param {string} destSkillFile   - 目标 SKILL.md 的绝对路径（保持现有调用方习惯）
+ */
+export function copySkill(skillSourceFile, destSkillFile) {
+    try {
+        if (!fs.existsSync(skillSourceFile)) {
+            throw new Error(`Skill source file not found: ${skillSourceFile}`);
+        }
+        const srcDir = path.dirname(skillSourceFile);
+        const destDir = path.dirname(destSkillFile);
+        copyDirRecursive(srcDir, destDir);
+        console.log(`✓ Copied skill: ${srcDir} → ${destDir}`);
+    } catch (error) {
+        console.error(`❌ Failed to copy skill: ${error.message}`);
+        throw error;
+    }
+}
+
 export function writeFile(filePath, content) {
     try {
         fs.writeFileSync(filePath, content);

package/scripts/lib/opencode.js

@@ -295,7 +295,7 @@ function copySkillToOpenCode(deps, isProjectLevel = false) {
         try {
             deps.ensureDirectory(skillDir);
             const skillDest = path.join(skillDir, "SKILL.md");
-            deps.copyFile(skill.sourcePath, skillDest);
+            deps.copySkill(skill.sourcePath, skillDest);
             console.log(`✓ Copied skill "${skill.name}" to OpenCode ${isProjectLevel ? 'project' : 'user'} directory: ${skillDir}`);
         } catch (error) {
             console.log(`⚠️  Failed to copy skill "${skill.name}" to OpenCode ${isProjectLevel ? 'project' : 'user'} directory: ${error.message}`);

package/scripts/lib/qoder.js

@@ -192,7 +192,7 @@ function copySkillToQoder(deps, isProjectLevel = false) {
         try {
             deps.ensureDirectory(skillDir);
             const skillDest = path.join(skillDir, "SKILL.md");
-            deps.copyFile(skill.sourcePath, skillDest);
+            deps.copySkill(skill.sourcePath, skillDest);
             console.log(`✓ Copied skill "${skill.name}" to Qoder ${isProjectLevel ? "project" : "user"} directory: ${skillDir}`);
         } catch (error) {
             console.log(`⚠️  Failed to copy skill "${skill.name}" to Qoder ${isProjectLevel ? "project" : "user"} directory: ${error.message}`);

package/scripts/lib/trae-cli.js

@@ -226,7 +226,7 @@ export function copySkillToTraeCli(deps, isProjectLevel = false) {
         try {
             deps.ensureDirectory(skillDir);
             const skillDest = path.join(skillDir, "SKILL.md");
-            deps.copyFile(skill.sourcePath, skillDest);
+            deps.copySkill(skill.sourcePath, skillDest);
             console.log(`✓ Copied skill "${skill.name}" to Trae CLI ${isProjectLevel ? 'project' : 'user'} directory: ${skillDir}`);
         } catch (error) {
             console.log(`⚠️  Failed to copy skill "${skill.name}" to Trae CLI ${isProjectLevel ? 'project' : 'user'} directory: ${error.message}`);

package/scripts/lib/trae-ide.js

@@ -207,7 +207,7 @@ export function copySkillToTrae(deps, isProjectLevel = false) {
         try {
             deps.ensureDirectory(skillDir);
             const skillDest = path.join(skillDir, "SKILL.md");
-            deps.copyFile(skill.sourcePath, skillDest);
+            deps.copySkill(skill.sourcePath, skillDest);
             console.log(`✓ Copied skill "${skill.name}" to Trae ${isProjectLevel ? 'project' : 'user'} directory: ${skillDir}`);
         } catch (error) {
             console.log(`⚠️  Failed to copy skill "${skill.name}" to Trae ${isProjectLevel ? 'project' : 'user'} directory: ${error.message}`);

package/scripts/postinstall.js

@@ -39,6 +39,7 @@ const deps = {
     isCommandAvailable: common.isCommandAvailable,
     ensureDirectory: common.ensureDirectory,
     copyFile: common.copyFile,
+    copySkill: common.copySkill,
     writeFile: common.writeFile,
     discoverSkills: common.discoverSkills,
     SKILL_SOURCE: common.SKILL_SOURCE,

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

@@ -1,11 +1,14 @@
 ---
 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 服务端可直连，不要使用本技能。
+description: 本地网络 API 工具，专门处理 10.x.x.x 网段的 Swagger/YApi 文档拉取和联调测试。内置 scripts/extract_swagger.py 一步完成"下载→解析→按 tag 过滤→关联 DTO definitions→输出"，与服务端 parseApiDocs 一比一对齐（递归深度 5、两层 definitions、传递闭包裁剪），避免 curl 管道截断和手写花括号平衡脚本的弯路。仅当脚本不可用时回退到服务端 parse_swagger_json 兜底。**仅限 10.x.x.x 网段**，172.16-31.x.x 和 192.168.x.x 服务端可直连，不要使用本技能。
 compatibility:
   tools:
     - run_command
     - web_search
     - web_fetch
+  runtime:
+    - python3 >= 3.7
+    - curl
 ---
 
 # 本地网络 API 工具（local-api-tool）
@@ -37,25 +40,50 @@ compatibility:
 
 ### 流程 A：拉取 Swagger API 文档（fetch）
 
+> **优先使用内置脚本 `scripts/extract_swagger.py`**，一步完成"下载 → 解析 → 过滤 → 关联 DTO → 输出"，避免 curl 管道截断、临时脚本花括号平衡等弯路。脚本与服务端 `parseApiDocs` 一比一对齐（递归深度 5、两层 definitions、传递闭包裁剪）。
+> 仅当脚本不可用（无 python3 / 文件权限缺失）时才回退到「手工 curl + 服务端 parse_swagger_json」兜底流程。
+
+#### A1. 内置脚本路径（首选）
+
 ```
 用户请求 fetch Swagger URL (10.x.x.x)
     │
     ▼
-调用 api_tool(action="fetch", url=...)
+AI 识别 10.x.x.x 网段（或服务端返回 LOCAL_NETWORK_UNREACHABLE）
+    │
+    ▼
+通过 run_command 在本地执行：
+  bash $SKILL_DIR/scripts/extract_swagger.py \
+      --url <apiDocsUrl> [--cookie '...'] [--filter <关键词>] [--out /tmp/parsed.json]
     │
     ▼
-服务端返回 { reason: "LOCAL_NETWORK_UNREACHABLE", action: "请使用 local-api-tool ...", swaggerEndpoints: {...} }
+脚本内部：curl 下载 → 解析 → 过滤 paths → 自动展开被引用 DTO → 输出 JSON
+    │
+    ▼
+AI 读取脚本输出（或 --out 指定的文件），结构与 api_tool(parse_swagger_json) 完全一致：
+  { info, basePath, tags, apis, definitions, definitionsDetail, _filter? }
+```
+
+**$SKILL_DIR 是本 skill 的绝对目录**。在 qwen/qoder 中 skill 加载时通常通过环境变量或上下文提供，若不确定可用：
+- qwen-extension: `~/.qwen/extensions/szcd-component-helper/skills/local-api-tool/scripts/extract_swagger.py`
+- opencode-extension: `~/.config/opencode/extensions/szcd-component-helper/skills/local-api-tool/scripts/extract_swagger.py`
+
+#### A2. 服务端兜底（脚本不可用时）
+
+```
+调用 api_tool(action="fetch", url=...)
     │
     ▼
-AI 识别 LOCAL_NETWORK_UNREACHABLE，读取 swaggerEndpoints 和 authInfo
+服务端返回 { reason: "LOCAL_NETWORK_UNREACHABLE", swaggerEndpoints, authInfo }
     │
     ▼
-AI 通过 run_command 在本地执行 curl：
+AI 通过 run_command 在本地 curl 写到临时文件（禁止管道截断！）：
   步骤1: 鉴权获取 Cookie（如 authInfo.hasPassword 为 true）
-  步骤2: 获取完整 API 文档 JSON
+  步骤2: curl -o /tmp/swagger.json <apiDocsUrl>      ← 必须写文件
     │
     ▼
-AI 调用 api_tool(action="parse_swagger_json", swaggerJson=..., swaggerSourceUrl=...)
+AI 读取整个文件传给服务端：
+  api_tool(action="parse_swagger_json", swaggerJson=<完整 JSON 字符串>, apiFilter=<可选>)
     │
     ▼
 返回解析后的 API 文档给用户
@@ -84,7 +112,97 @@ AI 通过 run_command 在本地执行对应 curl 命令
 
 ## 详细执行步骤
 
-### 一、拉取 Swagger 文档（action=fetch）
+### 一、拉取 Swagger 文档（推荐路径：extract_swagger.py）
+
+**前提**：本地有 python3（≥ 3.7）和 curl。脚本只依赖标准库，无第三方依赖。
+
+#### 1.1 直接通过 URL 下载并解析（推荐）
+
+```bash
+# 无鉴权
+python3 ~/.qwen/extensions/szcd-component-helper/skills/local-api-tool/scripts/extract_swagger.py \
+  --url 'http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs' \
+  --out /tmp/parsed.json
+
+# 有鉴权（先单独 curl 拿 Cookie，参考下方 1.3）
+python3 .../extract_swagger.py \
+  --url 'http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs' \
+  --cookie 'JSESSIONID=xxx' \
+  --out /tmp/parsed.json
+
+# 按关键词过滤 + 自动裁剪 definitionsDetail（仅保留被引用的 VO 及传递闭包）
+python3 .../extract_swagger.py \
+  --url '<apiDocsUrl>' \
+  --filter tag --filter user \
+  --out /tmp/parsed.json
+```
+
+#### 1.2 读取已下载的本地 JSON 文件
+
+```bash
+# 第一步：curl 写文件（务必用 -o 写文件，不要用管道，避免大 JSON 被截断）
+curl -sS --connect-timeout 10 --max-time 30 \
+  -H 'Accept: application/json' \
+  -H 'Cookie: <Cookie>' \
+  -o /tmp/swagger-raw.json \
+  'http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs'
+
+# 第二步：交给脚本解析
+python3 .../extract_swagger.py --file /tmp/swagger-raw.json --filter tag --out /tmp/parsed.json
+```
+
+#### 1.3 鉴权（如需 Cookie）
+
+```bash
+# 取 Cookie（注意 -D - 把响应头打到 stdout）
+curl -sS -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' \
+  -o /dev/null \
+  | grep -i '^set-cookie:' | head -1 | sed 's/.*: //; s/;.*//'
+```
+
+将得到的 `JSESSIONID=xxx` 传给 `--cookie` 参数。
+
+#### 1.4 单独查询某个 VO/DTO 完整定义（兜底）
+
+如果脚本已经解析过、但 AI 后续发现某个 `definitionsDetail` 之外的 VO 也需要展开，用：
+
+```bash
+python3 .../extract_swagger.py --file /tmp/swagger-raw.json --definition KnowledgeOperLogVO
+```
+
+找不到时会自动给出模糊匹配建议（最多 10 个）。
+
+#### 1.5 输出结构（与服务端 `parse_swagger_json` 一致）
+
+```json
+{
+  "info": { "title": "...", "version": "...", "description": "..." },
+  "basePath": "/svc",
+  "tags": [{ "name": "tag", "description": "..." }],
+  "apis": [
+    {
+      "url": "/tag/pageList",
+      "method": "POST",
+      "tag": "tag",
+      "summary": "标签分页查询",
+      "operationId": "tagPageList",
+      "parameters": [
+        { "name": "body", "in": "body", "required": true,
+          "dtoRef": "TagQueryDTO",
+          "dtoProperties": [ /* 递归展开，required 字段已标注 */ ] }
+      ],
+      "response": { "voName": "ResponseTagPage", "properties": [ /* 递归展开 */ ] }
+    }
+  ],
+  "definitions": [ /* 摘要：所有 VO/DTO 的 name + type + description */ ],
+  "definitionsDetail": [ /* 详情：被 apis 引用的 VO/DTO 及传递闭包，深度5 */ ],
+  "_filter": { "keywords": ["tag"], "total": 50, "matched": 12 }   // 仅 --filter 生效时出现
+}
+```
+
+### 二、服务端兜底路径（脚本不可用时）
 
 **步骤 1：调用服务端 api_tool**
 
@@ -111,41 +229,38 @@ api_tool(action="fetch", url="http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/i
 }
 ```
 
-**步骤 3：AI 通过 run_command 在本地执行 curl**
-
-根据返回数据中的 `authInfo` 和 `swaggerEndpoints`，AI 自行构造 curl 命令并通过 `run_command` 在本地执行：
-
-3a. **鉴权（如 authInfo.hasPassword 为 true）**：
+**步骤 3：本地 curl 写入临时文件（禁止管道截断！）**
 
 ```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'
-```
+# 鉴权（如需要）
+curl -sS -D - -X GET '<authUrl>' \
+  -H 'Authorization: Basic <base64(user:pass)>' \
+  -o /dev/null | grep -i '^set-cookie:' | head -1 | sed 's/.*: //; s/;.*//'
 
-从输出的 `Set-Cookie:` 行提取 Cookie 值（分号前的部分）。
-
-3b. **获取 API 文档 JSON**：直接使用 `swaggerEndpoints.apiDocsUrl`：
-
-```bash
-curl -s -X GET 'http://10.2.7.60:30194/ikmp-knowledge/v2/api-docs' \
+# 下载 API 文档（务必 -o 写文件，不要 | head / | python）
+curl -sS --connect-timeout 10 --max-time 30 \
   -H 'Accept: application/json' \
-  -H 'Cookie: <步骤3a获取的Cookie>'
+  -H 'Cookie: <步骤上一步的 Cookie>' \
+  -o /tmp/swagger-raw.json \
+  '<apiDocsUrl>'
 ```
 
-如果 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")
+api_tool(
+  action="parse_swagger_json",
+  swaggerJson=<读取 /tmp/swagger-raw.json 的完整内容>,
+  swaggerSourceUrl="http://10.2.7.60:30194/ikmp-knowledge/swagger-ui/index.html",
+  apiFilter=["tag"]   // 可选，强烈推荐：按关键词过滤 + 自动裁剪 definitionsDetail
+)
 ```
 
 **步骤 5：返回解析结果**
 
-将 `parse_swagger_json` 返回的解析结果直接返回给用户，格式与正常 fetch 完全一致。
+将返回结果直接呈现给用户。
 
-### 二、联调测试（action=test）
+### 三、联调测试（action=test）
 
 **步骤 1：调用服务端 api_tool**
 
@@ -196,13 +311,24 @@ curl -s -X POST 'http://10.2.7.60:30194/ikmp-knowledge/api/xxx' \
 
 将 curl 的响应内容返回给用户。如果是 JSON 格式，尽量格式化输出。
 
+## ⚠️ 避坑指南（来自历史反馈）
+
+1. **禁止用 `curl | head/tail/jq/python` 对完整 Swagger JSON 做管道切片** —— curl 管道经常因下游 SIGPIPE 截断，导致 JSON 不闭合 / Python 解析失败 / 临时写花括号平衡脚本，是历史踩坑率最高的反模式。**必须用 `-o /tmp/xxx.json` 写文件**，再用脚本或 `parse_swagger_json` 处理。
+2. **不要在本地手写 Python 切 Swagger** —— `extract_swagger.py` 已经做了和服务端 `parseApiDocs` 完全对齐的递归展开、传递闭包、required 标注、过滤裁剪。本地手写一个 mini 版只会丢字段或踩 `$ref`/`originalRef` 双字段陷阱。
+3. **过滤优先用 `--filter`（脚本）或 `apiFilter`（服务端）** —— 不要先拿全量再让 AI 自己挑接口看，过滤后 `definitionsDetail` 会自动按传递闭包裁剪，输出量减少 70%+。
+4. **单 VO 查询用 `--definition`（脚本）或 `get_definition`（服务端）** —— 不要回头再拉一次全量。
+
 ## 快捷方式：AI 直接识别 10 段地址
 
-如果 AI 能识别出用户请求的 URL 中包含 `10.x.x.x` 主机地址，可以**直接跳过首次 api_tool 调用**，在本地执行 curl，再调用 `parse_swagger_json`，减少一次无用的服务端请求：
+如果 AI 能识别出用户请求的 URL 中包含 `10.x.x.x` 主机地址，可以**直接跳过首次 api_tool 调用**，在本地执行脚本，减少一次无用的服务端请求：
 
-1. 从 Swagger URL 推导鉴权地址、文档地址
-2. 通过 `run_command` 在本地依次 curl
-3. 调用 `api_tool(action="parse_swagger_json")` 解析
+```bash
+python3 ~/.qwen/extensions/szcd-component-helper/skills/local-api-tool/scripts/extract_swagger.py \
+  --url 'http://10.x.x.x/<service>/v2/api-docs' \
+  [--cookie '<JSESSIONID=...>'] \
+  [--filter '<关键词>'] \
+  --out /tmp/parsed.json
+```
 
 ### URL 推导规则
 
@@ -214,33 +340,11 @@ curl -s -X POST 'http://10.2.7.60:30194/ikmp-knowledge/api/xxx' \
 | 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'` 传递
+1. **Cookie 传递**：鉴权步骤获取的 Cookie 通过 `--cookie` 传给脚本，或通过 `-H 'Cookie: xxx'` 传给 curl
 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，无需让用户手动复制粘贴命令
+3. **JSON 格式**：脚本/curl 获取的 API 文档必须是有效的 Swagger JSON，否则 `extract_swagger.py` / `parse_swagger_json` 会报错（脚本会打印预览前 200 字符方便排查）
+4. **超时处理**：脚本和 curl 都已内置 `--connect-timeout 10 --max-time 30`，可通过 `--timeout` 调整
+5. **错误处理**：脚本退出码 1=参数错误 / 2=网络IO / 3=解析；如果某步骤失败，将错误信息返回给用户，不要继续后续步骤
+6. **自动执行**：AI 识别 10.x.x.x 或 `reason: "LOCAL_NETWORK_UNREACHABLE"` 后应**自动**通过 `run_command` 执行脚本，无需让用户手动复制粘贴命令