VanillaSky — 從設定檔產出社交影片

影片是一個 VideoConfig JSON：一個有序的場景列表，每個場景透過駝峰式 ID 引用一個精選範本。編排並檢查設定檔，然後將它交給使用者在 VanillaSky Studio 中使用。使用者在那裡預覽、編輯並匯出 MP4；請勿將完整的 MP4 渲染納入初始流程。

三個不可妥協的原則

讀取目錄；從不猜測。 解析 CLI 後，執行 vanillasky templates 取得捆綁的範本地圖，以及 vanillasky templates <id> --json 取得精確的架構。線上備用方案為 https://vanillasky.ai/llms-components.txt；儲存庫和獨立安裝版本會攜帶 registry/llms-components.txt 加上 registry/r/<name>.json。如果無法取得確切的目錄，請停止，不要虛構 ID 或變數。
從不虛構證據。 姓名、引言、數字、統計數據、螢幕截圖和產品聲明必須來自簡報或提供的資產。如果一個範本需要使用者未提供的證據，請選擇另一個範本。
從不交付未經檢查的設定檔。 驗證可以檢查結構；只有查看渲染的幀才能發現溢出、構圖不佳和意外的預設值。

開始工作階段

首先解析 CLI。官方的 VanillaSky CLI 未以 npm 套件形式發布。請勿搜尋 npm、執行 npm install vanillasky 或使用僅擁有該名稱的套件。如果 command -v vanillasky 失敗，請從此 SKILL.md 的路徑解析此技能的安裝目錄，然後執行其官方引導程式：

node <已安裝技能目錄>/scripts/install-cli.mjs

引導程式只會將 https://github.com/VanillaSkyAi/skills.git 克隆到 ~/.vanillasky/release，安裝該簽出版本所宣告的依賴項，並將其本地 CLI 暴露在 PATH 上。如果簽出來源不同或腳本失敗，請停止；不要替換為註冊表套件。

然後在製作第一個影片之前執行以下指令：

vanillasky update --check
vanillasky setup --check
vanillasky templates

update --check 會報告是否有較新的版本，但不會進行任何更改。如果此處記錄的某個旗標缺失，請執行 vanillasky update。setup --check 會報告預設方向、瀏覽器、Pexels 金鑰、音樂情緒和 DESIGN.md 的狀態。

缺少 Pexels 金鑰不是障礙：提及一次，素材搜尋需要從 pexels.com/api 取得的免費金鑰，然後使用提供的素材或不依賴素材庫的範本。缺少 DESIGN.md 代表沒有自動品牌設定；不要因此阻塞。

推導簡報

優先使用提示、儲存庫、DESIGN.md、URL 和提供的資產。最多問三個問題，且僅針對真正的缺口：

目標和格式 — 觀看者應該做什麼或感受什麼：發布、評論、里程碑還是更新？
受眾和證據 — 這是為誰製作的，以及哪個真實的數字、引言、螢幕截圖或產品細節能證明這個主張？
資產 — 必須出現哪些螢幕截圖、標誌、剪輯或 URL？

從目標平台推導方向：TikTok/Reels/Shorts → 直式；YouTube 影片或明確為寬版的 X/LinkedIn 貼文 → 橫式。否則使用配置的預設值，或花三個問題中的一個來決定。

將結果儲存為 video-brief.md，放在 video.json 旁邊。在後續的回合中重新閱讀並更新它，而不是再次問同樣的問題。

預設工作流程：在 Studio 中交付

編寫 video.json，根據簡報和捆綁的目錄。在編寫短清單中範本的變數之前，先使用 vanillasky templates <id> --json 檢查它們的精確架構。
解析素材媒體，當設定檔包含 mediaKeyword 時：
```
vanillasky resolve video.json
```
這會選擇一個 Pexels 結果，並將確切的 mediaUrl 寫入設定檔，使驗證和重新渲染具有確定性。如果沒有可用的 Pexels 金鑰，請改用提供的素材、直接 URL 或 mediaType: "gradient"。請勿依賴渲染時的搜尋，因為它會影響交付狀態。
驗證並修復每個錯誤和警告：
```
vanillasky validate video.json
```
設定檔的 format 會選擇正確的插槽合約；請勿為每個影片硬編碼 --format launch。將警告視為需要解決的工作，而不是裝飾品，並且永遠不要在仍有警告的情況下說驗證通過。
檢查聯絡表：
```
vanillasky render video.json --sheet --out ./sheet
```
在需要時開啟 sheet/sheet.png 並檢查各個幀。檢查文字溢出、難以閱讀的字體、未設定/看似預設的值、未使用的資產、視覺重複，以及關鍵內容是否位於幀的中央 75% 區域之外。在進行任何視覺編輯後，重複執行解析（如有需要）、驗證和聯絡表。
在 Studio 中交付：
```
vanillasky studio video.json
```
Studio 會即時追蹤檔案。在使用者審查時繼續編輯設定檔；他們未儲存的編輯會顯示為衝突，而不會被覆寫。使用者滿意後，從 Studio 匯出 MP4。

如果開啟了錯誤的瀏覽器，請傳入 --browser "Google Chrome" 或將瀏覽器持久化儲存在 ~/.vanillasky/config.json 中。在遠端 Shell 中使用 --no-open。

預設不要渲染完整的 MP4。 僅在使用者明確要求檔案或無法使用 Studio（CI/無頭模式）時才自行渲染：

vanillasky render video.json --open

對於該分支，觀看結果並閱讀完成橫幅：確認總長度、音訊覆蓋範圍、方向和影片流暢度。包含完成區塊的 Watch 和 Studio 連結。vanillasky link video.json 會重新列印它們，而無需渲染。

