handdraw-story-video：用一张张手绘母图，自动生成线稿逐渐上色的暖心竖屏短视频最新版

一、这个项目在解决什么

抖音、视频号、小红书上有一类很吃香的内容：手绘风格的情感故事短视频——黑白线稿从左往右一笔笔显现，紧接着低饱和的彩色像被轻轻晕染一样从左往右填进来，配上安静的字幕和 BGM，30 多秒讲完一个温暖的小故事。

过去这类视频要么靠 AE/PR 手动 K 帧，要么靠剪辑师一帧帧描，门槛高、效率低。xiejunjie524/handdraw-story-video 把这套流程工程化了：你只需准备 7–9 幅手绘故事彩色母图，它自动提取对应线稿，再用 HyperFrames 渲染成”线稿从左到右出现、颜色从左到右填充”的竖屏故事视频。

⚠️ 注意：这是一个非常新的仓库（分析时距创建仅约一周），但 Star 增长很快，方向踩中了”AI 情感故事短视频”这个热门赛道，值得关注。

二、核心特性

• 默认 40 秒、720×960、30 fps，竖屏平台（抖音/视频号/小红书）开箱适配。
• 每幕独立彩色母图：本地提取”完全对齐”的线稿，线稿与颜色像素级对应，不会出现错位。
• 统一从左向右推进：线稿显现和颜色填充共用同一个左侧起点，节奏感统一；并且不重复调用生图模型（省成本、保一致）。
• 可选故事字幕 + 画面内道具文字：字幕在画面外顶部安全区，道具文字只存在于便签、招牌、手机、收据等真实物体上。
• 自动校验：检查时长、重复素材、字幕行数与字号范围，提前拦掉常见翻车点。
• 不绑定任何生图服务、音乐来源或私有 API：你用 Seedream、Midjourney、Atlas Cloud 还是自建服务都行，BGM 自己放。

三、技术栈与渲染原理

项目本身负责故事配置校验、线稿提取、HyperFrames 页面生成，渲染交给一套成熟的前端动画栈：

渲染链路：story.json → build_story.py 生成 hyperframes/index.html → npx hyperframes check 校验 → npx hyperframes render 输出 story-v1.mp4。GSAP 被复制进 hyperframes/assets/vendor/ 本地引用，无需联网。

四、一键成片：从一句话主题到视频

仓库提供了 scripts/one_click.py，把流程压到最短：

“`bash
# 设置图像模型密钥（可接 Atlas Cloud 等）
$env:IMAGE_API_KEY = “你的图像模型密钥”

# 直接输入主题，生成 8 幕工程
python scripts/one_click.py –topic “凌晨四点的豆浆” –config config.local.json –output runs/soy-milk

# 先验证配置和提示词、不调用模型
python scripts/one_click.py –topic “楼下的流浪猫” –config config.local.json –output runs/dry-run –dry-run

# 确认素材就绪后，追加 –render 直接出片
python scripts/one_click.py –topic “凌晨四点的豆浆” –config config.local.json –output runs/soy-milk –render
“`

如果配置了可选的文本模型，脚本会先自动生成 8 幕故事；没有文本模型时，使用内置的八幕因果骨架（beat sheet）。每幕只请求一次彩色图，再从同一张图本地提取线稿——既省钱又保证线稿/颜色严格对齐。默认不自动重试生图，也不会覆盖已有输出目录。

五、画风是怎么锁定的

这是项目最见功力的地方。它在 docs/prompts.md 里给了一段固定风格段，要求原样放在每幕提示词开头：

成人故事感的手绘插画，清晰、纤细、连续的深灰黑色钢笔线稿……低饱和度彩铅轻柔填色……大面积温暖纸白留白，主体主要位于画面下方 45%–55%……适合后续做从左到右的线稿显现和从左到右的渐进着色动画。

配套还有一长串负面提示词，明确排除”照片写实、3D 渲染、动漫厚涂、鲜艳霓虹、人群、密集背景、大面积纯黑、粗重卡通轮廓、裁掉腿和鞋子、缺失手指”等——这些恰恰是 AI 生图做这类动画时最容易翻车的点。

