| name | video-editing |
| description | Xiaohongshu/RED-tuned short-form video workflow for voice-over, talking-head, tutorials, interviews, podcasts, screen recordings, green/blue-screen compositing, B-roll, captions, and generated assets. Covers edit routing, creator-owned edit-style profiles, transcription, semantic review, multi-take/audio sync/stabilization/dead-air cleanup, highlights/shorts, story and source gates, enrichment and video-generation planning, generated clip/sequence and scoped AI video-edit review, locked-EDL final audio storyboards, phrase-level narration loudness and final channel-integrity QA, color/speed/J-L cuts, reversible revisions and recipes, preflight/render/QA including flash/photosensitivity and encode-quality screening, subtitles, CapCut, platform/size exports, covers, captions, publish packages, dashboards, handoff formats, and Remotion. |
| metadata | {"openclaw":{"emoji":"🎬","os":["darwin","linux","win32"],"requires":{"bins":"[Truncated]"},"install":["[Truncated]"]}} |
Video Editing Skill — 视频剪辑技能（V3）
适配 小红书 / 抖音 / 微信视频号 三大主流平台。一条 从素材导入 → 口播 → 重组故事 → 平台守门 → 自动丰富 → 渲染 → 三平台导出 → 标题文案 的端到端流水线，按各平台的算法、比例、时长、审核规则调过参——不只是剪辑工具。
V3 完整流水线（一图看懂）
口播音频 + 无声素材
│
├─→ project_bootstrap.py 原始素材目录 → source inventory / project.md
├─→ edit_brief_plan.py 用户一句话需求 → 本地脚本 runbook / gates
├─→ edit_style_profile.py 个人/品牌创意方向、节奏与渲染/文案默认值 → 可移植 profile
├─→ production_authorization.py
│ 确切素材/动作/provider/权利依据 → 显式授权 + live gate
├─→ transcribe.py 转写 + 词级时间戳 + 口误标记
├─→ semantic_transcript_review.py
│ 全篇前后文审校包 / 最小补丁验证 / 人工 choices gate
├─→ transcript_review.py 本地同步媒体 HTML 校稿 / CPS 提示 / review.txt 回写
├─→ takes_pack.py 多 take / Scribe transcript → phrase-level 阅读视图
│ speaker / audio_event 编辑节拍
├─→ script_alignment.py 已审目标稿 → 多 take 原话候选 / choices / render_config
│ 词/段边界 / 透明分数 / 歧义与缺素材 gate
├─→ audio_sync.py 外录音轨自动对齐 / 替换音轨计划
├─→ multicam_sync.py 多机位 → 参考时间线 / 时钟漂移证据 / 对齐预览 gate
├─→ scene_boundaries.py fixed/adaptive 视觉切点 + 逐切点 evidence
├─→ visual_dedupe.py 多来源场景 → 感知哈希重复组 / 保留建议 / review gate
├─→ video_understanding.py 抽样帧 + 可选 YOLO 检测 / tracks / scene_tags
├─→ video_stabilization.py 手持素材 → source-bound 后端计划 / 工作副本 / 全长 A/B gate
├─→ chroma_key.py 绿幕/蓝幕 → composite + matte 代表帧 / 人工 review / 完整渲染 gate
├─→ highlight_picker.py 长视频精华候选 / brief-query 定向找片段
├─→ audio_boundary_snap.py 已选片段 → 词/句末/静音边界校正
├─→ shorts_batch.py 精华候选 → per-short render_config / render + QA job sheet
├─→ rough_cut.py ASR 粗剪：去纯口头禅 / 相邻重复句
├─→ hook_variants.py 前三秒 hook 批量角度 / 推荐排序 / 风险检查
├─→ rewrite_script.py LLM 重组 5 段式（hook/pain/turn/value/cta）
├─→ content_guard.py 80+ 条平台雷区 lint
├─→ source_receipts.py 事实 claim → URL/截图 source deck + publish gate
├─→ beat_sync.py BGM beat-grid → 可审计剪辑骨架，或吸附已有切点
├─→ speed_ramp.py impact ranges → source-bound 局部变速计划 / 验证 / apply
├─→ freeze_punch.py impact frame → 定格替换窗口 / punch crop / unchanged audio timeline gate
├─→ auto_enrich.py B-roll / 章节卡 / 贴纸 / 强调点 / BGM 卡点 / imagegen 提示词
│ └─→ Codex imagegen gpt-image-2 自动生图（抽象概念配图）
├─→ audio_cue_sheet.py BGM / SFX 音频设计清单 / 生成审批 gate
├─→ storyboard_plan.py 分镜 shot cards / 生成路由 / 连续性锚点
├─→ provider_capability.py provider/surface/model 能力合同 / 核验日期 / live gate
├─→ video_prompt_pack.py Dreamina/Veo/LTX/Wan/Sora 提示词包 / 审批 + capability gate
├─→ reference_frame_preflight.py
│ 首帧/style key 尺寸/方向/透明背景/画幅 gate
├─→ generation_task_log.py 异步生成任务台账 / submit_id / 下载 gate
├─→ generated_clip_review.py 生成片段 contact sheet / 常识物理 / 连续性 / 重生 gate
├─→ generated_motion_window.py
│ 短生成片 0.25s freeze → active intervals / 人工裁切 / live gate
├─→ scoped_video_edit_review.py
│ 原片 vs 局部 AI 编辑结果 / change-only + preserve invariants / A-B gate
├─→ generated_sequence_review.py
│ 已审片段相邻尾帧/首帧/预览 / 跨镜头连续性 gate
├─→ final_audio_storyboard.py
│ 锁定视觉 EDL + 原 storyboard → 最终声音分镜 / voice ledger / live gate
├─→ narration_loudness_qa.py 最终独立旁白 + 精确短语范围 → LUFS/spread/dBTP/LRA live gate
├─→ generation_lessons.py 已审片段 → provider/model scoped 提示词经验库
├─→ storyboard_assets.py 素材任务清单 / ready 预检 / paid 额度提醒
│ 可选 media_library.py recommend 排名 B-roll 候选
├─→ stock_material_plan.py 远程 stock 搜索规划
│ Pexels / Pixabay / Coverr 查询计划 + 素材登记提示
├─→ screen_focus.py 录屏点击/热点 → 自动聚焦计划
├─→ pip_overlay.py 录屏 + facecam → PIP 小窗计划
├─→ color_grade.py bounded 调色 plan / render_final 单次编码接入
├─→ jump_cut.py 自适应去停顿 + 20% 删除预算 + 可审计 cut list + 30ms 防爆音 fade
├─→ multimodal_dead_air.py 静音 AND 静帧 → source-bound 保守删段 / 单次编码 / live gate
├─→ audio_transition.py 显式 J-cut/L-cut → source handle / hash / 1× 试听 gate
├─→ edit_revision.py 文本剪辑 artifact → source-bound 审批 / 成组 apply / undo / redo
├─→ edit_recipe.py 已审 render_config → typed-slot 可移植配方 / 新素材绑定回放
├─→ edit_preflight.py render_config/enrich_plan/cut list 渲染前预检 gate
├─→ platform_safe_area_qa.py 字幕/PIP/CTA/marker → 平台 UI 安全区 gate + SVG guide
├─→ subtitle_style_preview.py 真实源帧 → 最终 ASS 预设对比 JPEG / 选择 / live gate
├─→ render_final.py 单次编码渲染（可选口播降噪 + enrich_plan/focus_events/pip_overlays + Heavy 字幕 + 响度规范化 + BGM ducking）
│ 可选 --versioned-output 防覆盖旧成片
├─→ render_qa.py 渲染后黑屏/静帧/静音/尺寸质检 + review packet
├─→ encode_quality_qa.py 同时间线 master vs 重编码件 → SSIM/PSNR / 最差帧 / live gate
├─→ audio_channel_qa.py 成片声道活动/起始/平衡/相位/mono fold-down live gate
├─→ flash_safety_qa.py 成片亮度/饱和红 flash → 1s/5s 风险窗口 / live gate
├─→ temporal_artifact_qa.py 单帧/少数帧 return-to-state spike → 三帧证据 / 人工 audit / live gate
├─→ shot_color_qa.py 成片镜头亮度/对比/色度/饱和度/broadcast-range + 切点跳变 gate
├─→ retention_rhythm_qa.py 成片 hook 活动 / 长镜头 / 注意力空窗 / 节奏 gate
├─→ reference_edit_rhythm.py 参考片 vs 成片 hard-cut 结构 / contact sheets / live gate
├─→ speech_continuity_qa.py 成片二次 ASR → 切点复读 / 近重复 take / 句内口吃 gate
├─→ lip_sync_review.py 最终 master → 1×/0.25× 口型证据 / 人工 audit / live gate
├─→ review_proxy.py 低码率完整审片 MP4 / 可见时间码 / faststart
├─→ timeline_view.py 源素材删除段 / 成片输出切点 filmstrip + waveform 复盘图
├─→ edit_compare.py 原片连续时钟 vs 最终像素 / 删段置黑 / 映射验证
├─→ subtitle_pack.py SRT/VTT/ASS/JSON 字幕交付包（speed/offset 对齐）
├─→ subtitle_readability_qa.py
│ 最终字幕 CPS / 时长 / 行长 / 重叠 / 媒体越界 gate
├─→ import_capcut_subtitles.py
│ 剪映/CapCut 自动字幕 → transcript / gap cut list
├─→ srt_edit_plan.py SRT + keep/drop 编辑指令 → render_config / cut list
├─→ project_resume.py 续跑上下文包 / agent handoff / 可选 CLAUDE.md
├─→ review_dashboard.py 静态 HTML/JSON 人工复核面板 / gate review queue
├─→ export_edl.py render_config / cut list → EDL + manifest
├─→ export_fcpxml.py render_config / cut list → FCPXML + manifest
├─→ export_otio.py render_config / cut list → OTIO + manifest
├─→ framing_preview.py master → 各平台 cover/contain/blur 真实帧 / 选择 / live gate
├─→ multi_export.py 已审画幅策略 → 小红书 3:4 / 抖音 9:16 / 视频号 ≤60s
├─→ hdr_sdr.py PQ/HLG HDR → source-bound Rec.709 SDR / 完整解码 gate
├─→ delivery_encode.py source-bound 两遍 H.264/AAC / 硬大小上限 / 完整解码 gate
├─→ generate_caption.py 标题 + 200-500 字正文 + 3-6 tags + 发布时段
├─→ cover_variants.py 2-4 套封面 / feed-size 预览 / 最终选择 gate
├─→ approval_receipt.py 已复核交付件 → SHA-256 收据 / stale approval gate
└─→ publish_package.py 平台视频/封面/字幕/章节/文案上传包 + gate 状态
每天做一条短视频的完整提示词模板：docs/prompts/15-xhs-daily-tech-video.md（推荐入口）。
生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。
V3 新增脚本一览（按调用顺序）
| 脚本 | 职责 | 关键 CLI |
|---|
project_bootstrap.py | 原始素材目录 → 项目结构 / source inventory / project.md | --source raw_dir --project-dir work/day61 `--mode copy |
edit_brief_plan.py | 自然语言剪辑需求 → 本地脚本 runbook / 命令 / manifest gate | --brief --brief-file --source-media --platform --markdown --strict |
edit_style_profile.py | 个人/品牌创意方向、剪辑节奏、渲染/文案默认值 → 无路径可移植 profile / digest 验证 / defaults-only 合并 | template / create --spec / verify --profile --strict / apply --config --receipt |
production_authorization.py | 外部上传、侵入性剪辑、付费生成、声音克隆、真人/IP 和发布 → source-bound 授权 gate | prepare --scope --response-template / audit --request --response --strict / verify --report --strict |
transcript_review.py | transcript → 文本或本地同步媒体 HTML 校稿 → reviewed transcript | export / html --video --max-cps / apply --review --output |
semantic_transcript_review.py | transcript → 前后文审校包 / 最小补丁审计 / 人工 choices / reviewed transcript | prepare / audit --strict / apply --choices |
_internal_text_guard.py | 拦截内部 token 进画面 | 内部模块，render_final 自动调 |
content_guard.py | 平台雷区 lint | --script --title --caption --strict |
source_receipts.py | 事实 claim → URL/截图 proof deck、Markdown/HTML 和发布 gate | --claims source_claims.json --html --require-primary-source --strict |
|
V3 新增 render_final.py 标志位
| 标志 | 默认 | 说明 |
|---|
--profile tech_pro | 关 | 加载 scripts/profiles/tech_pro.yaml 的节奏/字幕/BGM 默认值 |
--style-profile work/edit_style_profile.json | 关 | 验证个人/品牌剪辑风格档案，仅填充 config 中缺失或 null 的受控字段 |
--primary-speed 1.25 | 1.0 | 主输出速度。--speed 仍可加额外变种 |
--no-loudnorm | 不传 = 开启响度规范化 | 关闭 dynaudnorm + acompressor + loudnorm |
| `--speech-denoise light | medium | strong` |
--no-content-guard | 不传 = 开启 lint | 关闭平台规则检查（不推荐） |
--subtitle-style karaoke | normal | 逐词卡拉 OK 字幕 |
--enrich-plan work/enrich_plan.json | 关 | 可重复传入；自动接入 B-roll / 章节卡 / 贴纸 / 生成图 / focus_events / pip_overlays |
--color-grade work/color_grade.json | 关 | 接入 color_grade.py 输出或 preset，放在字幕/HUD 前 |
--bgm-ducking | 关 | 用最终旁白轨触发 FFmpeg sidechain，动态压低 BGM；--no-bgm-ducking 可覆盖 config |
--versioned-output | 关 | 输出到下一个 <name>_V<N>.mp4，避免覆盖上一版成片 |
V3 Day58 production 教训（已编码进默认行为）
| 教训 | V3 怎么解决 |
|---|
顶部漏 1.25x 这种内部 token | _internal_text_guard 自动拒绝，规则在 scripts/_internal_text_guard.py |
| 字幕 Hiragino W3 太细 | find_chinese_font() 默认排序：Source Han Sans Heavy > Smiley Sans > STHeiti Medium > PingFang Semibold |
| 加速后中段听不清 | render_final 默认 dynaudnorm=f=250:g=15 + acompressor=threshold=-18dB:ratio=3 + loudnorm=I=-16:TP=-1.5:LRA=11 |
1.25× 想做主输出但 --speed 还留 1.0× | 新增 --primary-speed 一等公民 |
| 字幕里 Whisper 错词（ChatGPTT 等） | rewrite_script.py 走清稿优先，原 Whisper 词只供时间戳 |
| 平台违规词被发现才知道（限流） | content_guard.py 渲染前自动 lint |
旧版（V2）参考资料
下面是 V2 时代的工作流文档。仍然有效，但日常使用推荐先看 docs/prompts/15。
Prerequisites（前置要求）
在执行任何操作之前，先运行环境检测：
python3 scripts/utils.py
这会自动检测平台（macOS/Linux/WSL/Windows）、GPU 类型、可用编码器、Whisper 引擎，并给出诊断报告。
Prerequisites（前置要求）
在执行任何操作之前，先运行环境检测：
python3 scripts/utils.py
这会自动检测平台（macOS/Linux/WSL/Windows）、GPU 类型、可用编码器、Whisper 引擎，并给出诊断报告。
如果缺少依赖，提示用户安装：
- ffmpeg:
brew install ffmpeg（macOS）或 apt install ffmpeg（Linux/WSL）或下载 Windows 版本
- whisper:
- Apple Silicon (M1/M2/M3/M4):
pip install mlx-whisper（推荐，Metal 加速最快）
- NVIDIA / CPU:
pip install faster-whisper（推荐，速度快 4 倍）或 pip install openai-whisper
- 中国用户加速安装（Apple Silicon）：
pip install mlx-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple
其他平台：pip install faster-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple
如果项目根目录有 .venv 虚拟环境，运行 Python 脚本前先激活：
source .venv/bin/activate # macOS/Linux/WSL
# Windows: .venv\Scripts\activate
平台说明
- macOS (Apple Silicon): 自动使用 VideoToolbox 硬件编码加速；Whisper 引擎自动选
mlx-whisper（已安装），推荐 large-v3-turbo 模型（走 mlx-community/whisper-large-v3-turbo）
- 字幕字体（短视频）: 默认优先选 Heavy / Medium 字重的中文字体：用户库的
Source Han Sans SC Heavy / Smiley Sans > 系统 STHeiti Medium > PingFang SC Semibold。如果都没有，会自动从 adobe-fonts/source-han-sans 下载 Heavy 字重缓存到 ~/.cache/video-editing/fonts/。绝不再默认使用 Hiragino W3 这类细字
- macOS (Intel): 使用 VideoToolbox 编码，Whisper 使用 CPU 模式
- Linux: 自动检测 NVIDIA GPU (NVENC)、Intel QSV、AMD AMF
- WSL: 支持，自动检测 Windows 字体路径 (
/mnt/c/Windows/Fonts/)
- Windows: 建议使用 WSL2 环境运行；支持 QSV/AMF 硬件编码
- 无独显 (集成显卡): Intel iGPU 使用 QSV 编码，AMD iGPU 使用 AMF 编码；Whisper 建议 medium 模型（而非 large）
- 中国用户: 自动检测中国区域，使用清华 pip 镜像和 HuggingFace 镜像下载模型，也可通过
--mirror 参数强制启用
Linux GPU 配置指南（NVIDIA / Intel Arc）
在 Linux 上使用 GPU 加速 Whisper 语音识别时，不同显卡需要不同的配置方案。运行 python3 scripts/utils.py 会自动检测显卡型号并给出建议，但如果遇到问题，请参考以下方案。
方案 A：NVIDIA 40 系列显卡（RTX 4060 / 4070 / 4080 / 4090）
40 系列（Ada Lovelace 架构，Compute Capability 8.9）对 faster-whisper 支持最成熟，开箱即用。
安装步骤：
# 1. 安装 NVIDIA 驱动（535+）和 CUDA Toolkit 12.4+
sudo apt install nvidia-driver-535 nvidia-cuda-toolkit
# 或从 NVIDIA 官网安装最新驱动：https://www.nvidia.com/drivers
# 2. 验证 CUDA
nvidia-smi # 应显示驱动版本和 CUDA 版本
# 3. 安装 faster-whisper（自动安装匹配的 CTranslate2）
pip install faster-whisper>=1.1.0
配置说明：
- CUDA Toolkit: 12.4+（推荐 12.6）
- CTranslate2: >= 4.5.0（自动随 faster-whisper 安装）
- 计算精度:
float16（默认）, int8_float16, int8 均可使用
- Whisper 模型: 推荐
large-v3（VRAM >= 6GB）
- 无需特殊配置，
python3 scripts/transcribe.py 会自动检测并使用 CUDA
方案 B：NVIDIA 50 系列显卡（RTX 5060 / 5060 Ti / 5070 / 5080 / 5090）
50 系列（Blackwell 架构，Compute Capability 12.0，sm_120）需要额外注意 CUDA 版本和计算精度设置。
已知问题：
CTranslate2 在 Blackwell 架构上使用 INT8 精度时会报错 cuBLAS failed with status CUBLAS_STATUS_NOT_SUPPORTED，
这是因为 Blackwell 的 INT8 Tensor Core 需要矩阵维度为 16 的倍数对齐。CTranslate2 >= 4.7.1 已修复此问题，
但为保险起见，本工具在检测到 50 系列显卡时会自动使用 float16 精度。
安装步骤：
# 1. 安装 NVIDIA 驱动（565+，必须支持 Blackwell）
# 从 NVIDIA 官网下载最新驱动：https://www.nvidia.com/drivers
# 或使用包管理器安装 565 以上版本
sudo apt install nvidia-driver-565
# 2. 安装 CUDA Toolkit 12.8+（Blackwell 最低要求）
# 推荐从 NVIDIA 官网安装：https://developer.nvidia.com/cuda-downloads
# 选择 Linux > x86_64 > Ubuntu > deb (network)
# 3. 验证 CUDA
nvidia-smi # 应显示 CUDA 12.8+
# 4. 安装 faster-whisper 和最新 CTranslate2
pip install faster-whisper>=1.1.0
pip install --upgrade ctranslate2>=4.7.1 # 确保包含 Blackwell 修复
# 5. 如果仍然报错，强制使用 float16 精度（本工具已自动处理）
# 手动测试：
python3 -c "
from faster_whisper import WhisperModel
model = WhisperModel('tiny', device='cuda', compute_type='float16')
print('CUDA float16 OK')
"
配置说明：
- CUDA Toolkit: >= 12.8（推荐 13.0+，最新为 13.2）
- NVIDIA 驱动: >= 565
- CTranslate2: >= 4.7.1（包含 INT8 padding 修复）
- 计算精度: 推荐
float16（最稳定）；int8_float16 在 CTranslate2 >= 4.7.1 上可能可用
- 如果
int8 仍然报错，工具会自动降级到 float16
- Whisper 模型: 推荐
large-v3（VRAM >= 6GB）
utils.py 会自动检测 50 系列显卡（通过 nvidia-smi 查询 GPU 名称中的 "RTX 50"），并选择安全的 float16 精度
排错：
如果出现 CUBLAS_STATUS_NOT_SUPPORTED 错误：
- 确认 CTranslate2 版本 >= 4.7.1：
python3 -c "import ctranslate2; print(ctranslate2.__version__)"
- 确认 CUDA 版本 >= 12.8：
nvidia-smi 或 nvcc --version
- 尝试手动指定
--compute-type float16（如果直接使用 transcribe.py 的话）
- 确认驱动版本 >= 565：
nvidia-smi 查看 Driver Version
方案 C：Intel Arc 独立显卡（A770 / A750 / B580）
Intel Arc 显卡不支持 CUDA，因此 faster-whisper（依赖 CTranslate2/CUDA）无法直接在 Intel Arc 上 GPU 加速。
需要使用替代方案。
推荐方案：OpenVINO + Whisper（最易用）
# 1. 安装 OpenVINO
pip install openvino openvino-genai
# 2. 使用 OpenVINO GenAI 的 WhisperPipeline
python3 -c "
import openvino_genai as ov_genai
pipe = ov_genai.WhisperPipeline('OpenVINO/whisper-large-v3-fp16-ov', device='GPU')
result = pipe.generate('audio.wav', language='<|zh|>')
print(result.texts[0])
"
# 3. 或使用 Hugging Face 预转换模型
pip install optimum[openvino]
# 从 HuggingFace 下载 OpenVINO 格式 Whisper 模型
# https://huggingface.co/OpenVINO/whisper-medium-int8-ov
备选方案：whisper.cpp + SYCL（性能更好，配置更复杂）
# 1. 安装 Intel oneAPI Base Toolkit
# https://www.intel.com/content/www/us/en/developer/tools/oneapi/base-toolkit-download.html
wget -O- https://apt.repos.intel.com/intel-gpg-keys/GPG-PUB-KEY-INTEL-SW-PRODUCTS.PUB \
| gpg --dearmor | sudo tee /usr/share/keyrings/oneapi-archive-keyring.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/oneapi-archive-keyring.gpg] \
https://apt.repos.intel.com/oneapi all main" \
| sudo tee /etc/apt/sources.list.d/oneAPI.list
sudo apt update && sudo apt install intel-oneapi-base-toolkit
# 2. 编译 whisper.cpp（启用 SYCL 后端）
source /opt/intel/oneapi/setvars.sh
git clone https://github.com/ggml-org/whisper.cpp.git
cd whisper.cpp
cmake -B build -DWHISPER_SYCL=ON
cmake --build build --config Release
# 3. 下载 Whisper 模型并运行
./build/bin/whisper-cli -m models/ggml-large-v3.bin -f audio.wav -l zh
配置说明：
- Intel Arc 不支持 CUDA，faster-whisper 在 Intel Arc 上只能用 CPU 模式
- OpenVINO 方案最简单，支持 Arc A770/A750/B580 和集成显卡
- whisper.cpp + SYCL 性能更好（A770 上接近 NVIDIA 中端显卡水平），但需要 oneAPI 环境
- B580（Battlemage 架构）的 SYCL 支持尚在优化中，A770 目前更稳定
- 推荐 Whisper 模型:
medium（12GB VRAM 的 A770）或 small（8GB VRAM 的 A750）
- 如果用户有 Intel Arc 显卡，脚本会自动检测并使用 CPU 模式运行 faster-whisper（作为 fallback）
GPU 配置速查表
| 显卡系列 | 架构 | CUDA Toolkit | 驱动版本 | CTranslate2 | 计算精度 | Whisper 引擎 |
|---|
| RTX 40xx | Ada Lovelace (sm_89) | >= 12.4 | >= 535 | >= 4.5.0 | float16 / int8 均可 | faster-whisper |
| RTX 50xx | Blackwell (sm_120) | >= 12.8 | >= 565 | >= 4.7.1 | float16（推荐） | faster-whisper |
| Intel Arc | Xe HPG / Battlemage | N/A | i915 | N/A | N/A | OpenVINO 或 whisper.cpp+SYCL |
| Intel iGPU | 集成显卡 | N/A | i915 | N/A | int8 (CPU) | faster-whisper (CPU 模式) |
| 无独显 | CPU | N/A | N/A | 任意版本 | int8 (CPU) | faster-whisper (CPU 模式) |
Workflow（工作流程）
Phase 0a: Project Bootstrap（项目启动 / 原始素材导入）
当用户给的是一个原始素材文件夹、下载目录或一组还没整理的素材时，先用 project_bootstrap.py 建立稳定项目结构，而不是直接在外部原始路径上剪辑：
python3 scripts/project_bootstrap.py \
--source ~/Downloads/raw-shoot \
--project-dir work/day61 \
--title "Day61 launch edit" \
--output work/day61/work/source_inventory.json \
--markdown work/day61/work/source_inventory.md \
--project-note work/day61/project.md \
--strict
输出：
origin/raw|broll|audio|bgm|images|assets|sidecars/：项目内 working copy。work/source_inventory.json：project_bootstrap.v1，记录外部 source_path、项目内 project_path、分类、动作和 next actions。work/source_inventory.md：给人审的素材清单。project.md：跨会话项目记忆。next_steps.md：下一步命令清单。
默认 --mode copy，同名文件自动加后缀，不覆盖。大素材同盘可用 --mode hardlink，失败会回退 copy 并写入 warning。此脚本不转码、不渲染、不上传、不调用 LLM，也不提交任何生成任务。需要把素材导入作为 analysis gate 时，跑：
python3 scripts/pipeline_manifest.py \
--project-dir work/day61 \
--target-stage analysis \
--require source_inventory \
--strict
Phase 0b: Production Authorization（按确切范围授权）
当流程涉及把素材交给外部服务、改变原始叙事顺序/删减范围、消耗生成额度、克隆真人声音、使用真人/未成年人/公众人物/品牌/IP，或直接发布时，在动作发生前先写 production_authorization_scope.v1。scope 必须命名项目内素材、具体动作、用途、exact provider/surface、可能的 cost/quota，以及适用的 rights subject；完整 schema 见 Production Authorization。
python3 scripts/production_authorization.py prepare \
--project-dir . \
--scope work/production_authorization_scope.json \
--output work/production_authorization_request.json \
--markdown work/production_authorization_request.md \
--response-template work/production_authorization_response.json \
--strict
# 逐项填写 approve/reject、note、rights basis 与 evidence_note 后：
python3 scripts/production_authorization.py audit \
--project-dir . \
--request work/production_authorization_request.json \
--response work/production_authorization_response.json \
--output work/production_authorization.json \
--markdown work/production_authorization.md \
--strict
python3 scripts/production_authorization.py verify \
--project-dir . \
--report work/production_authorization.json \
--strict
prepare 绑定 scope 与每个 source asset 的相对路径、大小和 SHA-256；audit 要求动作与权利项完整逐项决定；verify 现场重读 scope、素材、request、response 并重算 report。任一 provider、用途、成本说明、权利对象、素材字节或决定变化都会让旧报告失效。该 artifact 只记录本地、自报的复核范围，不执行上传/剪辑/生成/发布，也不替代身份认证、数字签名、真实授权文件或法律意见。
Phase 0: Media Library Setup（素材库初始化）
首次使用时，帮助用户建立素材目录结构：
python3 scripts/media_library.py init [project_dir]
这会创建以下目录结构：
media/
├── raw/ — 原始素材（摄像机/手机直出的视频）
├── broll/ — B-roll 素材（城市街景、产品特写等）
├── bgm/ — 背景音乐（MP3/WAV/M4A）
├── assets/ — 叠加素材（水印 PNG、Logo 等）
└── output/ — 输出目录
询问素材来源：
- 询问用户的视频文件位置（本地路径、外部设备或云端）
- 建议将原始素材复制/移动到
media/raw/ 目录
- 询问是否有 B-roll、BGM 等辅助素材
- 如果用户视频散落在多个目录，建议先集中到
media/raw/
扫描并建立索引：
python3 scripts/media_library.py scan [project_dir]
索引系统会自动：
- 扫描所有视频/音频/图片文件
- 提取时长、分辨率、帧率等元数据
- 关联已有的 transcript 文件
- 小型项目（< 200 文件）使用 JSON 索引（
media_index.json）
- 大型项目自动升级为 SQLite 索引（
media_index.db）
- 手动升级：
python3 scripts/media_library.py upgrade
查看素材库状态：
python3 scripts/media_library.py status
搜索素材：
python3 scripts/media_library.py search "关键词"
推荐 B-roll 候选：
python3 scripts/media_library.py recommend "AI workflow dashboard" \
--project-dir . \
--category broll \
--target-duration 3 \
--target-aspect 9:16 \
--json
推荐结果包含 score、reasons、absolute_path，用于人工/agent 先确认再写入 render_config 或 enrich_plan。默认过滤已经不存在的索引文件；需要清理 stale index 时可加 --include-missing。
本地素材不足时规划 stock 查询：
python3 scripts/stock_material_plan.py \
--subject "AI workflow automation" \
--script work/transcript.json \
--provider pexels \
--provider pixabay \
--provider coverr \
--media-library . \
--output work/stock_material_plan.json \
--markdown work/stock_material_plan.md
stock_material_plan.py 只生成 stock_material_plan.v1 和 Markdown review，不联网、不下载、不消耗额度。它借鉴 MoneyPrinterTurbo 的 video_terms / Pexels / Pixabay / Coverr / video_count 素材规划方式，但保持本 skill 的 artifact-first 风格。
下载或客户给的素材确认授权后登记：
python3 scripts/media_library.py import /path/to/downloaded.mp4 \
--project-dir . \
--category broll \
--copy \
--provider pexels \
--source-url "https://www.pexels.com/video/demo-123/" \
--creator "Demo Creator" \
--license "Pexels License" \
--tag "workflow,dashboard"
python3 scripts/media_library.py annotate media/broll/downloaded.mp4 \
--project-dir . \
--source-url "https://example.com/source" \
--license "owned" \
--tag "client-approved"
登记后的 provider、source_url、creator、license 会进入 media_index.json/db，后续由 asset_provenance.py 做发布门禁。
Phase 0.25: Creator-owned Edit Style Profile（个人/品牌剪辑风格，可选）
当用户希望多个项目保持同一套创意方向、剪辑节奏、字幕/封面/调色/BGM 习惯和标题拼写时，先生成并人工编辑 spec，再创建可移植 profile：
python3 scripts/edit_style_profile.py template \
--output work/edit_style_profile_spec.json
# 编辑 spec 中的真实偏好和 approval basis 后：
python3 scripts/edit_style_profile.py create \
--spec work/edit_style_profile_spec.json \
--output work/edit_style_profile.json \
--markdown work/edit_style_profile.md \
--strict
python3 scripts/edit_style_profile.py verify \
--profile work/edit_style_profile.json \
--strict
渲染时加 render_final.py --style-profile work/edit_style_profile.json；生成标题文案和封面时，分别给 generate_caption.py 和 cover_variants.py 加同一参数。Profile 只填充 config 中缺失或 null 的受控字段；项目 config 和显式 CLI（包括封面 --style）始终优先。它描述“通常怎么剪”，而 edit_recipe.py 保存“这条时间线怎么复刻”，两者不互相替代。Profile 的 digest 只能发现文件漂移，不是签名、身份认证或权利证明。完整用法见 docs/prompts/98-edit-style-profile.md。
Phase 0.5: Source Receipts（事实来源 proof deck，可选但推荐）
如果视频包含新闻、数据、产品事实、健康/金融/法律判断、来源页截图或“官方说法”，在进入分镜/发布前先把 claim 和证据落成 source receipts：
python3 scripts/source_receipts.py \
--claims work/source_claims.json \
--project-dir . \
--output work/source_receipts.json \
--markdown work/source_receipts.md \
--html work/source_receipts.html \
--require-primary-source \
--strict
source_receipts.py 只验证已提供的 URL 和本地截图/证据文件；不联网抓取、不截图、不上传。source_claims.json 里的 screenshot / source_file 相对 claims JSON 所在目录解析。新闻、数据、金融、健康、法律等高风险 claim 必须有 source_url；需要视觉 proof card 时加 --require-screenshot。发布门禁可用 pipeline_manifest.py --require source_receipts --strict 强制检查，summary.blocking > 0 会阻塞。
Phase 1: Audio Extraction（音频提取）
对每个输入视频文件，使用 extract_audio.py 提取音频：
python3 scripts/extract_audio.py "<video_path>"
输出：与视频同目录下的 <video_name>_audio.wav 文件。
Phase 2: Speech Recognition（语音识别）
使用 transcribe.py 对音频进行语音识别，生成带时间戳的逐句文本：
python3 scripts/transcribe.py "<audio_path>" --model auto --language zh --detect-fillers
--model auto：根据硬件自动选择最佳模型（NVIDIA GPU → large-v3，Apple Silicon → large-v3-turbo，集成显卡 → medium，纯 CPU → small）- 也可手动指定：
tiny, base, small, medium, large-v3, large-v3-turbo
--engine auto：自动检测 faster-whisper（推荐）或 openai-whisper--mirror：中国用户使用镜像源下载模型--language：zh（中文），en（英文），ja（日文）等，也可省略让 whisper 自动检测--silence-threshold 1.0：静音检测阈值（秒），默认 1.0。设为 0 关闭--word-timestamps：启用逐词时间戳（卡拉OK字幕必需）--detect-fillers：检测填充词（中文：嗯/呃/那个/就是说；英文：um/uh/like/you know），标记纯填充词片段为建议跳过
输出：与音频同目录下的 <video_name>_transcript.json 文件，格式如下：
{
"segments": [
{"id": 1, "start": 0.0, "end": 2.5, "text": "大家好"},
{"id": 2, "start": 2.5, "end": 5.1, "text": "今天我们来聊一个话题"}
],
"silences": [
{"start": 15.2, "end": 18.5, "duration": 3.3, "before_segment": 5, "after_segment": 6}
],
"filler_words": [
{"segment_id": 3, "text": "嗯那个", "fillers_found": ["嗯", "那个"], "is_filler_only": true},
{"segment_id": 7, "text": "就是说我觉得这个方案", "fillers_found": ["就是说"], "is_filler_only": false}
]
}
静音检测：transcribe.py 会自动分析相邻语音片段之间的间隙。超过阈值（默认 1 秒）的间隙会被标记为静音并输出到 silences 字段中。这些静音通常是说话人的停顿、卡壳或口误，在构建 render_config.json 选片时应注意避开这些区域。
Phase 2a: Video Keyframe Extraction（视频关键帧提取）
对于口播类视频（尤其是在户外行走中拍摄的、带有环境音的素材），仅靠音频转录无法了解视频的视觉内容。使用 extract_keyframes.py 提取视频关键帧并生成时序图，以便全面理解视频内容：
python3 scripts/extract_keyframes.py "<video_path>"
参数说明：
--max-frames 16：最大关键帧数量（默认 16）--threshold 0.4：场景变化检测灵敏度（0.0-1.0，越低提取越多关键帧，默认 0.4）--cols 4：时序图网格列数（默认 4）--thumb-width 320：缩略图宽度（默认 320px）--output-dir：关键帧输出目录（默认 <video_name>_keyframes/）--no-storyboard：仅提取关键帧，不合成时序图
输出：
<video_name>_keyframes/ — 各关键帧 PNG 图片（带时间戳命名）<video_name>_storyboard.png — 合成的时序图（网格布局 + 时间戳标注）<video_name>_keyframes.json — 关键帧元数据（时间戳、帧号、文件路径）
为什么需要关键帧提取：
- 口播视频经常在走路中拍摄，画面中的场景变化（街道→公园→咖啡店）是重要的叙事线索
- 时序图让 AI 可以同时看到音频内容（transcript）和视觉内容（keyframes），做出更好的选片判断
- 可以发现纯音频分析无法捕捉的信息：肢体语言、表情变化、环境切换、产品展示等
典型工作流：
# 1. 提取音频并转录
python3 scripts/extract_audio.py video.mp4
python3 scripts/transcribe.py video_audio.wav --model auto --language zh --detect-fillers
# 2. 提取关键帧生成时序图
python3 scripts/extract_keyframes.py video.mp4
# 3. AI 结合 transcript + storyboard 进行综合分析
# → 查看 video_storyboard.png 了解视频画面内容
# → 对照 video_transcript.json 了解语音内容
# → 综合判断哪些片段最适合保留
AI Agent 综合分析要点：
- 将关键帧时序图与转录文本对照，标注每个时间段的「说了什么 + 画面是什么」
- 找出画面与语音最匹配的高质量片段（如：讲到"这家店"时画面正好对着店铺）
- 识别画面模糊、遮挡、光线不佳的片段，建议跳过
- 户外拍摄时，注意画面抖动严重的片段，在选片时降低优先级
Phase 2a: Adaptive Scene Boundaries（自适应视觉场景边界）
长视频拆条、抽样理解或成片节奏分析前，优先为运动镜头生成自适应场景边界：
python3 scripts/scene_boundaries.py video.mp4 \
--method adaptive \
--adaptive-threshold 3.0 \
--min-scene-score 0.15 \
--min-scene-duration 1.0 \
--output work/scene_boundaries.json \
--markdown work/scene_boundaries.md
adaptive 把每帧 FFmpeg scene score 与前后邻域均值比较，可减少持续摇镜、运动或闪烁造成的密集误切；boundary_evidence[] 保留 score、adaptive ratio 和邻域均值，必须先看 Markdown 再交给 highlight_picker.py --scene-boundaries。需要复现旧流程或固定机位素材时，用 --method fixed --threshold 0.35。
Phase 2b: Visual Dedupe（跨素材重复镜头复核）
多机位、多 take、重复转码或 B-roll 候选进入时间线前，用 visual_dedupe.py 对多个 source 的场景做三点感知哈希复核：
python3 scripts/visual_dedupe.py \
--manifest work/visual_dedupe_sources.json \
--output work/visual_dedupe.json \
--markdown work/visual_dedupe.md \
--strict
manifest 的 sources[] 为每个来源提供 id、video、可选 scene_boundaries 和 quality_score；相对路径以 manifest 目录为基准。脚本默认只比较不同来源，要求 10%/50%/90% 至少两个采样点匹配，并把 quality_score、分辨率和文件大小用于保留建议。它只输出 review artifact，绝不删除或移动源素材。发现重复组时，先人工查看 source range，再从下游 edit plan 排除确认重复的候选。
Phase 2c: Video Understanding（抽样帧 + 可选 YOLO）
当素材里的人、手机、电脑屏幕、产品、车辆或其他动态对象会影响裁切、隐私遮挡或 B-roll 选择时，使用 video_understanding.py 生成结构化视觉理解 artifact。默认不需要安装 detector；如果要运行 YOLO，先安装可选依赖 ultralytics。
# 无 detector：只抽样帧并生成 review shell
python3 scripts/video_understanding.py video.mp4 \
--output work/video_understanding.json \
--markdown work/video_understanding.md
# 可选 YOLO：检测对象并生成 detections/tracks/scene_tags
pip install ultralytics
python3 scripts/video_understanding.py video.mp4 \
--scene-boundaries work/scene_boundaries.json \
--detector yolo \
--model yolo11n.pt \
--output work/video_understanding.json \
--markdown work/video_understanding.md \
--strict
输出：
video_understanding.json — video_understanding.v1，包含 frames[]、detections[]、tracks[]、scene_tags[]、warnings[]video_understanding.md — 人工 review 表，列出抽样帧、检测数量、轨迹、标签和 warning
典型下游：
python3 scripts/smart_reframe.py video.mp4 \
--detections work/video_understanding.json \
--platform douyin \
--output work/reframe_douyin.json \
--markdown work/reframe_douyin.md
python3 scripts/privacy_redact.py \
--video video.mp4 \
--detections work/video_understanding.json \
--output work/privacy_redaction.json \
--markdown work/privacy_redaction.md
注意：内置 tracklets 是为口播剪辑做的轻量关联，不等同于逐帧多目标跟踪。对体育、车流、多人遮挡等高动态素材，可以用 Ultralytics model.track(..., tracker="bytetrack.yaml")、BoT-SORT 或 Norfair 生成更密集的检测/track 结果，再转换成同一份 detections[] / tracks[] JSON。
Phase 2.5: Transcript Review（转录文字校验）
转录完成后，必须对所有 transcript.json 中的文字进行逐条审查，修正以下两类问题：
1. 语音识别错误（ASR errors）：
Whisper 常见的识别错误类型：
- 专有名词/产品名：如 "opencloud" → "OpenClaw"、"cloudcode" → "Claude Code"、"cloud ops" → "Claude Opus"
- 同音字错误：如 "小红树" → "小红书"、"检映" → "剪映"、"断耕" → "断更"、"懒得讲" → "懒得剪"
- 英文拼写：如 "scale" → "skill"、"箱子" → "视频"
- 尾部幻觉：Whisper 有时在安静片段末尾生成无意义的重复文字，应直接删除
2. 口误标记（Speaker errors）：
- 重复/卡壳：说话人重复说同一句话或卡住后重新说，标记为可跳过
- 乱码片段：语音模糊导致识别为无意义文字的片段（如连续的单字碎片），标记为可跳过
专业术语、人名、同音字或中英混说较多时，先运行 semantic_transcript_review.py prepare，让当前 Agent/模型填写 provider-neutral response；再运行 audit。不要把模型 confidence 当批准：从 audit Markdown 复制绑定 source_sha256 + review_id 的 choices 模板，逐项 approve / reject 后才运行 apply。audit 会从源 transcript 推导完整覆盖率，并拒绝整句润色、非最小字符补丁、数字/标点变化、越界/重叠补丁和旧 transcript hash。成功 apply 后，把 transcript_semantic_reviewed.json 交给下面的同步媒体 HTML 继续听审；详见 docs/prompts/79-semantic-transcript-review.md。
python3 scripts/semantic_transcript_review.py prepare \
--transcript work/transcript.json \
--output work/semantic_review_request.json \
--markdown work/semantic_review_request.md
python3 scripts/semantic_transcript_review.py audit \
--transcript work/transcript.json \
--response work/semantic_review_response.json \
--output work/transcript_semantic_review.json \
--markdown work/transcript_semantic_review.md \
--strict
python3 scripts/semantic_transcript_review.py apply \
--transcript work/transcript.json \
--audit work/transcript_semantic_review.json \
--choices work/semantic_review_choices.json \
--output work/transcript_semantic_reviewed.json
校验流程：
- 用
transcript_review.py html 生成一个无外部依赖的本地页面；纯终端环境用 export 生成文本。
- 页面里点击时间码对着媒体校稿；播放时当前段自动高亮。行内编辑支持本地自动保存、查找替换和 CPS 标黄。
- 显式保存
transcript_review.txt，不要让页面或 agent 直接覆盖原始 transcript。
- 用
apply 生成 transcript_reviewed.json；后续清稿、粗剪、分镜和字幕统一使用 reviewed 文件。
- 对于口误/乱码片段，在展示片段列表时（Phase 3）标注为建议跳过。
python3 scripts/transcript_review.py html \
--transcript work/transcript.json \
--video origin/talking.mp4 \
--corrections work/corrections.json \
--output work/transcript_review.html \
--max-cps 20
python3 scripts/transcript_review.py apply \
--transcript work/transcript.json \
--review work/transcript_review.txt \
--output work/transcript_reviewed.json
HTML 和媒体只在本机打开，不上传、不调用 LLM。浏览器不能直接写文件时会下载 transcript_review.txt；把它放回 work/ 后再 apply。CPS 是预渲染提示，最终还要跑 subtitle_readability_qa.py --strict。
注意：此步骤必须在 Phase 5（渲染）之前完成，因为字幕文字来源于 transcript.json。修正后再渲染，才能保证最终视频中的字幕文字正确。
Phase 2.5a: Target Script Alignment（按确认稿装配原话，可选）
如果客户、编导或用户已经确认成片稿，而同一句话录了多个 take 或分散在不同素材里，先把目标稿按“一行一个完整 spoken unit”整理，再匹配 reviewed transcript：
python3 scripts/script_alignment.py \
--target-script work/target_script.md \
--transcript take-a=work/take-a_transcript_reviewed.json \
--transcript take-b=work/take-b_transcript_reviewed.json \
--media take-a=origin/take-a.mp4 \
--media take-b=origin/take-b.mp4 \
--output work/script_alignment.json \
--markdown work/script_alignment.md \
--render-config work/render_config.json \
--clean-script work/clean_script.md \
--strict
脚本只做本地词面匹配，不调用 LLM、不改源文件、不判断表情/镜头/表演质量。它输出每句的稳定 candidate id、source time、原话和 sequence/coverage/ngram/length evidence；word timestamps 存在时优先收紧到词边界，只有 segment 时间戳时保守保留整段。低分、前两名过近、无候选、素材缺失或源时间重复占用会写 summary.blocking 并让 --strict 返回 2。
同文案多个 take 出现 ambiguous_match 时，必须看/听 Markdown 里的候选，把确认结果写成 {"choices":{"target-001":"<candidate-id>"}}，再用 --choices work/script_alignment_choices.json 重跑。人工 choice 只能解决词面低分/多解，不能绕过缺文件或时间重叠。summary.blocking=0 后再进入 edit_preflight.py / render_final.py；详细用法见 docs/prompts/78-script-alignment.md。
Phase 2.6: ASR Rough Cut（口头禅/重复句粗剪，可选）
如果 transcript 中纯口头禅、卡壳重说或相邻重复句较多，先用 rough_cut.py 生成可审计粗剪计划：
python3 scripts/rough_cut.py --transcript work/transcript.json --cut-list work/rough_cut.json
确认计划后可直接渲染粗剪版：
python3 scripts/rough_cut.py \
--transcript work/transcript.json \
--input origin/talking.mp4 \
--output output/talking.roughcut.mp4 \
--cut-list work/rough_cut.json
rough_cut.py 会输出 decisions / removed_segments / keep_segments / speedup_ratio。它不调用 LLM，不提交任何付费任务；只用 transcribe.py --detect-fillers 的 filler metadata 和相邻文本相似度做保守粗剪。渲染前用 timeline_view.py --cut-list work/rough_cut.json 看源素材删除段；渲染后用 --rendered-cut-list work/rough_cut.json 看成片实际拼接点。
Phase 2.6b: Multimodal Dead-Air（静音 + 静帧保守去死区，可选）
如果纯音频 jump_cut.py 可能误删仍有表情、手势、产品展示或屏幕操作的停顿，改用音频静音与画面静帧的 AND gate：
python3 scripts/multimodal_dead_air.py plan origin/talking.mp4 \
--delivery work/talking-dead-air-tight.mp4 \
--output work/multimodal_dead_air_plan.json \
--markdown work/multimodal_dead_air_plan.md \
--strict
python3 scripts/multimodal_dead_air.py verify work/multimodal_dead_air_plan.json --strict
DEAD_AIR_CUT_COUNT="$(python3 -c 'import json; print(len(json.load(open("work/multimodal_dead_air_plan.json"))["removed_segments"]))')"
python3 scripts/timeline_view.py origin/talking.mp4 \
--cut-list work/multimodal_dead_air_plan.json \
--output-dir verify/dead-air-cuts \
--limit "$DEAD_AIR_CUT_COUNT"
python3 scripts/multimodal_dead_air.py apply work/multimodal_dead_air_plan.json \
--markdown work/multimodal_dead_air_plan.md
默认只有静帧覆盖静音至少 60% 才入选，并且只删除二者交集；80ms padding、30ms 音频 fade 和 20% 删除预算继续生效。计划绑定源 SHA-256 和媒体契约，apply 使用临时 MP4，并在 H.264/AAC、yuv420p、尺寸、帧率、采样率、声道、时长和完整解码全部通过后原子提升。timeline_view.py 默认只看 20 个切点，因此必须像上面一样把本计划的实际删除段数传给 --limit；若计数为 0，停止并保留原片。它不理解表演、语义或有意留白；所有源切点仍须先看，输出仍须 1× 带声音完整复核。详见 docs/prompts/88-multimodal-dead-air.md。
Phase 3: User Interaction（用户交互）
展示片段列表给用户，格式如下：
视频片段列表：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# | 时间区间 | 内容
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
1 | 00:00.0 - 00:02.5 | 大家好
2 | 00:02.5 - 00:05.1 | 今天我们来聊一个话题
3 | 00:05.1 - 00:08.3 | 这个话题非常有意思
...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
请选择要合成的片段（示例）：
- 连续范围：1-10
- 多个片段：1,3,5,7
- 混合选择：1-4,6,8-10
如果有多个视频文件，分别展示每个视频的片段列表，让用户跨视频选择。
AI 智能选片建议
在展示片段列表时，AI agent 应基于以下维度为每个片段提供推荐评分（1-5 星）：
吸引力评分维度：
- Hook 强度（前 3 秒）：是否有吸引人的开头（提问、反直觉观点、情感触发）
- 信息密度：每秒传递的有效信息量（避免重复、废话）
- 情感变化：是否有情感起伏（幽默→严肃→惊喜）
- 完整性：片段是否构成完整叙事单元（有开头、展开、收尾）
自动跳过建议：
- transcript 中
is_filler_only: true 的片段（纯填充词）
- 静音间隙 > 2 秒的相邻片段（卡壳后重说）
- 转录文字与前一片段高度重复的片段（口误重说）
长视频自动拆短片（视频 > 3 分钟时）：
AI agent 应分析 transcript 识别话题转换点（语义断裂、过渡词如"接下来"、"另外"），将片段按话题分组为独立短视频（每个 30-90 秒），并为每组计算整体吸引力评分：
推荐短视频拆分方案：
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
方案 | 片段范围 | 时长 | 主题 | 推荐指数
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
A | #1-#8 | 45s | 痛点引入 | ★★★★★
B | #9-#18 | 62s | 核心方法 | ★★★★☆
C | #19-#25 | 38s | 实操演示 | ★★★☆☆
D | #1-#25 | 2m25s | 完整版 | ★★★★☆
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
等待用户回复选择后，进入 Phase 4。
选择完成后、批量渲染前，建议用词级时间戳校正切点，避免候选范围落在词中间或半句结尾：
python3 scripts/audio_boundary_snap.py \
--candidates work/highlight_candidates.json \
--transcript work/transcript.json \
--media origin/long-talk.mp4 \
--output work/audio_boundary_plan.json \
--markdown work/audio_boundary_plan.md \
--strict
输出 audio_boundary_plan.v1 的 selected[] 可直接传给 shorts_batch.py --highlights。脚本只读本地候选、transcript 和可选媒体；它不渲染、不上传、不调用 provider。--strict 会在缺词级时间戳、非法时间段、源媒体缺失或安全边界超平台时长时返回 2。
Phase 4: Render Config（渲染配置）
根据用户的选择，生成 render_config.json 配置文件。
重要说明：渲染配置是项目级文件
SKILL 中展示的 render_config.json 格式只是模板/参考，不要直接修改 Skill 仓库中的任何文件。每个视频项目应在用户工作目录下创建独立的渲染配置：
# 在用户的视频项目工作目录下创建 script/ 文件夹
mkdir -p script/
# 在 script/ 下为每个视频项目创建独立的渲染配置文件
# 例如：script/render_config.json
目录结构示例：
~/Videos/my-project/ ← 用户工作目录
├── script/ ← 渲染配置目录（每个项目独立）
│ └── render_config.json ← 本项目的渲染配置
├── media/
│ ├── raw/ ← 原始素材
│ ├── broll/
│ └── output/ ← 最终输出
├── *_audio.wav ← 提取的音频
└── *_transcript.json ← 转录文件
渲染配置文件格式（script/render_config.json）：
{
"clips": [
{"video": "path/to/video1.MOV", "segment_id": 4, "transcript": "path/to/transcript1.json"},
{"video": "path/to/video1.MOV", "segment_id": 5, "transcript": "path/to/transcript1.json"},
{"video": "path/to/video2.MOV", "segment_id": 1, "transcript": "path/to/transcript2.json",
"broll": "path/to/cityscape.mp4", "broll_start": 5.0}
],
"title": "封面标题文字",
"subtitle": "副标题/情感钩子（可选）",
"cover_style": "news",
"cover_duration": 2.0,
"cover_image": "path/to/custom_cover.png",
"cover_use_frame": false,
"video_overlay": "path/to/overlay.png",
"rec_blink": {
"dot_image": "path/to/dot.png",
"x": 55, "y": 66,
"period": 1.0
},
"end_cards": [
{"text": "感谢观看\n更多内容敬请期待", "duration": 3.5}
],
"bgm": "path/to/background_music.mp3",
"bgm_volume": 0.15,
"bgm_fade_out": 3.0,
"bgm_ducking": true,
"bgm_ducking_threshold": 0.03,
"bgm_ducking_ratio": 8,
"bgm_ducking_attack_ms": 20,
"bgm_ducking_release_ms": 500,
"subtitle_style": "karaoke",
"subtitle_highlight_color": "#FFFF00",
"chapters": [
{"title": "章节名", "start": 0.0, "end": 30.0}
],
"text_badges": [
{"text": "关键结论", "start": 12.0, "end": 13.5}
],
"broll_overlays": [
{"video": "path/to/cityscape.mp4", "start": 8.0, "end": 10.0, "source_start": 2.0}
],
"image_overlays": [
{"image": "path/to/generated.png", "start": 18.0, "end": 21.0, "fit": "cover"}
],
"pip_overlays": [
{"video": "path/to/facecam.mp4", "start": 0.0, "end": 42.0, "position": "bottom_right", "sync_offset": 0.18}
]
}
使用渲染配置：
# 渲染时指定 script/ 下的配置文件
python3 scripts/render_final.py --config script/render_config.json --output media/output/final.mp4
B-roll 替换（broll 字段）：
- 在 clip 中添加
"broll": "path/to/video.mp4" 可替换该片段的画面，同时保留原始音频
broll_start 指定从 B-roll 视频的哪个时间点开始截取（默认 0.0）- B-roll 视频会自动缩放/裁切以匹配主视频分辨率
- 适用场景：屏幕录制口播配城市街景、音频配音配画面等
Auto-Enrich 自动接入（推荐）：
- 先运行
auto_enrich.py --output work/enrich_plan.json
- 渲染时加
--enrich-plan work/enrich_plan.json
broll[].suggested_asset 会转成定时 B-roll video overlay；chapter_cards[]、stickers[] 和 emphasis_cues[] 会转成 ASS badge；emphasis_cues[] 还可生成无红框的轻微 center push-in；chapter_cards[].png / imagegen[].image_path / imagegen[].generated_path 会转成定时图片 overlaypip_overlays[] 会转成定时 facecam / camera 小窗；camera audio 默认忽略，主音频仍来自 render config- 没有实际生成文件的 imagegen cue 只作为提示输出，不会阻塞渲染
- 合并后的可见文字仍会走
_internal_text_guard 和 content_guard.py
Beat Edit Plan 节拍剪辑骨架（音乐视频 / 卡点 montage 可选）：
- 运行
beat_sync.py --bgm origin/bgm.mp3 --generate-plan --duration 30 --beats-per-cut 4 --min-segment 0.75 --max-segment 3 --output work/beat_edit_plan.json --markdown work/beat_edit_plan.md
- 输出
beat_edit_plan.v1：cut_times[]、program-time segments[]、逐切点 boundary_evidence[]、检测方法和 summary
- 默认每 4 拍提出一个切点；最短/最长镜头守卫会优先改选附近 beat，实在没有合适 beat 才插入
duration_guard
librosa 不可用或读取失败时只生成固定 BPM 网格，并把状态标为 review；必须听音乐复核，不能把 fallback 当作真实节拍- 计划只定义时间槽，不选择素材、不渲染、不改源文件；确认后再把镜头映射进
render_config / EDL / OTIO
- 已有 cut times 仍使用原命令
beat_sync.py --bgm origin/bgm.mp3 --cuts work/cut_times.json --window 0.2
Speed Ramp 局部慢动作 / velocity edit（动作、产品 reveal、游戏、montage 可选）：
- 先逐帧找到 impact frame，再运行
speed_ramp.py plan origin/action.mp4 --ramp 4.6,5.0,1,0.25,s_curve --hold 5.0,5.8,0.25 --ramp 5.8,6.2,0.25,1,ease --interpolate-fps 120 --output work/speed_ramp_plan.json --markdown work/speed_ramp_plan.md
verify 会重算 plan id、源文件 SHA-256、source/output coverage 和逐段 duration / speed；源片或 pieces 漂移立即阻塞apply 用同目录临时文件渲染，成功后才替换目标；默认不覆盖、不跟随 output symlink，也不能覆盖 source--interpolate-fps 是 FFmpeg motion interpolation，可能产生肢体 / 边缘伪影；极慢音频必须试听，必要时 plan 阶段加 --mute-audio- 最终必须用 1×、带声音完整播放；变速后重新生成字幕 / timecoded artifacts、跑 render QA，并重新做最终审批。详见
docs/prompts/83-speed-ramp.md
Freeze-Punch 关键帧定格强调（表情峰值、动作落点、产品揭晓可选）：
- 先逐帧确定 impact，再运行
freeze_punch.py plan origin/reaction.mp4 --freeze 4.8,0.8,1.08,0.5,0.42 --delivery work/reaction-freeze-punched.mp4 --output work/freeze_punch_plan.json --markdown work/freeze_punch_plan.md
- 它用 impact frame 替换其后的短画面窗口；音频和总时长保持不变，所以不会因本操作漂移字幕、章节或 cue 时间码
- pending plan 会阻塞；读完 Markdown 后运行
apply，再运行 verify --strict。apply 只有在 H.264/AAC、yuv420p、尺寸/fps/时长/音轨契约和全长解码通过后才原子提升输出并写回 hash
- 必须 1× 带音频检查 freeze 入口/出口、可见说话人冻嘴、动作跳跃、主体裁切和放大软化。源片/plan/成片漂移会让 live gate 失效；旧 QA、approval receipt 和 publish package 必须重做。详见
docs/prompts/101-freeze-punch.md
J-cut / L-cut 声音先行 / 延续转场（访谈、叙事、场景切换可选）：
- 只在人工明确选定的边界运行：
audio_transition.py plan work/render_config.json --transition 1,j_cut,0.4 --transition 3,l_cut,0.5 --output work/audio_transition_plan.json --markdown work/audio_transition_plan.md
- J-cut 使用下一 clip 入点之前的真实源音频 handle；L-cut 使用上一 clip 出点之后的 handle，并跳过下一 clip 等长的开头音频以恢复同步。handle 不足直接阻塞，不用静音伪造
- 计划绑定 render config、transcript、源片/B-roll SHA-256 和 canonical plan id；
verify 会从 live inputs 重新编译，手改 digest 不能隐藏漂移
- 用
audio_transition.py apply ... --output output/master.mp4 --receipt work/audio_transition_apply.json，或给 render_final.py 加 --audio-transition-plan；字幕、overlay、BGM 和错位主音频仍在一次 FFmpeg 编码中完成
- 必须在 1× 用耳机和手机逐个试听改变的边界，确认无吞字、复读、双人声、click、泵动和环境底噪跳变。机器只能验证时序/hash，不能判断交叠对白是否合适。详见 docs/prompts/86-audio-transition.md
Video Stabilization source-bound 手持防抖（仅用于不想要的抖动）：
- 先运行
video_stabilization.py doctor。plan --backend auto 优先两遍 vidstab；缺少该 filter 时会把单遍 deshake 明确写进计划并保留降级 warning，不会在 apply 时静默换后端
- 原片看过后，用
plan origin/handheld.mp4 --decision stabilize --reviewed-by editor --output work/video_stabilization_plan.json --markdown work/video_stabilization_plan.md 记录源 SHA-256、profile 和人工决定；有意手持 / pan 应改用 --decision keep
apply ... --output work/handheld-stabilized.mp4 --comparison verify/handheld-stabilization-compare.mp4 只写新工作副本与全长左/右 A/B；随后必须 1× 看完整 comparison，再运行 confirm --reviewed-by ... --note ...pipeline_manifest.py 会实时检查源片、稳定版、comparison 的 hash 与复核状态。稳定化不能修复滚动快门、运动模糊或失焦；后续用工作副本，不覆盖 origin/。详见 docs/prompts/84-video-stabilization.md
Chroma Key 绿幕 / 蓝幕抠像与换背景（仅用于明确纯色幕布）：
- 先运行
chroma_key.py prepare --project-dir . --foreground origin/presenter-green.mp4 --background origin/studio.png --output-video output/presenter-studio.mp4 --preview-dir verify/chroma_key --report work/chroma_key.json --markdown work/chroma_key.md
prepare 在默认 15%/50%/85% 时间点各生成 composite 与黑白 matte；检查头发/手/衣物边缘、主体缺口、绿/蓝溢色和背景透视/光色，必要时只改一项 --similarity / --blend / --despill 后重新预览- 四项均确认后运行
review --edge-quality pass --subject-integrity pass --spill-control pass --background-fit pass --reviewer ... --note ...，再运行 apply --strict 和 verify --strict
- 图片背景保持，视频背景从第一帧循环且忽略其音轨；最终声音只沿用前景。源/背景/预览/filter/output 任一漂移都会让 live gate 失效
- 这不是无幕布 AI matting 或逐帧 roto；复杂透明物、反光、幕布皱褶或主体同色应重拍或交给专业 keyer。完整说明见
docs/prompts/99-chroma-key.md
PIP Overlay 录屏摄像头小窗（录屏教程可选）：
- 运行
pip_overlay.py --camera origin/facecam.mp4 --segment "0,18,bottom_right" --segment "18,42,top_right" --sync-offset 0.18 --output work/pip_overlay_plan.json --markdown work/pip_overlay_plan.md
- 渲染时追加
--enrich-plan work/pip_overlay_plan.json；可和 screen_focus_plan.json、enrich_plan.json 重复传入
- 输出
pip_overlay_plan.v1，包含 pip_overlays[]、每段位置、source_start、sync offset、尺寸比例、透明度和淡入淡出
render_final.py 会随 --primary-speed / --speed 同步压缩 camera 小窗时间线，避免变速输出时 PIP 和主画面错位
Audio Sync 外录音频自动对齐（相机内录 + 外录麦克风时推荐）：
- 运行
audio_sync.py --reference-media origin/camera.mp4 --external-audio origin/lav.wav --output work/audio_sync_plan.json --markdown work/audio_sync_plan.md --replace-output output/camera_lav_synced.mp4 --strict
- 输出
audio_sync_plan.v1，包含 alignment.offset_seconds、confidence、replace_audio.command、Markdown 复核表和 summary.blocking
- 正数 offset 表示延迟外录音轨；负数 offset 表示裁掉外录音轨开头
- 确认计划后再加
--apply 执行 FFmpeg 替换音轨；脚本会 copy 原视频流、用同步后的外录音轨编码 AAC
- 如果自动估计低置信度，可用
--offset 0.18 这类手动偏移跳过估计；pipeline_manifest.py 会拦截低置信度或缺文件的 audio sync artifact
Multicam Sync 多机位可逆同步计划（两台以上设备录制同一事件时推荐）：
- 运行
multicam_sync.py --reference-media origin/cam-a.mp4 --angle origin/cam-b.mp4 --angle origin/cam-c.mp4 --measure-clock-drift --output work/multicam_sync_plan.json --markdown work/multicam_sync_plan.md --preview-output output/verify/multicam_sync_preview.mp4 --apply-preview --strict
- 输出
multicam_sync_plan.v1：每路 offset/confidence、自动最响音轨、reference/source coverage、公共 overlap、pairwise 一致性、可选 drift probes/线性 fit 和 preview command
- 原片不修改、不重编码；只有
--apply-preview 会生成短网格预览。正 offset 表示该机位 t=0 位于参考时间线更晚的位置
- 多音轨相机可用
--audio-stream "origin/cam-b.mp4=2" 指定有效轨；无音轨/人工拍板用 --manual-offset "origin/cam-c.mp4=1.24"
- 漂移测量默认关闭；启用后默认取 5 个 20 秒窗口，至少 4 个共识 inlier 才拟合
offset(R)=intercept+slope*R，报告明确符号的 ppm、测量分辨率、累计漂移、残差和未应用的 atempo/setpts advisory factors
- 漂移证据只覆盖选择的参考/源音轨；不能据此自动断言视频 PTS 或其他音轨共享同一时钟
- 漂移超阈值或拟合不可靠会进入 review gate；脚本不自动校正，音画必须使用同一仿射映射。未启用时，30 分钟以上仍必须复核头/中/尾
- 详细使用与边界见 docs/prompts/76-multicam-sync.md
Storyboard Plan 分镜与生成路由（生成素材前推荐）：
- 运行
storyboard_plan.py --transcript work/transcript.json --clean-script work/clean_script.md --output work/storyboard_plan.json --markdown work/storyboard_plan.md
- 输出每个 shot 的时间码、narration、first/motion/last-frame 描述、
codex_imagegen / dreamina_video / remotion_hyperframes / media_library_broll 路由、fallback 和 continuity anchors
- 使用生成视频 provider 前先运行
provider_capability.py verify --bundle work/provider_capabilities.json --max-age-days 30 --strict，核对 exact UI/API surface、model、mode、画幅、时长、分辨率、参考上限和证据日期
- 可选运行
video_prompt_pack.py --storyboard-plan work/storyboard_plan.json --asset-root work --style-reference work/imagegen/style-key.png --capability-profile work/provider_capabilities.json --require-capability-profile --resolution 720p --output work/video_prompt_pack.json --markdown work/video_prompt_pack.md --strict，把分镜转成 Dreamina/即梦 Seedance、Veo、LTX、Wan、Sora 提示词包、共享 style lock、approval 和 capability gate
- image-to-video 提交前运行
reference_frame_preflight.py --prompt-pack work/video_prompt_pack.json --output work/reference_frame_preflight.json --markdown work/reference_frame_preflight.md --require-style-reference --strict，拦截缺失/损坏/方向冲突/严重画幅冲突参考帧
- 再运行
storyboard_assets.py --storyboard-plan work/storyboard_plan.json --asset-root work --media-library . --output work/storyboard_assets.json --markdown work/storyboard_assets.md --strict，渲染前确认素材 ready
dreamina_video 只表示适合视频生成，不会自动提交任务；提交 Dreamina/即梦前必须确认，因为可能消耗 credits- 生图优先使用 Codex 内置
image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。
Video Prompt Pack + Reference Frame Preflight 视频生成提示词与参考帧门禁（生成视频前推荐）：
- 先按 docs/prompts/96-provider-capability.md 建立
provider_capabilities.json，再运行 provider_capability.py verify --bundle work/provider_capabilities.json --max-age-days 30 --strict；profile 绑定 exact provider/surface/model 和来源，默认超过 30 天就阻塞
- 运行
video_prompt_pack.py --storyboard-plan work/storyboard_plan.json --asset-root work --character "same host" --brand-anchor "palette=charcoal,white,signal yellow" --style-reference work/imagegen/style-key.png --capability-profile work/provider_capabilities.json --require-capability-profile --resolution 720p --output work/video_prompt_pack.json --markdown work/video_prompt_pack.md --strict
- 输出
global.character_sheet_prompt、global.style_reference、items[].prompt、items[].negative_prompt、items[].surface/model/resolution、items[].capability_profile、items[].capability_issues、items[].approval_status 和 summary.blocking
--style-reference 会把同一 style key 绑定到所有 shot，并在每条 provider prompt 加同一条 STYLE LOCK- 参考图落盘后运行
reference_frame_preflight.py --prompt-pack work/video_prompt_pack.json --output work/reference_frame_preflight.json --markdown work/reference_frame_preflight.md --require-style-reference --strict
reference_frame_preflight.v1 检查首帧/style key 是否存在、可解码、方向/画幅是否匹配、分辨率是否过低和透明背景；阻塞项接入 pipeline_manifest.py--provider veo|ltx|wan|sora|dreamina_seedance 可把同一分镜改写成指定模型提示词；--animate-stills 会把 codex_imagegen 参考图 route 转为 image-to-video 提示词--strict 会在 generated-video provider 还没 --approved，或 capability profile 缺失/过期/设置越界时返回 2；脚本不提交 provider 任务、不消耗 credits- 生图优先使用 Codex 内置
image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。
Generation Task Log 异步生成任务台账（提交生成任务后推荐）：
- 从 provider 决策生成待审批台账：
generation_task_log.py import-provider-decision --provider-decision work/provider_decision.json --log work/generation_tasks.json --markdown work/generation_tasks.md --strict
- Dreamina/即梦提交后必须保存
submit_id：generation_task_log.py add --log work/generation_tasks.json --provider dreamina --task-id <submit_id> --shot-id shot_002 --expected-path work/generated_video/shot_002.mp4 --status submitted
- 下载完成后更新本地文件：
generation_task_log.py update --log work/generation_tasks.json --provider dreamina --task-id <submit_id> --status downloaded --asset-path work/generated_video/shot_002.mp4 --markdown work/generation_tasks.md
- 输出
generation_task_log.v1，包含 poll_command、download_command、readiness 和 summary.blocking
completed 但没有本地 asset_path 仍会阻塞；pipeline_manifest.py 会自动识别 generation_tasks.json 并把未清零任务列为 gate
Generated Clip Review 生成视频片段复核（生成结果下载后、组装前必跑）：
- 先刷新
storyboard_assets.json，再运行 generated_clip_review.py prepare --project-dir . --asset-manifest work/storyboard_assets.json --contact-sheet-dir verify/generated_clips --output work/generated_clip_review_request.json --markdown work/generated_clip_review_request.md --response-template work/generated_clip_review_response.json
- reviewer 必须完整执行 1× 带声、0.25×、静音看画面、只听声音四遍检查；contact sheet 只是抽样导航，不能代替播放完整片段
- response 对每条 clip 记录 identity/wardrobe、action/end state、motion/anatomy/physics、camera、frame integrity、look consistency 六项 1–5 分，以及 hard-fail code、
keep_ranges / remove_ranges、是否重生和具体 prompt_fix
pass 要求加权分 ≥80 且无删段；pass_with_edits 要求 ≥65，并由 keep/remove 精确覆盖全片；常识/物理、身份、道具、文字水印、连续性或音画 hard fail 无论总分多高都必须 fail- 填完 response 后运行
generated_clip_review.py audit --request work/generated_clip_review_request.json --response work/generated_clip_review_response.json --output work/generated_clip_review.json --markdown work/generated_clip_review.md --strict；任何 clip/contact sheet 漂移、缺审、非法区间或需重生都会阻塞
- 组装/发布前再运行
generated_clip_review.py verify --report work/generated_clip_review.json --strict，也可用 pipeline_manifest.py --require generated_clip_review --strict。reviewer label 不是身份认证或数字签名
Generated Motion Window 生成视频有效运动窗口（逐片视觉 review 之后、跨镜头组装前运行）：
- contact sheet 可能漏掉 0.25–1 秒的冻结开头或短暂运动；对每条通过视觉复核的生成片运行
generated_motion_window.py analyze work/generated_video/shot_001.mp4 --project-dir . --output work/generated_motion_window/shot_001.json --markdown work/generated_motion_window/shot_001.md
- 脚本用本地 FFmpeg
freezedetect 保存 freezes[] 与其补集 active_intervals[]，绑定 source SHA-256、媒体契约、参数和 canonical plan id；刚 analyze 固定阻塞，不能把 detector 建议当批准
- 完整 1× 播放源片后运行
confirm ... --decision trim|keep|reject --reviewed-by ... --note ...。trim 默认使用建议区间，也可显式 --start/--end；两个边界都必须落在 active interval 内
trim 在 apply 前继续阻塞；apply ... --output work/generated_motion_window/shot_001-active.mp4 只写新 H.264/AAC、yuv420p working copy，验证时长/尺寸/fps/音轨并完整解码后才原子提升。原片、计划、检测证据或 output 漂移都会 fail closed- 新 working copy 必须重新完整播放，并重跑 generated-clip review、sequence/final QA 和下游审批；
pipeline_manifest.py --require generated_motion_window --strict 会逐个 live verify work/generated_motion_window/*.json。FFmpeg freeze 只衡量全帧相似度，不能判断动作意义、表演、身份、物理或产品质量。详见 docs/prompts/102-generated-motion-window.md
Scoped Video Edit Review 局部 AI 视频编辑范围复核（换装/换背景/换包装/局部 VFX 等 edit mode 后必跑）：
- 每次 provider call 只声明一个确切变化；运行
scoped_video_edit_review.py prepare --project-dir . --source origin/source.mp4 --edited work/scoped_video_edit.mp4 --change-category wardrobe --change "change only the jacket from blue to red" --preserve subject_identity --preserve performance_motion --preserve camera_motion --preserve framing_composition --preserve source_audio --evidence-dir verify/scoped_video_edit --output work/scoped_video_edit_review_request.json --markdown work/scoped_video_edit_review_request.md --response-template work/scoped_video_edit_review_response.json
prepare 绑定原片/编辑结果 SHA-256 与媒体契约，生成范围内 15%/50%/85% 同时间点左右并排 JPEG，以及完整左右并排 H.264 preview；两条输入音轨存在时，preview 把 source/edited 分别保留为独立音轨- reviewer 必须分别以 1×、带声完整看原片与编辑结果，再看完整 A/B scope preview；目标变化和每个
--preserve 只允许 pass|fail|not_observable，不能看不清仍猜 pass
audit --strict 只在目标确实完成、全部保护项通过、三遍播放确认齐全、时长/尺寸/帧率未漂移时 ready；失败必须写具体 repair_action- 组装/发布前运行
verify --report work/scoped_video_edit_review.json --strict，或 pipeline_manifest.py --require scoped_video_edit_review --strict。脚本不调用 provider、不上传素材、不消耗 credits；建议 prompt 是 provider-neutral contract，不能替代当前 surface 的 capability 核验。详见 docs/prompts/100-scoped-video-edit-review.md
Generated Sequence Review 跨镜头连续性复核（两条以上生成片段逐片通过后、组装前必跑）：
- 运行
generated_sequence_review.py prepare --project-dir . --clip-review work/generated_clip_review.json --storyboard-plan work/storyboard_plan.json --evidence-dir verify/generated_sequence --output work/generated_sequence_review_request.json --markdown work/generated_sequence_review_request.md --response-template work/generated_sequence_review_response.json
- 脚本按 storyboard 顺序，为每个相邻边界提取批准范围内的上一镜尾帧、下一镜首帧、并排图和“尾部 + 头部”无声 1× preview；如果上游是
pass_with_edits，只使用批准的首个/最后一个 keep range
- 完整查看 preview 和 comparison 后，为 identity/wardrobe、prop state、spatial orientation、action end state、camera framing、lighting/palette 填
match|intentional_change|mismatch|not_applicable。至少两项必须真实评估；mismatch 必须 fail，给 failure code 和具体 repair_action
- 运行
generated_sequence_review.py audit --request work/generated_sequence_review_request.json --response work/generated_sequence_review_response.json --output work/generated_sequence_review.json --markdown work/generated_sequence_review.md --strict，组装/发布前再 verify --report work/generated_sequence_review.json --strict；clip、上游 review、storyboard 或任一 evidence bytes 漂移都会阻塞
pipeline_manifest.py --require generated_clip_review --require generated_sequence_review --strict 可把逐片和跨镜头两层都设为门禁。preview 无声，不能替代最终 master 的完整声画复核；reviewer label 和 SHA-256 不是身份认证或签名
Generation Lessons 生成视频经验闭环（可选；只沉淀可泛化且人工明确批准的经验）：
- 从已完成的
generated_clip_review.json 选定一条 clip，运行 generation_lessons.py add --library work/generation_lessons.json --review work/generated_clip_review.json --clip-id shot_002 --category hand_contact --lesson "For hand-to-prop contact, isolate one interaction and keep the hand visible through release." --approved-by "<reviewer-label>" --model seedance-2.0
add 会实时重算 canonical review，允许“片段确实需要重生”这一预期 blocker，但拒绝 source/contact-sheet 漂移、漏审、非法 response、stored summary/report-id 篡改；entry 绑定 report/request/clip/contact-sheet SHA-256。approved_by 只是审计标签，不是身份认证或签名- 复用前运行
generation_lessons.py verify --library work/generation_lessons.json --strict；按 provider/model/category 预览可用 generation_lessons.py select --library work/generation_lessons.json --provider dreamina_seedance --model seedance-2.0 --limit 3 --output work/selected_generation_lessons.json --markdown work/selected_generation_lessons.md
- 新证据与旧规则冲突时，不删除旧 entry；新建 lesson 并加
--supersedes <old-lesson-id>。旧 evidence 继续留在 library，但只要新 entry 也匹配当前 provider/model/category，select 就排除被替代规则
- 下一次生成提示词包显式加
video_prompt_pack.py ... --lesson-library work/generation_lessons.json --lesson-model seedance-2.0 --lesson-limit 3。provider 专属规则优先，未给 --lesson-model 时不会误用 model-specific 经验；脚本只追加人工批准的 lesson，不会自动把 clip-specific prompt_fix 当成通用规则，也不会自动重生或消费 credits
- 生图优先使用 Codex 内置
image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。
- 详细说明见 docs/prompts/89-generated-clip-review.md
Storyboard Assets 素材清单与预检（分镜后、渲染前推荐）：
- 运行
storyboard_assets.py --storyboard-plan work/storyboard_plan.json --asset-root work --media-library . --output work/storyboard_assets.json --markdown work/storyboard_assets.md
- 输出每个 shot 的素材状态：
ready / candidate_found / needs_generation / needs_approval / needs_render / search_needed
- 如果传入
--media-library，media_library_broll shot 会从素材索引里生成 candidate_paths + candidate_scores，按 tag、文件名、metadata、时长和画幅透明排名
- 加
--strict 时，任何素材未 ready 都会返回退出码 2，适合放在最终渲染前
needs_approval 代表 Dreamina/即梦等可能消耗 credits 的任务，必须先确认再提交；生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。
自定义封面（cover_image）：
- 提供自定义封面 PNG 路径，优先于自动生成的封面
- 尺寸应与视频分辨率匹配（如 1080x1920）
持续叠加层（video_overlay）：
- 提供透明 PNG 路径，在封面之后的整个视频上持续叠加显示
- 适用场景：品牌水印、系列标识（如 DAY 标签、数据指标）等
- PNG 必须包含 Alpha 通道（RGBA），透明区域不会遮挡视频
闪烁圆点（rec_blink）：
- 在视频上叠加一个周期性闪烁的小圆点 PNG（如录像机 REC 标志）
dot_image：圆点 PNG 路径（建议 12-16px，RGBA 格式）x, y：圆点在视频画面中的像素坐标period：闪烁周期（秒），默认 1.0（0.5 秒亮 + 0.5 秒灭）
结尾卡片（end_cards）：
- 在视频末尾追加黑屏文字卡片，每张卡片有 300ms 淡入淡出
text：卡片文字内容，用 \n 换行duration：每张卡片显示时长（秒），建议 3.0-4.0- 文字居中显示，字号为正文字幕的 1.4 倍
口播稳态底噪清理（speech_denoise）：
- 默认
off；只有空调、风扇、电流声、轻微房间底噪相对稳定时才启用 "light" / "medium" / "strong"
- CLI 可用
--speech-denoise light；配置已开启时可用 --no-speech-denoise 临时关闭
- 三档固定 80 Hz、2-pole 高通，FFT reduction 为 6/9/12 dB；
strong 不会超过 12 dB
- 顺序固定为
highpass → afftdn → atempo → dynaudnorm → acompressor → loudnorm → cover delay → BGM ducking/mix
- 已做 VAD/noise gate、Adobe Podcast、Descript、RX 或机内强降噪的音轨通常保持 off；数字静音、噪声突变、多麦、瞬态敲击/咳嗽和混响必须另行处理
- 先渲染 10–20 秒 off/light/medium A/B，戴耳机正常速度试听辅音、尾音和停顿；渲染后继续运行
audio_master_report.py --strict
背景音乐（bgm）：
- 提供背景音乐文件路径（MP3/M4A/WAV 等 FFmpeg 支持的格式）
bgm_volume：BGM 音量（0.0-1.0），默认 0.15（人声为主，BGM 为辅）bgm_fade_out：结尾淡出时长（秒），默认 3.0bgm_ducking: true 或 CLI --bgm-ducking：用最终旁白轨作为 sidechain，旁白出现时自动压低 BGM；封面、停顿和片尾无旁白时音乐会自然恢复- 默认 ducking 参数是 threshold
0.03、ratio 8、attack 20ms、release 500ms；只有试听或 audio_master_report.py 证据表明需要时才调整
- ducking 分支用
amix normalize=0 保留人声响度，并在混音末尾加 alimiter=0.95 防止峰值溢出；旧配置默认仍关闭，保持已有输出兼容
- BGM 自动循环播放直到视频结束，不需要预先剪辑长度
- 推荐免费可商用音乐源：Pixabay Music、Mixkit、YouTube Audio Library
- 选曲建议：口播/教程用轻柔纯音乐（无人声），节奏不要太强，避免抢人声
字幕风格预设（subtitle_style）：
| 风格 | 效果 | 适用场景 |
|---|
normal | 白字黑描边（默认） | 适合所有场景 |
karaoke | 逐词高亮 | 音乐/节奏感内容 |
bold_pop | 粗描边高对比 | MrBeast/Hormozi 风格 |
neon | 霓虹灯青紫色 | 科技/潮流内容 |
minimal | 极简无描边 | 文艺/安静内容 |
yellow_pop | 黄字黑描边 | 高可见度，户外/嘈杂画面 |
卡拉OK字幕 / 逐词高亮（subtitle_style: "karaoke"）：
音频源替代（M4A/独立音频）：
封面标题：
- 如果用户提供了标题，直接使用。
- 如果用户没有特别要求，站在观众角度总结一个吸引人的标题（6-15 个字）。
subtitle 可选，用于补充情感钩子或关键信息。- 移动端优先：封面在手机列表页里只是一个缩略图，标题必须先保证可读性，再考虑画面细节。
封面文字排版规则：
- 标题按一行最多约 8 个汉字来设计；超过时自动换行，不要把单行塞得过满。
- 英文/数字按约半个汉字宽度估算；例如
AI、GPT-5 之类不应把整行宽度挤爆。
subtitle 字号默认按标题的约 50% 处理，只承担补充信息，不和主标题争抢视觉中心。- 如果标题超过两行，优先缩短文案，不要继续缩小字号来硬塞。
- 做教程/工具类封面时，主标题尽量控制在 4-8 个字，副标题控制在 6-12 个字。
封面风格（cover_style）— 根据视频内容选择最合适的风格：
| 风格 | 适用场景 | 视觉效果 |
|---|
bold | 教程、科普、技术 | 黑底 + 大号白色粗体字，简洁有力 |
news | 热点、观点、争议 | 深色渐变底 + 白色标题 + 黄色副标题，冲击力强 |
frame | Vlog、实拍、场景 | 视频首帧做背景 + 暗色遮罩 + 描边白字 |
gradient | 生活、情感、艺术 | 紫粉渐变底 + 发光白字，温柔优雅 |
minimal | 思考、文化、深度 | 纯黑底 + 细体白字，极简克制 |
white | 教程、产品、品牌化内容 | 纯白底 + 深色字，现代感更强 |
techcard | 屏幕录制、软件教程、AI 工具演示 | 左侧大标题 + 右侧画面卡片，兼顾信息量和可读性 |
AI agent 应根据视频主题和内容语气自动选择：
- 科技/工具类 →
bold 或 news
- 争议/观点类 →
news（白标题+黄副标题效果最抢眼）
- Vlog/实拍类 →
frame
- 情感/生活类 →
gradient
- 深度/文化类 →
minimal
- 纯桌面录屏 / 软件教程 →
techcard 优先；如果画面太杂，就退回 bold / white
背景取帧规则：
- 不要机械地使用第一帧。对于录屏教程，优先选择信息密度更高、界面更完整的一帧做背景或卡片图。
- 如果背景画面会影响标题识别，优先使用
bold / white / minimal 这类纯底风格。
- 单独预览封面时，可用
scripts/generate_cover_image.py --frame-timestamp 00:10:00 指定取帧时间。
多封面 A/B 方案与最终选择：
python3 scripts/cover_variants.py output/final_xhs.mp4 \
--title "20分钟出片" \
--subtitle "AI剪辑完整流程" \
--caption output/caption.json \
--platform xhs \
--frame-timestamp 12.5 \
--output-dir output/covers \
--render \
--output work/cover_variants.json \
--markdown work/cover_variants.md
默认产出 3 套方案和 *_preview.png 小图。先按 feed-size 预览比较，再重跑并加 --select cover-c --require-selection --strict 记录最终封面。标题负责主题/关键词，封面负责结果/情绪/反差/证据；需要强制不重复时加 --require-distinct-cover-text。pipeline_manifest.py --require cover_variants 可把选择设为发布 gate。若需要 AI 生成或编辑封面底图，生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。
封面时长（cover_duration）：
- 默认 2.0 秒，将第一帧冻结并叠加封面
- 也可通过
--cover-duration 命令行参数覆盖
章节划分：
- 根据视频内容逻辑划分章节，建议 不超过 4 个章节
- 章节名要简短（2-4 个字），如：痛点、原因、方案、工具
- 章节时间需要根据选定片段的累计时长精确计算
Phase 4.8: Edit Revision（剪辑 artifact 可逆修订，可选）
当用户要求修改 render_config.json、enrich_plan.json、caption 或字幕 sidecar，同时需要完整审稿、依赖防漂移和 undo/redo 时，先准备 proposal：
python3 scripts/edit_revision.py prepare \
--project-dir . \
--artifact work/render_config.json \
--artifact work/enrich_plan.json \
--depends-on work/transcript_reviewed.json \
--title "收紧开头并调整 B-roll" \
--reason "已完成时间码审片，采用第二版开头。" \
--output work/edit_revision_proposal.json
只改 proposal 的 artifacts[].proposed_content，再运行 audit。合法 audit 的 pending_approval 在 --strict 下返回 2 是预期人工 gate；必须另存绑定相同 review_id、decision: approve 和非空 approved_by_label 的 approval JSON，apply 才会把多个文件作为一个 revision 成组写入并创建 work/edit_revision_history.json。运行期写入错误会尝试恢复旧 bytes，但跨文件不承诺操作系统级原子提交；进程异常后先跑 status --strict。status 会实时检查 artifact、已应用 dependency 和 content-addressed before/after blobs；外部手改、依赖漂移、symlink 或 blob 损坏时拒绝 undo/redo。原始媒体、代码、输出成片和 verify/ 不在管理范围。详细流程见 docs/prompts/80-edit-revision.md。
Phase 4.85: Portable Edit Recipe（可移植剪辑配方，可选）
当用户要把已审 render_config.json 保存为模板，或换一批素材复刻同一时间线/字幕/BGM/overlay 结构时，先导出无路径 recipe：
python3 scripts/edit_recipe.py export \
--config work/render_config.json \
--name fast-tech-explainer \
--description "快节奏科技口播" \
--output work/recipes/fast-tech-explainer_edit_recipe.json \
--markdown work/recipes/fast-tech-explainer_edit_recipe.md
导出前必须通过 source preflight；本地文件引用会变成 typed slots，同一路径只占一个槽位，recipe 不保存原路径。新项目打开 Markdown slot 表，为每槽各传一次 --bind SLOT=PATH 运行 replay，同时写 --receipt 和 --markdown；脚本会验证 portable digest、槽位集合、文件类型与存在性，记录新 binding hash，并对输出 config 再跑 preflight。默认不覆盖，只有明确目标正确时加 --force。recipe hash 不是签名或人工批准；回放后仍必须渲染并看完整成片。详细流程见 docs/prompts/82-edit-recipe.md。
Phase 4.9: Platform Safe Area QA（平台 UI 安全区门禁）
在渲染或多平台导出前，按目标平台分别检查字幕、强调 badge、PIP 人像、CTA、章节卡和点击 marker 是否会进入顶部状态栏、底部文案区或右侧互动按钮栏：
python3 scripts/platform_safe_area_qa.py \
--config work/render_config.json \
--enrich-plan work/enrich_plan.json \
--platform xhs \
--output verify/xhs_platform_safe_area_qa.json \
--markdown verify/xhs_platform_safe_area_qa.md \
--guide verify/xhs_platform_safe_area_guide.svg \
--strict
抖音和视频号派生版分别改用 --platform douyin / --platform wxch。脚本按 render_final.py 的默认 ASS、PIP 和 focus-marker 几何规则估算 bbox；renderer 之外的 CTA/Logo 可以通过 --elements custom_elements.json 提供像素或 normalized bbox。平台 App UI 变化时用 --safe-left / --safe-top / --safe-right / --safe-bottom 覆盖实测边距。
这是本地、可审计的 layout gate：不上传、不调用 LLM、不做 OCR，不推断生成图或封面内部的主体/文字位置。已有整图章节卡会标记 uncheckable，需要打开 SVG guide 或渲染帧人工复核。summary.blocking > 0 会让 --strict 返回 2；需要设为生产线必需项时用 pipeline_manifest.py --require platform_safe_area_qa --strict。
Phase 4.95: Subtitle Style Preview（真实画面字幕样式预览）
最终编码前先把真实 ASS 预设渲染到源片早/中/晚代表帧：
python3 scripts/subtitle_style_preview.py create \
--project-dir . \
--video origin/talking.mp4 \
--platform xhs \
--text "这句字幕要覆盖中英文和数字 2026" \
--preview-dir verify/subtitle_styles \
--output work/subtitle_style_preview.json \
--markdown work/subtitle_style_preview.md \
--require-selection
python3 scripts/subtitle_style_preview.py select \
--report work/subtitle_style_preview.json \
--style normal
python3 scripts/subtitle_style_preview.py verify \
--report work/subtitle_style_preview.json \
--strict
