Video Editing Skill — 视频剪辑技能

这是一个面向 口播、教程、访谈、播客切片、录屏演示 / facecam demo 的 AI 视频剪辑生产线：给它原始口播音频/视频、transcript、B-roll、摄像头小窗或素材目录，它可以把“还没整理的素材”推进到 可发布的小红书 / 抖音 / 视频号短视频。

它不是一个单点 FFmpeg 脚本，而是一条完整工作流：项目启动/素材导入 → 手持防抖 → 转写 → 长视频择段 → 清稿 → 去口头禅/停顿 → 重组故事 → 事实来源 proof deck → 分镜 → B-roll/生图/生成视频规划 → 字幕与声音设计 → BGM 卡点 / 局部 speed ramp / J-cut/L-cut → 可逆剪辑修订 / 可移植剪辑配方 → 渲染前预检 → 单次编码渲染 → 质检 → 多平台导出 / 目标大小交付编码 → 标题文案 → 续跑交接。适配 小红书 / 抖音 / 微信视频号 的比例、节奏、字幕、文案和常见审核风险。

适合做什么

• 把口播短视频从“素材堆”推进到“发布包”：项目目录、source inventory、转写、清稿、分镜、素材清单、渲染配置、字幕 sidecar、QA、标题正文和标签都能落成可审计 artifact。
• 针对中文社媒口播做过生产化调参：Heavy CJK 字幕、1.25x 主输出、响度规范化、平台违禁词 lint、章节卡、贴纸、BGM/SFX cue、三平台导出都不是通用 demo。
• 噪声口播可在单次编码内保守清理：render_final.py --speech-denoise light|medium|strong 会在变速、压缩、响度规范化和 BGM ducking 前处理低频震动与稳态底噪；默认关闭，最大降噪限制为 12 dB。
• 多机位先同步再剪辑：multicam_sync.py 把两台以上相机/手机/录音设备对齐到同一参考时间线，记录每路 offset、置信度、有效音轨、公共重叠区间，并可用多窗口 probe 测量长片时钟漂移；原片不改、不重编码。
• 手持防抖保留原片和 A/B 证据：video_stabilization.py 把源 SHA-256、确切 FFmpeg 后端和人工决定写进计划；apply 只生成新工作副本与全长左右对照，完整 1× 复核并 confirm 后 manifest 才放行。
• 局部慢动作先计划再渲染：speed_ramp.py 把显式 impact frame 周围的 snap/ease/s_curve、hold 和可选 FFmpeg 插帧编译成 source-bound 计划；源 hash 或 piece 时间映射漂移会阻塞，apply 采用同目录临时文件事务式落盘。
• 上传大小限制变成硬门禁：delivery_encode.py 依据源片时长计算两遍 H.264/AAC 码率，绑定源与输出 SHA-256；完整解码、音视频契约或硬大小上限任一失败都不会提升成交付件。
• 专业声画错位不再靠手写 FFmpeg：audio_transition.py 对明确边界规划 J-cut/L-cut，验证真实音频 handle、config/transcript/source hash 和 compiled timing；render_final.py 在同一次编码中完成画面硬切、音频 pre-lap/overhang、字幕、overlay 与 BGM。
• 事实型内容有 proof deck：新闻、数据、产品事实或来源页截图可用 source_receipts.py 生成 URL/截图复核包，作为发布前 gate。
• 最终审批绑定到具体文件字节：approval_receipt.py 为人工看过的视频、封面、文案、字幕和 QA 报告记录 SHA-256；任何重渲染、替换、删除或 symlink 漂移都会让旧审批过期并阻塞发布。
• ASR 语义校稿不再只看单句：semantic_transcript_review.py 为每条字幕附带全篇前后文，验证完整覆盖、源 transcript hash 和最小字符补丁；模型只能提建议，独立人工 choices 才能写 reviewed transcript。
• 上游剪辑配置可以安全撤销/重做：edit_revision.py 把 render_config / enrich_plan 等文本 artifact 的完整改动绑定到基础和依赖 SHA-256；独立审批后成组写入，外部漂移时拒绝 undo/redo 并阻塞 manifest。
• 已审时间线可以换素材复用：edit_recipe.py 把 render_config.json 的全部本地文件路径替换成类型化槽位，生成 content-addressed 可移植配方；回放必须完整绑定新素材、记录 SHA-256 并重新通过 edit_preflight.py。
• 生成式素材有明确审批和台账：Codex image_gen / GPT Image 2 提示词、Dreamina/Veo/LTX/Wan/Sora 视频提示词、provider 决策、submit_id 轮询下载和本地落盘 gate 都先记录再执行。
• 适合交给强推理模型做长流程代理执行：在 GPT-5.6 Sol（OpenAI 当前旗舰；API 别名 gpt-5.6 指向 Sol）和 Claude Opus 4.8 这类面向复杂专业任务、agent 工作流的模型下，本 skill 对 口播类短视频 至少可以替代 80% 的常规视频剪辑工作。

这里的“80%”是按口播短视频生产来评估的：它已经覆盖素材整理、ASR、清稿、粗剪、字幕、B-roll/图像/生成视频规划、声音 cue、渲染前预检、渲染、质检、多平台导出和发布文案。剩下通常需要人工负责的是选题判断、最终审美取舍、品牌口吻、客户确认、复杂手工精修、调色混音和需要逐帧 keyframe 的高级特效。

模型说明：本仓库不会在脚本中硬编码 LLM 型号；这里推荐的是负责理解需求、编排脚本、调用工具和复核产物的 Agent 模型。OpenAI 官方将 gpt-5.6-sol 定位为 GPT-5.6 家族的旗舰型号；追求更低成本或更高吞吐时，可按运行环境选用 GPT-5.6 Terra 或 Luna。

项目现状与边界

做得比较完整的地方：

• 定位清楚：口播、教程、访谈、录屏和长视频切短视频是高重复剪辑场景，脚本化收益高。
• 流水线完整：从 transcript 到 publish gate 的 artifact 很全，失败点可复查，不依赖聊天上下文记忆。
• 风险控制到位：内容合规、素材授权、隐私遮挡、生成任务审批、渲染 QA、pipeline manifest 都有阻塞门禁。
• 本地优先：核心剪辑、渲染、质检不需要云端服务；外部生成任务只做规划、审批和台账。

需要用户知道的边界：

• 不应包装成全类型剪辑替代品：电影感剪辑、MV、广告大片、复杂调色混音和精细动效仍需要专业人工。
• AI 生成素材不等于自动可用：Dreamina/Veo/Sora 等结果必须经过下载、授权、视觉连续性和 QA 检查。
• 平台规则不是法律意见：content_guard.py 能拦常见风险词，但最终发布仍要人审。
• README 和 SKILL 偏长：功能很全，但新用户需要先走推荐入口，不适合从完整脚本文档硬读。

视频素材理解

当前版本已经加入可选的视频理解层：基础流程不依赖机器视觉模型，安装 ultralytics 后可以用 YOLO 对抽样帧做物体检测，并把结果整理成统一的 video_understanding.v1。

• extract_keyframes.py 会抽关键帧和时序图，帮助 agent/用户快速看懂一段视频的视觉内容。
• scene_boundaries.py 支持固定阈值和邻域自适应 FFmpeg scene score，输出逐切点证据，供长视频拆条、抽帧和 highlight snap 使用。
• visual_dedupe.py 会读取多个来源及其 scene_boundaries.v1，对每个场景取 10%/50%/90% 三帧做感知哈希，找出跨素材重复镜头并生成保留建议；只输出复核计划，不删除源素材。
• video_understanding.py 会按固定间隔和场景边界抽帧；--detector yolo 会运行 Ultralytics YOLO，输出 frames[]、detections[]、tracks[]、scene_tags[] 和 review Markdown。
• media_library.py 会读取视频元数据、文件名、标签、素材来源和关联 transcript，用透明分数推荐本地 B-roll。
• smart_reframe.py 可以读取 video_understanding.json，按人脸、人物、主体、物体等权重生成竖屏/方屏重构图计划。
• privacy_redact.py 可以读取同一份检测框或人工框，对人脸、车牌、屏幕敏感区域生成 blur/pixelate/mask 计划。

这个设计是有意的：YOLO/RT-DETR/MediaPipe 等模型会带来模型下载、GPU/Metal/CUDA 兼容和速度问题；对大量口播视频来说，ASR + 关键帧 + 场景边界已经能覆盖主要剪辑决策。因此本项目把 YOLO 做成“需要时打开”的增强能力，而不是强制依赖。

video_understanding.py 的工作方式：

1. 先用 FFmpeg 按场景边界和固定间隔抽帧，避免对每一帧跑模型。
2. 如果安装了 ultralytics，用 YOLO 检测 person、phone、laptop、screen/tv、car、bottle/cup 等短视频常见对象。
3. 用采样帧上的 bbox 做轻量 IoU/中心点关联，合并成 tracks[]，用于判断主体是否移动、是否大面积占画、是否适合自动重构图。
4. 输出统一的 video_understanding.v1：
   • frames[]：时间戳、关键帧路径、场景 id。
   • detections[]：label、bbox、confidence、source model。
   • tracks[]：主体轨迹、出现时间段、中心点、面积变化、运动强度。
   • scene_tags[]：人物、屏幕、产品、街景、车辆、手部演示等可检索标签。
   • warnings[]：未启用 detector、未检测到对象、低置信度检测等。
5. 下游复用这个 JSON：smart_reframe.py 做主体感知裁切，privacy_redact.py 做隐私遮挡，media_library.py 写入视觉标签，storyboard_assets.py 选择更匹配的 B-roll，pipeline_manifest.py 可把未复核的视觉检测列为 gate。

常用方式：

# 可选：只有需要 YOLO 检测时安装
pip install ultralytics

python3 scripts/scene_boundaries.py origin/talking.mp4 \
  --method adaptive \
  --output work/scene_boundaries.json \
  --markdown work/scene_boundaries.md

# 多机位/多条 B-roll 先分别生成 scene boundaries，再把来源写进 manifest。
# manifest 内的相对路径以 manifest 所在目录为基准。
python3 scripts/visual_dedupe.py \
  --manifest work/visual_dedupe_sources.json \
  --output work/visual_dedupe.json \
  --markdown work/visual_dedupe.md \
  --strict

python3 scripts/video_understanding.py origin/talking.mp4 \
  --output work/video_understanding.json \
  --markdown work/video_understanding.md \
  --frames-dir work/video_frames \
  --scene-boundaries work/scene_boundaries.json \
  --detector yolo \
  --model yolo11n.pt \
  --sample-interval 2 \
  --max-frames 32 \
  --strict

python3 scripts/smart_reframe.py origin/talking.mp4 \
  --detections work/video_understanding.json \
  --platform douyin \
  --output work/reframe_douyin.json \
  --markdown work/reframe_douyin.md

如果不想安装 YOLO，也可以只生成抽样帧和 review shell：

python3 scripts/video_understanding.py origin/talking.mp4 \
  --output work/video_understanding.json \
  --markdown work/video_understanding.md

对于需要更细的逐帧动态跟踪的素材，可以把 Ultralytics model.track(..., tracker="bytetrack.yaml")、BoT-SORT 或 Norfair 的结果转换成同一份 detections[] / tracks[] JSON 再交给本项目。当前内置版本优先服务口播剪辑：抽帧检测 + 轻量轨迹已经足够支持主体裁切、隐私遮挡提示和 B-roll 标签。

口播音频 + 无声素材
   │
   ├─→ project_bootstrap.py     原始素材目录 → origin/work/output/verify/edit + source inventory
   ├─→ edit_brief_plan.py       用户一句话需求 → 本地脚本 runbook / commands / gates
   ├─→ transcribe.py            转写 + 词级时间戳 + 口误标记
   │                            (mlx-whisper / faster-whisper / openai-whisper)
   ├─→ semantic_transcript_review.py
   │                            全篇前后文审校包 / 最小补丁验证 / 人工 choices gate
   ├─→ transcript_review.py     文本 round-trip / 本地同步视频 HTML 校稿
   │                            行内编辑 / 播放高亮 / 查找替换 / CPS 提示 / review.txt
   ├─→ takes_pack.py            多 take / Scribe transcript → phrase-level 阅读视图
   │                            speaker / audio_event / takes_packed.md / takes_pack.json
   ├─→ script_alignment.py      已审目标稿 → 多 take 原话候选 / choices / render_config
   │                            词/段边界 / 透明分数 / 歧义与缺素材 gate
   ├─→ audio_sync.py            外录音轨自动对齐 / 替换音轨计划
   │                            scratch audio + lav/recorder track → offset + gate
   ├─→ multicam_sync.py         多机位 → 同一参考时间线 / 公共重叠区间 / 对齐预览
   │                            最响音轨 / pairwise / 可选时钟漂移 / source-safe gate
   │
   ├─→ scene_boundaries.py      fixed/adaptive 视觉切点 + 逐切点 evidence
   ├─→ visual_dedupe.py         多来源场景 → 感知哈希重复组 / 保留建议 / review gate
   ├─→ video_understanding.py   抽样帧 + 可选 YOLO 物体检测
   │                            frames / detections / tracks / scene_tags
   ├─→ video_stabilization.py   手持素材 → source-bound 后端/决定/稳定工作副本
   │                            全长原片-vs-稳定版 A/B + confirm gate
   │
   ├─→ highlight_picker.py      长视频精华候选 / brief-query 定向找片段
   │                            输出 score / hook / reason / render_config
   ├─→ audio_boundary_snap.py   已选片段 → 词/句末/静音边界校正
   │                            adjustment delta / blocker / shorts_batch 兼容输出
   ├─→ shorts_batch.py          精华候选 → 多条短视频渲染 job sheet
   │                            per-short render_config / render command / QA command
   │
   ├─→ rough_cut.py             ASR 粗剪 → 去纯口头禅 / 相邻重复句
   │                            输出可审计 cut list，可选单次 concat 渲染
   │
   ├─→ hook_variants.py         transcript/clean_script → 8 个前三秒 hook 角度
   │                            推荐排序 / content guard 风险 / visual cue
   │
   ├─→ rewrite_script.py        LLM 重组为 5 段式 (hook/pain/turn/value[]/cta)
   │     ↑ 8 hook 模板 + 5 CTA 模板 + 3 故事结构
   │
   ├─→ content_guard.py         80+ 条平台雷区 lint (HARD-BLOCK / SOFT-WARN)
   │     极限词 / 导流 / 医美 / 财富诱导 ...
   │
   ├─→ source_receipts.py       事实 claim → URL/截图 source deck
   │                            Markdown/HTML proof deck + publish gate
   │
   ├─→ beat_sync.py             BGM beat-grid → 可审计 program-time 剪辑骨架
   │                            或把已有切点吸附到附近 beat
   ├─→ speed_ramp.py            局部慢动作 / velocity edit → source-bound 计划
   │                            snap/ease/s-curve / 可选插帧 / 音频同步 / 事务式 apply
   │
   ├─→ auto_enrich.py           调度 B-roll / 章节卡 / 贴纸 / 强调点 / BGM 卡点
   │     │ transition / entity match / emphasis cue / silence boundary / beat snap
   │     │
   │     └─→ imagegen_hint.py   抽象概念检测 → gpt-image-2 提示词
   │           ↓                 (Codex 内置 imagegen 工具直接执行；无 API key)
   │           Codex imagegen   注意力机制 / 复利 / 信息茧房 等自动配图
   │
   ├─→ audio_cue_sheet.py       transcript → BGM / SFX 音频设计清单
   │                            本地素材优先 / 生成审批 / pipeline gate
   │
   ├─→ storyboard_plan.py       transcript/clean_script → shot cards
   │                            生成路由 / 连续性锚点 / Dreamina 额度提醒
   │
   ├─→ video_prompt_pack.py     Dreamina/Veo/LTX/Wan/Sora 提示词包
   │                            角色/品牌/style lock / image-to-video / paid approval gate
   ├─→ reference_frame_preflight.py
   │                            首帧/style key 尺寸/方向/画幅/透明背景 gate
   │
   ├─→ generation_task_log.py   异步生成任务台账
   │                            submit_id / 轮询 / 下载 / 本地落盘 gate
   │
   ├─→ storyboard_assets.py     shot cards → 素材任务清单 / ready 预检
   │                            imagegen / Dreamina / motion / broll 状态表
   │                            可选接入 media_library.py recommend 排名候选素材
   │
   ├─→ stock_material_plan.py   stock B-roll 搜索规划
   │                            Pexels / Pixabay / Coverr 查询计划 + 素材登记提示
   │
   ├─→ screen_focus.py          录屏点击/热点 → focus_events 聚焦计划
   │                            render_final 自动放大、标记、标签
   ├─→ pip_overlay.py           录屏 + facecam → pip_overlays 小窗计划
   │                            render_final 单次编码合成 PIP camera
   │
   ├─→ jump_cut.py              自适应静音检测 → 20% 删除预算 → cut list → 去停顿成片 + 切点音频 fade
   │     └─→ timeline_view.py   源素材删除段 / 成片输出切点 filmstrip + waveform 人工复核图
   │
   ├─→ audio_transition.py      显式 J-cut/L-cut → source handle / hash / 单次编码 / 1× 试听 gate
   │
   ├─→ edit_revision.py         render_config/enrich_plan 等文本 artifact 可逆修订
   │                            source/dependency hash / 独立审批 / 成组 apply / undo / redo
   │
   ├─→ edit_recipe.py           已审 render_config → 无路径可移植配方 / 精确绑定回放
   │                            typed slots / portable SHA-256 / replay receipt / preflight
   │
   ├─→ edit_preflight.py        render_config/enrich_plan/cut list 渲染前预检
   │                            缺文件、空剪辑、非法时间段、危险参数 gate
   ├─→ platform_safe_area_qa.py 字幕/PIP/CTA/marker 平台 UI 安全区 gate
   │                            JSON/Markdown/SVG 证据 + 多平台 profile
   │
   ├─→ render_final.py          单次编码渲染 + enrich_plan 自动接入
   │     B-roll / 章节卡 / 贴纸 / 生成图 / 点击聚焦 / PIP camera + 可选口播降噪 + Heavy 字幕 + 响度规范化 + BGM ducking
   │     可选 --versioned-output：输出 _V，避免覆盖旧成片
   │
   ├─→ render_qa.py             渲染后黑屏/静帧/静音/尺寸质检 + review packet
   ├─→ shot_color_qa.py         成片镜头亮度/对比/色度/饱和度/broadcast-range + 切点跳变门禁
   ├─→ retention_rhythm_qa.py   成片 hook 活动 / 长镜头 / 注意力空窗 / 节奏门禁
   ├─→ speech_continuity_qa.py  成片二次 ASR → 切点复读 / 近重复 take / 句内口吃 gate
   ├─→ review_proxy.py          低码率完整审片 MP4 / 可见时间码 / faststart
   ├─→ audio_master_report.py   成片响度 / true peak / LRA / 长静音发布 gate
   │     └─→ timeline_view.py   QA 可疑区间可视化复盘
   │
   ├─→ subtitle_pack.py         SRT / VTT / ASS / JSON 字幕交付包
   │                            支持 render_config 串接、加速倍率、片头 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
   │                            交给 Premiere / Final Cut Pro / Resolve
   │
   ├─→ multi_export.py          小红书 3:4 / 抖音 9:16 / 视频号 ≤60s
   ├─→ delivery_encode.py       硬大小上限 / 两遍 H.264 / 完整解码验证
   ├─→ generate_caption.py      标题 + 200-500 字正文 + 3-6 tags + 发布时段建议
   ├─→ cover_variants.py        2-4 套封面 A/B 方案 / 小尺寸预览 / 最终选择 gate
   ├─→ approval_receipt.py      已复核交付件 → SHA-256 收据 / stale approval gate
   └─→ publish_package.py       平台视频 / 已选封面 / 字幕 / 文案上传包

适用场景：daily 短视频、口播为主的内容（创业/AI/职场/效率/Vlog）、要发小红书/抖音/视频号 不适用：电影感剪辑、纯音乐 MV、需要精细 keyframe 控制的特效视频

---

60 秒上手

# 1. 装好依赖（macOS Apple Silicon 为例）
brew install ffmpeg
pip install mlx-whisper Pillow

# 2. 克隆
git clone https://github.com/maxazure/video-editing-skill ~/projects/video-editing-skill
cd ~/projects/video-editing-skill

# 3. 环境自检（应该全 ✅ 或 ⚠️ 可选项）
python3 scripts/utils.py

# 4. 跑一遍测试套件确认 OK
pytest tests/           # 715 个测试，约 14 秒

每天做一条视频的完整模板：docs/prompts/15-xhs-daily-tech-video.md

---

安装

必装

Whisper 引擎（按平台选一种）

中国用户走清华镜像：

pip install mlx-whisper -i https://pypi.tuna.tsinghua.edu.cn/simple

NVIDIA GPU 配置详见本文末尾的 Linux GPU 配置 段。

可选

AI 图像生成（gpt-image-2）

生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。

本 skill 只负责产出提示词（imagegen_hint.py）+ 提供模板库（prompts/imagegen_templates.yaml）—— 不内置 OpenAI 客户端。在 Codex 里 agent 直接调内置 imagegen；其他环境用户自行接入。

完整规则详见 docs/prompts/19-imagegen.md。

---

V3 核心能力

🧠 Semantic Transcript Review — 全篇上下文校稿

scripts/semantic_transcript_review.py · 详细文档

专业术语、人名、同音字或中英混说较多时，先把 transcript 变成带 previous/next context 的 provider-neutral review packet。任何模型都只能填写 response；audit 从源 transcript 推导覆盖率，校验 SHA-256、精确字符范围、最小补丁、数字/标点不变、无重叠/越界，并给每条合法建议生成稳定 proposal id。只有独立 choices 文件绑定相同 source_sha256 + review_id，逐项 approve / reject 后，apply 才写 reviewed transcript。

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

第一次 audit --strict 在存在合法建议时返回 2 是预期 gate：还缺人工 choices。成功 apply 会把同一 audit 更新为 artifact_type=result、summary.blocking=0，并重新分配改动 segment 的词级时间戳。模型 confidence 和 reviewer 都不是身份认证或音频事实证明；仍要把输出交给下一节的同步媒体 HTML 听审。

📝 Interactive Transcript Review — 边看视频边校稿

scripts/transcript_review.py · 详细文档

转写后、清稿和渲染前，用一个无依赖的本地 HTML 页面逐段核对 ASR：点击时间码让视频跳到对应位置，播放时自动高亮当前 segment，文字可直接行内修改，并支持浏览器自动保存、全文查找替换、review 文本复制/保存和 CPS 阅读压力提示。页面不上传 transcript 或媒体，也不直接覆盖原 JSON；保存出的 transcript_review.txt 继续交给既有 apply 命令，保留原 segment 时间和可审计变更记录。

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

open work/transcript_review.html

python3 scripts/transcript_review.py apply \
  --transcript work/transcript.json \
  --review work/transcript_review.txt \
  --output work/transcript_reviewed.json

浏览器不支持直接写文件时会退回下载 transcript_review.txt；把它保存/移动到 work/ 后再运行 apply。CPS 标黄只是预渲染提示，最终输出仍应运行 subtitle_readability_qa.py --strict。

