先给结论：sweety-handdraw-video 不是"AI 视频生成"项目，它是一条「模型导演 + 本地引擎」的混合流水线——把创作判断交给 Agent，把渲染确定性交给 Python 脚本。 市面上的图生视频方案（Sora、可灵一类）走的是「文本提示 → 扩散模型整段生成」，笔触不可控、内容不可核对、中文字写不出笔顺、画面时间轴对不上旁白。这个项目换了一条路：Agent 负责理解内容、写口播、设计分镜、生成插画；本地引擎负责逐笔描线、按笔顺手写、配音对齐和导出，每一笔的位置和时刻都是算出来的，不是抽出来的。

目录

1. 它是什么：一周 715 star 的手绘视频 Skill
2. 它解决的问题：手绘视频为什么难
3. 五步流水线：从主题到成片
4. 预算制分镜：先算画得完，再生图
5. 六种导演密度模式
6. 像人一样画：运笔的物理常数
7. 渲染引擎与字幕硬门槛
8. 配音：旁白先行与语义分段门禁
9. 21 种画风与六款手臂
10. 工程细节：50MB 离线包与镜像修复
11. 诚实的边界：它自己写下的限制
12. 成熟度评估
13. 结语

一、它是什么：一周 715 star 的手绘视频 Skill

一句话：一个安装在 Claude Code / Codex 里的 Agent Skill，输入一个主题、一篇文章或一个完整故事，输出边画边讲的有声 MP4——Agent 当导演，本地 Python 引擎当画手。

数据快照（2026-10-20 通过 GitHub API 与仓库源码核实）：

几个数字值得单独说：

8 天 715 star、76 次提交。这个star 增速在工具类项目里属爆发级别，且迭代极快——10-12 建仓库，10-13 就连发 v1.2.1/v1.2.2/v1.2.3 三个封板，10-17 发 v1.3，10-19 发 v1.4.1。版本号里能看到功能演进：v1.2 封板包含整篇连续旁白和原片参考导入，v1.3 加了声音门禁和素材随包，v1.4 转向原生选项、9:16 竖屏默认和导演密度契约。

1,009 个文件里 981 个在 skills/ 目录——这不是冗余，是它把五个上游项目以固定快照内置了：

「内置而不安装」是个明确的工程取舍：运行时不自动追踪上游更新，用快照换可复现。README 把来源、许可和固定快照写进了 THIRD_PARTY_NOTICES.md。

三条精选样片（均为 1920×1080、30fps，Release 下载）：

二、它解决的问题：手绘视频为什么难

要理解这个项目的设计选择，先得看清「让 AI 做手绘讲解视频」这件事难在哪。三条路线各有各的坑：

这个项目的答案是把流水线切成两半：

