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

package/agents/src/szcd-component-expert.md

@@ -141,54 +141,54 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 ### 步骤2.5：Sketch 文件解析（条件执行）
 
-**当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `{{TOOL:map_design_data}}`。
+**当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式，**v1.5.0+**）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `{{TOOL:map_design_data}}`。
 
-**核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
+**核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text`、`rectangle`、`group` 节点的完整样式 Token + 父子归属。`queryNodes.type` 接受数组（一次拿三类）、`getMultipleNodeInfo` 内部自动分片、每个节点自动返回 `parent: {id,name,type}`，禁止凭节点名猜测样式，禁止用 x 坐标判定元素归属。
 
-**工作流（6步深度探查，像素级还原）**：
+**工作流（4 步，sketch-mcp-server v1.5.0+）**：
 
 1. **加载文件**：
    - `loadSketchByPath` 加载 .sketch 文件
    - `listPages` 列出所有页面
-   - `listNodesByPage`（type="artboard"）获取画板列表
+   - `queryNodes`（pageId, type="artboard"）获取画板列表
    - 根据画板名称选择目标页面
 
-2. **获取完整节点树**：
-   - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
-   - 必须 `includeDetails=true`，否则拿不到初始样式
-   - 拿到所有节点 ID 列表，为下一步分组做准备
-
-3. **按类型分组统计**：
-   - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
-   - 识别组件模式：
-     - `group(rectangle + text)` = 标签组件（如状态徽章）
-     - `group(text + text + rectangle...)` = 表单项
-     - `group(text 列表 + 边框)` = 表格行
-   - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
-
-4. **批量拉取样式 Token**：
-   - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
+2. **获取分区结构**：
+   - `getPageStructure`（pageId, mode="tree", maxDepth=3）— 看顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
+   - 记下每个分区根 group 的 id 和 name，后续按 `parent` 字段归属元素
+
+3. **批量获取目标节点 ID**：
+   - 推荐：`queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })` — **type 数组**一次拿三类节点的 ID
+   - 备选：`getPageStructure(pageId, mode="ids")` — 返回按类型分组的全量 ID `{ text: [...], rectangle: [...], group: [...], bitmap: [...], shapePath: [...] }`
+   - 顺手记下 bitmap/shapePath 节点列表，传给步骤 2.5.1
+
+4. **批量拉取样式 Token + 父子归属**：
+   - `getMultipleNodeInfo`（[id1, id2, ...]）— 传入全部 ID，**内部自动按 100 个一批分片**，无需手动拆分
+   - **同批必须包含 text + rectangle + group 三类节点 ID**（漏 group 会丢失渐变背景/边框/阴影）
    - 关键字段提取：
-     - 背景色：`style.fills[0].color.hex`
+     - 背景色：`style.fills[0].color.hex`（含 group 容器的渐变）
      - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
      - 字号：`style.fontSize`
      - 字重：`style.fontWeight`
      - 边框：`style.borders[0].color.hex` + `thickness`
+     - 阴影：`style.shadows`
+     - **父子归属**：`parent: { id, name, type }` ← v1.5.0+ 自动返回，元素归属判定唯一可信来源
    - **禁止**逐个 `getNodeInfo` 探查
 
 **步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
-- Sketch 节点结构 + 全量节点 ID 列表
-- text/rectangle 节点的完整样式 Token
+- Sketch 顶层分区结构（步骤 2 的 tree）
+- text/rectangle/group 节点的完整样式 Token + parent 父子关系
 - 图表区结构规律识别结果
+- bitmap ID 列表 + shapePath 节点名列表（传给步骤 2.5.1）
 
 组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程步骤 3.5 中结合步骤 1 的 `templatePatterns` 推理**。
 
-**Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
+**Sketch → szcd 工作流（v1.5.0+）**：
 ```
