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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (16) hide show
  1. package/agents/opencode-extension/agents/szcd-component-expert.md +9 -9
  2. package/agents/qwen-extension/agents/szcd-component-expert.md +9 -9
  3. package/agents/src/szcd-component-expert.md +9 -9
  4. package/agents/szcd-component-expert.md +9 -9
  5. package/agents/szcd-component-expert.qoder.md +9 -9
  6. package/agents/szcd-component-expert.trae.md +9 -9
  7. package/opencode-extension/agents/szcd-component-expert.md +9 -9
  8. package/opencode-extension/skills/szcd-component-helper/SKILL.md +15 -13
  9. package/opencode-extension/skills/szcd-design-to-code/SKILL.md +66 -27
  10. package/package.json +1 -1
  11. package/qwen-extension/agents/szcd-component-expert.md +9 -9
  12. package/qwen-extension/qwen-extension.json +1 -1
  13. package/qwen-extension/skills/szcd-component-helper/SKILL.md +15 -13
  14. package/qwen-extension/skills/szcd-design-to-code/SKILL.md +66 -27
  15. package/standard-skill/szcd-component-helper/SKILL.md +15 -13
  16. package/standard-skill/szcd-design-to-code/SKILL.md +66 -27
package/agents/opencode-extension/agents/szcd-component-expert.md CHANGED
@@ -79,7 +79,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
79
79
  1. **加载文件**：
80
80
  - `loadSketchByPath` 加载 .sketch 文件
81
81
  - `listPages` 列出所有页面
82
- - `listNodesByPage`（type="artboard"）获取画板列表
82
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
83
83
  - 根据画板名称选择目标页面
84
84
 
85
85
  2. **获取完整节点树**：
@@ -88,7 +88,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
88
88
  - 拿到所有节点 ID 列表，为下一步分组做准备
89
89
 
90
90
  3. **按类型分组统计**：
91
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
91
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
92
92
  - 识别组件模式：
93
93
  - `group(rectangle + text)` = 标签组件（如状态徽章）
94
94
  - `group(text + text + rectangle...)` = 表单项
@@ -114,9 +114,9 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
114
114
 
115
115
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
116
116
  ```
117
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
117
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
118
118
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
119
- → getNodesSummary(groupBy="type")
119
+ → getPageStructure(pageId, mode="summary", groupBy="type")
120
120
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
121
121
  → [进入主流程步骤 3.5 统一推理]
122
122
  ```
@@ -127,7 +127,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
127
127
  |------|------------|---------|
128
128
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
129
129
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
130
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
130
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
131
131
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
132
132
 
133
133
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -165,15 +165,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
165
165
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
166
166
 
167
167
  **提示**：
168
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
169
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
170
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
168
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
169
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
170
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
171
171
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
172
172
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
173
173
 
174
174
  **提示**：
175
175
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
176
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
176
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
177
177
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
178
178
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
179
179
 
package/agents/qwen-extension/agents/szcd-component-expert.md CHANGED
@@ -75,7 +75,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
75
75
  1. **加载文件**：
76
76
  - `loadSketchByPath` 加载 .sketch 文件
77
77
  - `listPages` 列出所有页面
78
- - `listNodesByPage`（type="artboard"）获取画板列表
78
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
79
79
  - 根据画板名称选择目标页面
80
80
 
81
81
  2. **获取完整节点树**：
@@ -84,7 +84,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
84
84
  - 拿到所有节点 ID 列表，为下一步分组做准备
85
85
 
86
86
  3. **按类型分组统计**：
87
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
87
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
88
88
  - 识别组件模式：
89
89
  - `group(rectangle + text)` = 标签组件（如状态徽章）
90
90
  - `group(text + text + rectangle...)` = 表单项
@@ -110,9 +110,9 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
110
110
 
111
111
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
112
112
  ```
113
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
113
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
114
114
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
115
- → getNodesSummary(groupBy="type")
115
+ → getPageStructure(pageId, mode="summary", groupBy="type")
116
116
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
117
117
  → [进入主流程步骤 3.5 统一推理]
118
118
  ```
@@ -123,7 +123,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
123
123
  |------|------------|---------|
124
124
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
125
125
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
126
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
126
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
127
127
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
128
128
 
129
129
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -161,15 +161,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
161
161
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
162
162
 
163
163
  **提示**：
164
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
165
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
166
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
164
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
165
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
166
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
167
167
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
168
168
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
169
169
 
170
170
  **提示**：
171
171
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
172
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
172
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
173
173
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
174
174
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
175
175
 
package/agents/src/szcd-component-expert.md CHANGED
@@ -150,7 +150,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
150
150
  1. **加载文件**：
151
151
  - `loadSketchByPath` 加载 .sketch 文件
152
152
  - `listPages` 列出所有页面
153
- - `listNodesByPage`（type="artboard"）获取画板列表
153
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
154
154
  - 根据画板名称选择目标页面
155
155
 
156
156
  2. **获取完整节点树**：
@@ -159,7 +159,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
159
159
  - 拿到所有节点 ID 列表，为下一步分组做准备
160
160
 
161
161
  3. **按类型分组统计**：
162
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
162
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
163
163
  - 识别组件模式：
164
164
  - `group(rectangle + text)` = 标签组件（如状态徽章）
165
165
  - `group(text + text + rectangle...)` = 表单项
@@ -185,9 +185,9 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
185
185
 
186
186
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
187
187
  ```
188
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
188
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
189
189
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
190
- → getNodesSummary(groupBy="type")
190
+ → getPageStructure(pageId, mode="summary", groupBy="type")
191
191
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
192
192
  → [进入主流程步骤 3.5 统一推理]
193
193
  ```
@@ -198,7 +198,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
198
198
  |------|------------|---------|
199
199
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
200
200
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
201
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
201
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
202
202
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
203
203
 
204
204
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -236,15 +236,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
236
236
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
237
237
 
238
238
  **提示**：
239
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
240
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
241
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
239
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
240
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
241
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
242
242
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
243
243
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
244
244
 
245
245
  **提示**：
246
246
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
247
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
247
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
248
248
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
249
249
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
250
250
 
