传化AI 影搭子

概述

「传化AI 影搭子」是一个把文本/文档转化为视频的智能生产工具，基于传化小智（封面图生成）与
WorkBuddy（TTS 语音合成、音频混音、Remotion 渲染编排）构建。目标是让业务团队不碰代码、不写
配置、不接触 Remotion 工程，也能快速产出宣传视频与培训课件。

本技能是编排层 + 胶水脚本层，自身保持轻量；底层视频工程通过环境变量 TF_REMOTION_DIR
指向一份已部署的 tfremotionvideos（含 node + ffmpeg + soffice + TTS）。制作者只通过
WorkBuddy 对话或上传入口使用，对工程路径无感。

适用场景

• 产品宣传 / 演示视频（promo 模式）
• 新闻稿 / 产品稿（docx / md）→ 宣传视频（promo 模式，文档驱动分镜）
• PPT / PDF → 有声课件（courseware 模式）
• 用户上传文件并口述需求（"男声、语速正常"），由 AI 全链路驱动

支持平台

• ✅ macOS（走 Homebrew 安装依赖）
• ✅ Linux / Ubuntu（走 apt-get 安装依赖）
• ✅ Windows（WSL2 + Ubuntu，推荐）：管理员 PowerShell 执行 wsl --install -d Ubuntu，
  重启后进 Ubuntu 终端，按 Linux 流程运行 setup_env.sh。
• ✅ Windows 原生 LibreOffice（PPT 提取兜底可用）：若已在 Windows 原生安装 LibreOffice，
  ppt_extract.py 可通过 soffice_helper 自动探测 C:\Program Files\LibreOffice\program\soffice.exe
  等路径并直接复用（无需 WSL2）；但完整渲染流水线仍建议在 WSL2 / macOS / Linux 下运行。
• 🔧 soffice 跨平台定位 + 防卡死：scripts/soffice_helper.py 统一负责探测（Mac/Linux/Windows）
  并以 SAL_USE_VCLPLUGIN=svp + LD_PRELOAD socket shim 规避受限环境（WSL2 / 沙箱）下
  AF_UNIX 被屏蔽导致的 soffice 卡死；Windows 无 AF_UNIX，自动跳过 shim。

前置条件（AI 自动完成，制作方零操作、零命令）

环境初始化完全由 AI 影搭子在后台自动执行，制作方无需运行任何命令、无需看懂脚本。首次使用时
AI 会自动初始化环境（约 1–3 分钟，含 ffmpeg / Python 依赖 / 渲染工程 / npm install；若输入为 PPTX 会额外按需安装 LibreOffice，PDF 直出可跳过），
期间主动用大白话播报进度；若遇网络波动、权限、沙箱限制等问题，AI 会自动重试或在对话里用人话说明
需要什么（联网 / 授权 / 代理），绝不把一行命令甩给制作方，也绝不会静默卡死。

• 安装脚本做了什么（AI 内部知识）：scripts/setup_env.sh 自动安装 ffmpeg / poppler（PDF 转图必需）/
  Python / edge-tts / node，从技能自带 vendor/tfremotionvideos 复制渲染工程、执行 npm install、
  配置 TF_REMOTION_DIR。Linux 仅装 libreoffice-impress + fonts-noto-cjk（体积小、保证中文不乱码）；
  soffice 已存在则跳过；装完自动「首次启动预热」避免正式转换卡顿。
• 失败不静默、不卡死（脚本已保证）：脚本每一步都有超时护栏（macOS/Linux 通用，纯 bash 实现），
  soffice 预热失败自动启用 shim 重试、绝不无限挂起；npm / pip 失败自动重试一次；任何失败都会写入
  progress.json（status=error，error 为人话）并落到 setup.log。
• 工程来源：默认用技能自带的 vendor/ 工程（离线可用）；若贵司有内部 GitLab 仓库，可设
  TF_REMOTION_SOURCE=git REPO_URL=git@gitlab.xxx.com:etransfar/tfremotionvideos.git 改为克隆。
