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

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

@@ -143,79 +143,104 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `{{TOOL:map_design_data}}`。
 
-**工作流（4步直传）**：
+**核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
 
-1. **解析 Sketch 结构**：
+**工作流（6步深度探查，像素级还原）**：
+
+1. **加载文件**：
    - `loadSketchByPath` 加载 .sketch 文件
    - `listPages` 列出所有页面
    - `listNodesByPage`（type="artboard"）获取画板列表
-   - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
+   - 根据画板名称选择目标页面
+
+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 个节点
+   - 关键字段提取：
+     - 背景色：`style.fills[0].color.hex`
+     - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
+     - 字号：`style.fontSize`
+     - 字重：`style.fontWeight`
+     - 边框：`style.borders[0].color.hex` + `thickness`
+   - **禁止**逐个 `getNodeInfo` 探查
+
+**步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
+- Sketch 节点结构 + 全量节点 ID 列表
+- text/rectangle 节点的完整样式 Token
+- 图表区结构规律识别结果
+
+组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程步骤 3.5 中结合步骤 1 的 `templatePatterns` 推理**。
+
+**Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
+```
+.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+→ getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
+→ getNodesSummary(groupBy="type")
+→ getMultipleNodeInfo([所有text+rectangle节点ID])    ← 步骤 2.5 结束
+→ [进入主流程步骤 3.5 统一推理]
+```
 
-2. **获取组件库架构**（已在步骤1完成，复用结果）：
-   - `{{TOOL:get_architecture_overview}}` 的 `templatePatterns` 提供模板组合模式
-   - `llmMappingHints` 提供常见错误修正
+**首轮常见错误 → 正确做法对照表**：
 
-3. **LLM 推理组件范围**：
-   - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
-   - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
-   - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
+| 步骤 | 第一次做错的 | 应该做的 |
+|------|------------|---------|
+| 结构获取 | `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` |
 
-4. **批量获取组件详情**：
-   - 调用 `{{TOOL:get_component_full_profile}}`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
-   - 如需样式注入细节，追加 `{{TOOL:get_style_injection_guide}}`
+**实战经验沉淀（重要，4 条核心收获）**：
 
-**Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
-```
-.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
-→ getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
-→ get_component_full_profile(批量) → 编码
-```
+**收获 1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
+- 错误做法：先查 7 个顶层容器，再根据需要分批补漏（结果补了 7 轮 ≈ 108 个节点）
+- 正确做法：`getPageStructure(pageId)` 一次性拿全量 ID → `getMultipleNodeInfo(全部 text + 全部 rectangle 节点 ID)`，≤100 个/批，**2 批搞定**
 
-**Sketch 结构 → 组件映射规则**：
+**收获 2：text 节点是颜色/DOM 映射的两级索引**
+每个 text 节点同时关联两种上下文，**必须同批拉取**：
+- 自身样式：`fontSize`、`fontWeight`、`text.color`
+- 所属 group 父级 rectangle 样式：`bg`、`border`、`radius`、`shadow`
 
-*页面级布局*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
-| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
-| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
-| 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
+错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
+正确做法：构造查询列表时，**把同一 group 内的 text + rectangle 节点 ID 合并提交**
 
-*区域级组件*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
-| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
-| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
-| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
+**收获 3：图表区样式提取有规律可循**
 
-*数据可视化*：
-| Sketch 特征 | 推断结果 | 依据 |
+| 图表子元素 | 对应 Sketch 节点类型 | 关键样式字段 |
 |---|---|---|
-| 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
-| 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
-| 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
-| 雷达图/多维度对比 | `Radar` | ECharts 层图表组件 |
-| 仪表盘/进度指示 | `Gauge` | ECharts 层图表组件 |
-| 漏斗图/转化率 | `Funnel` | ECharts 层图表组件 |
+| 图表标题 | `text`（带蓝色矩形左饰线） | 14px Semibold；矩形 4×14 #0079f7 |
+| 图例文字 | `text` | 14px |
+| 图例色块 | `rectangle` | 8×8 / 10×3 |
+| 坐标轴文字 | `text`（成组） | 12px #7b828d |
+| 柱体颜色 | 区域 `rectangle` | `style.fills[0].hex` |
+| 数据标签 | `text`（白字） | 12px #ffffff |
 
