@szc-ft/mcp-szcd-client 0.22.0 → 0.23.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 (13) hide show
  1. package/agents/opencode-extension/agents/szcd-component-expert.md +53 -11
  2. package/agents/qwen-extension/agents/szcd-component-expert.md +53 -11
  3. package/agents/src/szcd-component-expert.md +53 -11
  4. package/agents/szcd-component-expert.md +53 -11
  5. package/agents/szcd-component-expert.qoder.md +53 -11
  6. package/agents/szcd-component-expert.trae.md +53 -11
  7. package/opencode-extension/agents/szcd-component-expert.md +53 -11
  8. package/opencode-extension/skills/szcd-design-to-code/SKILL.md +17 -8
  9. package/package.json +1 -1
  10. package/qwen-extension/agents/szcd-component-expert.md +53 -11
  11. package/qwen-extension/qwen-extension.json +1 -1
  12. package/qwen-extension/skills/szcd-design-to-code/SKILL.md +17 -8
  13. package/standard-skill/szcd-design-to-code/SKILL.md +17 -8
package/agents/opencode-extension/agents/szcd-component-expert.md CHANGED
@@ -72,34 +72,76 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
72
72
 
73
73
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
74
74
 
75
- **工作流（4步直传）**：
75
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
76
76
 
77
- 1. **解析 Sketch 结构**：
77
+ **工作流（6步深度探查，像素级还原）**：
78
+
79
+ 1. **加载文件**：
78
80
  - `loadSketchByPath` 加载 .sketch 文件
79
81
  - `listPages` 列出所有页面
80
82
  - `listNodesByPage`（type="artboard"）获取画板列表
81
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
82
-
83
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
83
+ - 根据画板名称选择目标页面
84
+
85
+ 2. **获取完整节点树**：
86
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
87
+ - 必须 `includeDetails=true`，否则拿不到初始样式
88
+ - 拿到所有节点 ID 列表，为下一步分组做准备
89
+
90
+ 3. **按类型分组统计**：
91
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
92
+ - 识别组件模式：
93
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
94
+ - `group(text + text + rectangle...)` = 表单项
95
+ - `group(text 列表 + 边框)` = 表格行
96
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
97
+
98
+ 4. **批量拉取样式 Token**：
99
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
100
+ - 关键字段提取：
101
+ - 背景色：`style.fills[0].color.hex`
102
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
103
+ - 字号：`style.fontSize`
104
+ - 字重：`style.fontWeight`
105
+ - 边框：`style.borders[0].color.hex` + `thickness`
106
+ - **禁止**逐个 `getNodeInfo` 探查
107
+
108
+ 5. **获取组件库架构**（复用步骤1结果）：
84
109
  - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
85
110
  - `llmMappingHints` 提供常见错误修正
86
111
 
87
- 3. **LLM 推理组件范围**：
88
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
112
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
113
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
89
114
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
90
115
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
91
-
92
- 4. **批量获取组件详情**：
93
116
  - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
94
117
  - 如需样式注入细节，追加 `get_style_injection_guide`
95
118
 
96
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
119
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
97
120
  ```
98
121
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
99
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
122
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
123
+ → getNodesSummary(groupBy="type")
124
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
125
+ → [步骤1架构数据] → LLM推理组件
100
126
  → get_component_full_profile(批量) → 编码
101
127
  ```
102
128
 
129
+ **首轮常见错误 → 正确做法对照表**：
130
+
131
+ | 步骤 | 第一次做错的 | 应该做的 |
132
+ |------|------------|---------|
133
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
134
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
135
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
136
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
137
+
138
+ **提示**：
139
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
140
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
141
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
142
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
143
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
144
+
103
145
  **Sketch 结构 → 组件映射规则**：
104
146
 
105
147
  *页面级布局*：
package/agents/qwen-extension/agents/szcd-component-expert.md CHANGED
@@ -68,34 +68,76 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
68
68
 