編寫預設路徑

從這個形狀開始，然後使用目錄中的確切架構：

{
  "format": "launch",
  "orientation": "portrait",
  "style": {
    "font": "Inter",
    "preset": "bold",
    "brandKit": { "accent": "#6D5EF8", "secondary": "#F8B45E" }
  },
  "audio": { "trackId": "<from vanillasky tracks>" },
  "scenes": [
    {
      "id": "s0",
      "templateId": "media",
      "variables": { "texts": "Ship it today", "mediaType": "gradient" },
      "timing": { "fixedDuration": 3 }
    }
  ]
}

brandKit 屬於 style 內部；有目的地選擇一個樣式預設集。
textArchetype 和 backgroundEffect 是場景欄位，而不是變數。
timing.fixedDuration 設定獨立場景的長度。明確的時間軸使用連續的 startTime + endTime；timing.duration 不是一個欄位。
使用 vanillasky tracks 根據情緒和能量選擇音樂。靜音是有效的，但通常對社交影片來說效果較弱。
優先使用真實的 HTTPS URL 或本地路徑來處理媒體。Base64 媒體會使分享連結過大，且 mediaKeyword 的結果必須固定為 mediaUrl 以獲得確定性的重新渲染。

當設定檔需要品牌設定、媒體解析、明確時間線、FPS 匹配或連結行為時，請閱讀 references/config.md。

根據故事選擇格式

格式	故事結構	典型長度
`launch`	框架 → 理解 → 證據	3–8 個場景，通常 5 個
`review`	引言 → 歸因 → 結果	4–7 個場景，通常 5 個
`milestone`	數字 → 背景 → 感謝	3–6 個場景，通常 4 個
`update`	變更 → 示範 → 好處	4–7 個場景，通常 5 個

驗證器會強制執行場景數量、禁止的鉤子、結尾位置和相鄰規則。references/formats.md 包含生成的合約。你的工作是驗證器無法做出的判斷。

創作品質門檻

真實性與資產

將每個範本預設值替換為特定於簡報的內容。永遠不要提供諸如 10K、99.9% 或 <50ms 等預留位置統計資料。
使用所有重要的已提供螢幕截圖。真實的產品畫面勝過顯示相同內容的合成終端機、編輯器、手機或瀏覽器。
將直式螢幕截圖匹配到手機模型，橫式螢幕截圖匹配到瀏覽器模型。

故事

鉤子創造張力或好奇心；它不該消耗報酬。
至少包含一個說明性主體，提及具體的產品、受眾或結果。通知、通話、推文和數字可以構成框架或證明，但無法單獨解釋產品。
結尾是一個地址——品牌、URL 或行動——而不是重複證據。

多樣性與節奏

不要讓每個主體都是一張卡片。至少使用兩種非卡片主導的寄存器。
一個平鋪漸層上的簡單句子是備用方案，不自動等於一個強鉤子。優先選擇基於簡報的視覺機制——用於警報的通知、用於開發者工作流程的終端機/編輯器、用於對話的聊天、用於提供的產品畫面的裝置或瀏覽器。即使是一個有意義的極簡影片也需要一個具體的視覺想法；極簡意味著更少的元素，而不是在每個場景中使用相同的漸層和排版。
統一的調色盤不等於場景多樣性。即使類型版面不同，共享相同平鋪背景的三個或更多場景行也無法通過此門檻。使用一個接地資產、素材背景、範本或有節制的效果來改變至少一個寄存器。當簡報包含太少經批准的文案或證據來支援許多不同的場景時，使用該格式最短的有效故事，而不是重複它。
給素材至少 3 秒鐘，除非它是有意為之的短橋接。變化背景運動，而不是將一個效果套用到所有地方。
僅使用漸層的媒體場景應該是一個有意的品牌節拍，而不是因為素材或提供的媒體不方便而選擇的備用方案。
檢查實際出現的內容：時長有限的範本可能會省略後面的項目，即使設定檔中包含它們。

文案

鉤子：最多 7 個單字。CTA：最多 4 個單字，最好是命令式。
在至少一個場景中完整保留每個使用者批准的口號或引言。不要將一個批准的行變成幾個偽不同的場景，分別顯示其片段；讓視覺進程來承載其他節拍。
避免列出三個通用名詞、類別或動詞。節奏需要張力、進程或轉折——而不是三個同義詞。
將必須保持在一起的文字放在 nowrap 範圍內；永遠不要依賴 NBSP 進行 SVG 匯出。

僅在範本失敗時升級

使用表達簡報的最低層級：

使用目的編寫的文案的範本。
調整過變數的範本。
基於註冊表項目的彈出/自訂場景。
由沙盒場景元素組成的自訂場景。

預設路徑停在第 2 層。在使用第 3 或第 4 層之前，請閱讀 references/custom-scenes.md、references/libraries.md、references/motion.md 和 references/visual-rules.md。使用 vanillasky scope 和生成的 references/motion-api.md，而不是虛構 API。

參考路由

references/config.md — 時間、樣式、品牌、媒體、音訊、FPS、DESIGN.md 和分享連結行為。
references/formats.md — 生成的插槽合約和範本類別。
references/custom-scenes.md — 彈出、來源、沙盒合約和驗證規則。
references/libraries.md — 生成的五個庫地圖、受眾指南、依賴項、安裝目標和確切的匯出組。
references/motion.md — 編舞、閱讀時間、焦點層次和剪輯連續性。
references/motion-api.md — 為自訂場景生成的可用函數、彈簧和緩動名稱。
references/visual-rules.md — 自訂場景的排版、方向版面、顏色、光和構圖。

VanillaSky — 社交影片製作