OneVideo

OneVideo 是做什麼的？

OneVideo 把「做一條影片」拆成 10 個階段。每個階段都有一份導演文件（stages/<id>.md）、一個落盤的產物（plan/*.json），以及機械門控；需要人拍板的階段要審批，審批會鎖定產物的雜湊。共享的渲染引擎在 template/，專案目錄裡只放數據。

工作方式

1. onevideo status 顯示每個階段的狀態和下一步該讀哪份導演文件。每進入一個階段，先讀對應的 stages/<id>.md，再動手。
2. 創作階段（research、proposal、script、storyboard）由你寫 JSON / Markdown，然後 onevideo validate，再把產物給用戶看，用戶確認後執行 onevideo approve <stage>。不要替用戶審批，除非用戶明確授權。
3. 非創作階段由 CLI 執行：tts、music、assets fetch、depth、timeline、render、qc，也可以用 build 一次跑到 qc（缺的素材自動下載，有 depth 工具時自動做深度圖和亮度網格）。publish 要求 review 已審批。
4. 結構按觀眾的問題排（proposal 寫問題鏈，script 每個場景寫 question）；畫面按三條線分工：旁白解釋、螢幕文字只放關鍵詞、畫面給證據（storyboard.md）。
5. 分鏡按動效引擎寫，不要做成一頁一張卡：先讀 references/motion-rules.md，參考 examples/spacex-motion。實拍做主角（footage 變速、標題壓在主體後），數字進 canvas 連續飛行，每個場景都有 shots，鉤子和結論每句一個 word 關鍵詞，有音樂時寫 music.offset: "auto"。onevideo timeline 報出的 rhythm 警告（畫面超過 4.5s 沒有新東西、連續相同轉場）要處理掉，或者向用戶說明為什麼保留。
6. 渲染後必須執行 onevideo qc，並逐張看 out/qc/frames/，確認畫面沒問題後再 approve review。

你是導演

節奏由你把控：每個鏡頭為什麼在這裡、停多久、怎麼切，都由你決定並寫進分鏡。CLI 和模型只是工具，它們給出的結論要由你核實後再採用。

• 缺畫面就自己做：assets.json 裡寫 generate，可以生圖（variants: 2–4 出多張，由視覺模型按 brief 挑一張，所有備選都留在 public/assets/<id>.take<k>.*，覺得它挑不對就寫 pick 改掉），也可以生影片（kind: "video"，from: <圖片 id> 把一張圖做成首幀動起來）。生成失敗時會回落到同一條目的 url / query，所以關鍵素材最好留一個備選來源。能找到真實素材時優先使用真實素材，生成的素材只用來補鏡頭、做氛圍、做概念畫面，不能冒充新聞實拍。
• 看片：onevideo sheet 把成片按秒鋪成聯繫表（out/qc/sheet-NN.jpg，同時輸出每個場景從哪一格開始）。用 Read 看聯繫表，比逐幀翻快得多。onevideo look 再請視覺模型按剪輯標準過一遍，結果寫進 out/qc/look.json，每條意見帶時間點和場景。它只是第二意見：先在聯繫表或 stills 裡確認問題確實存在，再改分鏡。
• 先做 15 秒樣片：整片渲染之前，先 render --draft --scenes hook,ipo（或 --from 0 --to 15）把開頭渲一段，確認風格、配音、字號、節奏都對，再渲整片。
• 迭代：改分鏡 → timeline（處理 rhythm / echo 警告）→ render --draft [--scenes …] --note "改了什麼" → sheet --vs prev 對比上一版 / look → 再改。每一輪只改一件事，改完對比確認變好了再動下一件；確認過的東西用 handoff --lock "…" 記下來，後面不要再碰。
• 交接：換對話、交給子 agent 之前先跑 onevideo handoff，它把階段、已定參數、素材質檢、最近幾版渲染、看片意見和待處理警告寫進 plan/handoff.md，並保留手寫的「鎖定 / 下一輪只改 / 備註」三節。接手一個已有專案時，先讀 plan/handoff.md。
• 並行：調研、找素材、生素材互相獨立，可以交給子 agent 並行做。分鏡和節奏由你自己寫，不要外包。

硬規則

• 旁白裡的每個數字都要能在 plan/research.json 的 facts 裡找到，facts 必須有來源（numbers 門控）。不要為了過門控而編造來源。
• 素材只用白名單授權（references/licensing.md），CC BY 素材要寫作者和來源。
• API key 只從環境變數或本機配置讀取，不列印、不寫進專案檔案。共用 key（MANGO_API_KEY 等）只發往 api.mangoqwq.com；換 baseUrl 必須配專用 keyEnv。~/.zcode 的 provider 配置僅在顯式 ONEVIDEO_ZCODE_PROVIDER=1 時讀取。
• 已審批的產物被改動後，該階段顯示 stale，需重新給用戶看並 approve。改了 script 之後必須重跑 tts，否則 timings 門控報錯、渲染被攔；不要手改 timeline.json。

命令

onevideo init <dir> --pipeline data-explainer|documentary|shorts|promo [--style midnight-data] [--aspect 16:9] [--example spacex-motion|spacex-ipo|promo-demo]
onevideo status | validate [--strict] | approve <stage> [--note …]
onevideo tts [--sample|--dry|--force|--only a,b]   # 逐句合成 → plan/timings.json（含響度歸一化）
onevideo music [--preset ambient|pulse|documentary|bright]
onevideo assets search <q> [--provider nasa,wikimedia,openverse,pexels] | assets fetch [--only a,b] [--force]   # 含 generate：AI 生圖 / 生影片
onevideo depth [asset ids] [--step N]               # 深度圖 + 亮度網格：主體穿越、關鍵詞避讓、自動加底、字幕避讓
onevideo capture <url> --id x [--device phone|tablet|desktop] [--click sel] [--rects name=sel,…] [--full] [--dark]   # 真實介面截圖（自起無頭 Chrome）
onevideo screen <asset> [--at s] [--threshold 40]   # 找實拍裡黑屏的四角 → footage.screen 片段
onevideo stems                                     # 按 stem 分組匯出分軌 wav → out/publish/stems/
onevideo timeline | stills [--scene id] [--at 0.3,0.7] | studio
onevideo render [--draft] [--scenes a,b | --from s --to s] [--note …]   # 每次一個版本 → out/versions/vN
onevideo versions                                   # 渲染記錄：版本、範圍、時間軸雜湊、備註
onevideo handoff [--lock …] [--next …]              # 交接頁 → plan/handoff.md
onevideo lib list|search|recipe <name> --id x --set k=v   # 音效 / Lottie / 鏡頭配方
onevideo sheet [--fps 1] [--from s] [--to s] [--video v3] [--vs prev]   # 聯繫表 → out/qc/sheet-NN.jpg；--vs 新舊對比
onevideo look [--focus "字幕可讀性"] [--models a,b]   # 視覺模型看片 → out/qc/look.json
onevideo qc | publish [--stems] | build [--draft] | doctor | decide <category> <subject> --selected X

未全域安裝時，用 node <repo>/cli/onevideo.mjs … 呼叫。

參考

• 流水線定義：pipelines/*.json；視覺風格：styles/*.json
• 寫作：references/writing-zh.md · 讀音：references/tts-pronunciation.md
• 場景與動效：references/motion-rules.md（先讀）· references/scene-catalog.md
• 數據與授權：references/data-integrity.md · references/licensing.md
• 質檢：references/qc-thresholds.md
• 範例：examples/spacex-motion/（動效引擎示範，36s）· examples/spacex-ipo/（數據圖表版，85s）· examples/promo-demo/（promo 流水線：capture 截圖 + device 場景，20s）；onevideo init demo --example spacex-motion