@remixmate/cli 0.9.71 → 0.9.73

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

@@ -1,4 +1,4 @@
-"""Portable stdlib-only context and opt-in stderr diagnostics; never writes stdout."""
+
 import json
 import os
 import re

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

@@ -1,39 +1,39 @@
-"""
-template-registry 库模块 — DSL → TemplateBinding 的纯函数实现。
 
-仅作为 Python library 被 render-video 的 render_video.py / gen-script 的
-gen_script.py 通过 `sys.path.insert` 后 `import match_template` 引入；
-对外不暴露 binding CLI。template-registry skill 的 `--list-templates` 入口由
-sibling 的 `list_templates.py` 实现（它复用 registry_loader 的统一加载 +
-状态门控），两者共享同一份 registry 读取逻辑，无 TS 侧重复实现。
 
-提供的公共接口：
-  load_registry()                 → list[dict]   模板列表
-  load_full_template(template)    → dict         模板完整定义（registry 自带，原样返回）
-  build_binding(template, dsl)    → dict         DSL → TemplateBinding
-"""
+
+
+
+
+
+
+
+
+
+
+
+
 
 from registry_loader import load_registry_data
 import sys
 
 
 def load_registry() -> list:
-    """Load template list via the unified registry loader."""
+
     return load_registry_data().get("templates", [])
 
 
 def load_full_template(template: dict) -> dict:
-    """Load the full template definition.
 
-    Since the metadata registry.json now contains the complete template
-    definition (including slotMapping, compositions, etc.), this simply
-    returns the template as-is.
-    """
+
+
+
+
+
     return template
 
 
 def _resolve_slot_def(slot_mapping: dict, purpose: str) -> dict:
-    """Resolve a slotMapping entry, following $ref chains (max depth 10)."""
+
     slot_def = slot_mapping.get(purpose) or slot_mapping.get("default") or {}
     visited: set = set()
     while "$ref" in slot_def:
@@ -46,15 +46,15 @@ def _resolve_slot_def(slot_mapping: dict, purpose: str) -> dict:
 
 
 def _extract_prop(scene: dict, extractor: dict):
-    """Extract a single prop value from a scene using an extractor definition.
 
-    Supports two extractor patterns:
-      { "from": "textLayers", "role": "headline" }   – search textLayers by role
-      { "from": "visuals.background.assetRef" }      – dotted-path traversal
-    """
+
+
+
+
+
     source = extractor.get("from", "")
 
-    # textLayers extractor
+
     if source == "textLayers":
         role = extractor.get("role", "")
         for tl in scene.get("textLayers") or []:
@@ -62,7 +62,7 @@ def _extract_prop(scene: dict, extractor: dict):
                 return tl.get("content")
         return None
 
-    # Dotted-path extractor
+
     val = scene
     for part in source.split("."):
         if not isinstance(val, dict):
@@ -72,7 +72,7 @@ def _extract_prop(scene: dict, extractor: dict):
 
 
 def build_binding(template: dict, dsl: dict) -> dict:
-    """Build a TemplateBinding from template and DSL."""
+
     bindings = []
     slot_mapping = template.get("slotMapping", {})
 
@@ -84,41 +84,41 @@ def build_binding(template: dict, dsl: dict) -> dict:
         comp_id = slot_def.get("compositionId", "GenericScene")
         slot_id = slot_def.get("slotId", f"{purpose}-slot")
 
-        # 用模板的 propExtractors 提取 props
+
         props = {}
         for prop_name, extractor in slot_def.get("propExtractors", {}).items():
             val = _extract_prop(scene, extractor)
             if val is not None:
                 props[prop_name] = val
 
-        # P1.3: props 提取仅保留两条路径——
-        #   (1) 显式 propExtractors（上面的 _extract_prop 调用）
-        #   (4) customPayload 全字段透传（顶层 + templateData）— 模板内部 schema
-        # 去掉了原来的"白名单同名隐式透传"两层 fallback，因为它们让"字段写在哪"
-        # 这个问题变得不可预测：同一字段写在 optionalProps + propExtractors
-        # 里时优先级会冲突，让 AI 反复出错。
-        #
-        # 顶层透传是必要的：DSL 示例（hermes-agent-purple / vibe-coding 等）以
-        # `customPayload.slideId` 顶层声明 slide id，而 html-slide 模板的
-        # `propExtractors.slideId` 只声明从 templateData.slideId 取值。如果不
-        # 同时透传顶层，slideId 就会缺失，html-slide 的 `point` slot 把
-        # slideId 设为 requiredProps，缺失会导致 React 端回退到通用「标题 +
-        # 字幕」兜底样式，所有场景看起来都是同一个布局。
+
+
+
+
+
+
+
+
+
+
+
+
+
         custom = scene.get("customPayload") or {}
         template_data = custom.get("templateData") or scene.get("templateData") or {}
 