flowchart LR
    subgraph OLD["图生视频模型路线"]
        A1["文本提示词"] --> A2["扩散模型
整段生成"]
        A2 --> A3["笔触不可控
内容不可核对"]
    end
    subgraph NEW["sweety-handdraw-video"]
        B1["SKILL.md
模型当导演"] --> B2["口播稿 + 分镜 + 插画"]
        B2 --> B3["Python 引擎
逐笔确定性渲染"]
        B3 --> B4["每笔可检查
每帧可复现"]
    end
    style A3 fill:#fff1f0,stroke:#d9534f,color:#8a2b28
    style B4 fill:#f0f7ff,stroke:#2f6fb5,color:#1c4570

关键在于分工边界：模型负责"画什么、讲多久、用什么风"，脚本负责"画得完画不完、运笔像不像人、字幕压没压图"。SKILL.md 里有一句话把这份分工写得很直白：

主体内容由模型设计；脚本只执行已确定的素材与时间线，并用客观指标拦截错误。

翻译成工程语言：模型是创作者，脚本是护栏。护栏不创作，只拦截——旁白没锁不给渲染、分镜没算预算不给生图、线稿门槛不过不给编排、检查记录过期不给交付。这套边界感是后面所有机制的前提。

三、五步流水线：从主题到成片

完整流程在 SKILL.md 里固化为六步，我按数据流重新画了一遍：

flowchart TD
    S1["① 讲清因果
受众 · 机制 · 反例 → design.json"] --> S2["② 旁白先行
完整口播稿 → 语义分段 → 逐段合成"]
    S2 --> S3["③ 分镜算预算
storyboard_lint.py --budget"]
    S3 --> S4["④ 生图
美术指导 + 缩略图/线稿门槛"]
    S4 --> S5["⑤ 编排渲染
job.json 时间线 → FFmpeg"]
    S5 --> S6["⑥ 分层核对
verify / review.json"]
    S3 -- 预算不足 --> S3R["改分镜：减视觉 / 加 beat / 并板"]
    S3R --> S3
    style S3 fill:#fff7e6,stroke:#d48806,color:#7a4d00
    style S6 fill:#f0f7ff,stroke:#2f6fb5,color:#1c4570

两个反直觉的顺序值得注意：

声音先于画面。 不是先出图再配音，而是先写完整口播稿、逐段合成、拼成母带、生成 alignment.json 逐句时间戳——然后用时间戳反推每幅画能画几秒。这解决了手绘视频最经典的死局：画面画完了，旁白没说这么长。

生图前先算账。 分镜按旁白算出每个 visual 的绘制窗口和笔数上限，图按预算设计。约 3 倍人速画得完就停，笔忙占比受模式约束且不超过 70%。画不完的图不是渲染时压缩时间轴（那会变成"快进糊弄"），而是上游简化图片或把窗口跨句延长——storyboard_lint.py 里对"引擎超预算"是直接判 error 的：

if asset.get('time_compression', 1) > 1.001 or ... speed_over_cap or ... fill_over_cap:
    errors.append(f'{label}: the engine exceeded its drawing budget; simplify the image or extend its window across beats instead of compressing its strokes')

四、预算制分镜：先算画得完，再生图

这是整个项目里我最欣赏的部分，也是它与"AI 生成视频"拉开本质差距的地方。核心问题一句话：给定一段真实时长的旁白，每幅图能画几秒、能画几笔？ storyboard_lint.py（479 行）把这个问题做成了可执行的门禁。

4.1 绘制节奏的标定常数

STROKES_PER_SECOND = 3.5  # measured draw-v2 pace at the cap: contour strokes, pen lifts and marker color included
MAX_DRAWING_SHARE = .7    # the pen is busy at most this share of the narration

3.5 笔/秒不是拍的脑袋——注释写明是 draw-v2 引擎实测节奏，且轮廓笔、抬笔移动、马克笔上色都算笔数。70% 是笔忙占比上限：剩下的 30% 必须留给观众看完成图。这两个数决定了后面所有的分档和窗口计算。

4.2 按秒数分档的复杂度契约

def tier(seconds, hold):
    strokes = max(3, int(seconds * STROKES_PER_SECOND))
    if seconds < 3:
        return f'label or tiny icon: at most ~{strokes} strokes'
    if seconds < 6:
        return f'simple icon/silhouette: at most ~{strokes} strokes, flat fills'
    if seconds <= hold:
        return f'one subject: at most ~{strokes} strokes, flat fills, no texture lines'
    return (f'at most ~{strokes} strokes: a scene with background ... or split into two visuals')

一幅图能画几秒，就只允许几笔——不到 3 秒的窗口只配画个小图标或标签，超过单镜停留上限的要么画带背景的场景（靠部位分节拍撑时间），要么拆成两幅。复杂度不是美术喜好，是时间预算的函数。

4.3 窗口与视觉数量：两条硬公式

每个 visual 的绘制窗口这样算：

cursor = start + LEAD                                              # LEAD = 0.54
window = times[shot['beats'][-1]]['end'] - HOLD - cursor - GAP * max(0, len(visuals) - 1)   # HOLD = 0.6, GAP = 0.08
seconds = window * weight / sum(weights)

即：镜头内首 beat 起点 + 0.54 秒起笔，末 beat 终点前留 0.6 秒收尾，多个 visual 之间留 0.08 秒抬笔间隔，剩余时间按权重分配。窗口不足 0.5 秒直接报错：「only Xs to draw; give the shot more beats or fewer visuals」。

全片视觉数量也有下限：

required = max(1, math.ceil(narration / hold * rules['cadence_factor']))

旁白总时长除以单镜停留上限再乘模式系数——信息密度不够会被拦，而且报错信息直接告诉你该往哪加：

3 planned visuals for 92.0s of narration; at least 12 are needed (a new visual every 8s).
Add visuals to the sparsest shots: shot_07 (14.2s per visual), shot_03 (12.8s per visual) ...

插画占比也有要求：图片数少于 0.8 × required 且没写 text_only_reason 时判错；纯文字镜头超过 20% 时长同样拦。宿主没有生图能力时必须停下告诉用户，不允许静默降级成"文字滚动视频"——这条写在了错误信息里。

4.4 成片后的三项节奏复核

预算检查只是"计划"，渲染完还有"实测"三件套：

还有一条防偷懒的：同一张主图连续占超过 2 个 beat 会被拦，除非该镜标注了 callback 并写明理由。完成图停留时间的中位数低于模式要求会警告，单幅低于 1 秒也警告——注释里给了标定基准：「the first Codex film held only 0.56s on average, validated films hold 1.1-1.7s」。

4.5 镜头类型不是随便填的

七种 shot type 各有结构化真值条件，编剧意图要过代码校验：

SHOT_TYPES = {
    'scene_with_background': (lambda visuals: any(v.get('kind')=='illustration' and v.get('background') for v in visuals)),
    'comparison': (lambda visuals: sum(v.get('kind') in PICTURES for v in visuals) >= 2),
    'character_action': (lambda visuals: any(v.get('kind')=='illustration' and v.get('characters') for v in visuals)),
    ...
}

声明了 comparison 却只放了一幅图、声明了 character_action 却没有登记角色——都会被拦。角色必须绑定锁定参考图 + SHA-256，且绘制计划里要引用该参考图，防止跨画面角色漂移。

五、六种导演密度模式

v1.4 引入了 presentation.mode——这不是用户选项，是导演根据受众和内容推断的密度契约，写在 design.json 和 storyboard.json 里，由 storyboard_lint.py 强制执行。六种模式的参数差异很大：

几个设计细节：

accumulating_board（黑板报模式）的 cadence_factor 只有 0.55——同一块板跨 beat 累积，不需要每句重画整页，所以"每 hold 秒一幅新图"的要求减半。它还要求整页先规划 boards 的区域位置，同一块板在一张物理页面上按阅读顺序逐项补齐，不每句话清场。这是从"白板动画"向"课堂板书"的关键扩展。

模式必须带 reason。validate_presentation() 强制要求解释为什么这个模式适合受众和内容，density 字段还必须与模式内置值一致——想手动把 picture_book 标成 dense 会被拒。

模式是推断出来的，不是问出来的。infer_hints() 给模型的先验很直白：儿童叙事走绘本、单概念深挖走焦点图、清单对比走信息图、连续板书走黑板报、操作流程走步骤序列。用户不选，模型按内容定。

六、像人一样画：运笔的物理常数

如果说预算制分镜保证了"画得完"，line_drawing.py（306 行）保证的就是"像人在画"。它的做法是把拟人感拆成一组可标定的物理常数：

这组常数撑起了几个具体的拟人机制：

转弯自动减速。 弧长计算不是欧氏长度，而是按曲率加权——steps * (1 + 1.5 * clip(turn / (π/8), 0, 1))，转弯处弧长膨胀，笔尖在曲线和拐角自然放慢。转角用 ±6 px 窗口测量，防止骨架像素抖动被误判为弯曲。

右手方向偏好。 REVERSE_COST = 250 的注释写得很直白：「px of extra travel a right-hander accepts rather than draw a line upward or leftward」。路径规划时，向左或向上画一笔要计入 250 px 的额外代价——于是笔画方向整体呈现出右手绘制的顺手感。倍速顶上还有个 HURRIED = REVERSE_COST / SPEED_FACTOR = 62.5：手快到顶上时，方向偏好让步于速度。

两种速度剖面。 stroke_profile() 按笔画长度和人速倍率切换：长笔画在倍速模式下用 plateau（两端缓入缓出、中间巡航），短笔画用 min-jerk。lift_seconds() 算抬笔时间——人类节奏 80–150 ms，随墨迹同步倍速，2 帧保底，且要满足抬笔移动的帧内位移不超 TRAVEL_PX。

部位分级与停顿。 笔画按 SILHOUETTE / KEY / STRUCTURE / DETAIL / TEXTURE 五档归类（KEY_PART 正则认 head/face/eye/mouth/nose/hand/finger/paw 这些关键部位），每个语义部分先轮廓后细节，部分之间停 0.18 秒——像人画完一个部分停下来想下一步。注释里给这部分的总纲是：

Order, time and render whole line strokes like a right-handed person: per part the silhouette first, then long interior structure, then details and short marks.

七、渲染引擎与字幕硬门槛

video_renderer.py（529 行）负责把时间线渲染成帧：手部合成、路径文字、马克笔运动、水印。几个细节见功力：

手腕倾角上限 7 度（MAX_TILT = 7）——手臂跟随时加一点手腕转动，但不许过，过了就是"橡皮手"。阴影方向统一为向右下（SHADOW_DIRECTION = (0.555, 0.832)，光源在左上），连笔杆阴影都按笔尖起算、随 barrel 距离漂移（PEN_SHADOW_SLOPE = 0.2）。手臂进出场 0.45/0.5 秒、镜头停留 1 秒——短于 1 秒的抬笔间隔会让手"留在画面里抢戏"。

每个像素都有语义归属。 质量门禁要求每个插画像素归到具体部位，所有轮廓结束后才填色，且两个阶段按同一部位顺序。部位审查还要处理遮挡关系——「发丝间露出的伞面属于伞，手持物不属于手臂，包与腿相交处按实际前后关系分配」。程序只能验证给定归属的执行顺序，不能证明模型分区语义正确——这句自我认知也写进了文档。

字幕唯一性是交付硬门槛。 同一句旁白同一时刻只允许一份字幕：画面烘焙、字幕事件、MP4 内嵌轨、网页 <track>、播放器自动加载，五条路都不许叠加。build 时就检查字幕避让——插画像素不得压进字幕区（含边距），不等渲染后才发现。编辑用字幕只能放 outputs/editing/。交付时检查成片无额外字幕轨、同目录无 SRT/ASS/VTT，并实际看解码画面的长句、换句和片尾。

检查记录分三层，不许互相顶替。 review.json 里工程检查（verify）、观感检查（visual / motion / content）、连续播放和实际听音分别记录。continuous_playback 和 listening 只能是 pass 或 not_done（写原因），做了 ASR 不等于听过——文档原话：「若只检查了 ASR，不能写’已经完整听过’」。抽帧能验证字形和版面，不能单独证明全片运动流畅。用户拒绝成片有专门命令：handdraw_video.py reject JOB --reason "用户原话"，回执改为"用户已拒绝，需要返工"，这一版不能再 finalize。

八、配音：旁白先行与语义分段门禁

声音在这条流水线里是时间轴的主锚，所有画面节奏都由它倒推。管线设计：

flowchart LR
    V1["完整口播稿"] --> V2["语义分段
每段 ≤100 字 · 只在句末切"]
    V2 --> V3["逐段合成
VoxCPM2 / VoiceStudio"]
    V3 --> V4{"噪声门禁
嗡声 · 底噪 · 削波"}
    V4 -- "不通过 → 换种子重试" --> V3
    V4 -- 通过 --> V5["拼接母带
实测停顿 · 不一律删静音"]
    V5 --> V6["alignment.json
逐句时间戳"]
    V6 --> V7["分镜预算 / 字幕 / 运笔
全部由时间戳驱动"]
    style V4 fill:#fff7e6,stroke:#d48806,color:#7a4d00

几个关键决策：

按语义分段，每段不超过约 100 字，只在句末切。 不按标点硬切、不跨句合并——保证每段的韵律完整，重读某句时只重新生成变化的语义段落。

每段过噪声门禁才保留。 嗡声、底噪、削波三项，不通过就换种子重试。这不是矫情——样片《那条死于愤怒的蛇》原版旁白带 235 Hz 嗡声，v1.3 门禁会直接拦截。拼接母带时用实测停顿，禁止"一律删静音、缩短所有停顿或全片交叉淡化"来掩盖错误，真实换气和语义停顿要保留。

四类配音后端，音色与后端分离：

六款声音里四款随包合成（磁性解说男声为默认、儒雅青年、温柔知性女声、悬疑故事解说），逼真男声/女声沿用原片参考、需用户自行导入。随包合成声音由本机 VoxCPM2 仅凭文字描述设计，未使用真人/主播/平台音色作参考；用户导入声音要声明授权（consent: self / consent: authorized），不克隆公众人物音色。作者本机环境是 M3 Max / 36GB——这是跑 3.23 GB 模型的家底，换个 8GB 的机器这条路直接不用考虑。

改一句话不必全部重做。 只改字幕/笔杆/水印/布局可复用图和声音；改口播正文只重新生成变化的语义段落。但改旁白后必须重算画面和字幕——「不能让视频页面成为声音切口」。

九、21 种画风与六款手臂

画风库是 20 个编号风格 + 一个稳定变体，按绘制方式分两类：

逐笔绘制（先描线后上色）：编号 1、4、5、17、19、20——清晰墨线轮廓 + 平涂，这也是没有指定画风时模型默认挑选的范围。 揭示模式（笔带宽软笔刷按部位扫出成图）：其余画风——只能由用户明确接受（reveal_accepted），因为"刷出来"和"画出来"是两种观感，不能替用户决定。纯黑白的 1 号要写明理由才用。

选择方式有四种：直接看预览选编号、库内自动匹配、模型独立设计（线条/颜色/明暗/材质/背景全自定义）、用户描述方向。风格选择器直接读包内预览，不访问网络——这是 v1.3 把 21 张预览图随包分发的原因。

六款手臂预设按笔尖到手腕校准，裁切边留在画外：

笔杆文字最多 16 个 Unicode 字符、水印最多 180 字符可换行——默认都不加。这两个选项本质是给做号的人留的商业化口子，作者没有默认塞广告。

十、工程细节：50MB 离线包与镜像修复

这个项目的工程质量不止在渲染管线，也在分发和资产完整性上。几个机制值得单独看：

10.1 安装体积的硬预算

validate_package.py 把「二进制文件禁令」换成了更实用的预算制：安装包总量 ≤ 50 MB、单文件 ≤ 10 MB，且包内预设必须与清单记录的哈希一致。v1.3 实测 843 个文件 / 49.4 MB 通过——贴着上限走，说明作者在主动管理体积。

同时按 omitted_showcase_media 机制移除了 omniailab 导演依赖里的 examples/motion 和 examples/images 宣传示例（533 个文件），方法文档和运行代码保留。README 特意说明：减小代码包不等于清理 Git 历史，没有改写历史提交。

10.2 资产修复：四级回退与哈希校验

手部、画风预览、试听共 30 个文件（约 8.8 MB）随包分发，hosted-manifest.json 为每个文件记录字节数、SHA-256 和有序镜像地址（jsDelivr CDN → Fastly → GitHub Release）。读取顺序：

flowchart TD
    H1["包内副本
大小 + SHA-256 校验"] -- "一致 → 使用" --> H2["离线可用"]
    H1 -- "缺失 / 损坏" --> H3["本地缓存
~/.cache/sweety-handdraw-video/<sha256>/"]
    H3 -- "未命中" --> H4["HANDDRAW_MIRROR
自定义前缀（https:// 或 file://）"]
    H4 --> H5["清单顺序逐个尝试
每个地址 15 秒超时"]
    H5 -- "全部失败" --> H6["报错列出每个 URL 及错误
+ 手动放置路径"]
    H1 -. "HANDDRAW_OFFLINE=1" .-> H6
    style H6 fill:#fff1f0,stroke:#d9534f,color:#8a2b28

三个细节：只有大小和哈希都一致的内容才写入缓存，不会"退回另一张图或另一种声音"；HANDDRAW_OFFLINE=1 跳过联网直接说明缺失文件；HANDDRAW_MIRROR 支持 file:// 前缀——内网/Gitee 镜像可以顶上去。

10.3 一次真实的图床迁移

README 记录了一次值得写进教科书的资产运维事故：内置画风库的参考图原托管在 Netlify，额度耗尽停用，75 个链接变死链。修复方案是把链接整体迁到 jsDelivr 并固定到上游含图提交 cdfd004c89164096c861ad06ebab2aa1527d1710，Release 附件作最后回退。还有个更细的处理：五张运行参考锚点里三张清理了来源与模拟相机字段（逐像素一致），jsDelivr 返回上游原字节时校验不符，会自动转用 Release 清理版——清单保留上游字节校验值以便追溯。这种"清理过隐私的资产和上游原字节不一致"的边界情况，大多数项目到死都不会遇到。

10.4 纯 Python 隐私清理

图片隐私清理（clean_image.py）从原来的 Bun + ExifTool 改成纯 Python 实现——少两个外部依赖，setup.sh 也少两样要装的东西。所有生成图都要过这一步，元数据与来源属性分别报告，且文档明确：隐私处理不等于 AI 检测保证。

10.5 测试与验证

v1.3 记录：158 项回归通过（1 项平台用例跳过）、离线冒烟短片通过、安装包 843 文件 49.4 MB 通过核验。scripts/ 下 71 个文件里 test_*.py 有 30 个——对一个 Skill 项目来说测试密度相当高，且 smoke_test.py 可以离线跑通整条渲染链。

十一、诚实的边界：它自己写下的限制

这个项目的文档质量里最难得的，是把边界写在明面上：

还有一条容易被忽略的：脚本不能替代观看。文档反复强调「最终实际画面仍须检查，不能以程序检查替代观看」「工程能约束检查是否完成和证据是否对应当前图，不能自动理解’切断’」。叙事事实甚至要做进图里——《蛇》样片的"身体切断"必须在 drawing-plan 里列为 narrative_requirements，要求两处可见空隙与断开的蛇段，看图时按相同 id 记录证据。把"剧情真实性"做成可勾验的契约，这是我对这个项目印象最深的细节之一。

十二、成熟度评估

一句话：这是一个"作者自己天天在做片"的项目。判断依据不是 star 数，而是那些只有真正做过片才会加的机制——3.5 笔/秒的标定（被画不完的图坑过）、235 Hz 嗡声门禁（被样片杂音坑过）、Netlify 死链迁移（被图床坑过）、字幕唯一性硬门槛（被双字幕坑过）、“做了 ASR 不等于听过”（被自己的验收记录坑过）。每一条都对应一次具体的翻车。

十三、结语

回到开头那个判断：它把"AI 做视频"从生成问题重构成了约束满足问题。

图生视频模型的范式是"生成然后祈祷"——抽一笔、看结果、不对再抽。这个项目的范式是"先算账再动手"——旁白时长决定绘制窗口，窗口决定笔数上限，笔数决定图片复杂度，复杂度决定生图提示词。渲染引擎只执行已验证可画的计划，预算不够就在上游改分镜，绝不靠压缩时间轴糊弄。确定性不是从模型里榨出来的，是从流水线的结构里长出来的。

但它真正值得学的地方，是那份贯穿所有文档的分工自觉：模型该做的（理解、创作、判断）和脚本该做的（标定、拦截、核验）划得很清，而且双方都不越界——脚本不假装能审美，模型不假装能保证。放到更大的语境里，这其实是所有 Agent 产品都要回答的问题：当执行者是不可靠的智能体时，工程系统的价值就在于把"不可靠"约束在可验收的边界内。

对普通读者，它的实用价值也很直接：有一条两分钟的知识讲解/寓言故事/产品原理要做口播视频，又不想出镜、不想 K 帧、不想学动画软件——装个 Skill，把文章丢给 Agent，喝杯咖啡回来审片。macOS 用户现在就能试；Windows 用户（比如我）只能等，或者去催作者。

承认自己做不到什么，比宣称自己什么都能做，更能建立信任。 这条在工程上和在别处一样成立。

免责声明：本文基于 2026-10-20 的仓库快照（main 分支、Release v1.4.1）与公开源码、SKILL.md、references 文档及 GitHub API 数据撰写，所有代码片段与常数均可在仓库 skills/sweety-handdraw-video/scripts/ 核对。文中「实测」指作者记录的 v1.3 验证结果（158 项回归、843 文件 49.4 MB 安装包等），非本文在本机复跑；本文未在 macOS 环境实际制作视频。项目仍在高速迭代，接口、默认值、支持平台均可能变化，使用前请以仓库最新 README 与 SKILL.md 为准。文中引样的星标、提交数等动态数据随时间变化。本项目涉及本地运行第三方 TTS 模型与声音素材，声音授权与平台 AIGC 声明规则请自行确认遵守。