69
69
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
70
70
 
71
- **工作流（4步直传）**：
71
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
72
72
 
73
- 1. **解析 Sketch 结构**：
73
+ **工作流（6步深度探查，像素级还原）**：
74
+
75
+ 1. **加载文件**：
74
76
  - `loadSketchByPath` 加载 .sketch 文件
75
77
  - `listPages` 列出所有页面
76
78
  - `listNodesByPage`（type="artboard"）获取画板列表
77
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
78
-
79
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
79
+ - 根据画板名称选择目标页面
80
+
81
+ 2. **获取完整节点树**：
82
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
83
+ - 必须 `includeDetails=true`，否则拿不到初始样式
84
+ - 拿到所有节点 ID 列表，为下一步分组做准备
85
+
86
+ 3. **按类型分组统计**：
87
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
88
+ - 识别组件模式：
89
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
90
+ - `group(text + text + rectangle...)` = 表单项
91
+ - `group(text 列表 + 边框)` = 表格行
92
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
93
+
94
+ 4. **批量拉取样式 Token**：
95
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
96
+ - 关键字段提取：
97
+ - 背景色：`style.fills[0].color.hex`
98
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
99
+ - 字号：`style.fontSize`
100
+ - 字重：`style.fontWeight`
101
+ - 边框：`style.borders[0].color.hex` + `thickness`
102
+ - **禁止**逐个 `getNodeInfo` 探查
103
+
104
+ 5. **获取组件库架构**（复用步骤1结果）：
80
105
  - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
81
106
  - `llmMappingHints` 提供常见错误修正
82
107
 
83
- 3. **LLM 推理组件范围**：
84
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
108
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
109
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
85
110
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
86
111
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
87
-
88
- 4. **批量获取组件详情**：
89
112
  - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
90
113
  - 如需样式注入细节，追加 `get_style_injection_guide`
91
114
 
92
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
115
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
93
116
  ```
94
117
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
95
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
118
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
119
+ → getNodesSummary(groupBy="type")
120
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
121
+ → [步骤1架构数据] → LLM推理组件
96
122
  → get_component_full_profile(批量) → 编码
97
123
  ```
98
124
 
125
+ **首轮常见错误 → 正确做法对照表**：
126
+
127
+ | 步骤 | 第一次做错的 | 应该做的 |
128
+ |------|------------|---------|
129
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
130
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
131
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
132
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
133
+
134
+ **提示**：
135
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
136
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
137
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
138
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
139
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
140
+
99
141
  **Sketch 结构 → 组件映射规则**：
100
142
 
101
143
  *页面级布局*：
package/agents/src/szcd-component-expert.md CHANGED
@@ -143,34 +143,76 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
143
143
 
144
144
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `{{TOOL:map_design_data}}`。
145
145
 
146
- **工作流（4步直传）**：
146
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
147
147
 
148
- 1. **解析 Sketch 结构**：
148
+ **工作流（6步深度探查，像素级还原）**：
149
+
150
+ 1. **加载文件**：
149
151
  - `loadSketchByPath` 加载 .sketch 文件
150
152
  - `listPages` 列出所有页面
151
153
  - `listNodesByPage`（type="artboard"）获取画板列表
152
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
153
-
154
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
154
+ - 根据画板名称选择目标页面
155
+
156
+ 2. **获取完整节点树**：
157
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
158
+ - 必须 `includeDetails=true`，否则拿不到初始样式
159
+ - 拿到所有节点 ID 列表，为下一步分组做准备
160
+
161
+ 3. **按类型分组统计**：
162
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
163
+ - 识别组件模式：
164
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
165
+ - `group(text + text + rectangle...)` = 表单项
166
+ - `group(text 列表 + 边框)` = 表格行
167
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
168
+
169
+ 4. **批量拉取样式 Token**：
170
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
171
+ - 关键字段提取：
172
+ - 背景色：`style.fills[0].color.hex`
173
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
174
+ - 字号：`style.fontSize`
175
+ - 字重：`style.fontWeight`
176
+ - 边框：`style.borders[0].color.hex` + `thickness`
177
+ - **禁止**逐个 `getNodeInfo` 探查
178
+
179
+ 5. **获取组件库架构**（复用步骤1结果）：
155
180
  - `{{TOOL:get_architecture_overview}}` 的 `templatePatterns` 提供模板组合模式
