html-explainer

一个 Agent Skill：给任意主题，产出一条带配音、硬字幕、封面的讲解视频。

HTML 写画面 → 确定性逐帧渲染 → 真 MP4。全本地跑，核心链路零 API key、零按次计费。

画面用一套可 seek 的动效库写，风格由主题驱动编排，渲染支持 4K60、快门运动模糊与多进程并行。

简体中文 · English

两条用本技能生成的成片——画面、配音、字幕、封面全部由流水线产出，无手工后期。 封面等素材托管在演示仓库，本仓库零体积。

港股创新药 · 早盘	量化简史
https://github.com/user-attachments/assets/8007843c-088d-457c-8550-81ec912e0add	https://github.com/user-attachments/assets/28949988-449b-4c4e-8d0f-6706af6f64ee

---

它是什么

html-explainer 把一个主题做成带配音、带硬字幕、带进度条的讲解视频，画面用 HTML/CSS/GSAP 写。

它是一个 Agent Skill（SKILL.md + scripts/ + references/），遵循 Agent Skills 约定，Claude Code / OpenAI Codex / WorkBuddy / Cursor / Gemini CLI 等都能直接加载。内部是普通的 Python 与 Node 脚本， 手工跑也完全没问题。

你只需要说一句：

把「为什么天空是蓝色的」做成一条 1 分钟的讲解视频。

技能会带着智能体走完：调研 → 解说词 → 配音 → 字幕与节拍 → 编排风格并写画面 → 渲染 → 体检 → 封面。

画面不必对着空白页从零写。技能内置一套可 seek 的动效库（40+ 动作词汇，见 动效库与模板编排），和一份模板编排器 —— 它读解说词本身，判断每场在片子里 扮演什么角色，再挑风格、混用、决定开场与转场；渲染层则支持 4K60、快门运动模糊与多进程并行。 这些开关都是可选的：不带任何参数跑，就是一条最朴素的 1080p30 片子。

---

安装

一句话安装（推荐）

把下面这句发给你的智能体：

给当前本地环境安装该 Skill：https://github.com/OneMoh/html-explainer.git
安装到你的技能目录，并检测安装必要的运行环境（Python 3.9+ / Node 18+ / Chrome 或 Edge / ffmpeg）

它会自己 clone 到对应目录、跑环境自检、把缺的东西装上。装完新开一个会话，让智能体重新 扫描技能目录。

手动安装

仓库根目录就是技能目录（SKILL.md 在根），直接 clone 进技能目录即可，不用再拷子目录：

git clone https://github.com/OneMoh/html-explainer.git ~/.workbuddy/skills/html-explainer
bash ~/.workbuddy/skills/html-explainer/setup_env.sh --install

Windows 上 ~ 就是 C:\Users\<你的用户名>。

各智能体的技能目录

智能体	个人级（全局）	项目级（仓库内）
WorkBuddy	~/.workbuddy/skills/	<工作区>/.workbuddy/skills/
Claude Code	~/.claude/skills/	.claude/skills/
OpenAI Codex	~/.codex/skills/	.codex/skills/ 或 .agents/skills/
Gemini CLI	~/.gemini/skills/	.gemini/skills/ 或 .agents/skills/
Cursor	~/.cursor/skills/	.cursor/skills/
GitHub Copilot / VS Code	~/.copilot/skills/	.github/skills/
OpenCode	~/.config/opencode/skills/	.opencode/skills/
Windsurf	~/.windsurf/skills/	.windsurf/skills/
其他（通用约定）	~/.agents/skills/	.agents/skills/

记不住放哪：优先 .agents/skills/，多数工具都认它（Claude Code 是例外，只认 .claude/skills/）。

环境要求

项	最低	说明
Python	3.9+	edge-tts==7.2.8（刻意钉死 —— v7 改过边界 API）、numpy、pillow、imageio-ffmpeg。火山引擎引擎零额外依赖（只用标准库 urllib，不需要装 SDK）
Node.js	18+	渲染器与封面器用
浏览器	Chrome 或 Edge	自动探测；都没有才下载 playwright chromium（约 115MB，只需一次）
ffmpeg	任意版本	先在 PATH 找；没有则用 imageio-ffmpeg 自带的静态二进制
磁盘	每条成片约 2GB	帧 PNG 体积大，合成后可删

bash setup_env.sh 只检查并报告缺什么，--install 才会装。全程不需要管理员权限。 动效库、编排器与全部渲染档位都只用上面已声明的库，没有引入任何新的运行时依赖。

---

配音：两个引擎

流水线开始前，智能体会先问你用哪个 TTS，再列候选音色让你挑（也可以直接给它音色 ID）：

	edge-tts	火山引擎语音合成 2.0
你要做什么	什么都不用做	填一次 API Key
费用	免费	按字符计费
音色	内置中英文若干	豆包 2.0 音色库，含声音复刻
字级时间戳	WordBoundary	sentence.words[]
额外依赖	edge-tts==7.2.8、imageio-ffmpeg	零 —— 只用标准库 urllib
什么时候选它	默认。开箱可用、够用	想要更自然的语气与更好音质

两者产出的 audio-manifest.json 结构完全一致，所以时间轴、字幕、渲染全都不用改 —— 换引擎只是换一个字段的事。

选火山时，你唯一要动手的地方

技能第一次跑火山时会生成一个 tts.env 并停下来，然后告诉你把 API Key 填进去 （火山控制台 → 语音技术 → API Key 管理）。你填好回来说一声，智能体就去测连接、确认音色， 然后接着往下跑。