v0.16.0／架構 6.2：長片／Shorts／Reels 共用高效率模板編譯器、證據式電影工藝與唯一發布中樞； 運鏡、剪輯、聲音、調色、特效與轉場沒有鏡頭證據時會自動退回乾淨切鏡。33 圖設計 DNA、Tracking、Quality-95 審片、發佈包、成效學習與安全自動更新仍在同一套公開版。 執行
python src/system_health.py --quick可驗證乾淨安裝；個人媒體與成效資料不會進 release。
一套框架式的 YouTube / 短影音自動化工具 + 方法論模板。 給你純程式 ffmpeg pipeline + CapCut 自動化的程式碼，加上一份「問卷」—— 你回答關於你自己頻道的問題，它就變成屬於你的系統。
⚠️ 不含任何人的私人數據 —— 後台讀數（自己的與別人的）／個人檔案一律不進 repo（profiles/、config.py是 gitignored 本機檔）。 兩類具名例外，兩類都是公開資訊不是私人數據：① LICENSE 與各 README 的作者署名； ②knowledge/引用第三方公開創作者／頻道時會直接寫名字（例如演算法檔引用的公開戰術、teaching-niche-playbook.md的參考頻道列），規矩是 citation-first：沒有可點的出處連結就不給數字。 voice 詞表、KPI 門檻與社群欄位要嘛是空白模板（<fill in>/______/ 產出檔的{你的…}佔位字樣），要嘛標示為「範例值」，你填你的。 反過來說：knowledge/裡的方法論是原作者的實戰結論，那是刻意開源的部分 —— 是「怎麼想」，不是「他的數字」。
- 用 Mac / Linux？ → Path 1 Programmatic（純程式，跨平台，不碰 CapCut）
- 要 CapCut 的特效 / 花字 / 雲端模板？ → Path 2 CapCut-assisted（Windows 優先；版本敏感，先看 TROUBLESHOOTING 的版本相容矩陣）
- 只想全自動、不想開任何 GUI？ → Path 1 Programmatic
想先看它真的會動？examples/ 裡有自包含、可直接跑的 demo —— 用 ffmpeg 合成測試素材，不需要任何真實影片或 CapCut：
python examples/01_vertical_short.py # 合成素材 → 完整 1080x1920 直式 Short
python examples/02_caption_broll_match.py # 零設定：b-roll 用內容命名就自動對位字幕
python examples/04_shorts_gate.py # 直式 Shorts 閘門：壞剪法被擋 → 修好放行 → 換你的門檻放行 → 換平台也放行
python examples/05_interview_plan.py # 訪談來賓閘門：沒來源的數據在「錄影之前」就被擋下
python examples/06_teardown.py # 競品拆解數學：中位數騙人、標準差不騙人、換句÷剪點是拍攝決策需求：Python 3.9+。04 / 05 / 06 連 ffmpeg 都不用（純 Python、零 pip install、零素材）；01 需要
ffmpeg/ffprobe，03 另需 Pillow + numpy。細節見 examples/README.md。
市面上的「creator 系統」要嘛賣你某個人的設定（抄了對你沒用、還可能誤導），
要嘛太通用沒有方法論。這個 kit 給你骨架（經實戰的結構），
SETUP.md 一區一區問你問題，用你的答案填滿它 —— 這樣它才真的是你的系統。
這一版沒有拿掉任何功能，拿掉的是借來的把握。四個地方犯的是同一種錯： 一個沒人量過的數字，掛上權威標籤，比沒有數字更糟 —— 因為你會信它。
- Shorts 片長帶改平台感知 —— 死區是在 YT Shorts 上量出來的，套到 IG/FB 會擋掉正常的剪法。
改用
spec["platform"]選帶（rules=仍逐鍵優先）；平台名打錯是擋下的失敗，不是靜默 fallback - 腳本 gate 的四層詞表改成出貨即空 —— 行話分級只能從你自己的逐字稿審計出來；
照抄別人的白名單 = 用別人的觀眾檢查你的稿。空表不擋你（只回一條 warn），
load_vocab()載你自己的 - 演算法線補上合規層＋「沒出處就不引用」 ——
knowledge/ai-content-compliance.md（R26-R38 ＋ 發布前 10 項 checklist） ＋ 53 條分級法源；查無官方出處的門檻數字就地標記，不再與有出處的並排 - 新工具
src/teardown.py—— 一個指令把競品直式短片拆成可比較的數字（刀速／刀距分布／換句速率／換句÷剪點／LUFS）； OCR 是選配，沒裝只跳過字幕抽取、退出碼仍是 0
完整清單（含兩個靜默失敗修復）→ CHANGELOG。
以前這個 kit 只回答一件事：「怎麼把一支長片做好。」現在是三條生產線 —— 而且刻意長成同一個形狀：知識層（為什麼這樣做）→ 機械閘門（不靠任何人記得）→ 一鍵驅動（幾個指令跑完）。 學會一條就等於學會三條；要加第四條（Podcast？教程系列？）也照這個骨架接。
| 生產線 | 知識層（為什麼） | 機械閘門（擋在前面） | 一鍵驅動 |
|---|---|---|---|
| 教學長片 | knowledge/premium-motion-fx.md＋knowledge/meta-lessons.md＋腳本三支柱 script-style-framework.md／script-retention-craft.md |
plan_gate → script_gate（觀眾語言 fail／節奏 warn）→ delivery_qa(profile='teaching_longform') |
src/longform_maker/ 各模組 |
| 直式 Shorts | knowledge/shorts-mastery-2026.md＋knowledge/vertical-teardown-method.md（怎麼量競品） |
src/longform_maker/shorts_gate.py 九條結構／字幕規則擋出片 ＋ S-O 換句節奏 warn；片長帶平台感知（YT 的死區不套用到 IG/FB），純 Python |
src/shorts_autopilot.py scan → 看畫面填字 → build（含自動 QA 驗證圖） |
| 線上訪談 | knowledge/interview-show-playbook.md |
src/interview_gate.py I-A~I-E：沒來源的來賓數據不上鏡 |
src/interview_autopilot.py invite → plan（產 7 件套）→ build |
- 閘門共用外殼
src/longform_maker/gate_core.py—— 回傳結構 /assert訊息 / self-test 印法一致， 你自己加的閘門 import 三個函式就跟內建的行為一模一樣（判定規則各自留在自己的檔，不集中才不會互相污染） - 經營層（v0.9 起）：
src/channel_tracker.pyD2/D7/D28 快照排程＋待辦、src/system_health.py一鍵 GREEN/RED 健檢 → 接線指南knowledge/ops-automation.md；爆款定義框架knowledge/viral-playbook-framework.md ⚠️ 兩道閘門裡的門檻數字都是範例校準值，不是宇宙常數 —— Shorts 片長帶 / 首刀秒數 / 非白字上限請用你自己的 3-5 支片重算 （做法見 SETUP.md 的「Shorts 規則校準」）
這個 kit 有兩條同等地位的路，不是「主力 vs 次要」：
跟上面的「三條生產線」是不同的軸：生產線＝你在做哪種片（長片 / Shorts / 訪談）； path＝你用什麼方式做（純程式 vs CapCut）。三條生產線都可以走 Path 1。
| 路徑 | 模組 | 是什麼 | 平台 |
|---|---|---|---|
| ⭐ Path 1 — Programmatic（推薦採用者預設） | src/longform_maker/ |
教學長片模組 —— fx_lib premium 動態引擎（亞像素 Ken Burns / 雙層 bloom / light sweep / easing / 合成 SFX）、word_captions 字級時間字幕（M105）、screen_clean 螢幕錄影機械化清理（M104）。參數真值 → knowledge/premium-motion-fx.md |
Win / Mac / Linux |
| ⭐ Path 1 — Programmatic | src/silent_vlog_maker/ |
純 ffmpeg pipeline —— 直式 Shorts（多色字幕 / BGM 高光起點 / 正規化）、靜音 vlog、素材清理 | Win / Mac / Linux |
| ⭐ Path 1 — Programmatic（v0.10） | src/shorts_autopilot.py + src/longform_maker/shorts_gate.py |
直式 Shorts 生產線 —— scan 正規化 9:16 + 抽接觸表 + 產 _plan.py 骨架 → 你（或 AI）看畫面填字 → build 過閘門、成片、自動 QA 出驗證圖。閘門本身純 Python（連 ffmpeg 都不用）。v0.11：片長帶改平台感知（spec["platform"]；rules= 仍優先），新增 S-O 換句節奏 warn |
Win / Mac / Linux |
| ⭐ Path 1 — Programmatic（v0.10） | src/interview_autopilot.py + src/interview_gate.py + templates/interview/ |
線上訪談生產線 —— 來賓資訊 → 邀約訊息 / 主持台本 / 訪綱 / 準備包 / 授權書 / 錄製 checklist / 發布套件 / Shorts 切條，全部從模板 render；來賓數據沒來源就擋在錄製前 | Win / Mac / Linux |
| ⭐ Path 1 — Programmatic（v0.11） | src/longform_maker/script_gate.py ＋ templates/style_profile.template.md ＋ templates/audience_vocab.example.json |
腳本線（錄音前擋稿） —— gate(text)：觀眾語言 fail 級／留存節奏 warn 級。觀眾語言四層詞表隨 kit 出貨是空的（只能從你自己的逐字稿審計出來），空表時不掃詞、只回一條 lang.no_vocab warn，load_vocab("你的.json") 載你自己的。知識層 → script-style-framework.md（語氣）＋script-retention-craft.md（觀眾語言＋節奏） |
Win / Mac / Linux |
| ⭐ Path 1 — Programmatic（v0.11） | src/teardown.py |
競品拆解 —— 一個指令量出刀速／刀距中位＋標準差／換句速率／換句÷剪點節奏判讀／LUFS。統計那半邊純 Python；OCR（燒錄字幕抽逐字稿）是選配，缺套件只降級不崩潰。方法論＋量測坑 → knowledge/vertical-teardown-method.md |
Win / Mac / Linux |
| ⭐ Path 1 — Programmatic（v0.10） | src/longform_maker/gate_core.py、src/av_util.py |
共用底座 —— 所有閘門的統一外殼（report / assert / self-test）＋ autopilot 共用機械動作（subprocess / ffprobe 時長 / 抽幀 / 接觸表） | Win / Mac / Linux |
| ⭐ Path 1 — Programmatic | src/capcut_helpers/ 的 QA gates |
交付前機械化 QA（delivery_qa：頻閃·死空檔·caption-sync·全幀掃描 M91-M95 / broll_audit 占比 / caption_broll_matcher 對位）—— 純 ffmpeg/Python，不需要 CapCut，兩條 path 的成品都該過這關 |
Win / Mac / Linux |
| Path 2 — CapCut-assisted（作者本人主用） | src/capcut_helpers/ 其餘 |
CapCut Desktop 自動化 —— 草稿 JSON 直改（draft I/O / 4-level 靜音 / 花字 / AI 字幕校正）+ AI 助手 + Computer Use 操作 CapCut 視窗（套模板 / 匯出）。版本敏感 → TROUBLESHOOTING | Windows-first |
| 共用 | knowledge/ |
影片製作知識庫 —— M1-M111 避坑大全 + 演算法 + SOP + 剪輯心法（索引 → knowledge/README.md） |
— |
| 共用（v0.11） | knowledge/ai-content-compliance.md＋-sources.md |
AI 內容合規 —— R26-R38 十三條規則 ＋ 發布前 10 項 checklist（擬真揭露／原創貢獻／防模板化／深偽三不／語音克隆邊界／只引用有官方出處的數字）＋ 53 條分級法源（[official]／[reported]／[speculative]）。 |
— |
| 共用 | examples/ |
自包含可跑 demo —— ffmpeg 合成素材，60 秒看 pipeline 真的動（不用 CapCut/真素材） | — |
| 共用 | ⭐ SETUP.md |
從這開始 —— 回答問題讓系統變成你的 | — |
| 共用 | templates/ |
voice / 品牌 / 演算法 / 社群 的空白填寫模板；v0.10 加 show_profile（節目設定）與 templates/interview/ 11 份訪談交付模板 —— 改話術改模板，不要改程式 |
— |
| 共用 | config.example.py |
路徑設定範例（複製成 config.py 填你的，範例不含任何帳號名） |
— |
誠實聲明：原作者的私人流程以 Path 2（CapCut） 為主 —— 但那是因為他的素材、模板、肌肉記憶都在 CapCut 上。 開源採用者多數應該從 Path 1 開始：跨平台、無 CapCut 依賴、不吃 CapCut 版本變動、全程可重現。 需要 CapCut 的花字/雲端模板時再上 Path 2。
| 模組 | Windows | macOS |
|---|---|---|
Programmatic（longform_maker / silent_vlog_maker / QA gates） |
✅ | ✅（路徑/字型由 src/platform_compat.py 探測；Linux 同） |
CapCut 草稿 JSON 直改（capcut_helpers draft I/O） |
✅ 本機親測 | CAPCUT_USER_DATA env override + detect_draft_format()），自動化未在 Mac 實測 |
| Computer Use GUI 自動化（套模板 / 匯出） | ✅ | ❌（CapCut Mac 無 AppleScript dictionary；見 TROUBLESHOOTING 的 Mac 節） |
- 讀
SETUP.md→ 照問題把templates/*.template.md填成profiles/*.md（或把整個 repo 丟給 Claude / ChatGPT，說「照 SETUP.md 問我問題，幫我生成 profiles/」） cp config.example.py config.py→ 填你的素材 / 匯出路徑（走 Path 2 才需要 CapCut 路徑）- 選路：Path 1 裝好 Python + ffmpeg 就能跑；Path 2 額外裝 CapCut Desktop + 開啟 AI 助手的 Computer Use（見下方需求）
- 開始用
src/的工具
這個 repo 現在把完整可執行核心＋公開 Codex Skill＋更新／回滾系統當作同一個產品發布。 不論你是第一次安裝，或還停在沒有 updater 的舊版，都從同一支 bootstrap 開始：
舊版資料夾沒有這支程式時，只要先下載這一個公開檔（之後的相容版才可自動迭代）：
Invoke-WebRequest https://github.com/Hao0321/video-autopilot-kit/releases/latest/download/install_or_upgrade.py -OutFile install_or_upgrade.py
python install_or_upgrade.py --install-root . --check
python install_or_upgrade.py --install-root . --apply --install-skillmacOS／Linux 可用：
curl -fLO https://github.com/Hao0321/video-autopilot-kit/releases/latest/download/install_or_upgrade.py
python3 install_or_upgrade.py --install-root . --check
python3 install_or_upgrade.py --install-root . --apply --install-skill第一次採用舊資料夾必須明確執行 --apply；不能用 --auto 靜默接管。採用完成並建立管理檔清單後，
未來相容、帶 migration 宣告且本機管理檔未改動的版本才可自動升級。
python install_or_upgrade.py --install-root <你的資料夾> --check
python install_or_upgrade.py --install-root <你的資料夾> --apply --install-skill- 新版會比較 semver，驗證 release zip SHA-256 與逐檔 SHA-256 後才套用。
shorts_autopilot.py生產入口每 24 小時最多自動檢查一次；只有相容版本能自動升級，更新後會重新啟動一次再執行。也可手動跑python src/release_manager.py auto。publish_hub.py保持純交付服務，避免 updater／workspace migrator 形成反向循環。- v0.19 起，安裝／相容升級後會非破壞地補齊
videos/_PUBLISH_HUB與根目錄發布入口，並把既有*/_out/current.mp4以 hardlink 註冊為發布包；不刪除、不覆寫影片、設定或未知檔案。 config.py、profiles/、projects/、data/、videos/、assets/、後台成效與本機 outcome 永遠留在你的電腦，不進公開包、不被更新器覆蓋。- 未知自訂檔永不刪；已修改的官方管理檔在自動模式會停在
CONFIRM_REQUIRED。 - 每次覆蓋前建立
.video-autopilot/backups/<transaction>/；需要時執行python src/release_manager.py rollback。 - 重大／不相容版本不會靜默升級，必須由使用者確認。
完整契約見 codex-skill/video-autopilot/references/open-source-release-and-upgrade.md。
開發者發布前使用 python src/release_manager.py build --base-url <本版 GitHub release URL>，會產生
固定 zip、.sha256 與 release-channel.json 三件 release assets。
安全邊界：自動迭代的是相容而且驗證過的公開核心，不是把任何人的私人影片、數據、設定或 授權不明素材同步給別人。完整開源與保護使用者資料必須同時成立。 套件邊界與「完整」定義見
docs/OPEN_SOURCE_SUITE.md。
Path 1 — Programmatic（推薦採用者預設；Win / Mac / Linux）
- Python 3.9+
ffmpeg/ffprobe（在 PATH 上）- 不需要 CapCut、不需要 Computer Use —— 整條 pipeline 都是可重現的程式碼
- Mac/Linux：系統路徑與 CJK 字型由
src/platform_compat.py自動探測（不要 hardcode 系統字型路徑） - 唯一需要 pip 套件的是
src/shorts_autopilot.py（一鍵直式 Shorts 流程）：Pillow + numpy —— 用來分析畫面品質、拼接觸表、抽 QA 驗證圖。 規則閘門src/longform_maker/shorts_gate.py這個檔案本身是純 Python（連 ffmpeg 都不用）， 只想用閘門就不必裝任何東西 →python examples/04_shorts_gate.py。⚠️ 但要平面 import（把src/longform_maker/加進sys.path再from shorts_gate import …， 範例 04 就是這樣寫的）；走from longform_maker.shorts_gate import …會經過套件__init__， 那裡會載入fx_lib（需要 numpy + Pillow）。或直接把shorts_gate.py+gate_core.py複製走。 - 訪談生產線（
src/interview_autopilot.py/src/interview_gate.py）的訪前企劃全程純 Python —— 產 7 件套不需要 ffmpeg 也不需要 pip 套件；ffmpeg 只有錄完build才用得到 →python examples/05_interview_plan.py - 競品拆解
src/teardown.py有兩個選配套件（其餘功能都不需要它們）：rapidocr-onnxruntime（本機實測裝完約 25MB 量級，不拉 torch/paddle）＋opencc-python-reimplemented（簡轉繁）- 不裝會少什麼：只少「把對方燒錄字幕自動抽成逐字稿」這一段。刀速／刀距分布／ 換句速率／換句÷剪點判讀／LUFS 全部照跑，退出碼仍是 0，工具會印出安裝指令。
- 只裝 OCR 沒裝 opencc → 逐字稿照抽，只是不做簡轉繁（會混雜簡體字）。
- 統計那一半（
rhythm_stats/pace_profile）是純 Python，連 ffmpeg 都不用 →python examples/06_teardown.py ⚠️ OCR 只讀得動燒錄字幕（0.92-1.00），實景招牌準確率 ≈ 0，而且讀錯時信心值仍有 0.85-0.92 —— 門檻擋不掉。 所以它只能拿來讀別人的片， 不可以拿去自動生成你自己影片的品名／價格字幕 → 邊界說明見knowledge/vertical-teardown-method.md§2-8
Path 2 — CapCut-assisted（作者本人主用；Windows-first、版本敏感）
- CapCut Desktop 國際版（有 Pro 更好）—— 剪輯 / 套字幕 / 套模板在這。
⚠️ 版本敏感：草稿 JSON 直改對版本有相容矩陣（剪映 CN 6.0+ 已加密不可直改）—— 動手前先讀 TROUBLESHOOTING，並用detect_draft_format()驗明文 - AI 助手 + Computer Use（Claude Desktop / Claude Code 等）—— GUI 自動化（套雲端模板 / 匯出）必需；Mac 上沒有可用的等效機制（見 TROUBLESHOOTING 的 Mac 節）
- Python 3.9+ 與
ffmpeg/ffprobe—— 匯出後的後製：BGM loop / 修剪到人聲尾 / player-safe 重編
(選用) AI 助手（Claude / ChatGPT）也能照 SETUP.md 自動把你的答案生成 profiles。
一套創作系統最值錢的是結構與方法論，不是某個人的私人數字。 所以這個 repo 給你骨架，你用自己的血肉填滿。
MIT — 保留標註即可自由使用 / 修改 / 商用。
Hao0321 Studio — 從一套實戰的個人創作系統抽出來的開源框架。