156
181
  - `llmMappingHints` 提供常见错误修正
157
182
 
158
- 3. **LLM 推理组件范围**：
159
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
183
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
184
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
160
185
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
161
186
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
162
-
163
- 4. **批量获取组件详情**：
164
187
  - 调用 `{{TOOL:get_component_full_profile}}`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
165
188
  - 如需样式注入细节，追加 `{{TOOL:get_style_injection_guide}}`
166
189
 
167
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
190
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
168
191
  ```
169
192
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
170
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
193
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
194
+ → getNodesSummary(groupBy="type")
195
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
196
+ → [步骤1架构数据] → LLM推理组件
171
197
  → get_component_full_profile(批量) → 编码
172
198
  ```
173
199
 
200
+ **首轮常见错误 → 正确做法对照表**：
201
+
202
+ | 步骤 | 第一次做错的 | 应该做的 |
203
+ |------|------------|---------|
204
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
205
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
206
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
207
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
208
+
209
+ **提示**：
210
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
211
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
212
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
213
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
214
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
215
+
174
216
  **Sketch 结构 → 组件映射规则**：
175
217
 
176
218
  *页面级布局*：
package/agents/szcd-component-expert.md CHANGED
@@ -72,34 +72,76 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
72
72
 
73
73
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
74
74
 
75
- **工作流（4步直传）**：
75
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
76
76
 
77
- 1. **解析 Sketch 结构**：
77
+ **工作流（6步深度探查，像素级还原）**：
78
+
79
+ 1. **加载文件**：
78
80
  - `loadSketchByPath` 加载 .sketch 文件
79
81
  - `listPages` 列出所有页面
80
82
  - `listNodesByPage`（type="artboard"）获取画板列表
81
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
82
-
83
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
83
+ - 根据画板名称选择目标页面
84
+
85
+ 2. **获取完整节点树**：
86
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
87
+ - 必须 `includeDetails=true`，否则拿不到初始样式
88
+ - 拿到所有节点 ID 列表，为下一步分组做准备
89
+
90
+ 3. **按类型分组统计**：
91
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
92
+ - 识别组件模式：
93
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
94
+ - `group(text + text + rectangle...)` = 表单项
95
+ - `group(text 列表 + 边框)` = 表格行
96
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
97
+
98
+ 4. **批量拉取样式 Token**：
99
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
100
+ - 关键字段提取：
101
+ - 背景色：`style.fills[0].color.hex`
102
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
103
+ - 字号：`style.fontSize`
104
+ - 字重：`style.fontWeight`
105
+ - 边框：`style.borders[0].color.hex` + `thickness`
106
+ - **禁止**逐个 `getNodeInfo` 探查
107
+
108
+ 5. **获取组件库架构**（复用步骤1结果）：
84
109
  - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
85
110
  - `llmMappingHints` 提供常见错误修正
86
111
 
87
- 3. **LLM 推理组件范围**：
88
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
112
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
113
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
89
114
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
90
115
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
91
-
92
- 4. **批量获取组件详情**：
93
116
  - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
94
117
  - 如需样式注入细节，追加 `get_style_injection_guide`
95
118
 
96
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
119
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
97
120
  ```
98
121
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
99
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
122
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
123
+ → getNodesSummary(groupBy="type")
124
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
125
+ → [步骤1架构数据] → LLM推理组件
100
126
  → get_component_full_profile(批量) → 编码
101
127
  ```
102
128
 
