@remixmate/cli 0.1.0

package/skills/template-bind/scripts/registry_loader.py

@@ -0,0 +1,379 @@
+#!/usr/bin/env python3
+"""
+模板 registry 加载器 - 统一抽象本地文件 / HTTP API 两种数据源。
+
+为什么独立成一个模块：
+  template-bind、render-video 等多个 skill 都要读 registry，集中在一处便于：
+    - 缓存策略一致（HTTP 拉取 5 分钟 TTL + ETag 复用）
+    - 解析顺序一致（环境变量 → 本地文件 → monorepo 回退）
+    - 错误降级一致（HTTP 故障时复用上一次缓存）
+
+环境变量解析优先级（高 → 低）：
+  1. VIDEO_TEMPLATE_REGISTRY        显式本地文件路径（CI / 调试）
+  2. VIDEO_TEMPLATE_REGISTRY_URL    HTTP API（生产，多租户由 ab-api 鉴权过滤）
+  3. monorepo 默认回退               <repo>/template-library/packages/metadata/registry.json
+
+P1.2 — list/detail split (待后端就绪)：
+  100+ 模板时 ``GET /api/template/list`` 应该只返摘要（id / name / aspects /
+  styleTags / status / llmHint），``GET /api/template/{id}`` 按需返完整定义。
+  目前本模块一次拉整个 registry。后端 endpoint 就绪后只需在 ``_fetch_http``
+  下新增 ``_fetch_summary`` / ``_fetch_detail`` 两个函数,``load_registry_data``
+  改成「先拉摘要,触发 ``get_template`` 时再补全」,公共 API 不变。
+  调用方今天用 ``get_template(id)`` / ``list_templates()`` 已经是按需消费的形态,
+  迁移时不需要改任何 caller。
+
+本地 dev 调试开关：
+  VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL=1
+    将 monorepo registry.json 提到 #2 之前 —— 即"软优先"语义：
+      - monorepo 文件存在 → 用本地源码（与 template-library 改动严格一致）
+      - monorepo 文件不存在 → 自动落到 HTTP API，行为与未开启此开关时一致
+    设计意图：让本地开发避开"数据库 template_json 与 template-library 源码不一致"
+    导致的渲染问题，同时不破坏在容器/CI 中错误启用此开关时的鲁棒性。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from functools import lru_cache
+from typing import Optional
+
+from template_paths import monorepo_registry_path
+
+__all__ = [
+    "load_registry_data",
+    "load_registry_indexed",
+    "get_template",
+    "list_templates",
+    "invalidate_cache",
+]
+
+# 默认缓存 TTL（秒）。HTTP 拉取后该时间内不再重新请求。
+_DEFAULT_TTL_SECONDS = 300
+
+# HTTP 请求超时（秒）。registry 体积小，超时设短一些避免阻塞。
+_DEFAULT_HTTP_TIMEOUT = 5
+
+# 缓存目录：默认 /tmp，CI/容器中也能写。
+_CACHE_DIR = os.environ.get(
+    "VIDEO_TEMPLATE_REGISTRY_CACHE_DIR",
+    os.path.join(tempfile.gettempdir(), "ab-template-registry"),
+)
+
+
+def _monorepo_fallback_path() -> str:
+    """monorepo 内 registry.json 的路径（仅 dev / 本地单仓部署用）。
+
+    路径解析现已统一到 ``template_paths.monorepo_registry_path``;
+    本函数保留只是为了让模块内其它函数（``_load_from_url`` 的兜底分支）
+    继续按既有名字调用。
+    """
+    return monorepo_registry_path()
+
+
+def _cache_path_for(url: str) -> str:
+    """根据 URL 生成本地缓存文件路径，URL 不同则缓存隔离。"""
+    digest = hashlib.sha256(url.encode("utf-8")).hexdigest()[:16]
+    return os.path.join(_CACHE_DIR, f"registry-{digest}.json")
+
+
+def _read_cached(cache_file: str) -> Optional[dict]:
+    """读取缓存元数据 + 内容；任何异常都返回 None。"""
+    if not os.path.exists(cache_file):
+        return None
+    try:
+        with open(cache_file, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _write_cached(cache_file: str, payload: dict) -> None:
+    """原子化写入缓存（先写临时文件再 rename，避免半写文件）。"""
+    os.makedirs(os.path.dirname(cache_file), exist_ok=True)
+    tmp_fd, tmp_path = tempfile.mkstemp(dir=os.path.dirname(cache_file))
+    try:
+        with os.fdopen(tmp_fd, "w", encoding="utf-8") as f:
+            json.dump(payload, f, ensure_ascii=False)
+        os.replace(tmp_path, cache_file)
+    except Exception:
+        try:
+            os.unlink(tmp_path)
+        except OSError:
+            pass
+        raise
+
+
+def _fetch_http(url: str, timeout: int) -> dict:
+    """执行 HTTP 请求，自动加 X-Priv-Token / If-None-Match 头。
+
+    支持两种 endpoint 形态：
+      - 老形态（@ab-templates/metadata 静态文件）：GET 返回纯 registry JSON
+      - ab-api 形态：POST 返回 {code, msg, data: <registry>} 包装
+
+    通过环境变量 VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD 切换，默认 POST 适配 ab-api。
+    """
+    cache_file = _cache_path_for(url)
+    cached = _read_cached(cache_file)
+
+    method = os.environ.get("VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD", "POST").upper()
+
+    headers = {"Accept": "application/json"}
+    if method == "POST":
+        headers["Content-Type"] = "application/json"
+    if token := os.environ.get("PRIV_TOKEN", "").strip():
+        headers["X-Priv-Token"] = token
+    if cached and (etag := cached.get("etag")):
+        headers["If-None-Match"] = etag
+
+    body = b"{}" if method == "POST" else None
+    req = urllib.request.Request(url, data=body, headers=headers, method=method)
+
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            raw = resp.read().decode("utf-8")
+            etag = resp.headers.get("ETag", "")
+            parsed = json.loads(raw)
+
+            # ab-api 风格：{code, msg, data} → 取 data；其他场景视作直接 registry
+            if isinstance(parsed, dict) and "data" in parsed and "code" in parsed:
+                if parsed.get("code") not in (0, "0"):
+                    raise RuntimeError(
+                        f"registry HTTP 业务失败: code={parsed.get('code')} msg={parsed.get('msg')}"
+                    )
+                data = parsed["data"]
+            else:
+                data = parsed
+
+            _write_cached(
+                cache_file,
+                {"fetchedAt": time.time(), "etag": etag, "data": data},
+            )
+            return data
+    except urllib.error.HTTPError as e:
+        # 304 Not Modified — 复用缓存内容
+        if e.code == 304 and cached:
+            cached["fetchedAt"] = time.time()
+            _write_cached(cache_file, cached)
+            return cached["data"]
+        raise
+
+
+def _load_from_url(url: str, ttl: int, timeout: int) -> dict:
+    """先看缓存是否在 TTL 内；超期则远程拉取，失败时按以下顺序降级：
+       1. HTTP 缓存（fetchedAt 之后的最后一份成功响应）
+       2. monorepo 本地 registry.json（仅本地 dev 时存在）
+       3. 都没有则抛错
+    """
+    cache_file = _cache_path_for(url)
+    cached = _read_cached(cache_file)
+    now = time.time()
+
+    if cached and (now - cached.get("fetchedAt", 0)) < ttl:
+        return cached["data"]
+
+    try:
+        return _fetch_http(url, timeout)
+    except Exception as exc:
+        # 1. HTTP 故障时降级：有缓存就继续用，写日志告警
+        if cached:
+            print(
+                f"⚠️  registry HTTP 拉取失败，降级使用本地缓存: {exc}",
+                file=sys.stderr,
+            )
+            return cached["data"]
+        # 2. 没缓存再尝试 monorepo fallback（本地 dev / 单仓库部署时这条路一定通）
+        fallback = _monorepo_fallback_path()
+        if os.path.exists(fallback):
+            print(
+                f"⚠️  registry HTTP 拉取失败且无 HTTP 缓存，降级使用 monorepo registry: {exc}",
+                file=sys.stderr,
+            )
+            return _load_from_file(fallback)
+        # 3. 都没有，向上抛
+        raise RuntimeError(
+            f"registry HTTP 拉取失败且无可用缓存 / 本地 fallback: {url} ({exc})"
+        ) from exc
+
+
+def _load_from_file(path: str) -> dict:
+    """从本地文件加载并解析 registry.json。"""
+    with open(path, "r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def _truthy(value: str) -> bool:
+    """统一解析布尔型环境变量：1 / true / yes / on（大小写不敏感）。"""
+    return value.strip().lower() in ("1", "true", "yes", "on")
+
+
+def load_registry_data(
+    *,
+    ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+    http_timeout: int = _DEFAULT_HTTP_TIMEOUT,
+) -> dict:
+    """加载 registry 完整文档（含 version / generatedAt / templates）。
+
+    解析顺序：
+      1. 环境变量 VIDEO_TEMPLATE_REGISTRY 指定的本地文件
+      2. 若 VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL 开启且 monorepo registry 存在，先走本地
+      3. 环境变量 VIDEO_TEMPLATE_REGISTRY_URL 指定的 HTTP API（带缓存）
+      4. monorepo 默认回退（仅本地 dev 有效）
+
+    任何来源都返回相同形状的 dict，调用方按 `data.get("templates", [])` 取列表。
+    """
+    if explicit_path := os.environ.get("VIDEO_TEMPLATE_REGISTRY", "").strip():
+        print(f"[registry_loader] using explicit file: {explicit_path}", file=sys.stderr)
+        return _load_from_file(explicit_path)
+
+    prefer_local = _truthy(os.environ.get("VIDEO_TEMPLATE_REGISTRY_PREFER_LOCAL", ""))
+    fallback = _monorepo_fallback_path()
+
+    if prefer_local and os.path.exists(fallback):
+        print(
+            f"[registry_loader] PREFER_LOCAL=1, using monorepo registry: {fallback}",
+            file=sys.stderr,
+        )
+        return _load_from_file(fallback)
+
+    if url := os.environ.get("VIDEO_TEMPLATE_REGISTRY_URL", "").strip():
+        if prefer_local:
+            # 走到这里说明开启了 PREFER_LOCAL 但 monorepo 文件不存在 —— 例如容器里
+            # 误启用此开关。给出明确告警，避免使用者以为还在用本地源码。
+            print(
+                f"[registry_loader] PREFER_LOCAL=1 but monorepo registry not found"
+                f" ({fallback}), falling back to HTTP: {url}",
+                file=sys.stderr,
+            )
+        else:
+            print(f"[registry_loader] using HTTP registry: {url}", file=sys.stderr)
+        return _load_from_url(url, ttl=ttl_seconds, timeout=http_timeout)
+
+    # 第 ③ 级：monorepo 相对路径兜底。仅在该文件【实际存在】时生效
+    # （私有 monorepo 本地源码可见的场景）。独立开源仓库 clone / npm 安装
+    # 后该路径不存在，这里静默跳过，不抛错、不中断，落到下方的可理解失败。
+    if os.path.exists(fallback):
+        print(
+            f"[registry_loader] using monorepo registry (default fallback): {fallback}",
+            file=sys.stderr,
+        )
+        return _load_from_file(fallback)
+
+    raise RuntimeError(
+        "找不到模板 registry。请设置 VIDEO_TEMPLATE_REGISTRY_URL（ab-api HTTP 接口）"
+        " 并配置有效的 PRIV_TOKEN，或用 VIDEO_TEMPLATE_REGISTRY 指向一份本地"
+        " registry.json。（monorepo 内本地源码可见时会自动走 template-library 兜底。）"
+    )
+
+
+# ════════════════════════════════════════════════════════════════════════════
+# Indexed views — O(1) template-id lookup + status / beta gating
+#
+# `load_registry_data` returns the raw registry document; consumers that
+# repeatedly look up templates by id (validator, render_video, gen-script)
+# used to do `for tpl in registry.get("templates", []): if tpl["templateId"]
+# == X: ...` — O(N) per call. With 100+ templates that becomes 100 scans for
+# every validate() invocation. The helpers below materialize the list into a
+# dict[templateId → tpl] once per process and serve everyone from there.
+#
+# `status` / `version` are P2.2 fields on template.json. When templates
+# don't declare them yet, we treat them as stable + version "0.0.0" — pure
+# additive behavior, no regressions on legacy templates.
+# ════════════════════════════════════════════════════════════════════════════
+
+_DEFAULT_STATUS = "stable"
+_BETA_GATE_ENV = "ENABLE_BETA_TEMPLATES"
+
+
+def _truthy_env(name: str) -> bool:
+    return _truthy(os.environ.get(name, ""))
+
+
+def _resolve_status(tpl: dict) -> str:
+    raw = tpl.get("status")
+    if isinstance(raw, str) and raw.strip():
+        return raw.strip().lower()
+    return _DEFAULT_STATUS
+
+
+def _allowed_statuses() -> set[str]:
+    """Which template statuses the current process is allowed to see.
+
+    Default: only `stable`. Set `ENABLE_BETA_TEMPLATES=1` (or any truthy
+    value) to also include `beta`. `deprecated` is always hidden — callers
+    that explicitly need it can call ``load_registry_data`` directly.
+    """
+    allowed = {"stable"}
+    if _truthy_env(_BETA_GATE_ENV):
+        allowed.add("beta")
+    return allowed
+
+
+@lru_cache(maxsize=4)
+def _indexed_view(allowed_statuses_key: Optional[tuple[str, ...]]) -> dict[str, dict]:
+    """Build (and memoize) ``{templateId: tpl}`` keyed by the allowed-status set.
+
+    The key is a sorted tuple so equal sets map to the same cache entry. The
+    HTTP/file load underneath has its own TTL — this layer only avoids
+    re-iterating the list across the typical 10-100 lookups per render run.
+    """
+    raw = load_registry_data()
+    allow_filter = allowed_statuses_key is not None
+    allowed = set(allowed_statuses_key) if allowed_statuses_key else set()
+    out: dict[str, dict] = {}
+    for tpl in raw.get("templates", []) or []:
+        tid = tpl.get("templateId")
+        if not isinstance(tid, str) or not tid:
+            continue
+        if allow_filter and _resolve_status(tpl) not in allowed:
+            continue
+        out[tid] = tpl
+    return out
+
+
+def load_registry_indexed(
+    *,
+    ttl_seconds: int = _DEFAULT_TTL_SECONDS,
+    http_timeout: int = _DEFAULT_HTTP_TIMEOUT,
+    include_all_statuses: bool = False,
+) -> dict[str, dict]:
+    """Return registry as ``{templateId: template_dict}``.
+
+    Filters by the process-wide status gate unless ``include_all_statuses``
+    is set (used by maintenance tooling like ``check_contracts``). Templates
+    missing ``status`` are treated as ``stable`` for backwards compatibility.
+
+    ``ttl_seconds`` / ``http_timeout`` are accepted for API symmetry with
+    ``load_registry_data`` but the memoization layer below is per-process
+    rather than time-based; call ``invalidate_cache()`` to force a reread.
+    """
+    if include_all_statuses:
+        return _indexed_view(None)
+    return _indexed_view(tuple(sorted(_allowed_statuses())))
+
+
+def get_template(template_id: str, *, include_all_statuses: bool = False) -> Optional[dict]:
+    """Return a single template dict by id, or None when missing/filtered out."""
+    if not template_id:
+        return None
+    return load_registry_indexed(include_all_statuses=include_all_statuses).get(template_id)
+
+
+def list_templates(*, include_all_statuses: bool = False) -> list[dict]:
+    """Return the visible templates as a list (status-filtered)."""
+    return list(load_registry_indexed(include_all_statuses=include_all_statuses).values())
+
+
+def invalidate_cache() -> None:
+    """Drop the indexed-view memoization. Mostly for tests / hot reload.
+
+    Note: the on-disk HTTP cache is independent and respects its own TTL;
+    this only resets the in-process memoization built by ``lru_cache``.
+    """
+    _indexed_view.cache_clear()

package/skills/template-bind/scripts/render_job_client.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+"""
+render_job_client.py — ab-api renderJob 接口 Python 客户端
+
+封装对 ab-api /api/renderJob/* 的调用，供 render_video.py 和
+gen_jianying_draft.py 使用。
+
+认证方式: X-Priv-Token header（与其他 skill 脚本一致）
+接口地址: 由环境变量 MM_BACKEND_API_URL 控制（默认 http://localhost:2999/api）
+"""
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+
+
+def _api_base() -> str:
+    return os.environ.get("MM_BACKEND_API_URL", "http://localhost:2999/api").rstrip("/")
+
+
+def _make_headers(priv_token: str) -> dict:
+    headers = {
+        "Content-Type": "application/json",
+        "X-Priv-Token": priv_token,
+        "x-invoke-skill": "render-video",
+    }
+    agent_name = os.environ.get("AGENT_NAME", "")
+    if agent_name:
+        headers["x-invoke-agent"] = agent_name
+    return headers
+
+
+def _post(path: str, payload: dict, priv_token: str, timeout: int = 30) -> dict:
+    """发送 POST 请求并返回响应 data 字段；失败时抛出 RuntimeError。"""
+    url = f"{_api_base()}{path}"
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(url, data=body, headers=_make_headers(priv_token), method="POST")
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            result = json.loads(resp.read().decode("utf-8"))
+    except urllib.error.HTTPError as e:
+        raise RuntimeError(f"HTTP {e.code} request failed: {path}") from e
+    except urllib.error.URLError as e:
+        raise RuntimeError(f"network request failed ({path}): {e.reason}") from e
+
+    if result.get("code") != 0:
+        msg = result.get("msg") or result.get("message") or "unknown error"
+        raise RuntimeError(f"API returned an error [{path}]: {msg}")
+
+    return result.get("data") or {}
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+
+
+def create_job(priv_token: str, dsl: str = "", dsl_meta: dict = None) -> int:
+    """
+    创建渲染任务。
+
+    Args:
+        priv_token: PrivToken
+        dsl: 完整 DSL JSON 字符串（可选）
+        dsl_meta: DSL 摘要字典（可选，将被序列化为 JSON）
+
+    Returns:
+        jobId (int)
+    """
+    payload: dict = {}
+    if dsl:
+        payload["dsl"] = dsl
+    if dsl_meta:
+        payload["dslMeta"] = dsl_meta
+
+    data = _post("/renderJob/create", payload, priv_token)
+    job_id = data.get("jobId")
+    if not job_id:
+        raise RuntimeError("create render job failed: response has no jobId")
+    return int(job_id)
+
+
+def save_plan(job_id: int, render_plan: str, priv_token: str) -> None:
+    """
+    保存 RenderPlan 到数据库（Phase 1 完成后调用）。
+
+    Args:
+        job_id: 渲染任务 ID
+        render_plan: 完整 RenderPlan JSON 字符串
+        priv_token: PrivToken
+    """
+    _post("/renderJob/savePlan", {"jobId": job_id, "renderPlan": render_plan}, priv_token)
+
+
+def get_plan(job_id: int, priv_token: str) -> str:
+    """
+    从数据库加载 RenderPlan（Phase 2 开始前调用）。
+
+    Args:
+        job_id: 渲染任务 ID
+        priv_token: PrivToken
+
+    Returns:
+        RenderPlan JSON 字符串
+    """
+    data = _post("/renderJob/getPlan", {"jobId": job_id}, priv_token)
+    render_plan = data.get("renderPlan")
+    if not render_plan:
+        raise RuntimeError(f"job {job_id} has no saved RenderPlan; run --resolve-only --save-job first")
+    return render_plan
+
+
+def save_manifest(job_id: int, manifest: dict, priv_token: str) -> None:
+    """
+    保存渲染结果到数据库（渲染完成后调用）。
+
+    Args:
+        job_id: 渲染任务 ID
+        manifest: 渲染结果字典
+        priv_token: PrivToken
+    """
+    _post("/renderJob/saveManifest", {"jobId": job_id, "manifest": manifest}, priv_token)
+
+
+def get_job(job_id: int, priv_token: str) -> dict:
+    """
+    获取渲染任务完整详情。
+
+    Args:
+        job_id: 渲染任务 ID
+        priv_token: PrivToken
+
+    Returns:
+        任务详情字典（含 status / renderPlan / manifest 等）
+    """
+    return _post("/renderJob/get", {"jobId": job_id}, priv_token)
+
+
+# ─── CLI self-test ────────────────────────────────────────────────────────────
+
+if __name__ == "__main__":
+    import argparse
+
+    parser = argparse.ArgumentParser(description="render_job_client self-test tool")
+    parser.add_argument("--priv-token", default=os.environ.get("PRIV_TOKEN", ""), help="PrivToken")
+    parser.add_argument("--get", type=int, metavar="JOB_ID", help="Fetch job details")
+    parser.add_argument("--get-plan", type=int, metavar="JOB_ID", help="Fetch RenderPlan")
+    args = parser.parse_args()
+
+    token = args.priv_token
+    if not token:
+        print("❌ PRIV_TOKEN not configured (or pass --priv-token)", file=sys.stderr)
+        sys.exit(1)
+
+    if args.get:
+        result = get_job(args.get, token)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    elif args.get_plan:
+        plan = get_plan(args.get_plan, token)
+        print(plan)
+    else:
+        parser.print_help()

package/skills/template-bind/scripts/sync_registry.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Write a local registry-cache.json from @ab-templates/metadata.
+
+Usage:
+    python3 scripts/sync_registry.py                    # write cache
+    python3 scripts/sync_registry.py --registry <path>  # use custom registry source
+
+The cache is a lightweight summary for LLM prompts and offline use.
+The authoritative source is template-library/packages/metadata/registry.json.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+import os
+
+# Make video_dsl.runtime importable regardless of CWD.
+_SKILL_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), ".."))
+sys.path.insert(0, _SKILL_DIR)
+
+from video_dsl.runtime.template_binder import sync_registry  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    parser.add_argument(
+        "--registry",
+        default=None,
+        help="Path to @ab-templates/metadata registry.json (auto-detected if omitted)",
+    )
+    parser.add_argument(
+        "--output",
+        default=None,
+        help="Output path for the cache file (default: video_dsl/registry-cache.json)",
+    )
+    args = parser.parse_args()
+
+    out = sync_registry(output_path=args.output, registry_path=args.registry)
+    print(f"wrote {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/template-bind/scripts/template_paths.py

@@ -0,0 +1,72 @@
+"""Centralized monorepo path resolution for template-library artifacts.
+
+Why this module exists
+----------------------
+Before this file landed, every caller that needed to reach into the
+monorepo's ``template-library/`` from inside ``apps/ab-skill/`` had to count
+``..`` segments by hand. The depth differs per call site:
+
+    skills/template-bind/scripts/registry_loader.py        → 5 × ".."
+    skills/template-bind/scripts/check_contracts.py        → 3 × ".."
+    skills/template-bind/video_dsl/runtime/template_binder → 6 × ".."
+    skills/gen-script/scripts/gen_script.py                → 5 × ".."
+    skills/render-video/scripts/render_video.py            → 4 × ".."
+
+Five copies, five chances for an off-by-one bug, and any future directory
+move silently breaks one site without touching the others. This module
+computes the monorepo root **once** from its own location and exposes
+helpers so callers no longer count.
+
+All sibling skills now go through these helpers; the TS handler in
+``src/handlers/template-bind.ts`` keeps its own one-off computation
+because it cannot import this Python module.
+"""
+from __future__ import annotations
+
+import os
+from typing import Optional
+
+__all__ = ["monorepo_root", "monorepo_registry_path", "monorepo_template_src_dir"]
+
+# This file lives at:
+#   <repo>/apps/ab-skill/skills/template-bind/scripts/template_paths.py
+# So the monorepo root is 5 levels up.
+_HERE = os.path.dirname(os.path.abspath(__file__))
+_REPO_ROOT = os.path.normpath(os.path.join(_HERE, "..", "..", "..", "..", ".."))
+
+
+def monorepo_root() -> str:
+    """Absolute path to the ab-platform monorepo root.
+
+    Always returns a string; the caller is responsible for checking
+    ``os.path.isdir(...)`` if the root may genuinely be absent (e.g. when
+    the skill is consumed standalone via the npm package).
+    """
+    return _REPO_ROOT
+
+
+def monorepo_registry_path() -> str:
+    """Path to ``template-library/packages/metadata/registry.json``.
+
+    Always returns the computed path even when the file does not exist —
+    so callers can keep their existing ``os.path.exists(...)`` / try-load
+    branches unchanged. Mirrors the historical behavior of the 4 in-tree
+    helpers it replaces.
+    """
+    return os.path.join(_REPO_ROOT, "template-library", "packages", "metadata", "registry.json")
+
+
+def monorepo_template_src_dir(template_id: str) -> Optional[str]:
+    """Locate a template's source directory under ``template-library``.
+
+    Returns the absolute path **only when the directory exists**; returns
+    ``None`` for the standalone / npm-consumer case where there is no
+    monorepo to reach into. Matches ``gen_script._locate_template_dir``'s
+    historical contract (callers test the result for None).
+    """
+    if not template_id:
+        return None
+    tpl_dir = os.path.join(
+        _REPO_ROOT, "template-library", "packages", "templates", "src", template_id
+    )
+    return tpl_dir if os.path.isdir(tpl_dir) else None

package/skills/template-bind/skill.json

@@ -0,0 +1,20 @@
+{
+  "name": "template-bind",
+  "toolName": "template_bind",
+  "tier": "orchestration",
+  "title": "Template Registry (List-only)",
+  "description": "List all available video templates (templateId / name / aspect ratio / style tags). Template-to-DSL binding is no longer exposed as a separate step — once prepare_video_assets receives a template_id it runs the full DSL→RenderPlan pipeline internally.",
+  "envVars": ["PRIV_TOKEN", "VIDEO_TEMPLATE_REGISTRY", "VIDEO_TEMPLATE_REGISTRY_URL", "VIDEO_TEMPLATE_REGISTRY_HTTP_METHOD"],
+  "entry": { "type": "builtin", "handler": "template-bind" },
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "list_templates": { "type": "boolean", "description": "List available templates (default behavior; also implied when other flags are passed)." },
+      "filter_tag": { "type": "string", "description": "Show only templates whose styleTags contain (or are contained in) this string. Case-insensitive. E.g. 'tech' / '科普' / 'walkthrough'." },
+      "filter_aspect": { "type": "string", "description": "Show only templates that declare this aspect ratio. E.g. '9:16' / '16:9' / '1:1'." },
+      "filter_language": { "type": "string", "description": "Show only templates whose contentLanguage includes this code ('zh' or 'en'). Templates with no declared language are always shown (treated as language-agnostic)." },
+      "include_beta": { "type": "boolean", "description": "Also list templates with status='beta'. Default off (only 'stable' shows). The ENABLE_BETA_TEMPLATES env var has the same effect process-wide." }
+    },
+    "required": []
+  }
+}