Communitygithub.com

DemoDay

將儲存庫(GitHub 或本地資料夾)及其即時網路應用程式或原生 macOS 應用程式,轉變為 45–75 秒的 1080p 展示影片,宛如應用程式自家設計師所製作。

DemoDay 是什麼?

DemoDay 是一款 Node/TS CLI 工具,能將程式碼儲存庫和對應的即時應用程式(網頁或 macOS 原生)自動轉換為高品質的展示影片。使用者扮演導演角色,透過編寫故事板(plan.json)來規劃影片腳本,工具則負責錄製與渲染。無需任何 API 金鑰。此技能支援 GitHub 儲存庫或本地資料夾,並針對 Web 與原生 macOS 應用程式提供不同的錄製路徑,後者使用 Accessibility API 與 ScreenCaptureKit。影片的視覺風格會自動匹配應用程式的設計系統(色彩、字型、吉祥物),並包含腳本化的語音、自動縮放、字幕與音效。若遇到錯誤,技能會提供詳細的除錯資訊(如事件日誌與存取性快照),並允許使用者僅重新渲染或重新錄製特定部分,大幅降低迭代成本。主要限制在於僅支援 macOS 原生應用程式錄製,且無法處理需要登入的網頁流程。

相容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/amoveablefeastym/demoday/tree/HEAD

在你喜歡的 AI 中提問

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

說明文件

DemoDay 是做什麼的?

將一個儲存庫(GitHub 或本地資料夾)及其即時網路應用程式或原生 macOS 應用程式,轉變為 45–75 秒的 1080p 展示影片,看起來就像是應用程式的自家設計師製作的。此工具是本技能隨附的 Node/TS CLI。您是導演:您編寫故事板(plan.json);工具負責錄製並渲染。無需 API 金鑰。

0. 找到並設定工具 (TOOL)

TOOL 是此技能的基礎目錄(如果它包含 package.json,即一般安裝:整個儲存庫被克隆到 ~/.claude/skills/demoday)。否則,它就是 ~/demoday。如果兩者都不存在,請停止並引導使用者參考 README 中的安裝步驟。

在機器上首次執行時(當 TOOL/node_modules 遺失時):

  1. 檢查 node --version(需要 ≥ 20)。如果遺失,告訴使用者安裝 Node.js(brew install node 或 nodejs.org)並停止。
  2. 在 TOOL 中執行 npm install && npx playwright install chromium。它會下載約 300 MB,所以在開始前先告訴使用者。
  3. 對於 Mac 應用程式,也要檢查 xcrun swiftc --version。如果遺失,請要求使用者執行 xcode-select --install。輔助程式會在首次使用時自行編譯。

以下所有指令都在 TOOL 中執行。OUT = out/<owner>__<repo>(由工具印出)。影片會保留在 TOOL/out/ 中,所以請告訴使用者完整路徑。

1. 收集

npx tsx src/cli.ts <owner/repo or github url> [--url <live app url>] --prepare

需要一個即時的網頁 URL(--url,否則使用儲存庫的首頁)——或者,對於原生 macOS 應用程式,請參閱下方的「原生 Mac 應用程式」。這會讀取儲存庫並探查應用程式,將以下內容寫入 OUT: prompt.md(導演規則 + README + 清單 + 檔案樹 + 存取性快照)、probe.png(首螢幕截圖)、probe.aria.yml。

閱讀 prompt.md 並查看 probe.png。閱讀 src/schema.ts——它正是 plan.json 的形狀,其欄位描述是規則(字數限制、每個節拍必須做什麼)。

2. 在撰寫任何內容之前先找出故事

影片的成敗取決於兩件事:為什麼現狀很糟以及這個產品有什麼特別之處。

  • 現狀:目標使用者今天在沒有這個產品的情況下所做的具體工作流程,並誠實地列出每個步驟的時間成本。只能對有名稱的競爭對手提出合理的聲明。
  • 特別之處:使這成為可能的機制(來自 README/程式碼),而不是形容詞。「只有 X …」。
  • 閱讀程式碼以尋找 README 低估的功能:一個始終存在的桌面或選單列圖示、一個全域快速鍵、離線/本地儲存、一個吉祥物。這些通常是真正的差異化因素。在將其放入影片之前,請先在程式碼中驗證您聲稱的每個功能。
  • 如果使用者告訴了您他們的定位、競爭對手或差異化因素,請使用他們的。如果沒有什麼能顯示出其與眾不同之處,請在撰寫計劃之前先問一個簡短的問題。

