智能口播自动剪辑

把用户的素材和自然语言要求转换为可审查、可反复修改的项目专属 HTML 样片。用户明确表示满意并确认生成视频后，才渲染 MP4 成片。

宿主兼容与提速入口

• 在新的 Codex、WorkBuddy 或其他本地宿主中，先运行 scripts/portable_runner.py doctor <项目目录> --require html。只报告依赖与能力，不自动安装软件、不上传素材、不修改代理。
• 若报告缺少共享依赖，先运行 portable_runner.py bootstrap <工作区>/.auto-talking-head-runtime 查看安装计划；只有用户明确同意后才添加 --install。安装限制在该专用目录，包含锁定的 Node 视频依赖、Remotion 无头浏览器和带 Pillow/PyYAML 的独立 Python 环境，不改系统 PATH、不改 WorkBuddy 自带 Python。
• 所有脚本必须从自身位置解析同目录资源，从项目目录解析素材；不得依赖启动时的当前目录、开发者用户名或固定盘符。
• 首次新素材才执行媒体分析、转写、代理和封面底图处理；后续反馈默认运行 portable_runner.py refresh <项目目录> --times <修改时间点>，复用转写、代理、封面和未变化的音频素材。
• 方向审查只截图本次受影响的少量节点；用户确认方向后再运行 --full，最终确认后才做全片解码和完整质检。
• 最终渲染先运行 plan_render.py：普通无重点字幕进入轻量 ASS，重点词、分段字幕、信息卡片和复杂动画进入可缓存视觉窗口。优先用 export_timeline_master.py 一次完成原片剪段、字幕/图形叠加、音频和最终编码，避免先编码底片再二次编码。
• 分享包自带 65 个去重音效：57 个已试听的个人实录音效，加 8 个生成音效家族的单一代表。不包含同一音效的多音调、多速度或多强度副本；不自动生成或启用音乐。
• NVENC 只有通过短小的真实硬件编码测试才可启用；失败时自动回退 x264，不能只因为 FFmpeg 列出了 h264_nvenc 就判定可用。
• 需要在 WorkBuddy 安装或迁移时读取 references/performance-and-workbuddy.md。

固定交付流程

1. 用户说“剪一下、预剪、样片、看看效果”时，进入 html-sample；分析素材、建立时间线并生成 HTML 样片，不先生成 MP4。
2. HTML 必须自动加载本项目的视频代理或源视频，并按真实时间预演字幕动画、重点词、B-roll、信息卡片/图形、音乐和音效；同页展示已经实际生成的三套 3:4 封面 PNG。禁止复制通用工作台、让用户再次选择视频，或用黑屏、静态字幕、JSON、封面占位图和功能说明冒充样片。
3. 启动本地 HTTP 服务，用浏览器检查源画面真实可见，并在代表时间点截图；主代理亲自检查黑屏、遮挡、越界、图文重叠和封面构图，同时实际试听声音。
4. 用户不满意时，只修改受影响的时间段、视觉或声音节点，刷新同一工程的 HTML 样片；保留已经确认的部分。
5. 只有用户明确说“满意、确认生成视频、按这个导出成片”等同意话语后，才能把 approval.finalVideoConfirmed 设为 true 并进入 final-video。
6. 最终视频默认保持原片显示方向、有效分辨率和帧率；代理仅供 HTML 流畅预览，不能充当成片。
7. 若用户另要 MP4 审看片，按真实来源帧率生成并核验运动连续性；禁止把低帧率截图复制成标称高帧率视频。它仍是审看片，不代表高清成片管线已通过。

剪辑硬规则

