Communitygithub.com

leocosta/octopus

將正在運行的應用程式轉變為高傳真、動態宣傳影片,透過驅動真實產品(無頭 Chrome)來操作示範/沙箱環境,捕捉乾淨的螢幕畫面,並使用 HyperFrames + GSAP 合成動態設計剪輯(動態文字排版、電影推近鏡頭、聚光燈高亮、手機框、配樂)。不限定特定應用程式:可讀取每個專案的 promo.config 和 beats 清單;自動提取目標應用程式的設計系統,使覆蓋層符合其品牌。輸出 16:9 主版本與 9:16 直立版本。

octopus 是什麼?

此技能(Motion Promo Protocol)能夠自動化地為真實產品產生高品質的動態宣傳影片。它並非進行螢幕錄製,而是透過操作無頭瀏覽器中的實際應用程式(針對示範/沙箱環境),逐一捕捉每個畫面的靜態截圖,再使用 HyperFrames 和 GSAP 進行運動設計合成,加入動態文字、推近鏡頭、聚光燈效果、手機框架和背景音樂。 此技能支援任何網頁應用程式,並透過讀取 `promo.config.mjs` 和 `beats.json` 來定義專案設定與鏡頭清單。其核心優勢在於其「品牌無關」的設計系統提取功能,能自動從目標應用程式中擷取設計權杖(如背景色、強調色、字型),確保生成的影片風格與品牌一致,無需手動調整。 此技能適用於需要為產品發布、登陸頁面或功能公告製作高傳真宣傳影片的場景,但它要求應用程式必須有可運行的示範環境,且不適用於內部簡單的操作說明影片。它能夠產出 16:9 的橫向主影片和 9:16 的直立版本,滿足不同平台的發布需求。

相容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/leocosta/octopus/tree/HEAD/skills/motion-promo

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

動態宣傳影片協定

概述

此技能渲染一個 動態、廣告等級的真實產品宣傳影片,而非螢幕錄製或模擬畫面。它驅動實際應用程式在無頭瀏覽器中操作示範環境,捕捉每個畫面的乾淨靜態截圖,並在其上合成運動設計剪輯:動態文字排版、電影推近鏡頭、追蹤縮放的聚光燈高亮、手機螢幕框、節奏性場景切換以及背景音樂。輸出為 16:9 主版本和 9:16 直立版本。

它是 launch-feature 的渲染端對應:launch-feature 撰寫 video-script.md(以散文形式呈現的腳本/節拍);motion-promo 則將節拍清單轉化為完成且配樂的影片。兩者同時運行時,可串聯使用 — launch-feature 腳本 → motion-promo 節拍。

為何選擇 HyperFrames(HTML→MP4)而非螢幕錄製: 確定性、可重複執行、品牌可控,且避免了捕捉即時導航的失敗模式(請參閱規則)。應用程式僅用於產生 靜態截圖 + 設計權杖;所有動畫皆經過精心編排。

使用時機

  • 登陸頁面/銷售頁面需要產品示範或主視覺影片。
  • 發布新功能,且您需要渲染完成的影片,而不只是腳本。
  • 您擁有包含真實資料的示範/沙箱租戶。

請勿用於:內部操作說明(原始螢幕錄製成本更低),或沒有可運行示範環境的應用程式。

前置條件與秘密

不需要 API 金鑰 / 秘密。 HyperFrames render 是無金鑰的(本地 HTML→MP4),字型(Google Fonts)和預設音樂(incompetech)皆為公開 URL。唯一的憑證是 目標應用程式的示範登入資訊,它位於目標儲存庫的 promo.config.mjs 中 — 絕不儲存在此技能中。驗證是一個可插拔的配方:authInject() 返回要注入的值(token 到 localStorage、cookie、API 金鑰、多步驟租戶選擇),或 authFlow(page) 驅動互動式登入 UI(Azure AD / Entra、Okta、Google SSO),引擎會快照該會話(localStorage + sessionStorage + cookies,包含 HttpOnly)。SSO 憑證來自環境變數,而非檔案。無頭瀏覽器無法通過互動式 MFA — 請使用免 MFA 的示範帳戶(條件存取例外)或應用程式密碼。

