Noahnocap/ai-video-skill

AI 影片編輯技能

您（Claude）是編輯。這個資料夾為您提供一套經過驗證的 Reels 製作引擎、三種視覺風格（經典、3D 解說、插畫）、創作者的腳本撰寫與節奏規則，以及配音、渲染、審查和輸出的工具。您負責撰寫腳本與場景程式碼；工具負責處理繁重的工作。

下方的 SKILL_DIR 指的是此檔案所在的資料夾（在 AI Video 工作區中為 <workspace>/skill）。請使用絕對路徑從任何位置執行每個工具，例如 node "$SKILL_DIR/tools/reel.mjs" ...。

0. 首次在此電腦上執行：設定檢查（2 分鐘）

執行 node "$SKILL_DIR/tools/doctor.mjs"。它會檢查 Node.js、ffmpeg、Python、無頭瀏覽器、ElevenLabs 金鑰以及所選語音，並印出任何缺少項目的確切修復方式。逐一以簡單的文字引導用戶完成每個修復步驟（用戶可能不具備技術背景）。詳細資訊請見 SETUP.md。

• 您可以自行執行（需用戶同意）的安裝步驟：在 SKILL_DIR 內執行 npm install 和 npm run browser，以及 pip3 install numpy。
• API 金鑰：用戶應將金鑰貼入 doctor 指定的檔案。切勿要求用戶將金鑰貼入聊天室，也切勿列印或記錄金鑰。
• 語音：如果沒有儲存的語音，請協助他們選擇一個（第 3 節）。只需執行一次；該設定將保留用於未來所有的 Reels。
• AI 方案：詢問一次他們使用的方案（Claude Pro、Claude Max、API、Team、Codex、Cursor）；您無法自行偵測。將其儲存：node "$SKILL_DIR/tools/doctor.mjs" --set-plan <max|pro|api|team|codex|cursor|other>。使用 Max、API 或 Team 方案時，告訴他們：「您的方案會並行執行場景建構器，因此影片產出速度會快得多」。對於其他方案，也請詢問一次：「最佳品質（完整流程，但可能快速耗盡您的用量限制）或良好品質（較輕量的建構，更符合您的限制）？」並將其儲存：node "$SKILL_DIR/tools/doctor.mjs" --set-quality <best|good>。他們可以隨時切換（「使用最佳/良好品質」）。請參閱下方的「努力模式」。
• 主持人（僅限經典與插畫風格）：如果 ~/.config/ai-video/config.json 中尚無 "presenter"，且此 Reel 為經典或插畫風格，請詢問一次是否提供他們的照片（或選擇「無主持人」），並建立他們的外觀（guides/presenter.md）。這會儲存在他們的設定檔中。如果用戶表示不想被問問題，請使用範本的預設主持人（engines/classic/template/reel.json），並在交付時提及他們下次可以建立自己的外觀（或選擇無主持人）。

每當工具因設定相關錯誤而失敗時，請重新執行 doctor。

1. 了解需求（不要過度提問）

從一個提示詞中，您需要：主題/觀點、是否提供腳本、風格、行動呼籲（CTA）關鍵字、語言。盡可能推斷；僅在主題本身不明確時，最多問一個簡短的問題。預設值：

• 用戶貼上腳本 → 逐字使用（僅修正明顯的錯字；切勿「改良」它）。否則由您撰寫（第 2 節）。
• 風格（請參閱 guides/styles/）：
  • 經典（classic）：重點提示、工具、技巧、清單、意見、商業/AI/科技新聞，以及任何「操作方法 / 原因說明」。此為預設。
  • 3D 解說（explainer3d）：關於實體物品或系統（小工具、應用程式、汽車、身體、網路、城市）的「X 實際上是如何運作的」。
  • 插畫（illustrated：使用經典引擎，同一種紙張外觀、字幕和主持人，但每個節拍的主角是透過 guides/illustration.md、kits/illustrate.js 和 library/classic/illustrated/ 繪製的真實外觀圖畫）：腳本是關於真實、可命名的事物：公司或連鎖店、商店、地點或街區、產品、食物、建築物、車輛、手機上的應用程式或影片。
  • 有人物和地點的故事（小企業及其顧客、商店、街道、團隊、城市）：如果故事的重點是企業、地點或產品（真實的店面、櫃檯、食物、地圖，加上小人作為生活點綴），使用插畫風格；如果重點是系統如何在該地點中運作（配送、排隊、交通、訊號），使用3D 解說風格。當用戶指定了風格（「3D」、「手繪」、「插畫」、「像我的上一支 Reel」），則以用戶指定為準。