• 不机械删除停顿，不剪断词、数字、意群或完整句。一镜到底优先保持动作和空间连续，分段素材优先利用真实拍摄边界。
• 短气口默认保留；较长停顿只能在完整意群结束且动作、镜头和环境声连续时收紧，并保留自然气口。阈值只用于找候选，不直接决定切点。
• 字幕、重点词、B-roll、图形、音乐和音效都必须落实到项目时间线。若用户排除某项或素材确实不适合，在 exclusions 中写明具体原因。
• 同屏原则上只有一个主视觉，不遮脸、不盖住关键环境，不用功能轮播代替语义选择。
• 多项卡片按阅读顺序递进；字幕在实际浏览器画面中最多两行，不以预设字符数或 JSON 换行数代替像素排版检查。通常按语义用单行短句，并从已有的上浮、聚焦、遮罩、弹入、错位、覆盖、逐字、翻转等动作中选与内容相符的一种，不逐句轮播。只有短时间口播信息密集、确实需要同屏两行时，才用“问题折叠／答案进入”或“左右异向”等两段接力：后段开始时前段向左上轻移，只降低普通字透明度而不改颜色，已强调的重点词保持 100% 不透明；新段落在中右下。同屏只保留当前段和紧邻前段。重点字下划线必须使用与重点字相近的色相。有明确开场冲突时保留 V8.1 的两行开场标题层，不与同一句底部字幕重复叠加。
• 人声始终优先；音效按动作和语义触发，种类有区别、频率克制，并通过试听确认。
• 未确认最终生成时，不渲染或交付 MP4 成片，不发布、不上传、不覆盖原片、不修改网络或代理设置。
• 原项目中的工作台可以保留，但默认流程不得打开、复制或展示它。只有用户当前明确要求“打开工作台、时间线编辑器、可视化编辑页面”时才进入该模式；HTML 样片本身不是工作台。

封面随样片生成

生成 HTML 前先确定标题来源与画面来源，并完成真实 1200×1600 PNG 封面；不能把“以后会生成”或纯图层框当作封面。

• 用户未提供“标题”时，不把普通需求说明误当成必须逐字上封面的文案；标题必须来自完整内容的核心命题，不能只截取开场寒暄或孤立刺激词。
• 封面使用真人讲解者时优先保留视频原帧像素，不重绘脸。人物在前、标题在中、背景与局部渐变在后；环境仍需可见，不整幅压黑。
• 三版候选必须在构图、主体比例、标题拓扑或视觉气质上有实质差异，不能只换颜色。每版只保留一个主命题、一个主视觉和一条阅读路径。房产题材可从本包 scripts/render_real_estate_cover.py 的 A–G 模板中按素材选三种不同版式；非房产继续使用 compose_source_cover.py。
• 素材有人出镜时，三版中至少一版必须保留“人物＋真实环境同框”：人物身份和环境证据都清楚，不能为了突出人物或标题牺牲景观与空间。
• 三版 PNG 与各自的背景、人物、标题、底板、标签等图层参数都写入当前项目；样片阶段只供审看，不自动选中、保存到成品目录或发布。
• 新项目只使用本次视频、图片、文字与用户明确要求沿用的抽象风格，不带入旧房源、旧人物、旧标题、旧数字或旧选帧。

执行顺序

1. 运行 scripts/portable_runner.py doctor <项目目录> --require html；通过后用 scaffold_project.py 建立独立项目，运行 media_preflight.py 记录原片规格与哈希，并用带缓存的 make_proxy.py 生成项目内预览代理。
2. 转写并校正数字、否定词、地名、房源参数和专有名词；判断一镜到底、分段或混合拍摄。
3. 建立 state/project.json，写入真实片段、字幕、重点词、B-roll、图形、音乐、音效，以及封面的输入路由、标题依据、选帧依据、三套图层方案与真实 PNG 路径；随后运行 portable_runner.py audio-plan-adaptive <项目目录>/state/project.json，从内置 65 个去重音效中按语义克制选用，不自动启用音乐。
4. 运行 scripts/validate_html_project.py --phase plan；通过后运行 scripts/make_html_sample.py。
5. 首次完整审查运行 check_html_sample.py；后续修改优先用 fast_refresh.py --times ... 只检查受影响节点。检查并试听后补齐 qa，再运行 --phase preview。
6. 启动 scripts/start_preview_server.py，把项目专属 HTTP 地址和封面预览交给用户。
7. 收到修改意见后更新同一状态文件和页面；不得把“请修改”误判为成片授权。
8. 收到明确确认后，运行 plan_render.py、make_caption_ass.py 和 render_visual_windows.py：普通短字幕走 ASS；重点词、自动拆分的长字幕、显式分段字幕和卡片只渲染各自的透明缓存窗。若时间线含音效，先用 build_audio_master.py 合成人声优先的音频母带，再把窗口清单与母带交给 export_timeline_master.py --confirmed --defer-full-qa 一次编码，最后立即运行 qa_video.py 完整质检。旧 export_master.py 仅作为已有预剪底片的兼容路径。

按需读取