• 若本机已具备完整环境，AI 可跳过脚本，仅 export TF_REMOTION_DIR=<工程根目录>。
• 初始化完成后即可对话出片，全程零手工配置。

模式识别

根据用户意图与输入文件类型选择模式：

• 输入为「品牌/产品文案 + 诉求描述」→ promo 模式，详见 references/promo-workflow.md
• 输入为「新闻稿 / 产品稿（docx / md）」→ promo 模式（文档驱动分镜）：由 AI 先把稿件结构化为
  promo_storyboard.json（N 个分镜：标题 / 要点 / 旁白 / 时长），再驱动 Remotion 渲染，详见
  references/promo-workflow.md
• 输入为「.pptx / .pdf + （可选）讲稿」→ courseware 模式，详见 references/courseware-workflow.md

两模式共享「封面生成、TTS、混音、Remotion、ffmpeg 封装」五类能力，仅内容编排组件不同。

性能优化（v1.2.19）

• TTS 去重：以前 tts_bridge 与 mix_courseware_audio 都会对每页调一次 edge-tts（合计 13 页 × 2 = 26 次网络往返）。v1.2.19 起 tts_bridge 改为逐句 TTS（保存到 public/assets/courseware/sentences/p{NNN}_s{KK}.mp3）并把 sentences / clip_durs / sentence_audios 写回 manifest；mix_courseware_audio 检测到 manifest 已有这些字段时直接复用，不再重复调 edge-tts——每课件可省 13 次网络往返（约 30-60 秒）。v1.2.18 旧 manifest 仍可工作（自动走 fallback 路径自己 TTS）。
• 运行计时（下次卡住能直接定位）：build_courseware.sh 现在每阶段都打印 ⏱ <name>: 累计 Xs（本段 Ys），5 个主要阶段分别是"提取讲稿与图片 / TTS 合成 / 音频混音 + Remotion 数据生成 / Remotion 渲染 / 封面拼接 + 元数据"。当任务卡住时看最后一行就能知道卡在哪。
• 标题占位符剥离：从 PP_PLACEHOLDER_TYPE.TITLE / CENTER_TITLE 取出的文字默认不进入旁白，彻底消除"PPT 标题被原样念出来"的问题。

课件零额外文档原则（重要，绝不向用户索取 md）

PPT → 课件是零输入即出片的：用户只需把 .pptx（或 .pdf / 图片序列）丢进对话，无需写讲稿、无需填 narration.md，技能按以下优先级链自动选旁白——

1. narration.md（仅可选升级路径：用户希望用更口语化/精修讲稿时才给）
2. PPT 备注栏（用户做 PPT 时若写了，会自动读出）
3. 每页正文文字（Plan A 自动兜底）——读出文本框/占位符/表格/组合图形内的文字，零额外文件
4. 静默页

⚠️ 绝不能因为用户没写备注、也没给 narration.md 就向用户索取 md 文档或阻塞流程；这正是"零阻断"的核心。详见 references/courseware-workflow.md 顶部"零额外文档原则"小节。

旁白优化（v1.2.19+ 默认开启）

旁白优化在 v1.2.19 起成为默认行为，无需手动加开关。每页原始讲稿/正文会被优化为自然、连贯、适合朗读的口播，并自动生成一句精简字幕（画面显示用）。编排链：