系統依賴項(您需自行安裝 — 技能無法安裝): Node 20+、系統 Chrome(google-chrome/Chromium)、ffmpeg + ffprobe。需要網路出口以獲取字型/音樂。

自動/按需依賴項: hyperframes 透過 npx 按需獲取(無需預先安裝)。puppeteer-core 是透過 scaffold 建立的 npm 依賴項 — 它使用系統 Chrome,且不會下載 Chromium。

設定: 將 templates/ scaffold 到 video/<slug>/(包含 hyperframes.json;meta.json 由 compose-gen 產生),將 gitignore 重新命名為 .gitignore,然後執行 npm install 和 npm run preflight(驗證 Chrome、ffmpeg/ffprobe 和 puppeteer-core;若缺少任一項則會大聲失敗)。逐步執行管線,或執行 npm run build。

  • 目標應用程式的可運行示範/沙箱。

輸入

所有專案特定的內容都位於目標儲存庫中,絕不在這個技能中:

  1. promo.config.mjs — 合約(請參閱 templates/promo.config.example.mjs)。 應用程式 URL / 如何提供服務、驗證配方、示範帳戶/租戶、輸出路徑和音樂偏好。設計權杖會自動提取(步驟 2),但可在這裡覆寫。
  2. beats.json — 有序的鏡頭清單(請參閱 templates/beats.schema.json)。 每個節拍 = 一個畫面(路由或捕獲的靜態截圖)+ 可選的高亮目標 + 說明文案 + 視口(桌面/行動裝置)。

從 templates/ 將兩者 scaffold 到目標儲存庫中的 video/<slug>/。

協定

在目標儲存庫中的 video/<slug>/ 目錄內工作。每個步驟都有其驗證。

0. 修復示範資料(請先執行此步驟 — 這決定了影片的成敗)

示範/沙箱資料通常對於當前週期而言是過時的或歸零的(未支付的當月發票、空的漏斗),這在 「自動駕駛」 旁邊會顯示為 「R$0 營收」 — 與訊息背道而馳。在捕獲之前,撰寫一個冪等、基於當前日期的種子,為每個節拍提供健康的數字(請參閱規則 → 示範資料歸零)。透過查詢每個節拍將顯示的指標來驗證。

1. 在允許 CORS 的來源上,針對示範 API 提供應用程式服務

建置/提供對應於示範 API 的應用程式服務。提供服務的來源必須在 API 的 CORS 允許清單中,否則每個資料請求都會被阻擋,畫面會渲染成空白(請參閱規則 → CORS 來源)。探查 API 的允許清單,並在允許的埠上提供服務。驗證:從該來源對深層路由發出請求應返回 200,且已驗證的 /api/... 請求應返回 2xx。

2. 提取目標應用程式的設計系統

針對正在提供服務且已驗證的應用程式執行 templates/engine/extract-design.mjs。它會取樣計算後的樣式(頁面背景、按鈕/連結的主要/強調色、標題+等寬字型、圓角半徑)→ design.tokens.json。這些權杖會以 CSS 變數的形式餵入合成,使動態覆蓋層、強調色和字型自動符合應用程式的品牌。請檢閱並在 promo.config 中覆寫取樣錯誤的權杖。

3. 為每個節拍捕獲乾淨的靜態截圖

執行 templates/engine/capture.mjs。它會進行驗證(透過設定的 authInject 配方),導航每個節拍的路由至其視口,等待真實資料載入(不僅是 network-idle — 請參閱規則),然後截圖至 assets/<beat>.png。驗證每個靜態截圖都顯示了已載入的內容(大小 > ~10 KB,抽查目標元素是否存在)。

4. 定義節拍 + 產生合成

填寫 beats.json(路由/靜態截圖、高亮 {x,y,w,h,label} 於靜態截圖像素空間中 — 或是 {selector,label,padding?},由 capture.mjs 自動測量,並優於手動調整的座標、說明 {kicker,headline,sub}、視口、持續時間)。執行 templates/engine/compose-gen.mjs → index.html 來自 templates/composition.html,注入權杖和節拍。保持簡潔有力:每個節拍 3–5 秒、硬切、每個節拍一個想法。

5. 獲取免費音樂曲目

執行 templates/engine/fetch-music.mjs → assets/music.mp3。預設來源是 CC-BY(incompetech);CC-BY 需要署名(記錄在 LP 描述中)。如有可用的專案提供/CC0 曲目,則優先使用。