• 语义剪辑、停顿、B-roll、声音和审片循环：读取 references/editing-workflow.md。
• 字幕、重点词、信息卡片和图形动画：读取 references/visual-system.md。
• 内置音效、自动规划和音频母带：读取 references/audio-system.md。
• HTML 样片状态与确认门控：读取 references/html-first-contract.md。
• 3:4 封面：先读取 references/cover-input-routing.md 判断四种输入组合，再读取 references/cover-system.md 完成设计与三版输出。房产题材另读 references/cover-template-integration.md。
• 封面含真实讲解者时读取 references/cover-identity-safe-layout.md；房产内容再读取 references/cover-real-estate.md。
• 代理、HTML 预览、最终渲染和质检：读取 references/quality-and-export.md。
• 安装 ZIP 和推荐调用方式：读取 references/share-and-use.md。
• 提速、缓存、通用本地宿主和 WorkBuddy 验收：读取 references/performance-and-workbuddy.md。

可复用脚本

• scripts/scaffold_project.py：创建 HTML 先审项目目录和状态文件，不创建工作台。
• scripts/media_preflight.py：检查媒体规格、方向、帧率和音轨。
• scripts/make_proxy.py：生成仅供 HTML 审片的代理视频。
• scripts/validate_captions.py：检查字幕时间、重叠和过长句。
• scripts/validate_html_project.py：阻止空壳 HTML 或未授权视频导出通过。
• scripts/make_html_sample.py：生成自动加载素材和时间线包装的项目专属 HTML 样片。
• scripts/check_html_sample.py：通过本地 HTTP 和浏览器检查源画面，并在多个时间点截图。
• scripts/extract_cover_frames.py：按语义时间点或全片粗采样抽取无 UI 的候选源帧。
• scripts/compose_source_cover.py：使用用户图片或视频原帧确定性生成 1200×1600 封面预览，保留真人原像素。
• scripts/normalize_cover.py：把生成式或外部图像规范化为精确 1200×1600 PNG。
• scripts/check_cover_previews.py：校验三套封面尺寸并生成联系表，供人工检查文字、遮挡与构图差异。
• scripts/render_real_estate_cover.py：从本次素材原帧用 A–G 响应式版式生成房产封面；只复用封面技能包的规则与渲染代码，不携带其中的示例人物、房源或图片。
• scripts/start_preview_server.py：启动项目专属 HTML 样片地址；不是工作台服务器。
• scripts/export_master.py：确认后将高清视觉层合成到原片。
• scripts/qa_video.py：对最终 MP4 做完整解码、黑帧、音轨和代表帧检查。
• scripts/runtime_preflight.py：检测 Python、Pillow、FFmpeg/FFprobe、页面检查浏览器、Remotion 无头浏览器、Node、Remotion 和真实 NVENC 能力。
• scripts/bootstrap_runtime.py：先展示依赖计划，获得明确授权后才在专用目录安装共享 Node 视频运行时、无头浏览器和隔离 Python/Pillow 环境。
• scripts/portable_runner.py：不依赖当前目录的统一入口，供 Codex/WorkBuddy 调用。
• scripts/fast_refresh.py：复用现有素材，只刷新 HTML 并检查受影响时间点。
• scripts/plan_render.py：输出阶段哈希、可复用项、普通字幕和复杂动画窗口。
• scripts/make_caption_ass.py：只为普通无重点字幕生成轻量 ASS，避免整段 Remotion 渲染。
• scripts/render_visual_windows.py：用专用 Remotion 无头浏览器渲染并缓存重点词、分段字幕和信息卡片透明窗口；默认不占用用户正在打开的 Edge。
• scripts/plan_adaptive_audio.py：从 57 个个人实录音效与 8 个生成音效家族单一代表中按语义规划时间线；不使用多音调副本，不自动启用音乐。
• scripts/build_audio_master.py：把项目音效与源视频人声合成为 48 kHz 双声道母带，人声保持优先。
• scripts/export_timeline_master.py：按原片入出点一次完成剪段、覆盖层、音频和最终编码。

交付说明

HTML 阶段报告本地地址、状态文件、截图、代理规格和声音试听结论，并明确“尚未生成视频”。最终阶段报告 MP4 与封面绝对路径、宽高、fps、时长、编码、音频状态和联系表。不得把“页面能打开”或“文件已生成”说成画面已经验证；也不得把 HTML 样片说成最终视频。