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

package/standard-skill/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/standard-skill/szcd-design-to-code/SKILL.md

@@ -86,6 +86,31 @@ 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 节点名列表
@@ -165,15 +190,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 再取子元素**
 
@@ -215,6 +245,121 @@ queryNodes({ pageId, type: ["text", "rectangle", "group"], limit: 500 })
 - 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*` 这类无语义类名、且颜色和设计稿对不上 → 几乎确定是凭空兜底
+
+### 步骤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：分析设计稿图片（有图片时执行）
 
 - 主智能体已提供图片描述时，直接使用，跳过此步
@@ -314,8 +459,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 +483,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. 补充表单校验/批量操作等功能