# Video DSL 体系

本目录包含视频内容生产的核心数据定义：DSL Schema、模板注册表、运行时工具和可复用组件库。

## 目录结构

```
video_dsl/
├── schema/                    # DSL Schema 定义
│   ├── video-dsl-v1alpha1.json          # Video DSL JSON Schema
│   ├── template-binding-v1alpha1.json    # 模板绑定 Schema
│   ├── render-plan-v1alpha1.json         # RenderPlan Schema
│   └── examples/                         # 各模板的 DSL + Binding 示例
│       ├── ai-learning-tips.dsl.json
│       ├── ai-learning-tips.binding.json
│       ├── html-slide-demo.dsl.json
│       └── ...
├── runtime/                   # DSL 运行时工具
│   ├── dsl_validator.py       # DSL Schema 校验
│   ├── template_binder.py     # Scene → Slot 绑定（从 @ab-templates/metadata 读取模板）
│   ├── timeline_compiler.py   # 时间线编译（帧号、字幕切片、旁白分段）
│   ├── asset_adapter.py       # 素材适配器
│   └── prompt_enhancer.py     # Prompt 增强
└── library/                   # 可复用组件库（预留）
    ├── blocks/                # 功能块（如 CTA、数字人、全屏背景）
    ├── components/            # 基础组件（音频、文本、背景、装饰）
    ├── scenes/                # 场景模板（开场钩子、知识点、绘本页）
    └── videos/                # 完整视频模板（英文绘本等）
```

> **注意**：模板元数据（template.json / registry.json）已迁移至独立的 `template-library` 仓库，
> 通过 `@ab-templates/metadata` 包发布。`template_binder.py` 直接读取该包产出的 `registry.json`。

## 核心概念

### 三个中间态

| 中间态 | Schema | 职责 |
|--------|--------|------|
| **Video DSL** | `video-dsl-v1alpha1.json` | 描述视频应该长什么样（场景、素材、旁白） |
| **TemplateBinding** | `template-binding-v1alpha1.json` | 描述 scene 如何映射到模板 slot |
| **RenderPlan** | `render-plan-v1alpha1.json` | DSL 与渲染引擎之间的防腐层 |

### 数据流

```
主题 → [gen-script] → Video DSL
                          ↓
                   [template-registry] → TemplateBinding
                          ↓
                   [render-video] → RenderPlan → MP4 / 剪映草稿
```

## 模板列表

| 模板 ID | 名称 | 适用场景 |
|---------|------|----------|
| `image-slide` | 图片幻灯片 | 通用知识分享、产品介绍（含 tech 科技风变体） |
| `picture-book-en` | 英文绘本视频 | 儿童英语启蒙、双语绘本故事 |
| `image-slideshow` | 图片轮播视频 | 知识分享、种草笔记、技巧总结 |
| `knowledge-slides` | 知识幻灯片 | 方法论拆解、教程讲解、知识科普 |
| `html-slide` | 知识看板 | 知识科普、概念讲解、白板风格内容 |

## runtime 模块说明

| 模块 | 职责 | 被谁调用 |
|------|------|----------|
| `dsl_validator.py` | DSL JSON Schema 校验与参数标准化 | gen-script、render-video |
| `template_binder.py` | 将 DSL scene 映射到模板 slot，生成 TemplateBinding（从 @ab-templates/metadata 读取模板定义） | template-registry |
| `timeline_compiler.py` | 帧号计算、字幕切片（`split_subtitle`）、旁白分段（`segment_narration`） | render-video（跨 skill import） |
| `asset_adapter.py` | 素材格式适配 | render-video |
| `prompt_enhancer.py` | 图片 prompt 增强 | render-video |

**注意**：`timeline_compiler.py` 被 `render-video/scripts/render_video.py` 直接 import，修改函数签名需两个 skill 同步测试。

## library 组件库（预留）

`library/` 目录采用四层分级设计，用于存放可复用的 DSL 片段：

- **components/**：最小粒度的基础组件（音频、文本、背景、头像、装饰、媒体、叠加层）
- **blocks/**：由多个 component 组合而成的功能块（CTA 按钮、数字人区域、全屏背景图、标题区、产品卡片、配音条、双语字幕）
- **scenes/**：完整的场景模板（开场钩子、知识点讲解、绘本封面/内页/结尾、CTA 结尾、数字人口播）
- **videos/**：完整的视频模板（英文绘本等）

组件库当前为目录骨架，后续可填充具体的 JSON 片段供 Agent 和 gen_script.py 复用。

## 示例文件

`schema/examples/` 下包含各模板的完整 DSL + Binding 示例，是 Agent 生成 DSL 时的权威参考：

- `ai-learning-tips.*` — image-slide 模板示例
- `html-slide-demo.*` — html-slide 模板示例
- `knowledge-slides-demo.*` — knowledge-slides 模板示例
- `animal-friends-picturebook.*` — picture-book-en 模板示例

Agent 在为指定模板生成 DSL 时，必须先读取对应示例，按模板原生要求生成。