變更日誌 → 品牌影片
輸入：一份 changelog .md 檔案（主題 + 項目，例如每週 HyperFrames 摘要）。
輸出：一個經 lint 檢查、通過 seam-gate-green 的 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（解析、路由、腳本、配音）規劃要放入框架的內容；步驟 5 則是在已複製的 project/index.html 內部填充佔位符（<RANGE>、<TOTAL>、<CUT_N>、<DUR_N>、場景主體）——您不得重寫框架的鍍鉻元素、字型、調色板或佈局外殼。
如果您發現自己正打算對先前影片的 index.html 執行 cp，或自行撰寫 @font-face 宣告，或設計 WebGL 著色器背景而不是使用上述編碼後的 bg-pattern MP4：請停止。刪除當前的 index.html，並從主框架樣板的 cp 步驟重新開始。在正確的框架上重建場景內容，遠比將品牌改造到錯誤的框架上來得省事。
1 · 解析 + 編輯剪裁
- 提取：週範圍、重點統計資料（發行次數、提交次數）、主題、項目。
- 預算：總計 45-60 秒。 標題 ≤2 秒，片尾 ≤3.5 秒，4 個主題各約 9-12 秒。
- 每個主題保留一個核心視覺化 + 最多 3 個口語項目。所有其他項目 僅作為片尾中「完整摘要」的指標存在。剪裁是關鍵任務： 一份包含 30 個項目的變更日誌，最終仍應產生 ≤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, 已固定)
# 僅限口語層文字；words JSON = 口語文字的 ground-truth 時間戳記
# 回購原生路徑：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/ 中）、動畫背景編碼、場景框架、
鍍鉻元素、字幕軌道、每個場景一個限量綠色時刻。然後按照箴言順序：ledger.json（所有一般接縫 cut-the-curve LEFT）→ seam-stamp →
依配音單詞的內部節拍 → seam-gate 驗證。
字幕為非選擇性項目。 主框架內建一個讀取 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 · 關卡（全部綠燈後才能呈現）
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"（或已安裝的hyperframesCLI，來自回購本機的skills/hyperframes-cli/技能）— 0 個錯誤（對比：暗淡文字 ≥ .66 透明度；場景內容保持在字幕軌道之上）。請勿使用npx hyperframes@latest；追蹤的回購本機 CLI 是此技能產生的構圖合約的 事實來源。seam-gate.mjs verify— 0 個失敗。- 重新啟動預覽伺服器（它會快取套件），透過
__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 著色器 / 自訂 BGM | 步驟 0 — 逐字複製此技能的 assets/；此技能的資產即為品牌 |
| 未執行 CloudFront 失效就交付 | 在任何 S3 替換後，針對發行版 E2BSLVSZ7FG3U0 的準確路徑執行 aws cloudfront create-invalidation — CDN 否則會快取舊檔案 |
框架中的 LINES 陣列為空卻發布 | 步驟 4 必須產生已填入資料的 captions.json；步驟 5 必須將其貼入 IIFE；步驟 6 關卡 5 必須確認渲染的影格上有字幕。空的 LINES = 無字幕發布 = 重新執行 |
沒有 vo-words.json → 跳過字幕仍發布 | 回退到使用 whisper 對產生的音訊進行強制對齊；字幕為非選擇性 |