0 Fork 0

Files

T

MohZhuang 66b61002f2 chore: prepare html-explainer v1.2.2 for public release

First public release of the html-explainer skill: deterministic HTML-to-MP4 explainer video pipeline for AI coding agents.

Additions since v1.2.1:

- scripts/lint_frames.py: pre-render audit of the eight frame-contract rules
- scripts/peek_frame.mjs: single-scene screenshot preview (seconds, not minutes)
- scripts/check_integrity.py: version/catalog/count consistency + stray-CDN scan
- Bilingual README (README.md Chinese default, README.en.md English)
- LICENSE (MIT), THIRD_PARTY_NOTICES.md, licenses/Apache-2.0.txt
- CHANGELOG.md, CONTRIBUTING.md, .gitignore, .gitattributes
- GitHub CI workflow and issue/PR templates

Fixes and docs:

- document lint_frames.py and peek_frame.mjs, previously absent from the file table
- add the lint stage to the pipeline order
- remove references to private client projects so the skill can ship publicly
- record the full upstream attribution chain for the style catalog
- package_skill.py now excludes repo-hygiene files and keeps licence files

2026-09-21 12:46:23 +08:00

4.2 KiB

Raw Permalink Blame History

模板改编指南（html-video 模板 → html-explainer 帧）

本技能的画面语言来自 html-video 的 23 个模板 / 8 个类别。 references/style-catalog.md 是完整目录，本页讲怎么把它变成合规帧。

一、先看模板属于哪一类

类型	数量	结构	处理方式
★ rich	12	单文件 + 纯 CSS `@keyframes`；带完整风格规范	几乎零改动：换字体栈 + 让出字幕带 + 填内容
gsap	11	多 composition + CDN GSAP，或 Remotion 引擎	需重写为单文件（照风格规范复刻，不要搬代码）

判断方法：references/style-catalog.md 速查表的「类型」列，或看 JSON 目录的 kf 字段（kf≥1 且 multi=false 且 engine≠remotion = rich）。

二、rich 模板改编（三步）

第 1 步：换字体栈（必须）

模板原文一律 <link href="https://fonts.googleapis.com/...">。 必须删掉，换成系统字体栈 —— 这是离线渲染的硬要求（详见 lessons.md #8）。

:root{
  /* 中文优先的系统栈；display 用 Impact/Arial Black 兜住"超大粗体"的观感 */
  --font-display: "Impact", "Arial Black", "Microsoft YaHei", "PingFang SC", sans-serif;
  --font-body: -apple-system, "Segoe UI", "Microsoft YaHei", "PingFang SC", sans-serif;
}

然后把模板里的 font-family: 'Archivo Black' 等替换为 var(--font-display)。

第 2 步：让出字幕带

模板不知道自己会被叠字幕。底部 80–170px 是字幕带，不许放内容。

模板里的 bottom: 74px / bottom: 92px / bottom: 104px 这类值一律抬到 bottom: 176–210px。参考 lessons.md #10。

第 3 步：填真实内容

从模板的 example.md 看它期待哪些字段（如 bold-signal 要 section / nav / card_label / title）。必须用真实内容，严禁 lorem ipsum。

三、gsap 模板改编（重写，不搬代码）

多 composition + GSAP 的结构在单帧里没有起播钩子，直接搬进 seek 渲染器会得到静止首帧、且零报错（这正是 lessons.md #9 的 __hvUnfreeze 整类坑）。

正确做法：只取它的视觉 DNA，用纯 CSS keyframes 重新表达。

读 source/index.html 或 index.html + compositions/*.html，提取：
- 配色（源码里的 #RRGGBB；目录 JSON 的 colors 字段已给线索）
- 字号层级 / 版式骨架（元素位置、栅格）
- 动效意图（谁先入场、位移方向、缓动感觉）
用 CSS @keyframes + animation-delay 重写成单文件时间轴。 animation-delay 就是时间轴 —— seek 渲染器靠它确定每一时刻的状态。
若确需 GSAP：用本技能内置的 assets/gsap.min.js（离线），并把时间轴注册到 window.__tl（见 references/frame-contract.md 契约 2）。

四、挑风格的实用建议

内容需求	推荐风格
开场 / 章节分隔	`frame-bold-signal`（橙卡滑入）、`frame-bold-poster`（海报大字）
高级感 / 极简	`frame-build-minimal`（70% 留白 + 暖金细线）
单个关键数字	`frame-pentagram-stat`（瑞士网格 + 巨型数字）、`frame-nyt-graph`
数据对比 / 趋势	`frame-data-chart-nyt`（NYT 编辑级图表）
概念关系 / 流程	`frame-takram-organic`（柔和有机）、`frame-decision-tree`（分支流程）
科技 / 赛博	`frame-glitch-title`（故障艺术）、`vfx-text-cursor`（光标拖光）
金句 / 引用	`frame-electric-studio`（白蓝分屏引言）
收尾 / 品牌	`frame-logo-outro`（Logo 组装 + glow）
电影感空镜	`frame-light-leak-cinema`（漏光 + 颗粒 + letterbox）

挑风格时同时看时长档：frame-bold-signal 是 3–6s 的短片花，硬拉到 20s 会显得空。长段（>10s）优先 frame-swiss-grid / frame-kinetic-type / frame-nyt-graph 这类 3–30s 档。

五、改编后的自检

# 单帧渲染验证（不必等整片）
node scripts/render_video.mjs <项目> --preview 5
# 抽帧看：字体是否本地、字幕带是否干净、动画是否真的在动

字幕带检查：抽一帧，确认底部 80–170px 区间内没有任何内容元素。

4.2 KiB Raw Permalink Blame History Unescape Escape