• 标题占位符自动剥离：从 PPT 标题占位符（CTRS_TITLE / TITLE）取出的文字默认不进入旁白（解决"第一章 / 标题"被原样念出来）。仅当某页完全无正文时才回退用标题兜底。
• 小节序号行自动剥离（v1.2.20 修正）：识别并剥除『第一章 引言 / 一、市场规模 / (一) 概述 / ① 核心要点 / 1.1.1 小节』等纯标题行；但只剥前缀、保留其后正文，所以『1. 营收12亿』这类带序号的要点不会被整行删掉（旧版会误删内容）。小数如『12.5 亿』『3.14』不再被误判为小节序号；单点小节如『1.1 背景』因无法与小数可靠区分，改为保留（TTS 读作「一点一 背景」），以优先保证数据不丢失。
• LLM 改写（质量最优）：当环境变量 TF_LLM_API_KEY 已配置时，调用 OpenAI 兼容接口（TF_LLM_BASE_URL 默认 https://api.openai.com/v1，TF_LLM_MODEL 默认 gpt-4o-mini）改写每页。
• 离线规则清洗（无 LLM 时自动降级）：去项目符号、去页码/页脚噪声、去小节序号、去重、拼接成句——零依赖、零成本，质量仍优于原样。
• 仍失败则回退原样，绝不阻塞出片。
• v1.2.20 修复（重要）：上一版（v1.2.19）的离线规则会把「整页仅剩标题」的页（如章节分隔页）和「以序号开头的要点行」误判为小节标题并整行删除，导致这些页变成静默页或内容丢失；小数（如 12.5 亿）也会被误删。v1.2.20 改为仅剥序号前缀、保留正文，并增加「优化后为空则回退原样」的兜底，杜绝静默页与内容丢失。

> 事实准确性约束（课件第一原则）：LLM 仅"重组/串联"幻灯片已有信息，严禁编造页外数据、结论或案例；保留关键数字与专业术语。此约束已写死在改写 Prompt 中。
> - 优化作用于每页原始文字（备注 + 正文兜底均覆盖）；--narration 文件（用户精修稿）不受影响、跳过优化。
> - 仅对 .pptx 输入生效；.pdf / --images-dir 无文字层，优化无意义（保持静默页，除非给 --narration）。
> - 可与 TF_MAX_NARRATION_CHARS 叠加：优化后文字同样受长度上限约束。
> - 关闭优化（不推荐）：--no-optimize-narration 或 SKIP_OPTIMIZE=1；关闭后仍保留"标题占位符剥离"这一结构性行为。

相关环境变量

调用示例（默认即开启；显式写法）：

# 默认（v1.2.19+ 已自动开启润色）
bash scripts/build_courseware.sh --input 课件.pptx --title 我的课件

# 关闭润色（不推荐）
bash scripts/build_courseware.sh --input 课件.pptx --title 我的课件 --no-optimize-narration

# LLM 改写（配了 key 才走 LLM，否则自动降级规则清洗）
TF_LLM_API_KEY=sk-xxx bash scripts/build_courseware.sh --input 课件.pptx --title 我的课件

课件音色（用户可选，默认沉稳男声）

courseware 模式配音默认 zh-CN-YunyangNeural（沉稳男声，适合培训/演示）。用户可在对话中指定
「女声 / 活泼女声 / 温柔女声」等，由 AI 影搭子映射到对应 edge-tts voice（完整清单见
references/courseware-workflow.md 的「音色选择」小节）。tts_bridge.py 也支持 --voice 直接覆盖。

字幕样式（浅色描边，适配浅色 PPT）

courseware 模式字幕默认：白色文字 + 1px 浅色半透明黑描边（rgba(0,0,0,0.35)）+ 柔和投影，
无底框，居中显示在底部。该样式在浅色 PPT 背景上既清晰又不抢画面，整体观感类似 B 站通用字幕
但更柔和。用户可在对话中要求调整（如取消描边、加底框、改位置）。

录屏按需插入（课件模式）

courseware 模式支持在指定 PPT 页后插入制作方提供的实操录屏，但默认不插入。只有当制作方
在对话中明确要求「在第 N 页后插入某录屏」时才启用；未提供录屏或不要求插入时，渲染为普通的
PPT 有声课件，无录屏段落。

对话识别方式：
- 一句话直达：「第 5 页后插入 demo.mp4，录屏用原声」
- 自动追问：检测到对话中有 .mp4/.mov 等视频附件时，主动询问「要插到第几页之后？用原声还是
AI 旁白覆盖？」