🛡️ Content Guard — 平台雷区 lint

scripts/content_guard.py · 详细文档

80+ 条 regex 检查 4 类硬性违规 + 3 类软性警告：

被 render_final.py / rewrite_script.py / generate_caption.py 自动调用——HARD 违规导出退出码 2。

📖 Story Engine — 让 AI 按小红书爆款公式重组

scripts/rewrite_script.py · hook 模板 · CTA 模板

• 8 个钩子模板：反常识、痛点共鸣、数字成绩、悬念问句、身份标签、反差对比、利益承诺、场景代入
• 5 个 CTA 模板：按小红书 CES 权重（关注 8 > 评论/分享 4 > 收藏/点赞 1）排序
• 3 种故事结构：pain_solve（干货）/ story_reversal（故事）/ listicle（盘点）
• Hook Variants：hook_variants.py 可先生成 8 个前三秒开头角度、风险检查、推荐排序和 visual cue，再把选中的 hook 放进清稿提示或 clean_script.md

不绑定任何 LLM 提供商——脚本输出 prompt，你可以交给 GPT-5.6 / Claude 等支持结构化 JSON 的模型，再把返回 JSON 喂回脚本验证 + 物化为 clean_script.md。

🎬 Auto-Enrich — 自动加 B-roll / 章节卡 / 贴纸 / 强调点 / 卡点

详细文档

render_final.py --enrich-plan work/enrich_plan.json 会把 plan 里的 B-roll、章节卡、贴纸、强调点和已生成图片 cue 自动接回单次渲染；emphasis_cues[] 会转成 timed badge 和 marker-free center push-in。--enrich-plan 可重复传入，用来叠加 screen_focus_plan.json 这类独立计划。没有实际文件的 imagegen cue 会保留为提示，不会阻塞导出。

音乐视频、产品 montage 或明确要求“按 BGM 卡点”时，可先让 beat_sync.py 从音乐直接生成剪辑骨架：

python3 scripts/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

默认每 4 拍提出一个 program-time 切点，最短/最长镜头守卫会改选附近 beat；找不到合适 beat 才写入 duration_guard。输出只定义 cut_times[]、segments[] 和逐切点 evidence，不选择素材、不渲染、不修改源文件。detection.method=fallback_grid 时状态为 review，必须实际听音乐复核；确认后再把素材映射进 render_config、EDL 或 OTIO。已有 cut times 继续使用 --cuts ... --window 0.2。

🧭 Video Stabilization — source-bound 手持防抖

scripts/video_stabilization.py · 详细文档

手机、运动相机或手持相机出现不想要的高频抖动时，先检查本机后端并把决定写成计划：

python3 scripts/video_stabilization.py doctor
python3 scripts/video_stabilization.py plan origin/handheld.mp4 \
  --decision stabilize \
  --reviewed-by "editor" \
  --note "固定机位访谈中的高频手抖，不是有意摇摄" \
  --output work/video_stabilization_plan.json \
  --markdown work/video_stabilization_plan.md
python3 scripts/video_stabilization.py apply work/video_stabilization_plan.json \
  --output work/handheld-stabilized.mp4 \
  --comparison verify/handheld-stabilization-compare.mp4 \
  --markdown work/video_stabilization_plan.md

--backend auto 创建计划时优先两遍 vidstabdetect + vidstabtransform；本机缺少它们时才选择 FFmpeg 内置单遍 deshake，并把 fallback warning 永久保存在 artifact 中。apply 不会临场换算法，原片永不覆盖，输出还会验证 duration、尺寸和音频存在性。

用 1× 看完整左原片 / 右稳定版，检查人物、直线、画面四角、镜像边缘和有意 pan；可接受后运行 confirm ... --reviewed-by "editor" --note "完整 A/B 已看..."。确认前 pipeline_manifest.py 会阻塞，确认后仍实时验证源片、稳定版和 comparison 的 SHA-256。它不能修复滚动快门、运动模糊或失焦；稳定版只作为下游 working copy。

⚡ Speed Ramp — source-bound 局部慢动作 / velocity edit

scripts/speed_ramp.py · 详细文档

动作、产品 reveal、游戏或 montage 需要突出少量 impact moment 时，先用逐帧播放器 / timeline_view.py 找 source-time 锚点，再创建计划：

python3 scripts/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

python3 scripts/speed_ramp.py verify work/speed_ramp_plan.json --strict
python3 scripts/speed_ramp.py apply work/speed_ramp_plan.json \
  --output work/action-speed-ramped.mp4 \
  --receipt work/speed_ramp_apply.json

计划把 linear/ease/s_curve/snap ramp 与 constant hold 编译成连续 source/output pieces，绑定源文件 SHA-256、fps、duration 和 canonical plan id；完整 coverage、速度范围、source_duration / speed 和 review contract 都会现场验证。低帧率极慢段会给出 native unique-fps warning；--interpolate-fps 使用 FFmpeg motion interpolation，不冒充 AI 生成补帧，也可能产生肢体 / 边缘伪影。apply 先写同目录临时 MP4，成功后才替换目标；默认拒绝覆盖、symlink 和原片自覆盖。

必须用 1×、带声音播放最终文件，检查 impact frame、曲线手感、插值伪影和极慢音频。局部变速会改变下游时间线：如果已有字幕、章节、cue 或 approval receipt，必须重新生成 / 审批；pipeline_manifest.py --require speed_ramp_plan --strict 可把 plan 设为显式 gate。

🎧 J-cut / L-cut — source-bound 声画错位转场

scripts/audio_transition.py · 详细文档

访谈、场景转换或叙事片需要“下一镜声音先进入”或“画面先切、上一镜声音继续”时，先完成 clip 选择，再逐边界试听并显式建计划：

python3 scripts/audio_transition.py plan work/render_config.json \
  --transition 1,j_cut,0.40 \
  --transition 3,l_cut,0.55 \
  --output work/audio_transition_plan.json \
  --markdown work/audio_transition_plan.md

python3 scripts/audio_transition.py apply work/audio_transition_plan.json \
  --output output/master.mp4 \
  --receipt work/audio_transition_apply.json

python3 scripts/audio_transition.py verify work/audio_transition_plan.json \
  --receipt work/audio_transition_apply.json \
  --strict

J-cut 读取下一 clip 画面入点之前的真实源音频，到视觉切点重新与画面对齐；L-cut 读取上一 clip 出点之后的真实源音频，并让下一 clip 的主音频从 overlap 之后恢复同步。没有足够 handle、L-cut 会意外吞掉下一句开头、config/transcript/source hash 漂移或 compiled timing 被修改都会阻塞。计划存在时，pipeline_manifest.py 会 live verify；edit_brief_plan.py 也能从“声音先行 / J-cut / 画面先切声音后走”自动路由。

apply 通过 render_final.py --audio-transition-plan 把画面、错位主音频、字幕、overlay、BGM 和响度链留在同一次 FFmpeg 编码里，并写 source-bound receipt。计划、Markdown、成片和 receipt 默认都拒绝覆盖；有外部 enrich/调色/降噪等 CLI 参数时，应在原 render_final.py 命令上追加 plan，而不是丢掉参数改用 wrapper。机器验证不能判断交叠对白是否正确；每个改变边界必须以 1× 在耳机和手机扬声器上试听，确认没有吞字、复读、双人声、click、泵动或环境底噪跳变。

🧱 Project Bootstrap — 项目启动与素材导入

scripts/project_bootstrap.py · 详细文档

借鉴 agent-native 视频工具的 folder-first / safe working copy / project memory 思路，但保持本项目本地 artifact-first：把原始素材目录整理成 origin/、work/、output/、verify/、edit/，并写出 source_inventory.json、source_inventory.md、project.md 和 next_steps.md。

常用：

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

默认 --mode copy，会按路径和扩展名把素材归入 origin/raw、origin/broll、origin/audio、origin/bgm、origin/images、origin/assets 或 origin/sidecars；同名文件自动加后缀，不覆盖已有文件。pipeline_manifest.py 会发现 source_inventory.json，需要把素材导入作为 analysis gate 时可加 --require source_inventory。脚本不转码、不渲染、不上传，也不调用 LLM 或生成服务。

🧭 Edit Brief Plan — 自然语言剪辑需求路由

scripts/edit_brief_plan.py · 详细文档

借鉴 GitHub 上视频 skill / MCP 项目的“用户自然语言 → agent 选工具、排顺序、留 checkpoint”的优点，但保持本项目轻量：只做本地确定性路由，输出 edit_brief_plan.v1 JSON 和 Markdown runbook，不调用 LLM、不渲染、不上传、不提交付费生成任务。

常用：

python3 scripts/edit_brief_plan.py \
  --brief "把 origin/interview.mp4 剪成三条抖音短视频，去停顿，加B-roll、BGM和字幕，最后生成发布包" \
  --project-dir . \
  --output work/edit_brief_plan.json \
  --markdown work/edit_brief_plan.md \
  --strict

它会识别 origin/interview.mp4 这类源素材路径、目标平台、手持防抖、目标脚本对齐、多 take、长视频拆条、批量短视频、字幕、B-roll、BGM、去停顿、J-cut/L-cut、生成素材、PIP、调色、QA、发布包等信号，并把它们映射到已有脚本，例如 video_stabilization.py、script_alignment.py、highlight_picker.py、shorts_batch.py、jump_cut.py、audio_transition.py、auto_enrich.py、render_final.py、render_qa.py 和 publish_package.py。pipeline_manifest.py 会发现 edit_brief_plan.json；当 summary.blocking > 0（例如 brief 为空或显式 source 缺失）时会作为 blocker，也可以用 --require edit_brief_plan 把需求路由作为 analysis gate。

👁️ Video Understanding — 抽样帧 + 可选 YOLO 检测

scripts/video_understanding.py · 详细文档

为口播、访谈、产品演示和户外素材补上结构化视觉线索：先按时间和场景边界抽帧；需要时再用 Ultralytics YOLO 识别人、手机、电脑、屏幕、车辆、杯子等常见对象；最后输出可审计的 video_understanding.v1。

常用：

python3 scripts/video_understanding.py origin/talk.mp4 \
  --output work/video_understanding.json \
  --markdown work/video_understanding.md

pip install ultralytics
python3 scripts/video_understanding.py origin/talk.mp4 \
  --scene-boundaries work/scene_boundaries.json \
  --detector yolo \
  --model yolo11n.pt \
  --output work/video_understanding.json \
  --markdown work/video_understanding.md \
  --strict

输出可以直接交给 smart_reframe.py --detections 做主体感知裁切，也可以交给 privacy_redact.py --detections 做隐私遮挡计划。ultralytics 不是必装依赖；没有 detector 时仍然能生成抽样帧和 review shell。

🧩 Takes Pack — 多 take phrase-level 阅读视图

scripts/takes_pack.py · 详细文档

借鉴 browser-use/video-use 把 phrase-level transcript 作为主要阅读视图、并保留音频事件的做法，但保持本项目 artifact-first：只读本地 transcript.json，输出 takes_packed.md 和可选 takes_pack.json，不转写、不渲染、不调用 LLM。除现有 segments[].words[] 外，也可直接读取 ElevenLabs Scribe 风格的顶层 words[]；speaker_id 会参与分段，audio_event 会作为带时间码的笑声、掌声、叹气或音乐剪辑节拍保留。

常用：

python3 scripts/takes_pack.py \
  --transcript take1=work/take1_transcript.json \
  --transcript take2=work/take2_transcript.json \
  --output work/takes_packed.md \
  --json work/takes_pack.json \
  --break-gap 0.5

takes_packed.md 按 source 分组列出 take1-003 这类 phrase id、源时间码、speaker、segment ids、audio events 和压缩文本，适合先比较多个 take 的表达质量，也能避免在笑点、掌声或反应声中间误切。takes_pack.json 还会给每个事件保留 label/start/end；确认后的 time range 可继续交给 highlight_picker.py、srt_edit_plan.py、render_config.json 或 EDL/FCPXML/OTIO。pipeline_manifest.py 会发现 takes_pack.json，但默认不把它作为 blocker；需要强制多 take review 时可加 --require takes_pack。

🧭 Target Script Alignment — 按确认稿从多 take 装配原话

scripts/script_alignment.py · 详细文档

客户、编导或 Agent 已经确认成片稿时，不必再靠人工逐条找时间码。script_alignment.py 把目标稿按行/句拆成 spoken units，在一份或多份 reviewed transcript 中搜索词级/segment 边界候选，输出稳定 candidate id、原话、source time、透明 score breakdown 和前三名备选；最终 render_config.json 按目标稿顺序排列，即使素材原始录制顺序不同也能重组。

第一次运行：

python3 scripts/script_alignment.py \
  --target-script work/target_script.md \
  --transcript take-a=work/takes/take-a_transcript_reviewed.json \
  --transcript take-b=work/takes/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

默认 65 分以下不采用、65-82 分要求 review；即使分数更高，只要前两名相差不超过 3 分，也会以 ambiguous_match 阻塞，避免同文案多个 take 被静默选错。人工看/听候选后，把 target-001 -> candidate id 写进 --choices work/script_alignment_choices.json 再跑一次。显式 choice 能解决低分/同分歧义，但不会绕过源素材缺失或时间段重复占用。该脚本不调用 LLM、不改源文件、不判断表演和画面质量；大幅同义改写仍需要人工语义判断或补录。pipeline_manifest.py 会发现此报告，只要 summary.blocking > 0 就阻塞，也支持 --require script_alignment。

🎞️ Adaptive Scene Boundaries — 运动镜头自适应切点

scripts/scene_boundaries.py · 详细文档

固定 scene score 阈值对静态访谈很直接，但持续摇镜、游戏画面、手持走拍或高运动 B-roll 可能整段都高于阈值。--method adaptive 会读取每帧 FFmpeg scene score，把目标帧与前后邻域均值比较，同时保留绝对 --min-scene-score 门槛；真正的局部峰值才进入 boundaries[]，每个保留切点还会在 boundary_evidence[] 记录 score、adaptive ratio 和邻域均值。

python3 scripts/scene_boundaries.py origin/long-talk.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

先看 Markdown 的 cut evidence，再把 JSON 交给 highlight_picker.py --scene-boundaries、video_understanding.py --scene-boundaries 或 retention_rhythm_qa.py --scene-boundaries。固定机位素材、旧项目复现或已经调好阈值的流程继续用 --method fixed --threshold 0.35，默认行为保持兼容。

🔎 Highlight Picker — 长视频精华候选 / brief 定向找片段

scripts/highlight_picker.py · 详细文档

长视频拆短视频时，先从 transcript.json 生成可发布候选，输出透明 score、signals、warnings、hook_text、reason 和可选 render_config。默认模式会找 hook/value/duration 表现好的短视频片段；如果用户已经知道要找什么，加 --brief 或 --query 做 prompt-based clipping。

常用：

python3 scripts/highlight_picker.py \
  --transcript work/long_transcript.json \
  --brief "产品发布 用户反应 价格对比" \
  --scene-boundaries work/scene_boundaries.json \
  --video origin/long-talk.mp4 \
  --output work/brief_highlights.json \
  --markdown work/brief_highlights.md \
  --render-config work/brief_render_config.json \
  --platform douyin \
  --num-clips 3 \
  --strict

--brief 会把自然语言意图拆成英文关键词和中文短语片段，写入每条 candidate 的 brief_match.score 与 matched_terms，但仍保留原来的自包含结尾、弱 hook、时长偏离等 warning。适合“找产品 reveal / 用户强反应 / 教程关键步骤 / 失败教训”这类定向剪片。

🎧 Audio Boundary Snap — 词/句末/静音剪辑边界校正

scripts/audio_boundary_snap.py · 详细文档

在 highlight_picker.py 已经选好内容以后，用 transcript 词级时间戳把每条 start/end 对齐到完整词，必要时把结尾扩到附近句号、问号或感叹号；如果 transcript 已有 silences[]，或提供 --media 让 FFmpeg 跑 silencedetect，还会优先把切点放到相邻静音区中点。每条调整都会保留原始时间、前后 delta、首尾词、reason、warning 和 blocker，不渲染也不改源文件。

常用：

python3 scripts/audio_boundary_snap.py \
  --candidates work/highlight_candidates.json \
  --transcript work/long_transcript.json \
  --media origin/long-talk.mp4 \
  --output work/audio_boundary_plan.json \
  --markdown work/audio_boundary_plan.md \
  --strict

python3 scripts/shorts_batch.py \
  --highlights work/audio_boundary_plan.json \
  --video origin/long-talk.mp4 \
  --output work/shorts_batch.json \
  --strict

支持 Whisper segments[].words[] 和 ElevenLabs Scribe 风格顶层 words[]，其中 spacing/audio event 不会当成词。没有词级时间戳、候选时间非法、源媒体缺失或安全边界超出平台时长时，summary.blocking 会非零；pipeline_manifest.py --require audio_boundary_plan --strict 可把它设为显式 gate。

🎞️ Shorts Batch — 多条精华短视频渲染 job sheet

scripts/shorts_batch.py · 详细文档

借鉴 AI shorts 类项目“长视频一次上传，产出多条可追踪短视频”的做法，但保持本项目本地优先：读取 highlight_picker.py 的 highlight_candidates.v1 或 audio_boundary_snap.py 的 audio_boundary_plan.v1，为每条 selected highlight 写一份独立 render_config，并输出 shorts_batch.v1 JSON、Markdown job sheet、render_final.py 命令和 render_qa.py 命令。脚本不渲染、不上传、不调用 LLM。

常用：

python3 scripts/shorts_batch.py \
  --highlights work/highlight_candidates.json \
  --video origin/long-talk.mp4 \
  --output work/shorts_batch.json \
  --markdown work/shorts_batch.md \
  --render-config-dir work/shorts_render_configs \
  --output-dir output/shorts \
  --qa-dir verify/shorts \
  --basename day63 \
  --platform douyin \
  --strict

输出后先打开 work/shorts_batch.md 看每条 job 的 hook、ending 和 warnings；确认后逐条运行表内 render_shell，再运行 qa_shell 生成 QA JSON/复核包。pipeline_manifest.py 会发现 shorts_batch.json；当 batch 自身有 summary.blocking > 0（例如源视频缺失）时会作为可见 blocker。

🎨 Color Grade — 可审计调色计划

scripts/color_grade.py · 详细文档

借鉴 agent 视频编辑工具对 color grading / filters 的重视，但保持本项目的单次编码原则：先生成 bounded color_grade.v1 调色计划和 Markdown review，最终由 render_final.py --color-grade 在字幕前接入同一条 FFmpeg filter graph。

常用：

python3 scripts/color_grade.py \
  --preset screen \
  --output work/color_grade.json \
  --markdown work/color_grade.md

python3 scripts/render_final.py \
  --config work/render_config.json \
  --color-grade work/color_grade.json \
  --output output/tutorial_master.mp4

内置 natural、warm、cool、punchy、soft、cinematic、screen 七个 preset；自定义 brightness、contrast、saturation、gamma、temperature、tint、sharpness 会被限制在保守范围内，--strict 在参数被 clamp 时返回 2。若主片已经渲染完，也可以用 color_grade.py --input output/master.mp4 --render-output output/master_grade.mp4 做单独复版；日常推荐仍是在 render_final.py 里一次编码完成。

🔬 Shot Color QA — 成片镜头色彩 / 曝光门禁

scripts/shot_color_qa.py · 详细文档

color_grade.py 负责渲染前的 bounded look，shot_color_qa.py 则在最终编码文件上按镜头复查实际结果。它用 FFmpeg signalstats 每秒默认抽 2 帧，对每个镜头聚合 YLOW/YAVG/YHIGH、U/V、SATAVG 和 BRNG 中位数，列出持续过暗/过亮、低对比、高饱和、broadcast-range 越界，以及相邻镜头的亮度/色度跳变。

python3 scripts/shot_color_qa.py output/day81_master.mp4 \
  --output output/verify/day81_shot_color_qa.json \
  --markdown output/verify/day81_shot_color_qa.md \
  --strict

# 已有 scene_boundaries.v1 时可复用同一场景时间轴
python3 scripts/shot_color_qa.py output/day81_master.mp4 \
  --scene-boundaries work/scene_boundaries.json \
  --output output/verify/day81_shot_color_qa.json \
  --markdown output/verify/day81_shot_color_qa.md \
  --strict

视觉跳变默认只 WARN，因为地点、日夜、图形/实拍或刻意 look 的变化可能完全合理；非 full-range 输出的持续 BRNG 越界和未覆盖镜头默认 BLOCK。需要把极暗/极亮或跳变作为当前项目的强人工门禁，可加 --fail-on-extremes / --fail-on-jumps。Markdown 会为可疑切点生成 timeline_view.py 命令；确认后应回到源 timeline / 调色计划重渲染，避免对 master 反复压缩。pipeline_manifest.py --require shot_color_qa --strict 可强制发布前存在报告；这是 SDR 社媒输出的轻量统计，不是校准 scopes、HDR proof、白平衡/肤色判断或审美评分。

🎧 Audio Cue Sheet — BGM / SFX 音频设计清单

scripts/audio_cue_sheet.py · 详细文档

借鉴 OpenMontage / vibeframe / Claude Code Video Toolkit 这类 agentic video 项目对 narration、music、SFX、成本和 review report 的一等公民设计，但保持本项目轻量：只读 transcript 和本地素材目录，不生成音乐、不提交 TTS、不消耗 provider credits。

常用：

python3 scripts/audio_cue_sheet.py \
  --transcript work/transcript.json \
  --asset-root media/bgm \
  --asset-root media/sfx \
  --output work/audio_cue_sheet.json \
  --markdown work/audio_cue_sheet.md

python3 scripts/audio_cue_sheet.py \
  --transcript work/transcript.json \
  --asset-root media \
  --require-local-music \
  --require-local-sfx \
  --output work/audio_cue_sheet.json \
  --markdown work/audio_cue_sheet.md \
  --strict

输出 audio_cue_sheet.v1：voice_track 记录主口播响度目标，music[] 给出全片 BGM mood / BPM / prompt / 本地候选或生成需求，sfx[] 根据“但是 / 重点 / 完成 / 风险”等触发词排 whoosh、ping、chime、warning tick。--strict 会在要求本地 BGM/SFX 但素材缺失时返回 2；pipeline_manifest.py 会自动识别 audio_cue_sheet.json 并把 summary.blocking > 0 列为 blocking gate。

选好 BGM 后，可让实际渲染兑现 cue sheet 里的 ducking 要求：

{
  "bgm": "media/bgm/tech-pulse.mp3",
  "bgm_volume": 0.15,
  "bgm_fade_out": 3.0,
  "bgm_ducking": true
}

也可给 render_final.py 加 --bgm-ducking 临时启用。它会用最终旁白轨触发 FFmpeg sidechaincompress，在说话时动态压低 BGM，在封面、停顿和片尾无旁白时恢复；默认 threshold 0.03、ratio 8、attack 20ms、release 500ms。旧配置默认关闭以保持兼容，配置已开启时可用 --no-bgm-ducking 覆盖。详细参数与试听检查见 背景音乐、旁白 Ducking 和片尾。

🎞️ Storyboard Plan — 分镜与生成路由