-.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
-→ getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
-→ getNodesSummary(groupBy="type")
-→ getMultipleNodeInfo([所有text+rectangle节点ID])    ← 步骤 2.5 结束
+.sketch → loadSketchByPath → listPages → queryNodes(pageId, type="artboard")
+→ getPageStructure(pageId, mode="tree", maxDepth=3)          ← 拿分区
+→ queryNodes(pageId, type=["text","rectangle","group"])      ← 拿全量 ID（数组类型）
+→ getMultipleNodeInfo([全部 ID])                              ← 自动分片，含 parent 字段
 → [进入主流程步骤 3.5 统一推理]
 ```
 
@@ -196,16 +196,17 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 | 步骤 | 第一次做错的 | 应该做的 |
 |------|------------|---------|
-| 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
-| 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
-| 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
-| 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
+| 分区识别 | 直接拉所有节点详情，靠 x/y 反推分区 | `getPageStructure(mode="tree", maxDepth=3)` 先看顶层 group 分布 |
+| 节点收集 | 分两次调用 queryNodes 拿 text 和 rectangle | `queryNodes(type=["text","rectangle","group"])` 一次拿三类 |
+| 样式提取 | 没做 | `getMultipleNodeInfo([全部 ID])` 内部自动分片，**单次调用** |
+| 元素归属 | 凭 x/y 坐标判定（"x=272 列都是同区域"） | 看 `getMultipleNodeInfo` 返回的 `parent.id/name` 字段 |
+| 颜色提取 | 跳过 group 只取 text/rectangle | 同批提交 group ID，从 `style.fills` 取渐变背景 |
 
-**实战经验沉淀（重要，4 条核心收获）**：
+**实战经验沉淀（重要）**：
 
 **收获 1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
 - 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
-- 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
+- 正确做法：`queryNodes(type=["text","rectangle","group"])` 一次性拿全量 ID → `getMultipleNodeInfo([全部 ID])`，**单次调用**（内部自动分片）
 
 **收获 2：text 节点是颜色/DOM 映射的两级索引**
 每个 text 节点同时关联两种上下文，**必须同批拉取**：
@@ -213,9 +214,28 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 - 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
 
 错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
-正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
+正确做法：用 `queryNodes(type=["text","rectangle","group"])` 一次拿三类 ID，`getMultipleNodeInfo` 返回的 `parent` 字段直接告诉你归属关系
+
+**收获 3：元素归属必须走 group 父子关系，禁止 x 坐标平面判定**
+
+实战教训：`'主题'text(x=272,y=149)` 被错误识别为内容区块标题，实际是左侧树标题（与树节点同 x=272 列）。同列坐标不代表同区域。
+
+正确做法：
+- 步骤 2 拿到完整节点树后，先识别顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
+- `getMultipleNodeInfo` v1.5.0+ **自动返回** `parent: { id, name, type }` 字段，按 parent 归属到具体分区
+- "主题"这类标题文本，先看 `parent.name` 是否带 "LeftTree" / "树" / "PageContent" 等容器关键字，不要看 x 坐标
+- 坐标仅作为同 parent 内子元素排序兜底使用
+
+**收获 4：信息栏/卡片容器必须先取 group 再取子元素**
+
+实战教训：仅提取 text 节点导致信息栏容器样式遗漏（渐变背景 #f3faff→#f8fdff、边框 #e9f5ff、图标编组）。
+
+正确做法：
+- 看到画板里有 `编组N`/`infoCard`/`statBox` 等 group 节点，必须连 group 自身和内部 rectangle 一起拉 `getMultipleNodeInfo`
+- group 节点的 `style.fills` 才是渐变背景、`style.borders` 才是边框
+- 子图标若为 group(rectangle + shapePath)，rectangle 是圆形/方形背景，shapePath 是矢量图标
 
-**收获 3：图表区样式提取有规律可循**
+**收获 5：图表区样式提取有规律可循**
 
 | 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
 |---|---|---|
@@ -230,23 +250,34 @@ 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"
+**收获 6：矢量图形 + 图标语义优先级（v1.5.0 已内置 compoundIcons）**
+- `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，`renderNodeAsBase64` 不支持渲染
+- 解压 `.sketch` 只能提取 `bitmap` 中内嵌的 PNG/PDF（常仅几张，通常是 Logo）
+- **`matchIconFromName` v1.5.0+ 评分制**：每个 nodeName 返回 Top-3 候选，complex 词组合（如"文件夹+新增"）自动命中 `FolderAddOutlined`（compound score 100+），不会被"新增"单独 +20 分压制
+  - 优先看 `bestMatch.source === "compound"`：表示已强映射，直接采用 `antdIcon`
+  - `unmatched`（无关键词信号，如"编组11备份"）必须看节点 `parent.name` 和兄弟节点上下文兜底
 
