cardbuddy 0.9.1 → 0.11.0

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

@@ -0,0 +1,624 @@
+#!/usr/bin/env python3
+"""
+DSL Schema Validator (hardened)
+
+Validates a generated schema.json for structural correctness and dsl-card
+contract conformance:
+
+  - top-level structure, component tree, unique componentId
+  - known className / property / style keys
+  - itemValueFrom / itemDefaultValue rules
+  - v-show shape (itemValue:{} + itemChildren.properties)
+  - data.json consistency with dictionary.inputParams.defaultValue
+
+When run from inside the repo it loads `vendor/preview/meta/{style,component}-meta.json`
+to validate style itemId groups and the allowed component set dynamically;
+otherwise it falls back to built-in tables.
+
+Usage:
+    python3 validate_schema.py <schema.json>            # validate one card
+    python3 validate_schema.py <schema.json> --no-data   # skip data.json check
+"""
+
+import json
+import os
+import sys
+import time
+from pathlib import Path
+
+# ---------------------------------------------------------------------------
+# Built-in fallbacks (used only if vendor/preview/meta is unavailable)
+# ---------------------------------------------------------------------------
+COMPONENT_TYPES = {
+    "Root", "Row", "Column", "Canvas", "AbsoluteLayout", "MultiColumn",
+    "Text", "Button", "Input", "Icon", "Divider", "Image", "Select", "Option",
+    "ListLayout", "GridLayout", "MultiText", "ViewContainer",
+    "SingleColumn", "CheckGroup", "RadioButton", "ProgressSlider", "Video", "Map"
+}
+
+CONTAINER_TYPES = {
+    "Root", "Row", "Column", "AbsoluteLayout", "MultiColumn",
+    "ListLayout", "GridLayout", "SingleColumn", "CheckGroup", "RadioButton"
+}
+
+STYLE_KEYS = {"rect", "font", "background", "flex", "padding", "margin", "image",
+              "border", "borderRadius", "opacity", "display", "other", "shadow", "transform",
+              "position"}
+
+STYLE_SUB_KEYS = {"width", "height", "color", "fontSize", "fontWeight", "textAlign", "lineHeight",
+                  "fontStyle", "textDecoration", "isMaxLine", "maxLine",
+                  "backgroundType", "backgroundColor", "backgroundImage", "backgroundGradient",
+                  "gap", "align", "alignItems",
+                  "justifyContent", "flexDirection", "flexWrap", "flexShrink",
+                  "paddingTop", "paddingBottom", "paddingLeft", "paddingRight",
+                  "paddingType", "padding",
+                  "marginTop", "marginBottom", "marginLeft", "marginRight", "marginType", "margin",
+                  "borderRadiusType", "borderRadius",
+                  "borderTopLeftRadius", "borderTopRightRadius", "borderBottomLeftRadius", "borderBottomRightRadius",
+                  "isBorder", "borderWidth", "borderColor", "borderStyle", "backgroundImage", "cropMode"}
+STYLE_SUB_KEYS.update({"opacity", "overflow", "isShadow", "borderRadiusType", "backgroundPosition",
+                       "backgroundSize", "backgroundRepeat", "rotate", "shadowColor", "shadowX",
+                       "shadowY", "shadowBlur", "shadowSpread", "left", "top", "right", "bottom"})
+
+PROP_KEYS = {"value", "placeholder", "disabled", "icon", "color", "content", "empty", "itemDefaultValue",
+             "direction", "row-spacing", "edge-insets", "inputType", "maxLength", "align",
+             "column", "item-spacing", "textList", "customClass", "customProps", "customRemarkImg",
+             "message"}
+
+DIRECTIVE_KEYS = {"v-show"}
+EVENT_KEYS = {"onReady", "click", "onMeasured", "action"}
+ACTION_TYPES = {"customAction", "startRouter", "closeAlertCard", "sendAiChatMessage"}
+# 运行时 property.js onPreview 严格按字符串比较 itemValueFrom === '0'/'1'/'2'；
+# 缺失或空串会导致该属性在预览时被**静默丢弃**（背景/内边距/gap/对齐全部失效）。
+# 因此只接受字符串 "0"/"1"/"2"；缺失/空串/数字由 check_value_from 升级为 ERROR。
+ITEM_VALUE_FROM_VALUES = {"0", "1", "2"}
+
+# augment 标志：避免重复扫 meta
+_META_KEYS_AUGMENTED = False
+
+# style-meta 派生：groupKey -> {childKey: childItemId}，用于校验样式子项 itemId 正确性
+# （捕捉 flexDirection 误用 002 而非 006 这类「itemId 存在但放错组」的隐形 bug）。
+_STYLE_MAPS_LOADED = False
+STYLE_GROUP_CHILD_MAP = {}
+
+FLEX_ENUMS = {
+    "justifyContent": {"flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly"},
+    "alignItems": {"flex-start", "flex-end", "center", "stretch", "baseline"},
+    "flexDirection": {"row", "row-reverse", "column", "column-reverse"},
+    "flexWrap": {"nowrap", "wrap", "wrap-reverse"},
+}
+
+# data.json keys that are allowed to differ from inputParams.defaultValue (i18n drift)
+DATA_JSON_TOLERATED_KEYS = {"otherLangLabels"}
+
+# ---------------------------------------------------------------------------
+# Dynamic meta loading
+# ---------------------------------------------------------------------------
+def _meta_dir():
+    """skill 自包含 meta 目录。
+
+    不再依赖仓库根或 package.json 锚点；直接委托给 scripts/lib/paths.py 的 meta_dir。
+    """
+    try:
+        # 同目录下的 lib/paths.py；本文件位于 scripts/validate_schema.py
+        sys.path.insert(0, str(Path(__file__).resolve().parent / "lib"))
+        from paths import meta_dir
+        return meta_dir
+    except Exception:
+        # 极端兜底（如本文件被单独拷出去执行）：使用内置 fallback，跳过动态 meta
+        return Path(__file__).resolve().parent / ".." / "vendor" / "preview" / "meta"
+
+def _augment_keys_from_meta(meta_dir):
+    """
+    从 component-meta.json / action-meta.json 把 PROP_KEYS / EVENT_KEYS / ACTION_TYPES
+    动态 augment 进模块级常量（保留内置值作 fallback）。
+
+    之前：内置白名单只覆盖老组件，新组件（CheckGroup/RadioButton/ProgressSlider/
+    Video/Map/ViewContainer 等）的属性/事件持续报 `Unknown property/event key` 警告
+    （docs/节点编辑问题清单.md #2）。现在从 meta 里把所有 properties.itemKey（含
+    itemChildren 递归）、events.eventKey、actions.actionType、lifecycleEvents.eventKey
+    都并入白名单，消除噪音。
+    """
+    global PROP_KEYS, EVENT_KEYS, ACTION_TYPES
+
+    cm = meta_dir / "component-meta.json"
+    if cm.is_file():
+        try:
+            data = json.load(open(cm, encoding="utf-8"))
+            comps = data.get("components")
+            if isinstance(comps, dict):
+                def walk_item(item):
+                    """递归收集一个属性项及其 itemChildren 的所有 itemKey。"""
+                    if not isinstance(item, dict):
+                        return
+                    ik = item.get("itemKey")
+                    if ik:
+                        PROP_KEYS.add(ik)
+                    for c in item.get("itemChildren") or []:
+                        walk_item(c)
+                    # MultiText 等用 itemList（每段一个属性组）
+                    for entry in item.get("itemList") or []:
+                        for c in entry.get("properties") or []:
+                            walk_item(c)
+
+                for cmeta in comps.values():
+                    for p in cmeta.get("properties") or []:
+                        walk_item(p)
+                    for e in cmeta.get("events") or []:
+                        ek = e.get("eventKey")
+                        if ek:
+                            EVENT_KEYS.add(ek)
+        except Exception:
+            pass
+
+    am = meta_dir / "action-meta.json"
+    if am.is_file():
+        try:
+            data = json.load(open(am, encoding="utf-8"))
+            for a in data.get("actions") or []:
+                at = a.get("actionType")
+                if at:
+                    ACTION_TYPES.add(at)
+            for ev in data.get("lifecycleEvents") or []:
+                ek = ev.get("eventKey")
+                if ek:
+                    EVENT_KEYS.add(ek)
+        except Exception:
+            pass
+
+
+def load_meta():
+    """Return (style_item_ids:set, component_classes:set). Falls back to built-ins.
+
+    副作用：第一次调用时从同一份 meta 文件 augment 进 PROP_KEYS / EVENT_KEYS /
+    ACTION_TYPES（消除新组件的"未知键"误报）。
+    """
+    global _META_KEYS_AUGMENTED
+    style_ids = set()
+    classes = set(COMPONENT_TYPES)
+    meta_dir = _meta_dir()
+    sm = meta_dir / "style-meta.json"
+    cm = meta_dir / "component-meta.json"
+    if sm.is_file():
+        try:
+            data = json.load(open(sm, encoding="utf-8"))
+            for grp in data.get("properties", []):
+                iid = grp.get("itemId")
+                if iid is not None:
+                    style_ids.add(str(iid))
+        except Exception:
+            pass
+    if cm.is_file():
+        try:
+            data = json.load(open(cm, encoding="utf-8"))
+            comps = data.get("components")
+            if isinstance(comps, dict):
+                classes = set(comps.keys())
+        except Exception:
+            pass
+    # 第一次调用时顺便 augment 其它白名单（与 classes/style_ids 同源，省一次 IO）
+    if not _META_KEYS_AUGMENTED:
+        _augment_keys_from_meta(meta_dir)
+        _META_KEYS_AUGMENTED = True
+    return style_ids, classes
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+def check_value_from(item, owner, errors, warnings):
+    """itemValueFrom 缺失/空串 → 运行时静默丢弃该属性（致命），升级为 ERROR。
+
+    根因（property.js L199-224）：onPreview 只在 itemValueFrom 为 '0'/'1'/'2' 时才把
+    属性写进预览产物；否则整条分支不执行，该 style/prop 直接消失。gen-card-test 生成时
+    曾因缺 itemValueFrom 导致背景/内边距/gap/对齐全部失效且旧 validate 因 "" 在白名单里漏报。
+    """
+    value_from = item.get("itemValueFrom")
+    if value_from is None or value_from == "":
+        errors.append(
+            f"Missing/empty itemValueFrom on {owner} — runtime silently drops this property "
+            f"(background/padding/gap/alignment lost). Set '0'(const)/'1'(var)/'2'(image)."
+        )
+        return
+    if value_from not in ITEM_VALUE_FROM_VALUES:
+        warnings.append(f"Unexpected itemValueFrom='{value_from}' in {owner}")
+
+
+def check_directives(comp, errors, warnings, depth, style_ids):
+    cn = comp.get("className", "")
+    for directive in comp.get("directives", []):
+        key = directive.get("itemKey", "")
+        if key and key not in DIRECTIVE_KEYS:
+            warnings.append(f"Unknown directive key '{key}' in component '{cn}' at depth {depth}")
+        check_value_from(directive, f"directive '{key}' of '{cn}'", errors, warnings)
+        if key == "v-show":
+            # Correct shape: itemValue:{} + itemChildren.properties[showType, condition]
+            iv = directive.get("itemValue")
+            if isinstance(iv, dict) and ("showType" in iv or "condition" in iv):
+                warnings.append(f"v-show in '{cn}' at depth {depth} puts showType/condition in itemValue; "
+                                f"use itemChildren.properties instead")
+            child_props = directive.get("itemChildren", {}).get("properties", [])
+            child_keys = [c.get("itemKey") for c in child_props]
+            if "showType" not in child_keys:
+                warnings.append(f"v-show directive in '{cn}' at depth {depth} has no showType child")
+            show_type = None
+            condition = None
+            for c in child_props:
+                if c.get("itemKey") == "showType":
+                    show_type = c.get("itemValue")
+                if c.get("itemKey") == "condition":
+                    condition = c.get("itemValue")
+            if show_type in ("01", "02"):
+                if not isinstance(condition, dict) or not condition.get("expression"):
+                    warnings.append(f"v-show showType='{show_type}' in '{cn}' at depth {depth} "
+                                    f"missing condition.expression")
+                else:
+                    name = condition.get("name")
+                    if name is None or not str(name).strip():
+                        errors.append(f"v-show showType='{show_type}' in '{cn}' at depth {depth} "
+                                      f"condition 缺显示名 name（必填、不能为空；表达式 <15 字符与表达式一致，>=15 字符设合适命名）")
+
+
+def check_eventactions(comp, warnings, depth):
+    cn = comp.get("className", "")
+    for action_index, eventaction in enumerate(comp.get("eventactions", [])):
+        event_key = eventaction.get("event", {}).get("eventKey", "")
+        action_type = eventaction.get("action", {}).get("actionType", "")
+        if event_key and event_key not in EVENT_KEYS:
+            warnings.append(f"Unknown eventKey '{event_key}' in '{cn}' at depth {depth}[eventactions[{action_index}]]")
+        if action_type and action_type not in ACTION_TYPES:
+            warnings.append(f"Unknown actionType '{action_type}' in '{cn}' at depth {depth}[eventactions[{action_index}]]")
+        if action_type == "customAction":
+            properties = eventaction.get("action", {}).get("properties", [])
+            has_function = any(prop.get("itemKey") == "function" for prop in properties)
+            if not has_function:
+                warnings.append(f"customAction in '{cn}' at depth {depth} has no function property")
+
+
+def load_style_maps():
+    """从 style-meta.json 构建 groupKey -> {childKey: childItemId} 映射（只跑一次）。
+
+    用于校验「itemId 存在但放错组」的隐形 bug：例如 flex 组的 flexDirection 子项
+    误用 itemId '002'（实为 alignItems），运行时 restoreProperty 按 itemId 先匹配到
+    alignItems 的 meta，导致 flexDirection 永远取默认值（row），Column 不堆叠。旧
+    validate 因 '002' 全局存在而漏报；本映射能精确识别。
+    """
+    global _STYLE_MAPS_LOADED, STYLE_GROUP_CHILD_MAP, STYLE_KEYS, STYLE_SUB_KEYS
+    if _STYLE_MAPS_LOADED:
+        return
+    meta_dir = _meta_dir()
+    sm = meta_dir / "style-meta.json"
+    if sm.is_file():
+        try:
+            data = json.load(open(sm, encoding="utf-8"))
+            for grp in data.get("properties", []):
+                gk = grp.get("itemKey")
+                if not gk:
+                    continue
+                cm = {}
+                for c in grp.get("itemChildren", []) or []:
+                    ck = c.get("itemKey"); cid = c.get("itemId")
+                    if ck is not None and cid is not None:
+                        cm[str(ck)] = str(cid)
+                STYLE_GROUP_CHILD_MAP[str(gk)] = cm
+                STYLE_KEYS.add(str(gk))
+                STYLE_SUB_KEYS.update(cm.keys())
+        except Exception:
+            pass
+    _STYLE_MAPS_LOADED = True
+
+
+def check_style_props(style, cn, loc, errors, warnings, style_ids=None):
+    """样式组 / 子项校验（Root 与普通节点共用）。
+
+    历史上这段只在 check_components 里跑，Root（view）的 style 从不过检 ——
+    实测事故：模型给 Root 背景猜了 gradientColor / gradientDirection（style-meta 无此键，
+    itemId 落空 → 运行时静默丢弃），子节点会 ERROR、Root 一声不响，模型连试 3 轮渐变全失效
+    都拿不到任何反馈，最后编了个「渲染器顶部蓝条是测量噪声」的理由收工。
+    """
+    if style_ids is None:
+        style_ids, _ = load_meta()
+    load_style_maps()
+    if not style:
+        return
+    for prop in style.get("properties", []):
+        sk = prop.get("itemKey", "")
+        iid = prop.get("itemId")
+        check_value_from(prop, f"style '{sk}' of '{cn}'", errors, warnings)
+        if sk and sk not in STYLE_KEYS:
+            warnings.append(f"Unknown style key '{sk}' in component '{cn}' {loc}")
+        if iid is not None and style_ids and str(iid) not in style_ids:
+            warnings.append(f"Style itemId '{iid}' (key '{sk}') in '{cn}' not in style-meta groups")
+        children = prop.get("itemChildren", {}).get("properties", [])
+        cmap = STYLE_GROUP_CHILD_MAP.get(sk)
+        for child in children:
+            ck = child.get("itemKey", "")
+            cv = child.get("itemValue")
+            if ck and ck not in STYLE_SUB_KEYS:
+                warnings.append(f"Unknown style sub-key '{ck}' in '{sk}' of '{cn}' {loc}")
+            # 样式子项 itemId 必须与 style-meta 中该组的预期 itemId 一致
+            if cmap and ck in cmap and child.get("itemId") is not None \
+                    and str(child.get("itemId")) != cmap[ck]:
+                errors.append(
+                    f"Style '{sk}.{ck}' in '{cn}' {loc} has itemId "
+                    f"'{child.get('itemId')}' but style-meta expects '{cmap[ck]}' "
+                    f"(common bug: flexDirection uses 002 instead of 006)"
+                )
+            # 空 itemId（缩写键 / 自造键未命中 style-meta）→ 运行时静默丢弃，必须 ERROR
+            if child.get("itemId") is not None and str(child.get("itemId")).strip() == "":
+                errors.append(
+                    f"Style '{sk}.{ck}' in '{cn}' {loc} has empty itemId "
+                    f"→ 运行时静默丢弃该样式（缩写键 / 自造键需用 style-meta 原文 itemKey）"
+                )
+            if sk == "flex" and ck in FLEX_ENUMS:
+                if isinstance(cv, str) and cv not in FLEX_ENUMS[ck]:
+                    errors.append(f"Illegal value for flex.{ck} in '{cn}' {loc}: "
+                                  f"'{cv}'. Use one of {sorted(FLEX_ENUMS[ck])}")
+
+
+def check_components(components, errors, warnings, depth=0, style_ids=None, seen_ids=None, stats=None):
+    if style_ids is None:
+        style_ids, _ = load_meta()
+    load_style_maps()
+    if seen_ids is None:
+        seen_ids = set()
+    if stats is None:
+        stats = {"var_props": 0}
+    if depth > 30:
+        warnings.append("Component tree depth exceeds 30, possible infinite nesting?")
+        return
+    for i, comp in enumerate(components):
+        if not isinstance(comp, dict):
+            errors.append(f"Component at depth {depth}[{i}] is not an object")
+            continue
+
+        cn = comp.get("className", "")
+        if not cn:
+            errors.append(f"Component at depth {depth}[{i}] missing 'className'")
+        elif cn not in COMPONENT_TYPES:
+            errors.append(f"Unknown className '{cn}' at depth {depth}[{i}] → 渲染空白（R28）")
+
+        cid = comp.get("componentId")
+        if not cid:
+            errors.append(f"Component '{cn}' at depth {depth}[{i}] missing 'componentId'")
+        else:
+            if cid in seen_ids:
+                errors.append(f"Duplicate componentId '{cid}' in '{cn}' at depth {depth}[{i}]")
+            seen_ids.add(cid)
+
+        check_directives(comp, errors, warnings, depth, style_ids)
+        check_eventactions(comp, warnings, depth)
+
+        # Style keys
+        check_style_props(comp.get("style", {}), cn, f"at depth {depth}[{i}]", errors, warnings, style_ids)
+
+        # Property keys
+        for prop in comp.get("properties", []):
+            pk = prop.get("itemKey", "")
+            check_value_from(prop, f"property '{pk}' of '{cn}'", errors, warnings)
+            if prop.get("itemValueFrom") in ("1", 1):
+                stats["var_props"] = stats.get("var_props", 0) + 1
+            if pk and pk not in PROP_KEYS and not pk.startswith("_"):
+                warnings.append(f"Unknown property key '{pk}' in component '{cn}' at depth {depth}[{i}]")
+            # itemValueFrom "1" (variable/expression) MUST carry itemDefaultValue
+            # (the fallback used by the preview when the binding is undefined).
+            # itemValueFrom "2" is an image/file value and needs no default.
+            if prop.get("itemValueFrom") in ("1", 1) and "itemDefaultValue" not in prop:
+                errors.append(f"Property '{pk}' in '{cn}' at depth {depth}[{i}] has itemValueFrom="
+                              f"'{prop.get('itemValueFrom')}' but no itemDefaultValue")
+
+        # Slots / children
+        if cn in CONTAINER_TYPES or cn == "Select":
+            slots = comp.get("slots", [])
+            if not slots:
+                warnings.append(f"Container '{cn}' at depth {depth}[{i}] has no slots")
+            else:
+                for slot in slots:
+                    for child in slot.get("components", []):
+                        check_components([child], errors, warnings, depth + 1, style_ids, seen_ids)
+        else:
+            slots = comp.get("slots", [])
+            if slots:
+                for slot in slots:
+                    if slot.get("components"):
+                        warnings.append(f"Leaf component '{cn}' at depth {depth}[{i}] has child components")
+
+
+def check_data_json(schema, path, warnings):
+    schema_dir = os.path.dirname(path)
+    data_path = os.path.join(schema_dir, "data.json")
+    if not os.path.isfile(data_path):
+        return
+    try:
+        data = json.load(open(data_path, encoding="utf-8"))
+    except Exception as e:
+        warnings.append(f"data.json beside schema is not valid JSON: {e}")
+        return
+    params = schema.get("dictionary", {}).get("inputParams", [])
+    expected = {p["key"]: p.get("defaultValue") for p in params if "key" in p}
+    if set(expected.keys()) != set(data.keys()):
+        only_in_schema = sorted(set(expected) - set(data))
+        only_in_data = sorted(set(data) - set(expected))
+        msg = "data.json key set differs from inputParams"
+        if only_in_schema:
+            msg += f"; missing in data.json: {only_in_schema}"
+        if only_in_data:
+            msg += f"; extra in data.json: {only_in_data}"
+        warnings.append(msg)
+    else:
+        for k in expected:
+            if k in DATA_JSON_TOLERATED_KEYS:
+                continue
+            if expected[k] != data.get(k):
+                warnings.append(f"data.json['{k}'] != inputParams default (schema={expected[k]!r}, data={data.get(k)!r})")
+
+
+def validate_schema(path, check_data=True):
+    """Return (ok: bool, errors: list, warnings: list)."""
+    errors = []
+    warnings = []
+
+    try:
+        with open(path, 'r', encoding='utf-8') as f:
+            schema = json.load(f)
+    except Exception as e:
+        return False, [f"Cannot read/parse schema: {e}"], warnings
+
+    top_level = {"version", "pageId", "name", "dictionary", "view"}
+    missing = top_level - set(schema.keys())
+    if missing:
+        errors.append(f"Missing top-level fields: {', '.join(sorted(missing))}")
+
+    if "version" in schema and not isinstance(schema["version"], str):
+        errors.append("'version' must be a string")
+
+    params = schema.get("dictionary", {}).get("inputParams", [])
+    if not params:
+        warnings.append("No inputParams defined")
+    else:
+        required_fields = ["key", "name", "type", "defaultValue", "desc", "rule", "children"]
+        valid_types = {"boolean", "string", "number", "object", "array"}
+        for i, p in enumerate(params):
+            for field in required_fields:
+                if field not in p:
+                    errors.append(f"inputParams[{i}] missing '{field}' (key={p.get('key', '?')})")
+            if "type" in p and p["type"] not in valid_types:
+                errors.append(f"inputParams[{i}] type='{p['type']}' is not valid")
+            if "rule" in p and not isinstance(p["rule"], dict):
+                errors.append(f"inputParams[{i}] rule must be an object (key={p.get('key', '?')})")
+            if "children" in p and not isinstance(p["children"], list):
+                errors.append(f"inputParams[{i}] children must be an array (key={p.get('key', '?')})")
+
+    view = schema.get("view")
+    style_ids, _ = load_meta()
+    if not view:
+        errors.append("Missing 'view' (component tree root)")
+    elif not isinstance(view, dict):
+        errors.append("'view' must be an object")
+    else:
+        if view.get("className") != "Root":
+            warnings.append(f"view.className is '{view.get('className')}', expected 'Root'")
+        # 铁律 rules.md §九：Root（view）宽度由顶层 view.width 承载，style 里不放 rect 组（width）。
+        # ERROR 级硬卡点（2026-08-17）：root style 含 rect → 直接拦截（生成器/手写均防）。
+        root_style_keys = {g.get("itemKey") for g in (view.get("style") or {}).get("properties", [])}
+        if "rect" in root_style_keys:
+            errors.append(
+                "view.style must NOT contain 'rect' group (width) — Root 宽度由顶层 view.width 承载，"
+                "style 里放 rect 组是冗余且冲突（铁律 rules.md §九；check_topology 亦报 Root_style_rect_forbidden）"
+            )
+        # Root 的 style 子项同样要过检（否则自造键 / 类型开关缺失在根节点上完全无声）
+        check_style_props(view.get("style", {}), view.get("className") or "Root",
+                          "at view (Root)", errors, warnings, style_ids)
+        if "components" not in view:
+            errors.append("view has no 'components'")
+        else:
+            stats = {"var_props": 0}
+            check_components(view.get("components", []), errors, warnings, style_ids=style_ids, stats=stats)
+            # 数据绑定（itemValueFrom='1'）必须声明在 dictionary.inputParams 中，
+            # 否则数据字典为空、绑定无法解析、绑定树无法编辑。与「无绑定的卡本就无 inputParams」
+            # 区分开：后者仅 warning，前者是 error（校验失败，CI 卡点拦截）。
+            if stats["var_props"] > 0 and not params:
+                errors.append(
+                    f"Schema declares {stats['var_props']} variable-binding(s) (itemValueFrom='1') "
+                    f"but dictionary.inputParams is empty — declare each bound key in "
+                    f"dictionary.inputParams so the data dictionary and bindings resolve correctly"
+                )
+
+    if check_data:
+        check_data_json(schema, path, warnings)
+
+    ok = len(errors) == 0
+    return ok, errors, warnings
+
+
+def _print_result(path, ok, errors, warnings):
+    if errors:
+        print(f"\n[FAIL] {path}: {len(errors)} error(s), {len(warnings)} warning(s):")
+        for e in errors:
+            print(f"  [ERROR] {e}")
+        for w in warnings:
+            print(f"  [WARN]  {w}")
+    elif warnings:
+        print(f"\n[OK]   {path}: no errors, {len(warnings)} warning(s):")
+        for w in warnings:
+            print(f"  [WARN]  {w}")
+    else:
+        print(f"\n[OK]   {path}: schema is valid")
+
+
+def main():
+    args = sys.argv[1:]
+    if not args:
+        print("Usage: python3 validate_schema.py <schema.json> [--no-data] [--json] [--topology]")
+        sys.exit(1)
+
+    positional = [a for a in args if not a.startswith("--")]
+    flags = set(a for a in args if a.startswith("--"))
+    if not positional:
+        print("Usage: python3 validate_schema.py <schema.json> [--no-data] [--json] [--topology]")
+        sys.exit(1)
+
+    path = positional[0]
+    check_data = "--no-data" not in flags
+    as_json = "--json" in flags
+    check_topo = "--topology" in flags
+
+    if not os.path.isfile(path):
+        if as_json:
+            print(json.dumps(
+                {"ok": False, "errors": [f"File not found: {path}"], "warnings": []},
+                ensure_ascii=False,
+            ))
+        else:
+            print(f"[ERROR] File not found: {path}")
+        sys.exit(1)
+
+    t0 = time.time()
+    ok, errors, warnings = validate_schema(path, check_data=check_data)
+    duration_ms = int((time.time() - t0) * 1000)
+
+    # 可选拓扑合规性检查（基于人力卡统计规则库）。
+    # 设计为纯建议层：只在 --topology flag 开启时跑，不修改 ok 判定，不影响默认调用。
+    topology_hints = []
+    if check_topo:
+        try:
+            # 同目录下的 check_topology.py
+            topo_path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "check_topology.py")
+            if os.path.isfile(topo_path):
+                # import 一次（脚本目录已在 sys.path 中作为 ''）
+                import importlib.util
+                spec = importlib.util.spec_from_file_location("check_topology", topo_path)
+                mod = importlib.util.module_from_spec(spec)
+                spec.loader.exec_module(mod)
+                hints, err = mod.check_all(path)
+                if err:
+                    topology_hints.append({"type": "topology_check_error", "message": err})
+                else:
+                    topology_hints = hints
+        except Exception as e:
+            topology_hints.append({"type": "topology_check_error", "message": str(e)})
+
+    if as_json:
+        # 机器可读输出：供 dev-server 中间件 / MCP / CI 直接消费。
+        # 现有人读输出在缺 --json 时保持不变。
+        out = {
+            "path": path,
+            "ok": ok,
+            "errors": errors,
+            "warnings": warnings,
+            "durationMs": duration_ms,
+        }
+        if check_topo:
+            out["topologyHints"] = topology_hints
+        print(json.dumps(out, ensure_ascii=False))
+    else:
+        _print_result(path, ok, errors, warnings)
+        if check_topo and topology_hints:
+            print(f"\n  [TOPOLOGY HINTS] {len(topology_hints)} hint(s) vs 人力卡范式：")
+            for h in topology_hints:
+                print(f"    [{h.get('type','?')}] {h.get('suggestion','')}")
+    sys.exit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()