@szc-ft/mcp-szcd-client 0.26.0 → 0.27.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 (17) hide show
  1. package/agents/opencode-extension/agents/szcd-component-expert.md +9 -31
  2. package/agents/qwen-extension/agents/szcd-component-expert.md +9 -31
  3. package/agents/src/szcd-component-expert.md +9 -31
  4. package/agents/src/tools.json +2 -2
  5. package/agents/szcd-component-expert.md +9 -31
  6. package/agents/szcd-component-expert.qoder.md +10 -32
  7. package/agents/szcd-component-expert.trae.md +9 -31
  8. package/opencode-extension/agents/szcd-component-expert.md +9 -31
  9. package/opencode-extension/skills/szcd-component-helper/SKILL.md +12 -13
  10. package/opencode-extension/skills/szcd-design-to-code/SKILL.md +72 -21
  11. package/package.json +1 -1
  12. package/qwen-extension/agents/szcd-component-expert.md +9 -31
  13. package/qwen-extension/qwen-extension.json +1 -1
  14. package/qwen-extension/skills/szcd-component-helper/SKILL.md +12 -13
  15. package/qwen-extension/skills/szcd-design-to-code/SKILL.md +72 -21
  16. package/standard-skill/szcd-component-helper/SKILL.md +12 -13
  17. package/standard-skill/szcd-design-to-code/SKILL.md +73 -21
package/agents/opencode-extension/agents/szcd-component-expert.md CHANGED
@@ -42,7 +42,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
42
42
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
43
43
 
44
44
  执行动作：
45
- 1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
45
+ 1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
46
46
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
47
47
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
48
48
 
@@ -370,6 +370,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
370
370
 
371
371
  **输入**：
372
372
  - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
373
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
373
374
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
374
375
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
375
376
  - 或步骤 3 的图片分析描述
@@ -383,38 +384,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
383
384
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
384
385
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
385
386
 
386
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
387
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
387
388
 
388
- *页面级布局*：
389
- | Sketch 特征 | 推断结果 | 依据 |
390
- |---|---|---|
391
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
392
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
393
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
394
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
389
+ 1. **画板名称** → 直接作为 `pageName`
390
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
391
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
392
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
393
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
395
394
 
396
- *区域级组件*：
397
- | Sketch 特征 | 推断结果 | 依据 |
398
- |---|---|---|
399
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
400
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
401
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
402
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
403
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
404
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
405
-
406
- *数据可视化（核心 3 类）*：
407
- | Sketch 特征 | 推断结果 | 依据 |
408
- |---|---|---|
409
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
410
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
411
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
412
-
413
- *表格子类型（核心 2 类）*：
414
- | Sketch 特征 | 推断结果 | 依据 |
415
- |---|---|---|
416
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
417
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
395
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
418
396
 
419
397
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
420
398
 
package/agents/qwen-extension/agents/szcd-component-expert.md CHANGED
@@ -38,7 +38,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
38
38
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
39
39
 
40
40
  执行动作：
41
- 1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
41
+ 1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
42
42
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
43
43
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
44
44
 
@@ -366,6 +366,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
366
366
 
367
367
  **输入**：
368
368
  - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
369
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
369
370
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
370
371
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
371
372
  - 或步骤 3 的图片分析描述
@@ -379,38 +380,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
379
380
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
380
381
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
381
382
 
382
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
383
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
383
384
 
384
- *页面级布局*：
385
- | Sketch 特征 | 推断结果 | 依据 |
386
- |---|---|---|
387
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
388
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
389
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
390
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
385
+ 1. **画板名称** → 直接作为 `pageName`
386
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
387
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
388
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
389
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
391
390
 
392
- *区域级组件*：
393
- | Sketch 特征 | 推断结果 | 依据 |
394
- |---|---|---|
395
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
396
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
397
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
398
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
399
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
400
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
401
-
402
- *数据可视化（核心 3 类）*：
403
- | Sketch 特征 | 推断结果 | 依据 |
404
- |---|---|---|
405
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
406
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
407
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
408
-
409
- *表格子类型（核心 2 类）*：
410
- | Sketch 特征 | 推断结果 | 依据 |
411
- |---|---|---|
412
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
413
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
391
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
414
392
 
415
393
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
416
394
 
package/agents/src/szcd-component-expert.md CHANGED
@@ -88,7 +88,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
88
88
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
89
89
 
90
90
  执行动作：
91
- 1. 调用 `{{TOOL:get_architecture_overview}}`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
91
+ 1. 调用 `{{TOOL:get_architecture_overview}}`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
92
92
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
93
93
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
94
94
 
@@ -457,6 +457,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
457
457
 
458
458
  **输入**：
459
459
  - 步骤 1 的 `{{TOOL:get_architecture_overview}}` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
460
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
460
461
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
461
462
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
462
463
  - 或步骤 3 的图片分析描述
@@ -470,38 +471,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
470
471
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
471
472
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
472
473
 
473
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
474
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
474
475
 
475
- *页面级布局*：
476
- | Sketch 特征 | 推断结果 | 依据 |
477
- |---|---|---|
478
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
479
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
480
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
481
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
476
+ 1. **画板名称** → 直接作为 `pageName`
477
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
478
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
479
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
480
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
482
481
 
483
- *区域级组件*：
484
- | Sketch 特征 | 推断结果 | 依据 |
485
- |---|---|---|
486
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
487
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
488
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
489
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
490
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
491
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
492
-
493
- *数据可视化（核心 3 类）*：
494
- | Sketch 特征 | 推断结果 | 依据 |
495
- |---|---|---|
496
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
497
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
498
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
499
-
500
- *表格子类型（核心 2 类）*：
501
- | Sketch 特征 | 推断结果 | 依据 |
502
- |---|---|---|
503
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
504
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
482
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
505
483
 
506
484
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
507
485
 
