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

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

@@ -55,20 +55,101 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
 
-**工具调用顺序（轻量优先，避免 token 膨胀）**：
+**核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
+
+**工具调用顺序（深度探查，像素级还原）**：
 
 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
 2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
 3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
-4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
+4. `mcp__sketch-mcp-server__getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
+5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
+   - `group(rectangle + text)` = 标签组件
+   - `group(text + text + rectangle...)` = 表单项
+   - 统计各类型数量，决定下一批查询范围
+6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
+   - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
+   - 不要逐个 `getNodeInfo`，太慢且容易漏
+
+**⚠️ 与旧策略的差异**：
+- 旧策略：maxDepth=2 拿布局，样式靠组件默认
+- 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
+- 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
+- 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
+
+**步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
+- Sketch 节点结构 + 全量节点 ID 列表
+- text/rectangle 节点的完整样式 Token
+- 图表区结构规律识别结果
+
+组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程中结合步骤 1 的 `templatePatterns` 推理**（详见主流程步骤 4 前置说明）。
+
+### 步骤2.5 实战经验沉淀（重要）
+
+**经验1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
+- 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
+- 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
+
+**经验2：text 节点是颜色/DOM 映射的两级索引**
+每个 text 节点同时关联两种上下文，**必须同批拉取**：
+- 自身样式：`fontSize`、`fontWeight`、`text.color`
+- 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
+
+错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
+正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
+
+**经验3：图表区样式提取有规律可循**
+
+| 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
+|---|---|---|
+| 图表标题 | `text`（带蓝色矩形左饰线） | 14px Semibold；矩形 4×14 #0079f7 |
+| 图例文字 | `text` | 14px |
+| 图例色块 | `rectangle` | 8×8 / 10×3 |
+| 坐标轴文字 | `text`（成组） | 12px #7b828d |
+| 柱体颜色 | 区域 `rectangle` | `style.fills[0].hex` |
+| 数据标签 | `text`（白字） | 12px #ffffff |
+
+**图表区结构规律**：`标题 text + 标题装饰 rectangle + 图例 text*N + 色块 rectangle*N + 坐标轴 text*N + 柱体 rectangle*N + 标签 text*N`
+
+识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
+
+**经验4：矢量图形是工具链盲区（兜底方案）**
+- `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%（实战中 434/926），但 `renderNodeAsBase64` 不支持渲染
+- 解压 `.sketch`（zip 格式）只能提取 `bitmap` 中内嵌的 PNG/PDF（实战中可能仅 2 张，常是侧边栏 Logo）
+- **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
+
+### 步骤3：分析设计稿图片（有图片时执行）
+
+- 主智能体已提供图片描述时，直接使用，跳过此步
+- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
+- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
+- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+
+### 步骤3.5：组件候选列表推理（统一环节，结合步骤1 + 步骤2.5/3）
+
+**这是统一推理环节**，无论设计稿来源是 .sketch 文件（步骤 2.5）还是图片（步骤 3），都需经过此环节：
+
+```
+步骤 1 templatePatterns  +  步骤 2.5/3 设计稿数据  →  组件候选列表
+(4 种模板模式 + llmMappingHints)  (结构 + 样式 Token)  (如 ["Query","TableOrList","LeftTree","TemplateMode"])
+```
+
+**输入**：
+- 步骤 1 的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
+- 步骤 2.5 的 Sketch 节点结构 + 样式 Token
+- 或步骤 3 的图片分析描述
 
-⚠️ **严格限制**：
-- `getPageStructure` maxDepth 不超过 2，足以判断布局
-- **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
-- 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
-- 结构数据拿到后立即进入 LLM 推理，不再继续探查
+**输出**：
+- **组件候选列表**（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
+- 模板类型选择（如 `TemplateMode(templateType="LeftRight")`）
 
-**Sketch 结构 → 组件映射规则**：
+**禁止**：
+- ❌ 在步骤 2.5 内部推理组件候选列表（应只产出 Sketch 数据 + 样式 Token）
+- ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
+- ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
+
+**推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
 
 | Sketch 特征 | 推断组件 |
 |---|---|
@@ -80,23 +161,23 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 弹窗/抽屉图层 | `ModelOrDrawer` |
 | 页面标题 + 返回箭头 | `TitleAndBack` |
 | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
-| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` |
+| 卡片列表 | `TableOrList(componentType="ProList")` |
 | 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
 | 折线趋势图 | `Line` |
 | 柱状对比图 | `Bar` |
 | 饼图/环形图 | `Pie` |
 
-推理出组件候选列表后，立即进入步骤4批量获取组件 API。
+**长尾场景走语义搜索**（不进文档，避免膨胀）：
+- 数据可视化长尾：`Radar` / `Gauge` / `Funnel`（用 `Line/Bar/Pie` 之外的图表）
+- 表格子类型长尾：`DragSortTable`（拖拽排序）、`steps` 步骤条表单
+- 辅助/插槽组件：`CustomOption`（LeftTree 添加按钮）、`TreeNode`（树节点右键菜单）、`ModeAvatar`（头像）、`Upload`（文件上传）
 
-### 步骤3：分析设计稿图片（有图片时执行）
-
-- 主智能体已提供图片描述时，直接使用，跳过此步
-- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
-- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
-- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+**处理方式**：本表未覆盖的视觉特征 → 调用 `{{TOOL:search_components_semantic}}`（query="[场景描述，如'拖拽排序表格']"）按需补全，再进入步骤 4。
 
 ### 步骤4：批量获取组件 API（必做）
 
+**前置条件**：已通过步骤 3.5 获得组件候选列表。
+
 调用 `mcp__szcd-component-helper__get_component_full_profile`：
 - `name` 用逗号分隔一次性查询所有候选组件，如 `"Query,TableOrList,LeftTree,TemplateMode"`
 - `depth="gencode"`（比 deep 小 30-50%，生成代码场景首选）

package/standard-skill/szcd-design-to-code/SKILL.md

@@ -55,20 +55,101 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 ### 步骤2.5：Sketch 文件解析（有 .sketch 文件时执行）
 
-**工具调用顺序（轻量优先，避免 token 膨胀）**：
+**核心原则**：写代码之前必须拿到所有 `text` 和 `rectangle` 节点的完整样式 Token，禁止凭节点名猜测颜色/字号/背景色。一次 `getMultipleNodeInfo(50-100 个节点)` 比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
+
+**工具调用顺序（深度探查，像素级还原）**：
 
 1. `mcp__sketch-mcp-server__loadSketchByPath` — 加载文件
 2. `mcp__sketch-mcp-server__listPages` — 获取页面列表
 3. `mcp__sketch-mcp-server__listNodesByPage`（type="artboard"）— 获取画板列表，确定目标画板
-4. `mcp__sketch-mcp-server__getPageStructure`（maxDepth=2）— **一次性**获取布局概况
+4. `mcp__sketch-mcp-server__getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID（含初始样式）
+5. `mcp__sketch-mcp-server__getNodesSummary`（pageId, groupBy="type"）— 按类型分组统计，识别组件模式
+   - `group(rectangle + text)` = 标签组件
+   - `group(text + text + rectangle...)` = 表单项
+   - 统计各类型数量，决定下一批查询范围
+6. `mcp__sketch-mcp-server__getMultipleNodeInfo`（[id1, id2, ...]）— **批量查询所有 type=text 和 type=rectangle 节点**，每次 ≤ 100 个
+   - 关键字段：`style.fills[0].color.hex`（背景色）、`text.color`（文字色）、`style.fontSize`、`style.fontWeight`
+   - 不要逐个 `getNodeInfo`，太慢且容易漏
+
+**⚠️ 与旧策略的差异**：
+- 旧策略：maxDepth=2 拿布局，样式靠组件默认
+- 新策略：includeDetails=true + 批量 `getMultipleNodeInfo` 拿所有 text/rectangle 完整样式 Token
+- 适用场景：需要像素级还原设计稿（颜色、字号、标签背景色等）
+- 代价：token 消耗约 10 倍（旧策略的几 KB → 新策略的几十到几百 KB，取决于节点数）
+
+**步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
+- Sketch 节点结构 + 全量节点 ID 列表
+- text/rectangle 节点的完整样式 Token
+- 图表区结构规律识别结果
+
+组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程中结合步骤 1 的 `templatePatterns` 推理**（详见主流程步骤 4 前置说明）。
+
+### 步骤2.5 实战经验沉淀（重要）
+
+**经验1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
+- 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
+- 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
+
+**经验2：text 节点是颜色/DOM 映射的两级索引**
+每个 text 节点同时关联两种上下文，**必须同批拉取**：
+- 自身样式：`fontSize`、`fontWeight`、`text.color`
+- 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
+
+错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
+正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
+
+**经验3：图表区样式提取有规律可循**
+
+| 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
+|---|---|---|
+| 图表标题 | `text`（带蓝色矩形左饰线） | 14px Semibold；矩形 4×14 #0079f7 |
+| 图例文字 | `text` | 14px |
+| 图例色块 | `rectangle` | 8×8 / 10×3 |
+| 坐标轴文字 | `text`（成组） | 12px #7b828d |
+| 柱体颜色 | 区域 `rectangle` | `style.fills[0].hex` |
+| 数据标签 | `text`（白字） | 12px #ffffff |
+
+**图表区结构规律**：`标题 text + 标题装饰 rectangle + 图例 text*N + 色块 rectangle*N + 坐标轴 text*N + 柱体 rectangle*N + 标签 text*N`
+
+识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
+
+**经验4：矢量图形是工具链盲区（兜底方案）**
+- `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%（实战中 434/926），但 `renderNodeAsBase64` 不支持渲染
+- 解压 `.sketch`（zip 格式）只能提取 `bitmap` 中内嵌的 PNG/PDF（实战中可能仅 2 张，常是侧边栏 Logo）
+- **兜底方案**：① 用解压提取的 PNG/PDF 资源；② 无资源时用 antd `@ant-design/icons` 同语义图标替代；③ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
+
+### 步骤3：分析设计稿图片（有图片时执行）
+
+- 主智能体已提供图片描述时，直接使用，跳过此步
+- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
+- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
+- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+
+### 步骤3.5：组件候选列表推理（统一环节，结合步骤1 + 步骤2.5/3）
+
+**这是统一推理环节**，无论设计稿来源是 .sketch 文件（步骤 2.5）还是图片（步骤 3），都需经过此环节：
+
+```
+步骤 1 templatePatterns  +  步骤 2.5/3 设计稿数据  →  组件候选列表
+(4 种模板模式 + llmMappingHints)  (结构 + 样式 Token)  (如 ["Query","TableOrList","LeftTree","TemplateMode"])
+```
+
+**输入**：
+- 步骤 1 的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
+- 步骤 2.5 的 Sketch 节点结构 + 样式 Token
+- 或步骤 3 的图片分析描述
 
-⚠️ **严格限制**：
-- `getPageStructure` maxDepth 不超过 2，足以判断布局
-- **禁止**循环调用 `getMultipleNodeInfo` / `getNodeInfo` 逐节点查询
-- 仅当 maxDepth=2 的结构不足以判断组件时，才对**特定可疑节点**调用一次 `getNodeInfo`
-- 结构数据拿到后立即进入 LLM 推理，不再继续探查
+**输出**：
+- **组件候选列表**（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
+- 模板类型选择（如 `TemplateMode(templateType="LeftRight")`）
 
-**Sketch 结构 → 组件映射规则**：
+**禁止**：
+- ❌ 在步骤 2.5 内部推理组件候选列表（应只产出 Sketch 数据 + 样式 Token）
+- ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
+- ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
+
+**推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
 
 | Sketch 特征 | 推断组件 |
 |---|---|
@@ -80,23 +161,23 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 弹窗/抽屉图层 | `ModelOrDrawer` |
 | 页面标题 + 返回箭头 | `TitleAndBack` |
 | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
-| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` |
+| 卡片列表 | `TableOrList(componentType="ProList")` |
 | 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
 | 折线趋势图 | `Line` |
 | 柱状对比图 | `Bar` |
 | 饼图/环形图 | `Pie` |
 
