@remixmate/cli 0.9.6 → 0.9.7

package/skills/template-registry/scripts/verify_props_contract.py

@@ -0,0 +1,273 @@
+#!/usr/bin/env python3
+"""
+脆弱点 6②：propExtractors / requiredProps ↔ 组件实际消费 props 的**双向对账**。
+
+不同于纯静态「consumed - providable」对账（噪声过大：分不清可选/必填、textLayers
+派生、同名变量污染），本校验用**三个无误报的稳健信号**做对账，且复用 render-video
+的真实 `build_binding`（而非重写绑定逻辑），保证与运行时一致：
+
+  A. requiredProps ⊆ produced
+     用真实 dsl-example.json 跑 build_binding，断言每个 slot 声明的 requiredProps
+     都真的进了 props。缺失 = 渲染前会回退通用布局（脆弱点 2 的 slideId 事故类）。
+     —— ERROR
+
+  B. requiredProps ⊆ typeFields
+     slot 声明 required 的 prop，组件 props 类型（entry.props as <T>，<T> 定义在
+     types.ts）里必须有该字段；否则 = 契约自相矛盾（声明必填却无处接收）。
+     —— ERROR
+
+  C. propExtractors keys ⊆ typeFields
+     提取器产出的每个 prop，目标组件类型必须声明；否则 = 死字段 / 漂移（提取器辛苦
+     算出来却没人读，或类型重命名后提取器没跟）。
+     —— WARN
+
+为什么这三个无误报：它们只用「类型声明（含 ?可选信息）」+「requiredProps 显式契约」
++「真实绑定产出」，完全不猜组件源码里的 `props.x` 成员访问（那才是噪声源，且 tsc
+已覆盖「读了类型里没有的字段」）。
+
+与 test-template-pipeline.py 的分工：后者通过 ab-api registry 跑 build_binding，已
+覆盖 A（missingRequiredProps），但**离线 CI 跑不了**（registry_loader 需 ab-api）；
+本模块直接从磁盘读 template.json + types.ts，**无需 ab-api**，且额外提供类型级的
+B/C 对账（别处都没有）。由 scripts/test-props-contract.py 作为 CI 入口驱动。
+
+库接口：
+  verify_template(template_dir) -> {name, errors[], warnings[], info{}}
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+
+# 复用真实绑定逻辑（同目录 sibling 模块）。registry_loader 无 import 期副作用，
+# 不触发 ab-api，故可安全 import。
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from match_template import build_binding  # noqa: E402
+
+
+CAST_RE = re.compile(r"entry\.props\s+as\s+([A-Za-z_$][\w$]*)")
+
+
+def parse_interface_fields(types_src: str) -> dict:
+    """从 types.ts 解析 `export interface Name { ... }` → {Name: {field: optional_bool}}.
+
+    只解析顶层 interface 的顶层成员（足够覆盖模板 props 类型——它们都是扁平接口）。
+    嵌套对象类型按整体跳过（不影响顶层字段名收集）。
+    """
+    result: dict = {}
+    i = 0
+    n = len(types_src)
+    iface_re = re.compile(r"export\s+interface\s+([A-Za-z_$][\w$]*)\s*\{")
+    for m in iface_re.finditer(types_src):
+        name = m.group(1)
+        # 从 `{` 起做花括号配平，截取 body
+        start = m.end() - 1
+        depth = 0
+        j = start
+        while j < n:
+            c = types_src[j]
+            if c == "{":
+                depth += 1
+            elif c == "}":
+                depth -= 1
+                if depth == 0:
+                    break
+            j += 1
+        body = types_src[start + 1 : j]
+        result[name] = _parse_members(body)
+    return result
+
+
+def _parse_members(body: str) -> dict:
+    """解析接口 body 顶层成员名 + 是否可选。嵌套 { } 整体跳过。"""
+    fields: dict = {}
+    i = 0
+    n = len(body)
+    # 移除注释，避免把注释里的标识符当成员
+    body = re.sub(r"/\*.*?\*/", "", body, flags=re.S)
+    body = re.sub(r"//[^\n]*", "", body)
+    n = len(body)
+    # 按顶层切分：在 depth==0 处遇到 `;` 或 `\n` 视为成员边界
+    member_re = re.compile(r"([A-Za-z_$][\w$]*)\s*(\??)\s*:")
+    depth = 0
+    seg_start = 0
+    segments = []
+    for k, c in enumerate(body):
+        if c in "{([":
+            depth += 1
+        elif c in "})]":
+            depth -= 1
+        elif c in ";\n" and depth == 0:
+            segments.append(body[seg_start:k])
+            seg_start = k + 1
+    segments.append(body[seg_start:])
+    for seg in segments:
+        seg = seg.strip()
+        if not seg:
+            continue
+        mm = member_re.match(seg)
+        if mm:
+            fields[mm.group(1)] = mm.group(2) == "?"
+    return fields
+
+
+def resolve_slot_def(slot_mapping: dict, purpose: str) -> dict:
+    slot_def = slot_mapping.get(purpose) or slot_mapping.get("default") or {}
+    visited = set()
+    while isinstance(slot_def, dict) and "$ref" in slot_def:
+        ref = slot_def["$ref"]
+        if ref in visited:
+            break
+        visited.add(ref)
+        slot_def = slot_mapping.get(ref) or {}
+    return slot_def
+
+
+def verify_template(tdir: str) -> dict:
+    """对单个模板目录做 A/B/C 对账，返回 {errors:[], warnings:[], info:{}}。"""
+    name = os.path.basename(tdir.rstrip("/"))
+    errors: list = []
+    warnings: list = []
+    info: dict = {}
+
+    tpl_path = os.path.join(tdir, "template.json")
+    with open(tpl_path, "r", encoding="utf-8") as f:
+        tpl = json.load(f)
+
+    slot_mapping = tpl.get("slotMapping", {}) or {}
+    compositions = tpl.get("compositions", []) or []
+
+    # compositionId → componentFile
+    comp_file = {c.get("compositionId"): c.get("componentFile") for c in compositions}
+
+    # componentFile → cast 类型名（entry.props as <T>）
+    file_cast: dict = {}
+    for cf in set(comp_file.values()):
+        if not cf:
+            continue
+        src_path = os.path.normpath(os.path.join(tdir, cf))
+        if not os.path.exists(src_path):
+            warnings.append(f"组件文件不存在：{cf}")
+            continue
+        with open(src_path, "r", encoding="utf-8") as f:
+            src = f.read()
+        casts = CAST_RE.findall(src)
+        file_cast[cf] = casts[0] if casts else None
+        if not casts:
+            warnings.append(f"{cf} 未找到 `entry.props as <Type>`，跳过类型对账")
+
+    # 收集 types.ts（含同目录所有 .ts 里的 interface，稳妥起见全扫）
+    type_fields: dict = {}
+    for root, _dirs, files in os.walk(tdir):
+        for fn in files:
+            if fn.endswith(".ts") and not fn.endswith(".d.ts"):
+                try:
+                    with open(os.path.join(root, fn), "r", encoding="utf-8") as f:
+                        type_fields.update(parse_interface_fields(f.read()))
+                except Exception:
+                    pass
+
+    # compositionId → 类型字段集合
+    def fields_for_comp(comp_id: str):
+        cf = comp_file.get(comp_id)
+        cast = file_cast.get(cf)
+        if cast and cast in type_fields:
+            return set(type_fields[cast].keys()), cast
+        return None, cast
+
+    # ---- B & C：基于 slot 声明（不依赖 dsl-example）----
+    seen_slots = set()
+    for purpose in list(slot_mapping.keys()):
+        sd = resolve_slot_def(slot_mapping, purpose)
+        comp_id = sd.get("compositionId")
+        if not comp_id or comp_id in seen_slots:
+            continue
+        seen_slots.add(comp_id)
+        tfields, cast = fields_for_comp(comp_id)
+        required = sd.get("requiredProps") or []
+        extractor_keys = list((sd.get("propExtractors") or {}).keys())
+
+        if tfields is None:
+            if required or extractor_keys:
+                warnings.append(
+                    f"slot→{comp_id}: 无法解析组件 props 类型({cast})，B/C 跳过"
+                )
+            continue
+
+        # B: requiredProps ⊆ typeFields
+        for rp in required:
+            if rp not in tfields:
+                errors.append(
+                    f"[B] slot→{comp_id}: requiredProps 含 '{rp}'，但组件类型 {cast} 未声明该字段"
+                )
+        # C: propExtractors keys ⊆ typeFields
+        for ek in extractor_keys:
+            if ek not in tfields:
+                warnings.append(
+                    f"[C] slot→{comp_id}: propExtractors 产出 '{ek}'，但组件类型 {cast} 未声明 → 死字段/漂移"
+                )
+
+    # ---- A：用真实 dsl-example 跑 build_binding，requiredProps ⊆ produced ----
+    ex_path = os.path.join(tdir, "dsl-example.json")
+    if os.path.exists(ex_path):
+        with open(ex_path, "r", encoding="utf-8") as f:
+            dsl = json.load(f)
+        binding = build_binding(tpl, dsl)
+        miss_rows = [b for b in binding.get("bindings", []) if b.get("missingRequiredProps")]
+        for b in miss_rows:
+            errors.append(
+                f"[A] scene={b['sceneId']} slot={b['slotId']}: "
+                f"requiredProps 缺失 {b['missingRequiredProps']}（dsl-example 跑真实绑定后仍未产出）"
+            )
+        info["scenes_bound"] = len(binding.get("bindings", []))
+    else:
+        warnings.append("缺 dsl-example.json，A（运行时绑定对账）跳过")
+
+    return {"name": name, "errors": errors, "warnings": warnings, "info": info}
+
+
+def verify_all(base: str) -> int:
+    """对 base/*/template.json 逐个对账，打印报告，返回 error 总数。"""
+    dirs = sorted(
+        os.path.join(base, d)
+        for d in os.listdir(base)
+        if os.path.isdir(os.path.join(base, d))
+        and os.path.exists(os.path.join(base, d, "template.json"))
+    )
+    if not dirs:
+        print(f"未发现模板（{base}/*/template.json）", file=sys.stderr)
+        return 0
+
+    total_err = 0
+    total_warn = 0
+    for tdir in dirs:
+        r = verify_template(tdir)
+        status = "FAIL" if r["errors"] else ("WARN" if r["warnings"] else "PASS")
+        scenes = r["info"].get("scenes_bound", "-")
+        print(f"\n=== {r['name']}  [{status}]  (scenes_bound={scenes}) ===")
+        for e in r["errors"]:
+            print(f"  ERROR {e}")
+        for w in r["warnings"]:
+            print(f"  WARN  {w}")
+        if not r["errors"] and not r["warnings"]:
+            print("  ✓ A/B/C 全部通过")
+        total_err += len(r["errors"])
+        total_warn += len(r["warnings"])
+
+    print(f"\n—— 汇总：{len(dirs)} 模板，{total_err} error，{total_warn} warning ——")
+    return total_err
+
+
+if __name__ == "__main__":
+    import argparse
+
+    ap = argparse.ArgumentParser(description="脆弱点 6② props 双向对账（A/B/C）")
+    ap.add_argument("--templates-dir", required=True, help="template-library/packages/templates/src")
+    args = ap.parse_args()
+    base = os.path.abspath(args.templates_dir)
+    if not os.path.isdir(base):
+        print(f"templates-dir 不存在: {base}", file=sys.stderr)
+        raise SystemExit(2)
+    raise SystemExit(1 if verify_all(base) else 0)