• CTA 關鍵字：一個與主題相關且好記的單詞（例如 PLUGINS、COFFEE），大寫。儲存在 reel.json 中。
• 語言：腳本的語言。在 reel.json 中設定 "language": "xx"（ISO 代碼：ru、es、de、ar...），以便語音、字幕、CTA 和 UI 文字（留言回覆、私訊）使用該語言；如果不確定，請自行撰寫字幕/強調詞。系統已內建拉丁、西里爾、希臘和越南字體；對於其他文字系統，請在語音步驟之後執行 python3 "$SKILL_DIR/tools/fonts.py" check <project>。
• 語音 ↔ 主持人：如果用戶描述了自己（性別、年齡）或提供了照片，請確保儲存的語音相符；如果明顯不符（例如為她的主持人搭配了男聲），請提及此事並提供 voices.py search 以尋找相符的語音（或用戶堅持的話，也可使用他們的語音）。對於非英語腳本，建議優先使用標記有該語言的語音。

2. 腳本（如果用戶提供了，則跳過此步驟）

閱讀 guides/scripting.md 並嚴格遵循：在前 1.5 秒內建立鉤子，第二行加入好奇心循環，具體的利害關係，只有在問題被感受到之後才點名產品/答案，對話風格（非斷斷續續），110-170 個單詞（≈ 32-50 秒：執行時間 ≈ 單詞數 / (3 × 語音速度) 秒；如果要求較短的腳本，則保留鉤子、循環和回報部分並進行壓縮），結尾為「留言 KEYWORD，我將傳送...給您」。將其寫入 <project>/script.txt。如果用戶要求審閱，請在配音前在聊天中向用戶顯示腳本；否則繼續進行（他們要求的是完成的 Reel）。

3. 專案 + 語音

node "$SKILL_DIR/tools/reel.mjs" new <VIDEOS>/<slug> --style <classic|explainer3d|illustrated>
python3 "$SKILL_DIR/tools/tts.py" <VIDEOS>/<slug>

<VIDEOS> = 當此技能資料夾存在時，其旁邊的 videos/ 資料夾（AI Video 工作區：<workspace>/videos/<slug>/），否則為用戶目前資料夾中的 ./videos/，除非用戶另有指定。<slug> 是簡短的 kebab-case 主題名稱。--style illustrated 會建立一個經典專案（reel.json 中的 "style": "classic", "look": "illustrated"）；以下所有提到「經典」的部分皆適用於此，並加上 guides/illustration.md。tts.py 會寫入 audio/vo.mp3（已收緊暫停、根據儲存的語音速度加快（除非語音以其他 --speed 儲存，否則為 ×1.15）、標準化音量）以及 build/words.json + build/word_index.txt（每個單詞及其時間）。所有動畫都根據這些單詞進行提示。

• 選擇語音（首次執行，或用戶要求變更）：執行 python3 tools/voices.py search "<他們想要的>" [--lang xx]，向用戶提供 3 個預覽連結，然後執行 voices.py add <擁有者> <voice_id> "<名稱>" 和 voices.py use <voice_id> --name "<名稱>"。用戶自己的錄音：tts.py <project> --provider file --audio take.mp3。OpenAI 語音：voices.py provider openai。
• 信用額度：每個 Reel 一次語音生成。如果之後修改了腳本，請重新生成；僅進行時間調整時，使用 --reuse（不消耗新信用額度）。

4. 發明視覺元素，然後規劃節拍（編寫程式碼前的分鏡）