-        # 脆弱点 3：双通道冲突检测。同一字段名既声明在 slot 的 propExtractors，
-        # 又被 customPayload 的全字段透传命中时，来源二义：propExtractors 永远赢
-        # （下面 `k not in props` 透传），但如果 extractor 返回 None、值又恰好在
-        # payload 里，作者会误以为"是 payload 生效"，反之亦然。html-slide 的
-        # slideId 事故正是此类——extractor 读 `templateData.slideId`，DSL 却把值
-        # 写在 `customPayload.slideId` 顶层。
-        #
-        # 仅标记**真正的位置冲突**，避开误报：当 extractor 的 `from` 恰好指向
-        # `templateData.<同名>` 时，templateData 里出现该字段是它的**法定来源**，
-        # 不算"写错位置"，跳过。其余命中（顶层透传、或 templateData 透传但 extractor
-        # 从别处取值）才算冲突。只记录 + warning，不改透传行为；CI 的
-        # test-template-pipeline.py 据此浮出去重提示。
+
+
+
+
+
+
+
+
+
+
+
+
         extractors = slot_def.get("propExtractors", {}) or {}
         top_keys = {k for k in custom.keys() if k != "templateData"}
         dual_channel = []
@@ -130,7 +130,7 @@ def build_binding(template: dict, dsl: dict) -> dict:
                 dual_channel.append(k)
         dual_channel = sorted(dual_channel)
 
-        # 先注入 templateData.* 再注入顶层 customPayload.*，让顶层覆盖同名值
+
         for k, v in template_data.items():
             if k not in props:
                 props[k] = v
@@ -140,16 +140,16 @@ def build_binding(template: dict, dsl: dict) -> dict:
             if k not in props:
                 props[k] = v
 
-        # animationHints 可能为 null
+
         anim = scene.get("animationHints") or {}
         entrance = anim.get("entrance", "fade")
         transition_type = entrance if entrance != "none" else "cut"
 
-        # requiredProps 完整性：slotMapping 声明的 requiredProps 必须都已进 props。
-        # 这里只**记录**缺失（不抛错，保持渲染行为不变）；CI 的
-        # test-template-pipeline.py 据此断言「requiredProps 齐全」并 fail loud，
-        # 避免历史上「声明了 requiredProps 却静默缺失 → React 端回退通用布局」的事故
-        # （见 template-json-design.md 脆弱点 2）。是否升级为渲染前硬失败属后续决策。
+
+
+
+
+
         required_props = slot_def.get("requiredProps") or []
         missing_required = [p for p in required_props if p not in props]
 
@@ -174,33 +174,33 @@ def build_binding(template: dict, dsl: dict) -> dict:
             )
         bindings.append(binding_row)
 
-    # P1.2: 不再做 screen-walkthrough 专属的截断 / 兜底。模板的 propExtractors
-    # 已声明 titleText ← textLayers[role=headline]、projectName ← textLayers[role=subheadline]，
-    # gen_script 在每个场景都填入了 headline / subheadline，因此 props 由提取器
-    # 直接产出，不再需要后处理。
+
+
+
+
 
     typography = template.get("defaultTypography", {})
     motion = template.get("defaultMotionPreset", "smooth")
     colors = template.get("defaultColorScheme", [])
 
-    # 用户选中的字体（DSL 的 global.font）。这里只是把不透明 key 折进 typography，
-    # 真正的解析（uniqId → 排印家族名 + 字重文件）在 ab-render 侧完成。
-    #
-    # 优先级见 ab-platform/docs/product/creation/font-selection-design.md §13.3：
-    #   用户选择 > variant.defaultFontId（预留档位，当前恒为空）
-    #     > template.defaultTypography.bodyFont（现状裸 family 名）> 模板 theme 字栈
-    # 下面的 variant 合并在此之后执行，所以 fontId 单独在合并后再写回，
-    # 避免被 variant 的 defaultTypography 覆盖掉。
+
+
+
+
+
+
+
+
     user_font_id = ((dsl.get("global", {}) or {}).get("font", {}) or {}).get("fontId")
 
