本地视频创作工坊（Video Studio）

把一句话创意、或一份上传的文件（剧本 / 产品资料 / PPT / 文章 / 需求文档…），按业界顶级短视频团队的标准产线，自动拆解、生成并合成为一支完整成片：剧本 → 角色/场景设定 → 分镜 → 关键帧 → 逐镜成片 → 配音 → 字幕 → 背景音乐 → 后期合成 → 导出。

核心目标：人物/角色外形前后一致、镜头衔接丝滑流畅、配音·字幕·片头·片尾·背景音乐·封面全部到位。

触发与运行前置

自动触发词：做视频、短视频、宣传片、口播视频、剧情短片、科普视频、产品视频、一句话做视频、把这个文件做成视频、安利视频、搞笑短剧、情感短片 等。

• 工具在每次执行前先确认存在：default venv Python（内置 Pillow + imageio_ffmpeg）、ImageGen / VideoGen 工具。三者缺一需先补齐说明。
• 无需连接任何外部 MCP（本技能完全本地 + 内置 Gen 工具，不依赖 Flova）。
• 视频/图片生成会消耗额度（视频约 50–100 额度/5 秒、图片约 5–10 额度/张）。开始前必须向用户明示额度消耗并让其确认规模（决定镜头数量与时长）。
• 涉及已连接工具不满足的需求时，遵循 find-skills 兜底规则。

运行环境断言（先做再往下走）