129
+ **首轮常见错误 → 正确做法对照表**：
130
+
131
+ | 步骤 | 第一次做错的 | 应该做的 |
132
+ |------|------------|---------|
133
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
134
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
135
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
136
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
137
+
138
+ **提示**：
139
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
140
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
141
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
142
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
143
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
144
+
103
145
  **Sketch 结构 → 组件映射规则**：
104
146
 
105
147
  *页面级布局*：
package/agents/szcd-component-expert.qoder.md CHANGED
@@ -122,34 +122,76 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
122
122
 
123
123
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
124
124
 
125
- **工作流（4步直传）**：
125
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
126
126
 
127
- 1. **解析 Sketch 结构**：
127
+ **工作流（6步深度探查，像素级还原）**：
128
+
129
+ 1. **加载文件**：
128
130
  - `loadSketchByPath` 加载 .sketch 文件
129
131
  - `listPages` 列出所有页面
130
132
  - `listNodesByPage`（type="artboard"）获取画板列表
131
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
132
-
133
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
133
+ - 根据画板名称选择目标页面
134
+
135
+ 2. **获取完整节点树**：
136
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
137
+ - 必须 `includeDetails=true`，否则拿不到初始样式
138
+ - 拿到所有节点 ID 列表，为下一步分组做准备
139
+
140
+ 3. **按类型分组统计**：
141
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
142
+ - 识别组件模式：
143
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
144
+ - `group(text + text + rectangle...)` = 表单项
145
+ - `group(text 列表 + 边框)` = 表格行
146
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
147
+
148
+ 4. **批量拉取样式 Token**：
149
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
150
+ - 关键字段提取：
151
+ - 背景色：`style.fills[0].color.hex`
152
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
153
+ - 字号：`style.fontSize`
154
+ - 字重：`style.fontWeight`
155
+ - 边框：`style.borders[0].color.hex` + `thickness`
156
+ - **禁止**逐个 `getNodeInfo` 探查
157
+
158
+ 5. **获取组件库架构**（复用步骤1结果）：
134
159
  - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
135
160
  - `llmMappingHints` 提供常见错误修正
136
161
 
137
- 3. **LLM 推理组件范围**：
138
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
162
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
163
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
139
164
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
140
165
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
141
-
142
- 4. **批量获取组件详情**：
143
166
  - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
144
167
  - 如需样式注入细节，追加 `get_style_injection_guide`
145
168
 
146
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
169
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
147
170
  ```
148
171
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
149
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
172
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
173
+ → getNodesSummary(groupBy="type")
174
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
175
+ → [步骤1架构数据] → LLM推理组件
150
176
  → get_component_full_profile(批量) → 编码
151
177
  ```
152
178
 
179
+ **首轮常见错误 → 正确做法对照表**：
180
+
181
+ | 步骤 | 第一次做错的 | 应该做的 |
182
+ |------|------------|---------|
183
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
184
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
185
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
186
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
187
+
188
+ **提示**：
189
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
190
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
191
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
192
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
193
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
194
+
153
195
  **Sketch 结构 → 组件映射规则**：
154
196
 
155
197
  *页面级布局*：
package/agents/szcd-component-expert.trae.md CHANGED
@@ -86,34 +86,76 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
86
86
 
87
87
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `mcp__szcd-component-helper__map_design_data`。
88
88
 
89
- **工作流（4步直传）**：
89
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
90
90
 
91
- 1. **解析 Sketch 结构**：
91
+ **工作流（6步深度探查，像素级还原）**：
92
+
93
+ 1. **加载文件**：
92
94
  - `loadSketchByPath` 加载 .sketch 文件
93
95
  - `listPages` 列出所有页面
94
96
  - `listNodesByPage`（type="artboard"）获取画板列表