-**提示**：
-- 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
-- `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
-- 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
-- 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
-- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+**参考表（内置 compoundIcons 已覆盖；列出供 unmatched 兜底参考）**：
 
-**提示**：
-- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
-- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
-- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
-- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+| Sketch 节点上下文 | 期望 antd 图标 | 反例（不要选） |
+|---|---|---|
+| 文件夹+新增/添加 | `FolderAddOutlined` | PlusOutlined |
+| 文件+新增 | `FileAddOutlined` | PlusOutlined |
+| 用户+新增 | `UserAddOutlined` | PlusOutlined |
+| 文件夹+打开 | `FolderOpenOutlined` | FolderOutlined |
+| 编辑+笔 | `EditOutlined` | FormOutlined |
+| 设置+齿轮 | `SettingOutlined` | ToolOutlined |
+
+- **兜底方案**：① 用 `extractBitmaps` 提取的 PNG/PDF 资源；② `matchIconFromName` 的 Top-1（若 source=compound）；③ unmatched 时按 parent 上下文 + 上表选 antd `@ant-design/icons` 复合图标；④ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
+
+**提示（sketch-mcp-server v1.5.0+）**：
+- 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
+- `queryNodes(pageId, type=["text","rectangle","group"])` 一次拿三类节点 ID（type 字段支持数组），跳过 `getPageStructure(mode="ids")` 单独调用
+- `getPageStructure(pageId, mode="tree", maxDepth=2-3)` 用于看分区层级；`mode="summary"` 用于按类型统计概况
+- 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部按 100 一批自动分片），无需手动拆分；每个节点自带 `parent: {id,name,type}` 字段，元素归属直接走 parent，禁止用 x/y 坐标
+- `matchIconFromName` 评分制返回 Top-3 + `bestMatch.source === "compound"` 强映射，shapePath 节点优先走它
+- 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g @szc-ft/sketch-mcp-server`
 
 ### 步骤3：分析设计稿（条件执行）
 
@@ -331,6 +362,19 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
 | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
 
+#### ⚠️ 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`（漏斗图）

package/agents/src/tools.json

@@ -31,7 +31,7 @@
     },
     {
         "name": "get_upload_endpoint",
-        "description": "获取设计稿图片上传接口地址和curl命令，上传后取upload_id传给analyze_design_image",
+        "description": "获取设计稿图片上传接口地址和curl命令，上传后取upload_id传给analyze_design_image。上传最多重试3次，超过后停止并向用户说明失败原因",
         "whenToUse": "步骤3：上传设计稿"
     },
     {

package/agents/szcd-component-expert.md

@@ -70,54 +70,54 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 
 ### 步骤2.5：Sketch 文件解析（条件执行）
 
-**当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
+**当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式，**v1.5.0+**）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
 
-**核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
+**核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text`、`rectangle`、`group` 节点的完整样式 Token + 父子归属。`queryNodes.type` 接受数组（一次拿三类）、`getMultipleNodeInfo` 内部自动分片、每个节点自动返回 `parent: {id,name,type}`，禁止凭节点名猜测样式，禁止用 x 坐标判定元素归属。
 
-**工作流（6步深度探查，像素级还原）**：
+**工作流（4 步，sketch-mcp-server v1.5.0+）**：
 
 1. **加载文件**：
    - `loadSketchByPath` 加载 .sketch 文件
    - `listPages` 列出所有页面
-   - `listNodesByPage`（type="artboard"）获取画板列表
+   - `queryNodes`（pageId, type="artboard"）获取画板列表
    - 根据画板名称选择目标页面
 
-2. **获取完整节点树**：
-   - `getPageStructure`（pageId）**或** `getDocumentStructure`（includeDetails=true）— 拿到完整节点树 + 所有节点 ID
-   - 必须 `includeDetails=true`，否则拿不到初始样式
-   - 拿到所有节点 ID 列表，为下一步分组做准备
-
-3. **按类型分组统计**：
-   - `getNodesSummary`（pageId, groupBy="type"）— 按类型分组，统计 text/rectangle/group 各多少个
-   - 识别组件模式：
-     - `group(rectangle + text)` = 标签组件（如状态徽章）
-     - `group(text + text + rectangle...)` = 表单项
-     - `group(text 列表 + 边框)` = 表格行
-   - 决定下一批 `getMultipleNodeInfo` 的目标节点范围（所有 type=text + type=rectangle）
-
-4. **批量拉取样式 Token**：
-   - `getMultipleNodeInfo`（[id1, id2, ...]）— 每次 ≤ 100 个节点
+2. **获取分区结构**：
+   - `getPageStructure`（pageId, mode="tree", maxDepth=3）— 看顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
+   - 记下每个分区根 group 的 id 和 name，后续按 `parent` 字段归属元素
+
+3. **批量获取目标节点 ID**：
+   - 推荐：`queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })` — **type 数组**一次拿三类节点的 ID
+   - 备选：`getPageStructure(pageId, mode="ids")` — 返回按类型分组的全量 ID `{ text: [...], rectangle: [...], group: [...], bitmap: [...], shapePath: [...] }`
+   - 顺手记下 bitmap/shapePath 节点列表，传给步骤 2.5.1
+
+4. **批量拉取样式 Token + 父子归属**：
+   - `getMultipleNodeInfo`（[id1, id2, ...]）— 传入全部 ID，**内部自动按 100 个一批分片**，无需手动拆分
+   - **同批必须包含 text + rectangle + group 三类节点 ID**（漏 group 会丢失渐变背景/边框/阴影）
    - 关键字段提取：
-     - 背景色：`style.fills[0].color.hex`
+     - 背景色：`style.fills[0].color.hex`（含 group 容器的渐变）
      - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
      - 字号：`style.fontSize`
      - 字重：`style.fontWeight`
      - 边框：`style.borders[0].color.hex` + `thickness`
+     - 阴影：`style.shadows`
+     - **父子归属**：`parent: { id, name, type }` ← v1.5.0+ 自动返回，元素归属判定唯一可信来源
    - **禁止**逐个 `getNodeInfo` 探查
 
 **步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
-- Sketch 节点结构 + 全量节点 ID 列表
-- text/rectangle 节点的完整样式 Token
+- Sketch 顶层分区结构（步骤 2 的 tree）
+- text/rectangle/group 节点的完整样式 Token + parent 父子关系
 - 图表区结构规律识别结果
+- bitmap ID 列表 + shapePath 节点名列表（传给步骤 2.5.1）
 
 组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程步骤 3.5 中结合步骤 1 的 `templatePatterns` 推理**。
 
-**Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
+**Sketch → szcd 工作流（v1.5.0+）**：
 ```