scripts/storyboard_plan.py · scripts/video_prompt_pack.py · scripts/storyboard_assets.py · 分镜文档 · 视频提示词包文档 · 素材清单文档

借鉴 GitHub 上视频生成类项目的 storyboard / shot continuity / provider routing 思路，但保持本项目的轻量原则：脚本只做本地规划，不提交任何付费生成任务。

常用：

python3 scripts/storyboard_plan.py \
  --transcript work/transcript.json \
  --clean-script work/clean_script.md \
  --output work/storyboard_plan.json \
  --markdown work/storyboard_plan.md \
  --max-shots 8 \
  --target-aspect 9:16

python3 scripts/storyboard_assets.py \
  --storyboard-plan work/storyboard_plan.json \
  --asset-root work \
  --media-library . \
  --output work/storyboard_assets.json \
  --markdown work/storyboard_assets.md

路由规则：抽象概念优先 codex_imagegen；数字/指标优先 remotion_hyperframes；动作/场景变化推荐 dreamina_video 但只标记为需确认，因为 Dreamina/即梦生成可能消耗 credits；其他先走本地素材库 B-roll。传 --media-library 时，storyboard_assets.py 会从 media_index.json / media_index.db 里按标签、文件名、时长和画幅推荐候选，并在 Markdown 表里显示分数。storyboard_assets.py --strict 会在素材未 ready 时返回退出码 2，适合渲染前拦截。生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。

🎥 Video Prompt Pack — 视频生成提示词包

scripts/video_prompt_pack.py · 详细文档

借鉴 GitHub 上视频生成 skill 对多模型提示词、角色参考 sheet、image-to-video 和 provider 成本审批的做法，但保持本项目 artifact-first：只把 storyboard_plan.json 转成 video_prompt_pack.v1 和 Markdown review，不提交 Dreamina/Veo/LTX/Wan/Sora 任务，不消耗 credits。

常用：

python3 scripts/video_prompt_pack.py \
  --storyboard-plan work/storyboard_plan.json \
  --asset-root work \
  --character "same Chinese founder-host, navy jacket" \
  --brand-anchor "palette=charcoal,white,signal yellow" \
  --style-reference work/imagegen/style-key.png \
  --output work/video_prompt_pack.json \
  --markdown work/video_prompt_pack.md \
  --strict

python3 scripts/video_prompt_pack.py \
  --storyboard-plan work/storyboard_plan.json \
  --asset-root work \
  --provider dreamina_seedance \
  --animate-stills \
  --approved \
  --output work/video_prompt_pack.json \
  --markdown work/video_prompt_pack.md

输出 global.character_sheet_prompt、global.style_reference、items[].prompt、items[].negative_prompt、items[].reference.expected_path/resolved_path、items[].approval_status 和 summary.blocking。--style-reference 会把同一 style key 绑定到每个生成 shot，并给 provider prompt 追加统一 STYLE LOCK。--strict 会在 generated-video provider 还没有 --approved 时返回 2；pipeline_manifest.py 会自动识别 video_prompt_pack.json 并把未清零的 summary.blocking 列为 blocking gate。Dreamina/即梦、Veo、LTX、Wan、Sora 等视频生成可能消耗 credits，提交前先确认并保持小批量。

🖼️ Reference Frame Preflight — 生成参考帧预检

scripts/reference_frame_preflight.py · 详细文档

借鉴 HeyGen 的 Frame Check、Higgsfield 的共享 style key 和 Seedance 的多素材角色标注：paid provider 提交前，先检查 image-to-video 首帧与共享 style reference 是否真的可用。

python3 scripts/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

脚本检查路径存在性、可解码性、尺寸、横竖方向、目标画幅、短边分辨率和透明背景。缺文件、损坏文件、横竖方向冲突或严重画幅冲突会写入 summary.blocking 并让 --strict 返回 2；低分辨率和透明背景写 warning 与修正建议。默认 20% 画幅容差会接受常见 1024×1536 → 9:16 参考工作流；需要临时改路径时可重复传 --reference shot_001=/path/to/approved.png。产物会被 pipeline_manifest.py 自动纳入 gate。

🧾 Generation Task Log — 异步生成任务台账

scripts/generation_task_log.py · 详细文档

借鉴 PixVerse skills 的 task polling / asset download 能力和 Claude Code Video Toolkit 的跨会话项目状态管理，但保持本项目本地化：只记录异步生成任务状态，不提交 paid jobs。

常用：

python3 scripts/generation_task_log.py import-provider-decision \
  --provider-decision work/provider_decision.json \
  --log work/generation_tasks.json \
  --markdown work/generation_tasks.md \
  --strict

python3 scripts/generation_task_log.py add \
  --log work/generation_tasks.json \
  --provider dreamina \
  --task-id "" \
  --shot-id shot_002 \
  --expected-path work/generated_video/shot_002.mp4 \
  --status submitted \
  --markdown work/generation_tasks.md \
  --strict

python3 scripts/generation_task_log.py update \
  --log work/generation_tasks.json \
  --provider dreamina \
  --task-id "" \
  --status downloaded \
  --asset-path work/generated_video/shot_002.mp4 \
  --markdown work/generation_tasks.md

输出 generation_task_log.v1：tasks[].provider_task_id 保存 Dreamina submit_id / provider task id，poll_command / download_command 保存下一步命令，readiness 区分 needs_approval / pending / processing / needs_download / missing_asset / failed / ready。--strict 会在 summary.blocking > 0 时返回 2；pipeline_manifest.py 会自动识别 generation_tasks.json 并把未清零的异步任务列为 blocking gate。

🗂️ Media Library Recommend — 本地 B-roll 候选推荐

scripts/media_library.py

借鉴终端视频编辑工具里的 transcript-aware B-roll 选择思路，但只做本地索引和透明打分，不下载 stock、不调用外部视觉模型。推荐结果会保留 score、reasons、absolute_path，方便 agent 或人工先确认再接入 render_config / enrich_plan。

常用：

# 先建立或刷新素材库索引
python3 scripts/media_library.py init .
python3 scripts/media_library.py scan .

# 给某个分镜或口播段找 B-roll 候选
python3 scripts/media_library.py recommend "AI workflow dashboard" \
  --project-dir . \
  --category broll \
  --target-duration 3 \
  --target-aspect 9:16 \
  --json

# 让 storyboard_assets 的素材预检表直接带候选排名
python3 scripts/storyboard_assets.py \
  --storyboard-plan work/storyboard_plan.json \
  --asset-root work \
  --media-library . \
  --output work/storyboard_assets.json \
  --markdown work/storyboard_assets.md

# 本地素材不够时，先规划 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

# 下载/自有素材确认授权后，登记到素材库和 provenance 元数据
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"

打分规则：tag 命中权重大于文件名命中，其次是路径、metadata、关联 transcript；category=broll、视频类型、时长覆盖 cue、画幅接近目标比例会加分；默认过滤索引里已经不存在的文件，--include-missing 可用于清理 stale index。本地素材不足时，用 stock_material_plan.py 生成 Pexels / Pixabay / Coverr 查询计划；下载或客户给的素材再用 media_library.py import / annotate 写入 provider、source URL、creator、license 等元数据，供 asset_provenance.py 发布门禁复核。

🔍 Screen Focus — 录屏点击聚焦

scripts/screen_focus.py · 详细文档

借鉴 Screen Studio/Recordly/JianYing 类工具里的自动点击放大体验，但保持本项目的轻量方式：不录屏、不申请桌面权限，只把手工或工具导出的点击/热点事件转成可审计 focus_events enrich plan。

常用：

python3 scripts/screen_focus.py \
  --events work/clicks.json \
  --screen-width 1920 \
  --screen-height 1080 \
  --output work/screen_focus_plan.json \
  --markdown work/screen_focus_plan.md

python3 scripts/render_final.py \
  --config work/render_config.json \
  --enrich-plan work/screen_focus_plan.json \
  --output output/tutorial_master.mp4

focus_events[] 支持像素或 0-1 坐标、duration、zoom、transition、marker_color 和 label；render_final.py 会在对应时间段淡入放大裁切画面，并把 label 合并为 timed badge，适合软件教程、产品演示和操作录屏。

🎥 PIP Overlay — 录屏摄像头小窗

scripts/pip_overlay.py · 详细文档

借鉴 Loop 这类录屏编辑工具把 screen、microphone 和 optional camera 合成一个短反馈闭环的做法，但保持本项目的 artifact-first 方式：先把 facecam/camera 录制转成 pip_overlays[] 计划，复核 Markdown 后再交给 render_final.py --enrich-plan 单次编码合成，不混入 camera audio。

常用：

python3 scripts/pip_overlay.py \
  --camera origin/facecam.mp4 \
  --segment "0,18,bottom_right" \
  --segment "18,42,top_right" \
  --sync-offset 0.18 \
  --width-ratio 0.24 \
  --output work/pip_overlay_plan.json \
  --markdown work/pip_overlay_plan.md

python3 scripts/render_final.py \
  --config work/render_config.json \
  --enrich-plan work/screen_focus_plan.json \
  --enrich-plan work/pip_overlay_plan.json \
  --output output/tutorial_master.mp4

pip_overlays[] 支持每段独立 position、source_start、sync_offset、width_ratio、margin_ratio、opacity 和 transition；render_final.py 会随 --primary-speed / --speed 同步压缩 camera 小窗时间线，避免变速输出时讲解人画面和主画面错位。

🎙️ Audio Sync — 外录音频自动对齐

scripts/audio_sync.py · 详细文档

借鉴 AICW Video 和 ffsubsync 把“同步”做成独立可复核能力的思路：先用相机/录屏 scratch audio 和外录 lav/recorder 音频估计 offset，输出 audio_sync_plan.v1 和 Markdown，再确认是否执行替换音轨。

常用：

python3 scripts/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 \
  --max-offset 5 \
  --strict

# 复核 work/audio_sync_plan.md 后再执行
python3 scripts/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 \
  --apply \
  --strict

alignment.offset_seconds 为正表示延迟外录音轨；为负表示裁掉外录音轨开头。自动估计低置信度时 status 会变成 review，也可以用 --offset 0.18 手动指定偏移。pipeline_manifest.py 会发现 audio_sync_plan.json 并在低置信度或缺文件时阻塞发布 gate。

🎥 Multicam Sync — 多机位可逆同步计划

scripts/multicam_sync.py · 详细文档

两台以上设备录下同一场访谈、播客、活动或演示时，先选一台参考机位，再把其他机位对齐到它的时间线：

python3 scripts/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，每路记录 alignment.offset_seconds、置信度、参考/源时间覆盖区间和实际采用的 0:a:N。多音轨相机会用中段 mean_volume 自动选择最响音轨，也可用 --audio-stream "origin/cam-b.mp4=2" 覆盖。三路以上自动对齐会额外直接比较非参考机位，若“参考机位推导 offset”与“机位间直接估计”相差超过阈值，就进入 review gate。--manual-offset "origin/cam-c.mp4=1.24" 可接入无音轨机位或已经人工确认的拍板点。

--measure-clock-drift 会在每个机位自己的可用重叠时长中默认抽取 5 个 20 秒窗口，按置信度筛 probe，再用稳健共识模型拟合 offset(R)=intercept+slope*R；至少需要 4 个跨越有效时段的 fit inlier。JSON/Markdown 保存每个 probe、offset_slope_ppm、测量/斜率分辨率、累计漂移、拟合残差和未应用的 atempo/setpts advisory factors；累计漂移超过 80 ms 或拟合不可靠会进入 review gate。可用 --drift-probes、--drift-probe-seconds、--drift-search-seconds、--drift-threshold-ms 调整。该能力默认关闭，只测当前选择的参考/源音轨；它不自动证明视频 PTS 或容器内其他音轨使用同一时钟，也不会自动校正。

原片始终不修改；只有显式 --apply-preview 才会生成短网格预览。正 offset 表示该机位的 t=0 位于参考时间线更晚的位置，预览按 source_local = reference_time - offset 读取每路画面。未启用漂移测量时，30 分钟以上素材仍会警告并要求头/中/尾复核。pipeline_manifest.py 会发现该计划并拦截缺文件、低置信度、无公共重叠、pairwise 不一致或漂移 review。

📝 Subtitle Pack — SRT/VTT/ASS 字幕交付

scripts/subtitle_pack.py · 详细文档

借鉴 VideoLingo / Twick / ffsubsync 这类字幕工具对“可上传字幕文件、单行可读切分、时间线对齐”的重视，但保持本项目轻量：不重新转写、不调翻译/配音服务，只把现有 transcript.json 或 render_config.json 变成可校对、可上传的 sidecar 字幕包。

常用：

python3 scripts/subtitle_pack.py \
  --transcript work/day58_transcript.json \
  --output-dir output/subtitles \
  --basename day58 \
  --formats srt vtt ass json

python3 scripts/subtitle_pack.py \
  --config work/render_config.json \
  --output-dir output/subtitles \
  --basename day58_master \
  --speed 1.25 \
  --offset 2.0

--transcript 默认保留原始时间码；--config 默认按 render_final.py 的 clips 顺序串接时间线。--speed 对齐 --primary-speed，--offset 对齐封面/片头秒数；中文默认 18 字单行、英文默认 42 字单行，也可用 --max-chars 覆盖。

🔎 Subtitle Readability QA — 最终字幕可读性门禁

scripts/subtitle_readability_qa.py · 详细文档

subtitle_pack.py 负责生成字幕，但生成成功不代表最终字幕一定可发布。subtitle_readability_qa.py 读取与 master 同速、同片头 offset 的 subtitle_pack.v1 JSON，检查 cue 时间缺失/倒序、真实重叠、极短闪现、CPS、持续时间、行数、单行长度，并可用 --media 检查字幕是否超过成片结尾。

python3 scripts/subtitle_readability_qa.py \
  output/subtitles/day58_master.json \
  --media output/day58_master.mp4 \
  --output verify/subtitle_readability_qa.json \
  --markdown verify/subtitle_readability_qa.md \
  --strict

默认中文 18 字/行、英文 42 字符/行；18 CPS 以上、0.5 秒以下、7 秒以上或超过 2 行只 WARN，必须结合正常速度成片判断。时间无效、cue 重叠、超过媒体结尾、短于 0.15 秒或超过 25 CPS 会写入 summary.blocking，--strict 返回 2。报告存在且 blocking 非零时 pipeline_manifest.py 会阻塞；要强制具备报告可加 --require subtitle_readability_qa。本 gate 只读 timed text，不做 OCR，也不声称能判断字体、颜色、描边或画面安全区。

📐 Platform Safe Area QA — 平台 UI 遮挡门禁

scripts/platform_safe_area_qa.py · 详细文档

渲染前读取 render_config.json、一个或多个 enrich plan 及可选自定义元素 bbox，按 renderer 默认布局估算字幕、badge、PIP、CTA、章节卡和 focus marker 的位置。内置 xhs、douyin、wxch、tiktok、reels、shorts、universal、landscape profile；输出 platform_safe_area_qa.v1 JSON、Markdown 和 SVG 安全区图。

python3 scripts/platform_safe_area_qa.py \
  --config work/render_config.json \
  --enrich-plan work/enrich_plan.json \
  --platform xhs \
  --output verify/platform_safe_area_qa.json \
  --markdown verify/platform_safe_area_qa.md \
  --guide verify/platform_safe_area_guide.svg \
  --strict

关键元素越界会进入 summary.blocking，--strict 返回 2；非关键元素只 WARN。pipeline_manifest.py 会发现报告并传播 blocker，也可加 --require platform_safe_area_qa 强制发布前必须存在。平台 UI 会变化，内置 profile 是可复现的社区经验保守值，不是永久官方规范；可用 --safe-left/top/right/bottom 覆盖当前实测边距。脚本不做 OCR，无法判断生成图或全屏画面内部的人脸/标题位置，SVG 和最终成片人工复核仍是必要步骤。

🔁 CapCut Subtitle Import — 剪映字幕反向导入

scripts/import_capcut_subtitles.py · 详细文档

借鉴 SmartCut / CapCut 自动字幕工作流：先在剪映里用 Auto Captions 生成或人工校对字幕，再把字幕轨导回本项目，生成兼容 rewrite_script.py、rough_cut.py、subtitle_pack.py 的 transcript.json。需要按字幕间隙做初剪时，同一个脚本也能输出 keep_segments cut list，交给 timeline_view.py 或 export_edl.py 复核。

常用：

python3 scripts/import_capcut_subtitles.py \
  --draft ~/Movies/JianyingPro/User\ Data/Projects/com.lveditor.draft/day58 \
  --transcript work/capcut_transcript.json \
  --cut-list work/capcut_gap_cut.json \
  --markdown work/capcut_subtitles.md \
  --gap-threshold 1.0

python3 scripts/import_capcut_subtitles.py \
  --srt exports/capcut_auto_captions.srt \
  --transcript work/capcut_transcript.json \
  --srt-output output/subtitles/capcut_clean.srt

默认只读取剪映草稿里的 subtitle 材料，避免把封面标题/贴纸文字误当口播字幕；如果某个草稿把自动字幕保存成普通文字轨，可加 --include-overlays。--cut-list 是“字幕间隙代理”的保守粗剪，最终渲染前仍应跑 timeline_view.py --cut-list 人工复核。

🧾 SRT Edit Plan — 字幕编辑指令转剪辑方案

scripts/srt_edit_plan.py · 详细文档

借鉴 video-use / OpenStoryline 这类“先让人或 agent 给出编辑意图，再生成可复核时间线”的方式；本项目把它压成一个本地确定性桥接脚本：SRT + keep/drop 字幕编号指令 → srt_edit_plan.json、render_config.json、source-time cut list 和 Markdown review。

work/edit_guide.md 示例：

title: 发布会高光
platform: xhs
keep 3-5: 先用产品发布和用户反应
drop 1-2: 铺垫太慢
keep 8: 补一句核心结论

常用：

python3 scripts/srt_edit_plan.py \
  --srt work/captions.srt \
  --guide work/edit_guide.md \
  --source-media origin/talking.mp4 \
  --output work/srt_edit_plan.json \
  --render-config work/render_config.json \
  --cut-list work/srt_edit_cut.json \
  --markdown work/srt_edit_plan.md \
  --strict

keep/include/use/select 行按出现顺序生成最终输出；drop/skip/exclude/remove 行写入 review。--cut-list 按原素材时间排序，适合 timeline_view.py --cut-list 复核；真正重排后的输出看 --render-config。

✂️ ASR Rough Cut — 自动去口头禅/重复句

scripts/rough_cut.py · 详细文档

借鉴 FireRed-OpenStoryline 的 ASR speech rough cut 思路，但保持本项目的本地可审计方式：不调用 LLM，直接利用 transcribe.py --detect-fillers 的结果和相邻 transcript 相似度，先输出计划，再选择是否渲染。

常用：

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
python3 scripts/timeline_view.py origin/talking.mp4 --cut-list work/rough_cut.json --output-dir output/verify/rough_cut

✂️ Jump Cut — 自动去停顿

scripts/jump_cut.py · 详细文档

借鉴视频生成/剪辑类 skill 里常见的 remove_silence / jumpcut 闭环，但默认先产出可审计 cut list，避免直接误切人声：

常用：

python3 scripts/jump_cut.py input/talking.mp4 --dry-run --cut-list output/talking.jumpcut.json --strict
python3 scripts/timeline_view.py input/talking.mp4 --cut-list output/talking.jumpcut.json --output-dir output/verify/cuts
python3 scripts/jump_cut.py input/talking.mp4 --output output/talking.jumpcut.mp4 --cut-list output/talking.jumpcut.json --fade-duration 0.03

cut list 会记录 removal_budget、status、summary.blocking、blockers/warnings。若预计删除超过 20%，先检查 removed_segments 和切点复盘图，再调整 --min-silence / --pad / --max-removal-ratio；只有明确接受超预算剪辑时才加 --allow-over-budget。pipeline_manifest.py 会把未批准的超预算 jump cut 识别为 rough_cut blocker。

🔎 Timeline View — 源素材/成片切点复盘图

scripts/timeline_view.py · 详细文档

借鉴视频剪辑类 skill 的 timeline_view 工作台：在跳切前后或 QA 报警区间生成一张 PNG，上半部分是 filmstrip，下半部分是 waveform，方便快速判断“切点是否咬字、画面是否突跳、静音是否自然”。除源素材删除段外，现在也可把 cut list 的 keep_segments 累计映射到已渲染成片的实际输出切点，逐个检查拼接结果。

常用：

python3 scripts/timeline_view.py output/day58_master.mp4 --at 42.5 --radius 1.5 --output output/verify/42_5s.png
python3 scripts/timeline_view.py origin/talking.mp4 --cut-list work/jumpcut.json --output-dir output/verify/cuts --limit 12
python3 scripts/timeline_view.py output/rough_cut.mp4 --rendered-cut-list work/rough_cut.json --output-speed 1.25 --output-offset 1.0 --output-dir output/verify/rendered_cuts --json output/verify/rendered_cuts.json

--rendered-cut-list 读取 keep_segments 的既定顺序，按每段 source duration / --output-speed 累加，并把 --output-offset 作为片头封面或其他前置时长。JSON 会为每张复盘图保存 boundary.output_time、前后 source range 与 source_gap；如果计算切点超过实际成片时长，脚本会提示校正 speed/offset，而不会输出错位证据。

🔀 Edit Compare — 原片 vs 成片 source-time 对照

scripts/edit_compare.py · 详细文档

把原片放在左栏连续播放，把最终交付像素按既有 keep_segments 投回右栏的原片时间轴；被删除范围显示黑屏。这样可以播放复核“删了什么”和“最终字幕/B-roll/调色/裁切变成了什么”，而不只看静态 cut plan。

python3 scripts/edit_compare.py \
  origin/talking.mp4 \
  output/day74_master.mp4 \
  --cut-list work/rough_cut.json \
  --output-speed 1.25 \
  --output-offset 2.0 \
  --output output/verify/day74_source_vs_final.mp4 \
  --report output/verify/day74_edit_compare.json \
  --markdown output/verify/day74_edit_compare.md

脚本自动验证双栏尺寸、原片时长、source-clock 音轨、删除范围黑屏和代表性保留范围的最终像素映射；pipeline_manifest.py 会把 summary.blocking > 0 的 edit_compare 报告列为阻塞 gate。V1 只接受单来源、按时间升序、无重叠的 keep_segments，并支持一个全局 --output-speed / --output-offset；重排、多来源、逐段不同速度或倒放要用 NLE/OTIO 时间线复核。没有 source-time 位置的 offset 片头和末段之后片尾不会出现在右栏，仍需完整播放 final/review proxy。

🎨 AI 图像生成（gpt-image-2 / Codex imagegen）

scripts/imagegen_hint.py · scripts/prompts/imagegen_templates.yaml · 详细文档

抽象概念（注意力机制 / 复利 / 信息茧房 / 长尾效应 …）自动检测 + 适配 gpt-image-2 七槽位提示词结构。