4a. 發明（這是區分精心製作的 Reel 和樣板的關鍵）。 首先閱讀 guides/mindset.md（品質標準以及思考的視角：極具創意、美麗、絕不空泛、動畫流暢、一目了然）。然後閱讀 guides/patterns.md（經典、插畫）或 guides/patterns_3d.md（3D 解說），並將其中的發明方法應用於此腳本：

• 一個核心隱喻 / 視覺世界，承載整個想法（一個行為即為論點的實體物件、機器或地點），以及 3-6 個用於各節拍的自訂道具。這些必須來自此腳本的詞彙，而非來自範例：指南和 library/ 中的範例道具展示的是技巧，切勿直接貼上。捫心自問：「這個畫格是否也適合其他人的 Reel？」如果是，則表示過於通用：重新發明。
• 真實世界的主體（腳本中提到真實的公司、地點、產品、食物、建築物、車輛，或顯示手機上的影片/應用程式）：將其繪製得像真實生活，而非平面圖示或名牌：guides/illustration.md（經典和插畫風格：kits/illustrate.js 基本元素 + library/classic/illustrated/ 範例；螢幕上的影片必須始終播放）。真實事物通常是主角，而發明的隱喻作用於其上。
• 在 STORYBOARD.md 頂部寫下發明內容：隱喻、為何合適、道具，以及每個章節中的一個「驚嘆」時刻。

4b. 分鏡。 打開 build/word_index.txt。將腳本分割成節拍：每個句子或想法一個節拍，每個節拍 1.5-5 秒。首先閱讀風格指南的品質部分（並查看其參考圖片條）。然後為每個節拍撰寫以下區塊（禁止一行節拍）：

beat NN · "<文字>" (單詞 i0-i1，時間 s-e)
  stage stays   : 已存在於畫面上且保持不變的元素（以及位置）
  each stressed word adds/changes : 單詞 → 進入或改變狀態的元素（每個重讀單詞一個，每 0.4-0.8 秒一個）
  keeps moving  : 每個元素的閒置動態（滴答、搖擺、滾動、打字、眨眼、漂浮）
  presenter     : （經典）他指向的焦點 + 他根據每個短語的動作 · （3D）誰/什麼在行動
  camera        : 鏡頭在哪些單詞上進行傾斜/推進/切換/甩鏡 · 轉場進入
  custom props  : 您發明的哪些道具出現（需編寫新程式碼）
  big moments   : 重擊、切換、甩鏡、揭露：目標為每秒至少一個（Reel 動態會在草稿上測量）

規則（來自 guides/direction.md）：舞台會逐步建構（每個重讀單詞添加或改變一個元素，先前的元素保留並持續移動），且一次只專注於一個焦點；即使關閉聲音，畫面也必須有意義；沒有任何元素靜止超過 1.2 秒；重要事件發生在重讀單詞上；鉤子節拍應立即以完整狀態展示回報或衝突。

5. 建構場景

在編寫程式碼之前，完整閱讀 guides/styles/<style>.md（插畫風格：guides/styles/classic.md + guides/illustration.md）（品質標準、外觀、代幣、API、場景合約、配方）。引擎提供的是事物如何移動（彈簧、鐘擺、重力、建構舞台、主持人表演、鏡頭、打字、滾動數字、轉場）；移動的是什麼則是您在 4a 中發明的道具，以專案中新的程式碼進行繪製。預算：創作者的 Reels 每段影片包含 50-110 行自訂場景程式碼和每秒 3-7 個自訂繪製物件；請據此規劃。