声音策略：
- original：保留录屏原声，该段不叠加 AI 旁白（推荐）
- ai：录屏静音，由 AI 朗读该段人工讲稿（适合后期补配音）
- mute：录屏静音，无旁白（纯画面）

实现方式：skill 把对话意图转成 clips 数组，经 mix_courseware_audio.py 混入全局音频时间轴，
再由 Remotion 的 <OffthreadVideo> 在对应页后渲染，与前后 PPT 段以 10 帧交叉淡入淡出衔接。

新闻稿 → 宣传视频（文档驱动 + 科技感分镜）

把产品新闻稿 / 产品稿直接变成宣传视频，无需手工写分镜、不碰 Remotion 工程。
风格参考「订小二」：动态科技背景 + 动能标题 + 数据跳动卡 + 步骤卡 + 插图科技面板 + 玻璃胶囊要点，
整体不像"动态 PPT"。

> ⏱️ 时长硬约束（务必遵守）：产品宣传视频总时长必须控制在 60 秒以内（1800 帧 @ 30fps），
> 推荐 45–55 秒。AI 结构化分镜时须据此设计镜数（建议 5–7 镜）与每镜旁白长度：
> 每镜旁白控制在 1–2 句话（约 8–25 秒），避免单镜过长。mix_promo_audio.py 会在
> 计算出总时长后做校验——若超过 60 秒会自动压缩段间停顿到下限并重告警；若仍超，会明确提示
> 制作方精简内容。不要为了塞内容而牺牲节奏。

