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
6.4 KiB
6.4 KiB
封面指南（cover-guide）
成片出来后必须同时出两张封面。这不是可选步骤——封面决定点击率，而成片 只决定完播率；一张被切掉半个钩子的封面会让整片白做。
一、为什么是「两张独立排版」而不是「一张裁两版」
成片画布 1920×1080。平台上主页栅格按 3:4 裁：
| 从 16:9 裁 3:4 的算法 | 结果 |
|---|---|
h=1080 → w=810 |
丢掉 1110px = 57.8% 的画面宽度 |
| 钩子如果横跨全宽（大字常常如此） | 必被切，只留中间一截 |
所以「兼容 3:4 的版本」定义是：同一套视觉基因（配色/幕底/主视觉/钩子文案）， 为 3:4 画幅重新排一次版。两份是姊妹图，不是母子图。
frames/cover_169.html 1920×1080 → out/cover_169.png 抖音主封面（信息流/播放页）
frames/cover_34.html 1440×1080 → out/cover_34.png 主页栅格兼容（防切字）
二、两张封面各自的排版纪律
A. 1920×1080（抖音主封面）
| 项 | 规格 |
|---|---|
| 钩子字号 | ≥96px（建议 110–130px），全画面最大最亮 |
| 主体视觉 | 偏左或偏右，不要居中——信息流两侧会被 UI 压住 |
| 安全边距 | 四边 ≥96px；关键元素集中在中间 80% 区域 |
| 悖论视觉 | 放右侧时数字可到 140–160px |
| 底部 | 可放角标/栏目名（16:9 版底部不会被裁成方图），但仍留 ≥96px |
B. 1440×1080（兼容 3:4）
这是真正的 3:4（1440:1080 = 4:3，视觉上等价 3:4 的宽高比），不是裁出来的。
| 项 | 规格 |
|---|---|
| 钩子字号 | 120–150px —— 画幅窄了，字必须更大才够冲击 |
| 布局 | 上中下三段式：视觉在上 55%、钩子在下 45%，或反之 |
| 左右边距 | ≥110px（窄画幅比例上边距要更大） |
| 悖论视觉 | 改成竖排堆叠（16:9 是左右并置）——这是"重排"的核心动作 |
| 禁止 | 横跨全宽的细长元素（会被裁成断线）；贴边文字 |
重排对照（同一份内容，两种摆法）
| 元素 | 16:9 版 | 3:4 版 |
|---|---|---|
| 悖论视觉 | 右侧，左右并置 | 上方，竖排堆叠 |
| 钩子 | 左下，两行 | 下方，三行 |
| 角标 | 左上 | 顶部居中或省略 |
| 主视觉字号 | 数字 150px | 数字 120px（画幅窄，缩一档） |
| 钩子字号 | 118px | 138px（放大，抢占视觉） |
三、封面三要素（缺一返工）
A. 大字钩子
一句话让人停下。必须含反差/悬念，验证方法：把这句单独发出去，会不会有人点？
| 好钩子 | 坏钩子 |
|---|---|
| 同一件事，为什么两拨人的感受完全相反 | 关于 X 的几个事实 |
| 涨了 38%，他们却在退出 | XX 行业分析 |
| 这条规则，让所有人都在做同一件蠢事 | 今天聊聊 XX |
字号 ≥96px（3:4 版 ≥120px），关键词用 <em> + accent 色 + 柔光。
B. 核心悖论视觉
画面主体本身要在讲一个矛盾——不是装饰图形。可选形态：
- 双数对照：一升一降的两个数字（见模板
.paradox），最直接 - 分裂线：一道斜切/裂缝把画面分成两半，两侧不同色
- 撞色块：accent 与 signal 两个色块相互挤压/重叠
- 一明一暗：主体一半在光里一半在暗处
禁止：中性几何装饰、无意义的曲线、跟内容无关的图标。
C. 信息余量
平台四边会再裁一点（各平台 2–5% 不等）。
- 钩子距边 ≥96px（3:4 版 ≥110px）
- 不要有贴边文字、贴边细线
- 16:9 版的关键信息集中在中间 80%
四、尺寸与倍率
| 规格 | CSS 画布 | 实际输出像素 |
|---|---|---|
169 |
1920×1080 | 3840×2160（--scale 2 默认，2 倍清晰度） |
34 |
1440×1080 | 2880×2160 |
2 倍是为了应付平台压缩和高分屏；字节数约 1–3MB，上传无压力。
要 1 倍原尺寸用 --scale 1。
五、用法
# ① 复制模板，做两份（改尺寸 + 重排版式 + 填真实钩子）
cp <skill>/assets/cover-template.html <项目>/frames/cover_169.html
cp <skill>/assets/cover-template.html <项目>/frames/cover_34.html
# ② 渲染（默认 seek 到时间轴末尾取完整态）
node <skill>/scripts/cover_build.mjs <项目>
# 常用变体
node <skill>/scripts/cover_build.mjs . --at 0.8 # 取入场动画中间态（更有张力）
node <skill>/scripts/cover_build.mjs . --only 169 # 只出 16:9
node <skill>/scripts/cover_build.mjs . --jpg # JPEG（体积小，平台都收）
node <skill>/scripts/cover_build.mjs . --scale 1 # 不要 2 倍
产出：out/cover_169.png、out/cover_34.png、out/cover_report.md
六、上传策略
| 场景 | 用哪张 |
|---|---|
| 抖音信息流 / 播放页主封面 | cover_169.png（选「横版封面」） |
| 抖音个人主页栅格 | cover_34.png（选「竖版封面」） |
| 平台只允许一张 | 用 cover_34.png —— 多数主页栅格按 3:4 裁，16:9 会被切两侧 |
| 小红书 / 视频号 | 视平台；容器通常也接受 3:4，优先 cover_34 |
封面文字必须与视频首帧钩子一致（或至少同义）——观众点进来看到的是同一个承诺， 不一致会立刻跳出。
七、自检清单（上传前逐条过）
先跑终态测量，再逐条肉眼过。 封面排版验收必须在时间轴终态下做 （
__MG_RENDER__=true+tl.pause(tl.duration(), false)），否则量到的是 入场动画起始值，边距/行数全错（lessons #30）。可照scripts/lint_frames.py的思路自写一个十余行的测量器：行数 / 四边边距 / 元素重叠 / 钩子字号一次判完。
- 两张封面都出了，都是独立排版（不是裁切关系）
- 钩子字号：16:9 版 ≥96px、3:4 版 ≥120px
- 钩子在任何画幅下都不被切（四边留 ≥96px / ≥110px）
- 钩子每行 ≤ 上限（16:9 ≤7 字、3:4 ≤5 字）；用「行宽 ≈ 字数×字号×(1+ls) ≤ 容器宽」反算，防孤字断行
- 悖论视觉是"真矛盾"（两个对数/一明一暗/分裂线），不是装饰
- 一份封面只有一个视觉焦点（大字钩子是最大的那个）
- 配色全部来自
theme.css（与成片同一主题，不串色） - 没有贴边文字、没有横跨全宽的细线
- 封面文字 = 视频首帧钩子（同义）
- 3:4 版的数字/标签已按窄画幅缩一档、钩子放大一档