-*表格子类型*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
-| 拖拽排序表格（有序号/拖拽手柄） | `TableOrList(componentType="DragSortTable")` | 拖拽排序特征 |
-| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
-| 步骤条表单（分步填写） | `ModelOrDrawer(componentType="steps")` | StepsForm 特征 |
+**图表区结构规律**：`标题 text + 标题装饰 rectangle + 图例 text*N + 色块 rectangle*N + 坐标轴 text*N + 柱体 rectangle*N + 标签 text*N`
 
-*辅助/插槽组件*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 树标题栏添加按钮/操作入口 | `CustomOption` | LeftTree 的 CustomOption 插槽 |
-| 树节点右键菜单/增删改操作 | `TreeNode` | LeftTree 的 CustomTreeNode 插槽 |
-| 圆形头像/头像编辑区 | `ModeAvatar` | 头像区域特征 |
-| 文件上传区/拖拽上传框 | `Upload`（Cover 层） | 上传区域特征 |
+识别出图表后，**图例色块**应归入 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"
+
+**提示**：
+- 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
+- `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
+- 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
+- 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `{{TOOL:analyze_design_image}}`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
 
 **提示**：
 - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
@@ -235,69 +260,86 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 <!-- /EXCLUDE:enhanced -->
 
 <!-- INCLUDE:enhanced -->
-**视觉元素 → 组件映射推理（必须执行）**：
+**步骤 3 职责边界**（与步骤 2.5 对称）：
+- ✅ 产出图片描述（结构化文本）
+- ❌ 不做组件候选列表推理（统一在步骤 3.5 进行）
+- ❌ 不调用 `get_component_full_profile`（统一在步骤 4 进行）
+
+**禁止在步骤 3 内部**：
+- ❌ 推理组件候选列表（应进入步骤 3.5）
+- ❌ 批量获取组件 API（应进入步骤 4）
+<!-- /INCLUDE:enhanced -->
+
+<!-- INCLUDE:full -->
+**输出**：设计稿的结构化描述文本（不含组件候选列表推理，候选列表由步骤 3.5 统一产出）
+<!-- /INCLUDE:full -->
+
+### 步骤3.5：组件候选列表推理（统一环节，必做）
+
+**这是统一的组件候选列表推理环节**，无论设计稿来源是 .sketch 文件（步骤 2.5）还是图片（步骤 3），都需经过此环节：
+
+```
+步骤 1 templatePatterns  +  步骤 2.5/3 设计稿数据  →  组件候选列表
+(4 种模板模式 + llmMappingHints)  (结构 + 样式 Token)  (如 ["Query","TableOrList","LeftTree","TemplateMode"])
+```
+
+**输入**：
+- 步骤 1 的 `{{TOOL:get_architecture_overview}}` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
+- 步骤 2.5 的 Sketch 节点结构 + 样式 Token
+- 或步骤 3 的图片分析描述
 
-获得设计稿描述后，**必须结合步骤1的 `templatePatterns`**，将视觉元素映射为具体组件名，生成组件候选列表。**禁止跳过此推理直接进入步骤4逐个搜索。**
+**输出**：
+- **组件候选列表**（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
+- 模板类型选择（如 `TemplateMode(templateType="LeftRight")`）
+
+**禁止**：
+- ❌ 在步骤 2.5 内部推理组件候选列表（应只产出 Sketch 数据 + 样式 Token）
+- ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
+- ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
+
+**推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
 
 *页面级布局*：
-| 视觉特征 | 推断组件 | 依据 |
+| Sketch 特征 | 推断结果 | 依据 |
 |---|---|---|
+| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
 | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
 | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
-| 标签页切换 + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
+| 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
 
 *区域级组件*：
-| 视觉特征 | 推断组件 | 依据 |
+| Sketch 特征 | 推断结果 | 依据 |
 |---|---|---|
-| 左侧窄区域 + 树形结构 | `LeftTree` | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` | 搜索区域特征 |
-| 中间表头 + 数据行 | `TableOrList` | 表格区域特征 |
-| 弹窗/抽屉 | `ModelOrDrawer` | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` | 标题栏特征 |
+| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
+| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
+| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
+| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
+| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
 | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
 
-*数据可视化*：
-| 视觉特征 | 推断组件 | 依据 |
-|---|---|---|
-| 折线趋势图/时间序列 | `Line` | ECharts 层，数据趋势展示 |
-| 柱状对比图/条形图 | `Bar` | ECharts 层，数据对比 |
-| 饼图/环形图/占比图 | `Pie` | ECharts 层，占比关系 |
-| 雷达图/多维度对比 | `Radar` | ECharts 层，多维指标 |
-| 仪表盘/进度指示 | `Gauge` | ECharts 层，单一指标 |
-| 漏斗图/转化率 | `Funnel` | ECharts 层，转化流程 |
-
-*表格子类型（根据 TableOrList 的 componentType 区分）*：
-| 视觉特征 | 推断 componentType | 依据 |
+*数据可视化（核心 3 类）*：
+| Sketch 特征 | 推断结果 | 依据 |
 |---|---|---|
-| 普通只读表格 + 分页 | `ProTable`（默认） | 标准表格 |
-| 可编辑表格（单元格直接输入） | `EditableProTable` | 单元格内编辑控件 |
-| 拖拽排序表格（有序号/拖拽手柄） | `DragSortTable` | 拖拽手柄特征 |
-| 卡片列表（非表格式数据卡片） | `ProList` | 卡片布局特征 |
-| 步骤条表单（分步填写） | `ModelOrDrawer(componentType="steps")` | StepsForm 特征 |
-
-*辅助/插槽组件*：
-| 视觉特征 | 推断组件 | 依据 |
+| 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
+| 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
+| 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
+
+*表格子类型（核心 2 类）*：
+| Sketch 特征 | 推断结果 | 依据 |
 |---|---|---|
-| 树标题栏添加按钮/操作入口 | `CustomOption` | LeftTree 的 CustomOption 插槽 |
-| 树节点右键菜单/增删改操作 | `TreeNode` | LeftTree 的 CustomTreeNode 插槽 |
-| 圆形头像/头像编辑区 | `ModeAvatar` | 头像区域特征 |
-| 文件上传区/拖拽上传框 | `Upload`（Cover 层） | 上传区域特征 |
+| 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
+| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
 
-**推理完成后，立即批量获取组件详情**：
-- 调用 `{{TOOL:get_component_full_profile}}`（name="Query,TableOrList,LeftTree,...", depth="deep"）**一次性**获取所有候选组件 API
-- 如需样式注入细节，追加 `{{TOOL:get_style_injection_guide}}`
+**长尾场景走语义搜索**（不进文档，避免膨胀）：
 
-**设计稿 → szcd 工作流（与 Sketch 流程对齐）**：
-```
-设计稿图片 → analyze_design_image → 视觉描述文本
-→ [步骤1 templatePatterns + 映射推理表] → 组件候选列表
-→ get_component_full_profile(批量) → 进入步骤4验证依赖
-```
-<!-- /INCLUDE:enhanced -->
+*数据可视化长尾*：`Radar`（雷达图）、`Gauge`（仪表盘）、`Funnel`（漏斗图）
 
-<!-- INCLUDE:full -->
-**输出**：设计稿的结构化描述文本 + 组件候选列表 + 批量获取的组件详情
-<!-- /INCLUDE:full -->
+*表格子类型长尾*：`DragSortTable`（拖拽排序表格）、`ModelOrDrawer(componentType="steps")`（步骤条表单）
+
+*辅助/插槽组件*：`CustomOption`（LeftTree 添加按钮插槽）、`TreeNode`（树节点右键菜单插槽）、`ModeAvatar`（圆形头像）、`Upload`（文件上传）
+
+**处理方式**：本表未覆盖的视觉特征 → 调用 `{{TOOL:search_components_semantic}}`（query="[场景描述，如'拖拽排序表格']"）按需补全，再进入步骤 4。
 
 ### 步骤4：查询组件 + 依赖验证（必做）
 

package/agents/szcd-component-expert.md

@@ -72,35 +72,146 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 
 **当用户提供 .sketch 设计文件时**，使用 `sketch-mcp-server`（独立 MCP Server，stdio 模式）解析，直接提取结构化数据，结合组件库架构推理组件方案，无需经过视觉模型和 `map_design_data`。
 
-**工作流（4步直传）**：
+**核心原则**：写代码前必须先 `getMultipleNodeInfo` 拉取所有 `text` 和 `rectangle` 节点的完整样式 Token（`style.fills[0].color.hex`、`text.color`、`style.fontSize`），禁止凭节点名猜测颜色和样式。一次批量查询（50-100 个 ID）比逐个 `getNodeInfo` 快 10 倍以上，且不会遗漏。
 
-1. **解析 Sketch 结构**：
+**工作流（6步深度探查，像素级还原）**：
+
+1. **加载文件**：
    - `loadSketchByPath` 加载 .sketch 文件
    - `listPages` 列出所有页面
    - `listNodesByPage`（type="artboard"）获取画板列表
-   - 根据画板名称选择目标页面，调用 `getNodeInfo` 或 `getPageStructure`（maxDepth=2）提取结构
+   - 根据画板名称选择目标页面
+
+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 个节点
+   - 关键字段提取：
+     - 背景色：`style.fills[0].color.hex`
+     - 文字色：`text.color`（部分版本在 `style.fills[0].color`）
+     - 字号：`style.fontSize`
+     - 字重：`style.fontWeight`
+     - 边框：`style.borders[0].color.hex` + `thickness`
+   - **禁止**逐个 `getNodeInfo` 探查
+
+**步骤 2.5 产出物**（**只产出数据，不做组件映射**）：
+- Sketch 节点结构 + 全量节点 ID 列表
+- text/rectangle 节点的完整样式 Token
+- 图表区结构规律识别结果
+
+组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程步骤 3.5 中结合步骤 1 的 `templatePatterns` 推理**。
+
+**Sketch → szcd 工作流（结构化直传 + 样式 Token，无需视觉模型）**：
+```
+.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
+→ getPageStructure(includeDetails=true) / getDocumentStructure(includeDetails=true)
+→ getNodesSummary(groupBy="type")
+→ getMultipleNodeInfo([所有text+rectangle节点ID])    ← 步骤 2.5 结束
+→ [进入主流程步骤 3.5 统一推理]
+```
+
+**首轮常见错误 → 正确做法对照表**：
+
+| 步骤 | 第一次做错的 | 应该做的 |
+|------|------------|---------|
+| 结构获取 | `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` |
+
+**实战经验沉淀（重要，4 条核心收获）**：
+
+**收获 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"
+
+**提示**：
+- 大型 .sketch 文件先 `listNodesByPage(type="artboard")` 锁定目标画板，避免一次性加载整个文档
+- `getNodesSummary` 是 token 节省关键：先按类型分组统计，再决定要查哪些节点 ID
+- 批量 `getMultipleNodeInfo` 严格 ≤ 100 个/次，超过需分批
+- 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+
+**提示**：
+- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
+- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
+- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
+- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+
+### 步骤3：分析设计稿（条件执行）
 
-2. **获取组件库架构**（已在步骤1完成，复用结果）：
-   - `get_architecture_overview` 的 `templatePatterns` 提供模板组合模式
-   - `llmMappingHints` 提供常见错误修正
+当用户提供了设计稿图片时：
+- 如果**主代理已提供图片描述**（设计稿已被解读为文字），直接使用该描述，跳过图像分析
+- 如果图片未被解读，调用 `analyze_design_image` 工具分析
+- 如果该工具不可用，告知用户需要提供设计稿的文字描述
+
+- 注意：OCR 降级模式下仅返回原始文字，需结合组件库工具自行映射
 
-3. **LLM 推理组件范围**：
-   - 从 Sketch 结构化数据推断：画板名称→`pageName`，区域分布→`layoutType`，图层类型→组件映射
-   - 对照 `templatePatterns` 选择最匹配的模板（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
-   - 输出组件候选列表（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
 
-4. **批量获取组件详情**：
-   - 调用 `get_component_full_profile`（name="Query,TableOrList,LeftTree,TemplateMode", depth="deep"）一次性获取所有需要的组件 API
-   - 如需样式注入细节，追加 `get_style_injection_guide`
+### 步骤3.5：组件候选列表推理（统一环节，必做）
+
+**这是统一的组件候选列表推理环节**，无论设计稿来源是 .sketch 文件（步骤 2.5）还是图片（步骤 3），都需经过此环节：
 
-**Sketch → szcd 工作流（结构化直传，无需视觉模型）**：
 ```
