html-explainer

html-explainer 是由开发者 OneMoh 发起并持续维护的开源 Agent Skill，核心定位是“把一句话变成一个成品——给任意主题，产出一条带配音、硬字幕、封面的讲解视频，画面用 HTML/CSS/GSAP 写，全本地跑，核心链路零 API Key、零按次计费”。它不满足于做又一个“文生视频套壳”或“录屏剪辑工具”，而是将调研→解说词→配音→字幕与节拍→主题驱动风格编排→并行构建 HTML 场景→确定性逐帧渲染→QC 体检→多画幅封面整合于一条完整的 Agent 工作流中，全部配有 git clone 一行安装、Claude Code / Codex / WorkBuddy / Cursor / Gemini CLI 等主流 Agent 兼容，以及 MIT 开源协议。

一、html-explainer 是什么

html-explainer 采用“Agent 提需求 + 流水线执行 + 确定性渲染”的三层架构，通过 GitHub 完全开源发布，采用 MIT 许可证，仓库约 165–189 Stars、20–24 Forks。它的仓库根目录就是技能目录（SKILL.md 在根），遵循 Agent Skills 约定，Claude Code、OpenAI Codex、WorkBuddy、Cursor、Gemini CLI 等都能直接加载；内部是普通的 Python 与 Node 脚本，手工跑也完全没问题。

它的运作机制与市面上所有“AI 视频工具”都有本质区别。大多数“HTML 转视频”工具的做法是启动浏览器、播放动画、录屏——这条路会生出一整类间歇性 bug：动画在录制开始前就播了、网络字体加载晚了导致半段视频用了错误字体、前几帧拍到的是动画前的状态。html-explainer 选择另一条路：它不录制，它 seek——把 GSAP 时间轴精确定位到那一瞬间（tl.pause(t, false)），同步所有 CSS 动画（document.getAnimations().currentTime），等两个动画帧后截图。于是第 1204 帧与下一次渲染的第 1204 帧逐像素一致——QC 可以定点抽查，单个场景可以独立重渲，一整类时序 bug 从根本上无法发生。代价是每个动画都必须可 seek——墙钟动画（setInterval、requestAnimationFrame 计数、CSS transition 入场）不可能工作，会被 lint_frames.py 直接拒绝；这也正是动效库被设计成“t → 一组数字”的纯函数的原因：它天生可 seek。

二、html-explainer 能做什么

调研与解说词——把主题变成可核对的旁白（研）——不是“让模型直接生成一段听起来合理的文案”，而是“先查资料、再写解说词”。技能会带着 Agent 走完调研，收集主题相关资料，再生成旁白文本。项目还要求每条事实标注依据，没有来源支持的内容标出不确定性，不要补成事实。这种“证据约束”的设计，让讲解视频的内容质量从“看起来像”升级为“经得起核对”。

配音与字级时间戳——声音和字幕共用一套时间信息（音）——不是“配音完再手动对字幕”，而是“配音产出字级时间戳，字幕和画面节拍从同一份时间信息中派生”。默认走 edge-tts（免费、不用填 Key），也可以换火山引擎语音合成 2.0（豆包音色库、声音复刻、更自然的语气与更好音质）。两种引擎产出的 audio-manifest.json 结构完全一致——换引擎只是换一个字段的事，时间轴、字幕、渲染全都不用改。字幕跟着配音走，每个字的落点按真实发音时刻对齐；改一句词，画面自动重排，手动对位省了。

23 种画面风格 + 40+ 动效词汇——不用对着空白页从零设计（画）——不是“一种模板走天下”，而是“8 个类别的 23 种风格，每种都记录了画布、字阶、时间轴与配色纪律”。配套的动效库（40+ 动作词汇） 把“镜头语言”变成时间的纯函数——入场、承接、接触、运镜、环境五组，无状态、可组合、可逐帧 seek；随机数走 seededRng，渲染路径上不出现 Math.random()。

主题驱动模板编排——不再是“一片一模板”（编）——不是“选一个模板套到底”，而是“编排器读解说词本身，判断每场在片子里扮演什么角色”。style_director.py 读解说词推断每场角色（开场、陈述、数据、原理、例证、收束），挑主风格、搭次风格、决定开场变体与转场——产物里每场都有 why 说明。这意味着同一支视频里，不同场景可以有不同的视觉语法，而整体又保持统一。

确定性逐帧渲染与画质档位——从 1080p30 到 4K60（渲）——不是“只能出一种画质”，而是“画质与帧率自由组合”。--profile draft|balanced|final|master|legacy，或 --quality 1080p|2k|4k × --fps 30|60 自由组合；画质只改 deviceScaleFactor，布局逐像素不变。支持快门运动模糊（--shutter 180，在线性光下做多样本积分，不是 blur 滤镜）、多进程并行 + 断点续渲（--workers N 起独立浏览器进程，--resume 跳过已积分帧，--recycle N 长片定期重启浏览器防 OOM）。渲染前必须先问你选哪条中间帧通道（png-fast 默认推荐 / jpeg q95 / png / jpeg q82），落进 consent.json，由 gate_check.py --phase render 挡在渲染之前。

QC 体检与多画幅封面——交付前审完再交（验）——不是“导出 MP4 就结束”，而是“渲染前体检 + 成片后 QC”。lint_frames.py 在渲染前报出契约违规；qc_check.py 查响度、时长漂移、抽帧速览。封面横竖两版各自排版，不是拿一张图硬裁——竖版想投，再单独出一张 3:4 甚至 9:16 封面。产物包括 slug.mp4、cover_169.png、cover_34.png、slug.srt、slug.vtt、qc_report.md 和 qc_sheet.jpg。

三、html-explainer 适合谁用

