cardbuddy 0.9.1 → 0.11.0

package/dist/vendored/skills/dsl-card-generator/scripts/check_topology.py

@@ -0,0 +1,678 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""check_topology.py — 基于人力卡统计规则库（references/handcrafted/patterns.json）
+对生成的 schema 做拓扑合规性检查。
+
+设计原则（关键）：
+- **纯建议层**：只产出 hints 清单（INFO 级），不抛 errors、不阻断 validate。
+  生成器与人工可以照常发布；本工具是「对比人力卡范式的偏离度报告」。
+- **不打分排序**：每条 hint 是一句话建议 + 证据 + 推荐做法，下游自行决定是否采纳。
+- **无业务词**：全部基于结构特征（className / itemKey / slotKey / parent-child 组合），
+  不引用任何具体业务字段名。
+
+hint 类型：
+  - "skeleton_uncommon": 父节点的子节点类型序列在人力卡中频次很低（<3 张卡支持）
+  - "slot unconventional": 该 className 在人力卡中 slot 约定与此不同
+  - "missing_required_style": 该 className 节点缺人力卡 ≥90% 都有的 style itemKey
+  - "var_name_uncommon": inputParams 的 key 不在人力卡 top-N 高频命名集
+  - "binding_low_expr_ratio": 文本绑定 literal:$expr 比例偏离人力卡均值（≥0.65 $expr）
+
+用法：
+    python check_topology.py <schema.json>             # 检查一张卡
+    python check_topology.py <schema.json> --quiet     # 只输出 hints 数量
+    python check_topology.py <schema.json> --patterns <path>  # 指定规则库
+默认规则库 = <skill>/references/handcrafted/patterns.json。
+"""
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+SKILL_DIR = SCRIPT_DIR.parent
+DEFAULT_PATTERNS = SKILL_DIR / "references" / "handcrafted" / "patterns.json"
+
+# 阈值（可调）
+SKELETON_MIN_SUPPORT = 3        # 低于此支持度的骨架触发 uncommon hint
+MISSING_REQUIRED_RATIO = 0.9    # 与 patterns.json 中 REQUIRED_RATIO 对齐
+VAR_NAME_TOP_N = 60             # inputParams 推荐集大小（与 patterns.json 一致）
+EXPR_RATIO_BASELINE = 0.65      # 文本绑定 $expr 比例的人力卡基线
+EXPR_RATIO_DEVIATION = 0.2      # 偏离基线 ±20% 触发 hint
+
+
+def load_patterns(path):
+    if not Path(path).is_file():
+        return None
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"[WARN] 无法加载规则库 {path}: {e}", file=sys.stderr)
+        return None
+
+
+def iter_children(node):
+    """统一提取直接子节点（兼容 view.components 与 comp.slots[].components）。"""
+    kids = []
+    if isinstance(node, dict):
+        comps = node.get("components")
+        if isinstance(comps, list):
+            kids.extend(c for c in comps if isinstance(c, dict))
+        slots = node.get("slots")
+        if isinstance(slots, list):
+            for sl in slots:
+                if isinstance(sl, dict) and isinstance(sl.get("components"), list):
+                    kids.extend(c for c in sl["components"] if isinstance(c, dict))
+    return kids
+
+
+def collect_style_itemkeys(node):
+    out = set()
+    style = node.get("style") or {}
+    for p in style.get("properties") or []:
+        if isinstance(p, dict):
+            ik = p.get("itemKey")
+            if ik:
+                out.add(ik)
+    return out
+
+
+def collect_slot_specs(node):
+    out = []
+    for sl in node.get("slots") or []:
+        if isinstance(sl, dict):
+            out.append((sl.get("slotKey", "default"), bool(sl.get("slotScope", False))))
+    return out
+
+
+def text_value_binding(node):
+    for p in node.get("properties") or []:
+        if isinstance(p, dict) and p.get("itemKey") == "value":
+            iv = p.get("itemValue")
+            ivf = p.get("itemValueFrom")
+            if isinstance(iv, str):
+                return "$expr" if "$" in iv else "literal"
+            if isinstance(ivf, str) and "$" in ivf:
+                return "$expr"
+    return None
+
+
+def walk_components(view):
+    """yield (node, depth, parent_type, parent_node)."""
+    def rec(c, depth, ptype, pnode):
+        if not isinstance(c, dict):
+            return
+        cn = c.get("className", "") or ""
+        yield (c, depth, ptype, pnode)
+        for k in iter_children(c):
+            yield from rec(k, depth + 1, cn, c)
+    yield from rec(view, 0, None, None)
+
+
+def check_skeletons(view, patterns):
+    """检查父节点的子节点类型序列是否落在人力卡常见骨架。
+    去重粒度：(parent_type, sibling_signature)。同卡片内同种拓扑模式只报一次（避免噪声），
+    但 hint 里给出出现次数供下游判断严重度。
+    """
+    hints = []
+    skeletons = patterns.get("topologySkeletons", {})
+    idx = {}
+    for parent, entries in skeletons.items():
+        idx[parent] = {(tuple(e["children"]), e["support"]) for e in entries}
+    # 第一次扫描：统计每个 (parent_type, sibling_signature) 在卡片内出现次数
+    counts = {}  # (parent_type, sig) -> count
+    queue = [view]
+    while queue:
+        node = queue.pop(0)
+        if not isinstance(node, dict):
+            continue
+        cn = node.get("className", "") or ""
+        kids = iter_children(node)
+        if kids and cn:
+            sibs = tuple(k.get("className", "?") for k in kids)
+            key = (cn, sibs)
+            counts[key] = counts.get(key, 0) + 1
+        for k in iter_children(node):
+            queue.append(k)
+    # 第二次：对每种出现的 (parent, sig) 输出一次 hint
+    for (cn, sibs), in_card_count in counts.items():
+        if cn not in idx:
+            continue
+        supports = [sup for (k, sup) in idx[cn] if k == sibs]
+        sup = supports[0] if supports else 0
+        if sup < SKELETON_MIN_SUPPORT:
+            hints.append({
+                "type": "skeleton_uncommon",
+                "severity": "info",
+                "parent": cn,
+                "children": list(sibs),
+                "support_in_handcrafted": sup,
+                "occurrences_in_card": in_card_count,
+                "suggestion": (
+                    f"父节点 {cn} 的子节点序列 {list(sibs)} 在人力卡中仅出现在 {sup} 张"
+                    f"（阈值 ≥{SKELETON_MIN_SUPPORT}），本卡片内出现 {in_card_count} 次。"
+                    f"可参考 patterns.json['topologySkeletons']['{cn}'] 的高频骨架。"
+                    f"若确为新形态请忽略。"
+                ),
+            })
+    return hints
+
+
+def check_slots(view, patterns):
+    """检查 className 的 slot 约定是否与人力卡多数派一致。"""
+    hints = []
+    conv = patterns.get("slotConventions", {})
+    seen = set()
+    for c, depth, ptype, pnode in walk_components(view):
+        cn = c.get("className", "") or ""
+        if cn not in conv:
+            continue
+        slots_here = collect_slot_specs(c)
+        if not slots_here:
+            continue
+        comp_id = c.get("componentId", "") or id(c)
+        if (cn, comp_id) in seen:
+            continue
+        seen.add((cn, comp_id))
+        default = conv[cn].get("default", {})
+        d_sk = default.get("slotKey", "default")
+        d_ss = default.get("slotScope", False)
+        for (sk, ss) in slots_here:
+            if sk != d_sk or ss != d_ss:
+                hints.append({
+                    "type": "slot_unconventional",
+                    "severity": "info",
+                    "className": cn,
+                    "actual": {"slotKey": sk, "slotScope": ss},
+                    "expected": {"slotKey": d_sk, "slotScope": d_ss},
+                    "suggestion": (
+                        f"{cn} 的 slot={sk} scope={ss} 与人力卡多数派不一致"
+                        f"（人力卡 {conv[cn].get('support',0)}/张默认 slotKey={d_sk} slotScope={d_ss}）。"
+                        f"若无理由请对齐。"
+                    ),
+                })
+    return hints
+
+
+def check_required_styles(view, patterns):
+    """检查每个 className 节点是否齐全人力卡 ≥90% 都有的 style itemKey。"""
+    hints = []
+    style_req = patterns.get("styleRequired", {})
+    seen = set()
+    for c, depth, ptype, pnode in walk_components(view):
+        cn = c.get("className", "") or ""
+        if cn not in style_req:
+            continue
+        required = style_req[cn].get("required", [])
+        if not required:
+            continue
+        comp_id = c.get("componentId", "") or id(c)
+        if (cn, comp_id) in seen:
+            continue
+        seen.add((cn, comp_id))
+        actual_keys = collect_style_itemkeys(c)
+        missing = [k for k in required if k not in actual_keys]
+        if missing:
+            hints.append({
+                "type": "missing_required_style",
+                "severity": "info",
+                "className": cn,
+                "componentId": c.get("componentId", ""),
+                "missing": missing,
+                "suggestion": (
+                    f"{cn} 节点缺失人力卡 ≥{int(MISSING_REQUIRED_RATIO*100)}% 都有的 style itemKey: {missing}。"
+                    f"可能导致样式无法对齐平台默认渲染。"
+                ),
+            })
+    return hints
+
+
+def check_var_naming(schema, patterns):
+    """检查 inputParams 的 key 是否在人力卡高频命名集或符合中性命名习惯。"""
+    hints = []
+    var_naming = patterns.get("variableNaming", {})
+    top_keys = {x["key"] for x in var_naming.get("topParamKeys", [])[:VAR_NAME_TOP_N]}
+    list_keys = {x["key"] for x in var_naming.get("listItemFieldKeys", [])[:VAR_NAME_TOP_N]}
+    params = schema.get("dictionary", {}).get("inputParams", [])
+    for p in params:
+        k = p.get("key", "")
+        if not k:
+            continue
+        # 中性命名（不以业务实体名命名）：白名单 = 字母/数字/下划线 + 通用语义后缀
+        # 这里简化：只要不在 top_keys 且明显含业务拼音/汉字，给提示
+        if k in top_keys:
+            continue  # 命中人力卡高频集，跳过
+        # 若是 list children 字段名则跳过
+        if k in list_keys:
+            continue
+        # 中性命名规则：纯 ASCII 字母数字下划线
+        is_neutral = all(ch.isalnum() or ch in "_-" for ch in k)
+        if not is_neutral:
+            hints.append({
+                "type": "var_name_non_ascii",
+                "severity": "info",
+                "key": k,
+                "suggestion": (
+                    f"inputParams key='{k}' 含非 ASCII 字符。人力卡变量名均为 ASCII（snake_case / camelCase）。"
+                    f"若是中文业务字段，建议改为英文语义命名或参考 patterns.json['variableNaming']['topParamKeys']。"
+                ),
+            })
+    return hints
+
+
+def check_text_binding_ratio(view, patterns):
+    """检查 Text 节点的字面量 vs $expr 比例是否偏离人力卡基线。"""
+    hints = []
+    baseline = patterns.get("textBindingParadigm", {}).get("exprRatio", EXPR_RATIO_BASELINE)
+    expr_count = 0
+    literal_count = 0
+    for c, depth, ptype, pnode in walk_components(view):
+        if (c.get("className", "")) != "Text":
+            continue
+        b = text_value_binding(c)
+        if b == "$expr":
+            expr_count += 1
+        elif b == "literal":
+            literal_count += 1
+    total = expr_count + literal_count
+    if total < 5:
+        return hints  # 样本太小不判
+    actual_ratio = expr_count / total
+    if abs(actual_ratio - baseline) > EXPR_RATIO_DEVIATION:
+        direction = "低于" if actual_ratio < baseline else "高于"
+        hints.append({
+            "type": "binding_ratio_deviation",
+            "severity": "info",
+            "expr_count": expr_count,
+            "literal_count": literal_count,
+            "actual_ratio": round(actual_ratio, 3),
+            "baseline_ratio": baseline,
+            "suggestion": (
+                f"Text 节点 $expr 比例 {actual_ratio:.0%}（{expr_count}/总{total}）{direction}人力卡基线 {baseline:.0%}。"
+                f"人力卡偏绑变量；过低意味着大量文本写死，可能不利于多状态/多语言扩展。"
+                f"若该卡片文本确实全静态可忽略。"
+            ),
+        })
+    return hints
+
+
+def check_all(schema_path, patterns_path=DEFAULT_PATTERNS):
+    patterns = load_patterns(patterns_path)
+    # v2 抽象规律库（与 patterns.json 同目录）
+    recipes_path = Path(patterns_path).parent / "recipes_v2.json"
+    recipes = load_patterns(recipes_path) if recipes_path.is_file() else None
+
+    try:
+        with open(schema_path, encoding="utf-8") as f:
+            schema = json.load(f)
+    except Exception as e:
+        return [], f"无法读取 schema: {e}"
+
+    view = schema.get("view")
+    if not isinstance(view, dict):
+        return [], "schema 缺 view 树"
+
+    hints = []
+
+    # v2 抽象层检查（新权威）
+    if recipes:
+        hints.extend(check_v2_intent_coverage(view, schema, recipes))
+        hints.extend(check_v2_param_roles(view, schema, recipes))
+        hints.extend(check_v2_style_contracts(view, recipes))
+    # v1 频率统计检查（fallback，仅当 v2 不可用时启用）
+    if patterns and not recipes:
+        hints.extend(check_skeletons(view, patterns))
+        hints.extend(check_slots(view, patterns))
+        hints.extend(check_required_styles(view, patterns))
+        hints.extend(check_var_naming(schema, patterns))
+        hints.extend(check_text_binding_ratio(view, patterns))
+    return hints, None
+
+
+# ====================================================================
+# v2 抽象层检查器
+# ====================================================================
+def _iter_children(node):
+    if not isinstance(node, dict):
+        return []
+    kids = []
+    comps = node.get("components")
+    if isinstance(comps, list):
+        kids.extend(c for c in comps if isinstance(c, dict))
+    slots = node.get("slots")
+    if isinstance(slots, list):
+        for sl in slots:
+            if isinstance(sl, dict) and isinstance(sl.get("components"), list):
+                kids.extend(c for c in sl["components"] if isinstance(c, dict))
+    return kids
+
+
+def _walk(node, depth=0):
+    if not isinstance(node, dict):
+        return
+    yield node, depth
+    for c in _iter_children(node):
+        yield from _walk(c, depth + 1)
+
+
+def _get_text_value(node):
+    for p in node.get("properties") or []:
+        if isinstance(p, dict) and p.get("itemKey") == "value":
+            iv = p.get("itemValue")
+            if isinstance(iv, str):
+                return iv
+    return ""
+
+
+def _get_font_size(node):
+    for grp in (node.get("style") or {}).get("properties") or []:
+        if isinstance(grp, dict) and grp.get("itemKey") == "font":
+            for c in (grp.get("itemChildren") or {}).get("properties") or []:
+                if isinstance(c, dict) and c.get("itemKey") == "fontSize":
+                    try:
+                        return int(c.get("itemValue"))
+                    except (TypeError, ValueError):
+                        return None
+    return None
+
+
+def _has_event_action(node, event_key=None, action_type=None):
+    for ea in node.get("eventactions") or []:
+        if not isinstance(ea, dict):
+            continue
+        ek = (ea.get("event") or {}).get("eventKey")
+        at = (ea.get("action") or {}).get("actionType")
+        if event_key and ek != event_key:
+            continue
+        if action_type and at != action_type:
+            continue
+        return True
+    return False
+
+
+def _get_custom_action_codes(node):
+    codes = []
+    for ea in node.get("eventactions") or []:
+        if not isinstance(ea, dict):
+            continue
+        if (ea.get("action") or {}).get("actionType") != "customAction":
+            continue
+        for p in (ea.get("action") or {}).get("properties") or []:
+            if isinstance(p, dict) and p.get("itemKey") == "function":
+                iv = p.get("itemValue")
+                if isinstance(iv, dict) and iv.get("code"):
+                    codes.append(iv["code"])
+    return codes
+
+
+def check_v2_intent_coverage(view, schema, recipes):
+    """检查生成卡命中哪些布局意图，给出 canonical 拓扑对照建议。
+
+    与 v1 check_skeletons 不同：v1 报「父子序列在人力卡中频次低」，
+    v2 报「这张卡命中哪些意图 + 是否符合 canonical 拓扑 + 是否漏抽关键参数」。
+    """
+    hints = []
+    layout = recipes.get("layoutIntents", {})
+
+    # 复用 extract_handcrafted 的意图识别逻辑（简单复制，避免循环依赖）
+    import re
+    intents = []
+
+    root_children = _iter_children(view)
+    root_classes = [c.get("className", "") for c in root_children]
+    if root_classes and root_classes[0] == "Column":
+        intents.append("single_column_flow")
+
+    has_list = any(c.get("className") == "ListLayout" for c, _ in _walk(view))
+    if has_list:
+        intents.append("list_with_sections")
+
+    # form_rows
+    form_rows = 0
+    for c, _ in _walk(view):
+        if c.get("className") != "Row":
+            continue
+        kids = _iter_children(c)
+        kc = [k.get("className", "") for k in kids]
+        if (len(kc) >= 2 and kc[0] == "Text" and kc[1] in ("Text", "Input")):
+            form_rows += 1
+        elif (len(kc) == 2 and kc[0] == "Text" and kc[1] in ("Image", "Icon")):
+            form_rows += 1
+    if form_rows >= 2:
+        intents.append("form_rows")
+
+    # canvas_chart
+    for c, _ in _walk(view):
+        if c.get("className") == "Canvas" and _has_event_action(c, "onMeasured"):
+            intents.append("canvas_chart")
+            break
+
+    # tab_switch
+    input_params = schema.get("dictionary", {}).get("inputParams", [])
+    has_active_tab = any(p.get("key") == "activeTab" for p in input_params)
+    vshow_count = sum(
+        1 for c, _ in _walk(view)
+        for d in c.get("directives") or []
+        if isinstance(d, dict) and d.get("itemKey") == "v-show"
+    )
+    if has_active_tab and vshow_count >= 2:
+        intents.append("tab_switch")
+
+    # 输出：每个命中的意图给一个 hint（含 canonical 拓扑对照）
+    for ik in intents:
+        spec = layout.get(ik, {})
+        if not spec:
+            continue
+        hints.append({
+            "type": "intent_matched",
+            "severity": "info",
+            "intent": ik,
+            "desc": spec.get("desc", ""),
+            "canonical_topology": spec.get("canonical_topology", ""),
+            "param_recipe": spec.get("param_recipe", ""),
+            "support": spec.get("support", 0),
+            "suggestion": (
+                f"命中布局意图 {ik}（{spec.get('desc', '')}）。"
+                f"人力卡 {spec.get('support', 0)} 张同构，canonical 拓扑："
+                f"{spec.get('canonical_topology', '')}。"
+                + (f" 参数配方：{spec.get('param_recipe', '')}。" if spec.get("param_recipe") else "")
+                + "若实际拓扑偏离 canonical，请确认是否有充分理由。"
+            ),
+        })
+
+    # 漏抽提示：命中的意图对应的关键参数角色在 inputParams 中是否缺失
+    INTENT_REQUIRED_ROLES = {
+        "list_with_sections": [("items", "array"), ("showAll", "boolean")],
+        "amount_header": [("primaryAmount", "number")],
+        "form_rows": [],  # 表单行参数按位置派生，不强求
+        "tab_switch": [("activeTab", "string")],
+    }
+    input_keys = {p.get("key", "") for p in input_params}
+    for ik in intents:
+        for role, _ in INTENT_REQUIRED_ROLES.get(ik, []):
+            # 简单检查：inputParams 含同名 key（不含则提示）
+            if role not in input_keys and role != "showAll":
+                hints.append({
+                    "type": "param_role_missing",
+                    "severity": "info",
+                    "intent": ik,
+                    "missing_role": role,
+                    "suggestion": (
+                        f"命中意图 {ik} 但 inputParams 未含角色 `{role}`。"
+                        f"若该卡确需此角色（如列表数据/Tab 状态），请补抽；"
+                        f"若该卡不适用此角色（如静态展示），可忽略。"
+                    ),
+                })
+
+    # 未命中任何意图的提示
+    if not intents:
+        hints.append({
+            "type": "no_intent_matched",
+            "severity": "info",
+            "suggestion": (
+                "未命中任何已知布局意图（single_column_flow / list_with_sections / "
+                "form_rows / tab_switch / canvas_chart / amount_header / accordion_groups / badge_overlay）。"
+                "可能是新型形态；若确为新范式，建议沉淀到 recipes_v2.json。"
+            ),
+        })
+
+    return hints
+
+
+def check_v2_param_roles(view, schema, recipes):
+    """检查参数角色是否符合规范（按 v2 抽象规则）。"""
+    hints = []
+    param_roles = recipes.get("paramRoles", {})
+
+    # 检查 list_items 角色：ListLayout 必须有 slotScope=true
+    for c, _ in _walk(view):
+        if c.get("className") != "ListLayout":
+            continue
+        slots = c.get("slots") or []
+        if not slots:
+            continue
+        ss = bool(slots[0].get("slotScope", False)) if isinstance(slots[0], dict) else False
+        if not ss:
+            hints.append({
+                "type": "param_role_violation",
+                "severity": "info",
+                "role": "list_items",
+                "violation": "ListLayout slotScope != true",
+                "suggestion": (
+                    "ListLayout 的 slotScope 必须为 true（v2 styleContract: ListLayout_slotScope_true, hard 级）。"
+                    "否则列表项作用域无法隔离。"
+                ),
+            })
+
+    return hints
+
+
+def check_v2_style_contracts(view, recipes):
+    """检查生成卡是否违反 v2 样式硬契约。"""
+    hints = []
+    contracts = recipes.get("styleContracts", {})
+
+    # Text_font_required
+    text_nodes = [c for c, _ in _walk(view) if c.get("className") == "Text"]
+    if text_nodes:
+        missing_font = 0
+        for t in text_nodes:
+            style_keys = set()
+            for p in (t.get("style") or {}).get("properties") or []:
+                if isinstance(p, dict):
+                    style_keys.add(p.get("itemKey"))
+            if "font" not in style_keys:
+                missing_font += 1
+        if missing_font:
+            hints.append({
+                "type": "style_contract_violation",
+                "severity": "info",
+                "contract": "Text_font_required",
+                "violations": missing_font,
+                "total_text": len(text_nodes),
+                "suggestion": (
+                    f"{missing_font}/{len(text_nodes)} 个 Text 节点缺 font 组（v2 styleContract: Text_font_required, hard 级）。"
+                    f"渲染器会回退浏览器默认样式（无大小无颜色）。请补 font 组（fontSize + color 至少）。"
+                ),
+            })
+
+    # Canvas_onMeasured_required
+    for c, _ in _walk(view):
+        if c.get("className") == "Canvas":
+            if not _has_event_action(c, "onMeasured"):
+                hints.append({
+                    "type": "style_contract_violation",
+                    "severity": "info",
+                    "contract": "Canvas_onMeasured_required",
+                    "suggestion": (
+                        "Canvas 节点缺 onMeasured 事件（v2 styleContract: Canvas_onMeasured_required, hard 级）。"
+                        "缺则 Canvas 不绘制（一片空白）。"
+                    ),
+                })
+
+    # Root_style_rect_forbidden：根节点宽度由顶层 view.width 承载，
+    # style 里不应再放 rect 组（width）——放重复宽度是冗余/冲突（铁律见 rules.md §九）
+    root_style_keys = set()
+    for p in (view.get("style") or {}).get("properties") or []:
+        if isinstance(p, dict):
+            root_style_keys.add(p.get("itemKey"))
+    if "rect" in root_style_keys:
+        hints.append({
+            "type": "style_contract_violation",
+            "severity": "info",
+            "contract": "Root_style_rect_forbidden",
+            "suggestion": (
+                "Root（view）style 含 rect 组（width）——根节点宽度由顶层 view.width 承载，"
+                "style 里不应再放 rect.width（v2 styleContract: Root_style_rect_forbidden, hard 级）。"
+                "删除根节点的 rect 组，保留 view.width 即可。"
+            ),
+        })
+
+    # Root_outer_radius_required：纯色卡片最外层外圆角应设在 Root（rules.md §九）。
+    # 判定：Root 有纯色背景（backgroundType=01）且 Root 无 borderRadius（或为 0），
+    # 但第一层主容器却设了 borderRadius>0 → 外圆角放错了层级（应上提 Root，内部归零）。
+    def _radius_of(node):
+        for gp in (node.get("style") or {}).get("properties") or []:
+            if isinstance(gp, dict) and gp.get("itemKey") == "borderRadius":
+                for c in (gp.get("itemChildren") or {}).get("properties") or []:
+                    if isinstance(c, dict) and c.get("itemKey") == "borderRadius":
+                        return c.get("itemValue")
+        return None
+
+    root_bg_type = None
+    for gp in (view.get("style") or {}).get("properties") or []:
+        if isinstance(gp, dict) and gp.get("itemKey") == "background":
+            for c in (gp.get("itemChildren") or {}).get("properties") or []:
+                if isinstance(c, dict) and c.get("itemKey") == "backgroundType":
+                    root_bg_type = c.get("itemValue")
+    root_radius = _radius_of(view)
+    first_children = (view.get("components") or []) or ((view.get("slots") or [{}])[0].get("components") or [])
+    if root_bg_type == "01" and (not root_radius or str(root_radius) == "0") and first_children:
+        child_radius = _radius_of(first_children[0])
+        if child_radius and str(child_radius) != "0":
+            hints.append({
+                "type": "style_contract_violation",
+                "severity": "info",
+                "contract": "Root_outer_radius_required",
+                "suggestion": (
+                    f"纯色卡（Root backgroundType=01）最外层外圆角应设在 Root（view.style.borderRadius），"
+                    f"但 Root 无 borderRadius 而第一层容器设了 {child_radius}——重复/错层圆角（rules.md §九）。"
+                    f"把外圆角上提至 Root，第一层容器 borderRadius 归 0。"
+                ),
+            })
+
+    return hints
+
+
+def main():
+    ap = argparse.ArgumentParser(description="基于人力卡规则库的拓扑合规性检查（纯建议层，v2 抽象规律优先）")
+    ap.add_argument("schema", help="schema.json 路径")
+    ap.add_argument("--patterns", default=str(DEFAULT_PATTERNS),
+                    help=f"规则库 JSON 路径（默认 {DEFAULT_PATTERNS}，v2 自动在同目录找 recipes_v2.json）")
+    ap.add_argument("--quiet", action="store_true", help="只输出 hints 数量与摘要")
+    args = ap.parse_args()
+
+    hints, err = check_all(args.schema, args.patterns)
+    if err:
+        print(f"[ERR] {err}", file=sys.stderr)
+        sys.exit(1)
+
+    by_type = {}
+    for h in hints:
+        by_type.setdefault(h["type"], 0)
+        by_type[h["type"]] += 1
+
+    if args.quiet:
+        print(f"hints={len(hints)} by_type={by_type}")
+        return
+
+    print(f"\n[TOPOLOGY CHECK] {args.schema}: {len(hints)} hint(s)")
+    for h in hints:
+        print(f"  [{h['type']}] {h.get('suggestion', '')}")
+    if by_type:
+        print(f"\n  Summary: {by_type}")
+
+
+if __name__ == "__main__":
+    main()