-.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
-→ getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
-→ getNodesSummary(groupBy="type")
-→ getMultipleNodeInfo([所有text+rectangle节点ID])    ← 步骤 2.5 结束
+.sketch → loadSketchByPath → listPages → queryNodes(pageId, type="artboard")
+→ getPageStructure(pageId, mode="tree", maxDepth=3)          ← 拿分区
+→ queryNodes(pageId, type=["text","rectangle","group"])      ← 拿全量 ID（数组类型）
+→ getMultipleNodeInfo([全部 ID])                              ← 自动分片，含 parent 字段
 → [进入主流程步骤 3.5 统一推理]
 ```
 
@@ -125,16 +125,17 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 
 | 步骤 | 第一次做错的 | 应该做的 |
 |------|------------|---------|
-| 结构获取 | `getDocumentStructure(includeDetails=false)` 只有名称和位置 | `includeDetails=true` 或 `getPageStructure`，拿到初始样式 |
-| 样式提取 | 没做 | `getMultipleNodeInfo` 批量拉取所有 type=text 和 type=rectangle 节点 |
-| 组件识别 | 凭节点名猜测（如看到 "tag" 节点就写 `<Tag>`） | `getNodesSummary(groupBy="type")` 统计类型分布，识别 text+rectangle 组合 → 标签组件 |
-| 颜色提取 | 跳过 | 对每个 rectangle（背景）+ text（文字）取 `style.fills[0].color.hex` + `text.color` |
+| 分区识别 | 直接拉所有节点详情，靠 x/y 反推分区 | `getPageStructure(mode="tree", maxDepth=3)` 先看顶层 group 分布 |
+| 节点收集 | 分两次调用 queryNodes 拿 text 和 rectangle | `queryNodes(type=["text","rectangle","group"])` 一次拿三类 |
+| 样式提取 | 没做 | `getMultipleNodeInfo([全部 ID])` 内部自动分片，**单次调用** |
+| 元素归属 | 凭 x/y 坐标判定（"x=272 列都是同区域"） | 看 `getMultipleNodeInfo` 返回的 `parent.id/name` 字段 |
+| 颜色提取 | 跳过 group 只取 text/rectangle | 同批提交 group ID，从 `style.fills` 取渐变背景 |
 
-**实战经验沉淀（重要，4 条核心收获）**：
+**实战经验沉淀（重要）**：
 
 **收获 1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
 - 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
-- 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
+- 正确做法：`queryNodes(type=["text","rectangle","group"])` 一次性拿全量 ID → `getMultipleNodeInfo([全部 ID])`，**单次调用**（内部自动分片）
 
 **收获 2：text 节点是颜色/DOM 映射的两级索引**
 每个 text 节点同时关联两种上下文，**必须同批拉取**：
@@ -142,9 +143,28 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 - 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
 
 错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
-正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
+正确做法：用 `queryNodes(type=["text","rectangle","group"])` 一次拿三类 ID，`getMultipleNodeInfo` 返回的 `parent` 字段直接告诉你归属关系
+
+**收获 3：元素归属必须走 group 父子关系，禁止 x 坐标平面判定**
+
+实战教训：`'主题'text(x=272,y=149)` 被错误识别为内容区块标题，实际是左侧树标题（与树节点同 x=272 列）。同列坐标不代表同区域。
+
+正确做法：
+- 步骤 2 拿到完整节点树后，先识别顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
+- `getMultipleNodeInfo` v1.5.0+ **自动返回** `parent: { id, name, type }` 字段，按 parent 归属到具体分区
+- "主题"这类标题文本，先看 `parent.name` 是否带 "LeftTree" / "树" / "PageContent" 等容器关键字，不要看 x 坐标
+- 坐标仅作为同 parent 内子元素排序兜底使用
+
+**收获 4：信息栏/卡片容器必须先取 group 再取子元素**
+
+实战教训：仅提取 text 节点导致信息栏容器样式遗漏（渐变背景 #f3faff→#f8fdff、边框 #e9f5ff、图标编组）。
+
+正确做法：
+- 看到画板里有 `编组N`/`infoCard`/`statBox` 等 group 节点，必须连 group 自身和内部 rectangle 一起拉 `getMultipleNodeInfo`
+- group 节点的 `style.fills` 才是渐变背景、`style.borders` 才是边框
+- 子图标若为 group(rectangle + shapePath)，rectangle 是圆形/方形背景，shapePath 是矢量图标
 
-**收获 3：图表区样式提取有规律可循**
+**收获 5：图表区样式提取有规律可循**
 
 | 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
 |---|---|---|
@@ -159,23 +179,34 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 
 识别出图表后，**图例色块**应归入 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"
+**收获 6：矢量图形 + 图标语义优先级（v1.5.0 已内置 compoundIcons）**
+- `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，`renderNodeAsBase64` 不支持渲染
+- 解压 `.sketch` 只能提取 `bitmap` 中内嵌的 PNG/PDF（常仅几张，通常是 Logo）
+- **`matchIconFromName` v1.5.0+ 评分制**：每个 nodeName 返回 Top-3 候选，complex 词组合（如"文件夹+新增"）自动命中 `FolderAddOutlined`（compound score 100+），不会被"新增"单独 +20 分压制
+  - 优先看 `bestMatch.source === "compound"`：表示已强映射，直接采用 `antdIcon`
+  - `unmatched`（无关键词信号，如"编组11备份"）必须看节点 `parent.name` 和兄弟节点上下文兜底
 