知识科普与讲解视频创作者——需要把“为什么天空是蓝色的”这类主题做成一条 1 分钟的讲解视频，但录配音、校字幕、找画面、调节奏、做封面每一道工序都耗时。html-explainer 把后半程全接了，成品带配音、硬字幕和封面，全程本地跑。有用户用新号发了几条，没剪辑、没露脸、没花一分钱，几乎每条都有 1W 播放和可观的互动率。

AI 编码 Agent 的重度使用者——已经在用 Claude Code、Codex、WorkBuddy 等 Agent 进行日常工作，希望给 Agent 增加一项“把主题做成视频”的能力。技能安装就是一句 git clone，Agent 会自动完成环境检测和配置。

独立开发者与内容创业者——不想为视频生成服务按次付费，也不想把素材上传到第三方云端。html-explainer 的核心链路零 API Key、零按次计费，配音默认 edge-tts 免费可用，所有渲染在本地完成。

对“录屏式”视频工具不满意的创作者——受够了录屏带来的间歇性 bug：动画提前播了、字体晚加载了、前几帧拍错了。html-explainer 的 Seek 渲染从机制上杜绝了这一类问题，每一帧都是确定性输出。

需要注意的是它不适合谁：如果你需要的是真人实拍或复杂的 3D 角色动画，它专注的是“讲解/科普类 HTML 动画视频”；如果你没有 Python 3.9+、Node 18+、Chrome/Edge 和 ffmpeg 环境，需要先完成环境准备；临时帧图可能占用不少磁盘空间，项目给出的量级是每条视频约 2GB。

四、html-explainer 的应用场景是什么

一分钟知识科普视频从零到交付场景——用户对 Agent 说一句“把‘为什么天空是蓝色的’做成一条 1 分钟的讲解视频”，技能走完调研 → 解说词 → 配音 → 字幕与节拍 → 编排风格并写画面 → 渲染 → 体检 → 封面。成片带进度条、硬字幕和配音，封面横竖两版独立排版。

已有解说词的“后半程自动化”场景——稿子已经写好，但配音要自己录、字幕要一句句追、画面和封面还排在后面。html-explainer 把查资料之后的所有工序串成一条链，Agent 只管点头。解说词改了，字幕与画面节拍基于新音频自动重算，而不是靠人拖着时间轴一点点找位置。

小样验证与事实核对场景——先选一个一分钟以内、事实容易核对的主题做小样，把目标受众、时长、参考资料和画面比例写清楚，要求 Agent 先交解说稿与场景节拍表；事实核对过，再继续配音和渲染。这种“分段确认”的流程，让视频制作从“一把梭”变成可干预、可审查的过程。

多画幅投放与多平台分发场景——同一支成片需要适配横版和竖版投放。html-explainer 的封面不是从一张图硬裁，而是 16:9 和 3:4 各自独立排版，竖版投放再加 9:16。成片之外还产出 SRT/VTT 字幕文件和 QC 报告，方便交给其他平台或继续检查。

本地化、零外部依赖的视频生产场景——不需要 Remotion/npm 工程，不需要 html-video 仓库/Studio/pnpm/agent 后端。GSAP 内置、浏览器自动探测、ffmpeg 缺失时回退到 imageio-ffmpeg 静态二进制、网络字体被契约禁止——结构性离线的设计让它在没有稳定外网的环境里也能跑通。

五、html-explainer 为什么值得关注

从“录屏”到“Seek”——确定性渲染是质量的地基。录屏式工具的问题不是“做得不好看”，而是“每次做出来的不一样”：字体加载时机、动画启动时序、浏览器状态都会引入不可复现的差异。html-explainer 用 tl.pause(t, false) 把时间轴钉死在精确时刻，同步所有 CSS 动画后再截图，同一时间点重复渲染逐像素一致。这让 QC 可以定点抽查、单个场景可以独立重渲、一整类时序 bug 从根本上无法发生。在一个“AI 生成即抽卡”的时代，这种确定性本身就是稀缺品。

从“硬编码帧号”到“锚定字幕文本”的音画同步机制。大多数视频工具的画面切换是“第 30 秒切到第二场”——改一句解说词，整个时间轴就乱了。html-explainer 的画面动画触发点直接锚定在匹配的字幕文本上（通过 B('块文本') 函数），而非硬编码帧号。修改解说词后，全片时间轴自动重排，画面代码零改动。这种“以文本为锚点”的设计，把音画同步从“手动对位”升级为“结构对齐”。

23 种风格 + 40+ 动效词汇 + 主题驱动编排——把视觉设计从“从零画”变成“选与编”。大多数视频工具要么只给一种默认风格，要么要求用户自己写 CSS。html-explainer 内置 8 个类别、23 种画面风格，每种都记录了画布、字阶、时间轴与配色纪律；40+ 动效词汇把镜头语言变成时间的纯函数，无状态、可组合、可逐帧 seek。更关键的是 style_director.py 读解说词推断每场角色，挑主风格、搭次风格、决定开场变体与转场——不再是“一片一模板”，而是“一场一策”，且每场都有 why 说明。

“结构性离线”与密钥纪律——全本地不等于裸奔。项目明确“全本地跑，核心链路零 API Key、零按次计费”，但并没有把安全当儿戏：火山引擎的 API Key 只存 tts.env（已 gitignore），只有接口包读它，智能体拿不到也不需要读密钥；异常信息脱敏；check_integrity.py 有专门的密钥防线检查；打包排除密钥文件。项目甚至坦诚地说：“合成代码是在你本机执行的，运行时进程里密钥对那一段脚本可见，‘智能体绝对读不到’做不到。上面保证的是不进对话、不进仓库、不进日志、不进分发，把泄露半径收敛成一次可撤销的事故”。这种“知道自己边界在哪”的诚实，在 AI 工具中极为罕见。