Changelog → 品牌影片
輸入：一份 changelog .md（主題 + 項目，例如每週 HyperFrames 摘要）。
輸出：一個 lint 乾淨、符合 seam-gate-green 標準的 HyperFrames 專案，放置在
projects/active/weekly-changelog-<range>/ 目錄下。僅在使用者要求時才進行渲染。
務必優先載入，不可妥協： motion-doctrine（+ cut-the-curve，
oversized-cursor（如果出現游標），seam-craft）以及 captions-overlay。
此技能提供 changelog 專用的管線；doctrine 則提供動畫法則。
首要原則：可視化，而非條列
每個主題都必須透過實際 UI 的動畫模擬，或能忠實呈現改變體驗的類比畫面來展現——絕對不使用文字條列。
在撰寫腳本之前，必須先將每個主題/項目路由至 references/visualization-registry.md；
該註冊表會決定使用 ui-recreate / ui-analog / terminal / checklist 哪一種方式。
文字檢查清單是最後的手段，僅保留給真正無法視覺化的項目（如可靠性修復列表）。
管線
0 · 從此技能的資產啟動專案——不可妥協
在撰寫任何 composition HTML 之前，務必先執行此步驟。跳過此步驟總是會產出一支看起來像你之前做過的類似專案的影片，而非此技能的品牌——這是此技能偏離品牌最常見的原因。 技能的資產、字型和 scaffold 本身就是技能；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 字幕軌道），這些都會被每個場景從 scaffold 繼承。
只有然後才開始執行下面的步驟 1-6。步驟 1-4（解析、路由、腳本、語音配音）規劃要放入 scaffold 的內容；步驟 5 在已複製的 project/index.html 中填入佔位符（<RANGE>，<TOTAL>，<CUT_N>，<DUR_N>，場景主體）——你不需要改寫 scaffold 的 chrome、字型、調色板或佈局外殼。
如果你發現自己正準備對先前影片的 index.html 執行 cp，或是自行撰寫 @font-face 宣告，或是設計 WebGL shader 背景而非使用上面編碼的 bg-pattern MP4：立即停止。刪除目前的 index.html，並從 cp master-skeleton scaffold 重新開始。在正確的 scaffold 上重建場景內容，遠比將品牌改造到錯誤的 scaffold 上更省成本。
1 · 解析 + 編輯剪裁
- 提取：週次範圍、標題統計資料（發行數量、提交次數）、主題、項目。
- 總預算：45-60 秒。 標題 ≤2 秒，結尾 ≤3.5 秒，4 個主題 ≈ 每個 9-12 秒。
- 每個主題保留一個主要可視化內容 + 最多 3 個口述項目。其他所有內容僅作為結尾「完整摘要」的指標存在。剪裁是關鍵工作：一個包含 30 個項目的 changelog 仍然只能產生 ≤14 個口述節拍。
- 按故事性排列主題：主打功能 → 產品表面 → 效能 → 可靠性（摘要通常已經是這種順序）。
2 · 可視化路由
對於每個主題，從 references/visualization-registry.md 中選取呈現表面，並撰寫一行：theme → surface → 模擬所執行的 2-4 個序列動作，每個動作都與腳本中的一句話相關聯。如果沒有任何註冊表的表面適合，且不存在忠實的類比，則將其設為檢查清單場景——不要為我們無法誠實呈現的內容憑空發明假 UI。
3 · 雙層腳本（口語 vs 顯示）
根據 references/script-voice.md 將腳本撰寫為標記行：
對話式語調，每個技術術語都要攜帶來自 references/lexicon.json 的 spoken 語音形式，而 display 則保持標準拼寫。
字幕顯示 display；語音配音朗讀 spoken。任何不在詞彙庫中的術語：立即停止並詢問使用者該術語的發音，然後將其添加到詞彙庫中。
將結果儲存為專案中的 script-tokens.json。
4 · 語音配音——Annie（HeyGen，固定）
# only spoken-layer text; 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/ 中）、動畫背景編碼、場景 scaffold、chrome、字幕軌道、每個場景一個限量的綠色時刻。然後是 doctrine 順序：ledger.json（所有普通接縫 cut-the-curve LEFT）→ seam-stamp → 基於語音配音單詞的內部節拍 → 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 中的畫面檢查將會失敗——不要透過從 scaffold 中移除 #cap-line 來掩蓋它。
6 · 閘門（在呈現之前全部必須為綠燈）
bun run --cwd packages/cli hyperframes check（或 repo 本地端skills/hyperframes-cli/技能中安裝的hyperframesCLI）——0 個錯誤（對比度：暗色文字 ≥ .66 alpha）。請不要使用npx hyperframes@latest；追蹤的 repo 本地端 CLI 是此技能所產生的 composition 合約的真相來源。seam-gate.mjs verify——0 個失敗。- 重新啟動預覽伺服器（它會快取 bundle），透過原始 comp 頁面上的
__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 # 單文件 master（場景作為幻燈片，已蓋章接縫）
├── 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" | 使用詞彙庫中的口語形式；顯示層保持標準拼寫 |
| 在字幕中使用語音拼寫 | 字幕始終呈現顯示層 |
| 猜測未知術語的發音 | 詢問使用者，然後擴充詞彙庫 |
| 口述每個 changelog 項目 | 每個主題最多 3 個；摘要連結承載其餘內容 |
| 到處使用綠色強調 | 每個場景一個綠色時刻（#5ef17c） |
| 從先前影片的 index.html 開始 | 步驟 0——始終從此技能複製 examples/master-skeleton.html 到 project/index.html |
手動製作 @font-face / WebGL shader / 自訂 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 強制對齊；字幕是非選擇性的 |