95
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
96
-
97
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
97
+ - 根据画板名称选择目标页面
98
+
99
+ 2. **获取完整节点树**：
100
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
101
+ - 必须 `includeDetails=true`，否则拿不到初始样式
102
+ - 拿到所有节点 ID 列表，为下一步分组做准备
103
+
104
+ 3. **按类型分组统计**：
105
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
106
+ - 识别组件模式：
107
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
108
+ - `group(text + text + rectangle...)` = 表单项
109
+ - `group(text 列表 + 边框)` = 表格行
110
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
111
+
112
+ 4. **批量拉取样式 Token**：
113
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
114
+ - 关键字段提取：
115
+ - 背景色：`style.fills[0].color.hex`
116
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
117
+ - 字号：`style.fontSize`
118
+ - 字重：`style.fontWeight`
119
+ - 边框：`style.borders[0].color.hex` + `thickness`
120
+ - **禁止**逐个 `getNodeInfo` 探查
121
+
122
+ 5. **获取组件库架构**（复用步骤1结果）：
98
123
  - `mcp__szcd-component-helper__get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
99
124
  - `llmMappingHints` 提供常见错误修正
100
125
 
101
- 3. **LLM 推理组件范围**：
102
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
126
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
127
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
103
128
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
104
129
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
105
-
106
- 4. **批量获取组件详情**：
107
130
  - 调用 `mcp__szcd-component-helper__get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
108
131
  - 如需样式注入细节，追加 `mcp__szcd-component-helper__get_style_injection_guide`
109
132
 
110
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
133
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
111
134
  ```
112
135
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
113
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
136
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
137
+ → getNodesSummary(groupBy="type")
138
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
139
+ → [步骤1架构数据] → LLM推理组件
114
140
  → get_component_full_profile(批量) → 编码
115
141
  ```
116
142
 
143
+ **首轮常见错误 → 正确做法对照表**：
144
+
145
+ | 步骤 | 第一次做错的 | 应该做的 |
146
+ |------|------------|---------|
147
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
148
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
149
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
150
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
151
+
152
+ **提示**：
153
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
154
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
155
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
156
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `mcp__szcd-component-helper__analyze_design_image`
157
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
158
+
117
159
  **Sketch 结构 → 组件映射规则**：
118
160
 
119
161
  *页面级布局*：
package/opencode-extension/agents/szcd-component-expert.md CHANGED
@@ -72,34 +72,76 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
72
72
 
73
73
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
74
74
 
75
- **工作流（4步直传）**：
75
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
76
76
 
77
- 1. **解析 Sketch 结构**：
77
+ **工作流（6步深度探查，像素级还原）**：
78
+
79
+ 1. **加载文件**：
78
80
  - `loadSketchByPath` 加载 .sketch 文件
79
81
  - `listPages` 列出所有页面
80
82
  - `listNodesByPage`（type="artboard"）获取画板列表
81
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
82
-
83
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
83
+ - 根据画板名称选择目标页面
84
+
85
+ 2. **获取完整节点树**：
86
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
87
+ - 必须 `includeDetails=true`，否则拿不到初始样式
88
+ - 拿到所有节点 ID 列表，为下一步分组做准备
89
+
90
+ 3. **按类型分组统计**：
91
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
92
+ - 识别组件模式：
93
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
94
+ - `group(text + text + rectangle...)` = 表单项
95
+ - `group(text 列表 + 边框)` = 表格行
96
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
97
+
98
+ 4. **批量拉取样式 Token**：
99
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
100
+ - 关键字段提取：
101
+ - 背景色：`style.fills[0].color.hex`
102
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
103
+ - 字号：`style.fontSize`
104
+ - 字重：`style.fontWeight`
105
+ - 边框：`style.borders[0].color.hex` + `thickness`
106
+ - **禁止**逐个 `getNodeInfo` 探查
107
+
108
+ 5. **获取组件库架构**（复用步骤1结果）：
84
109
  - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
85
110
  - `llmMappingHints` 提供常见错误修正
86
111
 
