縮圖產生器 是做什麼的？
代理工作流程 + 確定性渲染器，可適應任何頻道。此套件提供風格規則、佈局模板、字型、影格工具和渲染器；主機代理提供理解和判斷。
工作流程
- 影片簡介（主機理解，套件證據）：閱讀影片的標題、描述、章節/逐字稿和樣本影格。
scripts/video_brief.py --video V --transcript subs.srt --scenes --out brief.json會組合證據：逐字稿詞頻（純文字計數，不依賴模型）和透過 ffmpeg 取得的場景剪輯時間戳記。然後，主機會填寫簡介的main_question、show和avoid_implying欄位——縮圖必須誠實傳達的內容以及它絕對不能暗示的內容。套件本身無法理解影片內容；它需要一個能夠閱讀影片元數據、影格和文字的主機。候選影格：scripts/extract_frames.py VIDEO --out frames/（均勻抽樣）或--scenes（在最強烈的場景剪輯處的影格——內容發生變化的時刻，而非證明哪個時刻重要的證據）。 - 參考選擇（主機代理能力）：從建立者的私人參考庫中，挑選 2-3 個構圖適合此影片主題的參考，並記錄具體的模式（文字大小/位置、色彩對比、主體位置）。
scripts/analyze_references.py FOLDER [--labels sources.csv]會提供建立者自己本機庫資料夾的像素級統計資料（亮度、對比、暗色/彩色比例），以鞏固這些選擇；該庫永遠不會離開本機磁碟，也絕不會在此套件內分發。對於較大的庫，主機可以對資料夾進行一次視覺掃描，並將每個參考的主題/情緒/構圖記錄在私有的reference_tags.json中（架構見examples/example_reference_tags.json）；接著，scripts/match_references.py --tags reference_tags.json --topic ... --mood ...會根據標籤重疊來篩選候選項，供主機檢視。標籤檔案與圖像庫一起存放在 repo 外部。 - 收集缺少的輸入：縮圖文字（2-4 個詞，忠於影片）、一個強調詞、佈局、風格情緒（
styles.json中定義的五種之一）、語言（Hindi/English）以及選定的影格（一個真實的影片時刻，與主題相符，而不僅僅是最清晰的靜止畫面）。頻道設定檔（profiles.json）可以提供預設值；明確的選擇始終會覆蓋。如果仍有缺少的項目，請詢問建立者。 - 角色反應編輯和去背（可選；主機影像編輯能力）：當縮圖需要影片角色展現符合影片時刻的特定反應（震驚、喜悅、憤怒）時，主機可以使用影像編輯模型編輯選定的影格：保留角色的身份、插圖風格和背景；僅更改表情。對於去背外觀（主體從背景中分離出來並帶有輪廓，這是參考庫中的主要模式），請讓主機將角色放置在平坦的統一背景上（綠幕效果最佳）並執行
scripts/make_cutout.py shot.png --out subject.png——去背完全在本機運行；只有產生統一背景的畫面才需要主機的影像工具。使用--subject subject.png進行合成（stack-left/bottom-left：主體靠右，帶有彈出式輪廓和陰影，文字保持遠離主體）。此套件不包含任何影像模型——編輯使用主機環境提供的任何影像編輯能力，不假設有付費提供者或註冊。當不存在此類能力時，跳過此步驟並選擇一個現有表情已經合適的影格。規則：僅編輯來自建立者自己影片的插圖/頭像素材；切勿為了真實事件的宣稱而偽造真實人物的表情；每次編輯都記錄在運行清單中（--reaction-edit），以便建立者知道表情被編輯過。 - 不同的概念，而非色彩旋轉：對於每個影片，設計 2-3 個真正不同的概念——不同的鉤子、不同的影格/場景、不同的構圖——並在一次運行中渲染它們：
scripts/run_thumbnail.py --video V --concepts concepts.json --out set.jpg（JSON 中的每個條目都有自己的標題、影格、佈局、概念說明和可選的主體/reaction_edit；一個清單記錄整個集合）。--variants N仍然用於對相同文字進行風格/佈局旋轉，這對於真正的決策來說是一個較弱的選擇。 - 渲染 + 清單：
scripts/run_thumbnail.py --video V --title T --accent A [--profile P] [--style S] [--layout L] [--variants N] [--label K] [--lang hi] [--reaction-edit "被編輯的內容"] [--subject subject.png] [--brief brief.json] [--channel NAME] --frame F --frame-time SECONDS --concept "..." --refs ID --ref-notes "..." --out thumb.jpg會寫入最多 N 個變體和一個*.manifest.json運行記錄（輸入影片身份、設定檔、檢視的參考、概念、選定的影格、任何反應編輯、每個輸出）。使用--brief時，每個輸出都會獲得hook_evidence：與鉤子共享詞彙的逐字稿行，以及當鉤子做出逐字稿從未做出的絕對聲明（dead/khatam/over/...）時的警告——這是真實性審查的證據，而非真實性判決；一個鉤子可以共享詞彙但仍然進行誤導。使用--channel時，每個頻道的設計記憶（.thumbnail-history/，在 repo 外部）會在新增渲染將重複該頻道的近期模式時（相同風格系列或佈局連續出現 3 次，去背主體在最近 4 次中出現 3 次）發出警告——僅是警告，絕不封鎖，且刻意的系列風格是可以的；運行隨後被記錄。若要進行快速渲染而不產生清單，請直接使用scripts/make_thumbnail.py；--mobile-preview會增加一個 380px 寬的渲染，用於手機尺寸的可讀性檢查。 - 品質關卡，兩個層級：
- 自動（僅可測量）：
run_thumbnail.py已經在每個輸出上運行scripts/check_thumbnail.py，並將結果記錄在清單中（quality_checks）；警告/失敗會在運行時顯示。檢查項目：1280x720 尺寸、2MB YouTube 限制、380px 手機尺寸下的文字區域對比度，以及使用--subject去背景主體時的貼上去背主體亮度。主體檢查會讀取去背主體已知的放置位置——它不是人臉偵測器，也不會對背景影格內的人臉做出任何說明；基於影格的渲染仍然需要您的眼睛。您也可以獨立運行它：python3 scripts/check_thumbnail.py thumb.jpg --layout stack-left --subject subject.png（失敗時退出代碼為 1，因此它可以作為工作流程的閘道）。 - 語義（主機判斷，絕不保證）：審查像素無法顯示的內容：(1) 鉤子真實性——文字必須是影片實際提出的問題或它所支持的宣稱，絕不能是為了點擊而發明的絕對陳述（使用清單的
hook_evidence作為起始證據，然後進行判斷）；(2) 影像-主題匹配——影格必須屬於影片的主題（在科技解說鉤子後面放宗教或歷史繪畫是拒絕項）；(3) 風格-情緒契合——巨大、緊湊、煽情的文字適合戲劇性主題，較冷靜的解說影片使用較安靜的構圖可能更好；(4) 多樣性——不要在每個影片上都使用相同的佈局和相同的表情。然後打開圖像和手機預覽：強調詞是突出顯示的那個，不要與影格的主體重疊，編輯過的表情仍然看起來像同一個角色。
- 自動（僅可測量）：
- 核准：建立者在任何上傳之前核准。目標編輯：僅使用更改過的旗標重新執行
make_thumbnail.py --spec thumb.spec.json。
範圍——此套件能做什麼和不能做什麼
- 它能夠：提取/評分影片靜止畫面、應用風格系統（字型、顏色、4 種佈局）、渲染 Hindi 或 English 的變體、分析本機參考資料夾以獲得有根據的風格選擇、為每個縮圖保留可編輯的規格和運行清單。
- 它不能：理解影片語義、自行選擇鉤子或概念、自行編輯圖像（反應編輯使用主機自己的影像編輯能力；套件僅記錄它們）、驗證訊息的真實性，或上傳任何內容。這些是主機代理/建立者的判斷和主機能力，作為聲明的輸入提供。CTR 學習需要頻道分析存取權限和受控數據——不屬於此套件的一部分。
佈局和風格
四種佈局（bottom-left、stack-left、center-big、split），從包含 97 張圖像的參考庫中的主導模式學習而來：帶有高亮條的堆疊大字、置中目標標題、之前/之後分割，以及在漸層影格上的左下角區塊。styles.json 中有五種顏色組合（documentary、finance、tech、podcast、boldred）：一種背景、一種文字顏色、一種強調色。規則：2-4 個詞，一個強調詞（高亮顯示），一個字型家族。
需求
支援 Pillow 和 numpy 的 Python 3；用於影格提取和影片元數據的 ffmpeg 需在 PATH 中。渲染時無需網路。
參考庫
設計模式從建立者的私人參考庫（97 張縮圖，涵蓋反應臉、粗體排版、播客、遊戲、旅遊和其他類別）學習而來。該庫保持私有：切勿將其圖像包含在此套件或任何發行版中。analyze_references.py 僅讀取建立者指定的本機資料夾。