-    # --- variant selection（确定性）---
-    # 优先级：
-    #   1) DSL 显式声明 — meta.templateVariant / meta.variant / renderHints.templateVariant
-    #   2) meta.style 与 variant.styleTags 的**分级**匹配（精确 > 整段包含 > token 子串）
-    # 旧实现按 dict 遍历顺序「命中第一个」，多义时结果不稳定；现改为：
-    #   - 按 variant id 排序遍历（消除顺序依赖）；
-    #   - 取匹配等级最高（tier 数最小）的 variant；
-    #   - 同一最高等级有多个候选 → 记歧义、取排序首个，并把理由写进 variantReason。
+
+
+
+
+
+
+
+
     variant_id = None
     variant_reason = None
     meta = dsl.get("meta", {}) or {}
@@ -218,7 +218,7 @@ def build_binding(template: dict, dsl: dict) -> dict:
     elif variants:
         raw_style = (meta.get("style") or "").strip().lower()
         if raw_style:
-            # token 化：整段 + 分隔符拆分 + 单中文字符级
+
             s = raw_style
             for sep in [",", "，", ";", "；", " ", "/", "·", "、"]:
                 s = s.replace(sep, ",")
@@ -232,10 +232,10 @@ def build_binding(template: dict, dsl: dict) -> dict:
                     if "\u4e00" <= ch <= "\u9fff":
                         tokens.add(ch)
 
-            # 为每个 variant 算最佳匹配等级（1 最强）
-            #   tier 1: 某 style token 与某 tag 完全相等
-            #   tier 2: 整段 raw_style 与某 tag 互为子串（整体短语级）
-            #   tier 3: 某 token 与某 tag 互为子串（细粒度，最宽松）
+
+
+
+
             by_tier: dict = {}
             for vid in sorted(variants.keys()):
                 vtags = [str(t).strip().lower() for t in (variants[vid].get("styleTags") or []) if str(t).strip()]
@@ -251,7 +251,7 @@ def build_binding(template: dict, dsl: dict) -> dict:
 
             if by_tier:
                 best_tier = min(by_tier.keys())