87
- 3. **LLM 推理组件范围**：
88
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
112
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
113
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
89
114
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
90
115
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
91
-
92
- 4. **批量获取组件详情**：
93
116
  - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
94
117
  - 如需样式注入细节，追加 `get_style_injection_guide`
95
118
 
96
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
119
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
97
120
  ```
98
121
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
99
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
122
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
123
+ → getNodesSummary(groupBy="type")
124
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
125
+ → [步骤1架构数据] → LLM推理组件
100
126
  → get_component_full_profile(批量) → 编码
101
127
  ```
102
128
 
129
+ **首轮常见错误 → 正确做法对照表**：
130
+
131
+ | 步骤 | 第一次做错的 | 应该做的 |
132
+ |------|------------|---------|
133
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
134
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
135
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
136
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
137
+
138
+ **提示**：
139
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
140
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
141
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
142
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
143
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
144
+
103
145
  **Sketch 结构 → 组件映射规则**：
104
146
 
105
147
  *页面级布局*：
package/opencode-extension/skills/szcd-design-to-code/SKILL.md CHANGED
@@ -55,18 +55,27 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
55
55
 
56
56
  ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
57
57
 
58
- **工具调用顺序（轻量优先，避免 token 膨胀）**：
58
+ **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
59
+
60
+ **工具调用顺序（深度探查，像素级还原）**：
59
61
 
60
62
  1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
61
63
  2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
62
64
  3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
63
- 4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
64
-
65
- ⚠️ **严格限制**：
66
- - `getPageStructure` maxDepth 不超过 2，足以判断布局
67
- - **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
68
- - 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
69
- - 结构数据拿到后立即进入 LLM 推理，不再继续探查
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 个
71
+ - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
72
+ - 不要逐个 `getNodeInfo`，太慢且容易漏
73
+
74
+ **⚠️ 与旧策略的差异**：
75
+ - 旧策略：maxDepth=2 拿布局，样式靠组件默认
76
+ - 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
77
+ - 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
78
+ - 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
70
79
 
71
80
  **Sketch 结构 → 组件映射规则**：
72
81
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@szc-ft/mcp-szcd-client",
3
- "version": "0.22.0",
3
+ "version": "0.23.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
@@ -68,34 +68,76 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
68
68
 
69
69
  **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
70
70
 
71
- **工作流（4步直传）**：
71
+ **核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
72
72
 
73
- 1. **解析 Sketch 结构**：
73
+ **工作流（6步深度探查，像素级还原）**：
74
+
75
+ 1. **加载文件**：
74
76
  - `loadSketchByPath` 加载 .sketch 文件
75
77
  - `listPages` 列出所有页面
76
78
  - `listNodesByPage`（type="artboard"）获取画板列表
77
- - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
78
-
79
- 2. **获取组件库架构**（已在步骤1完成，复用结果）：
79
+ - 根据画板名称选择目标页面
80
+
81
+ 2. **获取完整节点树**：
82
+ - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
83
+ - 必须 `includeDetails=true`，否则拿不到初始样式
84
+ - 拿到所有节点 ID 列表，为下一步分组做准备
85
+
86
+ 3. **按类型分组统计**：
87
+ - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
88
+ - 识别组件模式：
89
+ - `group(rectangle + text)` = 标签组件（如状态徽章）
90
+ - `group(text + text + rectangle...)` = 表单项
91
+ - `group(text 列表 + 边框)` = 表格行
92
+ - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
93
+
94
+ 4. **批量拉取样式 Token**：
95
+ - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
96
+ - 关键字段提取：
97
+ - 背景色：`style.fills[0].color.hex`
98
+ - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
99
+ - 字号：`style.fontSize`
100
+ - 字重：`style.fontWeight`
101
+ - 边框：`style.borders[0].color.hex` + `thickness`
102
+ - **禁止**逐个 `getNodeInfo` 探查
103
+
104
+ 5. **获取组件库架构**（复用步骤1结果）：
80
105
  - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
