Hand-drawn Explainer Video Nikola 部署与使用教程

Hand-drawn Explainer Video Nikola 是一个专为中文知识讲解设计的 Codex Skill，能够将主题、文稿或字幕文件自动转化为“讲一部分、画一部分”的手绘风格讲解视频，并交付真实的 MP4 文件、字幕、时间轴和可编辑素材。它支持两种核心制作路线：逐笔故事动画（模拟真实手绘落墨）和程序动画（使用 HTML/SVG/GSAP 制作流程卡片等）。

本文将引导你完成从安装到生成第一个视频的完整流程。

一、准备工作

在开始安装前，请确保你的系统满足以下基本要求：

操作系统：Windows、macOS 或 Linux。
Python 环境：Python 3.10 或更高版本。在终端/命令行中运行 python --version 或 python3 --version 来检查。
包管理器 (pip)：通常与 Python 一同安装。
Git：用于克隆仓库（如果使用命令行）。
可选但强烈推荐：
- FFmpeg/FFprobe：最终合成完整 MP4 视频所必需。请根据你的系统安装。
- Node.js 和 npm：如果计划使用程序动画路线，用于管理 GSAP 等 JavaScript 依赖。
- 一个现代浏览器：用于预览程序动画效果。

注意：此 Skill 本身不包含大型 AI 模型，所有渲染在本地完成。但生成新的插画或使用云配音（如火山引擎 TTS）时需要外部 API 并可能产生费用。

二、安装步骤

第一步：将 Skill 安装到 Codex

这是最推荐的方式，让 Codex AI 助手能够调用此 Skill。在终端中执行以下命令：

# 1. 克隆仓库到 Codex 的 Skills 目录
git clone https://github.com/hi-nikola/hand-drawn-explainer-video-nikola.git "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola"

# 2. 运行环境检查脚本 (Windows)
python "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola/scripts/setup_check.py"

对于 macOS/Linux 用户：请将路径中的 $env:USERPROFILE 替换为 ~（例如 ~/codex/skills/...）。如果 python 命令指向 Python 2.x，请明确使用 python3。

第二步：安装逐笔动画核心依赖

如果您计划使用逐笔故事动画路线，需要额外安装其渲染依赖。

# 进入 Skill 目录
cd "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola"

# 准备 Python 环境 (会安装 opencv-python, numpy 等)
python vendor/srt-whiteboard-animation/scripts/prepare_env.py

# 运行预检脚本，生成环境报告
python scripts/stroke_story_preflight.py --report preflight-stroke-story.json

此过程会下载必要的 Python 库。请注意，此步骤不需要下载任何庞大的本地神经网络模型。

第三步：安装程序动画依赖 (可选)

如果您计划使用程序动画路线（例如流程卡片动画）：

# 进入 Skill 目录 (如果尚未进入)
cd "$env:USERPROFILE/.codex/skills/hand-drawn-explainer-video-nikola"

# 安装 Node.js 依赖 (包括 GSAP 等)
npm install

三、配置 API 密钥 (可选)

此步骤仅在您需要使用云服务（如 AI 生成新插图或使用火山引擎配音）时必需。

在 Skill 根目录下，复制 .env.example 文件并重命名为 .env。
编辑 .env 文件，填入您所使用服务的 API 密钥。例如，若使用火山引擎语音合成，需填入 VOLC_ACCESS_KEY 和 VOLC_SECRET_KEY 等。
重要：.env 文件包含敏感信息，请勿将其提交到公开仓库。

提示：如果你已经有现成的配音音频文件 (.mp3/.wav) 和手绘风格的源图片，可以跳过 API 配置，直接使用本地素材进行制作。

四、使用 Skill 生成视频

安装和配置完成后，你就可以通过 Codex 与之交互了。直接向 Codex 发送包含 Skill 名称和需求的指令即可。

直接可用的触发提示词示例

你可以直接复制以下提示词，发给 Codex 来启动任务：

制作一个 Q 版人物讲解的逐笔故事视频：

使用 $hand-drawn-explainer-video-nikola，把下面内容做成 45 秒中文手绘讲解视频。讲一部分画一部分，先画左边再画右边，重要结论用准确关键词后期写出；使用自然肤色 Q 版人物，先做代表镜头验证，再交付真实 MP4、SRT、时间轴和可编辑素材。
制作一个小黑风格 (怪诞小黑) 的抽象概念视频：

使用 $hand-drawn-explainer-video-nikola，用小黑风格解释这个方法：纯白背景、稀疏黑线、少量红橙蓝批注。要真实逐笔落墨，不要只做静图缩放；字幕和关键词必须准确。
制作一个手绘风格的流程卡片/关系图 (程序动画)：

使用 $hand-drawn-explainer-video-nikola，把这段内容做成手绘风流程卡片动画。使用可编辑 SVG/HTML，所有标题、数字和箭头关系必须确定性生成，并验证最终 MP4。

工作原理：收到指令后，Codex 会按照 SKILL.md 中定义的工作流，调用相应的脚本和渲染引擎，最终在指定目录下生成视频、字幕和素材工程。

五、两种制作路线详解

为了帮助你更好地选择，以下是两条路线的核心区别：

特性	逐笔故事动画 (Stroke Story)	程序动画 (Procedural Animation)
画面呈现方式	在同一画布上按语义区域持续落墨，先线稿后补色，已画内容保留，模拟真实手绘过程。	独立元素（卡片、人物、箭头）按时间轴移动、缩放、切换或描边。
核心技术	位图线稿提取 + skeleton/stream 连续笔迹 + 分区遮罩	HTML/SVG + GSAP + HyperFrames 动画框架
最适合	人物故事、历史叙事、白板讲解、一幅画逐步完成的场景。	流程、规则、关系、对比、需要精确文字和独立元素运动的场景。
不可混用	不能用整图淡入或卡片飞入冒充逐笔落墨。	不能称为“真实逐笔绘制”，但可产生精美的手绘风格动态。

六、常见问题与排错

脚本运行报错 python: command not found：你的系统可能未安装 Python 或未将其加入环境变量。请尝试使用 python3 替代 python。
提示缺少 FFmpeg：请根据你的操作系统安装 FFmpeg（Windows 可下载压缩包并添加到 PATH，macOS 可用 brew install ffmpeg，Linux 可用 apt install ffmpeg）。
生成最终 MP4 失败：确认 FFmpeg 安装正确，并且有足够的磁盘空间。
Codex 无法识别此 Skill：请确认你已将仓库克隆到正确的 Codex Skills 目录，并重启了 Codex 会话。
网络问题导致依赖下载失败：尝试配置 pip 或 npm 使用国内镜像源。
更详细的指南：项目内 docs/ 目录下包含了更深入的安装、配置、架构、风格指南和排错文档，建议查阅。

请确保你已阅读并遵守项目仓库中的 LICENSE 文件及相关开源许可，并注意云服务可能产生的费用。如果在使用中遇到问题，你也可以通过项目作者的 X/Twitter (@Nikola314159) 反馈，或在 GitHub 仓库提交 Issue。

Hand-drawn Explainer Video Nikola 部署与使用教程

一、 准备工作

二、 安装步骤