0 Fork 0

Files

T

MohZhuang 2581e2c685 docs: 重构 README 并统一文档语言为中文

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 原称两个方法来源项目「均为作者本人作品」，
与事实不符，已改为「他人独立项目」并补充来源链接。

2026-09-21 13:11:22 +08:00

6.1 KiB

Raw Blame History

参与贡献

感谢你愿意花时间。本文只说实际的东西：怎么把环境跑起来、项目的硬性规则有哪些、以及不同类型的贡献该往哪儿放。

可以贡献什么

贡献类型	该往哪儿放
报告 Bug	用 bug 模板开一个 issue
你已定位的渲染 / 同步问题	在 `references/lessons.md` 追加一条编号记录，并且修代码
新的画面风格，或更好的改编配方	更新 `references/style-catalog.md`，并附一个可运行的示例
文档修正	直接提 PR —— 改错别字不需要先讨论
新功能	先开 issue 把方案谈拢，再动手写
平台相关修复（macOS / Linux 路径、其它 shell）	非常欢迎 —— 本项目在 Windows + Git Bash 上开发

开发环境

git clone https://github.com/OneMoh/html-explainer.git
cd html-explainer

# 先自检，再装缺的东西
bash setup_env.sh            # 只报告
bash setup_env.sh --install  # 安装缺失依赖

# 确认工具链正常
node -v && python -V

要求：Python ≥ 3.9、Node ≥ 18，以及 Chrome 或 Edge（两者几乎总是已经装好）。 ffmpeg 优先从 PATH 取，取不到则回退到 imageio-ffmpeg 自带的静态二进制。

跑一次端到端自检

python scripts/new_project.py demo --topic "人工智能"
cd demo
# 填 narration.json、写 frames/*.html、设置 project.json 的 order
python ../scripts/tts_build.py      --project .
python ../scripts/timeline_build.py --project .
python ../scripts/subs.py           --project .
python ../scripts/lint_frames.py    --project .
node   ../scripts/render_video.mjs  . --preview 30

如果这些全部跑完、out/preview.mp4 播放时音画同步，你的环境就没问题。

项目的硬性规则

这些不是风格偏好。违反它们会产生静默失败 —— 视频能渲出来，但是错的。凡是能自动检查的，都由 scripts/lint_frames.py 强制。

任何画面帧里都不许引外部字体或 CDN 资源。 网络字体在很多网络下不可达，而且超时是静默的。只用系统字体栈，GSAP 一律从随包的 ../assets/gsap.min.js 引用。
颜色只能取 theme.css 的 CSS 变量。 画面代码里不许出现十六进制字面量 —— 这正是「换主题只改一个文件」得以成立的原因。
不许有墙钟逻辑。 setInterval 与 requestAnimationFrame 计数在确定性 seek 下不可能工作。动画用 GSAP 或 CSS @keyframes。
动画用 GSAP 时间轴，并注册到 window.__tl。 渲染器每帧 seek 这个时间轴；没有它，什么都不动。
动画定位用 B('块文本')，绝不用写死的时间。 兜底写法 B('x') || 3.2 是被禁止的 —— 块查不到就应该在构建时大声失败，而不是静默复用一具过期的数字。
保持字幕禁区干净。 底部 80–170px 不许有任何内容渲染，入场路径也不许穿过它。
项目目录与输出文件一律用 ASCII 路径。 非 ASCII 路径会让 Windows 上的 ffmpeg 出错。项目名与输出名保持 ASCII，要展示用的名字以后再改。

完整契约（每条规则背后的理由，以及会被打回的反例）见 references/frame-contract.md。

追加一条踩坑记录

references/lessons.md 是这个仓库里最值钱的文件。它之所以存在，是因为这条流水线的失败方式是静默的 —— 出问题不会报错，只会产出一条看着挺像样的视频。

一条好的记录按这个顺序写：

症状，就按你最初观察到的样子 —— 包括它是怎么把你带偏的。
定位过程，以及证明病因的证据（探针、diff、测量值）。
修法，以及修完该检查什么来确认。
由此得出的通用规则（如果确实能推出的话）。

编号顺次追加。不要给已有条目重新编号 —— 代码注释里在引用这些编号。

追加一种画面风格

在 references/style-catalog.md 与 references/style-catalog.json 里记录规范（画布、字阶、时间轴结构、配色纪律）。
分类为 rich（单文件，CSS @keyframes 时间轴 —— seek 渲染器零改动可驱动）或 gsap （多 composition —— 必须重写表达，不能照搬）。
如果这种风格需要超出标准三步（换字体栈、把底部元素抬出字幕带、填真实内容）之外的处理，在 references/template-guide.md 里补一条改编配方。
验证它能渲出来：node scripts/peek_frame.mjs <project> <id> --at 25,50,85。

风格标识符用 kebab-case，并沿用已有的命名模式（frame-*、vfx-*）。

PR 检查清单

提 PR 之前请确认：

python scripts/lint_frames.py --project <project> 对你动过的每一帧都没有 FAIL
你真的渲染过你的改动。画面代码「看着对」经常是不对的 —— seek 渲染有自己的失败模式
新增的踩坑记录已带编号写进 references/lessons.md
没有引入外部字体、CDN 引用或硬编码颜色
如果有再分发或再衍生的第三方内容，THIRD_PARTY_NOTICES.md 已更新
涉及使用者可见行为的改动，README.md 与 README.en.md 已同步更新

提交信息

建议使用 Conventional Commits（fix:、feat:、docs:、chore:）。如果这次改动修的是一个静默失败，请写正文说明它原来错在哪、你是怎么验证修好了的。

范围说明

本项目刻意不打算成为一个框架。它是一条流水线，接口很小、很无聊：HTML 帧进，MP4 出，音画同步稳得住。会增加构建系统、插件 API，或对云服务产生运行时依赖的功能，一般都在范围之外 —— 如果你认为有重要的例外，开个 issue 聊聊。

许可

提交贡献即表示你同意你的贡献以 MIT 许可授权（见 LICENSE），并确认你有权提交它们。如果你从别的项目移植了内容，请在同一个 PR 里把它写进 THIRD_PARTY_NOTICES.md。

6.1 KiB Raw Blame History Unescape Escape