6. 渲染

npx hyperframes render → 無聲 MP4。先執行 hyperframes lint/inspect;將畫布外的裝飾/退出動畫溢出視為干擾,真正的文字裁剪則需要修正。

7. 檢查影格 + 修復高亮對齊

提取每個推近鏡頭開始和結束時的影格並仔細檢查。第一大缺陷:聚光燈高亮在縮放過程中偏離目標 — 因為高亮框必須是縮放容器的子元素(請參閱規則 → 高亮追蹤)。同時驗證:沒有空白/載入中畫面,行動裝置畫面整齊地放置在手機框中,文案清晰可讀。

8. 混入音樂

執行 templates/engine/mux.mjs → 最終配樂 MP4(loudnorm、淡入/淡出、-shortest)。驗證輸出包含音訊串流,且與影片長度匹配。

9. 產生 9:16 直立版本

mux.mjs --reframe 會產生一個 1080×1920 的裁剪版本。請勿中心裁剪(這會切掉底部錨定的說明)— 使用保留整個影格的模糊信箱模式;行動裝置的節拍已經居中顯示。

規則(得之不易 — 請勿重蹈覆轍)

  • 高亮追蹤。 覆蓋在螢幕上的聚光燈/高亮矩形,在推近鏡頭時必須是同一獲得 scale 轉換之元素的子元素,並位於靜態截圖的像素座標空間中。作為同層級元素,它會保持在原位,而影像則會縮放,導致在鏡頭中偏離目標。
  • 示範資料歸零。 當前週期通常是未付或空的。使用一個冪等(確定性 ID,先刪除後插入)且相對於 current_date 的種子來修復它,使其能自動修復每個週期。
  • CORS 來源。 本地提供服務的建置呼叫已部署的示範 API 是跨來源的。請在 API 允許清單中的來源上提供服務(探查它)— 絕不停用瀏覽器網頁安全性來繞過此問題。
  • 等待真實資料。 networkidle2 可能在應用程式的資料請求到達之前就解析完成 → 您會捕獲到載入中畫面。在截圖之前,需額外等待成功的 /api/... 回應(或目標內容選擇器)。
  • HyperFrames 優於即時捕獲。 CDP screencast 會在頁面視覺上靜止時停止發送影格,並以低於標稱的 fps 運行;在 HTML (GSAP) 中編寫則可避免這兩者。如果您必須錄製即時內容,請讓游標抖動並以有效 fps 進行編碼。
  • 音樂授權。 CC-BY(incompetech/Kevin MacLeod)需要在 LP 描述中加入署名;CC0(Pixabay 等)則不需要。切勿在已發布的頁面上使用未經授權的抓取剪輯。
  • 如果片段具有可變 fps,請使用濾鏡而非分離器進行連接 — 分離器會無聲地丟棄影格。

設計系統提取(品牌無關)

合成是品牌中立的;extract-design.mjs 會從目標應用程式本身填入其 CSS 變數:--bg(頁面背景)、--accent(主要/連結顏色)、--fg(標題顏色)、--font-hero/--font-mono(計算後的字型)、--radius。這使得一個技能能夠為任何應用程式產生符合品牌的宣傳影片,而無需手動挑選權杖。務必檢查取樣的權杖 — 低對比或臨時顏色偶爾會取樣錯誤;請在 promo.config.design 中覆寫。

錯誤

  • 應用程式無法在無頭模式下驗證 → 設定的 authInject 配方有誤;請先驗證 token 在第一次導航之前已確實存入 localStorage/cookie。
  • 畫面渲染為空白 → 遺漏了 CORS 來源(步驟 1)或等待資料(規則)。
  • 渲染超出畫布錯誤 → 真正的文字裁剪需要較小的字型/換行;裝飾/退出溢出是干擾。
  • 高亮對齊不正確 → 它不是縮放容器的子元素(規則)。

與行銷人員角色的協作

使用行銷人員角色處理文案:標題鉤、主要標題和每個節拍的價值框架應遵循專案語調(launch-feature 的 voice.md / marketer-hooks.md,如存在)。保持螢幕上的文案為一個標題鉤 + 一個短標題 + 每節拍一行副標題。

相關技能