package/skills/template-registry/video_dsl/README.md

@@ -8,7 +8,6 @@
 video_dsl/
 ├── schema/                    # DSL Schema 定义
 │   ├── video-dsl-v1alpha1.json          # Video DSL JSON Schema
-│   ├── template-definition-v1alpha1.json # 模板定义 Schema
 │   ├── template-binding-v1alpha1.json    # 模板绑定 Schema
 │   ├── render-plan-v1alpha1.json         # RenderPlan Schema
 │   └── examples/                         # 各模板的 DSL + Binding 示例

package/skills/video-parser/SKILL.md

@@ -30,7 +30,7 @@ No skill-local env file — the executing process inherits the system environmen
 
 | Env var | Description | Default |
 |---------|-------------|---------|
-| `RENDER_API_URL` | ab-render service base URL (e.g. `http://localhost:3000`). Required. | (none) |
+| `RENDER_API_URL` | ab-render service base URL (e.g. `https://api-render.remixmate.com`). Required. | (none) |
 | `PRIV_TOKEN` | Tianyan token, sent as `X-Priv-Token`. | (none) |
 | `CONVERSATION_ID` | Optional, sent as `x-conversation-id` for file association. | (none) |
 

package/skills/video-parser/scripts/deconstruct_video.py

@@ -13,7 +13,7 @@
   python deconstruct_video.py --url "https://example.com/video.mp4" --json-output
 
 环境变量:
-  MM_API_BASE_URL  - 后端 API 地址（默认: http://localhost:3001/api）
+  MM_API_BASE_URL  - 后端 API 地址（默认: https://api-agent.remixmate.com/api）
   PRIV_TOKEN       - PrivToken 认证令牌
 """
 
@@ -27,7 +27,7 @@ import time
 import urllib.error
 import urllib.request
 
-API_BASE_URL = os.environ.get("MM_API_BASE_URL", "http://localhost:3001/api")
+API_BASE_URL = os.environ.get("MM_API_BASE_URL", "https://api-agent.remixmate.com/api")
 
 PRIVATE_TOKEN = ""  # 在 main() 中通过 resolve_token() 初始化
 SKILL_NAME = "video-parser"

package/skills/video-parser/scripts/parse_via_render.py

@@ -7,7 +7,7 @@
   POST $RENDER_API_URL/parseStatus  → { status, progress, result?, error? }
 
 必要环境变量（由 ab-agent 自动注入）：
-  RENDER_API_URL   ab-render 服务地址，例如 http://localhost:3000
+  RENDER_API_URL   ab-render 服务地址（默认 https://api-render.remixmate.com；指向本地/staging 时覆盖）
   PRIV_TOKEN       ab-api 私有 token
 
 可选环境变量：
@@ -24,7 +24,7 @@ import urllib.request
 
 # ─── 环境变量 ─────────────────────────────────────────────────────────────────
 
-RENDER_API_URL = os.environ.get("RENDER_API_URL", "").rstrip("/")
+RENDER_API_URL = os.environ.get("RENDER_API_URL", "https://api-render.remixmate.com").rstrip("/")
 PRIV_TOKEN = os.environ.get("PRIV_TOKEN", "")
 CONVERSATION_ID = os.environ.get("CONVERSATION_ID", "")
 

package/skills/template-registry/video_dsl/schema/template-definition-v1alpha1.json

@@ -1,247 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "video.dsl/template-definition/v1alpha1",
-  "title": "Template Definition v1alpha1",
-  "description": "视频模板定义规范，描述模板的匹配条件、slot 绑定规则、默认样式和扩展配置。",
-  "type": "object",
-  "required": ["templateId", "name", "version", "slotMapping", "remotionEntry"],
-  "properties": {
-    "templateId": {
-      "type": "string",
-      "pattern": "^[a-z][a-z0-9-]*$",
-      "description": "模板唯一标识，kebab-case"
-    },
-    "name": {
-      "type": "string",
-      "description": "模板显示名称"
-    },
-    "description": {
-      "type": "string",
-      "description": "模板用途说明"
-    },
-    "version": {
-      "type": "string",
-      "pattern": "^\\d+\\.\\d+\\.\\d+$",
-      "description": "语义化版本号"
-    },
-    "supportedAspectRatios": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["16:9", "9:16", "1:1", "4:3", "3:4", "21:9"]
-      },
-      "minItems": 1,
-      "description": "支持的宽高比列表"
-    },
-    "supportedDurations": {
-      "type": "object",
-      "properties": {
-        "min": { "type": "number", "minimum": 0, "description": "最短时长（秒）" },
-        "max": { "type": "number", "minimum": 1, "description": "最长时长（秒）" }
-      },
-      "required": ["min", "max"]
-    },
-    "styleTags": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "风格标签，用于匹配 DSL meta.style"
-    },
-    "scenePatterns": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["opening", "intro", "point", "example", "explanation", "transition", "highlight", "cta", "ending", "default"]
-      },
-      "description": "模板支持的场景 purpose 类型"
-    },
-    "assetRequirements": {
-      "type": "array",
-      "items": {
-        "type": "string",
-        "enum": ["image", "video", "audio", "avatar", "subtitle", "bgm"]
-      },
-      "description": "模板需要的素材类型"
-    },
-    "slotMapping": {
-      "type": "object",
-      "description": "purpose → slot 绑定规则映射，必须包含 default。值可以是完整 SlotDefinition 或 {\"$ref\": \"<purpose>\"} 别名引用另一个 purpose 的定义。",
-      "additionalProperties": {
-        "oneOf": [
-          { "$ref": "#/definitions/SlotDefinition" },
-          { "$ref": "#/definitions/SlotRef" }
-        ]
-      },
-      "required": ["default"]
-    },
-    "defaultTypography": { "$ref": "#/definitions/Typography" },
-    "defaultMotionPreset": {
-      "type": "string",
-      "enum": ["minimal", "smooth", "energetic", "cinematic"],
-      "default": "smooth"
-    },
-    "defaultColorScheme": {
-      "type": "array",
-      "items": { "type": "string" },
-      "description": "默认配色方案 HEX 值列表"
-    },
-    "remotionEntry": {
-      "type": "object",
-      "description": "按宽高比映射 Remotion 根 Composition ID",
-      "additionalProperties": { "type": "string" }
-    },
-    "themeConfig": {
-      "type": "object",
-      "description": "模板专属主题配置，透传给 Remotion Composition",
-      "additionalProperties": true
-    },
-    "imageStyleGuide": {
-      "$ref": "#/definitions/ImageStyleGuide",
-      "description": "图片生成视觉风格指南，用于增强自动生成的 image prompt"
-    },
-    "constraints": {
-      "type": "object",
-      "description": "模板级约束条件",
-      "additionalProperties": true
-    },
-    "extensions": {
-      "type": "object",
-      "description": "模板专属扩展类型声明（如 slideBlockTypes）",
-      "additionalProperties": true
-    },
-    "compositionMap": {
-      "type": "object",
-      "description": "（已废弃）旧版 purpose → compositionId 映射，请迁移到 slotMapping",
-      "additionalProperties": { "type": "string" }
-    },
-    "slotSchema": {
-      "type": "object",
-      "description": "（已废弃）旧版 slot 描述，请迁移到 slotMapping",
-      "additionalProperties": true
-    }
-  },
-  "definitions": {
-    "SlotRef": {
-      "type": "object",
-      "description": "引用另一个 purpose 的 SlotDefinition，消除重复定义",
-      "required": ["$ref"],
-      "properties": {
-        "$ref": {
-          "type": "string",
-          "description": "目标 purpose 名称，如 \"point\" 或 \"cta\""
-        }
-      },
-      "additionalProperties": false
-    },
-    "SlotDefinition": {
-      "type": "object",
-      "required": ["slotId", "compositionId"],
-      "properties": {
-        "slotId": {
-          "type": "string",
-          "description": "模板 slot 标识"
-        },
-        "compositionId": {
-          "type": "string",
-          "description": "对应 Remotion Composition ID"
-        },
-        "description": {
-          "type": "string"
-        },
-        "propExtractors": {
-          "type": "object",
-          "description": "props 提取规则：propName → 提取配置",
-          "additionalProperties": { "$ref": "#/definitions/PropExtractor" }
-        },
-        "requiredProps": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "必需的 props"
-        },
-        "optionalProps": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "可选的 props"
-        }
-      }
-    },
-    "PropExtractor": {
-      "oneOf": [
-        {
-          "type": "object",
-          "description": "从 textLayers 按 role 提取",
-          "required": ["from", "role"],
-          "properties": {
-            "from": { "type": "string", "const": "textLayers" },
-            "role": { "type": "string" }
-          }
-        },
-        {
-          "type": "object",
-          "description": "从 scene 按点分路径提取",
-          "required": ["from"],
-          "properties": {
-            "from": { "type": "string", "description": "点分路径，如 visuals.background.assetRef" }
-          }
-        }
-      ]
-    },
-    "Typography": {
-      "type": "object",
-      "properties": {
-        "titleFont": { "type": "string" },
-        "bodyFont": { "type": "string" },
-        "titleSize": { "type": "integer" },
-        "bodySize": { "type": "integer" },
-        "primaryColor": { "type": "string" },
-        "secondaryColor": { "type": "string" }
-      }
-    },
-    "ImageStyleGuide": {
-      "type": "object",
-      "description": "图片生成视觉风格指南",
-      "properties": {
-        "baseStyle": {
-          "type": "string",
-          "description": "基础视觉风格描述，追加到所有 prompt 末尾"
-        },
-        "colorDirective": {
-          "type": "string",
-          "description": "色彩方向指令（文字描述，非 HEX）"
-        },
-        "negativePrompt": {
-          "type": "string",
-          "description": "全局负向提示词，描述不希望出现的元素"
-        },
-        "guidanceScale": {
-          "type": "number",
-          "description": "推荐引导系数（如 7.5），控制生成图片对 prompt 的遵循程度"
-        },
-        "purposeOverrides": {
-          "type": "object",
-          "description": "按场景 purpose 覆盖的风格配置",
-          "additionalProperties": {
-            "$ref": "#/definitions/PurposeStyleOverride"
-          }
-        }
-      }
-    },
-    "PurposeStyleOverride": {
-      "type": "object",
-      "description": "针对特定 purpose 的风格覆盖",
-      "properties": {
-        "promptTemplate": {
-          "type": "string",
-          "description": "prompt 模板，支持 {narration_summary} {topic} {style_suffix} {scene_title} 变量"
-        },
-        "styleModifier": {
-          "type": "string",
-          "description": "追加的风格修饰符"
-        },
-        "negativePrompt": {
-          "type": "string",
-          "description": "覆盖全局的负向提示词"
-        }
-      }
-    }
-  }
-}