變更日誌 → 品牌化影片
輸入:變更日誌 .md(主題 + 項目,例如每週 HyperFrames 摘要)。
輸出:一個經過 lint 清理、通過 seam-gate-green 的 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 重建) / ui-analog(UI 類比) / 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(解析、路由、腳本、語音)規劃要放入架構的內容;步驟 5 在已複製的 project/index.html 中填入佔位符(<RANGE>、<TOTAL>、<CUT_N>、<DUR_N>、場景主體)——你不能重寫已複製架構的框架、字型、調色板或佈局外殼。
如果你發現自己正在執行 cp 複製之前影片的 index.html,或者編寫你自己的 @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 → the 2-4 sequenced actions the mock performs, each tied to a script phrase。如果沒有適合的註冊表表面且沒有忠實的類比物,則使用檢查清單場景——不要為我們無法誠實表示的內容發明虛假的 UI。
3 · 雙層腳本(口語 vs 顯示)
按照 references/script-voice.md 將腳本寫為標記行:會話風格,每個技術術語從 references/lexicon.json 中攜帶一個 spoken 語音形式,而 display 保持標準拼寫。字幕顯示 display;語音朗讀 spoken。任何不在詞彙表中的術語:停止並詢問使用者該術語的發音,然後將其添加到詞彙表中。將腳本儲存為專案中的 script-tokens.json。
4 · 語音——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;重新生成語音會重新打開每個接縫。
逐字時間戳記是一個硬性關卡。 在進入步驟 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 .
# then run align-captions.mjs with --words voiceover.json (same shape)
Whisper 可能會誤解 TTS 的渲染(例如 "gee-sap" → "gsap","heyjen" → "hey Jen" 等)——字幕仍然使用 script-tokens.json 中的 DISPLAY(顯示)拼寫;Whisper 僅提供時間戳記。align-captions.mjs 處理連接。這個回退方案是有字幕建置和無聲無字幕建置之間的區別。
5 · 建置
嚴格遵循 references/build-spec.md:品牌標記 + 字型(打包在 <SKILL_DIR>/assets/ 中)、動畫背景編碼、場景架構、框架、字幕軌道、每個場景一個限量的綠色亮點。然後遵循 doctrine 順序:ledger.json(所有普通接縫 cut-the-curve LEFT)→ 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 · 關卡(全部為綠色後方可提交)
bun run --cwd packages/cli hyperframes check(或從 repo 本地skills/hyperframes-cli/技能安裝的hyperframesCLI)——0 個錯誤(對比度:暗色文字 ≥ .66 alpha)。不要使用npx hyperframes@latest;追蹤到的 repo 本地 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-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 強制對齊;字幕是非可選的 |