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

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

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