MohZhuang
66b61002f2
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
88 lines
4.2 KiB
Markdown
88 lines
4.2 KiB
Markdown
# 模板改编指南（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）。
|
||
|
||
```css
|
||
: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 重新表达。**
|
||
|
||
1. 读 `source/index.html` 或 `index.html` + `compositions/*.html`，提取：
|
||
- 配色（源码里的 `#RRGGBB`；目录 JSON 的 `colors` 字段已给线索）
|
||
- 字号层级 / 版式骨架（元素位置、栅格）
|
||
- 动效意图（谁先入场、位移方向、缓动感觉）
|
||
2. 用 CSS `@keyframes` + `animation-delay` 重写成单文件时间轴。
|
||
**`animation-delay` 就是时间轴** —— seek 渲染器靠它确定每一时刻的状态。
|
||
3. 若确需 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 档。
|
||
|
||
## 五、改编后的自检
|
||
|
||
```bash
|
||
# 单帧渲染验证（不必等整片）
|
||
node scripts/render_video.mjs <项目> --preview 5
|
||
# 抽帧看：字体是否本地、字幕带是否干净、动画是否真的在动
|
||
```
|
||
|
||
字幕带检查：抽一帧，确认底部 80–170px 区间内没有任何内容元素。
|