package/agents/szcd-component-expert.md CHANGED
@@ -79,7 +79,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
79
79
  1. **加载文件**：
80
80
  - `loadSketchByPath` 加载 .sketch 文件
81
81
  - `listPages` 列出所有页面
82
- - `listNodesByPage`（type="artboard"）获取画板列表
82
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
83
83
  - 根据画板名称选择目标页面
84
84
 
85
85
  2. **获取完整节点树**：
@@ -88,7 +88,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
88
88
  - 拿到所有节点 ID 列表，为下一步分组做准备
89
89
 
90
90
  3. **按类型分组统计**：
91
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
91
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
92
92
  - 识别组件模式：
93
93
  - `group(rectangle + text)` = 标签组件（如状态徽章）
94
94
  - `group(text + text + rectangle...)` = 表单项
@@ -114,9 +114,9 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
114
114
 
115
115
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
116
116
  ```
117
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
117
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
118
118
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
119
- → getNodesSummary(groupBy="type")
119
+ → getPageStructure(pageId, mode="summary", groupBy="type")
120
120
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
121
121
  → [进入主流程步骤 3.5 统一推理]
122
122
  ```
@@ -127,7 +127,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
127
127
  |------|------------|---------|
128
128
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
129
129
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
130
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
130
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
131
131
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
132
132
 
133
133
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -165,15 +165,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
165
165
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
166
166
 
167
167
  **提示**：
168
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
169
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
170
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
168
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
169
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
170
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
171
171
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
172
172
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
173
173
 
174
174
  **提示**：
175
175
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
176
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
176
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
177
177
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
178
178
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
179
179
 
package/agents/szcd-component-expert.qoder.md CHANGED
@@ -129,7 +129,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
129
129
  1. **加载文件**：
130
130
  - `loadSketchByPath` 加载 .sketch 文件
131
131
  - `listPages` 列出所有页面
132
- - `listNodesByPage`（type="artboard"）获取画板列表
132
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
133
133
  - 根据画板名称选择目标页面
134
134
 
135
135
  2. **获取完整节点树**：
@@ -138,7 +138,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
138
138
  - 拿到所有节点 ID 列表，为下一步分组做准备
139
139
 
140
140
  3. **按类型分组统计**：
141
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
141
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
142
142
  - 识别组件模式：
143
143
  - `group(rectangle + text)` = 标签组件（如状态徽章）
144
144
  - `group(text + text + rectangle...)` = 表单项
@@ -164,9 +164,9 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
164
164
 
165
165
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
166
166
  ```
167
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
167
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
168
168
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
169
- → getNodesSummary(groupBy="type")
169
+ → getPageStructure(pageId, mode="summary", groupBy="type")
170
170
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
171
171
  → [进入主流程步骤 3.5 统一推理]
172
172
  ```
@@ -177,7 +177,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
177
177
  |------|------------|---------|
178
178
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
179
179
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
180
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
180
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
181
181
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
182
182
 
183
183
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -215,15 +215,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
215
215
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
216
216
 
217
217
  **提示**：
218
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
219
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
220
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
218
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
219
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
220
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
221
221
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
222
222
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
223
223
 
224
224
  **提示**：
225
225
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
226
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
226
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
227
227
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
228
228
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
229
229
 
package/agents/szcd-component-expert.trae.md CHANGED
@@ -93,7 +93,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
93
93
  1. **加载文件**：
94
94
  - `loadSketchByPath` 加载 .sketch 文件
95
95
  - `listPages` 列出所有页面
96
- - `listNodesByPage`（type="artboard"）获取画板列表
96
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
97
97
  - 根据画板名称选择目标页面
98
98
 
99
99
  2. **获取完整节点树**：
@@ -102,7 +102,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
102
102
  - 拿到所有节点 ID 列表，为下一步分组做准备
103
103
 
104
104
  3. **按类型分组统计**：
105
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
105
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
106
106
  - 识别组件模式：
107
107
  - `group(rectangle + text)` = 标签组件（如状态徽章）
108
108
  - `group(text + text + rectangle...)` = 表单项
@@ -128,9 +128,9 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
128
128
 
129
129
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
130
130
  ```
131
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
131
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
132
132
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
133
- → getNodesSummary(groupBy="type")
133
+ → getPageStructure(pageId, mode="summary", groupBy="type")
134
134
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
135
135
  → [进入主流程步骤 3.5 统一推理]
136
136
  ```
@@ -141,7 +141,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
141
141
  |------|------------|---------|
142
142
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
143
143
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
144
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
144
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
145
145
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
146
146
 
147
147
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -179,15 +179,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
179
179
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
180
180
 
181
181
  **提示**：
182
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
183
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
184
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
182
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
183
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
184
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
185
185
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `mcp__szcd-component-helper__analyze_design_image`
186
186
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
187
187
 
188
188
  **提示**：
189
189
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
190
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
190
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
191
191
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `mcp__szcd-component-helper__analyze_design_image`
192
192
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
193
193
 
package/opencode-extension/agents/szcd-component-expert.md CHANGED
@@ -79,7 +79,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
79
79
  1. **加载文件**：
80
80
  - `loadSketchByPath` 加载 .sketch 文件
81
81
  - `listPages` 列出所有页面
82
- - `listNodesByPage`（type="artboard"）获取画板列表
82
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
83
83
  - 根据画板名称选择目标页面
84
84
 
85
85
  2. **获取完整节点树**：
@@ -88,7 +88,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
88
88
  - 拿到所有节点 ID 列表，为下一步分组做准备
89
89
 
90
90
  3. **按类型分组统计**：
91
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
91
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
92
92
  - 识别组件模式：
93
93
  - `group(rectangle + text)` = 标签组件（如状态徽章）
94
94
  - `group(text + text + rectangle...)` = 表单项
@@ -114,9 +114,9 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
114
114
 
115
115
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
116
116
  ```
117
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
117
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
118
118
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
119
- → getNodesSummary(groupBy="type")
119
+ → getPageStructure(pageId, mode="summary", groupBy="type")
120
120
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
121
121
  → [进入主流程步骤 3.5 统一推理]
122
122
  ```
@@ -127,7 +127,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
127
127
  |------|------------|---------|
128
128
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
129
129
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
130
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
130
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
131
131
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
132
132
 
