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, color/speed/J-L cuts, reversible revisions and recipes, preflight/render/QA, subtitles, CapCut, platform/size exports, covers, captions, publish packages, dashboards, handoff formats, and Remotion.
metadata	{ "openclaw": { "emoji": "🎬", "os": ["darwin", "linux", "win32"], "requires": { "bins": ["ffmpeg", "python3"] }, "install": [{ "id": "ffmpeg-brew", "kind": "brew", "formula": "ffmpeg", "bins": ["ffmpeg"], "label": "Install FFmpeg (brew)" }] } }

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
   ├─→ 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
   ├─→ 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
takes_pack.py	多 take / 顶层 Scribe words → phrase-level Markdown/JSON，保留 speaker/audio events	--transcript take1=... --transcripts-dir --json --break-gap
script_alignment.py	已审目标稿 → 多 take 词/段边界候选、人工 choices、render_config 和 gate	--target-script --transcript label=... --media label=... --choices --render-config --strict
audio_sync.py	scratch audio + 外录音轨 → offset / 替换音轨命令 / gate	--reference-media --external-audio --replace-output --apply --strict
multicam_sync.py	多机位 → offset/coverage/音轨选择/pairwise/可选时钟漂移/对齐预览 gate	--reference-media --angle --manual-offset --measure-clock-drift --preview-output --apply-preview --strict
rough_cut.py	transcript 粗剪：去口头禅/重复句	--transcript --cut-list / --input --output
scene_boundaries.py	FFmpeg fixed/adaptive scene score → 场景边界 + cut evidence	--method adaptive --adaptive-threshold --min-scene-score --min-scene-duration
visual_dedupe.py	多来源场景三点感知哈希 → 重复组 / 保留建议 / review gate	--manifest / <videos...> --hamming-threshold --include-same-source --strict
video_understanding.py	抽样帧 + 可选 YOLO 物体检测 + 轻量 tracklets	--detector yolo --scene-boundaries --external-detections --strict
video_stabilization.py	源视频 → exact FFmpeg backend / source hash / 稳定工作副本 / 全长 A/B 复核 gate	doctor / plan --decision / apply --comparison / confirm / verify --strict
chroma_key.py	绿幕/蓝幕前景 + 图片/视频背景 → composite/matte 预览、四项人工 review、source-bound 完整渲染 gate	prepare --foreground --background --output-video / review / apply / verify --strict
highlight_picker.py	长视频精华候选 + brief/query 定向找片段	--transcript --brief/--query --scene-boundaries --render-config
audio_boundary_snap.py	selected highlights → 词级、句末和静音边界校正 + blocker	--candidates --transcript --media --markdown --strict
shorts_batch.py	highlight_candidates → 多条短视频 render_config / render + QA job sheet	--highlights --video --render-config-dir --output-dir --strict
hook_variants.py	transcript/clean_script → 8 个前三秒 hook 角度、风险检查和推荐排序	--transcript --topic --platform --output --markdown --strict
rewrite_script.py	LLM 5 段式重组 + 验证	--transcript --structure --hook-template --emit-prompt / --llm-output
auto_broll.py	B-roll 调度	--transcript --assets --max-single-shot
media_library.py	本地素材库索引 + B-roll 候选推荐 + 素材来源登记	init scan search recommend --category broll --json import annotate
stock_material_plan.py	主题/脚本 → Pexels/Pixabay/Coverr stock 查询计划	--subject --script --provider --media-library --output --markdown
auto_chapter_cards.py	章节卡 PNG	--script --audio --style --output-dir
auto_stickers.py	情绪→贴纸	--transcript --min-interval
auto_emphasis.py	问句/数字/转折/结论 → badge + subtle push-in cues	--transcript --output --markdown
beat_sync.py	BGM → beat edit slots / Markdown review，或吸附已有切点	--bgm --generate-plan --beats-per-cut 4 --output ... --markdown ... / --cuts --window
speed_ramp.py	impact ranges → snap/ease/s-curve/hold 计划、digest 验证和本地事务式 apply	plan <video> --ramp --hold --interpolate-fps / verify --strict / apply --output --receipt
freeze_punch.py	impact frame → source-bound 定格强调、轻微 anchor crop、时长/音频不变和成片 live gate	plan <video> --freeze --delivery / apply <plan> / verify --strict
auto_enrich.py	编排 B-roll / 贴纸 / 强调点 / 章节卡 / imagegen cues	--transcript --clean-script --bgm --output
imagegen_hint.py	检测抽象概念 → 产 gpt-image-2 提示词	--transcript --clean-script --codex-md
audio_cue_sheet.py	transcript → BGM/SFX cue、生成审批和音频门禁	--transcript --asset-root --require-local-music --require-local-sfx --strict
final_audio_storyboard.py	locked visual EDL + storyboard → 最终时间线声音分镜、voice ledger、omitted-story 决定和 live gate	prepare --edl --storyboard audit --request --response verify --report --strict
storyboard_plan.py	transcript/clean_script → 分镜 shot cards + 生成路由	--transcript --clean-script --output --markdown
provider_capability.py	exact provider/surface/model → 带日期的 mode/画幅/时长/分辨率/参考上限能力合同 live gate	verify --bundle --max-age-days --output --markdown --strict
video_prompt_pack.py	storyboard_plan → 多 provider 视频生成提示词包 + 角色/品牌/style lock + paid approval/capability gate	--storyboard-plan --capability-profile --require-capability-profile --resolution --approved --strict
reference_frame_preflight.py	video_prompt_pack → 首帧/style key 存在性、解码、尺寸、方向、画幅、透明背景 gate	--prompt-pack --require-style-reference --reference shot_id=... --strict
generation_task_log.py	异步生成任务台账：submit_id/task id、轮询、下载、本地落盘 gate	add update import-provider-decision report --strict
generated_clip_review.py	生成视频片段 source-bound 视觉复核：contact sheet、评分、裁切范围、重生建议	prepare --clip/--asset-manifest audit --request --response verify --report --strict
generated_motion_window.py	短生成片全帧 freeze → active intervals、人工 trim/keep/reject、帧准确 working copy 与 live gate	analyze <clip> confirm --decision apply --output verify --strict
scoped_video_edit_review.py	原片 + 局部 AI 编辑结果 → 同时间点 A/B 证据、唯一变更目标、保护项逐项复核和 live gate	prepare --source --edited --change --preserve audit --request --response verify --report --strict
generated_sequence_review.py	已审生成片段跨镜头连续性复核：真实尾帧/首帧、并排图、无声边界预览和 live gate	prepare --clip-review [--storyboard-plan] audit --request --response verify --report --strict
generation_lessons.py	从 canonical generated-clip review 提取经明确批准的 provider/model/category 经验，并供下一次 prompt pack 选择	add --review --clip-id --lesson --approved-by [--supersedes] verify --strict select --provider [--model]
storyboard_assets.py	storyboard_plan → 素材清单 + ready/paid 预检	--storyboard-plan --asset-root --output --strict
screen_focus.py	录屏点击/热点 → 聚焦 zoom enrich plan	--events --event --screen-width --output
pip_overlay.py	录屏 + facecam → PIP 摄像头小窗 enrich plan	--camera --segment --sync-offset --output
color_grade.py	bounded 调色 plan + FFmpeg filter + 可选现有 master 复版	--preset --output --markdown --render-output --strict
jump_cut.py	自适应静音检测 → 去停顿计划 / 删除预算 gate / 成片 + 切点音频 fade	<input.mp4> --dry-run --cut-list cuts.json --strict / --output jumpcut.mp4 --max-removal-ratio 0.20 --allow-over-budget
multimodal_dead_air.py	静音 + 静帧交集 → source-bound 死区计划 / live verify / 单次编码工作副本	plan --delivery --output --markdown --strict / verify --strict / apply --markdown
audio_transition.py	render_config → 显式 J-cut/L-cut source handle / hash / 单次编码 apply / receipt	plan --transition AFTER_CLIP,TYPE,DURATION / apply --output / verify --receipt --strict
edit_revision.py	render_config/enrich_plan 等文本 artifact → source-bound proposal / 独立审批 / 成组 apply / undo / redo	prepare --artifact --depends-on / audit --strict / apply --approval / `status
edit_recipe.py	已审 render_config → typed-slot 无路径配方 / digest 验证 / 绑定新素材回放	export --config --name / verify --recipe / replay --bind SLOT=PATH --receipt --strict
edit_preflight.py	render_config/enrich_plan/cut list 渲染前预检 gate	--config render_config.json --enrich-plan enrich_plan.json --output edit_preflight.json --strict
platform_safe_area_qa.py	字幕、badge、PIP、CTA、章节卡、marker → 平台 UI 遮挡 gate + SVG guide	--config --enrich-plan --elements `--platform xhs
subtitle_style_preview.py	真实源帧 → render_final.py 最终 ASS 样式对比 JPEG、人工选择与 source/font/style live gate	create --video --platform --preview-dir --require-selection / select --report --style / verify --strict
render_final.py	单次编码渲染 + 可选个人风格默认值 / 口播降噪 / J-cut/L-cut / enrich_plan / 旁白驱动 BGM ducking	--config render_config.json --style-profile work/edit_style_profile.json --audio-transition-plan audio_transition_plan.json --speech-denoise light --enrich-plan enrich_plan.json --bgm-ducking --output final.mp4
render_qa.py	渲染后 QA：尺寸/音频/黑屏/静帧/静音 + review packet	<video.mp4> --platform douyin --json qa.json --review-dir verify/qa
shot_color_qa.py	rendered master → 镜头亮度/对比/色度/饱和度/broadcast-range 与切点跳变 gate	<video.mp4> --scene-boundaries --output shot_color_qa.json --markdown --strict
retention_rhythm_qa.py	成片 hook 活动、长镜头、注意力空窗、等距/快切和字幕节奏风险	<video.mp4> --timed-text subtitles.json --output retention_rhythm_qa.json --strict
reference_edit_rhythm.py	参考片 vs 成片 hard-cut 密度、镜头时长、结尾 hold、归一化切点与 contact-sheet source-bound 对照	analyze --reference --candidate --evidence-dir [--require-match] / verify --report --strict
speech_continuity_qa.py	成片二次 transcript → 复读 / 近重复 take / 句内口吃 gate	<final_transcript.json> --output speech_continuity_qa.json --markdown --strict
lip_sync_review.py	最终 master → 完整短语 1× 带声 / 0.25× 静音 proof、口型人工 audit 与 source-bound live gate	prepare --video --segment --anchor --proof-dir / audit --request --response --strict / verify --report --strict
review_proxy.py	master/platform MP4 → 低码率 timecoded 审片视频 + JSON/Markdown	<video.mp4> --output verify/review_proxy.mp4 --dry-run --no-timecode
audio_master_report.py	成片响度报告：LUFS / true peak / LRA / 长静音 gate	<video.mp4> --output audio_master_report.json --markdown audio_master_report.md --strict
timeline_view.py	源素材删除段 / 成片输出切点可视化复盘图	<video.mp4> --at 42.5 --output view.png / --rendered-cut-list cuts.json --output-dir verify/
edit_compare.py	原片连续时钟 vs 最终像素双栏视频；删段置黑并验证映射	<source.mp4> <final.mp4> --cut-list --output-speed --output-offset --output
subtitle_pack.py	transcript/render_config → SRT/VTT/ASS/JSON 字幕包	--transcript work/transcript.json --output-dir output/subtitles / --config render_config.json --speed 1.25 --offset 2.0
subtitle_readability_qa.py	output-aligned 字幕 → CPS、时长、行长、重叠和媒体越界 gate	<subtitle_pack.json> --media final.mp4 --output subtitle_readability_qa.json --strict
import_capcut_subtitles.py	剪映/CapCut 自动字幕或 SRT → transcript + gap cut list	--draft <draft_dir> / --srt captions.srt --transcript work/capcut_transcript.json --cut-list work/capcut_gap_cut.json
srt_edit_plan.py	SRT + 人工/agent keep/drop 指令 → edit plan / render_config / cut list	--srt captions.srt --guide edit_guide.md --source-media origin/talking.mp4 --render-config work/render_config.json --strict
project_resume.py	本地 artifacts → 续跑上下文包 / agent handoff	--project-dir work/day58 --markdown work/day58/project_resume.md --agent-note work/day58/CLAUDE.md
review_dashboard.py	本地 artifacts → 静态 HTML/JSON review queue + gate snapshot	--project-dir work/day58 --html work/day58/review_dashboard.html --strict
export_edl.py	NLE handoff：导出 EDL + manifest	--config render_config.json --output edit.edl / --cut-list rough_cut.json --output rough.edl
export_fcpxml.py	NLE handoff：导出 FCPXML + manifest	--config render_config.json --output edit.fcpxml / --cut-list rough_cut.json --output rough.fcpxml
export_otio.py	NLE handoff：导出 OpenTimelineIO .otio + manifest	--config render_config.json --output edit.otio / --cut-list rough_cut.json --output rough.otio
framing_preview.py	master → 各平台 cover/contain/blur 真实帧预览、人工选择和 source/filter/preview live gate	create --video --platforms --require-selection / select --platform --strategy / verify --strict
multi_export.py	三平台导出，可消费已审画幅策略	<input.mp4> --platforms xhs douyin wxch --framing-preview work/framing_preview.json
hdr_sdr.py	PQ/HLG master → source-bound Hable tone-map / BT.709 limited tags / 完整解码 gate	plan --delivery / apply / verify --strict
delivery_encode.py	master → 目标大小 H.264/AAC MP4 / source hash / 两遍码率 / 完整解码 gate	plan --delivery --max-size-mib / apply / verify --strict
generate_caption.py	标题/正文/tag	--script --profile --output
cover_variants.py	多套封面 A/B 方案、个人风格默认值、feed-size 预览、标题协同和最终选择	<video> --title --style-profile --caption --platform --render --select cover-c --strict
approval_receipt.py	已复核视频/封面/文案/字幕/QA → SHA-256 收据和过期审批门禁	create --artifact ... --approved-by / verify --strict
publish_package.py	发布上传包：平台视频、封面、字幕、章节、文案和 gate 状态	--project-dir --platforms --video xhs=... --strict
profiles/__init__.py	受众档位加载	load_profile("tech_pro")

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 错误：

