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

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

@@ -51,7 +51,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 | 工具名 | 功能 | 何时使用 |
 |--------|------|---------|
-| `get_architecture_overview` | 获取7层架构图、模板组合模式、LLM映射错误提示 | 步骤1：架构认知 |
+| `get_architecture_overview` | 获取7层架构图、模板组合模式、LLM映射错误提示。detail=full 额外返回 componentSummary（全量组件+设计元信息：layoutRole/variantProps/styleInjection/useCases/chartType/sketchSignals）+ styleMapping（节点样式映射）+ assetExtraction（图标/位图/图表色提取规则），设计稿→代码场景必选 full | 步骤1：架构认知（设计稿场景用 detail=full 一次拿全） |
 | `search_components_semantic` | 基于Repowiki知识库的语义搜索，用自然语言描述匹配最适合的组件 | 步骤4：语义搜索匹配 |
 | `get_component_full_profile` | 一站式获取组件全景画像。name支持逗号分隔批量查询，depth=deep获取Props链+源码摘要+样式注入，返回值是紧凑Markdown格式 | 步骤4：批量获取全景画像 |
 | `get_best_practices` | 获取组件使用最佳实践和常见错误修正，指定scenario可获取组合最佳实践 | 步骤4：组合最佳实践 |
@@ -86,7 +86,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
 
 执行动作：
