html-explainer：把"我想讲清楚这件事"变成一条能发布的视频

一、凌晨两点，你有一个选题

"为什么天空是蓝色的"——这个念头冒出来的时候，你并不想写脚本、剪时间轴、找配音、调字幕。你只想把一个知识点变成一条能发出去的短视频。

html-explainer 就是干这件事的：给任意主题，产出一条带配音、硬字幕、封面的讲解视频。 画面用 HTML/CSS/GSAP 写，Python 与 Node 负责渲染，全程本地跑，核心链路零 API key、零按次计费。

二、它不是"AI 生成视频"，而是一条确定性流水线

这是理解该项目的关键。2024 年以来满屏的"文生视频"都是概率性的——同样的提示词，两次渲染结果可能天差地别。而 html-explainer 反其道而行：

用代码写画面，逐帧确定性渲染，输出真 MP4。

• 画面：HTML/CSS + GSAP 离线动画库（40+ 动作词汇）
• 渲染：playwright-core 无头浏览器逐帧截图 → ffmpeg 合成，支持 4K60、快门运动模糊、多进程并行、断点续渲
• 配音：edge-tts（钉死 7.2.8 版本）
• 字幕：词级时间戳对齐的硬字幕
• 节拍：B('块文本') 节拍器把画面切点直接锚在吐字时刻上

音画同步不是"尽量对齐"，是"结构上必然对齐"。 这是它和所有 AI 视频工具最本质的区别。

三、风格库：把菜谱抄回家

项目最有意思的设计决策，是它的风格来源。

作者明确写道：风格库是**"抄下来的设计规范文本"**（references/style-catalog.md），来自 html-video 项目（Apache-2.0）。作者自己的比喻很贴切——"把菜谱抄回家，之后做菜不需要原餐厅营业"。

23 个模板风格、8 大类别，全部以设计规范而非代码形式存在。每个模板规定了画布尺寸、字体、配色纪律、时间轴节奏。运行时只读自己的规范文件，不读任何来源项目的文件，因此完全独立可移植。

更有意思的是它区分了两种用法深度：

• 讲解片：从 23 个模板里挑一个，按 template-guide.md 改编成帧
• 宣传片（去模板化）：只吸纳配色/字体/时序骨架三层，画面语言用 assets/motion.js 重写

配合 scripts/style_director.py 编排器——它读解说词本身，判断每一场在片子里扮演什么角色，再挑风格、混用、决定开场与转场。

四、六个确认闸门：把"AI 冲动"关进笼子

这是我认为这个项目最值得学习的设计。

流程中有六个用户确认点，由用户拍板才放行。其中第五个是硬闸门：渲染前必须明确选择渲染通道（png-fast / jpeg q95 / png / jpeg q82），默认推荐 png-fast，并附上速度与画质描述。

为什么要这么做？因为 AI 视频生产最典型的失败模式是一路狂奔到底，最后才发现方向错了。把"选风格""选通道"这类关键决策显式卡在中间，每一步都留有纠偏机会。scripts/gate_check.py 强制执行这套流程，consent.json 记录用户拍板结果。

五、工程严谨度：超出"个人项目"的水准

• CI 矩阵：Ubuntu + Windows-latest × Python 3.9 + 3.13。Windows 不是事后补的，作者明说"Windows + Git Bash 是主要开发平台"
• UTF-8 强制：PYTHONUTF8: "1"，注释写明"Windows runner 的管道默认编码是 cp1252，脚本输出 ✓ 等字符会直接 UnicodeEncodeError——全局强制 UTF-8：ubuntu 上无感，windows 上是生死线"
• 仓库自洽性检查：scripts/check_integrity.py 检查版本号漂移、风格目录漂移、残留外链
• 测试：tests/ 含 Node 原生测试（motion、beats_norm、subs_text）与 Python 测试（style_director、skill_frontmatter）
• 依赖极简：Node 侧只有 playwright-core 一个依赖；GSAP 离线随包携带；ffmpeg 缺失时自动回退到 imageio-ffmpeg 静态二进制
• 环境自检：setup_env.sh 适配 Windows/macOS/Linux，全部装用户级无需管理员，且先尝试装再判定缺失，避免误报

六、局限与争议

依赖重。 需要 Python 3.9+、Node 18+、Chrome 或 Edge、ffmpeg——对于只想发一条视频的用户，安装门槛高于预期。setup_env.sh 缓解了这点，但没能消除。

能力边界明确。 它是讲解/科普/教学/知识/产品类视频的流水线。宣传片、剧情片、UGC 口播都不在射程内。想清楚这点比什么都重要。

"确定性"的代价。 逐帧渲染意味着不能像文生视频那样"用算力换惊喜"。所有视觉表现都在 HTML/GSAP 的表达能力边界内。

内容生态依赖第三方。 风格库抄自 Apache-2.0 的项目，虽然是设计规范文本而非代码，作者仍在 THIRD_PARTY_NOTICES.md 中做了完整署名——合规姿态值得肯定，但这类"设计规范抄写"的边界仍存在讨论空间。

版本迭代快。 v2.0.7，CHANGELOG 活跃，作者明确说 v2.0 新增能力"不用就是 v1.4 行为"——向下兼容做得不错，但文档负担也随之上升。

七、行业意义：Agent Skill 形态的样板

这是 2026 年 AI 工具的新形态——不是一个软件，而是一套写给 Agent 的工作手册。

仓库根目录就是技能目录（SKILL.md 在根），遵循 Agent Skills 约定，Claude Code、OpenAI Codex、WorkBuddy、Cursor、Gemini CLI 都能直接加载。内部是普通 Python 与 Node 脚本，手工跑也完全没问题。

安装方式简单到一句话：

给当前本地环境安装该 Skill：https://github.com/OneMoh/html-explainer.git
安装到你的技能目录，并检测安装必要的运行环境

207 star、27 fork、单人项目，却给出了 71% 的仓库健康度和一套接近企业级的 CI 规范。这说明在 Agent Skill 这个新形态上，"项目小"不再等于"工程差"——因为 Agent 承担了执行者角色，代码的职责从"提供功能"转向"提供确定的行为约束"。

对公司的启示：内部若要沉淀 Agent 工作流，值得参考这种**"SKILL.md + scripts/ + references/ + 硬闸门"**的四层结构，尤其是把关键决策点做成显式确认闸门这一条。

---

分析基于 GitHub API 实时数据：207 stars / 27 forks / MIT / Python+JavaScript / v2.0.7 / 80 个文件 / CI 矩阵 4 组合 / 仓库健康度 71%