更新日志 → 品牌视频
输入:一个更新日志 .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 重现 / UI 类比 / 终端 / 检查列表。
文本检查列表是最后的手段,仅用于真正无法可视化的项目(可靠性修复列表)。
管道
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(解析、路由、脚本、配音)计划放入脚手架的内容;步骤 5 填充已复制的 project/index.html 中的占位符(<RANGE>、<TOTAL>、<CUT_N>、<DUR_N>、场景体)——你不要重写脚手架的 chrome、字体、调色板或布局外壳。
如果你发现自己正在使用 cp 复制之前视频的 index.html,或者编写自己的 @font-face 声明,或者设计 WebGL 着色器背景而不是使用上面编码的 bg-pattern MP4:立即停止。删除当前的 index.html 并重新从主骨架脚手架的 cp 步骤开始。在正确的 scaffold 上重建场景内容比将品牌改造到错误的 scaffold 更便宜。
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;配音读取 spoken。任何不在词汇表中的术语:立即停止并向用户询问其发音,然后将其添加到词汇表中。将结果保存为项目中的 script-tokens.json。
4 · 配音——Annie(HeyGen,固定)
# 仅口语层文本;words JSON = 口语文本的真实时间戳
# 仓库本地路径:changelog-video 技能从 hyperframes 仓库根目录运行,
# 因此它使用跟踪的 hyperframes-media TTS 助手(无需 `npx hyperframes skills` 安装步骤)。
# 如果你已将技能复制到其他仓库,请换成你自己的 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 — 逼真(不要替换)
需要 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;重新生成配音会重新打开每个接缝。
单词时间是硬性门控。 在进入步骤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/ 中)、动画背景编码、场景脚手架、chrome、字幕轨道、每个场景一个限量的绿色瞬间。然后是教义顺序:ledger.json(所有普通接缝 cut-the-curve LEFT)→ seam-stamp → 配音单词上的内部节拍 → seam-gate 验证。
字幕是不可选的。 主骨架自带一个读取 LINES 数组的字幕轨道 IIFE——将该数组留空是已发货的 bug,不是风格选择。在进入步骤6之前,从 captions.json 填充它:
// 将 "const LINES = /* … */ []" 替换为字幕轨道 IIFE 中的内容:
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):字幕存在,背景视频不是黑色,没有微小/冻结的帧。 - 字幕存在门控——硬性失败。 在配音的口语窗口内采样 3-4 帧(例如对于 48 秒的配音,在
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-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 着色器 / 自定义背景音乐 | 步骤0——逐字复制该技能的 assets/;技能的资产就是品牌 |
| 交付时没有 CloudFront 失效处理 | 在任何 S3 替换后,对分发 E2BSLVSZ7FG3U0 运行 aws cloudfront create-invalidation 以获取精确路径——否则 CDN 会缓存旧文件 |
在脚手架中留有空的 LINES 数组发货 | 步骤4必须生成填充好的 captions.json;步骤5必须将其粘贴到 IIFE 中;步骤6门控5必须确认渲染帧上的字幕。空 LINES = 无字幕发货 = 重新执行运行 |
没有 vo-words.json → 跳过字幕并直接发货 | 回退到对生成的音频进行 whisper 强制对齐;字幕是不可选的 |