81
106
  - `llmMappingHints` 提供常见错误修正
82
107
 
83
- 3. **LLM 推理组件范围**：
84
- - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
108
+ 6. **LLM 推理组件范围 + 批量获取组件详情**：
109
+ - 从 Sketch 结构 + 样式 Token 推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型+颜色→组件映射
85
110
  - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
86
111
  - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
87
-
88
- 4. **批量获取组件详情**：
89
112
  - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
90
113
  - 如需样式注入细节，追加 `get_style_injection_guide`
91
114
 
92
- **Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
115
+ **Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
93
116
  ```
94
117
  .sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
95
- → getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
118
+ → getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
119
+ → getNodesSummary(groupBy="type")
120
+ → getMultipleNodeInfo([所有text+rectangle节点ID]) ← 关键：批量拿样式 Token
121
+ → [步骤1架构数据] → LLM推理组件
96
122
  → get_component_full_profile(批量) → 编码
97
123
  ```
98
124
 
125
+ **首轮常见错误 → 正确做法对照表**：
126
+
127
+ | 步骤 | 第一次做错的 | 应该做的 |
128
+ |------|------------|---------|
129
+ | 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
130
+ | 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
131
+ | 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
132
+ | 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
133
+
134
+ **提示**：
135
+ - 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
136
+ - `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
137
+ - 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
138
+ - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
139
+ - 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
140
+
99
141
  **Sketch 结构 → 组件映射规则**：
100
142
 
101
143
  *页面级布局*：
package/qwen-extension/qwen-extension.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "szcd-component-helper",
3
- "version": "0.22.0",
3
+ "version": "0.23.0",
4
4
  "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
5
5
  "mcpServers": {
6
6
  "szcd-component-helper": {
package/qwen-extension/skills/szcd-design-to-code/SKILL.md CHANGED
@@ -55,18 +55,27 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
55
55
 
56
56
  ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
57
57
 
58
- **工具调用顺序（轻量优先，避免 token 膨胀）**：
58
+ **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
59
+
60
+ **工具调用顺序（深度探查，像素级还原）**：
59
61
 
60
62
  1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
61
63
  2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
62
64
  3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
63
- 4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
64
-
65
- ⚠️ **严格限制**：
66
- - `getPageStructure` maxDepth 不超过 2，足以判断布局
67
- - **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
68
- - 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
69
- - 结构数据拿到后立即进入 LLM 推理，不再继续探查
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 个
71
+ - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
72
+ - 不要逐个 `getNodeInfo`，太慢且容易漏
73
+
74
+ **⚠️ 与旧策略的差异**：
75
+ - 旧策略：maxDepth=2 拿布局，样式靠组件默认
76
+ - 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
77
+ - 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
78
+ - 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
70
79
 
71
80
  **Sketch 结构 → 组件映射规则**：
72
81
 
package/standard-skill/szcd-design-to-code/SKILL.md CHANGED
@@ -55,18 +55,27 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
55
55
 
56
56
  ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
57
57
 
58
- **工具调用顺序（轻量优先，避免 token 膨胀）**：
58
+ **核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
59
+
60
+ **工具调用顺序（深度探查，像素级还原）**：
59
61
 
60
62
  1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
61
63
  2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
62
64
  3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
63
- 4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
64
-
65
- ⚠️ **严格限制**：
66
- - `getPageStructure` maxDepth 不超过 2，足以判断布局
67
- - **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
68
- - 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
69
- - 结构数据拿到后立即进入 LLM 推理，不再继续探查
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 个
71
+ - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
72
+ - 不要逐个 `getNodeInfo`，太慢且容易漏
73
+
74
+ **⚠️ 与旧策略的差异**：
75
+ - 旧策略：maxDepth=2 拿布局，样式靠组件默认
76
+ - 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
77
+ - 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
78
+ - 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
70
79
 
71
80
  **Sketch 结构 → 组件映射规则**：
72
81