-**提示**：
-- 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
-- `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
-- 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
-- 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
-- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+**参考表（内置 compoundIcons 已覆盖；列出供 unmatched 兜底参考）**：
 
-**提示**：
-- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
-- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
-- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
-- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+| Sketch 节点上下文 | 期望 antd 图标 | 反例（不要选） |
+|---|---|---|
+| 文件夹+新增/添加 | `FolderAddOutlined` | PlusOutlined |
+| 文件+新增 | `FileAddOutlined` | PlusOutlined |
+| 用户+新增 | `UserAddOutlined` | PlusOutlined |
+| 文件夹+打开 | `FolderOpenOutlined` | FolderOutlined |
+| 编辑+笔 | `EditOutlined` | FormOutlined |
+| 设置+齿轮 | `SettingOutlined` | ToolOutlined |
+
+- **兜底方案**：① 用 `extractBitmaps` 提取的 PNG/PDF 资源；② `matchIconFromName` 的 Top-1（若 source=compound）；③ unmatched 时按 parent 上下文 + 上表选 antd `@ant-design/icons` 复合图标；④ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
+
+**提示（sketch-mcp-server v1.5.0+）**：
+- 大型 .sketch 文件先 `queryNodes(pageId, type="artboard")` 锁定目标画板，避免一次性加载整个文档
+- `queryNodes(pageId, type=["text","rectangle","group"])` 一次拿三类节点 ID（type 字段支持数组），跳过 `getPageStructure(mode="ids")` 单独调用
+- `getPageStructure(pageId, mode="tree", maxDepth=2-3)` 用于看分区层级；`mode="summary"` 用于按类型统计概况
+- 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部按 100 一批自动分片），无需手动拆分；每个节点自带 `parent: {id,name,type}` 字段，元素归属直接走 parent，禁止用 x/y 坐标
+- `matchIconFromName` 评分制返回 Top-3 + `bestMatch.source === "compound"` 强映射，shapePath 节点优先走它
+- 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g @szc-ft/sketch-mcp-server`
 
 ### 步骤3：分析设计稿（条件执行）
 
@@ -244,6 +275,19 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
 | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
 
+#### ⚠️ 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`（漏斗图）