1. 脚本统一用 default venv Python 运行（它同时带 Pillow 与 imageio-ffmpeg，供片头片尾中文渲染与 ffmpeg 调用）：
   - C:\Users\80019070\.workbuddy\binaries\python\envs\default\Scripts\python.exe
   - 该解释器执行全部 scripts/*.py。执行前可 python -c "import PIL, imageio_ffmpeg" 自检。
2. 定位 ffmpeg：
   - 直接用 scripts/find_ffmpeg.py --probe 解析出可执行路径（优先 imageio_ffmpeg 内置二进制），据此拼接后续 ffmpeg 命令。
   - 找不到时提示安装 pip install imageio-ffmpeg（装进 default venv），不要空跑。
3. 建工作目录：每次成片在 C:\Users\80019070\WorkBuddy\<会话目录>\videos\<片名>\ 下新建 00_assets / 01_script / 02_characters / 03_keyframes / 04_clips / 05_voice / 06_audio / 07_subtitles / 08_compose / 09_delivery 子目录，逐阶段落盘，便于追溯。
   - 00_assets/ 是本片复用的资产库：角色定型图、风格参考、产品/实物参考图、固化锚点文案都放这里，且每一片做完后沉淀进项目级资产目录 C:\Users\80019070\WorkBuddy\<会话目录>\assets\（跨片复用）。

生产标准（业界最佳实践对照，决定质量上限）

这套方法提炼自 2026 年专业 AI 视频团队（pre-production 定死 → 生产 → 后期）的共识，是本技能的质量基线：

1. 四段式，先定再渲染：开发(故事/风格/锚点) → 前期(分镜/资产/规格) → 生产(生成) → 后期(合成/声音/交付)。在前期把所有"决定"锁死，生产阶段只负责"执行渲染"。跳过前期 = 后期大量返工。
2. 资产库驱动一致性（最高杠杆）：角色 → 先建一张稳定"定型图"+一行"canonical 描述"（发型/脸/服装/特征，全片不变）；风格 → 一段"palette/light/texture"固定词。跨镜头永远引用资产，绝不每次重新造。这是"人物不换脸、风格不漂移"的根本方法。
3. 音频前置（audio-first）：配音/旁白脚本在镜头定稿之前定（节奏跟旁白走）；BGM 在剪辑之前选（切点卡节拍）。画面与声音作为一体设计，不是最后贴上去。
4. 草稿分档渲染（draft→final）：先低成本批量出"草稿帧/草稿片段"，集中审计（构图/连续性/文字/动作），通过后再用精档渲染真正需要高质量的镜头。小批量审查、尽早纠偏，避免"整批做错再重来"。
5. 审查小批量：严禁一次性全量生成到底——先出 3-5 张关键帧或 2-3 个样片镜头给用户/自审，锁定风格后再继续。
6. 资产与提示词归档：每片结束把"可复用资产+赢的 prompt"归档，系列/渠道成为可重复的流程，而非每片从零开始。

据此，后续每个阶段都遵循"先定稿、再执行、小步审、可复用"。

历史坑位与修复（合成前后必查，防再犯）

> 以下条目都是从真实成片踩坑中提炼的已修复技术问题。合成后用 scripts/qa_check.py + 响度/时间戳自检即可拦截大部分。任何"没声音/对不上/字幕怪"先回到这张表对一遍。

合成后自查（每次必做）：
- python scripts/qa_check.py final.mp4 --ratio 16:9 → 比例/采样率/响度/解码全过
- 用响度时间窗检查配音段：max-min > 阈值 说明配音在、无恒定嗡嗡声；无声段 RMS≈0 说明无刺耳残留
- 比对 voice.json 每段 start 与该镜 SRT 首条 start 是否一致（abs(差)<0.35s）

阶段化流水线（按序执行，不跳步）

Stage 0 — 需求澄清与成片规格（先确认，再生成）

一次性用选择题或简短追问明确，绝不重复询问已有信息：

• 输入方式：（A）一句话创意　（B) 上传文件抽取信息
• 成片规格：时长（默认 30–60 秒口播 / 60–90 秒剧情）、画幅（竖屏 9:16 默认 / 横屏 16:9）、分辨率（720P 默认，1080P 可选）
• 风格调性：口播科普 / 剧情 / 情感 / 搞笑 / 科技/极简 / 复古 / 国风 等
• 语言与配音：中文普通话默认；男声/女声/童声；语气（激动/沉稳/温柔/欢快）
• 目标平台：抖音（竖屏9:16）、B站（横屏16:9）、小红书（竖屏3:4）等——决定字幕安全区与成片规格
• BGM 风格倾向：激昂 / 温馨 / 悬疑 / 轻快 / 史诗 / 悲伤（也可让 Agent 按主题自动匹配）

输出一屏“本片设定”复述目标、素材用途、交付规格、限制，请用户确认后再进入 Stage 1。生成规模（镜头数）在此一并确认以锁定额度。

Stage 1 — 剧本生成（一句话/文件 → 文案）

• 一句话入口：把创意扩写成三段式结构：钩子（0-3s 抓人）→ 展开（讲清卖点/冲突/过程）→ 反转/情绪收口 + 引导关注。按“每秒 4–5 字”的语速反推文案字数，例如 45 秒≈200–220字。
• 文件入口：先抽取文件核心信息（用 Read/解析能力），提炼 3–5 个最关键信息点做成“知识卡”，再据此写剧本。文件信息要可追溯，标注来源章节；缺关键信息不凭空补齐。
• 剧本交付物：01_script/scene_script.md，含：标题、一句话梗概、情绪曲线（起→承→转→合）、每段话术（台词）、目标时长、口播/对白拆分。
• 用 references/short-video-formulas.md 参照热门爆款结构（黄金三秒、留钩子、情绪反差、结尾引导）。

Stage 2 — 角色与场景设定（一致性基石）

> 人物外形前后一致的唯一可靠方法：先建“角色定型图”，后续所有镜头都以该图为图生视频/图生图的参考输入。 绝不允许每个镜头各自全新文生视频（必然变脸）。

• 用 ImageGen（文生图）生成每个核心人物/场景的角色定型图，保存到 02_characters/：
• 人物：一个全景正面全身像 + 一个特写头像（五官）、统一描述“同一人物”的物理特征（发型、发色、肤色、脸型、身高体型、服装/配色/配饰、年龄感、气质）。
• 场景：统一的光线氛围、色调、场地类型、时代感、风格（可用 references/consistency-prompts.md 的提示词模板）。
• 用一个固定“外观锚点文案块”（character anchor block）在每张图/每个视频 prompt 里复用：例如 同一角色：<名>，<发型>，<发色>，<脸型>，<肤色>，<体型的>，常穿<服装>，<气质>。这是保证跨镜头一致的“记忆锚”。
• 给主角编号 C1/C2…，场景编号 S1/S2…，后续所有分镜引用编号而非重新描述。

Stage 3 — 分镜脚本（Shot List）

按剧本线性拆成 N 个镜头（每镜通常 2–6 秒，取决于 VideoGen 默认片段与合成需要），输出 03_keyframes/shot_list.md 表格，每行一个镜头：

• 业界标准（5秒一镜 + 字数法则）：可先用 scripts/storyboard.py --script 口播文案 --out 分镜.md --target 60 自动切分——
  按"中文 4~5字/秒、每镜5秒(≈20~25字)、一镜一信息"生成分镜表 + 每镜关键帧/图生提示词。
  自动校验文案长度（偏短/偏长会警告），避免成片时长漂移。

• 每镜固定信息点：画面与台词强相关、前3秒抓注意力、结尾镜引导关注。

• 运镜词：推近 zoom-in / 拉远 zoom-out / 平移 pan / 环绕 orbit / 上摇 tilt-up / 跟随 follow；在 VideoGen prompt 里明确写“camera moves: zoom in smoothly, cinematic”。

• 关键帧策略：每个镜头首帧先 ImageGen 生成（作为该镜 video 的 image 起始图），借此把“画面主体、构图、光线”钉死，再图生视频，比纯文生更可控、更一致。

Stage 4 — 逐镜头关键帧生成（ImageGen）

• 为每个镜头生成首帧关键帧图，保存 03_keyframes/keyframe_S1C1.png。prompt = 场景锚点 + 角色锚点 + 镜头画面描述 + 构图 + 光线 + 风格。
• 尺寸硬规范（重要，避免比例漂移）：必须传与成片一致的标准档位尺寸。
• 横屏 16:9：size="1280x720"（或 "1920x1080"，ImageGen 实际归一为 1280x720）
• 竖屏 9:16：size="720x1280"
• 禁止使用 1536x1024 / 1024x1536 / 1216x832 等非标准尺寸 —— 实测会触发 ImageGen 输出 1216x832 等非 16:9 比例的关键帧，导致后续图生视频和合成时比例错乱、变形。
• 质量参数：quality="high"；构图词用 "wide cinematic frame / rule of thirds / high detail, sharp focus"。
• 生成后用 ffmpeg 校验关键帧宽高比（ffmpeg -i 看 Video: 分辨率），若比例与目标不一致，给出警告并修正 prompt/尺寸重试。
• 涉及已存在角色/场景的镜头，用 ImageGen.image 传参考图（角色定型图或上一镜末尾帧）做图生图，强化一致性。
• 首帧图同时可作为“封面/预览”。
• 多候选筛选（业界标准）：关键镜头生成 3–5 张候选，选主体清晰无畸形、构图符合分镜、光线统一、留运动空间那一张；涉及固定角色/风格的在每张加相同一致性标签。
• 关键帧提示词公式（参照 references/video-workflow-standard.md）：[主体]+[动作]+[环境]+[光线]+[构图]+[风格]+[画幅]+[一致性标签]。

Stage 5 — 逐镜头成片（VideoGen / Wan 精渲）

• 对每个镜头调用视频生成。引擎选型：
• 阿里云 Wan 精渲档（已接入 scripts/wan_api.py）：当设了 DASHSCOPE_API_KEY + DASHSCOPE_WORKSPACE_ID（新加坡专属域名）且需要高画质时，可用于文生视频/补充镜头（--type t2v，时长 2–15s，输出 1920×1080 带音频）。任务异步两段式：POST video-synthesis → GET /api/v1/tasks/{id}。
• 内置 VideoGen：默认，图生视频传本地关键帧路径（无公网 URL 依赖）。
• ⚠️ Wan 图生视频需关键帧公网 URL（input.media[].first_frame），本地图无法直接喂给 Wan；用户无公网图床时图生视频走内置 VideoGen，Wan 仅作文生/补充。
• 视频参数：
• 文生视频：prompt 复用关键帧描述 + 动作 + 运镜 + 秒级时长。
• 图生视频（内置）：必须传本镜首帧作为 image（标准 16:9 输入则输出跟随，避免画幅漂移）；有 last_image 插值能力则用首尾帧平滑过渡。
• 统一分辨率与画幅；片段时长 2–6 秒（Wan 允许 2–15s）；一次一镜，落盘 04_clips/clip_<镜号>.mp4。
• 生成后校验：用 ffmpeg 读输出分辨率，确认宽高比（16:9 ≈ 1.777）。异常比例在 prompt 强化 "maintain 16:9 aspect ratio" 并重试。VideoGen/Wan 可能重采样放大输入，属正常，最终合成用 cover 裁切。
• 生成遵循工具超时/重试契约（不外部 sleep 重试；失败用 --no-poll+status 两步、最多重试 1 次；不伪造结果）。

Stage 6 — 配音（Voiceover）

• 逐段台词生成配音。通道优先级：
  1. 本地离线优先：已集成 scripts/local_tts.py（基于 sherpa-onnx，CPU 可跑、免联网、稳定）。模型：~/.workbuddy/models/sherpa_tts_en/vits-piper-en_GB-alan-medium/（英国沉稳男声，已下载 67MB）。生成 wav → 再转 mp3。
  2. 在线高质量备选：edge-tts（英/中男声效果好，但需联网、偶发不稳定）。
  3. 兜底：pico2wave/espeak。
• 语法：python local_tts.py --text "..." --out out.wav [--model-dir <含.onnx目录>]。
• 响度归一（关键，常被忽略）：合成后用 ffmpeg loudnorm 归一到 -16 LUFS：
  ffmpeg -i out.wav -af loudnorm=I=-16:TP=-1.5:LRA=11 -ar 44100 out_norm.wav
  （漏掉此步 → 成片音轨过小/无声，历史踩坑）。
• 产出口播音频 05_voice/vo_seg_<n>.mp3（每镜头一段，便于对齐）。
• 记录每段时长 → 用于反向微调画面节奏与字幕时间轴。

Stage 7 — 字幕（Subtitles）

• 依据台词 + 配音实际时长生成 SRT：07_subtitles/subtitles.srt。
• 字幕单行优先（自动适配屏幕宽度）：同一句能一行显示完整就一行，不强制断句。
  按屏幕可用宽度估算（16:9 约 1150px / 字号≈23px → 英文 ≤95 字符一行），超过才在句号/分号/
  连词处语义分两行并分配前后半程时间窗。同步基准：SRT 每条 start=voice.json 对应配音真实
  start（diff<0.35s），绝不预估镜头时长。可用 scripts/subtitle_ass.py。
• 字幕位置（参考电影字幕）：字幕贴在画面底部安全区，左右居中。
• 横屏 16:9：下边距约为画面高度的 8%（不是 12-15%，那个太靠上）；字号约为画面高度的 5%。
• 竖屏 9:16：下边距约为画面高度的 8–10%，避开点赞/评论 UI 区。
• 用白字 + 黑粗描边 + 阴影（电影字幕经典样式），左右各留 5% 边距，单条 ≤ 8–10 字/行、≤2 行，短句优先。
• 字幕是包装不是补丁（参照 references/video-workflow-standard.md）：
• 一句 ≤ 15–18 字，关键词可放大/变色/加粗突出（当前 SRT 烧录为整句白字描边，如需关键词强调则拆句或用 ASS 样式）
• 用 scripts/subtitle_ass.py 生成 ASS（支持关键词高亮、避平台UI安全区、超长断句）：--kw "HEMS,储能" --style tech|cinema|guofeng
• 字体风格与视频风格统一（科技类无衬线、国风宋体/书法体）
• 避开平台 UI：抖音/视频号底部点赞评论区，字幕靠上或缩小
• 结尾镜头字幕引导关注/评论
• 提供自动断句规则（references/packaging-spec.md），标题使用大字样式。

Stage 8 — 背景音乐与音效（BGM）

• 按主题情感与节奏匹配 BGM：用 references/bgm-mood-mapping.md 的情感→曲风/速度映射表选定轨道。
• 禁止用 aevalsrc=sin(...) 合成正弦波当 BGM——会产生刺耳低频嗡嗡声且无音乐性（历史踩坑）。用真实音乐，参考 references/open-source-bgm-sources.md（Pixabay/Mixkit/YTB Audio Library 等，商用安全）。
• BGM 必须经用户审核后再用：选好曲目后先告知用户曲名/来源/风格，用户确认后再合成。不得擅自选定并直接合成交付。
• 来源：优先本地曲库；无版权音轨时用开源曲（Pixabay/Mixkit 免署名可商用）。不擅自使用受版权保护的音乐。用户明确"去掉 BGM"时，compose 不传 --bgm 即可（纯配音）。
• 音乐音量 bgm_vol≈0.15–0.25 低于配音；compose 已做 aresample=44100 + loudnorm，避免配音/BGM 采样率冲突或响度过载。
• 可选加：转场音效（whoosh）、重点时刻音效（boing/duang）、环境底噪，增强质感（参考 references/sfx-guide.md）。

Stage 9 — 后期合成（ffmpeg 剪辑）

用 scripts/compose.py（封装 ffmpeg）完成整条时间线组装：

1. 逐镜头精修剪：按时间轴对齐每个 clip 至目标时长（trim/pad），统一分辨率、帧率、像素格式。
2. 转场：根据分镜表转场列加入硬切/叠化(xfade)/推拉(wipe)/缩放(zoompan) 等，转场时长 0.3–0.5s。
3. 变速与卡点：按 BGM 节拍做轻微变速或卡点 cut。
4. 配音画面同步：配音轨按时间轴排列，去静音、对嘴、压缩归一化；人声与 BGM 混音做 ducking（淡入淡出 / sidechain 风格压低 BGM）。
5. 字幕烧录：subtitles filter 或集成软字幕，按安全区定位。
6. 片头片尾：片头用标题大字 + 主题动画（默认 2–3s），片尾用“关注/致谢/鸣谢”画面 + 淡出。
7. 调色 + 去AI感：eq/colorbalance/vignette 统一色调；加 --filmgrain 自动做"去AI感"（eq=contrast=1.05:saturation=1.08 + noise 胶片颗粒 + unsharp 锐化），降低 AI 塑料感，参照 references/video-workflow-standard.md。
8. 封装：按平台规格（见 references/packaging-spec.md）输出 .mp4，H.264 + AAC、高码率、1080P+。
9. 产物：08_compose/final.mp4 + 封面 cover.png（取首帧美化）。

Stage 10 — 导出与交付（Review Gate 硬关卡）

1. QA 硬校验（业界最佳实践：Review Gate / 质量回退）——合成后必跑：
   python scripts/qa_check.py final.mp4 --ratio 16:9
   自动检查：分辨率/宽高比、采样率(须 44.1k/48k，拒绝 96k 播放器不兼容)、响度 mean∈[-20,-8]dB(过低=无声/过高=削波)、解码完整性。任一 FAIL 即重做对应环节，不得交付。
   （历史踩坑：采样率 96k→播放器无声；响度 -30dB→"没声音"；字幕过大/靠上。）
2. 抽查画面：抽 5~8 个时间点帧，确认字幕在底部安全区且字号合适、无黑边/变形、镜头无花屏。
3. 多格式衍生（如需要）：从主片派生竖屏 9:16 / 不同字幕字号版本，用 --sub-size/--sub-margin 复用同一时间线。
4. 品牌与合规：涉及产品数据/功效/奖项，字幕或口播须注明信息来源或免责；不把 AI 生成内容冒充真实拍摄/验证事实。
5. 用 present_files 展示 final.mp4 + 资产归档该片新资源进 assets/。
6. 汇报：成片路径、规格、镜头数、配音语言、QA 结果、未完成事项。

一致性硬约束（不可违反）

• 角色外形：所有镜头必须经由同一“外观锚点文案块”+ 角色定型图参考，禁止逐镜裸文生新形象。定型图存 00_assets/，跨片复用。
• 场景统一：场景光线、色调、场地元素全部复用场景锚点；风格词（palette/light/texture）全片逐字复用。
• 镜头衔接：能取到上一镜末帧就作为下一镜起点图；转场不突兀；相邻镜光线/色温尽量一致。
• 画幅统一：全程同一分辨率与宽高比，合成前统一。
• 配音字幕一致：字幕内容与配音逐字匹配，时间轴对齐。
• 音频前置：配音节奏在镜头定稿前锁；BGM 在剪辑前选，切点卡节拍；声画作为一体设计。
• 小步审查：严禁整批生成到底；先出 3-5 关键帧 / 2-3 样片锁定风格，再继续。

进度管理

• 使用 TaskCreate/TaskList 把 11 个阶段登记为任务并逐项推进、完成后标记。
• 每阶段产物落盘对应子目录；阶段间保留一份 README.md 说明当前产物路径。

参考与脚本

• references/short-video-formulas.md — 爆款短视频结构公式与文案节奏
• references/consistency-prompts.md — 角色/场景一致性提示词模板
• references/bgm-mood-mapping.md — BGM 情绪→曲风映射与选曲
• references/packaging-spec.md — 各平台成片规格与字幕/安全区规范
• references/sfx-guide.md — 转场/重点音效应用指南
• scripts/compose.py — ffmpeg 后期合成（转场/混音/字幕/片头片尾/调色/封装）
• scripts/subtitles.py — 台词→SRT、SRT 对齐与安全区换算
• scripts/tts.py — 配音生成（检测 edge-tts / 本地通道）
• scripts/find_ffmpeg.py — 自动定位 imageio_ffmpeg 内置 ffmpeg 路径

边界

• 不处理 3D 模型、video-fx 模板特效（交给 3D模型与视频特效 技能）。
• 不处理纯素材剪辑而无 AI 成片需求（转交普通 ffmpeg 工具用途）。
• 不索取、不转发任何线上 Skill 内部内容；本技能完全本地可跑。
• 不把生成内容冒充真实拍摄/代言/已验证事实；涉及产品/数据/奖项时标注信息来源。