changelog-video

更新日志 → 品牌视频

输入：一份更新日志 .md（主题 + 条目，类似每周 HyperFrames 摘要）。 输出：一个通过 lint 检查且 seam gate 通过的 HyperFrames 项目，位于 projects/active/weekly-changelog-<range>/。仅在收到要求时渲染。

首先加载，不容妥协： motion-doctrine（以及 cut-the-curve、 oversized-cursor（如出现光标）、seam-craft）和 captions-overlay。 此技能提供更新日志专用流水线；doctrine 提供运动规则。

首要原则：可视化，而不是罗列

每个主题都要通过实际 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>、场景主体）——不要重写脚手架的界面装饰、字体、配色或布局外壳。

如果你发现自己正要对先前视频的 index.html 使用 cp，或编写自己的 @font-face 声明，或设计 WebGL 着色器背景来取代上文编码好的 bg-pattern MP4：立即停止。删除当前的 index.html，从复制 master-skeleton 脚手架重新开始。在正确的脚手架上重建场景内容，比把品牌风格改装到错误的脚手架上省事。

1 · 解析 + 编辑取舍

• 提取：周次范围、核心数据（发布、提交）、主题、条目。
• 总时长：45-60 秒。 标题 ≤2 秒，片尾 ≤3.5 秒，4 个主题各约 9-12 秒。
• 每个主题保留一个主视觉演示 + 最多 3 个口播条目。其余内容只在片尾以“完整摘要”指引的形式出现。取舍是关键：即使更新日志有 30 个条目，口播节拍也不得超过 14 个。
• 按故事脉络排列主题：旗舰功能 → 产品界面 → 性能 → 可靠性（摘要通常已按此顺序编排）。

2 · 可视化路由

针对每个主题，从 references/visualization-registry.md 中选择呈现界面，并写一行：theme → surface → 模拟所执行的 2-4 个连续操作，每个操作都对应脚本中的一句话。如果注册表中没有适用界面，也不存在忠实的类比，就使用清单场景——不要为无法如实呈现的内容编造假 UI。

3 · 双层脚本（口播与显示）

按 references/script-voice.md 将脚本写成令牌行：采用对话式语气；每个技术术语都要带有 references/lexicon.json 中的 spoken 音标形式，而 display 保留标准拼写。字幕显示 display；VO 朗读 spoken。任何不在词典中的术语：立即停止并询问用户其发音，然后将其添加到词典。保存为项目中的 script-tokens.json。

4 · VO — Annie（HeyGen，已固定）

# spoken-layer text only; words JSON = ground-truth timestamps of the SPOKEN text
# Repo-native path: the changelog-video skill runs from the hyperframes repo root,
# so it uses the tracked hyperframes-media TTS helper directly (no `npx hyperframes
# skills` install step). If you've copied the skill into another repo, swap in
# your own path to the 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 (do not substitute)

需要已完成身份验证的 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 是字幕轨的输入（显示拼写、口播时间）。 对齐器会打印 MISMATCH 警告——构建前必须逐一解决 （通常是词库中的拼写被 TTS 渲染成了多个词）。音频就是时钟：所有节拍时间都来自 vo-words.json；重新生成 VO 会重新打开 每一道接缝。

词语时间戳是硬性门槛。 进入第 5 步前，请确认 vo-words.json 非空，且包含 words: [...] 数组，其中每个词都有 start/end。 若文件为空（0 字节）或缺少该数组——当 TTS 提供商返回了音频，却未提供时间戳载荷时，这是已知的故障模式——切勿在没有时间戳的情况下继续。备用方案：使用本地 whisper 对生成的音频和显示脚本进行强制对齐：

uvx --from openai-whisper whisper voiceover.mp3 \
  --model base.en --language en --word_timestamps True \
  --output_format json --output_dir .
# then run align-captions.mjs with --words voiceover.json (same shape)

Whisper 可能会误听 TTS 渲染的内容（“gee-sap” → “gsap”，“heyjen” → “hey Jen”， 等等）——字幕仍使用 script-tokens.json 中的显示拼写；whisper 只提供时间戳。align-captions.mjs 负责合并。 这个备用方案决定了构建结果是带字幕，还是悄无声息地没有字幕。

5 · 构建

严格遵循 references/build-spec.md：品牌标记 + 字体（打包在 <SKILL_DIR>/assets/ 中）、动态背景编码、场景框架、 界面元素、字幕轨、每个场景一次酌情安排的绿色时刻。然后按原则规定的顺序执行：ledger.json（所有普通接缝均向左切断曲线）→ seam-stamp → VO 词语上的内部节拍 → seam-gate 验证。

字幕不可省略。 master-skeleton 自带读取 LINES 数组的字幕轨 IIFE——留空该数组属于发布缺陷，而非风格选择。进入第 6 步前，请从 captions.json 填充该数组：

// paste in place of "const LINES = /* … */ []" in the caption-rail IIFE:
const LINES = /* contents of captions.json */ [
  { id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
  …
];

如果跳过了 align-captions.mjs 或 LINES 为 []，第 6 步中的帧检查就会失败——切勿通过从框架中删除 #cap-line 来掩盖问题。

6 · 门槛（全部通过后才能交付）

1. node packages/cli/bin/hyperframes.mjs check --caption-zone "x0=0;y0=.90;x1=1;y1=1;severity=error;seek=.02,.06,.10,.14,.18,.22,.26,.30,.34,.38,.42,.46,.50,.54,.58,.62,.66,.70,.74,.78,.82,.86,.90,.94,.98"（或使用仓库本地 skills/hyperframes-cli/ 技能中已安装的 hyperframes CLI）——错误数为 0（对比度：暗色文本 ≥ .66 alpha；场景内容保持在字幕轨上方）。不要使用 npx hyperframes@latest；受跟踪的仓库本地 CLI 才是本技能所生成内容所遵循的构图规范的权威来源。
2. seam-gate.mjs verify——失败数为 0。
3. 重启预览服务（它会缓存包），在原始合成页面上通过 __player.seek 抽查 3-4 个节拍。
4. 除非用户要求，否则不要渲染。用户要求渲染后，请检查 MP4 中的帧（ffmpeg -ss <t> … -frames:v 1）：字幕存在、背景视频不是黑屏，且没有过小或冻结的帧。
5. 字幕显示门槛——硬性失败条件。 在 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            # single-doc master (scenes as slides, stamped seams)
├── ledger.json           # vector ledger (seam-stamp input)
├── script-tokens.json    # two-layer script (source of truth for VO + captions)
├── vo-spoken.txt         # generated: spoken layer, one line
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3               # copy from <SKILL_DIR>/assets/bgm.mp3 (the house track) unless the user supplies one
└── 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 会缓存旧文件
scaffold 中的 LINES 数组为空时就发布	步骤 4 必须生成已填充的 captions.json；步骤 5 必须将其粘贴到 IIFE 中；步骤 6 的关卡 5 必须确认渲染帧中有字幕。LINES 为空 = 发布内容无字幕 = 重新执行流程
没有 vo-words.json 就跳过字幕并照常发布	对生成的音频使用 whisper 强制对齐作为备用方案；字幕不可省略