• Codex 环境：检测到的 prompt 直接喂给 Codex 内置 imagegen 工具——无需 OpenAI API key，Codex 自动路由到 gpt-image-2
• 其他环境：用 OpenAI Python SDK 自己接（openai.OpenAI().images.generate(...)，需 OPENAI_API_KEY）。本 skill 只产 prompt，不内置客户端
• 内置 7 个 sample：注意力机制 / 信息茧房 / 复利 / 长尾效应 / 数据柱状图 / 章节标题卡 / 早晨笔记本 B-roll（每个都带双语 prompt + why-it-works）
• 5 个 structure 槽位：chapter_background / chapter_title_card / broll_fallback / data_visualization / abstract_concept
• gpt-image-2 规则全部编码：引号 = 精确文字渲染、约束写进 prose（无 negative-prompt 字段）、具体相机+光圈+光照（避免 “AI 味”）、默认拒绝人脸/人手特写、中文标题不走 gpt-image-2

🧪 Edit Preflight — 渲染前预检 gate

scripts/edit_preflight.py · 详细文档

借鉴 agent 视频编辑工具的 structured preflight / risky-parameter guardrails 思路，但保持本项目本地 artifact-first：先检查 render_config.json、enrich_plan.json 和 rough/jump cut list，再决定是否允许进入 FFmpeg 渲染。

常用：

python3 scripts/edit_preflight.py \
  --config work/render_config.json \
  --enrich-plan work/enrich_plan.json \
  --output work/edit_preflight.json \
  --markdown work/edit_preflight.md \
  --strict

输出 edit_preflight.v1，会检查空剪辑、缺视频/图片/音频文件、transcript + segment_id 不匹配、非法时间段、overlay 超出输出时间线、PIP/focus 参数风险。pipeline_manifest.py 会识别 edit_preflight.json，如果 summary.blocking > 0 就把它列为 blocking gate。它不解码、不渲染、不上传；渲染后仍然要跑 render_qa.py。

♻️ Portable Edit Recipe — 换素材复用已审时间线

scripts/edit_recipe.py · 详细文档

export 先对现有 render_config.json 跑 edit_preflight.py，再递归把视频、transcript、BGM、图片、字幕、LUT 等本地文件引用替换成 ${video_1} / ${transcript_1} 这类类型化槽位。配方只保留模板、槽位位置、原始文件 SHA-256/大小/后缀、源 config SHA-256 和无路径 preflight 摘要；portable_sha256 绑定整个模板与复用契约。

python3 scripts/edit_recipe.py export \
  --config work/render_config.json \
  --name fast-tech-explainer \
  --description "快节奏科技口播，双段原话 + 卡片 + ducking" \
  --output work/recipes/fast-tech-explainer_edit_recipe.json \
  --markdown work/recipes/fast-tech-explainer_edit_recipe.md

python3 scripts/edit_recipe.py verify \
  --recipe work/recipes/fast-tech-explainer_edit_recipe.json

在新项目回放时，必须为 Markdown 表中的每个槽位各传一次 --bind；缺失、重复、未知、扩展名类型不符、文件不存在、recipe digest/occurrence 被改或模板残留本地路径都会退出 2。回放输出新的绝对路径 render_config.json、绑定文件哈希 receipt 和 Markdown，并自动运行 preflight：

python3 scripts/edit_recipe.py replay \
  --recipe work/recipes/fast-tech-explainer_edit_recipe.json \
  --bind video_1=origin/episode-02.mp4 \
  --bind transcript_1=work/episode-02_transcript_reviewed.json \
  --bind image_1=work/cards/episode-02.png \
  --bind audio_1=origin/music/episode-02.wav \
  --output work/render_config.json \
  --receipt work/edit_recipe_replay.json \
  --markdown work/edit_recipe_replay.md \
  --strict

默认拒绝覆盖已有输出，确实要替换时显式加 --force。配方哈希只证明内容身份，不是作者签名、人工审批或“新素材与旧时间码语义等价”的证明；ready 以后仍必须实际渲染并人工审片。pipeline_manifest.py 对任何已发现的 *_edit_recipe.json 都会现场重算 schema、槽位 occurrence、路径泄漏和 digest，不能靠手改 summary.blocking 绕过。

🎚️ 渲染层（V3 强化）

scripts/render_final.py

🧾 Versioned Output — 成片不覆盖旧版本

scripts/render_final.py · 详细文档

借鉴 GitHub 上视频技能的“每次渲染保留新版本”工作流：--versioned-output 会把请求的 output/day58_master.mp4 写到下一个 output/day58_master_V.mp4，避免 ffmpeg -y 覆盖上一版成片。--formats 会跟随实际版本文件生成 day58_master_V3_vertical.mp4 这类多比例输出。

常用：

python3 scripts/render_final.py \
  --config work/render_config.json \
  --enrich-plan work/enrich_plan.json \
  --output output/day58_master.mp4 \
  --versioned-output \
  --formats vertical horizontal

配置式开启：

{
  "versioned_output": true,
  "clips": [
    {"video": "origin/talking.mp4", "segment_id": 1, "transcript": "work/transcript.json"}
  ]
}

🧭 NLE Handoff — EDL / FCPXML / OTIO 导出

scripts/export_edl.py · scripts/export_fcpxml.py · scripts/export_otio.py · 详细文档

借鉴自动剪辑/生成类项目常见的“先产 timeline，再交给专业剪辑软件继续精修”工作流：export_edl.py 可把本项目的 render_config.json 或 rough_cut.py / jump_cut.py 产生的 keep_segments 导出成单轨 CMX 3600 风格 EDL；export_fcpxml.py 导出 Final Cut Pro / DaVinci Resolve 更友好的单 spine FCPXML；export_otio.py 导出 OpenTimelineIO .otio，默认包含 V1 + A1 track。三者都会写 JSON manifest，保留绝对源路径和精确秒数。

常用：

python3 scripts/export_edl.py \
  --config work/render_config.json \
  --output work/day58_edit.edl \
  --fps 30 \
  --title DAY58_EDIT

python3 scripts/export_edl.py \
  --cut-list work/rough_cut.json \
  --output work/rough_cut.edl \
  --fps 30

python3 scripts/export_fcpxml.py \
  --config work/render_config.json \
  --output work/day58_edit.fcpxml \
  --fps 30 \
  --width 1080 \
  --height 1920

python3 scripts/export_otio.py \
  --config work/render_config.json \
  --output work/day58_edit.otio \
  --fps 30 \
  --title DAY58_EDIT

适合把自动粗剪交给 Premiere / Final Cut Pro / DaVinci Resolve 做调色、混音、精剪或协作复核。EDL 更通用，FCPXML 对 FCP / Resolve 更直接，OTIO 更适合使用 OpenTimelineIO adapter 的跨工具流程；复杂字幕、overlay、章节卡和 B-roll 仍以 render_final.py / export_capcut.py 为准。

2026-07-19 自动化升级记录（Subtitle Readability QA）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/subtitle_readability_qa.py，读取 subtitle_pack.v1 的 cues[]，本地、只读地产生 subtitle_readability_qa.v1 JSON 和可选 Markdown。报告覆盖无效/负数/非正时长、乱序、空文本、cue overlap、媒体越界、闪现字幕、CPS、过长/过短显示、最大行数与单行字符数；中文/英文默认单行上限分别为 18/42 字符。pipeline_manifest.py 新增 subtitle_readability_qa category，报告存在且 summary.blocking > 0 时阻塞，也支持 --require subtitle_readability_qa。同步更新 SKILL、每日工作流、提示词索引和 Subtitle Readability QA 文档。这一步不做 OCR 或视觉安全区判断，字体、遮挡与画面边缘仍需观看 master。

使用方式：先按实际 speed / cover offset 生成 output-aligned subtitle pack，再执行 python3 scripts/subtitle_readability_qa.py output/subtitles/final_master.json --media output/final_master.mp4 --output verify/subtitle_readability_qa.json --markdown verify/subtitle_readability_qa.md --strict。--strict 在存在 BLOCK 时退出码为 2；必须修正源字幕、speed/offset 或 render config 并重新生成。WARN 用于人工观看相应 cue，不建议为了清零指标机械拆句。

验证结果：新增 tests/test_subtitle_readability_qa.py 10 项，更新 tests/test_pipeline_manifest.py 2 项；定向 .venv/bin/python -m pytest tests/test_subtitle_readability_qa.py tests/test_pipeline_manifest.py -q 通过 55 passed in 0.63s；最终全量 .venv/bin/python -m pytest tests -q 通过 553 passed in 5.47s。真实 FFmpeg smoke 生成 4 秒 360×640 H.264/AAC master：正确对齐的 2 条字幕得到 ready、blocking=0、warnings=0、max_cps=3.5、媒体时长 4.0s；故意增加错误 offset 后检出 out_of_bounds=1，结果 blocked 且 strict 退出码为 2。.venv/bin/python -m compileall -q scripts tests、CLI --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-18 自动化升级记录（Retention Rhythm QA）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/retention_rhythm_qa.py，对已渲染 master / platform export 运行 FFmpeg hard scene detection，并可合并与 speed / cover offset 对齐的 subtitle pack JSON；输出 retention_rhythm_qa.v1 JSON / Markdown，检查前三秒 activity、6/10 秒长视觉 hold、6/10 秒 combined attention gap、镜头时长 CV、0.35 秒以下快切 burst、4.5 秒以上字幕 hold 和 1.5 秒以上无字幕区间。WARN 必须人工看 master，只有高置信严重项进入 summary.blocking；报告明确声明不预测真实留存率或爆款概率。pipeline_manifest.py 新增 retention_rhythm_qa category，报告存在且 blocking 非零会阻塞，也支持 --require retention_rhythm_qa。同步更新 SKILL、每日工作流、提示词索引和 Retention Rhythm QA 文档。

使用方式：先运行 subtitle_pack.py --config work/render_config.json --output-dir output/subtitles --basename final_master --speed 1.25 --offset 2.0 生成 output-aligned JSON，再运行 python3 scripts/retention_rhythm_qa.py output/final_master.mp4 --timed-text output/subtitles/final_master.json --output verify/retention_rhythm_qa.json --markdown verify/retention_rhythm_qa.md --strict。已有 scene_boundaries.v1 时可用 --scene-boundaries 复用，避免重复检测。若 BLOCK，按报告时间范围看 master / timeline_view.py，回到源 render_config、enrich plan 或 cut list 重渲染；不要为了清零 WARN 机械加切点。

验证结果：新增 tests/test_retention_rhythm_qa.py 10 项，更新 tests/test_pipeline_manifest.py 2 项；定向 .venv/bin/python -m pytest tests/test_retention_rhythm_qa.py tests/test_pipeline_manifest.py -q 通过 53 passed in 0.60s；最终全量 .venv/bin/python -m pytest tests -q 通过 541 passed in 7.40s。真实 FFmpeg smoke 生成 14 秒 360×640 非等距硬切视频，CLI 实测检出 5 个 cut / 6 个 shot、最长视觉 hold 4.00 秒、cadence CV 0.423，结果 ready、blocking=0、warnings=0。.venv/bin/python -m compileall -q scripts tests、CLI --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-17 自动化升级记录（Cover Variants + Publish Selection）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/cover_variants.py，支持 xhs、douyin、wxch、tiktok、reels、youtube_shorts、youtube，默认输出 3 套 cover-a/b/c 方案：主风格、对比风格和真实画面证据风格；--count 4 增加去副标题版本。脚本输出 JSON/Markdown、标题—封面 overlap 检查、content guard 风险、每套可复现渲染命令、完整 PNG 和 *_preview.png 小图；--select cover-c --require-selection --strict 会记录 selected_cover。generate_cover_image.py 新增 --width/--height，保证不同平台封面按目标尺寸渲染；缺 Pillow 时小图自动回退 FFmpeg。pipeline_manifest.py 新增 cover_variants gate；publish_package.py 会优先采用已选择且存在的封面，并避免把未选择的 variant / preview 误当发布封面。同步更新 SKILL、每日工作流、封面 / 发布包文档和 Cover Variants 提示词。若需要生成或编辑封面底图，生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。