-1. 调用 `get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
+1. 调用 `get_architecture_overview`（detail="full"）一次性获取：7 层架构图、模板组合模式、推荐使用顺序、LLM 映射错误提示，**以及 `componentSummary`（全量组件 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射）+ `assetExtraction`（图标/位图/图表色提取规则）**——这些是步骤 3.5 推理组件候选和步骤 5 样式注入的核心依据
 2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
 3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
 
@@ -181,6 +181,27 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 元素归属 | 凭 x/y 坐标判定（"x=272 列都是同区域"） | 看 `getMultipleNodeInfo` 返回的 `parent.id/name` 字段 |
 | 颜色提取 | 跳过 group 只取 text/rectangle | 同批提交 group ID，从 `style.fills` 取渐变背景 |
 
+#### getMultipleNodeInfo 返回字段契约（sketch-mcp-server ≥ v1.6.1）
+
+| 字段 | 适用类型 | 用途 |
+|------|----------|------|
+| `position:{x,y}` + `size:{width,height}` | 全部 | 步骤 2.6 表 1/2/3/4 的坐标推理 |
+| `parent:{id,name,type}` | 全部（顶层除外） | 步骤 2.6 表 1 大区归属、Pass 2 质检 |
+| `style.fills[].{color,gradient}` | rectangle / group / text | 表 5 样式映射 |
+| `style.borders[].{color,thickness}` | rectangle / group | 表 5 样式映射 |
+| `style.shadows[]` | rectangle / group | 表 5 样式映射 |
+| `text.attributes[0].attributes.{fontFamily,fontSize,color,lineHeight}` | text | 字号/字重/颜色（fontFamily 编码字重，如 PingFangSC-Semibold → 600） |
+| `children:[id]` | group / artboard | 推断容器子节点集合（与 parent 反向印证） |
+| `isVisualContainer:bool` | group / artboard | true = 该 group 自身带 fills/borders/shadows，必须作为 UI 容器渲染（不是纯图层分组） |
+| `shape.cornerRadius` | rectangle / oval | 圆角 |
+
+**字段缺失自检**（任一项失败 → sketch-mcp-server 版本过旧，升级到 ≥ v1.6.1 后重跑）：
+
+- [ ] 任取一个 text 节点，`parent.id` 非空 ✅
+- [ ] 任取一个 group 节点，`isVisualContainer` 类型是 boolean、`children` 是数组 ✅
+- [ ] 任取一个 rectangle 节点，`style.fills` 数组存在（即使为空也要是 `[]` 不能 undefined） ✅
+- [ ] 任取一个 text 节点，`text.attributes[0].attributes.fontFamily` 可读出（编码字重） ✅
+
 **实战经验沉淀（重要）**：
 
 **收获 1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
@@ -195,15 +216,20 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
 正确做法：用 `queryNodes(type=["text","rectangle","group"])` 一次拿三类 ID，`getMultipleNodeInfo` 返回的 `parent` 字段直接告诉你归属关系
 
-**收获 3：元素归属必须走 group 父子关系，禁止 x 坐标平面判定**
+**收获 3：归属判定走 x+y+parent 三轴联合，禁止单轴定论（坐标和 parent 互为纠错器）**
 
-实战教训：`'主题'text(x=272,y=149)` 被错误识别为内容区块标题，实际是左侧树标题（与树节点同 x=272 列）。同列坐标不代表同区域。
+实战教训：
+- 反例 A：`'主题'text(x=272,y=149)` 单看 x 在右侧内容区列，但 `parent.name=leftTreeHeader` 强语义 → 归左树（情形 C：parent 修正坐标）
+- 反例 B（反馈 #11）：`'段码含义'text(x=300,y=257)` 坐标落在 `渐变容器(x=240..960, y=189..297)` 内，但 parent 是兄弟编组 `cataMain` → 视觉上属于渐变容器内（情形 B：图层拆开，按坐标渲染）
 
 正确做法：
-- 步骤 2 拿到完整节点树后，先识别顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
-- `getMultipleNodeInfo` v1.5.0+ **自动返回** `parent: { id, name, type }` 字段，按 parent 归属到具体分区
-- "主题"这类标题文本，先看 `parent.name` 是否带 "LeftTree" / "树" / "PageContent" 等容器关键字，不要看 x 坐标
-- 坐标仅作为同 parent 内子元素排序兜底使用
+- 步骤 2.5 第 4 步先 `mode="tree"` 看顶层 group 分区（通常 2-5 个）
+- 步骤 2.6 做双向校验：Pass 1 坐标推假设 → Pass 2 parent 质检 → 四类情形 A/B/C/D 处理
+- 大区归属：`parent.name` 含 `LeftTree/树/PageContent/sidebar/cataMain` 等强语义关键字时优先于 x 分布
+- 容器归属：必须 `x ∈ [容器x, 容器x+w]` **且** `y ∈ [容器y, 容器y+h]`，单轴判定无效
+- 跨分区不比 y；同分区内按 y 升序；同行（y 差<8px）按 x 升序
+
+详细决策矩阵见步骤 2.6。
 
 **收获 4：信息栏/卡片容器必须先取 group 再取子元素**
 
@@ -249,14 +275,129 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 - **兜底方案**：① 用 `extractBitmaps` 提取的 PNG/PDF 资源；② `matchIconFromName` 的 Top-1（若 source=compound）；③ unmatched 时按 parent 上下文 + 上表选 antd `@ant-design/icons` 复合图标；④ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
 
-**提示（sketch-mcp-server v1.5.0+）**：
+**收获 8：rectangle 的 fill/border 必须以内联样式或精确选择器落到 DOM，禁止借用通用 CSS class**
+
+实战教训（反馈 #11）：5 个段码视觉块的颜色（#f2f8fd/#f5ffed/#fffbe6/#f5f6f7）完整地从 rectangle 节点拿到了，但代码却用了 `.beforebg{background:#ebf0ff}` 这种与设计稿无对应关系的通用 class，导致 5 个块颜色全错。
+
+正确做法：
+- 步骤 2.6 的样式映射表（表 5）必须为每个"颜色块"列出 rectangle 数据 → 内联 style 的对应关系
+- 写代码时直接用 `<div style={{background:'#f2f8fd',border:'1px solid #d9eafb'}}>`
+- 若必须用 CSS class，类名要能反向追到 Sketch 节点（如 `.segmentBlock-blue` 而非 `.beforebg`），且 class 内容必须**精确等于** rectangle 的 fill/border
+- 反例排查：写完代码后 grep 一下 CSS class 名，出现 `.bg1/.box2/.before*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
+
+### 步骤2.6：布局推理（必做，写代码前的最后一道关）
+
+⚠️ 这一步专治"数据全拿到却放错位置"。反馈 #11 的 5 处错位全部由跳过此步骤导致。
+
+**核心思路**：x+y 坐标先画"视觉假设"，parent 字段做质检纠错。两套信号**互为纠错器**，不是单方向"谁优先"。
+
+**输入**：步骤 2.5 产出的 `text + rectangle + group` 节点全量数据（含 `position.{x,y}`、`size.{width,height}`、`parent.{id,name,type}`、`style`、`isVisualContainer`）
+
+#### Pass 1：坐标推假设（产出 5 张表）
+
+每张表都必须输出，即使某类节点为空也要写"无"。
+
+##### 表 1：分区识别表（x+y+parent 联合，定大区）
+
+```
+| 节点 name      | x   | y   | parent.name      | 推断分区     | 决策依据                |
+|----------------|-----|-----|------------------|--------------|-------------------------|
+| 主题(text)     | 272 | 149 | leftTreeHeader   | 左树标题区   | parent 强语义压过 x 列  |
+| 段码定义(text) | 320 | 200 | cataMain         | 右侧内容-顶部 | parent 含 PageContent 类语义 |
+```
+
+判定流程：
+1. 按 x 把画板切成 1-3 列（x<300 → 左区、x≥300 → 右区，或按设计稿实际边界）
+2. 用 `parent.name` 校验：含 `LeftTree/树/sidebar/cataMain/PageContent/header/footer` 等关键字时以 parent 为准
+3. 冲突时遵循"收获 3"的 A/B/C/D 矩阵（见下方 Pass 2）
+
+→ 此表输出**布局类型**：UpDown（单列）/ LeftRight（双列）/ LeftMiddleRight（三列）
+
+##### 表 2：纵向顺序表（同分区内按 y）
+
+```
+| 分区       | 节点          | y   | 推断角色          |
+|------------|---------------|-----|-------------------|
+| 右侧内容区 | 段码定义      | 200 | 卡片 1            |
+| 右侧内容区 | Tabs          | 420 | Tabs(type=card)   |
+| 右侧内容区 | 配置说明      | 478 | 卡片 2(Tabs 下方) |
+```
+
+铁律：**同分区内**渲染顺序按 y 升序。跨分区不比 y（左树第 100 行 y 和右内容区第 1 行 y 没有可比性）。
+
+##### 表 3：横向排列表（同行按 x，y 差<8px 视为同行）
+
+```
+| 分区/容器       | 节点         | x   | y   | 推断角色                |
+|-----------------|--------------|-----|-----|-------------------------|
+| Query 操作栏    | 名称输入框   | 320 | 50  | Form.Item col-span=6    |
+| Query 操作栏    | 状态下拉     | 540 | 50  | Form.Item col-span=6    |
+| Query 操作栏    | 查询按钮     | 980 | 50  | 操作按钮(右对齐)        |
+```
+
+判定流程：
+1. y 差<8px 识别同一行
+2. 同行按 x 升序排
+3. 计算 x 间距推算 antd Col span（24 栅格）或 flex
+4. 最右元素若 `x + width` 接近容器右边界 → 右对齐（justify-content: flex-end）
+
+##### 表 4：容器归属表（x+y 双轴边界检测）
+
+仅对 `isVisualContainer === true` 的 group 和带 fill/border 的 rectangle 做检测。
+
+```
+| 容器             | x..x+w   | y..y+h   | 落入子元素                       |
+|------------------|----------|----------|----------------------------------|
+| 渐变容器(group)  | 240..960 | 189..297 | 段码含义(x=300,y=257) ✅          |
+| 段码块-蓝(rect)  | 320..420 | 320..360 | (无子节点，仅样式)               |
+```
+
+判定式：子元素 `x ∈ [容器x, 容器x+w]` **且** `y ∈ [容器y, 容器y+h]` → 渲染在容器内部。**单轴判定无效**。
+
+##### 表 5：样式映射表（rectangle/group fill → UI 组件内联样式）
+
+```
+| Sketch 节点          | 数据来源                 | bg/border                | 映射到代码                                                |
+|----------------------|--------------------------|--------------------------|-----------------------------------------------------------|
+| 段码块-蓝(rectangle) | style.fills[0]/borders[0]| bg #f2f8fd / b #d9eafb   | <div style={{background:'#f2f8fd',border:'1px solid #d9eafb'}}> |
+| 渐变容器(group)      | style.fills[0].gradient  | linear #f3faff→#f8fdff   | <div style={{background:'linear-gradient(180deg,#f3faff,#f8fdff)'}}> |
+| Tab 激活态           | rect bg #fff border #0079f7 | bg #fff / b #0079f7   | Tabs type="card" + .segmentTabs .ant-tabs-tab-active 覆盖 |
+```
+
+铁律（见收获 8）：rectangle 的 fill/border 必须以**内联样式**或精确选择器落到代码，**禁止**用 `.beforebg{background:#ebf0ff}` 这类与设计稿无对应关系的 CSS class。
+
+#### Pass 2：parent 质检（按 A/B/C/D 矩阵处理冲突）
+
+逐行扫表 1，对照 parent 字段：
+
+| 情形 | 坐标判定 | parent 判定 | 处理 |
+|------|----------|-------------|------|
+| A | 在容器 X 内 | parent 链含 X | ✅ 双向一致，直接采用 |
+| B | 在容器 X 内 | parent 是兄弟节点 Y | ⚠️ **视觉容器优先**（设计师把图层拆开了）→ 按坐标渲染到 X 内 |
+| C | 不在容器 X 内 | parent.name 强语义 = X | ⚠️ **parent 优先**（绝对定位/溢出布局）→ 按 parent 归属，加 `position:absolute` 标注 |
+| D | 双向都不落 | parent 是顶层 | 独立元素，按坐标走纵向顺序 |
+
+输出**最终归属表**：在表 1 末尾追加 `情形(A/B/C/D)` 列。
+
+#### Pass 3：自检清单（写代码前必跑）
+
+- [ ] 表 1 是否按 x 分布判定了布局类型（UpDown / LeftRight / LeftMiddleRight）？
+- [ ] 表 2 同分区内是否按 y 排序，没有跨分区比 y？
+- [ ] 表 3 同行元素（y 差<8px）是否按 x 排序，计算了栅格 span 或右对齐？
+- [ ] 表 4 容器归属是否做了 x+y 双轴检测，不是只看一轴？
+- [ ] 表 5 所有"颜色块/卡片/渐变"样式都来自 rectangle/group 的 style.fills/borders，没有出现凭空 CSS class？
+- [ ] Pass 2 冲突行是否标了 A/B/C/D 情形和决策依据？
+
+任一项 ❌ → 回 Pass 1 补；禁止跳到步骤 3 前未输出全部 5 张表 + 最终归属表。
+
+**提示（sketch-mcp-server v1.6.1+）**：
 - 大型 .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 坐标
+- 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部按 100 一批自动分片），无需手动拆分；每个节点自带 `parent: {id,name,type}` 字段 + group/artboard 额外有 `children` 和 `isVisualContainer` —— 步骤 2.6 的双向校验同时用 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`
+- 如果 sketch-mcp-server 工具不可用或版本 < v1.6.1（parent / isVisualContainer 字段缺失），提示用户升级：`npm install -g @szc-ft/sketch-mcp-server@latest`
 
 ### 步骤3：分析设计稿（条件执行）
 
@@ -288,6 +429,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 **输入**：
 - 步骤 1 的 `get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
 - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
 - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
 - 或步骤 3 的图片分析描述
@@ -301,38 +443,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
 - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
 
-**推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
-
-*页面级布局*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
-| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
-| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
-| 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
+**推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
 
-*区域级组件*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
-| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
-| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
-| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
-
-*数据可视化（核心 3 类）*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
-| 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
-| 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
+1. **画板名称** → 直接作为 `pageName`
+2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
+3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
+4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
+5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
 
-*表格子类型（核心 2 类）*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
-| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
+不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
 
 #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
 
@@ -427,10 +546,22 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 组件 | 依赖的 szcd 组件 | 依赖的 hooks |
 |------|-----------------|-------------|
 
+### 布局顺序（来自步骤 2.6 表 2 压缩，按 y 排序）
+[页面级垂直顺序，如：TitleAndBack → 段码定义卡片 → Tabs → 配置说明卡片]
+
+### 关键样式映射（来自步骤 2.6 表 5，仅列非默认样式）
+| UI 元素 | Sketch 数据来源 | 落地方式 |
+|---------|----------------|----------|
+| 段码块×5 | 5 个 rectangle 的 fills[0]/borders[0] | 内联 style |
+| 渐变容器 | group(isVisualContainer) 的 fills[0].gradient | 内联 linear-gradient |
+| Tab 激活态 | rectangle bg #fff border #0079f7 | type="card" + .segmentTabs 覆盖 |
+
 ### 备选方案（如有）
 [说明]
 ```
 
+用户在确认环节即可发现"段码块颜色没列上"或"Tab 样式漏识别"，避免反馈 #11 那样要等代码生成后反复修。
+
 **交互节点**：向用户确认：
 - "以上组件方案是否合适？是否需要调整？"
 - 提供选项：同意方案 / 需要调整 / 换一个方案
@@ -451,6 +582,20 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 - 复合组件配合 TemplateMode 使用实现标准页面布局
 - Hooks 按依赖关系正确引入（如 useLeftTree、useTable）
 
+#### 步骤 6 末尾必做：样式落地校验
+
+代码生成完成后，**逐行核对**步骤 2.6 表 5（样式映射表）的每一项是否真落到代码里：
+
+```
+| 样式映射表行                                | 代码中对应位置                                              | 校验 |
+|---------------------------------------------|-------------------------------------------------------------|------|
+| 段码块-蓝 bg #f2f8fd border #d9eafb         | CreateOrEdit.tsx:L120 `<div style={{background:'#f2f8fd',border:'1px solid #d9eafb'}}>` | ✅ |
+| 渐变容器 linear #f3faff→#f8fdff             | CreateOrEdit.tsx:L98 `style={{background:'linear-gradient(...)'}}` | ✅ |
+| Tab 激活态 bg #fff border #0079f7           | styles.less:L45 `.segmentTabs .ant-tabs-tab-active{...}`    | ✅ |
+```
+
+❌ 如果某行找不到对应代码位置 → 直接补到代码里再继续，**禁止说"代码已生成"前留缺口**。这是反馈 #11"5 个段码块全错"的根因——所有颜色都拿到了，但没逐一回查是否落到了代码上。
+
 
 **交互节点**：代码生成后，询问用户下一步：
 > "代码已生成，你可以选择：

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

@@ -56,7 +56,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 **在正式开始之前，获取项目架构全局视图，同时验证 MCP 连接。**
 
 执行动作：
-1. 调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取7层架构图、模板组合模式、推荐使用顺序和 LLM 映射错误提示
+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 样式注入的核心依据
 2. 如果连接失败，**立即停止并返回错误信息**，告知用户需要先配置 MCP 服务器
 3. 如果成功，根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板
 
@@ -145,6 +145,27 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 元素归属 | 凭 x/y 坐标判定（"x=272 列都是同区域"） | 看 `getMultipleNodeInfo` 返回的 `parent.id/name` 字段 |
 | 颜色提取 | 跳过 group 只取 text/rectangle | 同批提交 group ID，从 `style.fills` 取渐变背景 |
 
+#### getMultipleNodeInfo 返回字段契约（sketch-mcp-server ≥ v1.6.1）
+
+| 字段 | 适用类型 | 用途 |
+|------|----------|------|
+| `position:{x,y}` + `size:{width,height}` | 全部 | 步骤 2.6 表 1/2/3/4 的坐标推理 |
+| `parent:{id,name,type}` | 全部（顶层除外） | 步骤 2.6 表 1 大区归属、Pass 2 质检 |
+| `style.fills[].{color,gradient}` | rectangle / group / text | 表 5 样式映射 |
+| `style.borders[].{color,thickness}` | rectangle / group | 表 5 样式映射 |
+| `style.shadows[]` | rectangle / group | 表 5 样式映射 |
+| `text.attributes[0].attributes.{fontFamily,fontSize,color,lineHeight}` | text | 字号/字重/颜色（fontFamily 编码字重，如 PingFangSC-Semibold → 600） |
+| `children:[id]` | group / artboard | 推断容器子节点集合（与 parent 反向印证） |
+| `isVisualContainer:bool` | group / artboard | true = 该 group 自身带 fills/borders/shadows，必须作为 UI 容器渲染（不是纯图层分组） |
+| `shape.cornerRadius` | rectangle / oval | 圆角 |
+
+**字段缺失自检**（任一项失败 → sketch-mcp-server 版本过旧，升级到 ≥ v1.6.1 后重跑）：
+
+- [ ] 任取一个 text 节点，`parent.id` 非空 ✅
+- [ ] 任取一个 group 节点，`isVisualContainer` 类型是 boolean、`children` 是数组 ✅
+- [ ] 任取一个 rectangle 节点，`style.fills` 数组存在（即使为空也要是 `[]` 不能 undefined） ✅
+- [ ] 任取一个 text 节点，`text.attributes[0].attributes.fontFamily` 可读出（编码字重） ✅
+
 **实战经验沉淀（重要）**：
 
 **收获 1：首轮 `getMultipleNodeInfo` 必须全量拉取，不能挑**
@@ -159,15 +180,20 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 错误做法：先查 text 拿自身样式 → 再根据 parent ID 单独查 rectangle（多走一步）
 正确做法：用 `queryNodes(type=["text","rectangle","group"])` 一次拿三类 ID，`getMultipleNodeInfo` 返回的 `parent` 字段直接告诉你归属关系
 
-**收获 3：元素归属必须走 group 父子关系，禁止 x 坐标平面判定**
+**收获 3：归属判定走 x+y+parent 三轴联合，禁止单轴定论（坐标和 parent 互为纠错器）**
 
-实战教训：`'主题'text(x=272,y=149)` 被错误识别为内容区块标题，实际是左侧树标题（与树节点同 x=272 列）。同列坐标不代表同区域。
+实战教训：
+- 反例 A：`'主题'text(x=272,y=149)` 单看 x 在右侧内容区列，但 `parent.name=leftTreeHeader` 强语义 → 归左树（情形 C：parent 修正坐标）
+- 反例 B（反馈 #11）：`'段码含义'text(x=300,y=257)` 坐标落在 `渐变容器(x=240..960, y=189..297)` 内，但 parent 是兄弟编组 `cataMain` → 视觉上属于渐变容器内（情形 B：图层拆开，按坐标渲染）
 
 正确做法：
-- 步骤 2 拿到完整节点树后，先识别顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
-- `getMultipleNodeInfo` v1.5.0+ **自动返回** `parent: { id, name, type }` 字段，按 parent 归属到具体分区
-- "主题"这类标题文本，先看 `parent.name` 是否带 "LeftTree" / "树" / "PageContent" 等容器关键字，不要看 x 坐标
-- 坐标仅作为同 parent 内子元素排序兜底使用
+- 步骤 2.5 第 4 步先 `mode="tree"` 看顶层 group 分区（通常 2-5 个）
+- 步骤 2.6 做双向校验：Pass 1 坐标推假设 → Pass 2 parent 质检 → 四类情形 A/B/C/D 处理
+- 大区归属：`parent.name` 含 `LeftTree/树/PageContent/sidebar/cataMain` 等强语义关键字时优先于 x 分布
+- 容器归属：必须 `x ∈ [容器x, 容器x+w]` **且** `y ∈ [容器y, 容器y+h]`，单轴判定无效
+- 跨分区不比 y；同分区内按 y 升序；同行（y 差<8px）按 x 升序
+
+详细决策矩阵见步骤 2.6。
 
 **收获 4：信息栏/卡片容器必须先取 group 再取子元素**
 
@@ -213,14 +239,129 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 - **兜底方案**：① 用 `extractBitmaps` 提取的 PNG/PDF 资源；② `matchIconFromName` 的 Top-1（若 source=compound）；③ unmatched 时按 parent 上下文 + 上表选 antd `@ant-design/icons` 复合图标；④ 在代码注释中标注"⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath"
 
-**提示（sketch-mcp-server v1.5.0+）**：
+**收获 8：rectangle 的 fill/border 必须以内联样式或精确选择器落到 DOM，禁止借用通用 CSS class**
+
+实战教训（反馈 #11）：5 个段码视觉块的颜色（#f2f8fd/#f5ffed/#fffbe6/#f5f6f7）完整地从 rectangle 节点拿到了，但代码却用了 `.beforebg{background:#ebf0ff}` 这种与设计稿无对应关系的通用 class，导致 5 个块颜色全错。
+
+正确做法：
+- 步骤 2.6 的样式映射表（表 5）必须为每个"颜色块"列出 rectangle 数据 → 内联 style 的对应关系
+- 写代码时直接用 `<div style={{background:'#f2f8fd',border:'1px solid #d9eafb'}}>`
+- 若必须用 CSS class，类名要能反向追到 Sketch 节点（如 `.segmentBlock-blue` 而非 `.beforebg`），且 class 内容必须**精确等于** rectangle 的 fill/border
+- 反例排查：写完代码后 grep 一下 CSS class 名，出现 `.bg1/.box2/.before*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
+
+### 步骤2.6：布局推理（必做，写代码前的最后一道关）
+
+⚠️ 这一步专治"数据全拿到却放错位置"。反馈 #11 的 5 处错位全部由跳过此步骤导致。
+
+**核心思路**：x+y 坐标先画"视觉假设"，parent 字段做质检纠错。两套信号**互为纠错器**，不是单方向"谁优先"。
+
+**输入**：步骤 2.5 产出的 `text + rectangle + group` 节点全量数据（含 `position.{x,y}`、`size.{width,height}`、`parent.{id,name,type}`、`style`、`isVisualContainer`）
+
+#### Pass 1：坐标推假设（产出 5 张表）
+
+每张表都必须输出，即使某类节点为空也要写"无"。
+
+##### 表 1：分区识别表（x+y+parent 联合，定大区）
+
+```
+| 节点 name      | x   | y   | parent.name      | 推断分区     | 决策依据                |
+|----------------|-----|-----|------------------|--------------|-------------------------|
+| 主题(text)     | 272 | 149 | leftTreeHeader   | 左树标题区   | parent 强语义压过 x 列  |
+| 段码定义(text) | 320 | 200 | cataMain         | 右侧内容-顶部 | parent 含 PageContent 类语义 |
+```
+
+判定流程：
+1. 按 x 把画板切成 1-3 列（x<300 → 左区、x≥300 → 右区，或按设计稿实际边界）
+2. 用 `parent.name` 校验：含 `LeftTree/树/sidebar/cataMain/PageContent/header/footer` 等关键字时以 parent 为准
+3. 冲突时遵循"收获 3"的 A/B/C/D 矩阵（见下方 Pass 2）
+
+→ 此表输出**布局类型**：UpDown（单列）/ LeftRight（双列）/ LeftMiddleRight（三列）
+
+##### 表 2：纵向顺序表（同分区内按 y）
+
+```
+| 分区       | 节点          | y   | 推断角色          |
+|------------|---------------|-----|-------------------|
+| 右侧内容区 | 段码定义      | 200 | 卡片 1            |
+| 右侧内容区 | Tabs          | 420 | Tabs(type=card)   |
+| 右侧内容区 | 配置说明      | 478 | 卡片 2(Tabs 下方) |
+```
+
+铁律：**同分区内**渲染顺序按 y 升序。跨分区不比 y（左树第 100 行 y 和右内容区第 1 行 y 没有可比性）。
+
+##### 表 3：横向排列表（同行按 x，y 差<8px 视为同行）
+
+```
+| 分区/容器       | 节点         | x   | y   | 推断角色                |
+|-----------------|--------------|-----|-----|-------------------------|
+| Query 操作栏    | 名称输入框   | 320 | 50  | Form.Item col-span=6    |
+| Query 操作栏    | 状态下拉     | 540 | 50  | Form.Item col-span=6    |
+| Query 操作栏    | 查询按钮     | 980 | 50  | 操作按钮(右对齐)        |
+```
+
+判定流程：
+1. y 差<8px 识别同一行
+2. 同行按 x 升序排
+3. 计算 x 间距推算 antd Col span（24 栅格）或 flex
+4. 最右元素若 `x + width` 接近容器右边界 → 右对齐（justify-content: flex-end）
+
+##### 表 4：容器归属表（x+y 双轴边界检测）
+
+仅对 `isVisualContainer === true` 的 group 和带 fill/border 的 rectangle 做检测。
+
+```
+| 容器             | x..x+w   | y..y+h   | 落入子元素                       |
+|------------------|----------|----------|----------------------------------|
+| 渐变容器(group)  | 240..960 | 189..297 | 段码含义(x=300,y=257) ✅          |
+| 段码块-蓝(rect)  | 320..420 | 320..360 | (无子节点，仅样式)               |
+```
+
+判定式：子元素 `x ∈ [容器x, 容器x+w]` **且** `y ∈ [容器y, 容器y+h]` → 渲染在容器内部。**单轴判定无效**。
+
+##### 表 5：样式映射表（rectangle/group fill → UI 组件内联样式）
+
+```
+| Sketch 节点          | 数据来源                 | bg/border                | 映射到代码                                                |
+|----------------------|--------------------------|--------------------------|-----------------------------------------------------------|
+| 段码块-蓝(rectangle) | style.fills[0]/borders[0]| bg #f2f8fd / b #d9eafb   | <div style={{background:'#f2f8fd',border:'1px solid #d9eafb'}}> |
+| 渐变容器(group)      | style.fills[0].gradient  | linear #f3faff→#f8fdff   | <div style={{background:'linear-gradient(180deg,#f3faff,#f8fdff)'}}> |
+| Tab 激活态           | rect bg #fff border #0079f7 | bg #fff / b #0079f7   | Tabs type="card" + .segmentTabs .ant-tabs-tab-active 覆盖 |
+```
+
+铁律（见收获 8）：rectangle 的 fill/border 必须以**内联样式**或精确选择器落到代码，**禁止**用 `.beforebg{background:#ebf0ff}` 这类与设计稿无对应关系的 CSS class。
+
+#### Pass 2：parent 质检（按 A/B/C/D 矩阵处理冲突）
+
+逐行扫表 1，对照 parent 字段：
+
+| 情形 | 坐标判定 | parent 判定 | 处理 |
+|------|----------|-------------|------|
+| A | 在容器 X 内 | parent 链含 X | ✅ 双向一致，直接采用 |
+| B | 在容器 X 内 | parent 是兄弟节点 Y | ⚠️ **视觉容器优先**（设计师把图层拆开了）→ 按坐标渲染到 X 内 |
+| C | 不在容器 X 内 | parent.name 强语义 = X | ⚠️ **parent 优先**（绝对定位/溢出布局）→ 按 parent 归属，加 `position:absolute` 标注 |
+| D | 双向都不落 | parent 是顶层 | 独立元素，按坐标走纵向顺序 |
+
+输出**最终归属表**：在表 1 末尾追加 `情形(A/B/C/D)` 列。
+
+#### Pass 3：自检清单（写代码前必跑）
+
+- [ ] 表 1 是否按 x 分布判定了布局类型（UpDown / LeftRight / LeftMiddleRight）？
+- [ ] 表 2 同分区内是否按 y 排序，没有跨分区比 y？
+- [ ] 表 3 同行元素（y 差<8px）是否按 x 排序，计算了栅格 span 或右对齐？
+- [ ] 表 4 容器归属是否做了 x+y 双轴检测，不是只看一轴？
+- [ ] 表 5 所有"颜色块/卡片/渐变"样式都来自 rectangle/group 的 style.fills/borders，没有出现凭空 CSS class？
+- [ ] Pass 2 冲突行是否标了 A/B/C/D 情形和决策依据？
+
+任一项 ❌ → 回 Pass 1 补；禁止跳到步骤 3 前未输出全部 5 张表 + 最终归属表。
+
+**提示（sketch-mcp-server v1.6.1+）**：
 - 大型 .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 坐标
+- 批量 `getMultipleNodeInfo` 支持任意数量 ID（内部按 100 一批自动分片），无需手动拆分；每个节点自带 `parent: {id,name,type}` 字段 + group/artboard 额外有 `children` 和 `isVisualContainer` —— 步骤 2.6 的双向校验同时用 parent 和 x/y，不是只挑一个
 - `matchIconFromName` 评分制返回 Top-3 + `bestMatch.source === "compound"` 强映射，shapePath 节点优先走它
 - 仅当结构化样式数据仍不足（如复杂渐变、阴影）时，才回退到 `renderNodeAsBase64` + `mcp__szcd-component-helper__analyze_design_image`
-- 如果 sketch-mcp-server 工具不可用，提示用户安装：`npm install -g @szc-ft/sketch-mcp-server`
+- 如果 sketch-mcp-server 工具不可用或版本 < v1.6.1（parent / isVisualContainer 字段缺失），提示用户升级：`npm install -g @szc-ft/sketch-mcp-server@latest`
 
 ### 步骤3：分析设计稿（条件执行）
 
@@ -251,6 +392,7 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 **输入**：
 - 步骤 1 的 `mcp__szcd-component-helper__get_architecture_overview` 返回的 `templatePatterns`（TreeQueryTable / QueryTabsTables / LeftRight / UpDown）
+- 步骤 1 的 `componentSummary`：全量组件 + 设计元信息（layoutRole/variantProps/styleInjection/useCases，other/echarts 层附带 compositionSlots/requiredHooks/chartType/sketchSignals）—— **推理组件候选的权威目录，长尾场景按 layoutRole / useCases / sketchSignals 直接反查**
 - 步骤 1 的 `llmMappingHints.commonMistakes`（避免 LLM 常见映射错误）
 - 步骤 2.5 的 Sketch 节点结构 + 样式 Token
 - 或步骤 3 的图片分析描述
@@ -264,38 +406,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
 - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
 
-**推理时使用映射规则**（**此表为本步骤专用，仅含核心高频场景**）：
-
-*页面级布局*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
-| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
-| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
-| 标签页(Tabs) + 每个 Tab 内有表格 | `QueryTabsTables` 或 `TemplateMode` + Tabs | templatePatterns.QueryTabsTables |
+**推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录（由组件库源码动态生成），每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
 
-*区域级组件*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
-| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
-| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
-| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` | 详情区特征 |
-
-*数据可视化（核心 3 类）*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 折线趋势图/时间序列图 | `Line` | ECharts 层图表组件 |
-| 柱状对比图/条形图 | `Bar` | ECharts 层图表组件 |
-| 饼图/环形图/占比图 | `Pie` | ECharts 层图表组件 |
+1. **画板名称** → 直接作为 `pageName`
+2. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（如 TemplateMode），结合 `variantProps.templateType`（LeftRight / TopBottom）和 `templatePatterns`（TreeQueryTable / QueryTabsTables）选模板
+3. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack / FormItemOrDetailItem 等），按 `useCases` 描述匹配 Sketch 区域语义
+4. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
+5. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
 
-*表格子类型（核心 2 类）*：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 可编辑表格（单元格直接输入） | `TableOrList(componentType="EditableProTable")` | 可编辑表格特征 |
-| 卡片列表（非表格式数据卡片） | `TableOrList(componentType="ProList")` | 卡片布局特征 |
+不要硬编码任何「Sketch 特征 → 组件」对照表——`componentSummary` 是唯一可信源，硬编码表会和服务端动态扫描结果漂移。
 
 #### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
 
@@ -389,10 +508,22 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 | 组件 | 依赖的 szcd 组件 | 依赖的 hooks |
 |------|-----------------|-------------|
 
+### 布局顺序（来自步骤 2.6 表 2 压缩，按 y 排序）
+[页面级垂直顺序，如：TitleAndBack → 段码定义卡片 → Tabs → 配置说明卡片]
+
+### 关键样式映射（来自步骤 2.6 表 5，仅列非默认样式）
+| UI 元素 | Sketch 数据来源 | 落地方式 |
+|---------|----------------|----------|
+| 段码块×5 | 5 个 rectangle 的 fills[0]/borders[0] | 内联 style |
+| 渐变容器 | group(isVisualContainer) 的 fills[0].gradient | 内联 linear-gradient |
+| Tab 激活态 | rectangle bg #fff border #0079f7 | type="card" + .segmentTabs 覆盖 |
+
 ### 备选方案（如有）
 [说明]
 ```
 
+用户在确认环节即可发现"段码块颜色没列上"或"Tab 样式漏识别"，避免反馈 #11 那样要等代码生成后反复修。
+
 
 **交互节点**：向用户展示匹配结果，**必须确认方案后再生成代码**。
 
@@ -409,6 +540,20 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 - 复合组件配合 TemplateMode 使用实现标准页面布局
 - Hooks 按依赖关系正确引入（如 useLeftTree、useTable）
 
+#### 步骤 6 末尾必做：样式落地校验
+
+代码生成完成后，**逐行核对**步骤 2.6 表 5（样式映射表）的每一项是否真落到代码里：
+
+```
+| 样式映射表行                                | 代码中对应位置                                              | 校验 |
+|---------------------------------------------|-------------------------------------------------------------|------|
+| 段码块-蓝 bg #f2f8fd border #d9eafb         | CreateOrEdit.tsx:L120 `<div style={{background:'#f2f8fd',border:'1px solid #d9eafb'}}>` | ✅ |
+| 渐变容器 linear #f3faff→#f8fdff             | CreateOrEdit.tsx:L98 `style={{background:'linear-gradient(...)'}}` | ✅ |
+| Tab 激活态 bg #fff border #0079f7           | styles.less:L45 `.segmentTabs .ant-tabs-tab-active{...}`    | ✅ |
+```
+
+❌ 如果某行找不到对应代码位置 → 直接补到代码里再继续，**禁止说"代码已生成"前留缺口**。这是反馈 #11"5 个段码块全错"的根因——所有颜色都拿到了，但没逐一回查是否落到了代码上。
+
 
 **交互节点**：代码生成后，询问用户下一步：
 > "代码已生成，你可以选择：