# template-registry

CLI 暴露面是「列出可用模板」(`--list-templates`)。把 Video DSL 场景绑到具体模板 / 生成 TemplateBinding 的 Python 逻辑由本 skill 提供为**库**(`scripts/match_template.py`),被 `render-video` / `prepare-video-assets` 通过 `sys.path` 内联 import,**没有独立 CLI**。

## 模板数据来源

模板元数据维护在独立仓库 **template-library**，发布到 ab-api，运行时由本 skill 通过 `scripts/registry_loader.py` 从 **单一数据源（ab-api HTTP）** 加载：

| 来源 | 触发条件 | 适用场景 |
|---|---|---|
| 显式 `VIDEO_TEMPLATE_REGISTRY_URL`（ab-api 接口） | 环境变量非空 + `PRIV_TOKEN` 有效 | 指定后端 |
| 派生默认 URL `<MM_API_BASE_URL>/remotionTemplate/registry` | `VIDEO_TEMPLATE_REGISTRY_URL` 未设置 | 默认（含独立安装 codex / `npm i -g`，默认 `https://api.remixmate.ai/api`） |

只从 ab-api 取数，是为了避免「本地文件 / monorepo 源码 / 数据库」多源并存导致的不一致——私有 / 多租户模板只存在于 ab-api，本地源永远不全。默认 URL **内置在 remixmate-cli 自身**（按 CLI 后端约定 `MM_API_BASE_URL` 推导），不再依赖 ab-agent 等宿主在 spawn 时注入，独立运行即可找到 registry。指向你自己的 ab-api 只需设 `MM_API_BASE_URL`（或直接设 `VIDEO_TEMPLATE_REGISTRY_URL`）并配置 `PRIV_TOKEN`。

HTTP 拉取带磁盘缓存（TTL + ETag/304）；瞬时故障时降级复用同一 URL 的上一份缓存（同源容错，非第二个数据源），无缓存则直接报错。

ab-api 响应包装格式 `{code, msg, data}` 由 `registry_loader._fetch_http` 透明拆封;静态 JSON endpoint 也支持(直接返回 registry 文档)。

> 早期文档曾描述本 skill 通过 `@ab-templates/metadata` npm 包 / monorepo 文件消费 registry —— 这些本地来源已移除，运行时只走 ab-api HTTP。monorepo 文件仅供 `check_contracts.py` / `sync_registry.py` 等 monorepo-only 维护脚本使用。

## 新增模板工作流

新增模板**不需要改 remixmate / template-registry 代码**:

1. 在 template-library 仓库定义新模板(`template.json` + 组件代码)。
2. template-library CI 校验 schema + 契约。
3. 合并后 template-library 的发布流水线将新 registry 推到 ab-api。
4. remixmate 端无需更新——下一次 `--list-templates` 即可看到新模板。

## 契约一致性

template-library 仓库内置契约验证器,确保:

- 每个 `template.json` 中引用的 `compositionId` 都存在于 remotion-renderer 的 `manifest.ts`
- manifest 中的每个 compositionId 都被某个 `template.json` 引用
- 所有 `template.json` 通过 JSON Schema 校验

本地可运行 `check_contracts.py` 做跨仓库一致性检查(从 monorepo `<repo>/remotion-renderer/src/core/compositions/manifest.ts` 读 manifest):

```bash
python3 <SkillDir>/scripts/check_contracts.py
```

## 共享 Python 模块

`scripts/` 是 remixmate 内**跨 skill 共享 Python 代码**的约定位置。当前住户:

| 模块 | 谁在用 | 作用 |
|---|---|---|
| `template_paths.py` | registry_loader / template_binder / gen-script / check_contracts | 统一计算 monorepo / template-library 路径,代替 4 个 caller 各自数 `..` |
| `registry_loader.py` | template-registry / match_template / render-video / gen-script / dsl_validator | 加载 registry(HTTP + cache + file) |
| `match_template.py` | render-video(`auto_bind_template`) | DSL → TemplateBinding 算法 |
| `render_job_client.py` | render-video / export-jianying | ab-api renderJob HTTP 客户端 |
| `check_contracts.py` | 维护脚本 | template-library ↔ remotion-renderer 契约校验 |
| `sync_registry.py` | 维护脚本 | 把 registry 摘要落盘供 LLM prompt 使用 |

sibling skill 通过 `sys.path.insert(0, "<…>/template-registry/scripts")` 然后直接 `import` 模块名,模式见 `render_video.py` 顶部的"Single sys.path setup"段。

## 详细使用说明

完整的 CLI 参数、Props 提取规则、多项卡片配音写法等操作细节请参阅 [SKILL.md](./SKILL.md)。