| name | unit-video |
| description | 把一个阅读单元的「备读」做成「领读视频 / 备读视频 / 讲解视频」： 作者第一人称、课件式讲解、16:9 横屏。当前仅支持《道德经》。从 books/道德经/chNN/NN.md 出发， 经「口播稿 → TTS 时间轴 → 分镜 atoms/steps → 渐进渲染」产出 video/道德经/chNN/NN/领读视频.mp4。用户要求把《道德经》某章、某单元或备读内容做成视频、 重渲视频、检查视频流程时，使用本 skill。 |
unit-video — 备读变成领读视频
本 skill 是给 agent 使用的制作协议。它把一个阅读单元的备读内容，转成一条可听可看的「领读视频」：作者 / 主讲人以第一人称对「你」讲，画面像一块动态课堂白板。视频不是把笔记搬上屏幕，而是用配音、字幕、经文高亮和渐进板书，帮助观看者跟上这一段的理解节奏。
记：
ROOT = 项目根目录。SKILL = ROOT/.claude/skills/unit-video。<unit> = books/<书>/chNN/NN.md。<out> = ROOT/video/<书>/chNN/NN/。<assets> = SKILL/assets/<书>/<素材id>/。
核心不变量
-
配音是主时钟
整条视频只有一根时间轴：口播.tts.m4a。字幕、经文高亮、板书 reveal、片头后的背景循环，都对齐这根时间轴。口播改了必须重跑 TTS；分镜校验会用指纹拦住「改稿但没重配音」。
-
备读文件是事实源头
视频从 books/<书>/chNN/NN.md 第 1–7 段提炼。第 8 段「你的理解 / 疑问」和第 9 段「回看批注」不进入视频。视频产物可随时删除重生，不反写备读。
-
素材套与单元产物解耦
画面素材与配置放在 SKILL/assets/<书>/<素材id>/；单元产物固定放在 ROOT/video/<书>/chNN/NN/。分镜通过 assets:"<书>/<素材id>" 记录使用哪套素材，旧单元可以按原素材重渲。
-
分镜不是字幕复读
字幕已经逐字承载口播；白板内容必须是观看辅助层：关键词、结构提示、概念压缩、判断句。白板文字要比口播短、准、能帮助观看者抓住「这一小段正在讲什么」。
-
先看整体叙事，再用 atom 绑定时间
atom 是脚本生成的全局口播锚点；beat 是一页白板，必须用 take 引用一段连续 atoms；step 是这一页里的语义推进，也用 take 引用当前 beat 内的连续 atoms。agent 不手写 beat.narr，而是先理解完整口播稿的叙事结构，再拆 beat / step，最后用 atom id 绑定时间。
-
正式制作管线由 agent 全自动执行
基础素材由用户预先准备并导入；新素材套第一次初始化 配置.js 时，需要用户在 HTML 配置台 review 和微调。除此之外，单元视频制作管线由 agent 完成：写口播、TTS、生成/完善分镜、静态校验、对齐、渲染成片，中间不设置用户处理节点。
架构层次
事实源 books/<书>/chNN/NN.md 第 1–7 段
单元产物 video/<书>/chNN/NN/：口播稿、TTS、时间轴、分镜、成片
素材层 SKILL/assets/<书>/<素材id>/：片头、背景循环、底板、配置
模板层 SKILL/templates/* + src/templates/registry.ts：字段、容量、用途
协议层 references/分镜与模板.md：atoms / beat / step 的数据契约
执行层 dist/cli/* + runtime/*：TTS、骨架、校验、布局检查、渲染
核心依赖关系：
口播稿 → TTS 时间轴 → atoms
完整口播叙事 → beats / steps
模板定义 → 静态字段与容量校验
素材配置 → 白板几何、字体、T0 时刻
validate-storyboard → align → layout-check → render-video
一单元管线
0. 适用范围拦截
当前只支持《道德经》的备读视频制作，所有模板、规范都是为道德经定制的，尚不具备通用性，其他书籍无法制作
如果请求目标不是 books/道德经/chNN/NN.md，立即停止，向用户说明：当前 unit-video 只支持《道德经》，其他书籍的视频模板尚未接入。禁止强行向用户交付任何中间产物，浪费token。
1. 解析素材套
先看 SKILL/assets/<书>/：
- 只有一套素材：直接使用。
- 有多套素材：必须由请求或环境变量
ASSETS=<书>/<素材id> 给出确定素材套；未给出时停止并报告缺少素材套前置条件。
- 没有素材或缺
片头.mp4 / 背景循环.mp4 / 底板.png：停止，报告需要先导入基础素材资产；素材准备不属于单元制作管线。
- 有素材但没有
配置.js：按 references/资产层与新书.md 启动配置台初始化。这是唯一需要用户 review 和微调的环节；完成后再进入单元制作。
2. 写口播稿
从 <unit> 的备读第 1–7 段提炼，写：
<out>/口播稿.md
要求见 references/口播稿规范.md。口播稿只写要讲出口的话，不写画面指令、模板、秒数或 reveal 标记。
3. 配音并生成时间轴
node SKILL/dist/cli/gen-tts.js <out>/
默认嗓音、语速和看板时刻来自素材套 配置.js，必要时用环境变量覆盖：
VOICE=zh-CN-YunxiNeural RATE=-10% node SKILL/dist/cli/gen-tts.js <out>/
ENGINE=say node SKILL/dist/cli/gen-tts.js <out>/
4. 生成分镜骨架
node SKILL/dist/cli/draft-storyboard.js <out>/
脚本只产出新版 分镜.js 骨架：顶层 atoms[] + 粗 beats[]。它不决定最终叙事结构。接下来 agent 必须先理解完整口播稿，再照 references/分镜与模板.md 和对应 templates/<模板>/README.md 完成：
- 选定每个 beat 的模板。模板必须已在
src/templates/registry.ts 注册。
- 从原文拆
jing。
- 填
base：该模板开场即存在的对象，如经文句、标题、核心字。
- 重拆
beats[].take：一个 beat 是一页白板，覆盖一个完整小意思。
- 重拆
steps[].take：一个 step 是一页内的语义推进，不按句子或 atom 机械切。
- 按模板需要给 step 填摘要性板书和高亮：
state + show；T0/T3 这类无 reveal 模板只覆盖 atoms。
- 保证每个模板的
capacity 不超限；超限就拆下一个 beat。
5. 静态校验、对齐、布局检查
node SKILL/dist/cli/validate-storyboard.js <out>/分镜.js
node SKILL/dist/cli/align-durs.js <out>/分镜.js
node SKILL/dist/cli/layout-check.js <out>/分镜.js
validate-storyboard.js 负责 atoms/take、模板字段、jing/hi、capacity 等硬校验；align-durs.js 只在校验通过后回填 durs[] / stepDurs[]；layout-check.js 负责真实 DOM 溢出检查。失败时按错误修分镜，不绕过。
6. 渲染成片
bash SKILL/runtime/render-video.sh <out>/分镜.js
render-video.sh 会先跑 validate-templates、validate-storyboard、align 和 layout-check，通过后输出 <out>/领读视频.mp4。
浏览器预览：
SKILL/runtime/renderer.html?data=<分镜.js 相对 runtime 的路径>
常用参数：
&beat=N：跳到第 N 个 beat 的静帧。&step=N：配合 &beat=N 跳到该 beat 的第 N 个 step 静帧。&zone=1：显示看板分区。&auto=1：打开后自动播放。
依赖
- Node.js ≥ 21。
- Google Chrome：
/Applications/Google Chrome.app。
ffmpeg / ffprobe。- Python 包
edge-tts：pip install edge-tts。
- 离线兜底可用 macOS
say，但时间轴只能到段级。
常见判断
- 白板抢跑：不要把还没讲到的信息放在
base 或当前 step；按语义推进拆 step。
- 白板溢出：不要继续加 step；拆成下一个 beat，让白板重新开始。
- 白板复述口播：删掉近似原句，改成关键词、概念压缩、结构提示。
- 想精准卡点：不要写秒数；调整
beat.take / step.take 的 atom 边界，让 align 从 TTS 时间轴推导。
- 分镜校验失败：先看
validate-storyboard 的第一条错误。通常是改了 atom 文本、take 不连续、模板字段不合法、capacity 超限、hi key 不存在、T0 越线。
- layout-check 失败：说明真实 DOM 已溢出；压缩板书或拆 beat，不要调秒数绕过。
- 想改讲法：回到
口播稿.md，重跑 TTS，再重跑 draft/调整分镜。不要只改 atoms[].narr。
不做的事
- 不做逐字 TTS 对齐；中文 edge-tts 当前主要是句级，step 内部用字符比例插值。
- 不在口播稿里写视觉 marker，避免污染旁白。
- 不为单章临时新增模板；优先用
T0–T4 和 step 编排解决节奏。
- 不去除素材自带水印。