-                winners = by_tier[best_tier]  # 已按 vid 排序
+                winners = by_tier[best_tier]
                 variant_id = winners[0]
                 if len(winners) > 1:
                     variant_reason = (
@@ -278,7 +278,7 @@ def build_binding(template: dict, dsl: dict) -> dict:
         if vcolors:
             colors = vcolors
 
-    # 用户的字体选择压过 variant 默认值（§13.3 的优先级第一档），所以写在合并之后。
+
     if isinstance(user_font_id, str) and user_font_id.strip():
         typography = {**typography, "fontId": user_font_id.strip()}
 

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

@@ -1,41 +1,41 @@
 #!/usr/bin/env python3
-"""Fill a template-declared ``customPayload`` field from a source document, by reference.
-
-问题（2026-09-23 线上 conv_Sesw2g8oM81 的根因）
----------------------------------------------
-``ppt-to-video`` 要求每个场景都有 ``customPayload.slide`` —— 一整页 PPT 的节点树、
-坐标、配色、beats。这份数据只有一个合法产出方（ab-render 的 ``/extract`` layout 层），
-而它**体积大到不能过模型**：一页带内嵌图标可达几百 KB，23 页就是好几 MB。
-
-于是模板的 llmHint 写着「把返回的 slides[i].slide 整个填进 customPayload.slide」，
-doc-parse 的 SKILL.md 写着「feed slides[i] straight into customPayload.slide」，而实际
-链路是：doc_parse 把全量写进本地文件 → 模型没有任何文件读取工具 → 拿不到 → 
-prepare_video_assets 报 ``customPayload.slide (required)`` ×N。模型无论怎么改都过不了。
-
-解法
-----
-**不让这份数据过模型**。DSL 里只留一个引用（``meta.sourceDocument``），skill 侧在
-校验之前自己去把全量取回来填进每个场景。模型负责的是它真正能负责的东西：旁白、
-场景与页的对应关系、以及 mode 的下压。
-
-这与 ``extractCustomPayloadOverrides`` / ``extractNarrationOverrides`` 是同一类教训的
-第三次：**合并层丢掉了数据，而下游报的错指向模型**。前两次丢的是 slideId 和 items。
-
-模板怎么声明
------------
-``template.json`` 的 ``capabilities.payloadHydration``::
-
-    "payloadHydration": {
-      "payloadField": "slide",        # 要填的 customPayload 字段名
-      "source": "doc-extract",        # 数据来源（目前只有这一个）
-      "docKind": "pptx",
-      "fields": "content,layout",     # 传给 /extract 的层
-      "indexField": "slideIndex"      # 场景→页的映射键（写在 customPayload 里）
-    }
 
-不写 ``if template_id == "ppt-to-video"``（AGENTS.md 明令禁止）：任何模板声明了这一段
-就自动获得同样的行为。
-"""
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
 
 from __future__ import annotations
 
@@ -45,7 +45,7 @@ from typing import Callable, Optional
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-from doc_extract import (  # noqa: E402
+from doc_extract import (
     DocExtractError,
     extract_document,
     slides_by_index,
@@ -57,29 +57,29 @@ DEFAULT_INDEX_FIELD = "slideIndex"
 
 
 def declared_subfields(template_config: Optional[dict], payload_field: str) -> Optional[set[str]]:
-    """模板为 ``customPayload.<payload_field>`` 声明的子字段名集合。
 
-    注入必须按这个集合**投影**，不能把抽取器返回的整个对象原样塞进去 ——
-    两边的字段集根本不是一回事：
 
-      抽取器返回(每页)  slideIndex / title / text / rawNotes / verdict / coverage /
-                        flags / nodes / beats / mode / modeReason / ambientIds /
-                        background / recommendedSec / canvas …
-      模板声明(slide)    nodes / beats / mode / modeReason / ambientIds /
-                        background / recommendedSec / canvas
 
-    前者多出来的那些是**内容层与抽取器自己的记账字段**（备注原文、质检结论、覆盖率），
-    渲染端一个都不读。而 ``dsl_validator._check_custom_payload_fields`` 会逐字段核对
-    声明表，遇到没声明的就报「the slide does not read 'x' — the value is silently
-    dropped」并整单拒绝。2026-09-23 线上 conv_StrnauS7TaZNUQV4BfLX 就是这样：
-    注入明明成功（23/23 页），却因为多了 5 个字段被校验整单拒掉，而且**重试必然复现**。
 
-    为什么用投影而不是写个黑名单：抽取器以后再加字段（verdict / coverage 就是后加的）
-    黑名单就会再漏一次。声明表是渲染端真正读的那一份，按它投影才不会二次失效。
 
-    声明表读不到时返回 None = 不投影。这与校验层的行为一致：没有
-    ``customPayloadSchema`` 时它也不查字段名，所以不投影不会引入新的失败。
-    """
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     if not template_config:
         return None
     cps = template_config.get("customPayloadSchema")
@@ -95,21 +95,21 @@ def declared_subfields(template_config: Optional[dict], payload_field: str) -> O
 
 
 class HydrationError(RuntimeError):
-    """注入失败。message 必须直接告诉调用方下一步做什么。
+    pass
+
+
+
+
 
-    这个类存在的全部意义是替换掉 ``customPayload.slide (required)`` ×20 那种报错 ——
-    它说的是"某个字段没填"，而真相是"这个字段的数据源没有通路"，两者要采取的行动
-    完全不同，而模型只看得到前者。
-    """
 
 
 def hydration_spec(template_config: Optional[dict]) -> Optional[dict]:
-    """读 ``capabilities.payloadHydration``；未声明 / 声明无效返回 None。
 
-    宽容读取：一个写坏的 template.json 不该让所有模板的渲染一起失败。但
-    ``source`` 认不出来时要报错而不是静默跳过 —— 静默跳过会退回到「必填字段缺失」
-    那条死路，也就是这个模块本来要修掉的东西。
-    """
+
+
+
+
+
     caps = (template_config or {}).get("capabilities")
     if not isinstance(caps, dict):
         return None
@@ -140,16 +140,16 @@ def hydration_spec(template_config: Optional[dict]) -> Optional[dict]:
 
 
 def source_document_ref(dsl: dict, override_url: Optional[str] = None) -> Optional[dict]:
-    """取 DSL 里的源文件引用。``override_url`` 优先（CLI 显式传入时）。
 
-    位置是 ``meta.sourceDocument`` 而不是场景级：一条片子对一份源文件，写在场景里
-    会得到 23 份同样的 URL，还得处理它们互相矛盾的情况。
 
-    为什么是 ``meta``：ab-agent 的合并层（``applyNarrationToSkeleton``）以 gen_script
-    骨架为基底，只从模型提交的 DSL 里搬 narration 与 customPayload，``meta`` / ``global``
-    归骨架所有。所以写在 meta 的引用能活着穿过合并层，而模型自己往 dsl_json 里写
-    ``meta.sourceDocument`` 会被丢掉 —— 引用必须在 gen_script 那一步就进骨架。
-    """
+
+
+
+
+
+
+
+
     if override_url:
         return {"url": override_url}
     meta = dsl.get("meta")
@@ -178,16 +178,16 @@ def hydrate_dsl(
     override_url: Optional[str] = None,
     log: Optional[Callable[[str], None]] = None,
 ) -> list[str]:
-    """把源文件的每一页填进对应场景的 ``customPayload.<payloadField>``。
 
-    返回一份给人看的报告行列表（调用方自己决定打到哪）。什么都没做时返回空列表。
 
-    映射规则：场景的 ``customPayload.<indexField>`` 是 1-based 页号，缺省按场景顺序
-    取第 i 页。显式页号优先 —— 用户可能只讲其中几页，或者把两页并成一个场景。
 
-    已有值不覆盖：场景里已经有 ``customPayload.slide`` 时跳过。直接调 CLI 的调试流程
-    会手动塞一份进去，把它冲掉等于让调试者的输入人间蒸发。
-    """
+
+
+
+
+
+
+
     emit = log or (lambda _msg: None)
 
     spec = hydration_spec(template_config)
@@ -244,13 +244,13 @@ def hydrate_dsl(
     filled = 0
     missing: list[str] = []
 
-    # 按模板声明投影。抽取结果里混着内容层与抽取器记账字段，渲染端一个都不读，
-    # 而校验层见到未声明字段会整单拒绝（见 declared_subfields 的说明）。
+
+
     allowed = declared_subfields(template_config, field)
     dropped: set[str] = set()
 
-    # 页号只有在模板**声明**了它的时候才写回去。没声明就是未知字段，写了会被校验
-    # 拒掉 —— 这正是上一版的第二个错：既投影不足，又多写了一个 customPayload.slideIndex。
+
+
     index_is_declared = index_field in (declared_subfields(template_config, index_field) or ())
     if not index_is_declared:
         cps = (template_config or {}).get("customPayloadSchema")
@@ -271,7 +271,7 @@ def hydrate_dsl(
         else:
             dropped |= {k for k in page if k not in allowed}
             payload[field] = {k: v for k, v in page.items() if k in allowed}
-        # 留下"这一场用的是第几页"的痕迹 —— 仅当模板声明了这个字段。
+
         if index_is_declared:
             payload.setdefault(index_field, page_no)
         filled += 1
@@ -283,15 +283,15 @@ def hydrate_dsl(
         f"{source_meta.get('name', 'the source document')}"
     )
     if dropped:
-        # 说清丢了什么：这些是内容层/记账字段，渲染端本来就不读。写出来是为了
-        # 抽取器哪天把一个**该读**的字段也归到这里时，有人看得见。
+
+
         report.append(
             f"   （已按模板声明投影，忽略 {len(dropped)} 个渲染端不读的字段："
             f"{', '.join(sorted(dropped)[:8])}）"
         )
 
     if missing:
-        # 页号对不上不是警告而是错误：少一页 = 成片里一个空白场景，而它渲得出来。
+
         raise HydrationError(
             f"{len(missing)} scene(s) point at a page that the source document does not have "
             f"({'; '.join(missing[:5])}"
@@ -300,7 +300,7 @@ def hydrate_dsl(
             f"or fix customPayload.{index_field} on those scenes."
         )
 
-    # 降级记录要顺着传上来 —— 画面上少一块，这里不说就没人知道为什么。
+
     flagged = [
         f"page {no}: {'; '.join(page.get('flags') or [])}"
         for no, page in sorted(pages.items())