缩略图生成器
智能体工作流 + 确定性渲染器，可适配任何频道。该包提供样式规则、布局模板、字体、帧工具和渲染器；宿主智能体提供理解和判断。
工作流
- 视频简报（宿主理解，包证据）：读取视频的标题、描述、章节/字幕和示例帧。
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 ...通过标签重叠来筛选候选，供宿主查看。标签文件与库一同保留在仓库之外，就像图片一样。 - 收集缺失输入：缩略图文本（2-4 个单词，忠于视频）、一个重音词、布局、样式情绪（
styles.json中五种之一）、语言（印地语/英语）和选定的帧（视频中与主题匹配的真实时刻，而非最锐利的静止帧）。频道配置文件（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 中的每个条目都有自己的标题、帧、布局、概念说明和可选的主体/反应编辑；一个清单记录整个集合）。--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 "what was edited"] [--subject subject.png] [--brief brief.json] [--channel NAME] --frame F --frame-time SECONDS --concept "..." --refs IDs --ref-notes "..." --out thumb.jpg写入最多 N 个变体和一个*.manifest.json运行记录（输入视频身份、配置文件、检查过的参考、概念、选定的帧、任何反应编辑、每个输出）。使用--brief时，每个输出获得hook_evidence：共享钩子词的字幕行，加上当钩子做出字幕从未做出的绝对声明（dead/khatam/over/...）时的警告——这是真实性检查的证据，而非真实性判决；一个钩子可以共享词但仍可能歪曲事实。使用--channel时，每个频道的设计记忆（.thumbnail-history/，在仓库之外）会在新渲染重复频道近期模式（相同样式家族或布局连续 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（失败时 exit 1，因此可用来门控工作流）。 - 语义（宿主判断，从不保证）：检查像素无法检查的内容：(1) 钩子真实性——文本必须是视频实际提出的问题或其支持的声明，绝不能是为了点击捏造的绝对化内容（使用清单中的
hook_evidence作为起始证据，然后判断）；(2) 图像-主题匹配——帧必须属于视频的主题（技术解说钩子背后的宗教或历史绘画应被拒绝）；(3) 样式-情绪匹配——巨大紧凑的 hype 文字适合戏剧性主题，更冷静的解释类内容可能更适合安静构图；(4) 多样性——不是每个视频都相同的布局加相同表情。然后打开图像和移动预览：重音词是突出显示的词，不与帧的主体重叠，编辑后的表情看起来仍像同一个角色。
- 自动（仅可度量）：
- 审批：创作者在任何上传之前批准。定向编辑：使用仅更改的标记重新运行
make_thumbnail.py --spec thumb.spec.json。
范围——此包能做什么和不能做什么
- 它能做：提取/评分视频静止帧，应用样式系统（字体、颜色、4 种布局），以印地语或英语渲染变体，分析本地参考文件夹以获得有根据的样式选择，为每个缩略图保留可编辑的 spec 和运行清单。
- 它不能做：语义上理解视频，自行选择钩子或概念，自行编辑图像（反应编辑使用宿主自己的图像编辑能力；包仅记录它们），验证信息的诚实性，或上传任何内容。这些是宿主智能体/创作者判断和宿主能力，作为声明过的输入提供。CTR 学习需要频道分析访问权限和控制数据——不属于此包。
布局和样式
四种布局（bottom-left、stack-left、center-big、split），从 97 张参考库的主要模式中学习而来：堆叠的大字带高亮条、居中的目的地标题、前后分割、以及渐变帧上的左下角块。styles.json 中的五种颜色组合（纪录片、金融、技术、播客、粗体红色）：一种背景色、一种文字颜色、一个重音色。规则：2-4 个词，一个重音词（高亮），一种字体家族。
要求
Python 3，安装 Pillow 和 numpy；帧提取和视频元数据需要 ffmpeg 在 PATH 中。渲染时无需网络。
参考库
设计模式从创作者的私人参考库（97 张缩略图，涵盖反应脸、粗体排版、播客、游戏、旅行等类别）中学习。参考库保持私有：绝不将其图像包含在此包或任何分发中。analyze_references.py 仅读取创作者指向的本地文件夹。