使用方式：先运行 python3 scripts/cover_variants.py output/day68_master_xhs.mp4 --title "20分钟出片" --subtitle "AI剪辑完整流程" --caption output/day68_caption.json --platform xhs --frame-timestamp 12.5 --output-dir output/covers --render --output work/cover_variants.json --markdown work/cover_variants.md；检查 output/covers/*_preview.png 后，重跑并加 --select cover-c --require-selection --strict。发布包无需再传 --cover，会读取 selected_cover；需要显式覆盖时仍可传 publish_package.py --cover 。

验证结果：新增 tests/test_cover_variants.py 7 项，更新 tests/test_pipeline_manifest.py 和 tests/test_publish_package.py；定向 .venv/bin/python -m pytest tests/test_cover_variants.py tests/test_publish_package.py tests/test_pipeline_manifest.py -q 通过 57 passed in 0.85s；最终全量 .venv/bin/python -m pytest tests -q 通过 529 passed in 4.91s。真实 FFmpeg/Chrome smoke 用 1 秒 1080×1920 样片成功生成 3 张 1080×1440 小红书封面和 3 张 240×320 preview，选择 cover-c 后得到 status=ready、rendered=3、blocking=0。.venv/bin/python -m compileall -q scripts tests、两个 CLI --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-16 自动化升级记录（Rendered Speech Continuity QA）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/speech_continuity_qa.py，读取已渲染 master 的二次 transcript，检测 boundary_exact_repeat（前段结尾/后段开头精确复读）、adjacent_near_duplicate（相邻近重复 take）和 internal_immediate_repeat（句内即时口吃）。中文按字、英文按词归一化；默认至少 3 个单位、near-duplicate 相似度 0.90、相邻间隔不超过 2 秒。不同 speaker 默认不互判，可显式加 --include-speaker-changes。输出 speech_continuity_qa.v1 JSON / Markdown，--strict 命中返回 2；pipeline_manifest.py 会发现报告并把 summary.blocking > 0 视为发布 blocker，也支持 --require speech_continuity_qa。同步更新 SKILL 和 Speech Continuity QA 提示词。

使用方式：先对已渲染 master运行 extract_audio.py 和 transcribe.py，再执行 python3 scripts/speech_continuity_qa.py output/final_transcript.json --output verify/speech_continuity_qa.json --markdown verify/speech_continuity_qa.md --strict。如果退出 2，按报告时间范围试听 master，并用 timeline_view.py --at 看切点；调整源 render_config / cut list 后重新渲染、重新转录、复跑，不能复用源素材 transcript 或在成片上二次拼补。

验证结果：定向 .venv/bin/python -m pytest tests/test_speech_continuity_qa.py tests/test_pipeline_manifest.py -q 通过 50 passed in 0.49s；最终全量 .venv/bin/python -m pytest tests -q 通过 518 passed in 4.61s。测试覆盖中英 token 化、最长边界复读、句内口吃及 segment evidence、近重复 take、跨 speaker 默认跳过、clean ready、Markdown、strict CLI 和 manifest blocker / required gate。.venv/bin/python -m compileall -q scripts tests、speech_continuity_qa.py --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-15 自动化升级记录（Jump Cut Removal Budget）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/jump_cut.py 新增默认 --max-removal-ratio 0.20 删除预算。计划现在写入 version=jump_cut_plan.v2、status、removal_budget、blockers / warnings 和 summary.blocking；预计删除超过 20% 时仍会先写 cut list，但 dry-run 加 --strict 返回 2，实际渲染无论是否 strict 都返回 2 且不产生输出。人工检查 removed_segments 与 timeline_view.py 复盘图后，可调高预算，或用 --allow-over-budget 明确批准；批准会留在 JSON 的 removal_budget.override=true 和 warning 中。pipeline_manifest.py 现在把未批准的超预算 jump cut 识别为 rough_cut blocker；同步更新 SKILL、每日工作流和 Jump Cut 提示词。

使用方式：先运行 python3 scripts/jump_cut.py input/talking.mp4 --dry-run --cut-list work/jump_cut.json --strict。如果退出 2，打开 JSON 检查 removal_budget.proposed_ratio 和 removed_segments，再用 timeline_view.py --cut-list work/jump_cut.json 看切点。确认全部删除段都安全后，可调整 --min-silence / --pad / --max-removal-ratio，或在渲染命令上显式加 --allow-over-budget；不要把 override 当成默认参数。

验证结果：定向 .venv/bin/python -m pytest tests/test_jump_cut.py tests/test_pipeline_manifest.py -q 通过 47 passed in 0.45s；最终全量 .venv/bin/python -m pytest tests -q 通过 505 passed in 5.55s。10 秒真实 FFmpeg 样片含 3 秒静音，默认计划得到 proposed_ratio=0.284：strict dry-run 与实际渲染均返回 2，未生成 blocked MP4；加 --allow-over-budget 后得到 status=ready、override=true、warnings=1，成功输出 7.163 秒 MP4。.venv/bin/python -m compileall -q scripts tests、jump_cut.py --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-14 自动化升级记录（Rendered Cut Boundary Review）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/timeline_view.py 新增 --rendered-cut-list，读取 rough/jump cut 的 keep_segments，按输出顺序累计每段时长并为每个真实拼接点生成 filmstrip + waveform PNG。--output-speed 支持成片全局变速，--output-offset 支持片头封面/前置时长；两者映射不匹配、计算切点超过实际成片时长时会显式报错。JSON manifest 新增 mode=rendered_output_boundaries 和每张图的 boundary：包含 output_time、前后 source range 与被跳过的 source_gap。原有 --cut-list 源素材复核保持兼容；同步更新 SKILL、docs/prompts/22-timeline-view.md 和提示词索引。

使用方式：rough/jump cut 渲染完成后运行 python3 scripts/timeline_view.py output/rough_cut.mp4 --rendered-cut-list work/rough_cut.json --output-speed 1.25 --output-offset 1.0 --output-dir output/verify/rendered_cuts --json output/verify/rendered_cuts.json。逐张查看切点前后的主体位置、字幕/overlay 遮挡、黑闪和 waveform 硬断；要看源素材里被删区间，仍使用 --cut-list。

验证结果：tests/test_timeline_view.py 从 7 项扩展到 11 项，覆盖累计输出时间、变速、片头偏移、limit、source gap、窗口定位和成片时长错配；定向 .venv/bin/python -m pytest tests/test_timeline_view.py -q 通过 11 passed in 0.03s，最终全量 .venv/bin/python -m pytest tests -q 通过 502 passed in 5.46s。8 秒真实 FFmpeg smoke 含两段 1 秒静音，jump_cut.py 输出 6.433 秒成片，新模式准确定位 2.10s / 4.30s 两个拼接点并生成两张 1600×490 RGB PNG；人工查看图中切点前后 filmstrip 与 waveform 均位于预期窗口。.venv/bin/python -m compileall -q scripts tests、timeline_view.py --help、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-13 自动化升级记录（Timecoded Review Proxy）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/review_proxy.py，可把任何已渲染 master / platform MP4 转成低码率完整审片副本，默认不放大源视频、最大 720p、24fps、H.264 libx264 veryfast、CRF 28、AAC 96k、yuv420p 和 +faststart；左上角默认烧入 REVIEW PROXY + elapsed timecode。脚本同时输出 review_proxy.v1 JSON 和 Markdown，记录源/代理媒体参数、完整可复现 FFmpeg 命令、warning 与“不可发布”说明；--dry-run 只出计划，--no-timecode 可关闭时间码。edit_brief_plan.py 新增“审片代理/低码率时间码审片”路由，pipeline_manifest.py / review_dashboard.py 可发现 review proxy，但默认不阻塞发布；新增 docs/prompts/66-review-proxy.md。

使用方式：python3 scripts/review_proxy.py output/day66_master.mp4 --output verify/day66_review_proxy.mp4 --manifest verify/day66_review_proxy.json --markdown verify/day66_review_proxy.md。把 *_review_proxy.mp4 发给审片人，要求按画面可见时间码反馈；具体疑点再用 timeline_view.py --at 深查。最终 QA、平台导出和发布仍必须使用 master，不得把 review proxy 当成片。

验证结果：新增 tests/test_review_proxy.py 7 项，更新 tests/test_edit_brief_plan.py 和 tests/test_pipeline_manifest.py；定向 .venv/bin/python -m pytest tests/test_review_proxy.py tests/test_edit_brief_plan.py tests/test_pipeline_manifest.py -q 通过 51 passed in 0.48s；最终全量 .venv/bin/python -m pytest tests -q 通过 498 passed in 4.74s。4 秒真实 FFmpeg smoke 生成 360×640、24fps、H.264/AAC、4.01 秒的代理，抽取 1.25 秒帧确认双行 label/timecode 在小竖屏完整可读；文件头 ftyp 后紧接 moov（offset 0x20），确认 +faststart 生效。新增回归测试确认 *_master_review_proxy.mp4 不能误满足正式 master gate。.venv/bin/python -m compileall -q scripts tests、review_proxy.py --help、edit_brief_plan.py --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-12 自动化升级记录（Audio-aware Boundary Snap）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/audio_boundary_snap.py，可读取 highlight_candidates.v1 或其他含 selected[] / segments[] / clips[] 的候选计划，以及 Whisper segments[].words[] 或 ElevenLabs Scribe 顶层 words[]。脚本把 start/end 校正到完整词，在 --sentence-window 内补到句末，用 transcript silences[] 或可选 --media + FFmpeg silencedetect 吸附静音区中点，输出 audio_boundary_plan.v1 JSON/Markdown；每条保留 original/snapped time、delta、reason、首尾词、warning 和 blocker。shorts_batch.py 现在直接接受该输出并把 audio_boundary_snap 写入 per-short render config；edit_brief_plan.py 的长视频拆短路由会自动把它排在 highlight 与 batch 之间；pipeline_manifest.py 新增 audio_boundary_plan 类别，发现 summary.blocking > 0 会阻塞。

使用方式：先跑 highlight_picker.py 并人工确认 selected 候选，再运行 python3 scripts/audio_boundary_snap.py --candidates work/highlight_candidates.json --transcript work/long_transcript.json --media origin/long-talk.mp4 --output work/audio_boundary_plan.json --markdown work/audio_boundary_plan.md --strict；打开 Markdown 复核 start/end delta 后，用 python3 scripts/shorts_batch.py --highlights work/audio_boundary_plan.json --video origin/long-talk.mp4 --output work/shorts_batch.json --strict 继续。缺词级时间戳、非法范围、显式媒体缺失或安全边界超平台时长会形成 blocker。详细说明见 docs/prompts/65-audio-boundary-snap.md。

验证结果：新增 tests/test_audio_boundary_snap.py 8 项，更新 tests/test_edit_brief_plan.py、tests/test_pipeline_manifest.py 和 tests/test_shorts_batch.py；定向 .venv/bin/python -m pytest tests/test_audio_boundary_snap.py tests/test_edit_brief_plan.py tests/test_shorts_batch.py tests/test_pipeline_manifest.py -q 通过 53 passed in 0.52s；最终全量 .venv/bin/python -m pytest tests -q 通过 487 passed in 4.42s。8 秒真实 FFmpeg smoke 检出 3 段静音，把候选从 1.1-3.0s 校正到 0.5-4.5s，句末扩展、静音吸附、summary.blocking=0 均符合预期；.venv/bin/python -m compileall -q scripts tests、audio_boundary_snap.py --help、edit_brief_plan.py --help、manifest category smoke、skill quick_validate.py 和 git diff --check 全部通过。

2026-07-11 自动化升级记录（Audio-event-aware Takes Pack）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/takes_pack.py 现在除 segments[].words[] 外，也能直接读取 ElevenLabs Scribe 风格的顶层 words[]；type=spacing 不会混进正文，speaker_id 会和原有 speaker 一样触发 phrase 分段，type=audio_event 会以 (laughter) 形式留在可读文本，并在 phrases[].audio_events[] 中保留 label/start/end。summary.audio_events 与 sources[].audio_events 便于快速确认事件覆盖；没有 Scribe 或 ElevenLabs API key 也不影响原有 Whisper transcript 路径。

使用方式：python3 scripts/takes_pack.py --transcript interview=work/scribe_transcript.json --output work/takes_packed.md --json work/takes_pack.json --break-gap 0.5。打开 Markdown 的 Events 列复核笑声、掌声、叹气、音乐等反应节拍；选段时保留事件前后余量，再把 phrase time range 交给 highlight_picker.py、render_config.json 或 NLE handoff。详细格式见 docs/prompts/60-takes-pack.md。

验证结果：新增 tests/test_takes_pack.py 顶层 Scribe words / spacing / speaker_id / audio_event 覆盖；.venv/bin/python -m pytest tests/test_takes_pack.py -q 通过 6 passed in 0.06s；.venv/bin/python scripts/takes_pack.py --help、.venv/bin/python -m compileall -q scripts tests、skill quick_validate.py 和 git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 477 passed in 4.26s。

2026-07-09 自动化升级记录（Edit Brief Plan Router）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/edit_brief_plan.py，可从 --brief 或 --brief-file 读取自然语言剪辑需求，自动识别源素材路径、目标平台、长视频拆条、批量短视频、字幕、B-roll、生成素材、BGM/SFX、去停顿、PIP、录屏聚焦、调色、QA、NLE handoff 和发布包等信号，输出 edit_brief_plan.v1 JSON 与 Markdown runbook。新增 docs/prompts/64-edit-brief-plan.md，更新 daily workflow、提示词目录、SKILL、README 和 pipeline_manifest.py artifact 类别；edit_brief_plan.json 默认不阻塞，但当自身 summary.blocking > 0（如 brief 为空或显式 source 缺失）时会作为 gate blocker。

使用方式：先运行 python3 scripts/edit_brief_plan.py --brief "把 origin/interview.mp4 剪成三条抖音短视频，去停顿，加B-roll、BGM和字幕，最后生成发布包" --project-dir . --output work/edit_brief_plan.json --markdown work/edit_brief_plan.md --strict；打开 work/edit_brief_plan.md 检查每一步命令和产物，再按需要执行 runbook。需要把需求路由作为显式 gate 时用 python3 scripts/pipeline_manifest.py --project-dir . --target-stage analysis --require edit_brief_plan --strict。

验证结果：新增 tests/test_edit_brief_plan.py 6 项，更新 tests/test_pipeline_manifest.py 2 项；.venv/bin/python -m pytest tests/test_edit_brief_plan.py tests/test_pipeline_manifest.py -q 通过 38 passed in 0.38s；.venv/bin/python scripts/edit_brief_plan.py --help、.venv/bin/python scripts/pipeline_manifest.py --list-categories | rg edit_brief_plan smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 476 passed in 4.67s。

2026-07-08 自动化升级记录（Shorts Batch Planner）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/shorts_batch.py，读取 highlight_picker.py 产出的 highlight_candidates.v1，为每个 selected[] 生成独立 render_config、计划输出 MP4、render_final.py 命令、render_qa.py 命令和 shorts_batch.v1 JSON/Markdown job sheet。新增 docs/prompts/63-shorts-batch.md，更新提示词目录、SKILL、README 和 pipeline_manifest.py artifact 类别；shorts_batch.json 默认不阻塞，但当自身 summary.blocking > 0（如源视频缺失）时会作为 publish/render gate blocker。

使用方式：先运行 highlight_picker.py 选出多个精华候选，再运行 python3 scripts/shorts_batch.py --highlights work/highlight_candidates.json --video origin/long-talk.mp4 --output work/shorts_batch.json --markdown work/shorts_batch.md --render-config-dir work/shorts_render_configs --output-dir output/shorts --qa-dir verify/shorts --basename day63 --platform douyin --strict；打开 work/shorts_batch.md 确认每条 job 后，逐条执行表内 render_shell 和 qa_shell。

验证结果：新增 tests/test_shorts_batch.py 5 项，更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_shorts_batch.py tests/test_pipeline_manifest.py -q 通过 35 passed in 0.40s；.venv/bin/python scripts/shorts_batch.py --help、.venv/bin/python scripts/pipeline_manifest.py --list-categories | rg shorts_batch smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 468 passed in 5.25s。

2026-07-07 自动化升级记录（Hook Variants）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/hook_variants.py，可从 transcript.json、clean_script.md、--topic 和 --persona 生成 hook_variants.v1；内置 pattern_interrupt、pain_question、number_map、contrast_turn、proof_first、time_box、mistake_fix、identity_lens 8 类前三秒 hook；自动按平台限制长度，调用 content_guard.scan_text() 标记导流、极限词、医疗/财富等风险，输出推荐排序、visual cue、pacing、source terms 和 Markdown review 表。新增 docs/prompts/62-hook-variants.md，更新 daily workflow、SKILL、提示词目录、README 和 pipeline_manifest.py artifact 类别。

使用方式：转写后先跑 python3 scripts/hook_variants.py --transcript work/transcript.json --topic "AI剪辑" --persona "剪辑师" --platform xhs --output work/hook_variants.json --markdown work/hook_variants.md --strict；打开 work/hook_variants.md 选择一个 hook_XX，把对应 hook 文本放进 rewrite_script.py --emit-prompt 生成的 LLM 提示，或直接替换 clean_script.md 的 ## Hook 段。需要把这一步作为 review gate 时用 python3 scripts/pipeline_manifest.py --project-dir . --target-stage analysis --require hook_variants --strict。

验证结果：新增 tests/test_hook_variants.py 7 项，更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_hook_variants.py tests/test_pipeline_manifest.py -q 通过 35 passed in 0.38s；.venv/bin/python scripts/hook_variants.py --help、.venv/bin/python scripts/pipeline_manifest.py --list-categories | rg hook_variants smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 461 passed in 4.61s。

2026-07-06 自动化升级记录（Project Bootstrap）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/project_bootstrap.py，可从一个或多个素材文件/目录创建 origin/、work/、output/、verify/、edit/，按 raw/broll/audio/bgm/image/asset/sidecar 分类复制或 hardlink 素材，并输出 project_bootstrap.v1 的 work/source_inventory.json、work/source_inventory.md、project.md 和 next_steps.md。scripts/pipeline_manifest.py 新增 source_inventory artifact 类别；需要把素材导入作为 analysis gate 时可 --require source_inventory。新增 docs/prompts/61-project-bootstrap.md，并更新 README、SKILL 和提示词目录。

使用方式：新项目开工先运行 python3 scripts/project_bootstrap.py --source ~/Downloads/raw-shoot --project-dir work/day61 --title "Day61 launch edit" --strict；检查 work/day61/work/source_inventory.md 后，对主素材跑 transcribe.py，再用 python3 scripts/pipeline_manifest.py --project-dir work/day61 --target-stage analysis --require source_inventory --strict 确认项目入口和 transcript gate。默认 --mode copy 不改外部原始素材；同盘大素材可用 --mode hardlink，失败会回退 copy 并记录 warning。

验证结果：新增 tests/test_project_bootstrap.py 6 项，更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_project_bootstrap.py tests/test_pipeline_manifest.py -q 通过 33 passed in 0.35s；.venv/bin/python scripts/project_bootstrap.py --help 和 .venv/bin/python scripts/pipeline_manifest.py --list-categories | rg source_inventory smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 453 passed in 4.60s。

2026-07-05 自动化升级记录（Takes Pack）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/takes_pack.py，可读取多份 transcript.json（支持 label=path 或 --transcripts-dir），按 word/segment 时间戳、静音 gap 和 speaker change 生成 takes_packed.md 与 takes_pack.v1 JSON。pipeline_manifest.py 新增 takes_pack 可发现 artifact 类别，但默认不阻塞发布；需要强制多 take review 时可 --require takes_pack。新增 docs/prompts/60-takes-pack.md，并更新 README、SKILL 和提示词目录。

使用方式：多 take 粗选前运行 python3 scripts/takes_pack.py --transcript take1=work/take1_transcript.json --transcript take2=work/take2_transcript.json --output work/takes_packed.md --json work/takes_pack.json --break-gap 0.5；让 agent/剪辑师按 take1-003 这类 phrase id 或源时间码挑选最佳表达，再进入 highlight_picker.py、srt_edit_plan.py、render_config.json 或 EDL/FCPXML/OTIO。

验证结果：新增 tests/test_takes_pack.py 5 项，更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_takes_pack.py tests/test_pipeline_manifest.py -q 通过 31 passed in 0.33s；.venv/bin/python scripts/takes_pack.py --help 和 .venv/bin/python scripts/pipeline_manifest.py --list-categories | rg takes_pack smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 446 passed in 4.02s。

2026-07-04 自动化升级记录（Auto Emphasis Cues）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/auto_emphasis.py，可从 transcript 检测 question_hook、numeric_claim、contrast_turn、payoff_line、risk_warning 和 pause_resume，输出 auto_emphasis_plan.v1 JSON + Markdown review；scripts/auto_enrich.py 现在会把 emphasis_cues[] 放进综合 enrich plan；scripts/render_final.py 会把 cue 转成 timed ASS badge 和无红框的轻微 center push-in；scripts/edit_preflight.py 会检查 emphasis cue 的时间、label、zoom 和坐标风险；scripts/pipeline_manifest.py 会把 emphasis_plan.json 识别为 enrich artifact。新增 docs/prompts/59-auto-emphasis.md，并更新 Auto-Enrich 文档、提示词索引、SKILL 和 README。

使用方式：单独生成强调计划用 python3 scripts/auto_emphasis.py --transcript work/transcript.json --output work/emphasis_plan.json --markdown work/emphasis_plan.md --min-interval 3 --max-cues 12；渲染前用 python3 scripts/edit_preflight.py --config work/render_config.json --enrich-plan work/emphasis_plan.json --output work/edit_preflight.json --markdown work/edit_preflight.md --strict；最终渲染加 python3 scripts/render_final.py --config work/render_config.json --enrich-plan work/emphasis_plan.json --output output/master.mp4。如果已经跑完整自动丰富，直接用 auto_enrich.py --output work/enrich_plan.json，其中会自动包含 emphasis_cues[]。

验证结果：新增 tests/test_auto_emphasis.py 4 项，并更新 tests/test_auto_enrich.py、tests/test_render_enrich_plan.py、tests/test_edit_preflight.py 和 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_auto_emphasis.py tests/test_auto_enrich.py tests/test_render_enrich_plan.py tests/test_edit_preflight.py tests/test_pipeline_manifest.py -q 通过 46 passed in 0.58s；.venv/bin/python scripts/auto_emphasis.py --help、.venv/bin/python scripts/auto_enrich.py --help、.venv/bin/python scripts/render_final.py --help 和 .venv/bin/python scripts/edit_preflight.py --help smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；最终全量 .venv/bin/python -m pytest tests -q 通过 440 passed in 4.96s。

2026-07-03 自动化升级记录（OTIO NLE Handoff）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/export_otio.py，可读取 render_config.json、rough_cut.py 或 jump_cut.py 的 keep_segments，输出 OpenTimelineIO .otio 和 .json manifest。OTIO timeline 使用 Timeline.1 / Stack.1 / Track.1 / Clip.2 结构，默认写 V1 视频 track 和 A1 音频 track；--no-audio-track 可只导出视频，--include-transcript-metadata 可把口播文本写进 clip metadata。pipeline_manifest.py 的 nle_handoff 类别新增 .otio / .otio.json 发现规则；README、SKILL、daily workflow 和 docs/prompts/27-export-edl.md 已同步为 EDL/FCPXML/OTIO 三种交接格式。

使用方式：从成片配置导出用 python3 scripts/export_otio.py --config work/render_config.json --output work/day58_edit.otio --fps 30 --title DAY58_EDIT；从粗剪 cut list 导出用 python3 scripts/export_otio.py --cut-list work/rough_cut.json --output work/rough_cut.otio --fps 30 --include-transcript-metadata。复杂字幕、overlay、章节卡、B-roll 和生成素材仍以 render_final.py / export_capcut.py / JSON manifest 为准；OTIO 只负责轻量选段时间线交接。

验证结果：新增 tests/test_export_otio.py 5 项，更新 tests/test_pipeline_manifest.py 覆盖 NLE handoff 发现；.venv/bin/python -m pytest tests/test_export_otio.py tests/test_export_edl.py tests/test_export_fcpxml.py tests/test_pipeline_manifest.py -q 通过 40 passed in 0.40s；.venv/bin/python scripts/export_otio.py --help、.venv/bin/python scripts/pipeline_manifest.py --list-categories | rg nle_handoff smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；最终全量 .venv/bin/python -m pytest tests -q 通过 434 passed in 4.48s。

2026-07-02 自动化升级记录（Source Receipts）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/source_receipts.py，读取 source_claims.json 或 --claim 内联 claim，输出 source_receipts.v1、Markdown review 和可直接打开的 HTML source deck。每条 claim 支持 text、source_url、source_title、source_type、screenshot/source_file、risk 和 timecode；高风险 claim（news/data/finance/health/legal 等）必须有 URL，--require-screenshot 可强制本地截图/证据文件，--require-primary-source 可强制官方/primary/owned/government/academic 等来源类型。pipeline_manifest.py 新增 source_receipts artifact 类别，发现 summary.blocking > 0 会作为 publish blocker；新增 docs/prompts/58-source-receipts.md，并更新 daily workflow、SKILL、提示词目录和 README。

使用方式：先写 work/source_claims.json，再跑 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。事实型视频发布前可用 python3 scripts/pipeline_manifest.py --project-dir . --target-stage publish_ready --require source_receipts --strict 强制检查；纯观点类视频可跳过。

验证结果：新增 tests/test_source_receipts.py 8 项，更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_source_receipts.py tests/test_pipeline_manifest.py -q 通过 31 passed in 0.31s；.venv/bin/python scripts/source_receipts.py --help、.venv/bin/python scripts/pipeline_manifest.py --list-categories | rg source_receipts smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 428 passed in 4.86s。

2026-07-01 自动化升级记录（Review Dashboard）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/review_dashboard.py，从项目目录扫描现有 artifacts，复用 pipeline_manifest.py 输出 review_dashboard.v1 JSON 和可直接打开的 review_dashboard.html。它把 missing required、blocking 和 warning gate 排进 review_items[]，保留 next_actions[]、latest_artifacts[] 和完整 gate_snapshot[]；pipeline_manifest.py 新增 review_dashboard 可发现 artifact 类别但不把它作为发布 blocker。新增 docs/prompts/57-review-dashboard.md，并更新 README、SKILL 和提示词目录。

使用方式：发布确认或自动化收尾前运行 python3 scripts/review_dashboard.py --project-dir work/day58 --target-stage publish_ready --output work/day58/review_dashboard.json --html work/day58/review_dashboard.html --strict；需要额外要求音频/发布包 gate 时可重复加 --require audio_master_report --require publish_package；打开 HTML 后先处理 Review Queue，再按 Next Actions 补跑脚本。

验证结果：新增 tests/test_review_dashboard.py 4 项，更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_review_dashboard.py tests/test_pipeline_manifest.py -q 通过 25 passed in 0.30s；.venv/bin/python scripts/review_dashboard.py --help 和 .venv/bin/python scripts/pipeline_manifest.py --list-categories | rg review_dashboard smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 418 passed in 5.11s。

2026-06-29 自动化升级记录（SRT Edit Plan）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/srt_edit_plan.py，可读取 SRT 和人工/agent 写的 keep/drop 指令，输出 srt_edit_plan.v1 JSON、render_config.json、按原素材时间排序的 cut list 和 Markdown review；支持 title/platform/cover_style/profile metadata，支持 keep/include/use/select 与 drop/skip/exclude/remove，--require-all-reviewed --strict 可把未复核字幕段作为 blocking。新增 docs/prompts/55-srt-edit-plan.md，并更新 README、SKILL 和提示词目录。

使用方式：先写 work/edit_guide.md，例如 keep 3-5: 先用产品发布和用户反应、drop 1-2: 铺垫太慢、keep 8: 补一句核心结论；再运行 python3 scripts/srt_edit_plan.py --srt work/captions.srt --guide work/edit_guide.md --source-media origin/talking.mp4 --output work/srt_edit_plan.json --render-config work/render_config.json --cut-list work/srt_edit_cut.json --markdown work/srt_edit_plan.md --strict。切点复核用 timeline_view.py --cut-list work/srt_edit_cut.json，最终渲染用 render_final.py --config work/render_config.json。

验证结果：新增 tests/test_srt_edit_plan.py 4 项；.venv/bin/python -m pytest tests/test_srt_edit_plan.py tests/test_import_capcut_subtitles.py tests/test_subtitle_pack.py tests/test_export_edl.py tests/test_export_fcpxml.py -q 通过 24 passed in 0.24s；.venv/bin/python scripts/srt_edit_plan.py --help smoke 通过；.venv/bin/python -m compileall scripts tests 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 406 passed in 4.42s。

2026-06-28 自动化升级记录（Audio Master Report）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/audio_master_report.py，用 FFmpeg ebur128=peak=true 和 silencedetect 输出 audio_master_report.v1 JSON/Markdown，检查 integrated LUFS、true peak、LRA 和长静音总量；默认门槛为 -16 LUFS ±2 LU、true peak ≤ -1 dBFS、LRA ≤ 18 LU、长静音总量 ≤ 3 秒。pipeline_manifest.py 新增 audio_master_report artifact 类别，发现 summary.blocking > 0 会作为 publish gate 阻塞。新增 docs/prompts/54-audio-master-report.md，并更新 daily workflow、提示词目录、SKILL 和 README。

使用方式：渲染和 render_qa.py 后运行 python3 scripts/audio_master_report.py output/day58_master.mp4 --output output/day58_audio_master_report.json --markdown output/day58_audio_master_report.md --strict。脚本只读最终文件，不重写媒体、不上传、不调用 provider；失败时优先回到 render_final.py 默认响度链路重新渲染，不要反复压缩已完成 master。

验证结果：新增 tests/test_audio_master_report.py 7 项，并更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_audio_master_report.py tests/test_pipeline_manifest.py -q 通过 26 passed in 0.24s；.venv/bin/python scripts/audio_master_report.py --help smoke 通过；合成 1.5 秒 FFmpeg MP4 smoke 成功输出 JSON/Markdown，并正确把 -21.1 LUFS tone 标为 blocking；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 402 passed in 4.26s。

2026-06-23 自动化升级记录（Edit Preflight Gate）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/edit_preflight.py，输出 edit_preflight.v1 JSON 和 Markdown，可检查 render_config.clips[] 非空、视频/图片/音频路径存在、direct start/end 或 transcript + segment_id 时间段合法、B-roll/image/PIP overlay 路径和时间线边界、focus 像素坐标是否缺 source_width/source_height、PIP width_ratio/opacity/source_start 等风险参数，以及 rough/jump cut keep_segments[]。pipeline_manifest.py 新增 edit_preflight artifact 类别；只要项目里已有 unresolved edit_preflight.json 且 summary.blocking > 0，manifest 会把它列为 blocking gate。新增 docs/prompts/53-edit-preflight.md，并更新 daily workflow、提示词目录、SKILL 和 README。

使用方式：渲染前跑 python3 scripts/edit_preflight.py --config work/render_config.json --enrich-plan work/enrich_plan.json --output work/edit_preflight.json --markdown work/edit_preflight.md --strict。如果有多个计划文件可重复传 --enrich-plan，如果要检查 rough/jump cut 结果可加 --cut-list work/jump_cut.json。脚本不会渲染、上传、下载或提交任何付费生成任务；渲染后仍需跑 render_qa.py。

验证结果：新增 tests/test_edit_preflight.py 7 项，并更新 tests/test_pipeline_manifest.py；.venv/bin/python -m pytest tests/test_edit_preflight.py tests/test_pipeline_manifest.py -q 通过 25 passed in 0.24s；.venv/bin/python scripts/edit_preflight.py --help smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 394 passed in 3.94s。

2026-06-23 自动化升级记录（Jump Cut Audio Fades）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/jump_cut.py 新增 --fade-duration，默认 0.03 秒。渲染时每个 keep_segments[] 音频片段会在同一个 atrim/asetpts filter chain 中追加 afade=t=in 和 afade=t=out，不增加中间文件、不改变单次 concat 编码模型。短片段会自动把 fade 限制到片段时长的一半；需要完全硬切原声时可传 --fade-duration 0。cut list JSON 新增 fade_seconds 字段，方便后续 EDL/FCPXML/复核时知道实际音频边界策略。README、SKILL、docs/prompts/21-jump-cut.md、docs/prompts/15-xhs-daily-tech-video.md 和提示词索引已同步。

使用方式：先审查切点仍用 python3 scripts/jump_cut.py input/talking.mp4 --dry-run --cut-list output/talking.jumpcut.json；确认后渲染用 python3 scripts/jump_cut.py input/talking.mp4 --output output/talking.jumpcut.mp4 --cut-list output/talking.jumpcut.json --fade-duration 0.03。如需旧行为，传 --fade-duration 0。

验证结果：新增/更新 tests/test_jump_cut.py 3 项覆盖默认 fade、关闭 fade、短片段 fade clamp；.venv/bin/python -m pytest tests/test_jump_cut.py -q 通过 8 passed in 0.04s；相关回归 .venv/bin/python -m pytest tests/test_jump_cut.py tests/test_export_edl.py tests/test_export_fcpxml.py -q 通过 19 passed in 0.17s；合成 1.2 秒 FFmpeg smoke 成功输出 MP4 且 cut list 含 fade_seconds: 0.03；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；全量 .venv/bin/python -m pytest tests -q 通过 386 passed in 4.41s。

2026-06-21 自动化升级记录（Project Resume Handoff）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/project_resume.py，可扫描项目目录并复用 pipeline_manifest.py 的 gate，输出 project_resume.v1、Markdown resume 和可选项目级 CLAUDE.md。内容包括 phase、recommended_first_action、next_actions[]、latest_artifacts[]、ready artifacts、关键 gate snapshot、guardrails 和可直接交给下一位 agent 的 suggested_prompt。新增 docs/prompts/52-project-resume.md，更新 daily workflow、提示词目录、SKILL 和 README。另将 SKILL.md frontmatter 规范化：移除旧的顶层 argument-hint，并把过长 description 压缩到 skill 校验器允许范围。

使用方式：自动化收尾或跨会话接手前跑 python3 scripts/project_resume.py --project-dir work/day58 --target-stage publish_ready --output work/day58/project_resume.json --markdown work/day58/project_resume.md --agent-note work/day58/CLAUDE.md --strict。如果只想写默认项目级 agent note，可用 --agent-note 不带路径，脚本会写到 --project-dir/CLAUDE.md。脚本不渲染、不上传、不提交任何付费生成任务。

验证结果：新增 tests/test_project_resume.py 5 项；.venv/bin/python -m pytest tests/test_project_resume.py tests/test_pipeline_manifest.py -q 通过 22 passed in 0.27s；.venv/bin/python scripts/project_resume.py --help smoke 通过；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python /Users/maxazure/.codex/skills/.system/skill-creator/scripts/quick_validate.py /Users/maxazure/projects/video-editing-skill 通过 Skill is valid!；git diff --check 通过；最终全量 .venv/bin/python -m pytest tests -q 通过 384 passed in 4.40s。

2026-06-20 自动化升级记录（PIP Overlay）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/pip_overlay.py，可把 facecam/camera 视频转成 pip_overlay_plan.v1，输出 pip_overlays[] 与 Markdown 复核表；支持多段 --segment "start,end[,position]"、--sync-offset、--source-start、--width-ratio、--margin-ratio、--opacity 和 --transition。render_final.py --enrich-plan 现在会合并 pip_overlays[]，把 camera 小窗作为 timed video overlay 接入 B-roll/image/focus 之后、字幕之前，并在 --primary-speed / --speed 输出中同步压缩 PIP 时间线；camera audio 默认忽略，避免污染主口播/BGM 音频链路。

使用方式：先跑 python3 scripts/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，例如 python3 scripts/render_final.py --config work/render_config.json --enrich-plan work/enrich_plan.json --enrich-plan work/screen_focus_plan.json --enrich-plan work/pip_overlay_plan.json --output output/tutorial_master.mp4。详细说明见 docs/prompts/51-pip-overlay.md。

验证结果：新增 tests/test_pip_overlay.py 8 项；.venv/bin/python -m pytest tests/test_pip_overlay.py tests/test_render_enrich_plan.py tests/test_screen_focus.py -q 通过 19 passed in 0.26s；.venv/bin/python -m compileall scripts tests 通过；.venv/bin/python scripts/pip_overlay.py --help 和 .venv/bin/python scripts/render_final.py --help smoke 验证通过；2 秒 FFmpeg 变速合成 smoke 验证 pip_overlays[] 可渲染为有效 MP4；最终全量 .venv/bin/python -m pytest tests -q 通过 379 passed in 4.01s。

2026-06-19 自动化升级记录（Prompt-Based Highlight Picker）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/highlight_picker.py 新增 --brief / --query，可把“产品发布 用户反应”“find the product reveal”这类自然语言意图拆成英文关键词和中文短语片段，并把 brief_match.score 纳入原有 hook/value/duration/completeness 打分。输出 JSON 和 Markdown 会显示 brief_match.matched_terms、score_breakdown.brief 和弱匹配 warning；--render-config 也会保留 brief_match 供后续渲染/复核。

使用方式：常规自动找精华仍用 python3 scripts/highlight_picker.py --transcript work/long_transcript.json --output work/highlights.json --markdown work/highlights.md --platform douyin --strict；定向找片段用 python3 scripts/highlight_picker.py --transcript work/long_transcript.json --brief "产品发布 用户反应 价格对比" --video origin/long-talk.mp4 --output work/brief_highlights.json --markdown work/brief_highlights.md --render-config work/brief_render_config.json --platform douyin --num-clips 3 --strict。详细说明见 docs/prompts/31-highlight-picker.md。

验证结果：新增/更新 tests/test_highlight_picker.py 2 项 brief/query 覆盖；.venv/bin/python -m pytest tests/test_highlight_picker.py -q 通过 9 passed in 0.07s；.venv/bin/python scripts/highlight_picker.py --help smoke 验证 --brief/--query 参数正常；.venv/bin/python -m compileall scripts tests 通过；git diff --check 通过；完整 .venv/bin/python -m pytest tests -q 通过 371 passed in 3.71s。

2026-06-18 自动化升级记录（FCPXML NLE Handoff）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/export_fcpxml.py，可读取 render_config.json、rough_cut.py 或 jump_cut.py 的 keep_segments，生成单 spine FCPXML 和 .json manifest；支持 --fps、--width、--height、--title、--source 和 --fcpxml-version。export_edl.py 保留，二者共享同一套 segment/event 解析。

使用方式：从成片配置导出用 python3 scripts/export_fcpxml.py --config work/render_config.json --output work/day58_edit.fcpxml --fps 30 --width 1080 --height 1920；从粗剪 cut list 导出用 python3 scripts/export_fcpxml.py --cut-list work/rough_cut.json --output work/rough_cut.fcpxml --fps 30。详细说明见 docs/prompts/27-export-edl.md。

验证结果：新增 tests/test_export_fcpxml.py 4 项；.venv/bin/python -m pytest tests/test_export_fcpxml.py -q 通过 4 passed in 0.06s；相关回归 .venv/bin/python -m pytest tests/test_export_fcpxml.py tests/test_export_edl.py tests/test_pipeline_manifest.py -q 通过 28 passed in 0.29s；完整 .venv/bin/python -m pytest tests -q 通过 369 passed in 4.76s；.venv/bin/python -m compileall scripts tests 通过；git diff --check 通过。

2026-06-17 自动化升级记录（CapCut Subtitle Import）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/import_capcut_subtitles.py，可从剪映/CapCut 草稿目录、draft_content.json 或 SRT 导入字幕，输出兼容本项目的 capcut_subtitle_transcript；可选 --cut-list 会按字幕间隙生成 keep_segments，供 timeline_view.py、export_edl.py 或后续粗剪流程复核；默认只导入 subtitle 材料，避免封面标题/贴纸文字混入 transcript，必要时用 --include-overlays 兜底。

使用方式：从剪映草稿导入用 python3 scripts/import_capcut_subtitles.py --draft ~/Movies/JianyingPro/User\ Data/Projects/com.lveditor.draft/day58 --transcript work/capcut_transcript.json --cut-list work/capcut_gap_cut.json --markdown work/capcut_subtitles.md --source-media origin/talking.mp4；从 SRT 导入用 python3 scripts/import_capcut_subtitles.py --srt exports/capcut_auto_captions.srt --transcript work/capcut_transcript.json --srt-output output/subtitles/capcut_clean.srt。详细示例见 docs/prompts/50-import-capcut-subtitles.md。

验证结果：新增 tests/test_import_capcut_subtitles.py 5 项；.venv/bin/python -m pytest tests/test_import_capcut_subtitles.py -q 通过 5 passed in 0.05s；完整 .venv/bin/python -m pytest tests -q 通过 365 passed in 4.87s；.venv/bin/python -m compileall scripts tests 通过；git diff --check 通过；.venv/bin/python scripts/import_capcut_subtitles.py --help smoke 验证 CLI 参数正常。

2026-05-27 自动化升级记录（Subtitle Pack）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/subtitle_pack.py，可从 transcript.json 或 render_config.json 导出 SRT、VTT、ASS 和 JSON manifest；默认中文 18 字单行、英文 42 字单行，优先按标点/词边界切分；如果 transcript 带 words[]，会用词级时间戳生成更准的 cue；--config 会按最终 clips 串接时间线，--speed 和 --offset 用来对齐 render_final.py --primary-speed 和片头封面秒数。

使用方式：原始转写字幕用 python3 scripts/subtitle_pack.py --transcript work/day58_transcript.json --output-dir output/subtitles --basename day58 --formats srt vtt ass json；最终成片字幕用 python3 scripts/subtitle_pack.py --config work/render_config.json --output-dir output/subtitles --basename day58_master --speed 1.25 --offset 2.0。详细示例见 docs/prompts/29-subtitle-pack.md。

验证结果：新增 tests/test_subtitle_pack.py 4 项；.venv/bin/python -m pytest tests/test_subtitle_pack.py -q 通过 4 passed in 0.06s；完整 .venv/bin/python -m pytest tests -q 通过 218 passed in 3.28s；.venv/bin/python -m compileall scripts tests 通过；git diff --check 通过；.venv/bin/python scripts/subtitle_pack.py --help smoke 验证 CLI 参数正常。

2026-05-26 自动化升级记录（Media Library Recommend）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/media_library.py 新增 recommend 子命令，可从 media_index.json / media_index.db 中按查询词、tag、文件名、metadata、关联 transcript、时长覆盖和目标画幅给本地素材打分；scripts/storyboard_assets.py 新增 --media-library，会把 media_library_broll shot 的 ranked B-roll 候选写入 candidate_paths 和 candidate_scores，Markdown 复核表会显示候选分数。

使用方式：先用 python3 scripts/media_library.py scan . 建索引，再跑 python3 scripts/media_library.py recommend "AI workflow dashboard" --project-dir . --category broll --target-duration 3 --target-aspect 9:16 --json；分镜预检时加 --media-library .，例如 python3 scripts/storyboard_assets.py --storyboard-plan work/storyboard_plan.json --asset-root work --media-library . --output work/storyboard_assets.json --markdown work/storyboard_assets.md。

验证结果：新增 tests/test_media_library_recommend.py 3 项，并更新 tests/test_storyboard_assets.py；.venv/bin/python -m pytest tests/test_media_library_recommend.py tests/test_storyboard_assets.py -q 通过 9 passed in 0.11s；完整 .venv/bin/python -m pytest tests -q 通过 214 passed in 2.21s；.venv/bin/python -m compileall scripts tests 通过；git diff --check 通过；python3 scripts/media_library.py recommend --help smoke 验证 CLI 参数正常。

2026-05-25 自动化升级记录（Render QA Review Packet）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/render_qa.py 增加 --review-dir，可把黑屏、静帧、静音检测出的可疑区间汇总成 render_qa_review.json 和 render_qa_review.md；加 --review-clips 时会为每个可疑区间抽取带上下文的短 MP4 到 clips/。新增 build_review_segments() / write_review_packet()，便于自动化流水线复用。

使用方式：python3 scripts/render_qa.py output/day58_master.mp4 --platform douyin --json output/day58_qa.json --review-dir output/verify/day58_qa --review-clips；只想生成复核表、不抽视频片段时去掉 --review-clips。可用 --review-padding 1.0 调整前后文秒数，用 --max-review-segments 12 控制证据数量。

验证结果：新增/更新 tests/test_render_qa.py，.venv/bin/python -m pytest tests/test_render_qa.py -q 通过 9 passed in 0.02s；完整 .venv/bin/python -m pytest tests -q 通过 210 passed in 2.20s；.venv/bin/python -m compileall scripts tests 通过；git diff --check 通过；2 秒黑屏/静音合成视频 smoke 验证 --review-dir --review-clips 会写出 Markdown、JSON 和 2 个证据 MP4。

2026-05-25 自动化升级记录（Screen Focus）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/screen_focus.py 可读取 JSON/CSV/inline 点击事件，把像素或 0-1 坐标标准化为 screen_focus_plan.v1，输出 focus_events[] 和 Markdown 复核表；render_final.py --enrich-plan 现在可重复传入，并能把 focus_events 转成 timed zoom crop、提示框和可选 label badge。

使用方式：先跑 python3 scripts/screen_focus.py --events work/clicks.json --screen-width 1920 --screen-height 1080 --output work/screen_focus_plan.json --markdown work/screen_focus_plan.md；渲染时追加 --enrich-plan work/screen_focus_plan.json，或和 work/enrich_plan.json 一起重复传入。

验证结果：新增 tests/test_screen_focus.py 6 项通过；相关回归 tests/test_render_enrich_plan.py 5 项通过；完整 .venv/bin/python -m pytest tests -q 通过 208 passed in 3.10s；python3 -m compileall scripts tests 通过；git diff --check 通过；inline --event smoke 输出了有效 screen_focus_plan.v1，2 秒合成视频实测 focus_events 可成功渲染为有效 MP4。

2026-05-21 自动化升级记录

本次联网研究的 GitHub 参考：

新增/调整能力：next_versioned_output_path() 会扫描同目录已有 *_V.mp4，自动选下一个版本；CLI 增加 --versioned-output，配置文件支持 "versioned_output": true；多平台 --formats 改为基于实际版本主文件导出。

使用方式：在最终渲染命令加 --versioned-output，或在 render config 写入 "versioned_output": true。

验证结果：新增/相关测试 12 项通过；完整 .venv/bin/python -m pytest tests -q 通过 180 项；python3 -m compileall scripts tests 通过；真实 1 秒 ffmpeg 合成验证了 master.mp4 会输出为 master_V1.mp4。

2026-05-22 自动化升级记录

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/storyboard_plan.py 可把 transcript.json 和可选 clean_script.md 转为 storyboard_plan.json / storyboard_plan.md，为每个 shot 标注时间码、叙事段落、画面语言、生成路由、fallback、连续性锚点和 review checks；scripts/storyboard_assets.py 可把分镜转成素材 readiness manifest，标出 ready / candidate_found / needs_generation / needs_approval / needs_render / search_needed，其中 dreamina_video 只做规划并明确提示可能消耗 credits。

使用方式：先跑 python3 scripts/storyboard_plan.py --transcript work/transcript.json --clean-script work/clean_script.md --output work/storyboard_plan.json --markdown work/storyboard_plan.md --max-shots 8 --target-aspect 9:16，再跑 python3 scripts/storyboard_assets.py --storyboard-plan work/storyboard_plan.json --asset-root work --output work/storyboard_assets.json --markdown work/storyboard_assets.md --strict 做渲染前素材预检。

验证结果：新增 tests/test_storyboard_plan.py 5 项和 tests/test_storyboard_assets.py 5 项通过；.venv/bin/python -m pytest tests/test_storyboard_assets.py tests/test_storyboard_plan.py -q 通过 10 项；完整 .venv/bin/python -m pytest tests -q 通过 190 passed in 1.51s；python3 -m compileall scripts tests 通过。

2026-05-23 自动化升级记录

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/rough_cut.py 可读取 transcript.json，自动移除纯口头禅片段和相邻重复句，输出 rough_cut.json，其中包含每个删除决策、合并后的移除区间、保留区间、预计输出时长和节奏压缩比例；传入 --input/--output 时可直接复用现有 concat 渲染能力。

使用方式：先跑 python3 scripts/transcribe.py origin/voice.wav --language zh --word-timestamps --detect-fillers，再跑 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 渲染。

验证结果：新增 tests/test_rough_cut.py 5 项通过；python3 -m compileall scripts tests 通过；完整 .venv/bin/python -m pytest tests -q 通过 195 passed in 1.42s；docs/prompts/26-rough-cut.md 记录完整使用方式。

2026-05-24 自动化升级记录

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/export_edl.py 可读取 render_config.json、rough_cut.py 或 jump_cut.py 的 keep_segments，生成单轨 EDL 和 .json manifest；支持 --fps、--title、--source 和可选 --include-transcript-comments。

使用方式：从成片配置导出用 python3 scripts/export_edl.py --config work/render_config.json --output work/day58_edit.edl --fps 30；从粗剪 cut list 导出用 python3 scripts/export_edl.py --cut-list work/rough_cut.json --output work/rough_cut.edl。

验证结果：新增 tests/test_export_edl.py 7 项通过；完整 .venv/bin/python -m pytest tests -q 通过 202 passed in 3.18s；python3 -m compileall scripts tests 通过；git diff --check 通过；research archive validator 通过（4 个 repo、4 份 file tree）。

✅ Render QA — 渲染后质检回路

scripts/render_qa.py

借鉴 Remotion/视频生成类技能常见的“render → inspect → fix”闭环，以及 VideoDB 类项目的 playable evidence handoff，渲染完成后用 ffprobe/ffmpeg 自动检查并可生成复核包：

常用：

python3 scripts/render_qa.py output/day58_master.mp4 --platform douyin --json output/day58_qa.json
python3 scripts/render_qa.py output/day58_xhs.mp4 --platform xhs
python3 scripts/render_qa.py output/day58_master.mp4 \
  --platform douyin \
  --json output/day58_qa.json \
  --review-dir output/verify/day58_qa \
  --review-clips
python3 scripts/timeline_view.py output/day58_master.mp4 --at 42.5 --radius 1.5 --output output/verify/qa_42_5s.png

--review-dir 会写 render_qa_review.json 和 render_qa_review.md，把黑屏、静帧、静音的可疑区间按 FAIL/WARN 排序；--review-clips 会额外抽取短 MP4 证据片段。只需要审阅清单时不加 --review-clips。

📈 Retention Rhythm QA — 成片留存节奏风险审计

scripts/retention_rhythm_qa.py · 详细文档

render_qa.py 能发现信号和容器事故，但不会判断前三秒是否完全没有变化、镜头是否拖得过久、切点是否机械等距或字幕是否长时间不刷新。retention_rhythm_qa.py 对已渲染 master / platform export运行 FFmpeg scene detection，并可合并与成片速度、片头 offset 对齐的 subtitle_pack.v1 JSON，输出 retention_rhythm_qa.v1 JSON / Markdown。

常用：

python3 scripts/retention_rhythm_qa.py output/day58_master.mp4 \
  --timed-text output/subtitles/day58_master.json \
  --output verify/retention_rhythm_qa.json \
  --markdown verify/retention_rhythm_qa.md \
  --strict

默认检查前三秒 scene/subtitle attention event、6 秒以上视觉 hold、10 秒以上严重长镜头、scene + subtitle 的 combined attention gap、镜头时长 CV、0.35 秒以下快切 burst、4.5 秒以上字幕 hold 和 1.5 秒以上无字幕区间。inactive_hook 在没有 timed text 时只警告，避免把持续运镜/kinetic text 误判成硬失败；timed text 也无变化、视觉 hold 超过 10 秒或 combined attention gap 超过 10 秒时会进入 summary.blocking。这只是可观测的节奏风险，不预测真实留存率或“爆款概率”。报告存在且 blocking 非零时，pipeline_manifest.py 会阻塞；要强制具备报告可加 --require retention_rhythm_qa。

🗣️ Speech Continuity QA — 成片复读 / 口吃门禁

scripts/speech_continuity_qa.py · 详细文档

render_qa.py 和 waveform 能检查信号，却不能判断“上一句结尾是否又在下一句开头说了一遍”。speech_continuity_qa.py 读取已渲染 master 的二次 transcript，检测切点精确复读、相邻近重复 take 和句内即时口吃，输出 speech_continuity_qa.v1 JSON / Markdown；不同 speaker 默认不互判，减少访谈误报。

常用：

python3 scripts/extract_audio.py output/day58_master.mp4
python3 scripts/transcribe.py output/day58_master_audio.wav --model auto --language zh --word-timestamps
python3 scripts/speech_continuity_qa.py output/day58_master_transcript.json \
  --output verify/speech_continuity_qa.json \
  --markdown verify/speech_continuity_qa.md \
  --strict

命中项会写入精确成片时间范围、重复文本、segment evidence 和修复建议；--strict 返回 2。先试听 master 并用 timeline_view.py --at 看切点，再回到源 render_config / cut list 重渲染，避免在成片上二次拼补。只要报告存在且 summary.blocking > 0，pipeline_manifest.py 会阻塞；发布流程要强制具备此报告时加 --require speech_continuity_qa。

🎚️ Audio Master Report — 成片响度发布门禁

scripts/audio_master_report.py · 详细文档

借鉴 agent 视频工具对 audio-first correctness 和 render 后可审计报告的重视，但不做二次压缩：render_final.py 仍负责默认响度链路，audio_master_report.py 只读最终 master，用 FFmpeg ebur128 / silencedetect 输出 JSON + Markdown。

常用：

python3 scripts/audio_master_report.py output/day58_master.mp4 \
  --output output/day58_audio_master_report.json \
  --markdown output/day58_audio_master_report.md \
  --strict

默认检查 -16 LUFS ±2 LU、true peak ≤ -1 dBFS、LRA ≤ 18 LU、长静音总量 ≤ 3 秒。输出 audio_master_report.v1，如果 summary.blocking > 0，pipeline_manifest.py 会把它列为 blocking gate。若失败，优先回到 render_final.py 默认响度链路重新渲染，不要反复压缩已完成 master。

🧾 Source Receipts — 事实来源 proof deck

scripts/source_receipts.py · 详细文档

借鉴 proof-backed video skill 对 source deck 的要求，但保持本地优先：脚本只验证你提供的 claim、URL 和本地截图/证据文件，输出 source_receipts.v1、Markdown review 和可直接打开的 HTML source deck，不联网抓取、不截图、不上传。

常用：

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_claims.json 中每条 claim 可写 text、source_url、source_title、source_type、screenshot/source_file、risk 和 timecode。新闻、数据、金融、健康、法律等高风险 claim 必须有 URL；需要视觉 proof card 时加 --require-screenshot。pipeline_manifest.py --require source_receipts --strict 会把未解决的 summary.blocking 列为发布 blocker。

📦 多平台导出

scripts/multi_export.py · 详细文档

📦 Delivery Encode — source-bound 目标大小交付

scripts/delivery_encode.py · 详细文档

对“视频必须小于 20 MiB”这类硬上传限制，不再靠 CRF 反复试猜。plan 会读取源片时长、音视频流、旋转后尺寸和帧率，预留 6% 容器安全余量，再为 libx264 两遍编码分配视频码率。apply 先写同目录临时 MP4，硬大小、容器、codec、尺寸、fps、时长、音轨、像素格式和全长解码都通过后才原子提升。

python3 scripts/delivery_encode.py plan output/master.mp4 \
  --delivery output/master-under-20m.mp4 \
  --max-size-mib 20 \
  --output work/delivery_encode_plan.json \
  --markdown work/delivery_encode_plan.md

python3 scripts/delivery_encode.py apply work/delivery_encode_plan.json \
  --markdown work/delivery_encode_plan.md

python3 scripts/delivery_encode.py verify work/delivery_encode_plan.json --strict

可选 --max-width / --max-height 保持画幅比缩小，--fps 只允许不高于源片。交付编码是最后一次重编码，不能替代人工观感审片；交付 MP4 还应重跑 render_qa.py、字幕/平台安全区检查和 approval_receipt.py。

✍️ Caption Generator — 标题 + 正文 + 标签

scripts/generate_caption.py

无 LLM 依赖，纯规则：

• 标题 ≤18 字，前 18 字含 2 个 TF-IDF 关键词
• 正文 200-500 字，每 ~60 字一个 emoji（📌✨💡🔥👇✅🚀📈）
• 3-6 个 # tag，混合垂类 + 长尾（避免纯热词堆叠被判搬运）
• 发布时段建议来自所选 audience profile

🖼️ Cover Variants — 封面 A/B 方案与选择

scripts/cover_variants.py · 详细文档

借鉴同类视频 / creator skill 把 3 套缩略图、标题—封面信息分工和移动端小图检查做成一等流程的优点，但保持本项目本地优先：复用现有 generate_cover_image.py 的 Chrome 模板，不调用图片模型或外部 API。

常用：

python3 scripts/cover_variants.py \
  output/day68_master_xhs.mp4 \
  --title "20分钟出片" \
  --subtitle "AI剪辑完整流程" \
  --caption output/day68_caption.json \
  --platform xhs \
  --frame-timestamp 12.5 \
  --output-dir output/covers \
  --render \
  --output work/cover_variants.json \
  --markdown work/cover_variants.md

默认生成 cover-a 主方案、cover-b 对比色 / 层级方案和 cover-c 真实画面证据方案，并为每张图生成 feed-size *_preview.png。看完后用 --select cover-c --require-selection --strict 记录最终选择；publish_package.py 会优先读取 selected_cover，pipeline_manifest.py --require cover_variants 可把封面选择设为发布 gate。需要自定义 AI 底图时，生图优先使用 Codex 内置 image_gen 工具，即 OpenAI GPT Image 2（gpt-image-2）。

🔏 Approval Receipt — 最终审批收据

scripts/approval_receipt.py · 详细文档

人工完整审片并核对封面、文案、字幕和 QA 后，把稳定交付件显式列入 SHA-256 收据：

python3 scripts/approval_receipt.py create \
  --project-dir . \
  --artifact output/day77_xhs.mp4 \
  --artifact output/day77_douyin.mp4 \
  --artifact output/day77_wxch.mp4 \
  --artifact output/cover.png \
  --artifact output/day77_caption.json \
  --artifact verify/render_qa.json \
  --approved-by "Jay" \
  --note "三平台视频、封面、文案和字幕已人工复核。" \
  --output verify/approval_receipt.json \
  --markdown verify/approval_receipt.md

python3 scripts/approval_receipt.py verify \
  --project-dir . \
  --receipt verify/approval_receipt.json \
  --output verify/approval_receipt_verification.json \
  --strict

收据只保存项目相对路径、大小、修改时间和 SHA-256，不复制或锁定视频。任何文件后来被重渲染、替换、删除、改成 symlink 或在哈希期间变化，验证会输出 changed / missing / unsafe 并在 strict 模式返回 2。项目里存在收据时，pipeline_manifest.py 会实时重算最新一份并自动阻塞过期审批；--require approval_receipt 可强制必须有收据。publish_package.py --require-approval-receipt 即使拿到旧 pipeline manifest 也会独立验证当前文件。approved_by 只是本地自报标签，不是身份认证或数字签名；不要把会反复重写的 pipeline manifest、publish package 或 dashboard 放进收据。

📤 Publish Package — 最终上传包

scripts/publish_package.py · 详细文档

借鉴 vidpipe / OpenShorts / youtube-shorts-pipeline 这类项目的发布队列和多平台分发思路，但保持本项目本地优先：不登录平台、不调用上传 API，只把发布必需物料和 gate 状态整理成可审计的 JSON + Markdown。

常用：

python3 scripts/publish_package.py \
  --project-dir work/day58 \
  --platforms xhs douyin wxch \
  --require-approval-receipt \
  --output work/day58/publish_package.json \
  --markdown work/day58/publish_package.md \
  --strict

输出 publish_package.v1，包含每个平台的 MP4、封面图、SRT/VTT、标题、正文、tags、发布时间建议、上传 checklist、章节文本、pipeline_manifest 阻塞状态和 approval receipt 实时验证状态。若项目有 cover_variants.json 且 selected_cover 文件存在，会优先采用已复核封面；显式 --cover 仍可覆盖。--strict 会在缺少平台视频、caption 不完整、已有 gate blocked 或收据过期时返回 2；--require-approval-receipt 还会在没有收据时阻塞。pipeline_manifest.py 也会识别 publish_package.json 并把 summary.blocking > 0 列为 blocking gate。

🧭 Project Resume — 续跑上下文包

scripts/project_resume.py · 详细文档

借鉴 agent-native 视频工具的 project state / resume note 思路，但保持本项目本地 artifact-first：复用 pipeline_manifest.py 的 gate 判断，把状态、阶段、缺件、最近 artifacts 和下一步动作整理成可交给下一位 agent 的 JSON + Markdown。

常用：

python3 scripts/project_resume.py \
  --project-dir work/day58 \
  --target-stage publish_ready \
  --output work/day58/project_resume.json \
  --markdown work/day58/project_resume.md \
  --agent-note work/day58/CLAUDE.md \
  --strict

输出 project_resume.v1，包含 phase、recommended_first_action、next_actions[]、latest_artifacts[]、关键 gate snapshot 和一句 suggested_prompt。--agent-note 可写出项目级 CLAUDE.md；不传路径时默认写到 --project-dir/CLAUDE.md。脚本不渲染、不上传、不提交任何生成任务，适合自动化收尾、上下文压缩后续跑和跨 agent 交接。

🧾 Review Dashboard — 人工复核面板

scripts/review_dashboard.py · 详细文档

借鉴自动 vlog 剪辑和 agentic editor 里的浏览器预览 / reviewer loop，但保持本项目静态、可审计：不启动服务、不调用模型，只把本地 artifacts、blocking gates、warning 和下一步动作整理成 HTML + JSON。

常用：

python3 scripts/review_dashboard.py \
  --project-dir work/day58 \
  --target-stage publish_ready \
  --output work/day58/review_dashboard.json \
  --html work/day58/review_dashboard.html \
  --strict

输出 review_dashboard.v1，包含 review_state、review_items[]、next_actions[]、latest_artifacts[] 和完整 gate_snapshot[]。HTML 可直接在浏览器打开，适合最终发布前让用户看一眼，也适合自动化结束时把 blocker 留给下一位 agent。

👤 受众 Profile

scripts/profiles/

预设镜头节奏、字幕密度、BGM 增益、目标比例：

• tech_pro — AI/创业/效率向（90s 默认，每 2.5s 切镜，BGM -16dB，3:4 小红书首选）
• lifestyle — vlog/穿搭/家居向（60s 默认，每 2.0s 切镜，BGM -10dB）

字体预设（5 套）在 profiles/_fonts.yaml：得意黑 / 阿里妈妈数黑体 / 阿里妈妈方圆体 / 思源黑体 Heavy / 奶酪体。

---

日常工作流

完整命令链见 docs/prompts/15-xhs-daily-tech-video.md。

简化版（每天替换 和）：

DAY=NN
WORK=~/Movies/xiaohongshu/day$DAY
SKILL=~/projects/video-editing-skill

# 0b. 可选：手持素材防抖；只写 working copy，完整 A/B 确认前 manifest 会阻塞
python3 $SKILL/scripts/video_stabilization.py plan $WORK/origin/handheld.mp4 \
  --decision stabilize \
  --reviewed-by "editor" \
  --note "不想要的高频手抖，不是有意运镜" \
  --output $WORK/work/video_stabilization_plan.json \
  --markdown $WORK/work/video_stabilization_plan.md
python3 $SKILL/scripts/video_stabilization.py apply $WORK/work/video_stabilization_plan.json \
  --output $WORK/work/handheld-stabilized.mp4 \
  --comparison $WORK/verify/handheld-stabilization-compare.mp4 \
  --markdown $WORK/work/video_stabilization_plan.md
# 用 1× 看完整 comparison 后：
python3 $SKILL/scripts/video_stabilization.py confirm $WORK/work/video_stabilization_plan.json \
  --reviewed-by "editor" \
  --note "完整 A/B 已看；人物、边缘和有意摇摄均可接受" \
  --markdown $WORK/work/video_stabilization_plan.md

# 1. 转写
python3 $SKILL/scripts/transcribe.py $WORK/origin/voice.mp3 \
  --word-timestamps --detect-fillers

# 1a. 生成本地同步视频校稿页；保存 review.txt 后回写 reviewed transcript
python3 $SKILL/scripts/transcript_review.py html \
  --transcript $WORK/work/transcript.json \
  --video $WORK/origin/voice.mp3 \
  --output $WORK/work/transcript_review.html
python3 $SKILL/scripts/transcript_review.py apply \
  --transcript $WORK/work/transcript.json \
  --review $WORK/work/transcript_review.txt \
  --output $WORK/work/transcript_reviewed.json

# 1b. 可选：按 reviewed ASR 去纯口头禅/重复句，先审查 cut list 再渲染
python3 $SKILL/scripts/rough_cut.py \
  --transcript $WORK/work/transcript_reviewed.json \
  --cut-list $WORK/work/rough_cut.json

# 2. 重组（手动喂 prompt 给 LLM，落地 JSON 后回放）
python3 $SKILL/scripts/rewrite_script.py \
  --transcript $WORK/work/transcript_reviewed.json --emit-prompt > $WORK/work/prompt.md
# ...LLM 输出 work/llm.json 后...
python3 $SKILL/scripts/rewrite_script.py \
  --transcript $WORK/work/transcript_reviewed.json \
  --llm-output $WORK/work/llm.json \
  --output $WORK/work/clean_script.md

# 3. 自动丰富（plan 里会有 broll / stickers / chapter_cards / imagegen 四列）
python3 $SKILL/scripts/auto_enrich.py \
  --transcript $WORK/work/transcript.json \
  --clean-script $WORK/work/clean_script.md \
  --bgm $WORK/origin/bgm.mp3 \
  --output $WORK/work/enrich_plan.json

# 3b. 先生成分镜 shot cards，审查 B-roll / 生图 / 生成视频 / 动效路由
python3 $SKILL/scripts/storyboard_plan.py \
  --transcript $WORK/work/transcript.json \
  --clean-script $WORK/work/clean_script.md \
  --output $WORK/work/storyboard_plan.json \
  --markdown $WORK/work/storyboard_plan.md \
  --max-shots 8 \
  --target-aspect 9:16

# 3c. 可选：把分镜转成 Dreamina/Veo/LTX/Wan/Sora 视频生成提示词包
python3 $SKILL/scripts/video_prompt_pack.py \
  --storyboard-plan $WORK/work/storyboard_plan.json \
  --asset-root $WORK/work \
  --style-reference $WORK/work/imagegen/style-key.png \
  --output $WORK/work/video_prompt_pack.json \
  --markdown $WORK/work/video_prompt_pack.md \
  --strict
# style-key.png 可按 video_prompt_pack.md 的 Character / Style Reference prompt 用 Codex image_gen 生成。

# 3d. paid provider 提交前检查首帧和共享 style key
python3 $SKILL/scripts/reference_frame_preflight.py \
  --prompt-pack $WORK/work/video_prompt_pack.json \
  --output $WORK/work/reference_frame_preflight.json \
  --markdown $WORK/work/reference_frame_preflight.md \
  --require-style-reference \
  --strict

# 3e. 素材任务清单与预检：哪些已 ready，哪些要生图/审批/渲染/搜索
python3 $SKILL/scripts/storyboard_assets.py \
  --storyboard-plan $WORK/work/storyboard_plan.json \
  --asset-root $WORK/work \
  --output $WORK/work/storyboard_assets.json \
  --markdown $WORK/work/storyboard_assets.md

# 3f. 如果 imagegen[] 或 storyboard_assets 里的 needs_generation 非空，在 Codex 里直接调内置 imagegen 工具
#     生图优先使用 Codex 内置 `image_gen` 工具，即 OpenAI GPT Image 2（`gpt-image-2`）。
#     把每条 prompt_en 用 imagegen 生成 1024x1536，存到 $WORK/work/imagegen/
#     不需要 OPENAI_API_KEY；详见 docs/prompts/19-imagegen.md
#     如果 storyboard_assets 里有 needs_approval，提交 Dreamina/即梦前先确认，因为可能消耗 credits。

# 3f. 可选：软件教程/产品演示录屏，导入点击热点并生成自动聚焦计划
python3 $SKILL/scripts/screen_focus.py \
  --events $WORK/work/clicks.json \
  --screen-width 1920 \
  --screen-height 1080 \
  --output $WORK/work/screen_focus_plan.json \
  --markdown $WORK/work/screen_focus_plan.md

# 3g. 可选：录屏另有 facecam/camera，生成 PIP 小窗计划
python3 $SKILL/scripts/pip_overlay.py \
  --camera $WORK/origin/facecam.mp4 \
  --segment "0,42,bottom_right" \
  --sync-offset 0.18 \
  --output $WORK/work/pip_overlay_plan.json \
  --markdown $WORK/work/pip_overlay_plan.md

# 3h. 可选：生成调色计划，最终渲染时用 --color-grade 接入单次编码
python3 $SKILL/scripts/color_grade.py \
  --preset screen \
  --output $WORK/work/color_grade.json \
  --markdown $WORK/work/color_grade.md

# 3i. 可选：把已审 render_config 导出成无路径配方，供同栏目换素材复用
python3 $SKILL/scripts/edit_recipe.py export \
  --config $WORK/work/render_config.json \
  --name fast-tech-explainer \
  --description "快节奏科技口播" \
  --output $WORK/work/recipes/fast-tech-explainer_edit_recipe.json \
  --markdown $WORK/work/recipes/fast-tech-explainer_edit_recipe.md

# 4. 渲染前预检：先挡住缺文件、空剪辑、坏时间段和危险 overlay 参数
python3 $SKILL/scripts/edit_preflight.py \
  --config $WORK/work/render_config.json \
  --enrich-plan $WORK/work/enrich_plan.json \
  --output $WORK/work/edit_preflight.json \
  --markdown $WORK/work/edit_preflight.md \
  --strict

# 5. 渲染
#    如果生成了 screen_focus_plan.json，可额外追加：
#    --enrich-plan $WORK/work/screen_focus_plan.json
#    如果生成了 pip_overlay_plan.json，可额外追加：
#    --enrich-plan $WORK/work/pip_overlay_plan.json
#    如果生成了 color_grade.json，可额外追加：
#    --color-grade $WORK/work/color_grade.json
python3 $SKILL/scripts/render_final.py \
  --config $WORK/work/render_config.json \
  --enrich-plan $WORK/work/enrich_plan.json \
  --profile tech_pro \
  --primary-speed 1.25 \
  --subtitle-style karaoke \
  --output $WORK/output/day${DAY}_master.mp4

# 6. 主片质检
python3 $SKILL/scripts/render_qa.py \
  $WORK/output/day${DAY}_master.mp4 --platform douyin \
  --json $WORK/output/day${DAY}_master_qa.json \
  --review-dir $WORK/output/verify/day${DAY}_qa \
  --review-clips

# 6b. 主片镜头色彩 / 曝光 / broadcast-range 门禁
python3 $SKILL/scripts/shot_color_qa.py \
  $WORK/output/day${DAY}_master.mp4 \
  --output $WORK/output/verify/day${DAY}_shot_color_qa.json \
  --markdown $WORK/output/verify/day${DAY}_shot_color_qa.md \
  --strict

# 6c. 导出与 1.25x + 片头 offset 对齐的字幕 sidecar / timed-text JSON
python3 $SKILL/scripts/subtitle_pack.py \
  --config $WORK/work/render_config.json \
  --output-dir $WORK/output/subtitles \
  --basename day${DAY}_master \
  --speed 1.25 \
  --offset 2.0

# 6d. 最终字幕可读性门禁
python3 $SKILL/scripts/subtitle_readability_qa.py \
  $WORK/output/subtitles/day${DAY}_master.json \
  --media $WORK/output/day${DAY}_master.mp4 \
  --output $WORK/output/verify/day${DAY}_subtitle_readability_qa.json \
  --markdown $WORK/output/verify/day${DAY}_subtitle_readability_qa.md \
  --strict

# 6e. 主片留存节奏风险门禁
python3 $SKILL/scripts/retention_rhythm_qa.py \
  $WORK/output/day${DAY}_master.mp4 \
  --timed-text $WORK/output/subtitles/day${DAY}_master.json \
  --output $WORK/output/verify/day${DAY}_retention_rhythm_qa.json \
  --markdown $WORK/output/verify/day${DAY}_retention_rhythm_qa.md \
  --strict

# 6f. 主片响度/爆峰/长静音门禁
python3 $SKILL/scripts/audio_master_report.py \
  $WORK/output/day${DAY}_master.mp4 \
  --output $WORK/output/day${DAY}_audio_master_report.json \
  --markdown $WORK/output/day${DAY}_audio_master_report.md \
  --strict

# 6g. 如果 QA 有 WARN/FAIL，先看 review packet；想抽查关键切点再生成可视化复盘图
python3 $SKILL/scripts/timeline_view.py \
  $WORK/output/day${DAY}_master.mp4 --at 42.5 --radius 1.5 \
  --output $WORK/output/verify/day${DAY}_42_5s.png

# 6h. 有 rough/jump cut 时，可选生成原片连续时钟 vs 最终像素的可播放对照
python3 $SKILL/scripts/edit_compare.py \
  $WORK/origin/talking.mp4 \
  $WORK/output/day${DAY}_master.mp4 \
  --cut-list $WORK/work/rough_cut.json \
  --output-speed 1.25 \
  --output-offset 2.0 \
  --output $WORK/output/verify/day${DAY}_source_vs_final.mp4 \
  --report $WORK/output/verify/day${DAY}_edit_compare.json \
  --markdown $WORK/output/verify/day${DAY}_edit_compare.md

# 7. 多平台
python3 $SKILL/scripts/multi_export.py \
  $WORK/output/day${DAY}_master.mp4 --output-dir $WORK/output/

# 7b. 可选：交给专业剪辑软件继续精修/调色/混音
python3 $SKILL/scripts/export_edl.py \
  --config $WORK/work/render_config.json \
  --output $WORK/work/day${DAY}_edit.edl \
  --fps 30
python3 $SKILL/scripts/export_fcpxml.py \
  --config $WORK/work/render_config.json \
  --output $WORK/work/day${DAY}_edit.fcpxml \
  --fps 30 \
  --width 1080 \
  --height 1920
python3 $SKILL/scripts/export_otio.py \
  --config $WORK/work/render_config.json \
  --output $WORK/work/day${DAY}_edit.otio \
  --fps 30

# 8. 平台导出质检
python3 $SKILL/scripts/render_qa.py \
  $WORK/output/day${DAY}_xhs.mp4 --platform xhs
python3 $SKILL/scripts/render_qa.py \
  $WORK/output/day${DAY}_douyin.mp4 --platform douyin
python3 $SKILL/scripts/render_qa.py \
  $WORK/output/day${DAY}_wxch.mp4 --platform wxch

# 9. 文案
python3 $SKILL/scripts/generate_caption.py \
  --script $WORK/work/clean_script.md --profile tech_pro \
  --output $WORK/output/day${DAY}_caption.json

# 9b. 生成 3 套封面并在小图里选最终发布版
python3 $SKILL/scripts/cover_variants.py \
  $WORK/output/day${DAY}_xhs.mp4 \
  --title "" \
  --caption $WORK/output/day${DAY}_caption.json \
  --platform xhs \
  --output-dir $WORK/output/covers \
  --render \
  --select cover-c \
  --require-selection \
  --output $WORK/work/cover_variants.json \
  --markdown $WORK/work/cover_variants.md \
  --strict

# 10. 发布前 gate 汇总 + 最终上传包
python3 $SKILL/scripts/pipeline_manifest.py \
  --project-dir $WORK \
  --target-stage publish_ready \
  --require shot_color_qa \
  --output $WORK/work/pipeline_manifest.json \
  --markdown $WORK/work/pipeline_manifest.md \
  --strict

python3 $SKILL/scripts/publish_package.py \
  --project-dir $WORK \
  --platforms xhs douyin wxch \
  --output $WORK/work/publish_package.json \
  --markdown $WORK/work/publish_package.md \
  --strict

# 10b. 可选：自动化收尾或跨会话接手前生成续跑上下文包
python3 $SKILL/scripts/project_resume.py \
  --project-dir $WORK \
  --target-stage publish_ready \
  --output $WORK/work/project_resume.json \
  --markdown $WORK/work/project_resume.md \
  --agent-note $WORK/CLAUDE.md \
  --strict

# 10c. 可选：发布确认前打开静态复核面板
python3 $SKILL/scripts/review_dashboard.py \
  --project-dir $WORK \
  --target-stage publish_ready \
  --output $WORK/work/review_dashboard.json \
  --html $WORK/work/review_dashboard.html \
  --strict

---

测试

pytest tests/           # 完整本地测试套件，约 14 秒

按模块跑：

pytest tests/test_content_guard.py -v       # 80+ 规则的 38 个测试
pytest tests/test_rewrite_script.py -v      # Story Engine
pytest tests/test_auto_broll.py -v          # B-roll 调度
pytest tests/test_multi_export.py -v        # 多平台比例转换
pytest tests/test_hdr_sdr.py -v             # PQ/HLG → Rec.709 SDR / color tags / 完整解码门禁
pytest tests/test_delivery_encode.py -v     # 硬大小上限 / 两遍编码 / 完整解码门禁
pytest tests/test_render_qa.py -v           # 渲染后质检
pytest tests/test_shot_color_qa.py -v       # 成片镜头色彩 / 曝光 / broadcast-range 门禁
pytest tests/test_retention_rhythm_qa.py -v # 成片 hook / 长镜头 / 节奏风险门禁
pytest tests/test_subtitle_readability_qa.py -v # 最终字幕 CPS / 时长 / 重叠 / 越界门禁
pytest tests/test_platform_safe_area_qa.py -v # 字幕 / PIP / CTA / marker 平台安全区门禁
pytest tests/test_audio_master_report.py -v # 成片响度 / true peak / LRA 门禁
pytest tests/test_render_enrich_plan.py -v  # enrich_plan 自动接入渲染
pytest tests/test_auto_emphasis.py -v      # 问句/数字/转折/结论 emphasis cues
pytest tests/test_beat_sync.py -v          # BGM → beat edit slots / fallback review / cut snap
pytest tests/test_takes_pack.py -v          # 多 take phrase-level 阅读视图
pytest tests/test_project_bootstrap.py -v   # 项目启动与 source inventory
pytest tests/test_transcript_review.py -v  # 文本/HTML 同步视频 transcript 校稿回路
pytest tests/test_semantic_transcript_review.py -v # 全篇上下文审校 / 最小补丁 / choices gate
pytest tests/test_edit_brief_plan.py -v     # 自然语言剪辑需求 → 本地 runbook
pytest tests/test_hook_variants.py -v       # 前三秒 hook 批量角度 + 风险检查
pytest tests/test_rough_cut.py -v           # ASR 粗剪：口头禅/重复句 cut list
pytest tests/test_timeline_view.py -v       # 源素材/成片切点可视化复盘图
pytest tests/test_edit_compare.py -v        # 原片/成片 source-time 双栏对照 + 像素映射验证
pytest tests/test_generate_caption.py -v    # 文案合成
pytest tests/test_cover_variants.py -v      # 多套封面 + 小图预览 + 发布选择
pytest tests/test_imagegen_hint.py -v       # gpt-image-2 提示词检测
pytest tests/test_storyboard_plan.py -v     # 分镜 shot cards + 生成路由
pytest tests/test_video_prompt_pack.py -v   # 视频生成提示词包 + 审批 gate
pytest tests/test_reference_frame_preflight.py -v # 首帧/style key 尺寸/方向/透明背景 gate
pytest tests/test_generation_task_log.py -v # 异步生成任务台账 + 下载 gate
pytest tests/test_video_understanding.py -v # 抽样帧 + 可选 YOLO 检测 artifact
pytest tests/test_scene_boundaries.py -v # fixed/adaptive 场景检测 + cut evidence
pytest tests/test_visual_dedupe.py -v # 跨来源重复场景检测 + 保留建议
pytest tests/test_storyboard_assets.py -v   # 分镜素材 readiness manifest
pytest tests/test_export_edl.py -v          # NLE handoff EDL + manifest
pytest tests/test_export_fcpxml.py -v       # NLE handoff FCPXML + manifest
pytest tests/test_export_otio.py -v         # NLE handoff OTIO + manifest
pytest tests/test_screen_focus.py -v        # 录屏点击聚焦计划 + render 接入
pytest tests/test_subtitle_pack.py -v       # SRT/VTT/ASS/JSON 字幕交付包
pytest tests/test_srt_edit_plan.py -v       # SRT 编辑指令转 render_config/cut list
pytest tests/test_script_alignment.py -v    # 目标稿 → 多 take 原话匹配 / choices / render_config
pytest tests/test_audio_cue_sheet.py -v     # BGM/SFX 音频设计清单
pytest tests/test_multicam_sync.py -v       # 多机位 offset / 最响音轨 / pairwise / 真实预览
pytest tests/test_speech_denoise.py -v      # 口播降噪 preset / 顺序 / 真实 FFmpeg SNR smoke
pytest tests/test_bgm_ducking.py -v         # 旁白驱动 BGM sidechain + 真实 FFmpeg smoke
pytest tests/test_audio_transition.py -v    # J-cut/L-cut source handle / hash / 单次编码 / receipt
pytest tests/test_color_grade.py -v         # 调色计划 + render_final 接入
pytest tests/test_edit_preflight.py -v      # 渲染前结构/路径/参数预检 gate
pytest tests/test_edit_revision.py -v       # 文本剪辑 artifact source-bound revision / undo / redo
pytest tests/test_edit_recipe.py -v         # 可移植 render-config recipe / typed binding / replay preflight
pytest tests/test_video_stabilization.py -v # source-bound 后端计划 / 工作副本 / 全长 A/B / confirm gate
pytest tests/test_approval_receipt.py -v    # 最终交付件 SHA-256 审批收据 + stale gate
pytest tests/test_publish_package.py -v     # 最终上传包 + gate 状态汇总
pytest tests/test_project_resume.py -v      # 续跑上下文包 + agent handoff
pytest tests/test_review_dashboard.py -v    # 静态人工复核面板 + gate queue
pytest tests/test_source_receipts.py -v     # 事实来源 proof deck + 发布 gate

2026-08-12 自动化升级记录（Source-bound HDR → Rec.709 SDR Delivery）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/hdr_sdr.py、tests/test_hdr_sdr.py 和 docs/prompts/87-hdr-sdr.md。plan 绑定源绝对路径、SHA-256、大小、时长、显示尺寸、fps、codec、音轨、pixel format/bit depth、四项 color metadata 与 HDR side data；只接受 smpte2084 PQ 或 arib-std-b67 HLG，并要求 BT.2020 primaries/matrix，普通 SDR、未知或矛盾 tags 直接拒绝。apply 要求 FFmpeg 同时存在 zscale 和 tonemap，固定走 explicit input transfer → linear float → BT.709 primaries → Hable → BT.709 transfer/matrix/limited-range → yuv420p，输出 H.264/AAC MP4；临时文件必须通过 BT.709 四 tags、容器/codec/pixel format、尺寸/fps/时长/音轨和 -xerror 全长解码才原子提升。verify 现场重算源/输出 hash、media/color contract、canonical settings、plan id 和 decode receipt。pipeline_manifest.py 新增存在即 live verify、可 --require hdr_sdr_plan 的 gate；edit_brief_plan.py 新增 iPhone HDR/HLG/PQ/HDR 转 SDR/Rec.709/过曝意图路由，并在同时需要硬大小压缩时先产 SDR、再把 delivery_encode.py 接到 SDR 文件。README、SKILL、daily workflow 和提示词索引已同步。

使用方式：运行 python3 scripts/hdr_sdr.py plan output/master_hdr.mp4 --delivery output/master_sdr.mp4 --output work/hdr_sdr_plan.json --markdown work/hdr_sdr_plan.md；确认 metadata/profile/filter 后执行 python3 scripts/hdr_sdr.py apply work/hdr_sdr_plan.json，最后运行 python3 scripts/hdr_sdr.py verify work/hdr_sdr_plan.json 和 pipeline_manifest.py --require hdr_sdr_plan --strict。Dolby Vision/HDR10+ 动态 metadata 不会保留；技术通过后仍须在可信 SDR 显示器完整检查肤色、高光、阴影、渐变和饱和色，并对 SDR 文件重跑 render QA、shot color QA 和审批收据。

验证结果：HDR/manifest/brief 专项回归 101 passed in 1.11s，全量回归 837 passed in 18.77s；compileall、四组 HDR CLI help、manifest 分类枚举、git diff --check 和 Skill quick_validate 均通过。另以真实 10-bit BT.2020 HLG/HEVC 样片跑了 fail-closed smoke：计划正确识别 arib-std-b67 HLG，同时明确报告缺 zscale 和尚未 apply 两项 blocker；apply 返回 1，且没有写出 SDR 交付文件。本机 /opt/homebrew/bin/ffmpeg 8.1.1 有 tonemap 但没有 zscale，因此没有虚报真实 tone-map 成功，也没有安装额外 FFmpeg 或使用退化滤镜；完整编码、输出契约、全长解码、原子提升和 live verify 生命周期由 deterministic mocked FFprobe/FFmpeg 测试覆盖。实际使用前须安装带 zscale（libzimg）和 tonemap 的 FFmpeg，再以真实 PQ/HLG 项目完成视觉验收。

2026-08-11 自动化升级记录（Source-bound J-cut / L-cut Audio Transitions）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/audio_transition.py、tests/test_audio_transition.py 和 docs/prompts/86-audio-transition.md。plan 从已有 render_config / transcript 编译画面硬切与独立主音频 layers，J-cut 读取 incoming clip 入点之前的真实 handle，L-cut 延续 outgoing clip 出点之后的真实 handle并让 incoming audio 从 overlap 后恢复同步；handle 不足、时长越界、重复边界或短 clip 会 fail closed。config、transcript、源视频/B-roll 的 SHA-256、大小、媒体契约、clip timing、fade、source/output coverage 与 canonical plan id 全部入账；verify 从 live inputs 重建，即使重写 plan id 也不能隐藏 compiled layer 漂移。计划、Markdown、成片与 receipt 默认拒绝覆盖已有目标。apply 通过新增的 render_final.py --audio-transition-plan 把画面、错位主音频、字幕、overlay、BGM 和响度链留在一次 FFmpeg 编码中，临时文件成功 probe 后才原子提升并写 receipt。pipeline_manifest.py 新增存在即 live verify、可 --require audio_transition_plan 的 gate；edit_brief_plan.py 新增 J-cut/L-cut/声音先行/声音延续路由。README、SKILL、daily workflow 和提示词索引已同步。

使用方式：先逐边界试听素材，再运行 python3 scripts/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；用 audio_transition.py apply ... --output output/master.mp4 --receipt work/audio_transition_apply.json 安全渲染，或把 --audio-transition-plan work/audio_transition_plan.json 加到现有 render_final.py 命令；最后执行 audio_transition.py verify ... --receipt ... --strict。L-cut 会跳过 incoming clip 等长的开头音频以恢复同步，只能在该 handle 是 ambience/room tone/呼吸或明确要舍弃内容时使用。机器验证不能判断交叠对白是否合适；每个改变边界必须以 1× 在耳机和手机扬声器上试听。

验证结果：新增 13 项 audio-transition 计划/安全/篡改/lifecycle/真实渲染测试，并扩展 pipeline-manifest、edit-brief 与 render integration 回归；定向 .venv/bin/python -m pytest tests/test_audio_transition.py tests/test_pipeline_manifest.py tests/test_edit_brief_plan.py tests/test_render_guard_integration.py -q 通过 104 passed in 4.80s，最终全量 .venv/bin/python -m pytest tests -q 通过 825 passed in 17.11s。真实 FFmpeg smoke 分别执行 J-cut 与 L-cut plan → apply → receipt verify，两者都输出 2.4 秒、160×90、24fps 的 H.264/AAC 文件，保留音轨，临时输出清理且所有产物默认拒绝覆盖；CLI round-trip 另跑一遍 J-cut。.venv/bin/python -m compileall -q scripts tests、CLI help、manifest category、中文 brief route、Skill quick_validate.py 和 git diff --check 也均通过。

2026-08-10 自动化升级记录（Target-size Delivery Encode）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/delivery_encode.py、tests/test_delivery_encode.py 和 docs/prompts/85-delivery-encode.md。plan 绑定源路径、SHA-256、大小、时长、尺寸、fps、codec 和音轨，从硬 --max-size-mib 扣出 AAC 音频与 6% 安全余量，生成 canonical plan id 与 libx264 两遍命令。不可行的低码率直接拒绝；可选缩小分辨率/帧率，但不允许放大或插帧。apply 检查剩余磁盘，拒绝 symlink、路径冲突和默认覆盖；临时 MP4 必须通过硬大小、H.264/AAC、yuv420p、尺寸/fps/时长/音轨契约和 FFmpeg -xerror 全长解码，才会原子替换到交付路径。verify 重算源片/输出 hash 、canonical settings 和 derived status，即使手改 plan id 也不能隐藏漂移。pipeline_manifest.py 新增“存在即 live verify”的 delivery_encode_plan gate；edit_brief_plan.py 可从“压缩到 18MB 以内/满足上传限制”自动路由。README、SKILL、daily workflow 和提示词索引已同步。

使用方式：先运行 python3 scripts/delivery_encode.py plan output/master.mp4 --delivery output/master-under-20m.mp4 --max-size-mib 20 --output work/delivery_encode_plan.json --markdown work/delivery_encode_plan.md，检查计划中的码率、缩放和 warnings；再运行 python3 scripts/delivery_encode.py apply work/delivery_encode_plan.json --markdown work/delivery_encode_plan.md，最后执行 python3 scripts/delivery_encode.py verify work/delivery_encode_plan.json --strict。如交付路径已存在，只有显式 --force 才允许在新文件已完整验证后原子替换。交付件必须重跑 QA 并人工完整审片，原版审批收据不可复用。

验证结果：新增 11 项 delivery-encode 单元/安全/lifecycle 测试，并扩展 pipeline-manifest / edit-brief 回归；定向 .venv/bin/python -m pytest tests/test_delivery_encode.py tests/test_edit_brief_plan.py tests/test_pipeline_manifest.py -q 通过 97 passed in 1.01s，全量 .venv/bin/python -m pytest tests -q 通过 809 passed in 14.78s。严格真实 FFmpeg smoke 用 5 秒 640×360、30fps、H.264/AAC 高码率样片完成 plan → apply → verify --strict：源片 3,024,189 bytes，交付件 803,194 bytes，低于 838,860 bytes 硬上限，最终 blocking=0 / warnings=0，H.264/AAC、yuv420p、640×360、30fps、5.013s 契约和全长解码全部通过。.venv/bin/python -m compileall -q scripts tests、四个 CLI help、manifest category、中文 brief route、Skill quick_validate.py 和 git diff --check 也均通过。

2026-08-01 自动化升级记录（Long-form Multicam Clock Drift）

本次联网研究的 GitHub 参考：

新增/调整能力：scripts/multicam_sync.py 新增 --measure-clock-drift，在每个机位自己的可用重叠时长中默认均匀抽取 5 个 20 秒窗口，并在每个窗口的预测位置附近搜索 ±2 秒。置信度合格的 probe 会进入 exhaustive pairwise consensus，至少 4 个 inlier 且早晚跨度充足才做最小二乘复核，拟合 offset(reference_time)=intercept+slope*reference_time。报告以 selected_audio_drift.v1 明确限定所选音轨，保存 offset_slope_ppm / source_rate_error_ppm、测量和斜率分辨率、累计漂移、拟合残差、参考时间中点锚点、source-zero 映射和未应用的 advisory factors。累计漂移超过默认 80 ms 时写 correction_required，inlier 太少、残差超过独立 80 ms/两帧下限、搜索峰贴边或速率超出 ±5000 ppm 可信范围时写 unreliable；两者都会进入现有 strict/manifest review gate。默认不启用，旧固定 offset 结果不变。scripts/audio_sync.py 仅增加可选 start_seconds，旧调用保持兼容。脚本始终不修改原片，也不自动证明视频 PTS/其他音轨共享该时钟。

使用方式：运行 python3 scripts/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 --strict。先检查 Markdown 的 accepted/rejected probes、ppm、累计漂移和最大残差；只有 stable 才表示在本次阈值内未检出需要校正的线性漂移。correction_required 的 atempo/setpts 只是消费建议，必须在 NLE/FFmpeg 下游对同一路音频和视频应用同一时钟映射并再次验证头/中/尾。周期音乐、静音、混响或中途重启导致 unreliable 时，不要放宽 gate 取巧；应换清晰音轨、扩大局部搜索、使用可靠 LTC/timecode，或改用分段同步。

验证结果：新增/扩展 tests/test_multicam_sync.py 与 tests/test_audio_sync.py，覆盖 seek 参数、非法起点、已知正负 slope、高置信度 outlier 共识剔除、残差拒绝、窗口边界、advisory factor 符号和 strict review；定向 .venv/bin/python -m pytest tests/test_audio_sync.py tests/test_multicam_sync.py -q 通过 26 passed in 2.39s，最终全量测试通过 672 passed in 11.73s。真实 FFmpeg smoke 生成 60 秒确定性 PCM，分别用 atempo=0.996 / 1.004 制造反向时钟偏差；7 个 6 秒 probe 均得到 correction_required、applied=false，ppm 符号分别为负/正，--strict 均正确退出 2。compileall、CLI --help、skill quick_validate.py 和 git diff --check 全部通过。

2026-08-04 自动化升级记录（Semantic Transcript Review）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/semantic_transcript_review.py、tests/test_semantic_transcript_review.py 和 docs/prompts/79-semantic-transcript-review.md。prepare 把每个 segment 与前后 1–4 段上下文、规范化 segment SHA-256、硬规则和 response template 写成 JSON/Markdown；脚本不调用模型、不上传内容。audit 从原 transcript 自己推导完整 coverage，拒绝旧 source hash、未知/重复 segment、字符 span 不匹配、未裁掉相同前后缀的非最小 patch、数字/标点变化、空理由、越界/超长/重叠/重复提案和跨 segment 边界重复字，并生成稳定 patch-* / review-* id。合法 proposal 仍以 pending_choices 阻塞；apply 要求另一份 choices 绑定相同 canonical source hash 与 review id，逐条 approve|reject，成功后写 semantic_review metadata、重分配改动 segment 的词时间，并把 audit 更新为 ready。pipeline_manifest.py 新增存在即检查的 semantic_transcript_review gate；edit_brief_plan.py 可从“语义校稿/上下文校稿/专业术语错词”等 brief 自动路由到 prepare。README、SKILL、daily workflow、Transcript Review 文档和提示词索引已同步。

使用方式：运行 python3 scripts/semantic_transcript_review.py prepare --transcript work/transcript.json --output work/semantic_review_request.json --markdown work/semantic_review_request.md，让当前 Agent/模型按 request schema 生成 work/semantic_review_response.json；再运行 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。首次 strict 在有合法建议时退出 2 是预期人工 gate；从 Markdown 复制 choices template，逐项确认后运行 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 --markdown work/transcript_semantic_review.md，最后仍用同步媒体 HTML 听审。

验证结果：新增 12 项 semantic-review 测试，并扩展 pipeline-manifest / edit-brief 回归；定向 .venv/bin/python -m pytest tests/test_semantic_transcript_review.py tests/test_transcript_review.py tests/test_pipeline_manifest.py tests/test_edit_brief_plan.py -q 通过 98 passed in 0.98s，全量 .venv/bin/python -m pytest tests -q 通过 715 passed in 11.90s。覆盖上下文 packet、canonical source hash、完整/部分 coverage、最小补丁、数字/标点、精确 span、重叠提案、稳定 review id、旧 choices、approve/reject、词时间重分配、CLI 三阶段和 manifest/edit-brief gate；.venv/bin/python -m compileall -q scripts tests、四个 CLI help、manifest category、skill quick_validate.py 和 git diff --check 全部通过。

2026-08-02 自动化升级记录（Hash-bound Approval Receipt）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/approval_receipt.py 和 docs/prompts/77-approval-receipt.md。create 只接受项目内普通文件和显式重复 --artifact，保存项目相对路径、大小、修改时间与 SHA-256；拒绝重复路径、项目外路径、symlink、收据自身和会循环重写的 manifest/package/dashboard。verify 重新读取当前文件并输出 current / changed / missing / unsafe / invalid，--strict 在任何过期项上返回 2。pipeline_manifest.py 可用 --require approval_receipt 强制收据；只要发现收据，即使未显式 require 也会现场重算并阻塞 stale。publish_package.py --require-approval-receipt 还会确认当前选择的平台 MP4、封面、caption、字幕和章节都在收据覆盖范围内，并忽略旧 publish package 的循环 gate。approved_by 明确只是本地自报标签，不是身份认证、数字签名或发布授权。

使用方式：完整审片后运行 python3 scripts/approval_receipt.py create --project-dir . --artifact output/day77_xhs.mp4 --artifact output/day77_douyin.mp4 --artifact output/cover.png --artifact output/day77_caption.json --artifact verify/render_qa.json --approved-by "Jay" --output verify/approval_receipt.json --markdown verify/approval_receipt.md；上传前运行 python3 scripts/approval_receipt.py verify --project-dir . --receipt verify/approval_receipt.json --output verify/approval_receipt_verification.json --strict，再运行 python3 scripts/publish_package.py --project-dir . --platforms xhs douyin wxch --require-approval-receipt --strict。重新渲染、换封面或改文案/字幕后必须重新审查并用 create --replace 生成新收据，不能手改旧 hash。

验证结果：定向 .venv/bin/python -m pytest tests/test_approval_receipt.py tests/test_pipeline_manifest.py tests/test_publish_package.py -q 通过 82 passed in 1.20s；重放到最新主分支后，最终 .venv/bin/python -m pytest tests -q 通过 690 passed in 12.25s。CLI create/strict verify/stale exit-code、路径穿越、symlink、重复/self/volatile artifact、缺失/变更、旧 manifest、收据覆盖范围和 publish-package 循环 gate 均有回归测试；.venv/bin/python -m compileall -q scripts tests、三个 CLI help/category smoke 和 git diff --check 全部通过。

2026-08-03 自动化升级记录（Target Script Alignment）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/script_alignment.py 和 docs/prompts/78-script-alignment.md。脚本接受重复 --transcript label=path、--transcripts-dir 和可选 --media label=path，把 Markdown/文本目标稿按行或句拆分，对每个 unit 在多来源 word/segment 时间轴上搜索候选，并记录 sequence、target/source coverage、字符 n-gram overlap、length fit 与 exact evidence。默认禁止复用同一源时间段；低分、次优分差过小、无候选、素材未登记/缺失和显式 choice 冲突都写入 summary.blocking。第一次 review 后可用稳定 candidate id 写 --choices；人工 choice 只解决词面低分/多解，不绕过物理素材和时间重叠。脚本按目标稿顺序输出 render_config.json，并可另存 clean_script.md 供内容风控、分镜和发布文案使用。edit_brief_plan.py 新增“目标脚本/按稿剪”路由；pipeline_manifest.py 新增存在即阻塞未清 review 的 script_alignment gate。

使用方式：先运行 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。如果返回 2，打开 Markdown 比较原话和时间码，把确认候选写入 work/script_alignment_choices.json，再加 --choices 重跑；只有 summary.blocking=0 后才进入 edit_preflight.py 和最终渲染。

验证结果：新增 tests/test_script_alignment.py 7 项，并扩展 edit-brief / pipeline-manifest 回归；定向 .venv/bin/python -m pytest tests/test_script_alignment.py tests/test_pipeline_manifest.py tests/test_edit_brief_plan.py -q 通过 76 passed in 0.78s，最终 .venv/bin/python -m pytest tests -q 通过 700 passed in 11.02s。覆盖 Markdown 标题/逐句拆分、GPT-5.6 小数点保护、透明分数、目标顺序重排、多 take 同分阻塞、choices 复核、源时间防复用、缺素材 gate、CLI strict 两阶段和 clean-script/render-config 输出；.venv/bin/python -m compileall -q scripts tests、CLI --help、manifest category、skill quick_validate.py 和 git diff --check 全部通过。

2026-08-05 自动化升级记录（Source-bound Edit Revisions）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 scripts/edit_revision.py、tests/test_edit_revision.py 和 docs/prompts/80-edit-revision.md。prepare 只接受项目根或 work/ 中已经存在的 UTF-8 JSON/Markdown/text/subtitle artifact，记录完整内容、基础 SHA-256 和可选 dependency SHA-256；拒绝源素材、代码、输出/验证目录、symlink、隐藏/volatile/self artifact 和超大文件。audit 检查 title/reason、真实变化、JSON 可解析性、重复路径、基础/依赖漂移并生成稳定 review_id；合法 proposal 仍以 pending_approval 阻塞。apply 要求另一份 approval JSON 绑定同一 review id，live 重审后把多个文件作为一个 operation 成组写入，并把 before/after bytes 存进 work/.edit-revisions/blobs/。status、undo、redo 会验证 journal、当前 artifact、已应用 dependency 和 blob；redo 分支默认保留，新路线必须显式 --fork-history，旧操作存入 archived_branches[]。pipeline_manifest.py 新增存在即实时验证的 edit_revision_history gate，edit_brief_plan.py 新增“修订历史/撤销剪辑/重做剪辑”路由；README、SKILL、daily workflow 和提示词索引同步。

使用方式：运行 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 "收紧开头" --reason "时间码审片后采用第二版" --output work/edit_revision_proposal.json，只改 proposal 的 artifacts[].proposed_content；再运行 audit --proposal work/edit_revision_proposal.json --output work/edit_revision_audit.json --markdown work/edit_revision_audit.md --strict。合法 audit 因等待人工审批返回 2 是预期；从 Markdown 复制 approval template，填写 decision: approve 和 reviewer label 后运行 apply --proposal ... --audit ... --approval ... --strict。日常用 status --strict，需要时运行 undo / redo；依赖或文件被手工改过时先处理 stale，不得绕过 hash gate。最终待上传字节仍用 approval_receipt.py，不要用 edit revision 代替成片审批。

验证结果：新增 21 项 edit-revision 测试，并扩展 pipeline-manifest / edit-brief 回归；定向 .venv/bin/python -m pytest tests/test_edit_revision.py tests/test_pipeline_manifest.py tests/test_edit_brief_plan.py -q 通过 95 passed in 1.06s，全量 .venv/bin/python -m pytest tests -q 通过 738 passed in 11.84s。覆盖 prepare/audit hash、依赖漂移、非法 JSON、路径与 symlink 限制、独立审批、多文件单 operation、写入前二次校验、运行期写入失败回滚路径、exact-byte undo/redo、外部修改、旧 artifact 漂移、redo dependency、显式 history fork、blob/journal 损坏、CLI round-trip 和 manifest live gate；compileall、CLI help、manifest category、skill quick_validate.py 和 git diff --check 全部通过。

2026-08-06 自动化升级记录（Shot Color QA）

本次联网研究的 GitHub 参考：

新增/调整能力：新增 [`scripts/shot