MohZhuang
2581e2c685
README 精简（中文 528 → 364 行，-31%；英文 552 → 390 行，-29%）： - 删除使用者不需要的深层细节，改为指向 references/ 与 SKILL.md： 横向对比全表、八条契约表、project.json 逐字段说明、仓库目录树、B() 代码详解 - 第一定位改为「Agent Skill」，而不是「一条渲染流水线」 - 新增「安装」章：一句话安装 prompt + 九个智能体的技能目录对照表 + 环境要求 - 新增「参考思路与姊妹项目」：anything2explainer 与 html-video，并明确标注 两者为不同作者的独立项目，本项目运行时不依赖其代码 文档语言统一为中文（README.en.md 除外）： CHANGELOG.md、CONTRIBUTING.md、THIRD_PARTY_NOTICES.md、PR/issue 模板、CI 注释。 许可证原文（MIT / Apache-2.0）与 GSAP 自带 README 属第三方逐字文本，未翻译。 跨平台可移植性修复（原先隐含 WorkBuddy 专属路径）： - peek_frame.mjs 的技能根兜底改为遍历各智能体技能目录 （.workbuddy / .claude / .codex / .gemini / .cursor / .agents），已用隔离夹具正反验证 - setup_env.sh 标注哪几个候选是 WorkBuddy 托管路径 - SKILL.md 新增「跨 Agent 安装」章，安装路径不再写死单一平台 修正一处事实错误：THIRD_PARTY_NOTICES 原称两个方法来源项目「均为作者本人作品」， 与事实不符，已改为「他人独立项目」并补充来源链接。
6.8 KiB
6.8 KiB
变更日志
html-explainer 的所有重要变更都记录在这里。
格式遵循 Keep a Changelog， 版本号遵循语义化版本。
1.2.2 之前的版本都是私有内部发布。1.2.2 是 GitHub 上的首个公开版本。
1.2.2 — 2026-09-21 — 首个公开版本
新增
scripts/lint_frames.py—— 渲染前的画面静态体检。在花时间渲染整片之前，先检查八条 画面契约与已知坑：外部字体 / CDN 引用、硬编码颜色字面量、缺失window.__tl注册、 CDN 版 GSAP、墙钟逻辑（setInterval、requestAnimationFrame计数）、CSStransition入场、B('…') || 数字兜底写法、侵入字幕禁区的内容、缺失中文字体族。scripts/peek_frame.mjs—— 单帧速览。把一个场景 seek 到若干时点截图，耗时是秒级， 于是不用渲全片就能判断画面设计。--at收的是百分比，不是帧号。- 双语项目 README（
README.md中文为默认，README.en.md英文）。 - 开源治理文件：
LICENSE（MIT）、THIRD_PARTY_NOTICES.md、CHANGELOG.md、CONTRIBUTING.md、licenses/Apache-2.0.txt、.gitignore、.gitattributes、 GitHub issue / PR 模板，以及 CI 工作流。
修复
speech_end_sec在冷跑与缓存重跑之间不一致（lessons #31）。_result()量的是已经裁过 静音的输出文件，于是头部裁剪量被减了两次：冷跑报7.541s，缓存重跑报7.696s—— 0.155s 的差异破坏了「两次渲染逐帧一致」的保证，并让末块字幕提前消失。现在统一存裁后 坐标系下的值。
变更
- 文档：
scripts/lint_frames.py与scripts/peek_frame.mjs补进命令序列与文件表 （两者此前都没有被文档记录）。 - 文档：lint 现在是工作流里的显式阶段，位置在生成字幕之后、渲染之前。
- 文档：删除对私有客户项目的引用，使技能可以公开发布。
- 许可：风格目录衍生自 Apache-2.0 内容，现已带上完整的来源署名。
备注
- 从实战回填：预览渲染会清空帧目录（
--keep-frames）、重渲单个场景的临时项目法、 以及「开场 0.5 秒内就必须出现主角」的冷开场规则（lessons #32–#34）。
1.2.1 — 2026-09-20
四个渲染 / QC 正确性修复，全部是靠给渲染器加探针找出来的，而不是靠肉眼看。
详见 references/lessons.md #27–#30。
修复
tl.pause(t)会静默吞掉本次 seek 的回调。 GSAP 的签名是pause(atTime, suppressEvents)，第二参默认为true，于是 seek 触发的任何onUpdate/onStart/onComplete都被丢弃。用onUpdate写的计数器因此在成片里恒为 初值 —— 不报错、不告警、缩略图尺寸正确，静态检查也查不出来。渲染器与封面器现在调用tl.pause(t, false)。文档同时把数字滚动引导向纯 transform 的「数字卷轴」， 完全不依赖任何回调。- 传给
chromium.launch()的deviceScaleFactor被静默忽略。viewport与deviceScaleFactor都是 context 级选项，只在newPage()上生效。封面实际写成了 1 倍图， 而日志声称 2 倍。现在构建用 PIL 核验输出尺寸，不再信日志。 - QC 抽样只覆盖了视频前四分之一。
qc_check.py取字幕块起始时间后写成pts[:samples]， 拿的是前 N 块而不是均匀铺开。一条 39 块的视频抽了 12 块，只覆盖 0.25–23.86s，后 6 个 场景一帧没抽，却报告「全部通过」。现在按步长在全片范围均匀抽样。 - 封面排版是在动画中途量的。 校验紧接页面加载后就跑，读的是
fromTo起始值而不是稳定 终态，于是报出幽灵偏移。现在测量前先置__MG_RENDER__并 seek 到tl.duration()， 与封面渲染器完全一致。
1.2.0 — 2026-09-20
新增
- 封面双方案。 每条成片现在产出两张独立排版的封面而不是一张：
cover_169.png（1920×1080，输出 3840×2160）用于信息流与播放器，cover_34.png（1440×1080， 输出 2880×2160）用于主页栅格。scripts/cover_build.mjs—— 封面渲染器，复用场景渲染器的确定性 seek 内核，但有三处 刻意不同：不带字幕层、只 seek 到单个「封面时刻」（默认--at last）而不是逐帧步进、 以及默认 2 倍输出。assets/cover-template.html—— 封面模板，三个必需元素写在文件头注释里。references/cover-guide.md—— 重排对照表、尺寸规则、上传策略与自检清单。
scripts/new_project.py现在会把两份封面 HTML 一起生成到新项目里。
备注
- 两张封面是共享同一套视觉基因的姊妹版式，绝不是一对裁切。从 16:9 裁 3:4 会丢掉 57.8% 的画面宽度（1920 → 810px），必然把大字钩子切掉。重排改的是构型本身：悖论视觉 从「右侧左右并置」变成「上方竖排堆叠」，钩子从两行变成三行。
1.1.0 — 2026-09-20 — 首个打包发布
新增
- 核心流水线：
new_project.py→tts_build.py→timeline_build.py→subs.py→render_video.mjs→qc_check.py。 - 确定性 seek 渲染器（
render_video.mjs）。不录活页面的屏，而是每一帧都靠 seek GSAP 时间轴（tl.pause(t, false)）并同步 CSS 动画 （document.getAnimations().currentTime = t*1000）后再截图。这消掉了实时录制的一整类 失败：没有起播竞态、没有字体加载超时、没有不稳定的引导期。 B('块文本')节拍同步。 画面动画按匹配字幕块文本定位，而不是写死帧号，于是改解说词 会重排全片时序，而一个画面文件都不用动。scripts/subs.py—— 字幕三出口（运行时 JSON、SRT/VTT 外挂、渲染器注入的画面内层）， 外加每场景生成一份beats.js。scripts/make_theme.py—— 四个预设 + 按主题词推色，写出唯一颜色来源theme.css。scripts/qc_check.py—— 流 / 时长 / 响度 / 抽帧体检，附抽帧速览图。scripts/import_styles.py—— 移植期一次性工具，把模板设计规范转写成references/style-catalog.md/.json。- 23 种画面风格目录，8 个类别，按改编成本分类。
setup_env.sh做首次环境自检，--install装缺失依赖；package_skill.py打可移植 zip。