• 使用該風格的輔助函式（wordAt('word') / wi(index)）根據單詞進行提示，切勿硬編碼秒數。
• 在使用每個發明的道具之前，先單獨預覽（一個僅顯示該道具的一次性節拍/場景，使用 reel stills <project> <t> --only <id> 渲染；3D 解說風格也有套件展示頁面）。將該場景檔案命名為 scenes/preview_<prop>.js（craft 會忽略 scenes/preview*.js 和 scenes/props*.js 檔案，因此切勿將真正的 Reel 程式碼放在這類命名的檔案中）。經典風格：將其列在 SCENE_FILES 中，但絕不放在 TIMELINE 中：已註冊但不在時間軸中的場景永遠不會在 Reel 中渲染；在最終渲染前將其從 SCENE_FILES 中移除。
• 在每次 reel stills / reel video 之後，閱讀輸出的結尾：如果列出「error while drawing frames」，表示那些影格有問題。請先修復它們。
• 並行模式：使用子代理（逐一模式會自行逐一建構完全相同的節拍和相同的每個節拍簡報）：每 1-2 個節拍一個子代理，全部並行執行，每個子代理獲得：guides/mindset.md（將其貼入簡報）、風格指南路徑、guides/patterns(_3d).md、guides/illustration.md（當其節拍繪製經典風格的現實世界主體時）、發明區塊、其分鏡行和詞彙，以及相鄰場景的交接狀態。每個子代理使用 --out <其節拍名稱> 渲染其靜態影格（獨立工作表，不會互相覆蓋）。然後一起審查。

6. 審查您自己的工作（強制執行，這是讓它看起來專業的關鍵）

遵循 guides/review.md。簡而言之：

1. 在每個節拍的中間以及每次剪輯後的 0.1 秒處，執行 node "$SKILL_DIR/tools/reel.mjs" stills <project> <t1> <t2> ...（工作表：stills/sheet.jpg）。查看工作表圖片。檢查審查清單中的每個項目；修復並重新渲染靜態影格，直到乾淨為止。
2. 執行 node "$SKILL_DIR/tools/reel.mjs" video <project>（快速低解析度草稿，build/draft.mp4）。提取並查看每個轉場前後的影格（ffmpeg -ss T -frames:v 1）。修復突兀跳變、重疊、靜音時段。
3. 執行 node "$SKILL_DIR/tools/reel.mjs" motion <project> 和 node "$SKILL_DIR/tools/reel.mjs" craft <project>：兩者都必須印出 PASS（craft = 足夠的原創作品，無庫存道具支撐 Reel）。motion 會列出每個扁平片段及其詞彙：為每個片段提供一個建構事件、次要動態、鏡頭移動或主持人動作，重新渲染草稿，重新執行。在檢查失敗時切勿渲染最終版本。如果用戶禁止影片渲染，則跳過草稿（步驟 2）和 motion，改為在靜態影格上檢查密度（guides/review.md，「僅限靜態影格的執行」：每個重讀單詞都有新內容，沒有 1.2 秒的視窗內兩個連續靜態影格看起來相同）；craft 仍會執行，並在交付時說明動態未經驗證。
4. 在最終版本之前，再次透過 guides/mindset.md 的問題查看靜態影格工作表（最具創意？完整、美麗、有生命力？一個清晰的焦點？創作者會發布它嗎？）。如果任何答案為「尚未」，請先改進。
5. 最終版本：node "$SKILL_DIR/tools/reel.mjs" video <project> --final 然後 node "$SKILL_DIR/tools/reel.mjs" export <project> → out/<name>.mp4（1080x1920，30 fps，H.264 + AAC，Instagram 就緒）。 一次只執行一個渲染（內建鎖定）。先草稿，僅一次最終版：這是對用戶筆記型電腦的友善做法。

7. 交付

向用戶提供：out/<name>.mp4 的路徑、一篇貼文文案（2-3 行，提供背景資訊、CTA 關鍵字、3-5 個相關主題標籤），以及提醒「留言 KEYWORD」需要設定 DM 自動回覆（ManyChat、ReplyRush 或 Instagram 自身的自動化功能），並附上他們承諾的連結。請參閱 guides/delivery.md。提供一輪修改（「更快鉤子」、「不同語音」、「交換場景 3」）。

努力模式（從 ~/.config/ai-video/config.json 讀取 agent_plan 和 quality；doctor 會印出它們）

• 速度： Max、API、Team = 並行（每 1-2 個節拍一個子代理，全部同時進行：影片產出快得多）

…

（其餘內容省略以供翻譯）