-.sketch → loadSketchByPath → listPages → listNodesByPage(type=artboard)
-→ getNodeInfo/getPageStructure → [步骤1架构数据] → LLM推理组件
-→ get_component_full_profile(批量) → 编码
+步骤 1 templatePatterns  +  步骤 2.5/3 设计稿数据  →  组件候选列表
+(4 种模板模式 + llmMappingHints)  (结构 + 样式 Token)  (如 ["Query","TableOrList","LeftTree","TemplateMode"])
 ```
 
-**Sketch 结构 → 组件映射规则**：
+**输入**：
+- 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
+- 步骤 2.5 的 Sketch 节点结构 + 样式 Token
+- 或步骤 3 的图片分析描述
+
+**输出**：
+- **组件候选列表**（如 `["Query","TableOrList","LeftTree","TemplateMode"]`）
+- 模板类型选择（如 `TemplateMode(templateType="LeftRight")`）
+
+**禁止**：
+- ❌ 在步骤 2.5 内部推理组件候选列表（应只产出 Sketch 数据 + 样式 Token）
+- ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
+- ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
+
+**推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
 
 *页面级布局*：
 | Sketch 特征 | 推断结果 | 依据 |
@@ -120,47 +231,28 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
 | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
 | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
 
-*数据可视化*：
+*数据可视化（核心 3 类）*：
 | Sketch 特征 | 推断结果 | 依据 |
 |---|---|---|
 | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
 | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
 | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
-| 雷达图/多维度对比 | `Radar` | ECharts 层图表组件 |
-| 仪表盘/进度指示 | `Gauge` | ECharts 层图表组件 |
-| 漏斗图/转化率 | `Funnel` | ECharts 层图表组件 |
 
-*表格子类型*：
+*表格子类型（核心 2 类）*：
 | Sketch 特征 | 推断结果 | 依据 |
 |---|---|---|
 | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
-| 拖拽排序表格（有序号/拖拽手柄） | `TableOrList(componentType="DragSortTable")` | 拖拽排序特征 |
 | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
-| 步骤条表单（分步填写） | `ModelOrDrawer(componentType="steps")` | StepsForm 特征 |
-
-*辅助/插槽组件*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 树标题栏添加按钮/操作入口 | `CustomOption` | LeftTree 的 CustomOption 插槽 |
-| 树节点右键菜单/增删改操作 | `TreeNode` | LeftTree 的 CustomTreeNode 插槽 |
-| 圆形头像/头像编辑区 | `ModeAvatar` | 头像区域特征 |
-| 文件上传区/拖拽上传框 | `Upload`（Cover 层） | 上传区域特征 |
 
-**提示**：
-- 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
-- `listNodesByPage(type="artboard")` 优先于 `getPageStructure`，更轻量
-- 仅当结构化数据不足以判断视觉细节（颜色、间距、字体）时，才回退到 `renderNodeAsBase64` + `analyze_design_image`
-- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g sketch-mcp-server`
+**长尾场景走语义搜索**（不进文档，避免膨胀）：
 
-### 步骤3：分析设计稿（条件执行）
+*数据可视化长尾*：`Radar`（雷达图）、`Gauge`（仪表盘）、`Funnel`（漏斗图）
 
-当用户提供了设计稿图片时：
-- 如果**主代理已提供图片描述**（设计稿已被解读为文字），直接使用该描述，跳过图像分析
-- 如果图片未被解读，调用 `analyze_design_image` 工具分析
-- 如果该工具不可用，告知用户需要提供设计稿的文字描述
+*表格子类型长尾*：`DragSortTable`（拖拽排序表格）、`ModelOrDrawer(componentType="steps")`（步骤条表单）
 
-- 注意：OCR 降级模式下仅返回原始文字，需结合组件库工具自行映射
+*辅助/插槽组件*：`CustomOption`（LeftTree 添加按钮插槽）、`TreeNode`（树节点右键菜单插槽）、`ModeAvatar`（圆形头像）、`Upload`（文件上传）
 
+**处理方式**：本表未覆盖的视觉特征 → 调用 `search_components_semantic`（query="[场景描述，如'拖拽排序表格']"）按需补全，再进入步骤 4。
 
 ### 步骤4：查询组件 + 依赖验证（必做）