# 端到端示例：小明上学（4 句）

本教程用 `examples/script.txt` 从零跑通整条流水线。所有命令在技能根目录执行，Python 一律 `py -3.14`。

## 0. 样例文稿

`examples/script.txt` 内容（4 句，已按句分行）：

```
小明每天要走三公里山路去上学。
有一天，他在路边发现了一条隐藏的小路。
走这条小路，只要十分钟就能到学校！
从此，小明每天都蹦蹦跳跳地去上学。
```

## 1. 配音 + 词级时间戳

```
py -3.14 scripts/tts.py examples/script.txt out/voice.mp3 out/timing.json
```

预期产物：
- `out/voice.mp3` — 约 13~16 秒的中文女声旁白（zh-CN-XiaoxiaoNeural）。
- `out/timing.json` — 词级时间戳，形如：

```json
{
  "voice": "zh-CN-XiaoxiaoNeural",
  "audio_duration": 14.2,
  "words": [
    {"text": "小明", "start": 0.05, "dur": 0.32},
    {"text": "每天", "start": 0.37, "dur": 0.28},
    ...
  ]
}
```

快速核对：`words` 数量应覆盖全部 4 句；最后一个词的 `start+dur` 应接近 `audio_duration`。

## 2. 分幕规划

```
py -3.14 scripts/plan.py examples/script.txt out/timing.json out/plan.json
```

预期产物 `out/plan.json`：`scenes` 数组恰好 4 个元素，每个 scene 含 `id/text/start/end/intent/pose/face/keywords/subtitle/prop`。`start/end` 来自该句首末词的真实时间戳，4 幕首尾相接、无重叠。

### 4 句各自的预期结果

| # | 句子 | intent | pose / face | prop | keywords |
|---|------|--------|-------------|------|----------|
| 1 | 小明每天要走三公里山路去上学。 | walk | walk / calm | path | 三公里 |
| 2 | 有一天，他在路边发现了一条隐藏的小路。 | discover | idle / surprised | path | （无） |
| 3 | 走这条小路，只要十分钟就能到学校！ | excite | cheer / surprised | path | 十分钟 |
| 4 | 从此，小明每天都蹦蹦跳跳地去上学。 | cheer | cheer / calm | （无） | （无） |

### 每幕画面描述

- **幕 1（walk）**：小人用 `walk` 姿势循环行走——髋部 ±22° 反相位摆腿、双臂 ±25° 反向摆臂（yoyo 0.4s，见 rig_spec 的 `_swing` 注释），脚下是简笔山路道具（prop=path），表情 calm。**弹字卡点**：plan.json 里幕 1 的 `keywords` 形如 `{"text": "三公里", "t": 1.8}`——`t` 是"三公里"这个词被念出的那一刻（取自 timing.json 的词 start）；红色大字"三公里"必须恰好在 `t` 这一帧从小人头顶弹出（缩放 0→超调→回弹），不能提前也不能拖后。
- **幕 2（discover）**：小人切到 `idle` 站定，表情切 surprised（圆睁眼+张嘴），头顶可加叹号；旁侧一条虚线小路道具（prop=path）在本幕 `start` 处描线淡入，表现"发现"。
- **幕 3（excite）**：小人 `cheer` 姿势双臂高举（肩 ±165°），表情 surprised。**弹字卡点**：本幕 `keywords` 为 `{"text": "十分钟", "t": ...}`，红色弹字"十分钟"严格落在该词被念出的那一帧，可配一个简笔时钟符号同帧弹出。句尾是感叹号，整句情绪上扬，小人可在句尾小幅跳一下（起跳前先下蹲做预备）。
- **幕 4（cheer）**：小人 `cheer` 姿势 + calm 笑脸，蹦蹦跳跳地横向移动出画（每跳都要有下蹲预备和落地回弹），无道具无弹字，收尾。

## 3. 出片（二选一）

### 路径 A：After Effects（需 AE 已打开 + after-effects MCP 桥在运行）

```
py -3.14 scripts/build_ae.py out/plan.json out/timing.json assets/rig_spec.json <本技能根目录绝对路径>\out\voice.mp3 out/doodle_build.jsx
```

预期产物：`out/doodle_build.jsx`。然后经 after-effects MCP 工具逐步执行，或在 AE 菜单 File > Scripts > Run Script File 运行它——应得到一个含小人骨骼层、道具层、弹字层、字幕层和 voice.mp3 音频层的合成，时长 ≈ `audio_duration`。渲染走 AE 渲染队列或 `aerender`。

### 路径 B：HTML 兜底（无需 AE）

```
py -3.14 scripts/build_html.py out/plan.json out/timing.json assets/rig_spec.json out/voice.mp3 out/doodle.html
```

预期产物：`out/doodle.html` 单文件（音频内嵌），浏览器打开点播放即可预览。再渲 mp4：

```
node scripts/render_mp4.mjs out/doodle.html out/timing.json out/voice.mp3 out/demo.mp4
```

预期产物：`out/demo.mp4`，时长 ≈ `audio_duration`，画面与旁白同步。

## 4. 自检

对照 SKILL.md 第 5 节清单逐项核对，重点抽查两处弹字：把播放头分别拖到幕 1 的"三公里"和幕 3 的"十分钟"的 `t` 时刻，弹字应恰好在该帧出现，且与旁白念到该词完全同步。