完整流水线（已实现，由 build_promo.sh 串联 6 步）：
1. AI 读稿 → 结构化产出 promo_storyboard.json（字段约定见 references/promo-workflow.md，
含 type / title / points / narration / tone / stats / steps / images）
2. scripts/mix_promo_audio.py：逐镜逐逗号片段独立 TTS（字幕时长 = 该片段真实配音时长，
与语音 1:1 同步）→ WAV 样本叠加混音 → 可选 BGM 合成 → 生成 PROMO_TIMELINE / PROMO_SUBTITLES
3. scripts/build_promo.sh：部署 assets/promo/*.tsx → 幂等注册 Root.tsx → Remotion 渲染
→ 取首帧作封面 + ffmpeg 拼接 2 秒封面段 + 写入 attached_pic 元数据
4. 交付 output/promo-<标题>-final.mp4

调用方式：

# 完整构建（含合成环境 BGM）
TF_REMOTION_DIR=/path/to/tfremotionvideos \
  ./build_promo.sh --storyboard promo_storyboard.json --title 业财智核-v4 --bgm-synth

# 旗舰：从新闻稿直接抽取分镜骨架（再人工润色成 storyboard）
TF_REMOTION_DIR=... ./build_promo.sh --input 新闻稿.docx --title 业财智核

# 接入自有 BGM 文件（替代合成）
./build_promo.sh --storyboard promo_storyboard.json --bgm /path/bgm.mp3

• 默认音色 zh-CN-YunyangNeural（沉稳男声），可用 --voice 覆盖或 storyboard.voice 指定
• 默认合成 BGM 为 Am-F-C-G 轻柔环境 Pad（音量 0.16），可用 --bgm-vol 调、或 --no-bgm 关闭

后续可选（路径 B / C，未实现）：
- B. AI 生图：每镜用 image_gen.py（pluggable 后端）出 1920×1080 主视觉，PromoScene 改播主视觉 + Ken Burns
- C. 录屏嵌入：复用 courseware 的 <OffthreadVideo> 把演示录屏插到指定镜后

字幕样式：白字 + 浅色半透明黑描边（rgba(0,0,0,0.35)），单行 nowrap、去标点（数字小数点
如 99.9% 保留），在 promo 深色背景上清晰。

1. 对话式（推荐）：用户把文件拖入对话，说一句话（如"把这份新闻稿做成宣传视频"）。
   读取本技能后，按对应 workflow 调用 scripts/ 与 TF_REMOTION_DIR 完成全流程，最后把
   output/*.mp4 交回用户。用户全程不碰命令行、不碰配置。
2. 自助式：技术同学预装好后，把文件放入工作目录并运行 scripts/build_promo.sh。

promo 实现要点（防踩坑，务必遵守）

这些是从实战中沉淀的非显然规则，跳过会直接导致"字幕慢半拍 / 布局错位"等返工：

1. 字幕必须与配音逐片段同步：mix_promo_audio.py 对每镜旁白按逗号/顿号/分号/句末标点切成
   片段，每个片段独立 TTS，该片段字幕的 startFrame/endFrame 直接由该片段真实配音时长
   驱动。❌ 绝不要"整句 TTS 后按字符数比例把字幕铺到句时长里"——中文 TTS 各字时长不均且有停顿，
   按字符比例分配的节奏和实际读音对不上，听感就是"字幕比人声慢、不同步"。
2. 字幕去标点 + 单行：显示文本统一 strip_punct（保留数字中的小数点），组件强制
   white-space:nowrap。过短片段（<4 字）自动与后段合并，避免闪得太碎。
3. BGM 合成：无现成 bgm 文件时，--bgm-synth 用 ffmpeg lavfi 的多个 sine（A3/F3/C4/G3
   等频率 + 轻微 detune）叠加成环境 Pad，再与人声 WAV 叠加；音量默认 0.16 不压人声。
4. 文档插图是视频一等公民，且必须"结合文档上下文"呈现（务必落实，避免"像动态 PPT 且没插进图"）：
   制作方文档（docx）里的新闻图片 / 产品图片 / 流程图片等内嵌插图必须真实进入视频画面，
   且以主视觉方式呈现；更关键的是——图片不是孤立展示，而要带着它在文档里所属的上下文一起出现：
   插图所在的章节小标题作为镜头的 title，章节里描述这张图的句子作为 imageCaption（屏幕图注），
   章节正文作为 narration（配音会真的念出文档对这张图的说明）。这样观众看到图的同时，也读到 / 听到
   文档对它的解释，而不是一张没头没尾的图。三类呈现通道：
   - showcase 类型（首选，插图作主视觉 + 上下文）：该镜以插图为核心——大尺寸居中（objectFit:contain
   不裁切，流程图完整可见）、Ken Burns 缓慢推拉、底部渐隐遮罩 + 标题（章节小标题） + 图注（描述句），
   纪录片 / 新闻包式。news_extract.py 在 --input 抽图后会自动按"所属章节"分组产出 showcase 镜头，
   并自动填入真实上下文（标题取章节小标题、图注取含"图/示意/架构/流程"等词的句子、旁白取章节正文），
   不跨章节混图；因此从稿件直出时插图默认就"带说明"地出现在成片里。
   - points 类型带 images：右栏大图玻璃面板（已放大 1.18×，含 HUD 边角 + 扫描线 + Ken Burns + 高光扫过），
   适合"要点 + 一张佐证图"，该镜同样应让 title/narration 与图相关。
   - stat / steps / closing 类型带 images：右下角浮动紧凑图卡，确保任何带图的镜头都不会把图静默丢弃。
   - 字段："images": ["assets/promo/illustrations/xxx.png", ...]（相对 public/，由 news_extract
   抽取写入 public/assets/promo/illustrations/）；"imageCaption" 应填该图在文档里的描述句（而非
   "产品实拍"这类空泛词）；"narration" 应填该图所属章节的正文，使配音解释画面。
   - ⚠️ 撰写最终 promo_storyboard.json 时的铁律：① 必须保留骨架里的 images 字段，不要重写时漏掉；
   ② 成组的真实配图优先用 showcase 镜头呈现（同一章节的图归到一镜，共享同一段上下文）；
   ③ title / imageCaption / narration 必须取自文档真实内容，严禁写死"产品实拍 · 资料图"等空泛占位；
   ④ 不要把带图的镜头只写成 cover / closing 且不另配 showcase/points 镜——
   那样图会缩成角落小卡甚至被忽略。目标是让成片"有图有真相、看图知其所云"，而非纯文字幻灯片。
5. 动态背景：PromoBackground 共享炫光背景（光晕呼吸 + 旋转光环 + 漂浮线框 + HUD 网格 +
   上升粒子 + 斜向流光 + 扫描线 + 色散漂移光斑 + 同心脉冲环 + 透视地平线网格 + 流动曲线光带 +
   星点呼吸层 + 上升碎片 + 第二条反向流光），各镜复用，避免"纯色/渐变"的 PPT 感。
6. AbsoluteFill 默认 column：Remotion 的 AbsoluteFill 默认 flexDirection:'column'，所有
   横向布局容器必须显式写 flexDirection:"row"，否则内容会竖向堆叠错位。

关键执行原则

• 不要把整个 tfremotionvideos 工程塞进本技能。技能只放 scripts/（胶水）、references/
  （流程）、assets/courseware/（Remotion 组件模板，由 build 脚本部署到工程）。
• 课件模式的 Remotion 组件模板位于 assets/courseware/，由 build_courseware.sh 复制到
  $TF_REMOTION_DIR/src/compositions/courseware/ 并自动注册到 src/Root.tsx。
• 宣传视频（模板卡 MVP）的 Remotion 组件模板位于 assets/promo/，由 build_promo.sh 复制到
  $TF_REMOTION_DIR/src/compositions/promo/ 并自动注册 PromoComposition 到 src/Root.tsx。
• 混音务必复用 scripts/mix_courseware_audio.py 的 WAV 样本叠加法（避免 ffmpeg amix
  对人声的衰减），范式来自 tfremotionvideos 的 mix_audio_v32.py。
• 封面与视频拼接、元数据写入（attached_pic）复用 tfremotionvideos build.sh 的 ffmpeg 逻辑。

活源 ↔ 技能包 同步机制（必读）

本技能的渲染组件模板（assets/{promo,courseware}/*.tsx）与 vendor/tfremotionvideos
渲染工程，都是从活源工程 etransfar/tfremotionvideos 凝固而来的。三处同源文件
（活源 src/compositions / 技能 assets / 技能 vendor/.../compositions）必须保持一致，
否则会出现"改了 A 没改 B"的漂移。

单一事实来源 = 活源工程 etransfar/tfremotionvideos。 任何组件改动最终都要落到活源，
再由同步脚本凝固到技能包。

提供 scripts/sync_source.sh 维持同步：

# 查看三处差异（不改动文件）
bash scripts/sync_source.sh status

# 在技能包内改了组件 → 推回活源 + vendor（技能包较新时使用）
bash scripts/sync_source.sh push

# 活源工程演进 → 拉入 assets + 整包重建 vendor（活源较新时使用）
TF_SOURCE=/path/to/tfremotionvideos bash scripts/sync_source.sh pull

• 活源路径默认 /Users/admin/Desktop/etransfar/tfremotionvideos，可被环境变量
  TF_SOURCE 或 --source=PATH 覆盖。
• *.generated.ts 为构建期自动生成，不纳入同步。
• pull 重建 vendor 时会排除 node_modules/.git/构建产物/大媒体，保持快照精简。
• 约定：在技能包内修改组件后，先 push 把改动落回活源并在活源工程提交（git commit），
  后续 pull 即可保证三处长期一致。

交付与封面定制

• 一次性出片（默认）：build_promo.sh / build_courseware.sh 已串联「渲染 → 取成品首帧作封面
  → 2 秒封面段 → 写 attached_pic 元数据」全流程，单次运行即产出最终 MP4（promo：
  output/promo-<标题>-final.mp4；courseware：output/courseware-<标题>-cover2s-final.mp4）。
  ⚠️ 不要在 Remotion 渲染后就停下来等用户询问——直接跑完收尾、把最终 MP4 交回制作方，
  避免"卡住不通知 / 完成不通知"的体验问题。
• 自动复制到工作区可见目录（artifact 渲染友好）：脚本末尾会把最终 MP4 额外复制一份到
  ${PWD}/transfar_artifacts/（即构建脚本被调用时所在目录的 transfar_artifacts/ 子目录）。
  原因是 $TF/output/ 落在 .workbuddy/skills/.../vendor/... 这种隐藏深处路径，
  WorkBuddy artifact 卡片对这种路径下的 MP4 可能仅显示为可下载卡片而非 inline 卡片，
  工作区副本路径更浅，便于用户在对话里直接看到并预览。可覆盖：TF_FINAL_COPY_DIR=/其它/路径；
  临时禁用：SKIP_FINAL_COPY=1。
• 封面默认取成品首帧：promo 与 courseware 均取渲染首帧（首帧提取失败回退第一页 slide）。
• promo 模式：交付后必须显性引导自定义封面（强制，不可省略；且仅限 promo 模式）：把最终 MP4 交回制作方后，
  必须立即追加一段显性引导，不能只用"如需自定义封面告诉我"轻轻带过。如果已经知道产品名称，
  请把提示词中的占位符"产品名称XXXX"替换为真实产品名再输出。
  适用范围：本条封面提示（链接 + 16:9 路径 + 提示词）仅在该技能以「产品宣传视频（promo）」模式出片时触发；
  courseware（课件）模式一律不触发，也不得输出此提示词模板。

输出模板（必须原样发给制作方，禁止回引文档，链接/路径/提示词缺一不可）：

> 宣传视频（promo）：当前封面是自动截取的首帧。如需更贴合品牌主视觉，可到传化工作台 → 小智 → 【图片创作】 → 尺寸选 16:9 生成封面。
>
> 小智参考提示词（双引号内可替换为你的真实产品文案，复制时把"产品名称XXXX"换成真实产品名）：
>
> > 科技商务风海报，深邃藏蓝色背景，底部带有蓝色光晕与环形光轨，两侧延伸放射状光线，画面中心下方有简约线性图标。文案分三层排布：顶部为小字 "产品名称XXXX"，下方配对应英文；中间是主标题粗体大字 "产品名称XXXX 重磅上线"，字体为粗无衬线体，带蓝白渐变发光效果，醒目大气；主标题下方显示辅助小字，辅助文字均为纤细无衬线同色系字体。整体排版层级清晰，风格简洁正式，充满未来科技感。 >
>
> 生成封面后直接把图片发回对话，我帮你替换封面，无需重新渲染，也无需你自己替换任何工程文件。

> ⚠️ 强制约束：
> - 链接 + 16:9 路径 + 完整提示词必须完整、显性地出现在交付消息中，不得省略、折叠或只给链接；
> - 提示词必须直接显示在对话里，禁止出现"提示词见技能说明 / 见 SKILL / 看文档 / 替换 public 目录图片"等把制作方推回工程或文档的话术；
> - 制作方是不碰工程、不读 SKILL 的非技术人员，任何省略、回引或让制作方操作工程路径都等于没引导；
> - 制作方上传图片后，AI 内部调用 build_courseware_finalize.sh <正片mp4> <自定义封面png> <输出mp4>
> 重打包封面（promo 同样复用），无需重新渲染，不要让制作方执行任何命令或替换文件。
- courseware 模式：默认不需要自定义封面（且绝不触发 promo 封面提示）：课件封面取渲染首帧（或第一页 slide）即可，
一般无需定制，不要主动询问自定义封面；交付课件后，不得输出 promo 模式的「小智 / 16:9 / 提示词」封面引导模板，
仅在制作方主动提出时才按上文重打包流程处理（此时仅内部替换，不展示提示词给制作方）。

渲染进度查询（progress.json，方案 A）

• 环境初始化与渲染期间，构建脚本持续写入 /tmp/transfar-film-buddy/progress.json，字段：
  mode / title / status / stage / total_frames / rendered_frames / percent / started_at /
  updated_at / output / error。stage 让制作方直观看到「卡在哪一步」。
• 环境初始化 · 自愈监控协议（AI 必须遵守，绝不对制作方暴露脚本或命令）：
  环境初始化由 AI 在后台跑 scripts/setup_env.sh，并全程主动监控，确保「卡住 / 报错 / 超时」永远有人管、绝不静默：
  1. 启动即播报：后台启动前先对制作方说一句人话——「正在为您准备视频渲染环境，大约需要 1–3 分钟，请稍候～」
  （不要出现脚本名、路径、命令）。记下后台 task_id。
  2. 轮询（必做，不可省略）：循环读取后台输出 + /tmp/transfar-film-buddy/progress.json + setup.log：
  • status=ready → 环境就绪，进入渲染；
  • status=rendering/finalizing → 用 stage 字段播报进度（如「已装好 ffmpeg，正在安装 LibreOffice…」），继续轮询；
  • status=error → 进入第 3 步自愈；
  • 整体超过 20 分钟无 ready，或 updated_at 距现在 >180 秒且未 done → 视为卡死，进入第 3 步。
    3. 自愈（AI 主动修，不麻烦制作方）：读 progress.json.error 与 setup.log 末尾，按映射尝试一次修复后重跑
    setup_env.sh（脚本内部已带重试/超时，重跑安全幂等）：
  • 含 soffice / AF_UNIX / warmup → 带 TF_SOFFICE_SHIM=1 重跑；
  • 含 npm / ETIMEDOUT / network / 超时 / 下载 → 直接重跑一次（网络抖动自愈）；
  • 含 pip / python → 直接重跑一次（venv / break-system-packages 兜底）；
  • 含 sudo / 密码 / 授权 → 这是真人动作：用大白话告诉制作方「安装环境需要本机管理员授权一次，请在弹出的窗口输入开机密码」
    （绝不出现命令）；对方无法授权则建议联系 IT；
  • 含 网络 / 无法连接 / 下载失败 → 大白话：「当前网络似乎连不上下载源，请检查网络或公司代理后，对话里跟我说『重试』即可」；
  • 其他 → 大白话概括错误，并主动提议「我帮你重试一次」或「需要我联系技术支持吗」。
    4. 兜底：自愈一次仍失败，用大白话说明现状 + 需要什么（联网？授权？代理？），并明确「随时对话让我重试」，
    绝不丢命令、绝不静默结束。
• 渲染期间主动询问进度（推荐）：宣传片 / 长课件本地渲染耗时较长，应主动在对话中询问「渲染进度 /
  好了吗」并据此汇报，让制作方不必一直守着、也不必反复追问——
• status=ready：环境初始化完成，准备开始渲染；
• status=rendering：报「已渲染 X/Y 帧（Z%），预计还需约 T 分钟」（T 由 rendered_frames、
  total_frames 与已用时长估算）；若进度明显偏慢（如 1083/3017 帧耗时近 30 分钟），同时说明这是
  逐帧渲染的正常耗时，并非卡死；
• 若 updated_at 距当前超过 120 秒且仍为 rendering → 报「渲染可能已卡住，建议重试或检查环境」；
• status=finalizing：报「渲染已完成，正在封装封面，稍候」；
• status=done：报「✅ 已完成，最终文件：<output>」；
• status=error：报「❌ 渲染失败：<error>」。
• 制作方也可随时主动问「进度 / 好了吗」，机制同样即时回应（被动兜底）。主动询问 + 被动兜底共同保证
  进度透明、不静默；钉钉/企业微信 webhook 主动推送为后续增强项，不在当前版本。

实时联调

本技能的所有文件（SKILL.md / scripts）每次触发时从磁盘即时读取，改完即生效，无需重启
WorkBuddy。开发期用斜杠命令 /transfar-ai-film-buddy 强制触发；脚本可单独用 Bash 对样本
文件调试，不必每次走完整渲染。