133
133
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -165,15 +165,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
165
165
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
166
166
 
167
167
  **提示**：
168
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
169
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
170
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
168
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
169
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
170
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
171
171
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
172
172
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
173
173
 
174
174
  **提示**：
175
175
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
176
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
176
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
177
177
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
178
178
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
179
179
 
package/opencode-extension/skills/szcd-component-helper/SKILL.md CHANGED
@@ -81,14 +81,14 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
81
81
  ### 步骤3.5：Sketch 文件解析（如有 .sketch 设计稿）
82
82
  - **当用户提供 .sketch 文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`
83
83
  - 工作流（4步直传）：
84
- 1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `listNodesByPage(type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
84
+ 1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `queryNodes(pageId, type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
85
85
  2. **获取组件库架构**（复用步骤1结果）：`get_architecture_overview` 的 `templatePatterns` 提供模板组合模式，`llmMappingHints` 提供常见错误修正
86
86
  3. **LLM 推理组件范围**：从 Sketch 结构化数据推断画板名称→`pageName`、区域分布→`layoutType`、图层类型→组件映射，对照 `templatePatterns` 选择最匹配的模板，输出组件候选列表
87
87
  4. **批量获取组件详情**：调用 `get_component_full_profile(name="Query,TableOrList,LeftTree,TemplateMode", depth="deep")` 一次性获取所有需要的组件 API
88
88
 
89
89
  **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
90
90
  ```
91
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
91
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
92
92
  → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
93
93
  → get_component_full_profile(批量) → 编码
94
94
  ```
@@ -107,7 +107,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
107
107
 
108
108
  **提示**：
109
109
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
110
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
110
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
111
111
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
112
112
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
113
113
 
@@ -124,7 +124,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
124
124
  - 若用户表示不准确或不采纳，收集原因
125
125
  - 调用 `submit_feedback` 将反馈提交到服务器
126
126
 
127
- ## 可用工具（13 + 17 Sketch）
127
+ ## 可用工具（13 + 15 Sketch）
128
128
 
129
129
  ### Sketch 文件解析工具（sketch-mcp-server，独立 MCP Server）
130
130
 
@@ -152,26 +152,28 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
152
152
  - `nodeId` (string, required): 节点 ID（artboard 级别效果最佳）
153
153
  - `format` (enum, optional, default: "svg"): 输出格式，当前仅支持 svg
154
154
 
155
- #### S5. getNodesSummary
155
+ #### S5. getPageStructure (mode="summary")
156
156
  **功能**：获取节点统计摘要，Token 消耗比完整信息减少 80-90%。
157
157
  **参数**：
158
- - `pageId` (string, optional): 页面 ID
158
+ - `pageId` (string, required): 页面 ID
159
+ - `mode` (string, required): "summary"
159
160
  - `groupBy` (enum, optional): type/style/position/size
160
- - `includeStats` (boolean, optional, default: true)
161
+ - `maxSamples` (number, optional, default: 5)
161
162
 
162
- #### S6. findNodesByName
163
+ #### S6. queryNodes (name 参数)
163
164
  **功能**：按名称搜索节点，支持模糊匹配。
164
165
  **参数**：
165
166
  - `name` (string, required): 搜索关键词
166
- - `limit` (number, optional, default: 10): 最大返回数量
167
+ - `limit` (number, optional, default: 50): 最大返回数量
167
168
 
168
- #### S7-S17. 其他 Sketch 工具
169
- - `listNodes` / `listNodesByPage` — 列出节点（含过滤）
169
+ #### S7-S15. 其他 Sketch 工具
170
+ - `queryNodes` — 统一节点查询（支持 pageId/type/name/nameContains/limit/offset）
170
171
  - `getNodeInfo` / `getMultipleNodeInfo` — 获取节点详情
171
- - `getNodePosition` — 获取节点位置
172
172
  - `getDocumentStructure` — 获取文档结构（支持字段过滤和摘要模式）
173
- - `getSymbolMasters` / `getSymbolInstances` — Symbol 组件管理
173
+ - `getSymbols` — Symbol 组件查询（type="master" 或 "instance"）
174
174
  - `getSymbolMasterBySymbolID` / `getSymbolInstanceStyles` — Symbol 详情
175
+ - `getShapePathData` — 提取 shapePath SVG 路径数据
176
+ - `extractBitmaps` / `matchIconFromName` — 资源提取与图标匹配
175
177
 
176
178
  ### 复合组件工具
177
179
 
package/opencode-extension/skills/szcd-design-to-code/SKILL.md CHANGED
@@ -55,42 +55,80 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
55
55
 
56
56
  ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
57
57
 
58
- **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
58
+ **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。`getMultipleNodeInfo` 支持任意数量 ID（内部自动分片），比逐个 `getNodeInfo` 快 10 倍以上。
59
59
 
60
- **工具调用顺序（深度探查，像素级还原）**：
60
+ **工具调用顺序（优化后，4 次主调用）**：
61
61
 
62
- 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
62
+ 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件（内部自动解压并保存目录，供后续 extractBitmaps 使用）
63
63
  2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
64
- 3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
65
- 4. `mcp__sketch-mcp-server__getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
66
- 5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
67
- - `group(rectangle + text)` = 标签组件
68
- - `group(text + text + rectangle...)` = 表单项
69
- - 统计各类型数量，决定下一批查询范围
70
- 6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
64
+ 3. `mcp__sketch-mcp-server__queryNodes`（pageId, type="artboard"）— 获取画板列表，确定目标画板
65
+ 4. `mcp__sketch-mcp-server__getPageStructure`（pageId, mode="ids"）**替代旧的 getPageStructure + getNodesSummary 组合**
66
+ - 一次返回按类型分组的全量 ID：`{ text: [...], rectangle: [...], bitmap: [...], shapePath: [...] }`
67
+ - 可选 `typeFilter` 参数限制返回类型
68
+ - 同时返回 `summary`（各类型统计）和 `totalIds`（总数）
69
+ 5. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[所有 text + rectangle ID]）— **支持任意数量 ID，内部自动分批处理**
71
70
  - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
72
- - 不要逐个 `getNodeInfo`，太慢且容易漏
71
+ - 无需手动分批，传入全部 ID 即可（内部按 100 个一批自动处理）
73
72
 
74
- **⚠️ 与旧策略的差异**：
75
- - 旧策略：maxDepth=2 拿布局，样式靠组件默认
76
- - 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
77
- - 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
78
- - 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
73
+ **与旧策略的差异**：
74
+ - 旧策略：`getPageStructure`(可能截断) + `getNodesSummary` + 手动分批 `getMultipleNodeInfo`
75
+ - 新策略：`getPageStructure(mode="ids")`(轻量全量 ID) + `getMultipleNodeInfo`(自动分片)
76
+ - 调用次数：旧 6 次 → 新 4 次（含 loadSketch + listPages 合并）
79
77
 
80
78
  **步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
81
- - Sketch 节点结构 + 全量节点 ID 列表
79
+ - 按类型分组的全量节点 ID 列表
82
80
  - text/rectangle 节点的完整样式 Token
83
- - 图表区结构规律识别结果
81
+ - bitmap ID 列表（传给步骤 2.5.1）
82
+ - shapePath 节点名列表（传给步骤 2.5.1）
84
83
 
85
84
  组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程中结合步骤 1 的 `templatePatterns` 推理**（详见主流程步骤 4 前置说明）。
86
85
 
86
+ ### 步骤2.5.1：图标与位图提取（有 bitmap/shapePath 节点时执行）
87
+
88
+ **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
89
+
90
+ **工具调用**：
91
+
92
+ 1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
93
+ - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
94
+ - 位图资源用于 CSS `background-image` 引用
95
+ 2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库
96
+ - 输入 shapePath 节点名列表（如 `["表 icon", "文件 icon"]`）
97
+ - 匹配策略：节点名关键词 → 拼音匹配图标列表
98
+ - 返回格式：
99
+ ```json
100
+ {
101
+ "matchedIcons": [
102
+ { "nodeName": "表 icon", "iconType": "icon-biao", "library": "newFont" }
103
+ ],
104
+ "unmatched": ["菜单icon"],
105
+ "recommendFallback": { "菜单icon": "antd MenuOutlined" },
106
+ "matchRate": "80.0%"
107
+ }
108
+ ```
109
+
110
+ **步骤 2.5.1 产出物**：
111
+ - bitmap base64 资源列表 → 用于代码中的 CSS background-image
112
+ - IconfontWapper 代码片段（`<IconfontWapper assets="newFont" type="icon-biao" />`）
113
+ - 未匹配节点的 fallback 建议（antd 图标替代）
114
+
115
+ ### 步骤2.5.2：批量样式提取（合并入步骤 2.5）
116
+
117
+ 此步骤已合并入步骤 2.5 第 5 步，`getMultipleNodeInfo` 现在支持自动分片，无需手动分批调用。
118
+
87
119
  ### 步骤2.5 实战经验沉淀（重要）
88
120
 
89
- **经验1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
90
- - 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
91
- - 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
121
+ **经验1：用 `getPageStructure(mode="ids")` 一步拿全量 ID，避免 getPageStructure 截断**
122
+ - 错误做法：用 `getPageStructure(pageId)` 拿节点树 → 大文件截断 → 需要 agent 解析
123
+ - 正确做法：`getPageStructure(pageId, mode="ids")` 轻量返回 `{ text: [ids], rectangle: [ids], bitmap: [ids] }` → 无截断风险
124
+ - 如需节点层级关系，用 `getPageStructure(pageId, fields=["id","name","type"])` 过滤字段
125
+
126
+ **经验2：`getMultipleNodeInfo` 支持任意数量，无需手动分批**
127
+ - 旧做法：手动把 ID 分成每批 ≤ 100 个 → 多次调用
128
+ - 新做法：直接传入全部 ID（如 200 个）→ 内部自动按 100 个一批处理 → 返回合并结果
129
+ - 返回结构不变：`{ nodes: [...], total, requested, batches }`
92
130
 
93
- **经验2：text 节点是颜色/DOM 映射的两级索引**
131
+ **经验3：text 节点是颜色/DOM 映射的两级索引**
94
132
  每个 text 节点同时关联两种上下文，**必须同批拉取**：
95
133
  - 自身样式：`fontSize`、`fontWeight`、`text.color`
96
134
  - 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
@@ -98,7 +136,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
98
136
  错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
99
137
  正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
100
138
 
101
- **经验3：图表区样式提取有规律可循**
139
+ **经验4：图表区样式提取有规律可循**
102
140
 
103
141
  | 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
104
142
  |---|---|---|
@@ -113,10 +151,11 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
113
151
 
114
152
  识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
115
153
 
116
- **经验4：矢量图形是工具链盲区（兜底方案）**
117
- - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%（实战中 434/926），但 `renderNodeAsBase64` 不支持渲染
118
- - 解压 `.sketch`（zip 格式）只能提取 `bitmap` 中内嵌的 PNG/PDF（实战中可能仅 2 张，常是侧边栏 Logo）
119
- - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
154
+ **经验5：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
155
+ - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
156
+ - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
157
+ - bitmap 用 `extractBitmaps(bitmapIds)` 自动提取 PNG 资源
158
+ - 兜底：未匹配的节点用 antd `@ant-design/icons` 同语义图标替代，在代码注释中标注“⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath”
120
159
 
121
160
  ### 步骤3：分析设计稿图片（有图片时执行）
122
161
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@szc-ft/mcp-szcd-client",
3
- "version": "0.23.1",
3
+ "version": "0.24.0",
4
4
  "description": "MCP client for szcd component library - auto-configures AI coding tools with MCP server, skills, agents and commands",
5
5
  "keywords": [
6
6
  "mcp",
package/qwen-extension/agents/szcd-component-expert.md CHANGED
@@ -75,7 +75,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
75
75
  1. **加载文件**：
76
76
  - `loadSketchByPath` 加载 .sketch 文件
77
77
  - `listPages` 列出所有页面
78
- - `listNodesByPage`（type="artboard"）获取画板列表
78
+ - `queryNodes`（pageId, type="artboard"）获取画板列表
79
79
  - 根据画板名称选择目标页面
80
80
 
81
81
  2. **获取完整节点树**：
@@ -84,7 +84,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
84
84
  - 拿到所有节点 ID 列表，为下一步分组做准备
85
85
 
86
86
  3. **按类型分组统计**：
87
- - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
87
+ - `getPageStructure`（pageId, mode="summary", groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
88
88
  - 识别组件模式：
89
89
  - `group(rectangle + text)` = 标签组件（如状态徽章）
90
90
  - `group(text + text + rectangle...)` = 表单项
@@ -110,9 +110,9 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
110
110
 
111
111
  **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
112
112
  ```
113
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
113
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
114
114
  → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
115
- → getNodesSummary(groupBy="type")
115
+ → getPageStructure(pageId, mode="summary", groupBy="type")
116
116
  → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 步骤 2.5 结束
117
117
  → [进入主流程步骤 3.5 统一推理]
118
118
  ```
@@ -123,7 +123,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
123
123
  |------|------------|---------|
124
124
  | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
125
125
  | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
126
- | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
126
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getPageStructure(pageId, mode="summary", groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
127
127
  | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
128
128
 
129
129
  **实战经验沉淀（重要，4 条核心收获）**：
@@ -161,15 +161,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
161
161
  - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
162
162
 
163
163
  **提示**：
164
- - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
165
- - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
166
- - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
164
+ - 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
165
+ - `getPageStructure(pageId, mode="summary")` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
166
+ - 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部自动分批），无需手动拆分
167
167
  - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
168
168
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
169
169
 
170
170
  **提示**：
171
171
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
172
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
172
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
173
173
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
174
174
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
175
175
 
package/qwen-extension/qwen-extension.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "szcd-component-helper",
3
- "version": "0.23.1",
3
+ "version": "0.24.0",
4
4
  "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
5
5
  "mcpServers": {
6
6
  "szcd-component-helper": {
package/qwen-extension/skills/szcd-component-helper/SKILL.md CHANGED
@@ -81,14 +81,14 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
81
81
  ### 步骤3.5：Sketch 文件解析（如有 .sketch 设计稿）
82
82
  - **当用户提供 .sketch 文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`
83
83
  - 工作流（4步直传）：
84
- 1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `listNodesByPage(type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
84
+ 1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `queryNodes(pageId, type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
85
85
  2. **获取组件库架构**（复用步骤1结果）：`get_architecture_overview` 的 `templatePatterns` 提供模板组合模式，`llmMappingHints` 提供常见错误修正
86
86
  3. **LLM 推理组件范围**：从 Sketch 结构化数据推断画板名称→`pageName`、区域分布→`layoutType`、图层类型→组件映射，对照 `templatePatterns` 选择最匹配的模板，输出组件候选列表
87
87
  4. **批量获取组件详情**：调用 `get_component_full_profile(name="Query,TableOrList,LeftTree,TemplateMode", depth="deep")` 一次性获取所有需要的组件 API
88
88
 
89
89
  **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
90
90
  ```
91
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
91
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
92
92
  → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
93
93
  → get_component_full_profile(批量) → 编码
94
94
  ```
@@ -107,7 +107,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
107
107
 
108
108
  **提示**：
109
109
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
110
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
110
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
111
111
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
112
112
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
113
113
 
@@ -124,7 +124,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
124
124
  - 若用户表示不准确或不采纳，收集原因
125
125
  - 调用 `submit_feedback` 将反馈提交到服务器
126
126
 
127
- ## 可用工具（13 + 17 Sketch）
127
+ ## 可用工具（13 + 15 Sketch）
128
128
 
129
129
  ### Sketch 文件解析工具（sketch-mcp-server，独立 MCP Server）
130
130
 
@@ -152,26 +152,28 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
152
152
  - `nodeId` (string, required): 节点 ID（artboard 级别效果最佳）
153
153
  - `format` (enum, optional, default: "svg"): 输出格式，当前仅支持 svg
154
154
 
155
- #### S5. getNodesSummary
155
+ #### S5. getPageStructure (mode="summary")
156
156
  **功能**：获取节点统计摘要，Token 消耗比完整信息减少 80-90%。
157
157
  **参数**：
158
- - `pageId` (string, optional): 页面 ID
158
+ - `pageId` (string, required): 页面 ID
159
+ - `mode` (string, required): "summary"
159
160
  - `groupBy` (enum, optional): type/style/position/size
160
- - `includeStats` (boolean, optional, default: true)
161
+ - `maxSamples` (number, optional, default: 5)
161
162
 
162
- #### S6. findNodesByName
163
+ #### S6. queryNodes (name 参数)
163
164
  **功能**：按名称搜索节点，支持模糊匹配。
164
165
  **参数**：
165
166
  - `name` (string, required): 搜索关键词
166
- - `limit` (number, optional, default: 10): 最大返回数量
167
+ - `limit` (number, optional, default: 50): 最大返回数量
167
168
 
168
- #### S7-S17. 其他 Sketch 工具
169
- - `listNodes` / `listNodesByPage` — 列出节点（含过滤）
169
+ #### S7-S15. 其他 Sketch 工具
170
+ - `queryNodes` — 统一节点查询（支持 pageId/type/name/nameContains/limit/offset）
170
171
  - `getNodeInfo` / `getMultipleNodeInfo` — 获取节点详情
171
- - `getNodePosition` — 获取节点位置
172
172
  - `getDocumentStructure` — 获取文档结构（支持字段过滤和摘要模式）
173
- - `getSymbolMasters` / `getSymbolInstances` — Symbol 组件管理
173
+ - `getSymbols` — Symbol 组件查询（type="master" 或 "instance"）
174
174
  - `getSymbolMasterBySymbolID` / `getSymbolInstanceStyles` — Symbol 详情
175
+ - `getShapePathData` — 提取 shapePath SVG 路径数据
176
+ - `extractBitmaps` / `matchIconFromName` — 资源提取与图标匹配
175
177
 
176
178
  ### 复合组件工具
177
179
 
package/qwen-extension/skills/szcd-design-to-code/SKILL.md CHANGED
@@ -55,42 +55,80 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
55
55
 
56
56
  ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
57
57
 
58
- **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
58
+ **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。`getMultipleNodeInfo` 支持任意数量 ID（内部自动分片），比逐个 `getNodeInfo` 快 10 倍以上。
59
59
 
60
- **工具调用顺序（深度探查，像素级还原）**：
60
+ **工具调用顺序（优化后，4 次主调用）**：
61
61
 
62
- 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
62
+ 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件（内部自动解压并保存目录，供后续 extractBitmaps 使用）
63
63
  2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
64
- 3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
65
- 4. `mcp__sketch-mcp-server__getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
66
- 5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
67
- - `group(rectangle + text)` = 标签组件
68
- - `group(text + text + rectangle...)` = 表单项
69
- - 统计各类型数量，决定下一批查询范围
70
- 6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
64
+ 3. `mcp__sketch-mcp-server__queryNodes`（pageId, type="artboard"）— 获取画板列表，确定目标画板
65
+ 4. `mcp__sketch-mcp-server__getPageStructure`（pageId, mode="ids"）**替代旧的 getPageStructure + getNodesSummary 组合**
66
+ - 一次返回按类型分组的全量 ID：`{ text: [...], rectangle: [...], bitmap: [...], shapePath: [...] }`
67
+ - 可选 `typeFilter` 参数限制返回类型
68
+ - 同时返回 `summary`（各类型统计）和 `totalIds`（总数）
69
+ 5. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[所有 text + rectangle ID]）— **支持任意数量 ID，内部自动分批处理**
71
70
  - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
72
- - 不要逐个 `getNodeInfo`，太慢且容易漏
71
+ - 无需手动分批，传入全部 ID 即可（内部按 100 个一批自动处理）
73
72
 
74
- **⚠️ 与旧策略的差异**：
75
- - 旧策略：maxDepth=2 拿布局，样式靠组件默认
76
- - 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
77
- - 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
78
- - 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
73
+ **与旧策略的差异**：
74
+ - 旧策略：`getPageStructure`(可能截断) + `getNodesSummary` + 手动分批 `getMultipleNodeInfo`
75
+ - 新策略：`getPageStructure(mode="ids")`(轻量全量 ID) + `getMultipleNodeInfo`(自动分片)
76
+ - 调用次数：旧 6 次 → 新 4 次（含 loadSketch + listPages 合并）
79
77
 
80
78
  **步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
81
- - Sketch 节点结构 + 全量节点 ID 列表
79
+ - 按类型分组的全量节点 ID 列表
82
80
  - text/rectangle 节点的完整样式 Token
83
- - 图表区结构规律识别结果
81
+ - bitmap ID 列表（传给步骤 2.5.1）
82
+ - shapePath 节点名列表（传给步骤 2.5.1）
84
83
 
85
84
  组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程中结合步骤 1 的 `templatePatterns` 推理**（详见主流程步骤 4 前置说明）。
86
85
 
86
+ ### 步骤2.5.1：图标与位图提取（有 bitmap/shapePath 节点时执行）
87
+
88
+ **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
89
+
90
+ **工具调用**：
91
+
92
+ 1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
93
+ - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
94
+ - 位图资源用于 CSS `background-image` 引用
95
+ 2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库
96
+ - 输入 shapePath 节点名列表（如 `["表 icon", "文件 icon"]`）
97
+ - 匹配策略：节点名关键词 → 拼音匹配图标列表
98
+ - 返回格式：
99
+ ```json
100
+ {
101
+ "matchedIcons": [
102
+ { "nodeName": "表 icon", "iconType": "icon-biao", "library": "newFont" }
103
+ ],
104
+ "unmatched": ["菜单icon"],
105
+ "recommendFallback": { "菜单icon": "antd MenuOutlined" },
106
+ "matchRate": "80.0%"
107
+ }
108
+ ```
109
+
110
+ **步骤 2.5.1 产出物**：
111
+ - bitmap base64 资源列表 → 用于代码中的 CSS background-image
112
+ - IconfontWapper 代码片段（`<IconfontWapper assets="newFont" type="icon-biao" />`）
113
+ - 未匹配节点的 fallback 建议（antd 图标替代）
114
+
115
+ ### 步骤2.5.2：批量样式提取（合并入步骤 2.5）
116
+
117
+ 此步骤已合并入步骤 2.5 第 5 步，`getMultipleNodeInfo` 现在支持自动分片，无需手动分批调用。
118
+
87
119
  ### 步骤2.5 实战经验沉淀（重要）
88
120
 
89
- **经验1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
90
- - 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
91
- - 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
121
+ **经验1：用 `getPageStructure(mode="ids")` 一步拿全量 ID，避免 getPageStructure 截断**
122
+ - 错误做法：用 `getPageStructure(pageId)` 拿节点树 → 大文件截断 → 需要 agent 解析
123
+ - 正确做法：`getPageStructure(pageId, mode="ids")` 轻量返回 `{ text: [ids], rectangle: [ids], bitmap: [ids] }` → 无截断风险
124
+ - 如需节点层级关系，用 `getPageStructure(pageId, fields=["id","name","type"])` 过滤字段
125
+
126
+ **经验2：`getMultipleNodeInfo` 支持任意数量，无需手动分批**
127
+ - 旧做法：手动把 ID 分成每批 ≤ 100 个 → 多次调用
128
+ - 新做法：直接传入全部 ID（如 200 个）→ 内部自动按 100 个一批处理 → 返回合并结果
129
+ - 返回结构不变：`{ nodes: [...], total, requested, batches }`
92
130
 
93
- **经验2：text 节点是颜色/DOM 映射的两级索引**
131
+ **经验3：text 节点是颜色/DOM 映射的两级索引**
94
132
  每个 text 节点同时关联两种上下文，**必须同批拉取**：
95
133
  - 自身样式：`fontSize`、`fontWeight`、`text.color`
96
134
  - 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
@@ -98,7 +136,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
98
136
  错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
99
137
  正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
100
138
 
101
- **经验3：图表区样式提取有规律可循**
139
+ **经验4：图表区样式提取有规律可循**
102
140
 
103
141
  | 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
104
142
  |---|---|---|
@@ -113,10 +151,11 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
113
151
 
114
152
  识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
115
153
 
116
- **经验4：矢量图形是工具链盲区（兜底方案）**
117
- - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%（实战中 434/926），但 `renderNodeAsBase64` 不支持渲染
118
- - 解压 `.sketch`（zip 格式）只能提取 `bitmap` 中内嵌的 PNG/PDF（实战中可能仅 2 张，常是侧边栏 Logo）
119
- - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
154
+ **经验5：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
155
+ - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
156
+ - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
157
+ - bitmap 用 `extractBitmaps(bitmapIds)` 自动提取 PNG 资源
158
+ - 兜底：未匹配的节点用 antd `@ant-design/icons` 同语义图标替代，在代码注释中标注“⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath”
120
159
 
121
160
  ### 步骤3：分析设计稿图片（有图片时执行）
122
161
 
package/standard-skill/szcd-component-helper/SKILL.md CHANGED
@@ -81,14 +81,14 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
81
81
  ### 步骤3.5：Sketch 文件解析（如有 .sketch 设计稿）
82
82
  - **当用户提供 .sketch 文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`
83
83
  - 工作流（4步直传）：
84
- 1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `listNodesByPage(type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
84
+ 1. **解析 Sketch 结构**：`loadSketchByPath` → `listPages` → `queryNodes(pageId, type="artboard")` → `getNodeInfo`/`getPageStructure(maxDepth=2)` 提取结构
85
85
  2. **获取组件库架构**（复用步骤1结果）：`get_architecture_overview` 的 `templatePatterns` 提供模板组合模式，`llmMappingHints` 提供常见错误修正
86
86
  3. **LLM 推理组件范围**：从 Sketch 结构化数据推断画板名称→`pageName`、区域分布→`layoutType`、图层类型→组件映射，对照 `templatePatterns` 选择最匹配的模板，输出组件候选列表
87
87
  4. **批量获取组件详情**：调用 `get_component_full_profile(name="Query,TableOrList,LeftTree,TemplateMode", depth="deep")` 一次性获取所有需要的组件 API
88
88
 
89
89
  **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
90
90
  ```
91
- .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
91
+ .sketch → loadSketchByPath → listPages → queryNodes(pageId, type=artboard)
92
92
  → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
93
93
  → get_component_full_profile(批量) → 编码
94
94
  ```
@@ -107,7 +107,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
107
107
 
108
108
  **提示**：
109
109
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
110
- - `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
110
+ - `queryNodes(pageId, type="artboard")` 优先于 `getPageStructure`，更轻量
111
111
  - 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
112
112
  - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
113
113
 
@@ -124,7 +124,7 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
124
124
  - 若用户表示不准确或不采纳，收集原因
125
125
  - 调用 `submit_feedback` 将反馈提交到服务器
126
126
 
127
- ## 可用工具（13 + 17 Sketch）
127
+ ## 可用工具（13 + 15 Sketch）
128
128
 
129
129
  ### Sketch 文件解析工具（sketch-mcp-server，独立 MCP Server）
130
130
 
@@ -152,26 +152,28 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
152
152
  - `nodeId` (string, required): 节点 ID（artboard 级别效果最佳）
153
153
  - `format` (enum, optional, default: "svg"): 输出格式，当前仅支持 svg
154
154
 
155
- #### S5. getNodesSummary
155
+ #### S5. getPageStructure (mode="summary")
156
156
  **功能**：获取节点统计摘要，Token 消耗比完整信息减少 80-90%。
157
157
  **参数**：
158
- - `pageId` (string, optional): 页面 ID
158
+ - `pageId` (string, required): 页面 ID
159
+ - `mode` (string, required): "summary"
159
160
  - `groupBy` (enum, optional): type/style/position/size
160
- - `includeStats` (boolean, optional, default: true)
161
+ - `maxSamples` (number, optional, default: 5)
161
162
 
162
- #### S6. findNodesByName
163
+ #### S6. queryNodes (name 参数)
163
164
  **功能**：按名称搜索节点，支持模糊匹配。
164
165
  **参数**：
165
166
  - `name` (string, required): 搜索关键词
166
- - `limit` (number, optional, default: 10): 最大返回数量
167
+ - `limit` (number, optional, default: 50): 最大返回数量
167
168
 
168
- #### S7-S17. 其他 Sketch 工具
169
- - `listNodes` / `listNodesByPage` — 列出节点（含过滤）
169
+ #### S7-S15. 其他 Sketch 工具
170
+ - `queryNodes` — 统一节点查询（支持 pageId/type/name/nameContains/limit/offset）
170
171
  - `getNodeInfo` / `getMultipleNodeInfo` — 获取节点详情
171
- - `getNodePosition` — 获取节点位置
172
172
  - `getDocumentStructure` — 获取文档结构（支持字段过滤和摘要模式）
173
- - `getSymbolMasters` / `getSymbolInstances` — Symbol 组件管理
173
+ - `getSymbols` — Symbol 组件查询（type="master" 或 "instance"）
174
174
  - `getSymbolMasterBySymbolID` / `getSymbolInstanceStyles` — Symbol 详情
175
+ - `getShapePathData` — 提取 shapePath SVG 路径数据
176
+ - `extractBitmaps` / `matchIconFromName` — 资源提取与图标匹配
175
177
 
176
178
  ### 复合组件工具
177
179
 
package/standard-skill/szcd-design-to-code/SKILL.md CHANGED
@@ -55,42 +55,80 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
55
55
 
56
56
  ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
57
57
 
58
- **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
58
+ **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。`getMultipleNodeInfo` 支持任意数量 ID（内部自动分片），比逐个 `getNodeInfo` 快 10 倍以上。
59
59
 
60
- **工具调用顺序（深度探查，像素级还原）**：
60
+ **工具调用顺序（优化后，4 次主调用）**：
61
61
 
62
- 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
62
+ 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件（内部自动解压并保存目录，供后续 extractBitmaps 使用）
63
63
  2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
64
- 3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
65
- 4. `mcp__sketch-mcp-server__getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
66
- 5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
67
- - `group(rectangle + text)` = 标签组件
68
- - `group(text + text + rectangle...)` = 表单项
69
- - 统计各类型数量，决定下一批查询范围
70
- 6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
64
+ 3. `mcp__sketch-mcp-server__queryNodes`（pageId, type="artboard"）— 获取画板列表，确定目标画板
65
+ 4. `mcp__sketch-mcp-server__getPageStructure`（pageId, mode="ids"）**替代旧的 getPageStructure + getNodesSummary 组合**
66
+ - 一次返回按类型分组的全量 ID：`{ text: [...], rectangle: [...], bitmap: [...], shapePath: [...] }`
67
+ - 可选 `typeFilter` 参数限制返回类型
68
+ - 同时返回 `summary`（各类型统计）和 `totalIds`（总数）
69
+ 5. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[所有 text + rectangle ID]）— **支持任意数量 ID，内部自动分批处理**
71
70
  - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
72
- - 不要逐个 `getNodeInfo`，太慢且容易漏
71
+ - 无需手动分批，传入全部 ID 即可（内部按 100 个一批自动处理）
73
72
 
74
- **⚠️ 与旧策略的差异**：
75
- - 旧策略：maxDepth=2 拿布局，样式靠组件默认
76
- - 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
77
- - 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
78
- - 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
73
+ **与旧策略的差异**：
74
+ - 旧策略：`getPageStructure`(可能截断) + `getNodesSummary` + 手动分批 `getMultipleNodeInfo`
75
+ - 新策略：`getPageStructure(mode="ids")`(轻量全量 ID) + `getMultipleNodeInfo`(自动分片)
76
+ - 调用次数：旧 6 次 → 新 4 次（含 loadSketch + listPages 合并）
79
77
 
80
78
  **步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
81
- - Sketch 节点结构 + 全量节点 ID 列表
79
+ - 按类型分组的全量节点 ID 列表
82
80
  - text/rectangle 节点的完整样式 Token
83
- - 图表区结构规律识别结果
81
+ - bitmap ID 列表（传给步骤 2.5.1）
82
+ - shapePath 节点名列表（传给步骤 2.5.1）
84
83
 
85
84
  组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程中结合步骤 1 的 `templatePatterns` 推理**（详见主流程步骤 4 前置说明）。
86
85
 
86
+ ### 步骤2.5.1：图标与位图提取（有 bitmap/shapePath 节点时执行）
87
+
88
+ **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
89
+
90
+ **工具调用**：
91
+
92
+ 1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
93
+ - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
94
+ - 位图资源用于 CSS `background-image` 引用
95
+ 2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库
96
+ - 输入 shapePath 节点名列表（如 `["表 icon", "文件 icon"]`）
97
+ - 匹配策略：节点名关键词 → 拼音匹配图标列表
98
+ - 返回格式：
99
+ ```json
100
+ {
101
+ "matchedIcons": [
102
+ { "nodeName": "表 icon", "iconType": "icon-biao", "library": "newFont" }
103
+ ],
104
+ "unmatched": ["菜单icon"],
105
+ "recommendFallback": { "菜单icon": "antd MenuOutlined" },
106
+ "matchRate": "80.0%"
107
+ }
108
+ ```
109
+
110
+ **步骤 2.5.1 产出物**：
111
+ - bitmap base64 资源列表 → 用于代码中的 CSS background-image
112
+ - IconfontWapper 代码片段（`<IconfontWapper assets="newFont" type="icon-biao" />`）
113
+ - 未匹配节点的 fallback 建议（antd 图标替代）
114
+
115
+ ### 步骤2.5.2：批量样式提取（合并入步骤 2.5）
116
+
117
+ 此步骤已合并入步骤 2.5 第 5 步，`getMultipleNodeInfo` 现在支持自动分片，无需手动分批调用。
118
+
87
119
  ### 步骤2.5 实战经验沉淀（重要）
88
120
 
89
- **经验1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
90
- - 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
91
- - 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
121
+ **经验1：用 `getPageStructure(mode="ids")` 一步拿全量 ID，避免 getPageStructure 截断**
122
+ - 错误做法：用 `getPageStructure(pageId)` 拿节点树 → 大文件截断 → 需要 agent 解析
123
+ - 正确做法：`getPageStructure(pageId, mode="ids")` 轻量返回 `{ text: [ids], rectangle: [ids], bitmap: [ids] }` → 无截断风险
124
+ - 如需节点层级关系，用 `getPageStructure(pageId, fields=["id","name","type"])` 过滤字段
125
+
126
+ **经验2：`getMultipleNodeInfo` 支持任意数量，无需手动分批**
127
+ - 旧做法：手动把 ID 分成每批 ≤ 100 个 → 多次调用
128
+ - 新做法：直接传入全部 ID（如 200 个）→ 内部自动按 100 个一批处理 → 返回合并结果
129
+ - 返回结构不变：`{ nodes: [...], total, requested, batches }`
92
130
 
93
- **经验2：text 节点是颜色/DOM 映射的两级索引**
131
+ **经验3：text 节点是颜色/DOM 映射的两级索引**
94
132
  每个 text 节点同时关联两种上下文，**必须同批拉取**：
95
133
  - 自身样式：`fontSize`、`fontWeight`、`text.color`
96
134
  - 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
@@ -98,7 +136,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
98
136
  错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
99
137
  正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
100
138
 
101
- **经验3：图表区样式提取有规律可循**
139
+ **经验4：图表区样式提取有规律可循**
102
140
 
103
141
  | 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
104
142
  |---|---|---|
@@ -113,10 +151,11 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
113
151
 
114
152
  识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
115
153
 
116
- **经验4：矢量图形是工具链盲区（兜底方案）**
117
- - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%（实战中 434/926），但 `renderNodeAsBase64` 不支持渲染
118
- - 解压 `.sketch`（zip 格式）只能提取 `bitmap` 中内嵌的 PNG/PDF（实战中可能仅 2 张，常是侧边栏 Logo）
119
- - **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
154
+ **经验5：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
155
+ - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
156
+ - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
157
+ - bitmap 用 `extractBitmaps(bitmapIds)` 自动提取 PNG 资源
158
+ - 兜底：未匹配的节点用 antd `@ant-design/icons` 同语义图标替代，在代码注释中标注“⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath”
120
159
 
121
160
  ### 步骤3：分析设计稿图片（有图片时执行）
122
161