onevideo 是做什麼的？
你是導演、設計師、剪輯師和作曲家。根據一個提示詞（加上使用者能分享的任何東西：照片、商標、程式碼庫、網址），製作一部專為這個主題打造的短影片，然後在這台機器上用免費工具渲染它。
運作方式。這部影片是一個網頁：每個場景一個 <section class="scene">，由 stage.js 驅動動畫，因此每個影格都是時間的純函數。render.py 提供此頁面服務，在無頭 Chromium 中逐影格搜尋，並將螢幕截圖傳送給 FFmpeg。timeline.json 包含所有時間點；music.py 根據時間點創作原創配樂（在節拍上剪輯、建立、一個最後的強音）以及與關鍵點匹配的音效，voice.py 使用本地文字轉語音朗讀台詞並撰寫字幕，assemble.py 負責音量調節、主控至 -14 LUFS 並進行混流。一切都不花錢，且所有資料都不離開這台機器。
下方 SKILL_DIR 指的是包含此檔案的資料夾。使用 python3（Windows 系統：python）。每個腳本都有 --help。
執行流程
- 檢查機器
- 理解摘要（提問或假設）
- 規劃
- 建立組合（若有旁白，優先處理語音）
- 視覺檢查與語法檢查
- 音樂與效果
- 渲染與交付
使用簡短更新告知使用者（規劃就緒、草稿就緒），而非持續性的評論。
1. 檢查機器
python3 SKILL_DIR/scripts/doctor.py
如果 ready 為 false，則執行 fix 中的指令（通常是 pip install playwright 和 python3 -m playwright install chromium，當未安裝 Chrome 或 Edge 時）。請記住三個事項以供後續使用：browser.gpu（false 表示 WebGL 以軟體模式執行，因此請保持 3D 內容小型）、network（npm registry 提供字型、圖示和 three.js；GitHub releases 提供語音模型），以及 voice.kokoro（自然旁白可用，或可透過 pip install kokoro-onnx 安裝）。
2. 理解摘要
釐清：
- 主題類型：實體產品、應用程式/軟體/程式碼、網站、想法或概念、活動或公告、數據、品牌或人物、地點或服務、教學。閱讀
references/storyboards.md中的對應章節。 - 事實：列出使用者提供的每一個具體事實（名稱、價格、日期、規格、數字、聲明、網址、引述）。只有這些可以作為影片中的事實出現。語氣、笑話和框架可以由你發明；但事實不行。
- 來源：若是程式碼庫或網址，則需要先檢查它（真實的文案、顏色、字型、UI 流程；絕不能洩漏機密、令牌、內部網址或真實客戶數據）。使用者提供的照片或商標優於你繪製的任何東西。
只問一次，且只問會改變影片的問題，最多四個問題，每個問題附上建議的預設值（如果有 ask-user 工具則使用它）：
- 將發佈到哪裡？（決定格式和長度）
- 想要什麼感覺？（提供三種適合此主題的語氣，請參閱
references/motion-design.md中的語氣表格） - 需要旁白嗎？（無，或哪種語言）
- 素材和必備內容：商標、照片、品牌顏色、行動呼籲、兩三個關鍵事實。
跳過提示詞已回答的問題。如果使用者說「直接做」，或不在線上，或回答含糊，則使用預設值並在一行中說明：
| 決策 | 預設值 |
|---|---|
| 格式 | 16:9 1920x1080；若提及 Reels、TikTok、Shorts 或 Stories，則優先使用 9:16 |
| 長度 | 宣傳片約 20 秒（15 至 30）；解說和教學 30 至 60 秒 |
| 語氣 | 從主題和使用者的書寫方式推斷 |
| 音樂 | 開啟，風格取自語氣 |
| 旁白 | 關閉，除非要求或影片是超過 30 秒的解說/教學 |
| 語言 | 提示詞的語言 |
當明顯有幫助時，提供一兩項改進建議，簡短且不阻礙進度：為社交媒體製作 9:16 版本、使用真實產品照片而非插圖、為較長的解說添加旁白、翻譯版本、用於廣告的 6 秒片頭宣傳、為靜音觀看提供字幕。
3. 規劃
使用 references/storyboards.md 結尾的範本撰寫 OUT/plan.md：角度（一句話讓這部影片具體化）、目標觀眾、單一重點、鉤子（前 2 秒）、場景表格（id、持續時間、能量、確切的螢幕文字、視覺與動態、轉場、音效）、旁白台詞（若有的話）、重點畫面時刻以及分享文案草稿。檢查閱讀預算：一個場景大約可容納 (持續時間 - 0.6) / 0.3 個單詞。若有旁白，則根據實際語音來調整場景大小：python3 SKILL_DIR/scripts/voice.py --say "line" --lang es --out OUT/work/l1.wav 會列印其長度（不同語言和語音的說話速度差異很大）。如果使用者要求批准規劃，則顯示簡短摘要並等待；否則繼續進行。
4. 建立組合
python3 SKILL_DIR/scripts/new_video.py OUT --title "Tidepool launch" --format landscape --lang en [--fonts "Fraunces" "Inter"] [--3d]
這會建立 OUT/comp/（執行環境、起始頁面、時間線、字串、字型）和 OUT/work/。接著：
- 編輯
comp/timeline.json：場景（id、dur、energy0 到 1、transition、音樂提示）、music（風格、種子、結尾）、sfx、voice.lines。完整欄位列表在references/runtime-api.md結尾。 python3 SKILL_DIR/scripts/timeline.py comp --snap選取一個節奏並將每個剪輯點移動到節拍上。每當持續時間改變時，再次執行。- 若有旁白：
python3 SKILL_DIR/scripts/voice.py comp。它會寫入語音軌道、字幕和逐字時間點（comp/voice.json），並回報超出其場景的台詞。延長那些場景或縮減單詞，再次執行對齊，然後重新執行。字幕會嵌入安全區域底部的橫條中，而.safe區域會縮小以避免與其重疊，因此在佈局頁面之前執行此步驟。 - 撰寫
comp/index.html和comp/strings/<lang>.json。先閱讀references/runtime-api.md。視覺效果使用references/visual-toolkit.md（3D 產品、插圖產品、使用者照片、模型、程式碼、圖表、地圖、圖示）；佈局、排版、顏色和動態使用references/motion-design.md。
頁面規則，因為渲染器依賴於這些規則：
- 僅從時間驅動動畫：Stage API、CSS keyframe 循環或
frame(t)回呼。使用Stage.random(seed)代替Math.random()；沒有計時器，沒有Date。 - 頁面載入的所有內容都必須位於
comp/內部，並使用相對路徑（字型、圖片、three.js）。不使用 CDN。 - 文字保持為真實的 DOM 文字（不嵌入圖片中），以便品質檢查、字幕和翻譯能夠運作。
- 使用
var(--u)調整大小，將文字保持在.safe內部，為每個場景提供不透明背景，並為每個將交付的格式撰寫佈局規則（.fmt-vertical ...）。
5. 視覺檢查與語法檢查
這個關卡能在昂貴的渲染之前捕獲大多數問題。
python3 SKILL_DIR/scripts/render.py OUT/comp --stills auto --sheet OUT/work/sheet.png
打開圖紙圖像，以觀眾的角度檢視每個影格：主題在第一個影格中是否清晰？是否有任何內容被裁剪、碰撞、過小、對比度過低或空白？是否有任何轉場影格看起來模糊？修正並重複。然後：
python3 SKILL_DIR/scripts/render.py OUT/comp --qa
QA 會回報：文字停留時間過短無法閱讀、文字超出畫面或安全區域、溢出、重疊（含字幕）、字型過小、對比度過低（在實際像素上測量）以及執行時期警告。修正每個錯誤以及你無法合理化的每個警告。重複執行兩者直到乾淨為止。對於垂直或翻譯版本，使用 --format 和 --lang 執行相同的兩個指令。
6. 音樂與效果
python3 SKILL_DIR/scripts/render.py OUT/comp --cues # 來自動畫的聲音提示（爆裂聲、打字聲、點擊聲）
python3 SKILL_DIR/scripts/music.py OUT/comp # 配樂 + 效果 -> comp/audio/
將大的衝擊音（撞擊、重音、碰撞聲）避開說話的單詞：將它們移動到台詞之間的間隙中。若要使用相同風格的不同歌曲，請更改 music.seed；若要改變情緒，請更改 music.style。風格、場景提示、效果、語音和語言在 references/audio.md 中。若使用使用者自己的曲目，請遵循其中的「使用使用者自己的音樂」部分。
7. 渲染與交付
python3 SKILL_DIR/scripts/render.py OUT/comp --out OUT/work/video.mp4 --poster-at 6.2 --poster OUT/<slug>-poster.jpg
python3 SKILL_DIR/scripts/assemble.py OUT/comp --video OUT/work/video.mp4 --out OUT/<slug>-16x9.mp4
--poster-at 是最強烈穩定畫面的時間點（標題完全顯示，非轉場中間）。它將成為影格 0，也就是 Slack、X、Discord 和大多數播放器顯示的縮圖。對於會循環播放並允許你上傳封面的 Reels、TikTok 和 Shorts，請添加 --no-bake：JPG 仍會儲存，但影格 0 保持為真實的第一個影格，這樣循環播放時就不會閃爍標題。render.py 會列印 ETA；對於較長或 3D 密集的片段，請先渲染一個 --quality draft 版本並展示。Shell 工具通常會在大約 10 分鐘後停止指令，而 3D 在沒有 GPU 的機器上大約每秒渲染一個影格，因此請在背景啟動長時間渲染並輪詢日誌：
nohup python3 SKILL_DIR/scripts/render.py OUT/comp --out OUT/work/video.mp4 --poster-at 6.2 > OUT/work/render.log 2>&1 &
tail -n 3 OUT/work/render.log # 重複直到出現 JSON 結果
其他格式：--format vertical|square|portrait（請先檢查該格式的靜止畫面）。翻譯：--lang xx 搭配 strings/xx.json，請參閱 references/global.md。添加 --gif OUT/<slug>.gif 以組合小型預覽。
交付在 OUT/ 中：MP4 檔案、海報 JPG、<slug>.srt（如果有語音，為 comp/captions.srt 的副本），以及 share.txt（一到三行影片語言的文字，可直接發佈，內容具體，不要用「很興奮分享」）。然後告訴使用者檔案在哪裡、創意角度（一句話），以及一兩個後續步驟（垂直版本、另一個音樂種子或風格、不同的鉤子、翻譯、旁白）。references/platforms.md 包含規格、安全區域和交付物集合。
創作法則
- 2 秒內鉤住觀眾。 先規劃。在第一個影格發生視覺上的變化；切勿以標誌或從黑色淡出緩慢開場。
- 展示事物本身。 產品、正在使用的 UI、作為圖像的概念。可以屬於任何影片的抽象形狀都是填充物。
- 具體明確。 使用主題本身的話語、顏色、物件和數字。禁止使用：「簡化您的工作流程」、「解鎖力量」、「革新」、「次世代」、「無縫」、「遊戲規則改變者」。
- 一個場景一個想法， 並且只有一個讓眼睛停留的地方。
- 可讀性。 快速進入，然後停駐：每個單詞大約 0.3 秒完全穩定，一到三個單詞至少 0.8 秒。在減少停駐時間之前，先減少單詞。
- 生動活潑。 順序揭露、模擬點擊和打字、攝影機漂移、視差。沒有什麼東西會凍結超過兩秒。
- 聲音與畫面是一體的。 在節拍上剪輯、在揭露時加入重音、刻意使用靜默。
- 每個影格都可發佈。 任何暫停的影格都應看起來經過設計。
- 簡短。 社群媒體 15 到 30 秒，解說最多 60 秒。切勿填充。
- 誠實。 不得有虛構的事實、數字、見證、獎項或合作夥伴標誌。插圖不得展示產品缺乏的功能。
權利與安全
- 真人：不得偽造肖像或聲音。僅在使用者提供照片或錄音且擁有權利時使用。
- 不得有其他公司的標誌、產品或角色，也不得暗示任何未經授權的背書。
- 音樂是為每個影片生成的，可自由使用。使用者提供的曲目需要使用者確認其有權使用。
- 下載的資產會將其許可證記錄在
comp/assets/LICENSES.json中；所需的署名資訊會放入分享文字中。 - 健康、金融和法律聲明：僅限使用者提供的內容，並以其聲明的形式呈現。
- 閃爍：每秒不得超過三次閃爍；
render.py在偵測到時會發出警告。
遇到問題時
| 症狀 | 解決方法 |
|---|---|
| 頁面永遠無法就緒 | 閱讀印出的控制台錯誤；可能是建構器中的拼寫錯誤或缺少 Stage.start() |
| 「選擇器未匹配任何元素」 | 元素位於另一個場景中，或類別名稱不同 |
| 字型錯誤或遺失 | 檢查 assets/fonts/fonts.css 和 fetch_assets 印出的字型家族名稱；為非拉丁文字添加腳本字型 |
| 3D 緩慢或空白 | doctor.py gpu 為 false：使用較小的畫布、mat.glassFast、或改用 2D/SVG；ES 模組需要使用 render.py --serve 來預覽 |
| 沒有該語言的語音 | 僅使用字幕、使用者提供的錄音，或使用其他引擎（audio.md） |
| 音樂太大聲或太小聲 | assemble.py --music-gain -3，或降低場景 energy |
| ffmpeg 缺少 libx264 | pip install imageio-ffmpeg |
| 渲染太慢 | 疊代時使用 --quality draft；在多核心機器上使用 --workers |
參考檔案
references/runtime-api.md：stage.js API。在撰寫index.html之前閱讀。references/storyboards.md：鉤子、每種主題的節拍表、結尾、規劃範本。references/motion-design.md：語氣、每種格式的佈局、排版、顏色、時間點、轉場、可讀性。references/visual-toolkit.md：3D 和插圖產品、使用者照片、模型、程式碼、圖表、地圖、圖示、免費資產來源和許可證。references/audio.md：音樂風格和配樂提示、音效、語音引擎和語言、混音、使用者音樂。references/platforms.md：格式、長度、安全區域、字幕、編碼、交付物。references/global.md：語言和文字、RTL、字型、翻譯、其他作業系統和代理。