更新日志 → 品牌化视频
输入：更新日志 .md（主题 + 项目，如每周 HyperFrames 摘要）。
输出：一个经过 lint 清理、符合“缝-门-绿色”标准的 HyperFrames 项目，位于
projects/active/weekly-changelog-<range>/。仅当用户要求时才进行渲染。
首先加载，不可协商： motion-doctrine（+ cut-the-curve、
oversized-cursor（如果出现光标）、seam-craft）和 captions-overlay。
此技能提供更新日志专用管道；运动教义提供运动法则。
首要指令：可视化，而不是列出
每个主题都通过实际 UI 的动画模拟或一个忠实类比来表现，这个类比要演绎出体验上的变化——绝不使用文本子弹点。在编写脚本之前，将每个主题/项目路由到 references/visualization-registry.md；该注册表决定采用 ui-recreate / ui-analog / terminal / checklist 中的哪一种。文本检查表是最后的手段，仅用于真正无法可视化的项目（可靠性修复列表）。
管道
0 · 从此技能的资产启动项目——不可协商
在编写任何合成 HTML 之前执行此操作。跳过它总是会产生一个看起来像你以前构建的类似项目的视频，而不是此技能的品牌——这是该技能偏离品牌的最常见方式。 技能的资产、字体和脚手架就是技能本身；SKILL.md 提示是一个路由器。
mkdir -p project/assets/fonts
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
然后从头到尾阅读 references/build-spec.md（不要略读）——它定义了品牌标记（TT Norms Pro + ABC Solar Display + TT Norms Mono、奶油色 #f5f6f4、限量绿色 #5ef17c、带有绿色边框的玻璃卡片、kicker/sec-chip 药丸形状、位于 top: 990 的 32px 字幕轨道），每个场景都从脚手架继承这些标记。
只有然后开始下面的步骤 1-6。步骤 1-4（解析、路由、脚本、VO）规划要放入脚手架的内容；步骤 5 在已复制的 project/index.html 中填充占位符（<RANGE>、<TOTAL>、<CUT_N>、<DUR_N>、场景主体）——你不要重写脚手架的镀铬、字体、调色板或布局外壳。
如果你发现自己正在使用 cp 复制先前视频的 index.html，或者编写自己的 @font-face 声明，或者设计 WebGL 着色器背景而不是使用上面编码的 bg-pattern MP4：停止。删除当前的 index.html 并重新从 master-skeleton 脚手架的 cp 开始。在正确的脚手架上重建场景内容比将品牌改造到错误的脚手架中更便宜。
1 · 解析 + 编辑裁剪
- 提取：周范围、头条统计（发布、提交）、主题、项目。
- 总时间预算：45-60 秒。 标题 ≤2 秒，结尾 ≤3.5 秒，4 个主题每个约 9-12 秒。
- 每个主题保留一个主要可视化和最多 3 个口头提及的项目。其他所有内容仅作为结尾的“完整摘要”指针存在。裁剪是工作：一个包含 30 个项目的更新日志仍然产生 ≤14 个口头节拍。
- 按故事顺序排列主题：主打功能 → 产品表面 → 性能 → 可靠性（摘要通常已经这样排列）。
2 · 可视化路由
对于每个主题，从 references/visualization-registry.md 中选择表面，并写一行：主题 → 表面 → 模拟执行的 2-4 个序列化动作，每个动作都与一个脚本短语绑定。如果没有注册表表面适用且没有忠实的类比，则它是一个检查表场景——不要为无法诚实表示的内容发明虚假的 UI。
3 · 双层脚本（口语 vs 显示）
按照 references/script-voice.md 将脚本写成令牌行：对话式语域，每个技术术语携带一个来自 references/lexicon.json 的 spoken 音标形式，而 display 保持标准拼写。字幕显示 display；VO 读取 spoken。任何不在词典中的术语：停止并向用户询问其发音，然后将其添加到词典中。
将其保存为项目中的 script-tokens.json。
4 · VO——Annie（HeyGen，固定）
# spoken-layer 文本仅；words JSON = SPOKEN 文本的地面真相时间戳
# Repo 原生路径：changelog-video 技能从 hyperframes 仓库根目录运行，
# 因此它使用跟踪的 hyperframes-media TTS 助手（无需 `npx hyperframes
# skills install` 步骤）。如果你将技能复制到另一个仓库，请切换到
# 你自己的 media-use / hyperframes-media heygen-tts.mjs 路径。
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie — lifelike（不要替换）
需要 heygen CLI ≥0.3.0 已认证（heygen auth login --oauth）。
然后将口语时间戳对齐回显示令牌：
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json 是字幕轨道的输入（显示拼写，口语时间）。
aligner 会打印 MISMATCH 警告——在构建之前解决每一个（通常是词典将 TTS 渲染成多个单词的拼写）。音频是时钟：所有节拍时间都来自 vo-words.json；重新生成 VO 会重新打开每个接缝。
单词时间戳是一个硬性关卡。 在继续步骤 5 之前，验证
vo-words.json 非空并且有一个包含每个单词 start/end 的 words: [...] 数组。如果它为空（0 字节）或缺少该数组——这是 TTS 提供程序返回音频但没有时间戳负载时的一个已知故障模式——不要在没有它们的情况下继续。回退：使用本地 whisper 对产生的音频执行强制对齐，针对显示脚本：
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# 然后使用 --words voiceover.json（相同形状）运行 align-captions.mjs
Whisper 可能会听错 TTS 渲染（"gee-sap" → "gsap"，"heyjen" → "hey Jen"，
等等）——字幕仍然使用来自 script-tokens.json 的 DISPLAY 拼写；
whisper 仅提供时间戳。align-captions.mjs 处理连接。
此回退是有字幕构建和无提示无字幕构建之间的区别。
5 · 构建
精确遵循 references/build-spec.md：品牌标记 + 字体（打包在
<SKILL_DIR>/assets/ 中）、动画背景编码、场景脚手架、
镀铬、字幕轨道、每个场景一个限量的绿色时刻。然后是运动教义
顺序：ledger.json（所有普通接缝 cut-the-curve LEFT）→ seam-stamp →
VO 单词上的内部节拍 → seam-gate 验证。
字幕不是可选的。 master-skeleton 附带一个读取 LINES 数组的字幕轨道 IIFE——将该数组留空是一个已发货的错误，而不是风格选择。在继续步骤 6 之前，从 captions.json 填充它：
// 粘贴替换字幕轨道 IIFE 中的 "const LINES = /* … */ []"：
const LINES = /* captions.json 的内容 */ [
{ id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
…
];
如果 align-captions.mjs 被跳过或 LINES 是 []，那么步骤 6 中的帧检查将失败——不要通过从脚手架中移除 #cap-line 来掩盖它。
6 · 关卡（在提交之前全部绿色）
bun run --cwd packages/cli hyperframes check（或从仓库本地的skills/hyperframes-cli/技能安装的hyperframesCLI）——0 个错误（对比度：暗淡文本 ≥ .66 alpha）。不要使用npx hyperframes@latest；跟踪的仓库本地 CLI 是此技能产生的合成合同的事实来源。seam-gate.mjs verify——0 个失败。- 重新启动预览服务器（它会缓存 bundle），通过原始合成页面上的
__player.seek抽查 3-4 个节拍。 - 除非用户要求，否则不要渲染。 在请求的渲染之后，从 MP4 验证帧（
ffmpeg -ss <t> … -frames:v 1）：字幕存在，背景视频不是黑色，没有微小/冻结的帧。 - 字幕存在性关卡——硬性失败。 在整个 VO 口语窗口内抽取 3-4 帧（例如 48 秒 VO 的
t=3、t=15、t=30、t=42），并确认位于top: 990的字幕轨道在每个帧上都渲染了可见文本。如果在口语区间内的任何帧缺少字幕，则构建将发货无字幕的版本——将其视为红色关卡并重新检查步骤 5 的LINES填充。这正是 Jul 13-20 v4 构建中出错的地方。
项目布局
projects/active/weekly-changelog-<range>/
├── index.html # 单文档主文件（场景作为幻灯片，带有盖章接缝）
├── ledger.json # 向量分类账（seam-stamp 输入）
├── script-tokens.json # 双层脚本（VO + 字幕的事实来源）
├── vo-spoken.txt # 生成：口语层，一行
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # 从 <SKILL_DIR>/assets/bgm.mp3 复制（主场原声），除非用户提供了
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
反模式
| 不要这样做 | 改为这样做 |
|---|---|
| UI 更改的子弹点幻灯片 | 模拟演绎更改的表面 |
| 不可表示项目的虚假 UI | 诚实的检查表场景 |
| TTS 文本中的纯 "JSON"/"CLI" | 词典口语形式；显示保持标准 |
| 字幕中的音标拼写 | 字幕始终渲染显示层 |
| 猜测未知术语的发音 | 询问，然后扩展词典 |
| 说出每个更新日志项目 | 每个主题 ≤3 个；摘要链接承载其余部分 |
| 到处使用绿色强调 | 每个场景一个绿色时刻 (#5ef17c) |
| 从之前视频的 index.html 开始 | 步骤 0——从此技能复制 examples/master-skeleton.html 到 project/index.html，始终如此 |
手写的 @font-face / WebGL 着色器 / 自定义 BGM | 步骤 0——逐字复制此技能的 assets/；技能的资产就是品牌 |
| 交付时没有 CloudFront 失效 | 在任何 S3 替换后，为分发 E2BSLVSZ7FG3U0 的精确路径运行 aws cloudfront create-invalidation——否则 CDN 会缓存旧文件 |
脚手架中的 LINES 数组为空时发货 | 步骤 4 必须生成填充好的 captions.json；步骤 5 必须将其粘贴到 IIFE 中；步骤 6 关卡 5 必须确认渲染帧上有字幕。空的 LINES = 无字幕发货 = 重新运行 |
没有 vo-words.json → 跳过字幕并无论如何发货 | 回退到对产生的音频进行 whisper 强制对齐；字幕不是可选的 |