需要角色一致性时，用参考图编辑：固定一张角色参考图 + 一张画风参考图，每幕仍生成不同完整彩色母图，只改地点/动作/道具，不重新设计主角。这种”固定参考图 + 改变量段”的做法，是解决 AI 多幕故事”主角忽胖忽瘦”问题的标准答案。

六、八幕结构与节奏规范

docs/story-spec.md 定义了清晰的叙事骨架（非常符合短视频平台的完播逻辑）：

1. 在生活化场景建立具体困难，出现主角与另一人的踪迹；
2. 展示受影响者的反应，让障碍变清楚；
3. 用道具特写引入线索或小小的帮助；
4. 主角理解并决定行动（转折不能只靠字幕）；
5. 帮助正在被使用，环境/物体状态同步变化；
6. 主角回来、继续或把善意传下去；
7. 至少让另一人加入或回应，善意扩散可见；
8. 用宽景展示累积结果，一句克制的结尾。

每个 5 秒镜头的节奏也被精确规划：0.00–0.20s 转场/字幕进入 → 0.55–1.80s 线稿左→右显现 → 2.15–4.30s 颜色左→右填入 → 4.30–4.78s 保持完整彩色 → 4.78–5.00s 进下一幕。这正是”治愈系手绘故事”观感统一的技术来源。

七、示例：凌晨四点的豆浆

仓库自带一个完整可运行示例 examples/soy-milk-at-4am，8 幕讲了一个扫地工人与早餐店老板娘的暖心日常：

这是一个典型的”默默互相关照”的暖心叙事，和项目内置 Codex Skill 的触发词”做一个 40 秒线稿逐渐上色的暖心故事”高度契合。

八、生图模型接入：不绑定供应商

项目不内置任何 API 地址、模型名或密钥，使用者自己接供应商，只要每幕最终产出一张本地 PNG 彩色母图即可。文档给了约定变量名（IMAGE_API_KEY / IMAGE_API_BASE_URL / IMAGE_MODEL 等），真实密钥不写进 Git。

默认示例支持 Atlas Cloud：图像模型默认 bytedance/seedream-v5.0-lite（字节 Seedream 5.0 Lite），文本模型默认 qwen/qwen3.5-flash（通义千问）。若配置 reference_images，脚本先上传参考图再把 URL 传给生图请求，实现角色一致性。生图的价格、速率、可商用范围以各供应商条款为准。

九、Codex Skill 与生态定位

仓库根目录本身就符合 Codex Skill 结构，可复制到 $CODEX_HOME/skills/handdraw-good-deed-story，用”做一个 40 秒线稿逐渐上色的暖心故事”之类的自然语言触发。这让它能直接嵌进 Agent 工作流——和 joeseesun「乔木技能宇宙」、OpenCLI 等 Agent Skills 生态是同一波潮流：把创作流程拆成可触发的原子技能。

它和此前我们评测过的 qiaomu-cut-skill（乔木智能视频导演）、qiaomu-mtv-creator（Suno 歌曲转 MTV）一样，都属于”AI 短视频生成”这个大方向，但切入点不同：handdraw-story-video 专攻手绘/线稿上色这一特定治愈风格，并把画风锁定、八幕结构、节奏规范都固化进了提示词和配置，工程完成度高。

十、合规与注意事项

• 代码 MIT，但生成的图片、字体、GSAP、音乐不自动获得 MIT 授权，须遵守各自提供方条款；GSAP 商业使用需购买授权。
• 仓库不含 API 密钥、浏览器会话、参考视频、下载音乐或完整渲染历史——干净、无 secrets。
• BGM 必须”已获授权”，不要塞版权音乐进仓库。
• 生图可商用范围取决于你接的供应商条款，发布前务必确认。

十一、一句话总结

handdraw-story-video 是一套把”手绘情感故事短视频”从手工剪辑变成可工程化、可一键成片的完整方案：固定画风提示词 + 八幕叙事骨架 + 左→右线稿/上色动画 + HyperFrames 渲染 + 可选 Codex Skill 触发。643 Star、一周上线，说明”AI 治愈系手绘故事”这个赛道的需求是真实且旺盛的。如果你在做情感号、本地生活号或知识类短视频，这是个值得 fork 的高质量起点。

GitHub 地址：https://github.com/xiejunjie524/handdraw-story-video