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

package/qwen-extension/skills/local-api-tool/scripts/extract_swagger.py

@@ -11,8 +11,10 @@ extract_swagger.py — 本地 Swagger 文档提取与解析（与服务端 parse
         递归深度 5，两层 definitions（summary + detail），引用树传递闭包裁剪。
 
 用法：
-  # 方式 A：脚本内部 curl 下载
+  # 方式 A：脚本内部 curl 下载（自动缓存到 /tmp/swagger-cache/，TTL 10 分钟）
   extract_swagger.py --url http://10.x.x.x/svc/v2/api-docs [--cookie 'JSESSIONID=xxx']
+  extract_swagger.py --url ... --no-cache         # 强制重新下载
+  extract_swagger.py --url ... --cache-ttl 3600   # 自定义 TTL（秒），0 关闭缓存
 
   # 方式 B：读取本地已下载的 JSON 文件
   extract_swagger.py --file /tmp/swagger.json
@@ -27,18 +29,40 @@ extract_swagger.py — 本地 Swagger 文档提取与解析（与服务端 parse
   # 输出到文件而非 stdout
   extract_swagger.py --file /tmp/swagger.json --filter tag --out /tmp/parsed.json
 
+容错：
+  - 自动修复八进制字面量（如 [011,015] → [11,15]），无需手动预处理
+  - JSON 解析失败给出错误位置上下文 + 常见原因提示（HTML 跳转/截断/八进制）
+
+跨平台：
+  - Linux/macOS：`python3 extract_swagger.py ...`（脚本 shebang 已带 #!/usr/bin/env python3）
+  - Windows：`python extract_swagger.py ...`（python3 命令可能不可用）
+
 退出码：0 成功；1 参数错误；2 网络/IO 错误；3 解析错误
 """
 
 import argparse
+import hashlib
 import json
+import os
+import re
 import sys
 import subprocess
+import tempfile
+import time
 from pathlib import Path
 
 MAX_DEPTH = 5
 METHOD_KEYS = ["post", "get", "put", "delete", "patch"]
 
+# 缓存配置（与 Node 版 extract-swagger.mjs 完全一致：共用同一目录 + sha256 key）
+CACHE_DIR = Path(tempfile.gettempdir()) / "swagger-cache"
+DEFAULT_CACHE_TTL = 600  # 10 分钟
+
+# 八进制字面量：JSON 标准不允许数字以 0 开头（除 0 本身或小数），
+# 但部分 Java/旧网关序列化会产出 [011,015,022] 这类数组。
+# 匹配 JSON value 位置上的非法前导零数字（不含小数、不含 0 单独存在）。
+OCTAL_LITERAL_RE = re.compile(r'(?<=[\s,\[:])0(\d+)(?=[\s,\]}])')
+
 
 # ==================== 工具函数 ====================
 
@@ -367,7 +391,69 @@ def get_definition(api_docs, definition_name):
     }
 
 
-# ==================== 输入：curl 下载 / 读文件 ====================
+# ==================== 输入：curl 下载 / 读文件 / 缓存 ====================
+
+def _diagnose_json_error(text, err):
+    """根据错误位置给出 ±80 字符上下文 + 常见原因建议。"""
+    pos = getattr(err, "pos", None)
+    if pos is None:
+        # 用 lineno/colno 反推 pos
+        lines = text.split("\n")
+        pos = sum(len(l) + 1 for l in lines[: err.lineno - 1]) + (err.colno - 1)
+    start, end = max(0, pos - 80), min(len(text), pos + 80)
+    snippet = text[start:end].replace("\n", "\\n")
+    marker = " " * (pos - start) + "^"
+
+    # 常见原因诊断
+    hints = []
+    low = text[:500].lstrip()
+    if low.startswith("<"):
+        hints.append("响应以 '<' 开头，可能是 HTML 错误页/登录跳转页，而非 JSON。检查 cookie/auth 是否过期")
+    if OCTAL_LITERAL_RE.search(text):
+        hints.append("检测到八进制字面量（如 [011,015]），脚本应已自动修复——若仍报错请提交 issue")
+    if len(text) < 1024 and text.rstrip().endswith(("}", "]")) is False:
+        hints.append("响应可能被截断（curl 管道/终端缓冲），建议改用 --file 模式直接读本地文件")
+
+    msg = f"JSON 解析失败 at line {err.lineno} col {err.colno}: {err.msg}\n"
+    msg += f"  上下文: ...{snippet}...\n"
+    msg += f"          {' ' * 11}{marker}\n"
+    if hints:
+        msg += "  可能原因:\n" + "\n".join(f"    - {h}" for h in hints)
+    return msg
+
+
+def _fix_octal_literals(text):
+    """把 [011,015] 这类八进制字面量改成 [11,15]（仅在 array/value 位置）。"""
+    return OCTAL_LITERAL_RE.sub(lambda m: m.group(1), text)
+
+
+def load_json_text(text):
+    """解析 JSON；首次失败则尝试八进制修复 fallback，再失败给出诊断信息。"""
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError as e:
+        # Fallback: 尝试修复八进制字面量
+        if OCTAL_LITERAL_RE.search(text):
+            fixed = _fix_octal_literals(text)
+            if fixed != text:
+                try:
+                    parsed = json.loads(fixed)
+                    print(f"[INFO] 自动修复八进制字面量后解析成功", file=sys.stderr)
+                    return parsed
+                except json.JSONDecodeError as e2:
+                    raise RuntimeError(_diagnose_json_error(fixed, e2)) from None
+        raise RuntimeError(_diagnose_json_error(text, e)) from None
+
+
+def _cache_key(url, cookie, auth):
+    h = hashlib.sha256()
+    h.update(url.encode("utf-8"))
+    if cookie:
+        h.update(b"\x00" + cookie.encode("utf-8"))
+    if auth:
+        h.update(b"\x00" + auth.encode("utf-8"))
+    return h.hexdigest()[:16]
+
 
 def fetch_via_curl(url, cookie=None, auth=None, timeout=30):
     """脚本内部走 curl 下载 Swagger JSON。失败抛 RuntimeError。"""
@@ -389,13 +475,36 @@ def fetch_via_curl(url, cookie=None, auth=None, timeout=30):
     return r.stdout
 
 
-def load_json_text(text):
+def fetch_with_cache(url, cookie=None, auth=None, timeout=30, ttl=DEFAULT_CACHE_TTL, no_cache=False):
+    """带 TTL 缓存的 fetch：缓存命中直接读 /tmp/swagger-cache/<key>.json，否则 curl 拉取并写入。"""
+    if no_cache or ttl <= 0:
+        return fetch_via_curl(url, cookie=cookie, auth=auth, timeout=timeout)
+
+    key = _cache_key(url, cookie, auth)
+    CACHE_DIR.mkdir(parents=True, exist_ok=True)
+    cache_file = CACHE_DIR / f"{key}.json"
+    meta_file = CACHE_DIR / f"{key}.meta.json"
+
+    if cache_file.exists() and meta_file.exists():
+        try:
+            meta = json.loads(meta_file.read_text(encoding="utf-8"))
+            age = time.time() - meta.get("cached_at", 0)
+            if age < ttl:
+                print(f"[CACHE] 命中 {key} (age={int(age)}s, ttl={ttl}s)", file=sys.stderr)
+                return cache_file.read_text(encoding="utf-8")
+        except Exception:
+            pass  # 缓存损坏 → 重新拉
+
+    raw = fetch_via_curl(url, cookie=cookie, auth=auth, timeout=timeout)
     try:
-        return json.loads(text)
-    except json.JSONDecodeError as e:
-        # 给出第一行 200 字符 + 错误位置，方便排查
-        preview = text[:200].replace("\n", "\\n")
-        raise RuntimeError(f"JSON 解析失败: {e.msg} (line {e.lineno} col {e.colno})。响应预览: {preview}") from None
+        cache_file.write_text(raw, encoding="utf-8")
+        meta_file.write_text(json.dumps({
+            "url": url, "cached_at": time.time(), "ttl": ttl, "size": len(raw),
+        }), encoding="utf-8")
+        print(f"[CACHE] 已写入 {key} ({len(raw)} bytes)", file=sys.stderr)
+    except Exception as e:
+        print(f"[WARN] 缓存写入失败: {e}", file=sys.stderr)
+    return raw
 
 
 # ==================== CLI ====================
@@ -413,6 +522,10 @@ def main():
     parser.add_argument("--cookie", help="--url 模式可选，鉴权后的 Cookie 值（如 'JSESSIONID=xxx'）")
     parser.add_argument("--auth", help="--url 模式可选，Basic 鉴权 base64(user:pass)")
     parser.add_argument("--timeout", type=int, default=30, help="--url 模式 curl 超时秒数，默认 30")
+    parser.add_argument("--cache-ttl", type=int, default=DEFAULT_CACHE_TTL,
+                        help=f"--url 模式缓存 TTL 秒数，默认 {DEFAULT_CACHE_TTL}（10 分钟），设为 0 关闭")
+    parser.add_argument("--no-cache", action="store_true",
+                        help="--url 模式强制重新下载，忽略缓存")
 
     parser.add_argument(
         "--filter", action="append", default=[],
@@ -433,7 +546,10 @@ def main():
     # 1. 读取原始 Swagger JSON
     try:
         if args.url:
-            raw_text = fetch_via_curl(args.url, cookie=args.cookie, auth=args.auth, timeout=args.timeout)
+            raw_text = fetch_with_cache(
+                args.url, cookie=args.cookie, auth=args.auth, timeout=args.timeout,
+                ttl=args.cache_ttl, no_cache=args.no_cache,
+            )
         else:
             raw_text = Path(args.file).read_text(encoding="utf-8")
     except Exception as e:

package/qwen-extension/skills/szcd-component-helper/SKILL.md

@@ -61,7 +61,7 @@ compatibility:
 AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 
 ### 步骤1：架构认知 + 需求理解
-- 调用 `get_architecture_overview(detail="summary")` 获取 7 层架构和模板组合模式
+- 调用 `get_architecture_overview(detail="full")` 获取 7 层架构、模板组合模式、全量组件设计元信息（componentSummary）+ styleMapping + assetExtraction，用于后续步骤的组件推理与样式注入
 - 分析用户需求的页面布局类型、查询字段、操作按钮、表格列等
 
 ### 步骤2：组件发现（优先语义搜索）
@@ -93,17 +93,13 @@ AI 助手在处理页面生成需求时，必须按以下流程使用工具：
 → get_component_full_profile(批量) → 编码
 ```
 
-**Sketch 结构 → 组件映射规则**：
-| Sketch 特征 | 推断结果 | 依据 |
-|---|---|---|
-| 画板名称（如 "4.1-编目审核-待办"） | `pageName` | 直接使用 |
-| 左侧窄区域 + 树形图层 | `LeftTree` 组件 | templatePatterns.TreeQueryTable |
-| 顶部输入框/下拉框/日期选择器 | `Query` 组件 | 搜索区域特征 |
-| 中间表头 + 数据行图层 | `TableOrList` 组件 | 表格区域特征 |
-| 弹窗/抽屉图层 | `ModelOrDrawer` 组件 | 弹窗交互特征 |
-| 页面标题 + 返回箭头 | `TitleAndBack` 组件 | 标题栏特征 |
-| 左右分区布局 | `TemplateMode(templateTpye="LeftRight")` | 区域分布 |
-| 上下分区布局 | `TemplateMode(templateTpye="TopBottom")` | 区域分布 |
+**Sketch 结构 → 组件映射依据**：直接查阅步骤 1 `get_architecture_overview(detail="full")` 返回的 `componentSummary` 全量元信息，按以下顺序反查组件：
+1. **大区切分** → `componentSummary.other` 中 `layoutRole === '页面定位'`（如 TemplateMode），结合 `variantProps.templateType` 和 `templatePatterns` 选模板
+2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer / TitleAndBack 等），按 `useCases` 匹配 Sketch 区域语义
+3. **图表** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`
+4. **变体** → `variantProps` 配合 `useCases` 区分子类型
+
+`componentSummary` 由组件库源码动态扫描生成，是唯一可信源；不要依赖任何硬编码 Sketch→组件对照表。
 
 **提示**：
 - 大型 .sketch 文件用 `getPageStructure(maxDepth=1-2)` 即可获取布局概况，避免深层递归超时
@@ -204,7 +200,10 @@ sketch-mcp-server 是社区版 MCP Server（npm: `sketch-mcp-server`），通过
 #### 4. get_architecture_overview
 **功能**：查看 7 层架构（AntD→Cover→Wrapper→ProPackage→复合组件→模板）、层级关系和推荐使用顺序。含 LLM 映射修正提示。
 **参数**：
-- `detail` (enum, optional, default: "summary"): summary=层级概览+模板模式+LLM提示；full=含所有层组件列表详情
+- `detail` (enum, optional, default: "summary"):
+  - `summary`：层级概览 + 模板模式 + LLM 提示（轻量，~2K tokens）
+  - `full`：在 summary 基础上附加 `componentSummary`（全量组件清单 + 设计元信息：layoutRole/variantProps/styleInjection/useCases，other/echarts 层另含 compositionSlots/requiredHooks/chartType/sketchSignals）+ `styleMapping`（节点样式映射 + 注入机制 + 选择器表）+ `assetExtraction`（位图/图标/图表色提取规则）。设计稿 → 代码场景必选 full
+  - `decisions`：含架构决策记录
 
 ### Props 深度解析工具
 

package/qwen-extension/skills/szcd-design-to-code/SKILL.md

@@ -34,12 +34,15 @@ Ant Design → ProComponents → Cover 层 → Wrapper 层 → ProPackages →
 
 ### 步骤1：架构认知（必做）
 
-调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="summary"）获取：
+调用 `mcp__szcd-component-helper__get_architecture_overview`（detail="full"）一次性获取：
 - `templatePatterns`：4种模板模式（TreeQueryTable/QueryTabsTables/LeftRight/UpDown）
 - `llmMappingHints.commonMistakes`：LLM 常见映射错误
 - `recommendedUsageOrder`：推荐使用顺序
+- **`componentSummary`**：全量组件清单（cover/wrappers/proPackages/other/echarts），每个组件附带 `layoutRole`（页面定位/区域容器/可视化等）、`variantProps`（关键 variant 参数）、`styleInjection`（样式注入入口）、`useCases`（典型场景）；other/echarts 层还附带 `compositionSlots`、`requiredHooks`、`chartType`、`sketchSignals` 等元信息——LLM 据此推理组件候选
+- **`styleMapping`**：节点样式 → 组件样式的映射规则（nodeStyleRules / injectionMechanisms / selectorMap）
+- **`assetExtraction`**：图标/位图/图表色提取规则（bitmapRules / iconWorkflow / chartColorMapping）
 
-根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板。
+根据返回的 `templatePatterns` 初步判断用户需求匹配哪个模板，并在步骤 3.5 用 `componentSummary` 推理组件候选列表。
 
 ### 步骤2：理解需求（必做）
 
@@ -86,15 +89,78 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 
 组件候选列表推理**不**在步骤 2.5 内部完成，**统一在主流程中结合步骤 1 的 `templatePatterns` 推理**（详见主流程步骤 4 前置说明）。
 
+### 步骤 2.5 必读：getMultipleNodeInfo 返回字段契约（sketch-mcp-server ≥ v1.6.1）
+
+**每个节点的实测返回结构**（与本表不一致即视为版本不匹配，提示用户 `npm i -g @szc-ft/sketch-mcp-server@latest`）：
+
+| 节点类型 | 必有字段 | 关键样式字段（取值路径） |
+|----------|----------|--------------------------|
+| 所有 | `id`, `name`, `type`, `position:{x,y}`, `size:{width,height}`, `parent:{id,name,type}`, `style:{fills,borders,shadows,innerShadows,blur}`, `isVisible`, `opacity` | `style.fills[i].color.hex` / `style.borders[i].color.hex+thickness` / `style.shadows[i].{color,offsetX,offsetY,blurRadius}` |
+| text | + `text:{content, attributes:[{location,length,attributes:{fontFamily,fontSize,color,alignment,lineHeight,letterSpacing}}]}` | 文字色 `text.attributes[0].attributes.color.hex`、字号 `text.attributes[0].attributes.fontSize`、**字重** = `text.attributes[0].attributes.fontFamily` 末尾（如 `PingFangSC-Semibold` → 600，`-Regular` → 400，`-Medium` → 500） |
+| rectangle/oval | + `shape:{type, cornerRadius}` | `shape.cornerRadius`（圆角）；背景 `style.fills[0].color.hex`；描边 `style.borders[0]` |
+| **group/artboard** | + `children:[id]`, **`isVisualContainer:bool`** | **`isVisualContainer === true`** 时：`style.fills[0]`（含 `gradient`）= 容器背景、`style.borders[0]` = 容器边框 ← **渐变盒/卡片样式的唯一来源**；`false` 时只是图层文件夹，无视觉样式 |
+| bitmap | + `image:{imageRef, originalSize}` | 用 `extractBitmaps` 取 base64 |
+| shapePath | + `shape:{path}` | 用 `matchIconFromName` 匹配 iconfont |
+
+#### 字段缺失自检（getMultipleNodeInfo 返回后立即跑）
+
+抽样 5 个节点（含至少 1 text + 1 group + 1 rectangle）做契约校验：
+
+- [ ] 5 个节点都有 `parent.name`（任一为 undefined → 服务端版本旧，提示升级到 ≥ v1.6.1）
+- [ ] 所有 group/artboard 节点都有 `isVisualContainer` 布尔字段
+- [ ] 所有 group 节点都有 `children` 数组（即使为空）
+- [ ] text 节点 `text.attributes[0].attributes.fontFamily` 不为空
+- [ ] 至少 1 个 rectangle 的 `style.fills.length > 0` 或 `style.borders.length > 0`（若全为 0，可能 .sketch 文件本身无视觉样式，或抽样偏差）
+
+**任一项 ❌ → 停下来定位原因，禁止带着不完整的数据进入步骤 2.6**。
+
 ### 步骤2.5.1：图标与位图提取（有 bitmap/shapePath 节点时执行）
 
 **输入**：步骤 2.5 产出的 bitmap ID 列表 + shapePath 节点名列表
 
+#### 🔒 资源优先级铁律（必读，违反则直接重做本步骤）
+
+代码中的每一处图标、背景、装饰资源，必须按以下优先级**依次尝试**，前一级能命中就**不许跳到下一级**：
+
+| 优先级 | 来源 | 适用判定 | 渲染产物 |
+|---|---|---|---|
+| **P0** | **sketch 自带 bitmap** | 节点是 `type=bitmap` | `extractBitmaps` 返回的 `siblingsAfterMe + position + nodeSize` 三维判定渲染产物：区域背景图 / 行内图标 / 独立装饰插图（详见下方表 6） |
+| **P1** | **sketch 自带 shapePath（iconfont 命中）** | shapePath/shapeGroup 节点名能在 iconfont 库匹配到 | `matchIconFromName` → `<IconfontWapper type='icon-xxx' />` |
+| **P2** | **sketch 自带 shapePath（SVG 直出）** | 独立 shapePath（parent.type !== 'shapeGroup'），P1 未命中且 viewBox 校验通过 | `getShapePathData` → 内联 SVG |
+| **P3** | **antd 图标语义匹配** | 上面三级都失败：shapeGroup 无法直出、节点名无 iconfont 匹配 | `<XxxOutlined />` 按 contextTable 选语义最近的 antd 图标 |
+| **P4** | **纯 CSS / div 渲染** | 上面四级全部失败，且元素是几何/色块（非图标语义） | `<div style={{...}}>` |
+
+**禁止行为（违反 = 重做）**：
+- ❌ sketch 里有 bitmap 节点，却用 `<div style={{backgroundColor}}>` 模拟（必须 P0 提取真图）
+- ❌ shapePath 节点直接降级 antd 图标，没跑过 `matchIconFromName`（跳过 P1）
+- ❌ 凭节点名"猜"语义就选 antd 图标，没看 parent 上下文（contextTable 在 `assetExtraction.iconWorkflow.contextTable`）
+- ❌ 把 P0 提取出的 base64 写成 hardcoded url 而非 inline data URI（资源会丢）
+
+**前置自检**：步骤 1 拿到的 `assetExtraction.bitmapRules` + `assetExtraction.iconWorkflow` 是上述铁律的服务端权威定义；本步开始前必须已加载，否则回到步骤 1 调 `get_architecture_overview(detail="full")`。
+
 **工具调用**：
 
 1. `mcp__sketch-mcp-server__extractBitmaps`（bitmapIds）— 从 .sketch 解压目录提取 bitmap PNG 资源
-   - 返回 `{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName }] }`
-   - 位图资源用于 CSS `background-image` 引用
+   - 返回（v1.7.0+）：`{ bitmaps: [{ nodeId, name, base64, mimeType, size, fileName, position:{x,y}, nodeSize:{width,height}, parentId, parent:{id,name,type,size}, siblingsBeforeMe:[...], siblingsAfterMe:[...] }] }`
+   - **`siblingsAfterMe` 是 z-order 渲染在 bitmap 上方的兄弟节点**（Sketch `layers[]` 排在它之后的项），是判定"区域背景图 vs 独立装饰"的核心信号
+   - **不要再为每个 bitmap 单独跑 `getNodeInfo` 拿 position/parent**，这些字段在 extractBitmaps 返回里已有
+
+##### 表 6：bitmap 用途判定与代码落地（必做）
+
+每个 bitmap 都要按本表归类，**只看 `siblingsAfterMe` + `position` + `nodeSize/parent.size`**，不要凭名字猜。判定后必须落到代码（详见经验 9 的"资源落地校验"）。
+
+| # | 判定信号（联合判断） | 用途 | 代码落地方式 |
+|---|---|---|---|
+| 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 子节点正常渲染 |
+| 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>` 占位 |
+| 3 | `siblingsAfterMe.length === 0 && siblingsBeforeMe.length === 0`（独占父容器） | **独立装饰插图**（占位图、空状态图等） | `<img src={`data:image/png;base64,${base64}`} style={{width:nodeSize.width,height:nodeSize.height}} />` 走文档流 |
+| 4 | `siblingsAfterMe.length > 0` **但** 占父宽 < 70% | **嵌入式插图**（区域内某子块的背景） | 同 #1，但 wrapper 是该子块而非整个 parent；定位用 `position:'absolute', top:position.y, left:position.x` |
+
+**反例（违反 = 重做）**：
+- ❌ 把 #1 区域背景图渲染为独立 `<img>`（反馈 #14 的 `未编目资源` 493×64 y=52 错例）——丢失"内容叠在底图上"的视觉关系
+- ❌ 把 #2 行内图标用 `backgroundImage` 写在 `<div>` 上——`<div>` 没设宽高就塌缩；用 `<img>` 自带尺寸更稳
+- ❌ 同一 imageRef 多个 nodeId 引用，extractBitmaps 多次调用——只调一次（按 nodeId 列表去重前判断 `fileName`），渲染时复用 base64 引用
+
 2. `mcp__sketch-mcp-server__matchIconFromName`（nodeNames, library="newFont"）— 匹配 iconfont 图标库（v1.5.0+ 评分制）
    - 输入 shapePath 节点名列表（如 `["表 icon", "新建文件夹", "编组11备份"]`）
    - **评分机制**：compoundIcons 强映射 +100、keyword 精确 +20、keyword 包含 +10、semanticTag +3
@@ -165,15 +231,20 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 - 新做法：直接传入全部 ID（如 200 个）→ 内部自动按 100 个一批处理 → 返回合并结果
 - 返回结构不变：`{ nodes: [...], total, requested, batches }`
 
-**经验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.5 第 4 步先 `mode="tree"` 看顶层 group 分区（通常 2-5 个，对应 LeftTree区/Query+Table区/信息栏区/标题栏区）
-- `getMultipleNodeInfo`/`getNodeInfo` v1.5.0+ **自动返回** `parent: { id, name, type }` 字段，按 parent 归属到具体分区即可
-- "主题"这类标题文本，先看 `parent.name` 是否带 "LeftTree" / "树" 等容器关键字，不要看 x 坐标
-- 坐标仅作为同 parent 内子元素排序兜底使用
+- 步骤 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 再取子元素**
 
@@ -209,12 +280,146 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 
 识别出图表后，**图例色块**应归入 ECharts `legend` 配置（不要用 div 硬编码），**柱体色**映射到 `series.itemStyle.color`。
 
+**图表组件类型选择**：参考步骤 1 返回的 `componentSummary.echarts`，每项含 `chartType`（line/bar/pie 等）和 `sketchSignals`（典型 Sketch 特征），按 sketchSignals 反查 chartType 即可锁定组件名（如 `Line` / `Bar` / `Pie`）。
+
 **经验7：矢量图形用 matchIconFromName 自动匹配，无需手动解压**
 - `shapePath` / `shapeGroup` 在 sketch 节点中占比可能高达 46.8%，但 `renderNodeAsBase64` 不支持渲染
 - **新方案**：`matchIconFromName(shapePathNames)` 自动查询 iconfont 库 → 返回匹配结果
 - bitmap 用 `extractBitmaps(bitmapIds)` 自动提取 PNG 资源
 - 兜底：未匹配的节点用 antd `@ant-design/icons` 同语义图标替代，在代码注释中标注“⚠️ 矢量图标用 antd 图标替代，原始 Sketch 为 shapePath”
 
+**经验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*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
+
+**经验9：bitmap 资源落地校验（每张 PNG 必须对应一处代码引用）**
+
+实战教训（反馈 #14，2026-06-15）：`未编目资源` bitmap（493×64, y=52）首版被渲染为独立 `<img>` 装饰插图，实际上它是 64px 高统计区域的底图（`siblingsAfterMe` 含 7 个 text/rect 内容元素叠在上面）。9 张 PNG 资源拿到了 base64，但其中 1 张用错位置——这种"提取了但用错"的回退比"忘记提取"更隐蔽。
+
+**校验流程（写代码后必跑）**：
+
+1. 把 `extractBitmaps` 返回的每个 `bitmap` 按表 6 归类，列出"用途清单"（区域背景 N 个、行内图标 N 个、独立装饰 N 个）
+2. 在生成的代码里 grep `data:image/png;base64`，统计实际引用数 ≥ 用途清单总数（去重后）
+3. 对每个 #1 区域背景图核对：是否真的写在 wrapper div 的 `style.backgroundImage` 上？wrapper 内部是否包含 `siblingsAfterMe` 列出的子节点？
+4. 对每个 #2 行内图标核对：原本在该位置的 `<IconfontWapper>` / antd 图标是否已被 `<img>` 替换？
+5. 对每个 #3 独立装饰核对：是否在 parent 的纵向流中出现？
+
+**反例（违反 = 重做）**：
+- ❌ extractBitmaps 拿到 9 张 PNG，代码里只 grep 出 8 个 `data:image/png;base64` 引用——必有 1 张被丢
+- ❌ #1 区域背景图被错放成独立 `<img>`，导致 `siblingsAfterMe` 的内容元素失去底图衬托（这是反馈 #14 的具体回退）
+- ❌ 同 imageRef 多次出现（如 `文件备份2/3/4` 复用同一 PNG），代码生成了 N 份 base64 字符串而非引用同一个常量——文件大小翻倍
+
+### 步骤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 张表 + 最终归属表。
+
 ### 步骤3：分析设计稿图片（有图片时执行）
 
 - 主智能体已提供图片描述时，直接使用，跳过此步
@@ -246,23 +451,14 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 - ❌ 在步骤 3 内部推理组件候选列表（应只产出图片描述）
 - ❌ 跳过此环节直接调 `get_component_full_profile`（必须先有候选列表）
 
-**推理时使用映射规则**（**此表为本步骤专用，核心高频场景**）：
-
-| Sketch 特征 | 推断组件 |
-|---|---|
-| 左右分区布局 | `TemplateMode(templateType="LeftRight")` |
-| 上下分区布局 | `TemplateMode(templateType="TopBottom")` |
-| 左侧窄区域 + 树形图层 | `LeftTree` |
-| 顶部输入框/下拉框/日期选择器 | `Query` |
-| 中间表头 + 数据行图层 | `TableOrList` |
-| 弹窗/抽屉图层 | `ModelOrDrawer` |
-| 页面标题 + 返回箭头 | `TitleAndBack` |
-| 详情展示区域（只读字段） | `FormItemOrDetailItem(type="detail")` |
-| 卡片列表 | `TableOrList(componentType="ProList")` |
-| 可编辑表格 | `TableOrList(componentType="EditableProTable")` |
-| 折线趋势图 | `Line` |
-| 柱状对比图 | `Bar` |
-| 饼图/环形图 | `Pie` |
+**推理依据**：步骤 1 返回的 `componentSummary` 是组件候选的权威目录，每项含 `layoutRole` / `variantProps` / `useCases` / `sketchSignals`（图表层）。按以下顺序反查：
+
+1. **大区切分** → 看 `componentSummary.other` 里 `layoutRole === '页面定位'` 的组件（TemplateMode）匹配 `templateType` 变体
+2. **区域容器** → `layoutRole === '区域容器'` 的组件（LeftTree / Query / TableOrList / ModelOrDrawer 等），按 `useCases` 描述匹配 Sketch 区域语义
+3. **图表组件** → `componentSummary.echarts[*].sketchSignals` 反查 `chartType`，锁定 Line / Bar / Pie / Scatter 等
+4. **变体选择** → 同一组件的子类型（如 TableOrList 的 ProTable / ProList / EditableProTable）查 `variantProps` 配合 useCases
+
+不要再依赖任何硬编码映射表——`componentSummary` 由组件库源码动态生成，是唯一可信源。
 
 ### ⚠️ TemplateMode 槽位传参铁律（高频踩坑）
 
@@ -314,8 +510,20 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 ### 依赖关系
 | 组件 | 依赖的 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 那样要等代码生成后反复修。
+
 ### 步骤6：生成代码（必做）
 
 遵循规范：
@@ -326,7 +534,21 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 - Hooks 按依赖关系正确引入（useLeftTree、useTable 等）
 - 复合组件配合 TemplateMode 使用
 
-代码生成后询问用户：
+#### 步骤 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 个段码块全错"的根因——所有颜色都拿到了，但没逐一回查是否落到了代码上。
+
+代码生成 + 落地校验都通过后，询问用户：
 > "代码已生成，你可以选择：
 > 1. 调整样式或交互细节
 > 2. 补充表单校验/批量操作等功能