story-to-handdrawn-video 是一个能够将中文故事文案或一组有序图片，转换成 3:4 竖屏 手绘故事动画 的 Agent Skill。它内置了 20 种不同的手绘风格（如彩铅日记、儿童蜡笔、水墨等），并支持手写体字幕和多种转场效果。

本教程将指导你在本地完成环境配置、项目安装，并通过 AI Agent 驱动动画生成。

1. 部署前准备

硬件与系统要求

  • 操作系统：Windows、macOS 或 Linux。
  • 处理器：推荐多核 CPU，用于视频渲染。
  • 内存：至少 8GB RAM，推荐 16GB 或以上。
  • 存储：至少 5GB 可用空间（用于存放项目、依赖和生成的视频）。

软件环境

你需要安装以下核心软件，并确保它们可以从终端（命令行）中调用：

  • Node.js: 版本 20 或更高。可通过 node -v 检查。
  • Python: 版本 3.10 或更高。可通过 python --version 检查。
  • npm: 通常随 Node.js 一起安装。可通过 npm -v 检查。
  • FFmpeg: 必须安装 ffmpeg 和 ffprobe，并确保它们在系统 PATH 环境变量中。这是视频渲染的核心依赖。
  • Google Chrome: 或任何 Remotion 兼容的浏览器，用于渲染。

2. 部署步骤

第一步：克隆并初始化渲染器项目

这是核心的 Remotion 渲染引擎。

1
2
3
4
5
6
7
8
9
# 克隆仓库
git clone https://github.com/gnipbao/story-to-handdrawn-video.git
cd story-to-handdrawn-video

# 安装 Node.js 依赖
npm ci

# 运行检查（TypeScript 类型检查 + 分镜结构校验）
npm run check

第二步：安装 Agent Skill

这个 Skill 允许你通过自然语言驱动渲染器，而无需手动运行脚本。根据你使用的 AI Agent，将 Skill 复制到对应的目录：

  • Codex:

    1
    cp -R skill-package/story-to-handdrawn-video ~/.codex/skills/

  • Claude Code / 通用 Agent:

    1
    cp -R skill-package/story-to-handdrawn-video ~/.claude/skills/

  • Kimi Code:

    1
    cp -R skill-package/story-to-handdrawn-video ~/.agents/skills/

第三步：配置环境变量 (可选)

如果你不在项目根目录下运行 Agent，或者想指定渲染器项目的位置，可以设置以下环境变量：

1
export STORY_VIDEO_PROJECT=/absolute/path/to/story-to-handdrawn-video

将 /absolute/path/to/story-to-handdrawn-video 替换为你克隆项目的实际绝对路径。

第四步：验证安装

在项目根目录下，运行以下命令列出所有内置风格，以验证环境是否配置正确：

1
python3 scripts/run_story_video.py --list-styles

你应该能看到一个包含 20 种风格及其示例图路径的列表。

3. 基本使用方法

这个项目主要通过 AI Agent (如 Codex) 以自然语言驱动。启动你的 Agent，并确保它位于项目目录内（或已设置 STORY_VIDEO_PROJECT 环境变量）。

从故事文本生成动画

在 Agent 中输入以下指令：

1
2
3
使用 $story-to-handdrawn-video 把这段故事生成可后期配音的手绘动画。

[在这里粘贴你的故事文本]

你也可以指定一个文本文件：

1
使用 $story-to-handdrawn-video 把 /absolute/path/to/story.txt 生成手绘动画，标题叫「纸上的夏天」。

从一组图片生成动画

如果你已有手绘图片，可以按顺序导入：

1
2
使用 $story-to-handdrawn-video 把这几张图片按顺序生成手绘动画：
/absolute/01.jpg /absolute/02.jpg /absolute/03.jpg

选择风格

默认风格是「彩铅日记漫画」。你可以通过自然语言切换：

1
使用 $story-to-handdrawn-video 选择「水墨写意」风格，把这段故事生成静音手绘动画。

生成预览版

在正式渲染前，可以先输出低分辨率预览版检查效果：

1
使用 $story-to-handdrawn-video 先给这个故事生成一个预览版。

4. 输出与结果

  • 预览版：分辨率 720×960，输出路径为 out/picture_silent-preview.mp4 或 out/uploaded_picture_silent-preview.mp4。
  • 正式版：分辨率 1080×1440，输出路径为 out/picture_silent.mp4 或 out/uploaded_picture_silent.mp4。

所有输出均为 静音 H.264 画面轨，方便你后期进行配音和添加背景音乐。

5. 维护与更新

更新项目

进入项目目录，拉取最新代码并重新安装依赖：

1
2
git pull
npm ci

故障排查

  • ffmpeg 或 ffprobe 未找到：请确保 FFmpeg 已正确安装，并且其安装路径已添加到系统的 PATH 环境变量中。重启终端后再试。
  • Node.js 版本过低：使用 nvm (Node Version Manager) 等工具升级 Node.js 到 20 或更高版本。
  • Agent 找不到 Skill：确认 Skill 已复制到正确的 Agent 技能目录，并且 Agent 已重新启动以加载新的技能。
  • 渲染失败：检查 out/ 目录下是否有错误日志。确保 Chrome 浏览器已关闭或没有占用过多资源。

总结

story-to-handdrawn-video 为内容创作者提供了一个将文字故事转化为风格化手绘动画的高效工具。通过以下关键点，你应该能够顺利开始使用：

  1. 核心是 Node.js + Remotion 渲染引擎，确保 FFmpeg 等依赖安装正确。
  2. 通过 Agent Skill 进行自然语言驱动，降低了使用门槛。
  3. 20 种内置风格提供了丰富的视觉选择，你可以通过 --list-styles 查看并选择。
  4. 先预览后渲染的工作流有助于节省时间和资源。

建议从简单的故事文本和默认风格开始尝试，熟悉流程后再探索风格切换、图片上传等高级功能。如果在部署或使用中遇到问题，可以查阅项目根目录下的 DESIGN.md 和 CONTRIBUTING.md 文件。