3. 匹配應用程式的風格(必要)

影片必須看起來像是應用程式的一部分:相同的顏色、相同的字型、相同的吉祥物或圖示、相同的語氣。在一個溫馨的粉彩應用程式上使用一個通用的深色啟動模板(或反之亦然)會讓人覺得不符品牌形象。使用者會立刻注意到。

  1. 從程式碼中提取應用程式的設計符號:
    • SwiftUI/AppKit: 一個 Theme.swift 風格的檔案、Assets.xcassets/*.colorset、Color(hex:) 呼叫。
    • 網頁: CSS 自訂屬性、tailwind.config.*、主題檔案、<meta name="theme-color">。
    • 收集:背景、文字、卡片/面板、強調色,以及顯示/正文字型。
    • 字型: 偏好儲存庫中捆綁的字型檔案(Resources/Fonts/*.ttf、public/fonts、@font-face 來源、next/font/local)。
    • 吉祥物/圖示: 精靈圖、應用程式圖示(AppIcon.icns → sips -s format png … --out icon.png),或標誌 SVG/favicon。
  2. 從應用程式的 UI(而非其類別)選擇情緒。當 UI 是淺色、溫暖、俏皮或極簡時,使用 mood: "soft"。當應用程式本身是深色、技術性或高對比度時,使用 bold(預設的深色啟動外觀)。
  3. 填寫 plan.look:
    "look": { "mood": "soft", "paper": "<app bg>", "ink": "<app text>", "surface": "<app card>",
              "fontFile": "<repo font file>", "bodyFontFile": "<optional>",
              "motifImage": "<app icon/mascot png/svg>" }
    
    • 將 product.accent 設定為應用程式的強調色,選擇在 paper 上可讀的色調。淺色模式的強調色通常是 soft 的正確選擇。
    • 淡化的文字和線條會從 paper/ink 自動衍生。
    • 如果沒有字型檔案,請使用 display(Inter Tight、Pixelify Sans、Fredoka、Nunito)。要支援另一個 Google 字型,請將其添加到 remotion/lib.ts 和 schema 列舉中的 DISPLAY。
    • motif: "loaf" 是一個內建的像素麵包精靈圖(僅限烘焙應用程式)。否則請使用 motifImage。
    • CLI 會將這些檔案複製到 OUT/brand/。路徑可以是相對於本地儲存庫的絕對路徑。
  4. 匹配語氣:借用應用程式自身的微型文案和隱喻來製作字幕和標題(例如烘焙應用程式的「麵團 / 發酵 / 出爐」)。
  5. 預設保持極簡:
    • 文案預算:鉤子 ≤ 8 個字,約 3 個舊方法步驟,3 個比較行,2–5 個字的字幕,除了基本要素外沒有標籤或統計資料。
    • 太多的文字和響亮的紅色警告樣式是最大的抱怨。soft 外觀已經移除了計數器、痛苦標籤、抖動和印章。

4. 撰寫 OUT/plan.json

遵循 prompt.md 頂部的導演規則。錄製規則(newWay.actions):

  • 涵蓋整個核心流程,而不僅僅是達到一個結果的最短路徑。當頭條功能遺失時,使用者會注意到。目標是 10–20 個動作(最多 20 個),每個功能都有自己的字幕節拍,執行與舊方法相同的工作,並以回報結束。網頁:第一個動作是 goto 即時 URL。
  • 幾乎為每個動作添加字幕。 對於靜音觀看者來說,沒有字幕的節拍就像是死寂的空氣。
  • 攝影機:它會推近每個動作的目標方塊。未指定目標的 fill/press 動作會瞄準具有焦點的欄位。錄製器會在發送按鍵後記錄其位置,而打字鏡頭會放大到 2 倍於文字開始處。字幕會放在視窗下方的專屬頻帶中,永遠不會覆蓋應用程式。如果某個鏡頭框錯了東西,請修正目標。不要手動編輯方塊。
  • 選擇器來自快照。偏好逐字複製的 {role, name}(macOS:id,然後 placeholder,然後 role+name)。程式碼編輯器內的隱藏輸入是可以的;錄製器會點擊它們的可見容器。
  • 從真實快照(而非猜測)編寫更深層的腳本:
    1. 撰寫一個一次性腳本,導航到該處並以點擊一個不存在的 id 結束。
    2. 執行它:mac/.build/macdriver run --app X.app --out <scratch> --script s.json -- --demo <scratch>/data。檔案是 {"actions":[…]}。網頁:執行 --from plan 執行。
    3. 閱讀 <scratch>/events.json 中的 failures[].aria。
  • 打字:長度 > 80 個字元的 fill 值會被貼上;較短的值則會可見地輸入。使用真實的資料,永遠不要用 "test"。如果在點擊進入新欄位後按鍵遺失(標題被截斷、欄位為空、後續點擊找不到文字),請將其拆分:click 該欄位,wait 500,然後是無目標的 fill。
  • 回報:恰好有一個動作帶有 emphasis: true。將其放在一個最終的 wait(約 2000 毫秒)上,並附上字幕,緊跟在觸發它的點擊之後,而不是在點擊本身上。然後攝影機會拉遠以顯示整個結果,而強調等待會以即時速度播放。其他長時間等待會被快轉。
  • 啟動器節拍:如果應用程式以一個始終存在的圖示(桌面、選單列)或透過全域快速鍵存在,請設定 plan.launcher(captions、可選的 hint 如快速鍵、可選的 badge)。
    • 影片隨後會在逐步解說之前獲得一個節拍:圖示位於一個平靜的桌面上,周圍是模糊的視窗,遊標點擊它,然後真實的視窗從中長出,精確地落在逐步解說開始的位置。
    • 它是在 Remotion 中合成的(錄製器只捕捉應用程式視窗),並使用 motifImage/motif 作為圖示。僅在程式碼確認該行為時使用它。

5. 錄製 + 渲染

npx tsx src/cli.ts <repo> --plan OUT/plan.json --from plan

監控日誌:每個動作 ✓,失敗時顯示 ✗ 以及錯誤訊息。發生失敗時,閱讀 OUT/events.json → failures[](每個都包含失敗當下的存取性快照),修正目標,然後重新執行。失敗的動作會被跳過,不是致命的。不要發送其回報失敗的影片。如果早期動作失敗,其後的所有動作通常會在錯誤的畫面上執行: 將整個錄製視為不良,並查看 raw.mp4 影格以了解實際發生的情況。

低成本重新執行:

  • 程式碼、外觀、launcher、音效或場景程式碼變更: --from render,無需重新錄製。
  • 動作字幕在錄製時已嵌入 events.json 中。從 plan.json(按 index)將它們修補到那裡,使用 npx tsx -e 'import {editRecording} from "./src/edit.ts"; editRecording("OUT")' 重建時間軸,然後 --from render。
  • 步驟變更: --from plan(重新錄製)。

6. 在報告前審查

審查渲染後的 MP4,而不僅僅是靜止影像。製作聯絡表並查看每個影格:

ffmpeg -v error -y -i OUT/demo.mp4 -vf "fps=1/2,scale=640:-1,tile=4x8" -frames:v 1 <scratch>/sheet.jpg

檢查:

  • 風格匹配:將 probe.png 放在靜止影像旁邊。背景系列、字型、強調色和吉祥物相同嗎?如果影片看起來像不同的品牌,請在處理其他任何事之前先修正 look。
  • 每個 fill 值都完全如輸入般出現在螢幕上。✓ 只表示動作已執行,並不表示文字已落地。
  • 攝影機已推近到重要的東西(正在輸入的文字、正在點擊的控制項),而不是寬景或空白畫布。
  • 字幕可讀,且從不覆蓋應用程式。文字適合;沒有溢出。
  • 驚嘆影格顯示回報(不是載入狀態或裁剪過的按鈕)。
  • 比較節拍的「X → Y」令人信服。如果比例荒謬,則舊方法的 seconds 被誇大了。
  • 音訊存在且峰值低於 0 dB:ffmpeg -i OUT/demo.mp4 -af volumedetect -vn -f null -。要檢查同步,繪製一個打字片段的 showwavespic 並與影格進行比較。

7. 報告

提供使用者:

  • OUT/demo.mp4 的路徑及其長度
  • 鉤子、舊方法和只有我們的行,每行一行
  • 外觀是如何匹配的(哪些顏色、字型和吉祥物來自應用程式)
  • 您無法使其運作的任何東西,或者是合成的而不是錄製的(例如啟動器節拍)
  • 您在他們的應用程式中注意到的任何錯誤(例如遺失的按鍵)

提及工具印出的 npx remotion studio … 指令用於即時調整,以及 --music <file> 用於配樂。

音效

預設開啟;--no-sfx 將其關閉。scripts/make-sfx.py 將所有內容合成(無樣本,無授權)到 assets/sfx/ 中,而 remotion/Sfx.tsx 根據錄製的事件為每個聲音定時:

  • 打字:每個字元一個觸覺機械開關聲音(凸點點擊、到底聲、釋放聲),以錄製器的實際打字速度進行。空格鍵獲得更深沉的聲音,Enter 鍵則更重。
  • 點擊:在錄製的遊標點擊處發出滑鼠點擊聲,包括啟動器點擊。
  • 轉場:每個場景變換時發出嗖嗖聲。
  • 舊方法:每個步驟發出卡片落地聲(soft 中為彈出聲,bold 中為砰的一聲)和一個裁決聲(soft 為輕柔的彈出聲,bold 為印章聲)。
  • 回報:發出提示音。
  • 比較:每行發出一個彈出聲,並在時間結果上發出提示音(soft)或印章聲(bold)。

使用 --music 時,音樂會在效果下降低。在 Sfx.tsx 中更改音量並重新執行 --from render。編輯後重新執行腳本以重新生成 WAV 檔案。

原生 Mac 應用程式

流程相同,但錄製器不同(mac/macdriver.swift:使用 Accessibility API 尋找控制項、真實的滑鼠/鍵盤事件、ScreenCaptureKit 僅錄製應用程式視窗)。新增 --app 並在 -- 之後傳遞啟動參數:

npx tsx src/cli.ts <repo or ./local/dir> --app path/To.app [--app-seed demo/items.json] --prepare -- --demo {data}
  • {data} 每次執行都會變成一個全新的暫存資料夾,而 --app-seed 會被複製到其中。永遠不要針對使用者的真實資料進行錄製。 如果應用程式沒有 demo/data-dir 啟動標誌,請在錄製前新增一個(或要求使用者新增)。如果使用者有未提交的變更,請先重建應用程式。
  • 首先執行 mac/.build/macdriver check --open。它需要承載終端機的應用程式具備輔助使用和螢幕與系統音訊錄製權限。如果缺少任一項,它會開啟確切的系統設定面板並命名要啟用的應用程式(退出碼 3)。使用者必須在授予權限後重新啟動該應用程式,這會結束此工作階段,所以請停止並告訴他們稍後再回來,而不是重試。沒有螢幕錄製時,--prepare 仍然有效,但錄製會失敗。同時編寫故事板,以便準備就緒。
  • 錄製會接管使用者的真實滑鼠和鍵盤(約 20–60 秒,3 秒倒數計時)。在每次執行前告訴使用者,包括短暫的探查執行。不要在他們可能正在打字時開始:他們的輸入會竊取焦點並毀掉拍攝。
  • 目標:id,然後 placeholder,然後 role+name。沒有 goto。沒有目標的 fill 會輸入到焦點欄位。使用 press 來處理 Enter/Tab/Meta+N。
  • 無標籤的圖示按鈕對自動化是不可見的。如果一個關鍵控制項沒有名稱並且您擁有程式碼,請添加 .accessibilityLabel/.accessibilityIdentifier。
  • 不要在鍵盤輸入鍵時查詢 Accessibility 樹。 在 SwiftUI 應用程式中,AX 查詢可能會觸發重新渲染,從而將文字欄位重置為過時的文字,導致按鍵遺失。驅動器只在打字後讀取焦點元素。如果您更改驅動器,請保持這種方式。如果按鍵仍然消失,應用程式很可能有這個錯誤(一個 NSViewRepresentable 文字視圖,其 updateNSView 用一個過時的綁定覆蓋了字串)。告訴使用者。

限制

需要登入的網頁需要流程從一個公開頁面或預先認證的 URL 開始。原生錄製僅限 macOS,並錄製單一應用程式視窗。其外部的任何內容(桌面、選單列、其他應用程式)都是在 Remotion 中合成的,而不是錄製的,所以在報告中說明這一點。

相關技能