1. 确认 CTranslate2 版本 >= 4.7.1：python3 -c "import ctranslate2; print(ctranslate2.__version__)"
2. 确认 CUDA 版本 >= 12.8：nvidia-smi 或 nvcc --version
3. 尝试手动指定 --compute-type float16（如果直接使用 transcribe.py 的话）
4. 确认驱动版本 >= 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/   — 输出目录

询问素材来源：

1. 询问用户的视频文件位置（本地路径、外部设备或云端）
2. 建议将原始素材复制/移动到 media/raw/ 目录
3. 询问是否有 B-roll、BGM 等辅助素材
4. 如果用户视频散落在多个目录，建议先集中到 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

校验流程：

1. 用 transcript_review.py html 生成一个无外部依赖的本地页面；纯终端环境用 export 生成文本。
2. 页面里点击时间码对着媒体校稿；播放时当前段自动高亮。行内编辑支持本地自动保存、查找替换和 CPS 标黄。
3. 显式保存 transcript_review.txt，不要让页面或 agent 直接覆盖原始 transcript。
4. 用 apply 生成 transcript_reviewed.json；后续清稿、粗剪、分镜和字幕统一使用 reviewed 文件。
5. 对于口误/乱码片段，在展示片段列表时（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 星）：

吸引力评分维度：

1. Hook 强度（前 3 秒）：是否有吸引人的开头（提问、反直觉观点、情感触发）