package/agents/src/tools.json CHANGED
@@ -1,8 +1,8 @@
1
1
  [
2
2
  {
3
3
  "name": "get_architecture_overview",
4
- "description": "获取7层架构图、模板组合模式、LLM映射错误提示",
5
- "whenToUse": "步骤1：架构认知"
4
+ "description": "获取7层架构图、模板组合模式、LLM映射错误提示。detail=full 额外返回 componentSummary（全量组件+设计元信息：layoutRole/variantProps/styleInjection/useCases/chartType/sketchSignals）+ styleMapping（节点样式映射）+ assetExtraction（图标/位图/图表色提取规则），设计稿→代码场景必选 full",
5
+ "whenToUse": "步骤1：架构认知（设计稿场景用 detail=full 一次拿全）"
6
6
  },
7
7
  {
8
8
  "name": "search_components_semantic",
package/agents/szcd-component-expert.md CHANGED
@@ -42,7 +42,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
42
42
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
43
43
 
44
44
  执行动作：
45
- 1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
45
+ 1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
46
46
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
47
47
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
48
48
 
@@ -370,6 +370,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
370
370
 
371
371
  **输入**：
372
372
  - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
373
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
373
374
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
374
375
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
375
376
  - 或步骤 3 的图片分析描述
@@ -383,38 +384,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
383
384
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
384
385
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
385
386
 
386
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
387
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
387
388
 
388
- *页面级布局*：
389
- | Sketch 特征 | 推断结果 | 依据 |
390
- |---|---|---|
391
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
392
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
393
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
394
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
389
+ 1. **画板名称** → 直接作为 `pageName`
390
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
391
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
392
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
393
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
395
394
 
396
- *区域级组件*：
397
- | Sketch 特征 | 推断结果 | 依据 |
398
- |---|---|---|
399
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
400
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
401
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
402
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
403
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
404
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
405
-
406
- *数据可视化（核心 3 类）*：
407
- | Sketch 特征 | 推断结果 | 依据 |
408
- |---|---|---|
409
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
410
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
411
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
412
-
413
- *表格子类型（核心 2 类）*：
414
- | Sketch 特征 | 推断结果 | 依据 |
415
- |---|---|---|
416
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
417
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
395
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
418
396
 
419
397
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
420
398
 
package/agents/szcd-component-expert.qoder.md CHANGED
@@ -51,7 +51,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
51
51
 
52
52
  | 工具名 | 功能 | 何时使用 |
53
53
  |--------|------|---------|
54
- | `get_architecture_overview` | 获取7层架构图、模板组合模式、LLM映射错误提示 | 步骤1：架构认知 |
54
+ | `get_architecture_overview` | 获取7层架构图、模板组合模式、LLM映射错误提示。detail=full 额外返回 componentSummary（全量组件+设计元信息：layoutRole/variantProps/styleInjection/useCases/chartType/sketchSignals）+ styleMapping（节点样式映射）+ assetExtraction（图标/位图/图表色提取规则），设计稿→代码场景必选 full | 步骤1：架构认知（设计稿场景用 detail=full 一次拿全） |
55
55
  | `search_components_semantic` | 基于Repowiki知识库的语义搜索，用自然语言描述匹配最适合的组件 | 步骤4：语义搜索匹配 |
56
56
  | `get_component_full_profile` | 一站式获取组件全景画像。name支持逗号分隔批量查询，depth=deep获取Props链+源码摘要+样式注入，返回值是紧凑Markdown格式 | 步骤4：批量获取全景画像 |
57
57
  | `get_best_practices` | 获取组件使用最佳实践和常见错误修正，指定scenario可获取组合最佳实践 | 步骤4：组合最佳实践 |
@@ -86,7 +86,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
86
86
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
87
87
 
88
88
  执行动作：
89
- 1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
89
+ 1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
90
90
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
91
91
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
92
92
 
@@ -429,6 +429,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
429
429
 
430
430
  **输入**：
431
431
  - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
432
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
432
433
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
433
434
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
434
435
  - 或步骤 3 的图片分析描述
@@ -442,38 +443,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
442
443
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
443
444
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
444
445
 
445
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
446
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
446
447
 
447
- *页面级布局*：
448
- | Sketch 特征 | 推断结果 | 依据 |
449
- |---|---|---|
450
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
451
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
452
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
453
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
448
+ 1. **画板名称** → 直接作为 `pageName`
449
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
450
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
451
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
452
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
454
453
 
455
- *区域级组件*：
456
- | Sketch 特征 | 推断结果 | 依据 |
457
- |---|---|---|
458
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
459
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
460
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
461
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
462
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
463
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
464
-
465
- *数据可视化（核心 3 类）*：
466
- | Sketch 特征 | 推断结果 | 依据 |
467
- |---|---|---|
468
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
469
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
470
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
471
-
472
- *表格子类型（核心 2 类）*：
473
- | Sketch 特征 | 推断结果 | 依据 |
474
- |---|---|---|
475
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
476
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
454
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
477
455
 
478
456
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
479
457
 
package/agents/szcd-component-expert.trae.md CHANGED
@@ -56,7 +56,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
56
56
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
57
57
 
58
58
  执行动作：
59
- 1. 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
59
+ 1. 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
60
60
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
61
61
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
62
62
 
@@ -392,6 +392,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
392
392
 
393
393
  **输入**：
394
394
  - 步骤 1 的 `mcp__szcd-component-helper__get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
395
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
395
396
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
396
397
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
397
398
  - 或步骤 3 的图片分析描述
@@ -405,38 +406,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
405
406
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
406
407
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
407
408
 
408
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
409
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
409
410
 
410
- *页面级布局*：
411
- | Sketch 特征 | 推断结果 | 依据 |
412
- |---|---|---|
413
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
414
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
415
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
416
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
411
+ 1. **画板名称** → 直接作为 `pageName`
412
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
413
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
414
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
415
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
417
416
 
418
- *区域级组件*：
419
- | Sketch 特征 | 推断结果 | 依据 |
420
- |---|---|---|
421
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
422
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
423
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
424
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
425
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
426
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
427
-
428
- *数据可视化（核心 3 类）*：
429
- | Sketch 特征 | 推断结果 | 依据 |
430
- |---|---|---|
431
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
432
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
433
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
434
-
435
- *表格子类型（核心 2 类）*：
436
- | Sketch 特征 | 推断结果 | 依据 |
437
- |---|---|---|
438
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
439
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
417
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
440
418
 
441
419
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
442
420
 
package/opencode-extension/agents/szcd-component-expert.md CHANGED
@@ -42,7 +42,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
42
42
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
43
43
 
44
44
  执行动作：
45
- 1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
45
+ 1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
46
46
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
47
47
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
48
48
 
@@ -370,6 +370,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
370
370
 
371
371
  **输入**：
372
372
  - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
373
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
373
374
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
374
375
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
375
376
  - 或步骤 3 的图片分析描述
@@ -383,38 +384,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
383
384
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
384
385
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
385
386
 
386
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
387
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
387
388
 
388
- *页面级布局*：
389
- | Sketch 特征 | 推断结果 | 依据 |
390
- |---|---|---|
391
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
392
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
393
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
394
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
389
+ 1. **画板名称** → 直接作为 `pageName`
390
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
391
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
392
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
393
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
395
394
 
396
- *区域级组件*：
397
- | Sketch 特征 | 推断结果 | 依据 |
398
- |---|---|---|
399
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
400
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
401
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
402
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
403
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
404
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
405
-
406
- *数据可视化（核心 3 类）*：
407
- | Sketch 特征 | 推断结果 | 依据 |
408
- |---|---|---|
409
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
410
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
411
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
412
-
413
- *表格子类型（核心 2 类）*：
414
- | Sketch 特征 | 推断结果 | 依据 |
415
- |---|---|---|
416
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
417
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
395
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
418
396
 
419
397
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
420
398
 
package/opencode-extension/skills/szcd-component-helper/SKILL.md CHANGED
@@ -61,7 +61,7 @@ compatibility:
61
61
  AI 助手在处理页面生成需求时，必须按以下流程使用工具：
62
62
 
63
63
  ### 步骤1：架构认知 + 需求理解
64
- - 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
64
+ - 调用 `get_architecture_overview(detail="full")` 获取 7 层架构、模板组合模式、全量组件设计元信息（componentSummary）+ styleMapping + assetExtraction，用于后续步骤的组件推理与样式注入
65
65
  - 分析用户需求的页面布局类型、查询字段、操作按钮、表格列等
66
66
 
67
67
  ### 步骤2：组件发现（优先语义搜索）
@@ -93,17 +93,13 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
93
93
  → get_component_full_profile(批量) → 编码
94
94
  ```
95
95
 
96
- **Sketch 结构 → 组件映射规则**：
97
- | Sketch 特征 | 推断结果 | 依据 |
98
- |---|---|---|
99
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
100
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
101
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
102
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
103
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
104
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
105
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
106
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
96
+ **Sketch 结构 → 组件映射依据**：直接查阅步骤 1 `get_architecture_overview(detail="full")` 返回的 `componentSummary` 全量元信息，按以下顺序反查组件：
97
+ 1. **大区切分** → `componentSummary.other` 中 `layoutRole === '页面定位'`（如 TemplateMode），结合 `variantProps.templateType` 和 `templatePatterns` 选模板
98
+ 2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack 等），按 `useCases` 匹配 Sketch 区域语义
99
+ 3. **图表** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`
100
+ 4. **变体** → `variantProps` 配合 `useCases` 区分子类型
101
+
102
+ `componentSummary` 由组件库源码动态扫描生成，是唯一可信源；不要依赖任何硬编码 Sketch→组件对照表。
107
103
 
108
104
  **提示**：
109
105
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
@@ -204,7 +200,10 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
204
200
  #### 4. get_architecture_overview
205
201
  **功能**：查看 7 层架构（AntD→Cover→Wrapper→ProPackage→复合组件→模板）、层级关系和推荐使用顺序。含 LLM 映射修正提示。
206
202
  **参数**：
207
- - `detail` (enum, optional, default: "summary"): summary=层级概览+模板模式+LLM提示；full=含所有层组件列表详情
203
+ - `detail` (enum, optional, default: "summary"):
204
+ - `summary`：层级概览 + 模板模式 + LLM 提示（轻量，~2K tokens）
205
+ - `full`：在 summary 基础上附加 `componentSummary`（全量组件清单 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层另含 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射 + 注入机制 + 选择器表）+ `assetExtraction`（位图/图标/图表色提取规则）。设计稿 → 代码场景必选 full
206
+ - `decisions`：含架构决策记录
208
207
 
209
208
  ### Props 深度解析工具
210
209
 
package/opencode-extension/skills/szcd-design-to-code/SKILL.md CHANGED
@@ -34,12 +34,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
34
34
 
35
35
  ### 步骤1：架构认知（必做）
36
36
 
37
- 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
37
+ 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="full"）一次性获取：
38
38
  - `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
39
39
  - `llmMappingHints.commonMistakes`：LLM 常见映射错误
40
40
  - `recommendedUsageOrder`：推荐使用顺序
41
+ - **`componentSummary`**：全量组件清单（cover/wrappers/proPackages/other/echarts），每个组件附带 `layoutRole`（页面定位/区域容器/可视化等）、`variantProps`（关键 variant 参数）、`styleInjection`（样式注入入口）、`useCases`（典型场景）；other/echarts 层还附带 `compositionSlots`、`requiredHooks`、`chartType`、`sketchSignals` 等元信息——LLM 据此推理组件候选
42
+ - **`styleMapping`**：节点样式 → 组件样式的映射规则（nodeStyleRules / injectionMechanisms / selectorMap）
43
+ - **`assetExtraction`**：图标/位图/图表色提取规则（bitmapRules / iconWorkflow / chartColorMapping）
41
44
 
42
- 根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
45
+ 根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板，并在步骤 3.5 用 `componentSummary` 推理组件候选列表。
43
46
 
44
47
  ### 步骤2：理解需求（必做）
45
48
 
@@ -115,11 +118,49 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
115
118
 
116
119
  **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
117
120
 
121
+ #### 🔒 资源优先级铁律（必读，违反则直接重做本步骤）
122
+
123
+ 代码中的每一处图标、背景、装饰资源，必须按以下优先级**依次尝试**，前一级能命中就**不许跳到下一级**：
124
+
125
+ | 优先级 | 来源 | 适用判定 | 渲染产物 |
126
+ |---|---|---|---|
127
+ | **P0** | **sketch 自带 bitmap** | 节点是 `type=bitmap` | `extractBitmaps` 返回的 `siblingsAfterMe + position + nodeSize` 三维判定渲染产物：区域背景图 / 行内图标 / 独立装饰插图（详见下方表 6） |
128
+ | **P1** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
129
+ | **P2** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
130
+ | **P3** | **antd 图标语义匹配** | 上面三级都失败：shapeGroup 无法直出、节点名无 iconfont 匹配 | `<XxxOutlined />` 按 contextTable 选语义最近的 antd 图标 |
131
+ | **P4** | **纯 CSS / div 渲染** | 上面四级全部失败，且元素是几何/色块（非图标语义） | `<div style={{...}}>` |
132
+
133
+ **禁止行为（违反 = 重做）**：
134
+ - ❌ sketch 里有 bitmap 节点，却用 `<div style={{backgroundColor}}>` 模拟（必须 P0 提取真图）
135
+ - ❌ shapePath 节点直接降级 antd 图标，没跑过 `matchIconFromName`（跳过 P1）
136
+ - ❌ 凭节点名"猜"语义就选 antd 图标，没看 parent 上下文（contextTable 在 `assetExtraction.iconWorkflow.contextTable`）
137
+ - ❌ 把 P0 提取出的 base64 写成 hardcoded url 而非 inline data URI（资源会丢）
138
+
139
+ **前置自检**：步骤 1 拿到的 `assetExtraction.bitmapRules` + `assetExtraction.iconWorkflow` 是上述铁律的服务端权威定义；本步开始前必须已加载，否则回到步骤 1 调 `get_architecture_overview(detail="full")`。
140
+
118
141
  **工具调用**：
119
142
 
120
143
  1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
121
- - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
122
- - 位图资源用于 CSS `background-image` 引用
144
+ - 返回（v1.7.0+）：`{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName, position:{x,y}, nodeSize:{width,height}, parentId, parent:{id,name,type,size}, siblingsBeforeMe:[...], siblingsAfterMe:[...] }] }`
145
+ - **`siblingsAfterMe` 是 z-order 渲染在 bitmap 上方的兄弟节点**（Sketch `layers[]` 排在它之后的项），是判定"区域背景图 vs 独立装饰"的核心信号
146
+ - **不要再为每个 bitmap 单独跑 `getNodeInfo` 拿 position/parent**，这些字段在 extractBitmaps 返回里已有
147
+
148
+ ##### 表 6：bitmap 用途判定与代码落地（必做）
149
+
150
+ 每个 bitmap 都要按本表归类，**只看 `siblingsAfterMe` + `position` + `nodeSize/parent.size`**，不要凭名字猜。判定后必须落到代码（详见经验 9 的"资源落地校验"）。
151
+
152
+ | # | 判定信号（联合判断） | 用途 | 代码落地方式 |
153
+ |---|---|---|---|
154
+ | 1 | `siblingsAfterMe.length > 0` **且** `nodeSize.width / parent.size.width >= 0.7` | **区域背景图**（容器底图，内容元素叠在上面） | `parent` 包一层 wrapper div，bitmap 作为 wrapper 的 `style={{backgroundImage:` `url(data:image/png;base64,${base64})` `, backgroundSize:'cover'}}`；`siblingsAfterMe` 作为 wrapper 子节点正常渲染 |
155
+ | 2 | `nodeSize.width <= 32 && nodeSize.height <= 32` **且** 同 parent 内有 text 兄弟（`siblingsBeforeMe + siblingsAfterMe` 含 text） | **行内图标**（表格行图标、按钮前缀图标等） | `<img src={`data:image/png;base64,${base64}`} style={{width:N,height:N}} />` 替换原本的 `<IconfontWapper>` 占位 |
156
+ | 3 | `siblingsAfterMe.length === 0 && siblingsBeforeMe.length === 0`（独占父容器） | **独立装饰插图**（占位图、空状态图等） | `<img src={`data:image/png;base64,${base64}`} style={{width:nodeSize.width,height:nodeSize.height}} />` 走文档流 |
157
+ | 4 | `siblingsAfterMe.length > 0` **但** 占父宽 < 70% | **嵌入式插图**（区域内某子块的背景） | 同 #1，但 wrapper 是该子块而非整个 parent；定位用 `position:'absolute', top:position.y, left:position.x` |
158
+
159
+ **反例（违反 = 重做）**：
160
+ - ❌ 把 #1 区域背景图渲染为独立 `<img>`（反馈 #14 的 `未编目资源` 493×64 y=52 错例）——丢失"内容叠在底图上"的视觉关系
161
+ - ❌ 把 #2 行内图标用 `backgroundImage` 写在 `<div>` 上——`<div>` 没设宽高就塌缩；用 `<img>` 自带尺寸更稳
162
+ - ❌ 同一 imageRef 多个 nodeId 引用，extractBitmaps 多次调用——只调一次（按 nodeId 列表去重前判断 `fileName`），渲染时复用 base64 引用
163
+
123
164
  2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库（v1.5.0+ 评分制）
124
165
  - 输入 shapePath 节点名列表（如 `["表 icon", "新建文件夹", "编组11备份"]`）
125
166
  - **评分机制**：compoundIcons 强映射 +100、keyword 精确 +20、keyword 包含 +10、semanticTag +3
@@ -239,6 +280,8 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
239
280
 
240
281
  识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
241
282
 
283
+ **图表组件类型选择**：参考步骤 1 返回的 `componentSummary.echarts`，每项含 `chartType`（line/bar/pie 等）和 `sketchSignals`（典型 Sketch 特征），按 sketchSignals 反查 chartType 即可锁定组件名（如 `Line` / `Bar` / `Pie`）。
284
+
242
285
  **经验7：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
243
286
  - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
244
287
  - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
@@ -255,6 +298,23 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
255
298
  - 若必须用 CSS class，类名要能反向追到 Sketch 节点（如 `.segmentBlock-blue` 而非 `.beforebg`），且 class 内容必须**精确等于** rectangle 的 fill/border
256
299
  - 反例排查：写完代码后 grep 一下 CSS class 名，出现 `.bg1/.box2/.before*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
257
300
 
301
+ **经验9：bitmap 资源落地校验（每张 PNG 必须对应一处代码引用）**
302
+
303
+ 实战教训（反馈 #14，2026-06-15）：`未编目资源` bitmap（493×64, y=52）首版被渲染为独立 `<img>` 装饰插图，实际上它是 64px 高统计区域的底图（`siblingsAfterMe` 含 7 个 text/rect 内容元素叠在上面）。9 张 PNG 资源拿到了 base64，但其中 1 张用错位置——这种"提取了但用错"的回退比"忘记提取"更隐蔽。
304
+
305
+ **校验流程（写代码后必跑）**：
306
+
307
+ 1. 把 `extractBitmaps` 返回的每个 `bitmap` 按表 6 归类，列出"用途清单"（区域背景 N 个、行内图标 N 个、独立装饰 N 个）
308
+ 2. 在生成的代码里 grep `data:image/png;base64`，统计实际引用数 ≥ 用途清单总数（去重后）
309
+ 3. 对每个 #1 区域背景图核对：是否真的写在 wrapper div 的 `style.backgroundImage` 上？wrapper 内部是否包含 `siblingsAfterMe` 列出的子节点？
310
+ 4. 对每个 #2 行内图标核对：原本在该位置的 `<IconfontWapper>` / antd 图标是否已被 `<img>` 替换？
311
+ 5. 对每个 #3 独立装饰核对：是否在 parent 的纵向流中出现？
312
+
313
+ **反例（违反 = 重做）**：
314
+ - ❌ extractBitmaps 拿到 9 张 PNG，代码里只 grep 出 8 个 `data:image/png;base64` 引用——必有 1 张被丢
315
+ - ❌ #1 区域背景图被错放成独立 `<img>`，导致 `siblingsAfterMe` 的内容元素失去底图衬托（这是反馈 #14 的具体回退）
316
+ - ❌ 同 imageRef 多次出现（如 `文件备份2/3/4` 复用同一 PNG），代码生成了 N 份 base64 字符串而非引用同一个常量——文件大小翻倍
317
+
258
318
  ### 步骤2.6：布局推理（必做，写代码前的最后一道关）
259
319
 
260
320
  ⚠️ 这一步专治"数据全拿到却放错位置"。反馈 #11 的 5 处错位全部由跳过此步骤导致。
@@ -391,23 +451,14 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
391
451
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
392
452
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
393
453
 
394
- **推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
395
-
396
- | Sketch 特征 | 推断组件 |
397
- |---|---|
398
- | 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
399
- | 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
400
- | 左侧窄区域 + 树形图层 | `LeftTree` |
401
- | 顶部输入框/下拉框/日期选择器 | `Query` |
402
- | 中间表头 + 数据行图层 | `TableOrList` |
403
- | 弹窗/抽屉图层 | `ModelOrDrawer` |
404
- | 页面标题 + 返回箭头 | `TitleAndBack` |
405
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
406
- | 卡片列表 | `TableOrList(componentType="ProList")` |
407
- | 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
408
- | 折线趋势图 | `Line` |
409
- | 柱状对比图 | `Bar` |
410
- | 饼图/环形图 | `Pie` |
454
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录，每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
455
+
456
+ 1. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（TemplateMode）匹配 `templateType` 变体
457
+ 2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer 等），按 `useCases` 描述匹配 Sketch 区域语义
458
+ 3. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
459
+ 4. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
460
+
461
+ 不要再依赖任何硬编码映射表——`componentSummary` 由组件库源码动态生成，是唯一可信源。
411
462
 
412
463
  ### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
413
464
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@szc-ft/mcp-szcd-client",
3
- "version": "0.26.0",
3
+ "version": "0.27.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
@@ -38,7 +38,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
38
38
  **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
39
39
 
40
40
  执行动作：
41
- 1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
41
+ 1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
42
42
  2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
43
43
  3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
44
44
 
@@ -366,6 +366,7 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
366
366
 
367
367
  **输入**：
368
368
  - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
369
+ - 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
369
370
  - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
370
371
  - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
371
372
  - 或步骤 3 的图片分析描述
@@ -379,38 +380,15 @@ szcd 是基于 Ant Design 5.27 封装的企业级 React 组件库，采用分层
379
380
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
380
381
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
381
382
 
382
- **推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
383
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
383
384
 
384
- *页面级布局*：
385
- | Sketch 特征 | 推断结果 | 依据 |
386
- |---|---|---|
387
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
388
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
389
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
390
- | 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
385
+ 1. **画板名称** → 直接作为 `pageName`
386
+ 2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
387
+ 3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
388
+ 4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
389
+ 5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
391
390
 
392
- *区域级组件*：
393
- | Sketch 特征 | 推断结果 | 依据 |
394
- |---|---|---|
395
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
396
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
397
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
398
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
399
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
400
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
401
-
402
- *数据可视化（核心 3 类）*：
403
- | Sketch 特征 | 推断结果 | 依据 |
404
- |---|---|---|
405
- | 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
406
- | 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
407
- | 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
408
-
409
- *表格子类型（核心 2 类）*：
410
- | Sketch 特征 | 推断结果 | 依据 |
411
- |---|---|---|
412
- | 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
413
- | 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
391
+ 不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
414
392
 
415
393
  #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
416
394
 
package/qwen-extension/qwen-extension.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "szcd-component-helper",
3
- "version": "0.26.0",
3
+ "version": "0.27.0",
4
4
  "description": "szcd 组件库 MCP 助手 — 查询组件信息、匹配需求、生成代码",
5
5
  "mcpServers": {
6
6
  "szcd-component-helper": {
package/qwen-extension/skills/szcd-component-helper/SKILL.md CHANGED
@@ -61,7 +61,7 @@ compatibility:
61
61
  AI 助手在处理页面生成需求时，必须按以下流程使用工具：
62
62
 
63
63
  ### 步骤1：架构认知 + 需求理解
64
- - 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
64
+ - 调用 `get_architecture_overview(detail="full")` 获取 7 层架构、模板组合模式、全量组件设计元信息（componentSummary）+ styleMapping + assetExtraction，用于后续步骤的组件推理与样式注入
65
65
  - 分析用户需求的页面布局类型、查询字段、操作按钮、表格列等
66
66
 
67
67
  ### 步骤2：组件发现（优先语义搜索）
@@ -93,17 +93,13 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
93
93
  → get_component_full_profile(批量) → 编码
94
94
  ```
95
95
 
96
- **Sketch 结构 → 组件映射规则**：
97
- | Sketch 特征 | 推断结果 | 依据 |
98
- |---|---|---|
99
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
100
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
101
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
102
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
103
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
104
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
105
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
106
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
96
+ **Sketch 结构 → 组件映射依据**：直接查阅步骤 1 `get_architecture_overview(detail="full")` 返回的 `componentSummary` 全量元信息，按以下顺序反查组件：
97
+ 1. **大区切分** → `componentSummary.other` 中 `layoutRole === '页面定位'`（如 TemplateMode），结合 `variantProps.templateType` 和 `templatePatterns` 选模板
98
+ 2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack 等），按 `useCases` 匹配 Sketch 区域语义
99
+ 3. **图表** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`
100
+ 4. **变体** → `variantProps` 配合 `useCases` 区分子类型
101
+
102
+ `componentSummary` 由组件库源码动态扫描生成，是唯一可信源；不要依赖任何硬编码 Sketch→组件对照表。
107
103
 
108
104
  **提示**：
109
105
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
@@ -204,7 +200,10 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
204
200
  #### 4. get_architecture_overview
205
201
  **功能**：查看 7 层架构（AntD→Cover→Wrapper→ProPackage→复合组件→模板）、层级关系和推荐使用顺序。含 LLM 映射修正提示。
206
202
  **参数**：
207
- - `detail` (enum, optional, default: "summary"): summary=层级概览+模板模式+LLM提示；full=含所有层组件列表详情
203
+ - `detail` (enum, optional, default: "summary"):
204
+ - `summary`：层级概览 + 模板模式 + LLM 提示（轻量，~2K tokens）
205
+ - `full`：在 summary 基础上附加 `componentSummary`（全量组件清单 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层另含 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射 + 注入机制 + 选择器表）+ `assetExtraction`（位图/图标/图表色提取规则）。设计稿 → 代码场景必选 full
206
+ - `decisions`：含架构决策记录
208
207
 
209
208
  ### Props 深度解析工具
210
209
 
package/qwen-extension/skills/szcd-design-to-code/SKILL.md CHANGED
@@ -34,12 +34,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
34
34
 
35
35
  ### 步骤1：架构认知（必做）
36
36
 
37
- 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
37
+ 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="full"）一次性获取：
38
38
  - `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
39
39
  - `llmMappingHints.commonMistakes`：LLM 常见映射错误
40
40
  - `recommendedUsageOrder`：推荐使用顺序
41
+ - **`componentSummary`**：全量组件清单（cover/wrappers/proPackages/other/echarts），每个组件附带 `layoutRole`（页面定位/区域容器/可视化等）、`variantProps`（关键 variant 参数）、`styleInjection`（样式注入入口）、`useCases`（典型场景）；other/echarts 层还附带 `compositionSlots`、`requiredHooks`、`chartType`、`sketchSignals` 等元信息——LLM 据此推理组件候选
42
+ - **`styleMapping`**：节点样式 → 组件样式的映射规则（nodeStyleRules / injectionMechanisms / selectorMap）
43
+ - **`assetExtraction`**：图标/位图/图表色提取规则（bitmapRules / iconWorkflow / chartColorMapping）
41
44
 
42
- 根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
45
+ 根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板，并在步骤 3.5 用 `componentSummary` 推理组件候选列表。
43
46
 
44
47
  ### 步骤2：理解需求（必做）
45
48
 
@@ -115,11 +118,49 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
115
118
 
116
119
  **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
117
120
 
121
+ #### 🔒 资源优先级铁律（必读，违反则直接重做本步骤）
122
+
123
+ 代码中的每一处图标、背景、装饰资源，必须按以下优先级**依次尝试**，前一级能命中就**不许跳到下一级**：
124
+
125
+ | 优先级 | 来源 | 适用判定 | 渲染产物 |
126
+ |---|---|---|---|
127
+ | **P0** | **sketch 自带 bitmap** | 节点是 `type=bitmap` | `extractBitmaps` 返回的 `siblingsAfterMe + position + nodeSize` 三维判定渲染产物：区域背景图 / 行内图标 / 独立装饰插图（详见下方表 6） |
128
+ | **P1** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
129
+ | **P2** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
130
+ | **P3** | **antd 图标语义匹配** | 上面三级都失败：shapeGroup 无法直出、节点名无 iconfont 匹配 | `<XxxOutlined />` 按 contextTable 选语义最近的 antd 图标 |
131
+ | **P4** | **纯 CSS / div 渲染** | 上面四级全部失败，且元素是几何/色块（非图标语义） | `<div style={{...}}>` |
132
+
133
+ **禁止行为（违反 = 重做）**：
134
+ - ❌ sketch 里有 bitmap 节点，却用 `<div style={{backgroundColor}}>` 模拟（必须 P0 提取真图）
135
+ - ❌ shapePath 节点直接降级 antd 图标，没跑过 `matchIconFromName`（跳过 P1）
136
+ - ❌ 凭节点名"猜"语义就选 antd 图标，没看 parent 上下文（contextTable 在 `assetExtraction.iconWorkflow.contextTable`）
137
+ - ❌ 把 P0 提取出的 base64 写成 hardcoded url 而非 inline data URI（资源会丢）
138
+
139
+ **前置自检**：步骤 1 拿到的 `assetExtraction.bitmapRules` + `assetExtraction.iconWorkflow` 是上述铁律的服务端权威定义；本步开始前必须已加载，否则回到步骤 1 调 `get_architecture_overview(detail="full")`。
140
+
118
141
  **工具调用**：
119
142
 
120
143
  1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
121
- - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
122
- - 位图资源用于 CSS `background-image` 引用
144
+ - 返回（v1.7.0+）：`{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName, position:{x,y}, nodeSize:{width,height}, parentId, parent:{id,name,type,size}, siblingsBeforeMe:[...], siblingsAfterMe:[...] }] }`
145
+ - **`siblingsAfterMe` 是 z-order 渲染在 bitmap 上方的兄弟节点**（Sketch `layers[]` 排在它之后的项），是判定"区域背景图 vs 独立装饰"的核心信号
146
+ - **不要再为每个 bitmap 单独跑 `getNodeInfo` 拿 position/parent**，这些字段在 extractBitmaps 返回里已有
147
+
148
+ ##### 表 6：bitmap 用途判定与代码落地（必做）
149
+
150
+ 每个 bitmap 都要按本表归类，**只看 `siblingsAfterMe` + `position` + `nodeSize/parent.size`**，不要凭名字猜。判定后必须落到代码（详见经验 9 的"资源落地校验"）。
151
+
152
+ | # | 判定信号（联合判断） | 用途 | 代码落地方式 |
153
+ |---|---|---|---|
154
+ | 1 | `siblingsAfterMe.length > 0` **且** `nodeSize.width / parent.size.width >= 0.7` | **区域背景图**（容器底图，内容元素叠在上面） | `parent` 包一层 wrapper div，bitmap 作为 wrapper 的 `style={{backgroundImage:` `url(data:image/png;base64,${base64})` `, backgroundSize:'cover'}}`；`siblingsAfterMe` 作为 wrapper 子节点正常渲染 |
155
+ | 2 | `nodeSize.width <= 32 && nodeSize.height <= 32` **且** 同 parent 内有 text 兄弟（`siblingsBeforeMe + siblingsAfterMe` 含 text） | **行内图标**（表格行图标、按钮前缀图标等） | `<img src={`data:image/png;base64,${base64}`} style={{width:N,height:N}} />` 替换原本的 `<IconfontWapper>` 占位 |
156
+ | 3 | `siblingsAfterMe.length === 0 && siblingsBeforeMe.length === 0`（独占父容器） | **独立装饰插图**（占位图、空状态图等） | `<img src={`data:image/png;base64,${base64}`} style={{width:nodeSize.width,height:nodeSize.height}} />` 走文档流 |
157
+ | 4 | `siblingsAfterMe.length > 0` **但** 占父宽 < 70% | **嵌入式插图**（区域内某子块的背景） | 同 #1，但 wrapper 是该子块而非整个 parent；定位用 `position:'absolute', top:position.y, left:position.x` |
158
+
159
+ **反例（违反 = 重做）**：
160
+ - ❌ 把 #1 区域背景图渲染为独立 `<img>`（反馈 #14 的 `未编目资源` 493×64 y=52 错例）——丢失"内容叠在底图上"的视觉关系
161
+ - ❌ 把 #2 行内图标用 `backgroundImage` 写在 `<div>` 上——`<div>` 没设宽高就塌缩；用 `<img>` 自带尺寸更稳
162
+ - ❌ 同一 imageRef 多个 nodeId 引用，extractBitmaps 多次调用——只调一次（按 nodeId 列表去重前判断 `fileName`），渲染时复用 base64 引用
163
+
123
164
  2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库（v1.5.0+ 评分制）
124
165
  - 输入 shapePath 节点名列表（如 `["表 icon", "新建文件夹", "编组11备份"]`）
125
166
  - **评分机制**：compoundIcons 强映射 +100、keyword 精确 +20、keyword 包含 +10、semanticTag +3
@@ -239,6 +280,8 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
239
280
 
240
281
  识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
241
282
 
283
+ **图表组件类型选择**：参考步骤 1 返回的 `componentSummary.echarts`，每项含 `chartType`（line/bar/pie 等）和 `sketchSignals`（典型 Sketch 特征），按 sketchSignals 反查 chartType 即可锁定组件名（如 `Line` / `Bar` / `Pie`）。
284
+
242
285
  **经验7：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
243
286
  - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
244
287
  - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
@@ -255,6 +298,23 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
255
298
  - 若必须用 CSS class，类名要能反向追到 Sketch 节点（如 `.segmentBlock-blue` 而非 `.beforebg`），且 class 内容必须**精确等于** rectangle 的 fill/border
256
299
  - 反例排查：写完代码后 grep 一下 CSS class 名，出现 `.bg1/.box2/.before*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
257
300
 
301
+ **经验9：bitmap 资源落地校验（每张 PNG 必须对应一处代码引用）**
302
+
303
+ 实战教训（反馈 #14，2026-06-15）：`未编目资源` bitmap（493×64, y=52）首版被渲染为独立 `<img>` 装饰插图，实际上它是 64px 高统计区域的底图（`siblingsAfterMe` 含 7 个 text/rect 内容元素叠在上面）。9 张 PNG 资源拿到了 base64，但其中 1 张用错位置——这种"提取了但用错"的回退比"忘记提取"更隐蔽。
304
+
305
+ **校验流程（写代码后必跑）**：
306
+
307
+ 1. 把 `extractBitmaps` 返回的每个 `bitmap` 按表 6 归类，列出"用途清单"（区域背景 N 个、行内图标 N 个、独立装饰 N 个）
308
+ 2. 在生成的代码里 grep `data:image/png;base64`，统计实际引用数 ≥ 用途清单总数（去重后）
309
+ 3. 对每个 #1 区域背景图核对：是否真的写在 wrapper div 的 `style.backgroundImage` 上？wrapper 内部是否包含 `siblingsAfterMe` 列出的子节点？
310
+ 4. 对每个 #2 行内图标核对：原本在该位置的 `<IconfontWapper>` / antd 图标是否已被 `<img>` 替换？
311
+ 5. 对每个 #3 独立装饰核对：是否在 parent 的纵向流中出现？
312
+
313
+ **反例（违反 = 重做）**：
314
+ - ❌ extractBitmaps 拿到 9 张 PNG，代码里只 grep 出 8 个 `data:image/png;base64` 引用——必有 1 张被丢
315
+ - ❌ #1 区域背景图被错放成独立 `<img>`，导致 `siblingsAfterMe` 的内容元素失去底图衬托（这是反馈 #14 的具体回退）
316
+ - ❌ 同 imageRef 多次出现（如 `文件备份2/3/4` 复用同一 PNG），代码生成了 N 份 base64 字符串而非引用同一个常量——文件大小翻倍
317
+
258
318
  ### 步骤2.6：布局推理（必做，写代码前的最后一道关）
259
319
 
260
320
  ⚠️ 这一步专治"数据全拿到却放错位置"。反馈 #11 的 5 处错位全部由跳过此步骤导致。
@@ -391,23 +451,14 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
391
451
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
392
452
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
393
453
 
394
- **推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
395
-
396
- | Sketch 特征 | 推断组件 |
397
- |---|---|
398
- | 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
399
- | 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
400
- | 左侧窄区域 + 树形图层 | `LeftTree` |
401
- | 顶部输入框/下拉框/日期选择器 | `Query` |
402
- | 中间表头 + 数据行图层 | `TableOrList` |
403
- | 弹窗/抽屉图层 | `ModelOrDrawer` |
404
- | 页面标题 + 返回箭头 | `TitleAndBack` |
405
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
406
- | 卡片列表 | `TableOrList(componentType="ProList")` |
407
- | 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
408
- | 折线趋势图 | `Line` |
409
- | 柱状对比图 | `Bar` |
410
- | 饼图/环形图 | `Pie` |
454
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录，每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
455
+
456
+ 1. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（TemplateMode）匹配 `templateType` 变体
457
+ 2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer 等），按 `useCases` 描述匹配 Sketch 区域语义
458
+ 3. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
459
+ 4. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
460
+
461
+ 不要再依赖任何硬编码映射表——`componentSummary` 由组件库源码动态生成，是唯一可信源。
411
462
 
412
463
  ### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
413
464
 
package/standard-skill/szcd-component-helper/SKILL.md CHANGED
@@ -61,7 +61,7 @@ compatibility:
61
61
  AI 助手在处理页面生成需求时，必须按以下流程使用工具：
62
62
 
63
63
  ### 步骤1：架构认知 + 需求理解
64
- - 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
64
+ - 调用 `get_architecture_overview(detail="full")` 获取 7 层架构、模板组合模式、全量组件设计元信息（componentSummary）+ styleMapping + assetExtraction，用于后续步骤的组件推理与样式注入
65
65
  - 分析用户需求的页面布局类型、查询字段、操作按钮、表格列等
66
66
 
67
67
  ### 步骤2：组件发现（优先语义搜索）
@@ -93,17 +93,13 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
93
93
  → get_component_full_profile(批量) → 编码
94
94
  ```
95
95
 
96
- **Sketch 结构 → 组件映射规则**：
97
- | Sketch 特征 | 推断结果 | 依据 |
98
- |---|---|---|
99
- | 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
100
- | 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
101
- | 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
102
- | 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
103
- | 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
104
- | 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
105
- | 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
106
- | 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
96
+ **Sketch 结构 → 组件映射依据**：直接查阅步骤 1 `get_architecture_overview(detail="full")` 返回的 `componentSummary` 全量元信息，按以下顺序反查组件：
97
+ 1. **大区切分** → `componentSummary.other` 中 `layoutRole === '页面定位'`（如 TemplateMode），结合 `variantProps.templateType` 和 `templatePatterns` 选模板
98
+ 2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack 等），按 `useCases` 匹配 Sketch 区域语义
99
+ 3. **图表** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`
100
+ 4. **变体** → `variantProps` 配合 `useCases` 区分子类型
101
+
102
+ `componentSummary` 由组件库源码动态扫描生成，是唯一可信源；不要依赖任何硬编码 Sketch→组件对照表。
107
103
 
108
104
  **提示**：
109
105
  - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
@@ -204,7 +200,10 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
204
200
  #### 4. get_architecture_overview
205
201
  **功能**：查看 7 层架构（AntD→Cover→Wrapper→ProPackage→复合组件→模板）、层级关系和推荐使用顺序。含 LLM 映射修正提示。
206
202
  **参数**：
207
- - `detail` (enum, optional, default: "summary"): summary=层级概览+模板模式+LLM提示；full=含所有层组件列表详情
203
+ - `detail` (enum, optional, default: "summary"):
204
+ - `summary`：层级概览 + 模板模式 + LLM 提示（轻量，~2K tokens）
205
+ - `full`：在 summary 基础上附加 `componentSummary`（全量组件清单 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层另含 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射 + 注入机制 + 选择器表）+ `assetExtraction`（位图/图标/图表色提取规则）。设计稿 → 代码场景必选 full
206
+ - `decisions`：含架构决策记录
208
207
 
209
208
  ### Props 深度解析工具
210
209
 
package/standard-skill/szcd-design-to-code/SKILL.md CHANGED
@@ -34,12 +34,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
34
34
 
35
35
  ### 步骤1：架构认知（必做）
36
36
 
37
- 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
37
+ 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="full"）一次性获取：
38
38
  - `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
39
39
  - `llmMappingHints.commonMistakes`：LLM 常见映射错误
40
40
  - `recommendedUsageOrder`：推荐使用顺序
41
+ - **`componentSummary`**：全量组件清单（cover/wrappers/proPackages/other/echarts），每个组件附带 `layoutRole`（页面定位/区域容器/可视化等）、`variantProps`（关键 variant 参数）、`styleInjection`（样式注入入口）、`useCases`（典型场景）；other/echarts 层还附带 `compositionSlots`、`requiredHooks`、`chartType`、`sketchSignals` 等元信息——LLM 据此推理组件候选
42
+ - **`styleMapping`**：节点样式 → 组件样式的映射规则（nodeStyleRules / injectionMechanisms / selectorMap）
43
+ - **`assetExtraction`**：图标/位图/图表色提取规则（bitmapRules / iconWorkflow / chartColorMapping）
41
44
 
42
- 根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
45
+ 根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板，并在步骤 3.5 用 `componentSummary` 推理组件候选列表。
43
46
 
44
47
  ### 步骤2：理解需求（必做）
45
48
 
@@ -115,11 +118,50 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
115
118
 
116
119
  **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
117
120
 
121
+ #### 🔒 资源优先级铁律（必读，违反则直接重做本步骤）
122
+
123
+ 代码中的每一处图标、背景、装饰资源，必须按以下优先级**依次尝试**，前一级能命中就**不许跳到下一级**：
124
+
125
+ | 优先级 | 来源 | 适用判定 | 渲染产物 |
126
+ |---|---|---|---|
127
+ | **P0** | **sketch 自带 bitmap** | 节点是 `type=bitmap` | `extractBitmaps` 返回的 `siblingsAfterMe + position + nodeSize` 三维判定渲染产物：区域背景图 / 行内图标 / 独立装饰插图（详见下方表 6） |
128
+ | **P1** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
129
+ | **P2** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
130
+
131
+ | **P3** | **antd 图标语义匹配** | 上面三级都失败：shapeGroup 无法直出、节点名无 iconfont 匹配 | `<XxxOutlined />` 按 contextTable 选语义最近的 antd 图标 |
132
+ | **P4** | **纯 CSS / div 渲染** | 上面四级全部失败，且元素是几何/色块（非图标语义） | `<div style={{...}}>` |
133
+
134
+ **禁止行为（违反 = 重做）**：
135
+ - ❌ sketch 里有 bitmap 节点，却用 `<div style={{backgroundColor}}>` 模拟（必须 P0 提取真图）
136
+ - ❌ shapePath 节点直接降级 antd 图标，没跑过 `matchIconFromName`（跳过 P1）
137
+ - ❌ 凭节点名"猜"语义就选 antd 图标，没看 parent 上下文（contextTable 在 `assetExtraction.iconWorkflow.contextTable`）
138
+ - ❌ 把 P0 提取出的 base64 写成 hardcoded url 而非 inline data URI（资源会丢）
139
+
140
+ **前置自检**：步骤 1 拿到的 `assetExtraction.bitmapRules` + `assetExtraction.iconWorkflow` 是上述铁律的服务端权威定义；本步开始前必须已加载，否则回到步骤 1 调 `get_architecture_overview(detail="full")`。
141
+
118
142
  **工具调用**：
119
143
 
120
144
  1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
121
- - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
122
- - 位图资源用于 CSS `background-image` 引用
145
+ - 返回（v1.7.0+）：`{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName, position:{x,y}, nodeSize:{width,height}, parentId, parent:{id,name,type,size}, siblingsBeforeMe:[...], siblingsAfterMe:[...] }] }`
146
+ - **`siblingsAfterMe` 是 z-order 渲染在 bitmap 上方的兄弟节点**（Sketch `layers[]` 排在它之后的项），是判定"区域背景图 vs 独立装饰"的核心信号
147
+ - **不要再为每个 bitmap 单独跑 `getNodeInfo` 拿 position/parent**，这些字段在 extractBitmaps 返回里已有
148
+
149
+ ##### 表 6：bitmap 用途判定与代码落地（必做）
150
+
151
+ 每个 bitmap 都要按本表归类，**只看 `siblingsAfterMe` + `position` + `nodeSize/parent.size`**，不要凭名字猜。判定后必须落到代码（详见经验 9 的"资源落地校验"）。
152
+
153
+ | # | 判定信号（联合判断） | 用途 | 代码落地方式 |
154
+ |---|---|---|---|
155
+ | 1 | `siblingsAfterMe.length > 0` **且** `nodeSize.width / parent.size.width >= 0.7` | **区域背景图**（容器底图，内容元素叠在上面） | `parent` 包一层 wrapper div，bitmap 作为 wrapper 的 `style={{backgroundImage:` `url(data:image/png;base64,${base64})` `, backgroundSize:'cover'}}`；`siblingsAfterMe` 作为 wrapper 子节点正常渲染 |
156
+ | 2 | `nodeSize.width <= 32 && nodeSize.height <= 32` **且** 同 parent 内有 text 兄弟（`siblingsBeforeMe + siblingsAfterMe` 含 text） | **行内图标**（表格行图标、按钮前缀图标等） | `<img src={`data:image/png;base64,${base64}`} style={{width:N,height:N}} />` 替换原本的 `<IconfontWapper>` 占位 |
157
+ | 3 | `siblingsAfterMe.length === 0 && siblingsBeforeMe.length === 0`（独占父容器） | **独立装饰插图**（占位图、空状态图等） | `<img src={`data:image/png;base64,${base64}`} style={{width:nodeSize.width,height:nodeSize.height}} />` 走文档流 |
158
+ | 4 | `siblingsAfterMe.length > 0` **但** 占父宽 < 70% | **嵌入式插图**（区域内某子块的背景） | 同 #1，但 wrapper 是该子块而非整个 parent；定位用 `position:'absolute', top:position.y, left:position.x` |
159
+
160
+ **反例（违反 = 重做）**：
161
+ - ❌ 把 #1 区域背景图渲染为独立 `<img>`（反馈 #14 的 `未编目资源` 493×64 y=52 错例）——丢失"内容叠在底图上"的视觉关系
162
+ - ❌ 把 #2 行内图标用 `backgroundImage` 写在 `<div>` 上——`<div>` 没设宽高就塌缩；用 `<img>` 自带尺寸更稳
163
+ - ❌ 同一 imageRef 多个 nodeId 引用，extractBitmaps 多次调用——只调一次（按 nodeId 列表去重前判断 `fileName`），渲染时复用 base64 引用
164
+
123
165
  2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库（v1.5.0+ 评分制）
124
166
  - 输入 shapePath 节点名列表（如 `["表 icon", "新建文件夹", "编组11备份"]`）
125
167
  - **评分机制**：compoundIcons 强映射 +100、keyword 精确 +20、keyword 包含 +10、semanticTag +3
@@ -239,6 +281,8 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
239
281
 
240
282
  识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
241
283
 
284
+ **图表组件类型选择**：参考步骤 1 返回的 `componentSummary.echarts`，每项含 `chartType`（line/bar/pie 等）和 `sketchSignals`（典型 Sketch 特征），按 sketchSignals 反查 chartType 即可锁定组件名（如 `Line` / `Bar` / `Pie`）。
285
+
242
286
  **经验7：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
243
287
  - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
244
288
  - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
@@ -255,6 +299,23 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
255
299
  - 若必须用 CSS class，类名要能反向追到 Sketch 节点（如 `.segmentBlock-blue` 而非 `.beforebg`），且 class 内容必须**精确等于** rectangle 的 fill/border
256
300
  - 反例排查：写完代码后 grep 一下 CSS class 名，出现 `.bg1/.box2/.before*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
257
301
 
302
+ **经验9：bitmap 资源落地校验（每张 PNG 必须对应一处代码引用）**
303
+
304
+ 实战教训（反馈 #14，2026-06-15）：`未编目资源` bitmap（493×64, y=52）首版被渲染为独立 `<img>` 装饰插图，实际上它是 64px 高统计区域的底图（`siblingsAfterMe` 含 7 个 text/rect 内容元素叠在上面）。9 张 PNG 资源拿到了 base64，但其中 1 张用错位置——这种"提取了但用错"的回退比"忘记提取"更隐蔽。
305
+
306
+ **校验流程（写代码后必跑）**：
307
+
308
+ 1. 把 `extractBitmaps` 返回的每个 `bitmap` 按表 6 归类，列出"用途清单"（区域背景 N 个、行内图标 N 个、独立装饰 N 个）
309
+ 2. 在生成的代码里 grep `data:image/png;base64`，统计实际引用数 ≥ 用途清单总数（去重后）
310
+ 3. 对每个 #1 区域背景图核对：是否真的写在 wrapper div 的 `style.backgroundImage` 上？wrapper 内部是否包含 `siblingsAfterMe` 列出的子节点？
311
+ 4. 对每个 #2 行内图标核对：原本在该位置的 `<IconfontWapper>` / antd 图标是否已被 `<img>` 替换？
312
+ 5. 对每个 #3 独立装饰核对：是否在 parent 的纵向流中出现？
313
+
314
+ **反例（违反 = 重做）**：
315
+ - ❌ extractBitmaps 拿到 9 张 PNG，代码里只 grep 出 8 个 `data:image/png;base64` 引用——必有 1 张被丢
316
+ - ❌ #1 区域背景图被错放成独立 `<img>`，导致 `siblingsAfterMe` 的内容元素失去底图衬托（这是反馈 #14 的具体回退）
317
+ - ❌ 同 imageRef 多次出现（如 `文件备份2/3/4` 复用同一 PNG），代码生成了 N 份 base64 字符串而非引用同一个常量——文件大小翻倍
318
+
258
319
  ### 步骤2.6：布局推理（必做，写代码前的最后一道关）
259
320
 
260
321
  ⚠️ 这一步专治"数据全拿到却放错位置"。反馈 #11 的 5 处错位全部由跳过此步骤导致。
@@ -391,23 +452,14 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
391
452
  - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
392
453
  - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
393
454
 
394
- **推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
395
-
396
- | Sketch 特征 | 推断组件 |
397
- |---|---|
398
- | 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
399
- | 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
400
- | 左侧窄区域 + 树形图层 | `LeftTree` |
401
- | 顶部输入框/下拉框/日期选择器 | `Query` |
402
- | 中间表头 + 数据行图层 | `TableOrList` |
403
- | 弹窗/抽屉图层 | `ModelOrDrawer` |
404
- | 页面标题 + 返回箭头 | `TitleAndBack` |
405
- | 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
406
- | 卡片列表 | `TableOrList(componentType="ProList")` |
407
- | 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
408
- | 折线趋势图 | `Line` |
409
- | 柱状对比图 | `Bar` |
410
- | 饼图/环形图 | `Pie` |
455
+ **推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录，每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
456
+
457
+ 1. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（TemplateMode）匹配 `templateType` 变体
458
+ 2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer 等），按 `useCases` 描述匹配 Sketch 区域语义
459
+ 3. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
460
+ 4. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
461
+
462
+ 不要再依赖任何硬编码映射表——`componentSummary` 由组件库源码动态生成，是唯一可信源。
411
463
 
412
464
  ### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
413
465