-推理出组件候选列表后，立即进入步骤4批量获取组件 API。
+**长尾场景走语义搜索**（不进文档，避免膨胀）：
+- 数据可视化长尾：`Radar` / `Gauge` / `Funnel`（用 `Line/Bar/Pie` 之外的图表）
+- 表格子类型长尾：`DragSortTable`（拖拽排序）、`steps` 步骤条表单
+- 辅助/插槽组件：`CustomOption`（LeftTree 添加按钮）、`TreeNode`（树节点右键菜单）、`ModeAvatar`（头像）、`Upload`（文件上传）
 
-### 步骤3：分析设计稿图片（有图片时执行）
-
-- 主智能体已提供图片描述时，直接使用，跳过此步
-- 否则调用 `mcp__szcd-component-helper__analyze_design_image` 分析
-- 获得描述后，结合步骤1的 `templatePatterns` 推理组件候选列表
-- 立即调用 `mcp__szcd-component-helper__get_component_full_profile`（批量，depth="gencode"）
+**处理方式**：本表未覆盖的视觉特征 → 调用 `{{TOOL:search_components_semantic}}`（query="[场景描述，如'拖拽排序表格']"）按需补全，再进入步骤 4。
 
 ### 步骤4：批量获取组件 API（必做）
 
+**前置条件**：已通过步骤 3.5 获得组件候选列表。
+
 调用 `mcp__szcd-component-helper__get_component_full_profile`：
 - `name` 用逗号分隔一次性查询所有候选组件，如 `"Query,TableOrList,LeftTree,TemplateMode"`
 - `depth="gencode"`（比 deep 小 30-50%，生成代码场景首选）