@oh-story/dsh 0.1.4 → 0.1.5

package/lib/video-recap/skills/video-recap/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: video-recap
+description: >
+ 从输入视频端到端生成中文解说成片。用户提供 .mp4 / .mov / .mkv / .webm，并要求添加旁白、
+ 配音、总结、短剧/电视剧/电影/纪录片/科普解说时使用。负责编排 video-* 技能链：视频理解 →
+ Agent 制定故事与视听方案 → 剪辑 → 配音 → 合成。触发词：视频解说、视频旁白、生成解说、
+ 视频 recap、video recap、voiceover、narration、auto-dub、recap。
+---
+
+## 1. 定位与流程
+
+本技能是五个独立技能的轻量编排器。各技能只通过 `work_dir` 中的 JSON / MP4 产物通信，不共享代码：
+
+```text
+video-understanding ─▶ Agent 按 video-script 制定方案并写稿 ─▶ [video-cut] ─▶ video-voiceover ─▶ video-assemble
+```
+
+流程支持断点续跑：写好 `narration.json` 后重复同一条命令即可继续。第二阶段会校验
+`recap_run_manifest.json`，拒绝复用来自其他源视频或其他运行参数的旧工作目录；视频理解产物也只在来源一致时复用。
+
+## 2. 创作职责
+
+这不是单纯的 JSON / 渲染流水线。Agent 是本次内容的创作负责人。先判断本轮的**创作控制模式**；它与 `--edit-mode full|cut|dub` 是两个维度：
+
+- **CREATE**：从素材创作新成片。比较真正可行的故事/剪辑假设，再选择主线。
+- **DIRECTED**：用户已经指定结构、镜头、台词或包装方向。把这些决定当作基线落实，不为满足模板而另起方案。
+- **REVISION**：用户针对已有版本看片修改。最新反馈覆盖旧决定；本轮未点名的故事、镜头、声音和包装默认冻结，不重新发散创作。
+
+REVISION 开始前先明确“本轮修改项”和“冻结项”。表达、节奏、字幕反馈写回 `style_card.json`，镜头、入出点和声音分工写回 `visual_audio_board.json`；只有观众承诺、POV、主线或故事 beat 改变时才更新 `recap_story_plan.json`。删除成片内容时同步删除计划中的旧描述，不能让工作产物继续指导已不存在的镜头。
+
+确定模式后，在进入昂贵的下游处理前完成五次判断：
+
+1. **导演判断**：确定观众承诺、POV、戏剧问题、情绪终点，以及哪些信息要保留到后面揭示。
+2. **故事编辑**：CREATE 比较至少两个可行的剪辑假设；DIRECTED / REVISION 继承用户指定或已确认的主线。beat 始终定义为“发生了什么变化”，而不是场景摘要。
+3. **画面剪辑**：选择真正值得保留的具体时刻、人物反应、入点与出点。
+4. **声音/旁白**：先分配画面、原声、沉默和旁白的任务，再写解说词。
+5. **观众复核**：分别检查无旁白、只听声音和第一次观看时的体验，优先修改回报最高的问题。
+
+执行前阅读本技能的 `references/creative-editing-playbook.md`，并把简洁的创作决定写入：
+
+- `recap_story_plan.json`：导演意图、适用时的备选假设、选定主线和基于变化的 beat 图。
+- `visual_audio_board.json`：每拍的画面任务、表演/反应选择、原声锚点、`audio_owner` 与 `narration_job`。
+- `style_card.json`（有表达要求或表达反馈时）：当前声音、口语节奏、字幕阅读姿态与明确禁忌。
+
+这些文件只记录可审计的当前决定，不记录冗长思维过程；它们不会增加服务或渲染依赖。现有工具可以忽略它们，Agent 与建议型解说评审会用它们保持创作一致。建立这条内容基线不需要平台数据。
+
+## 3. 环境与脚本路径
+
+```bash
+# ffmpeg: brew install ffmpeg | apt install ffmpeg | choco install ffmpeg
+export MIMO_API_KEY=***
+```
+
+同一个 MiMo key 驱动：
+
+- ASR：`mimo-v2.5-asr`
+- VLM：`mimo-v2.5`
+- TTS：`mimo-v2.5-tts`
+
+TTS 可通过 `--tts-provider fish-audio` / `TTS_PROVIDER=fish-audio` 改用 Fish Audio；此时另需 `FISH_API_KEY`，默认模型为 `s2.1-pro-free`，默认使用“娱乐扒妹”音色（`5653cea4ac83480aaf2bf45406556185`），可用 `FISH_TTS_REFERENCE_ID` 覆盖。ASR/VLM 仍使用 MiMo。
+
+`tp-*` Token Plan 密钥默认使用中国区集群，可用 `MIMO_TOKEN_PLAN_CLUSTER` 覆盖。
+
+可选能力：
+
+- `--mimo-video-overview`：按场景块补充 MiMo 视频理解。
+- `--mimo-qc pre-assemble|post-render|both`：在合成前、成片后或两个阶段给出建议型复核。
+
+MiMo QC 默认关闭；每个选定阶段最多请求一次，写入 `mimo_qc.json`。任何凭证缺失、限流、超时、格式错误或采样失败都只记录状态，不阻断流程。详细可覆盖配置见 `references/config-playbook.md`。
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本启动后会自行定位兄弟技能和资源。
+
+## 4. 标准解说流程
+
+### 4.1 背景调研
+
+若能识别影片、剧集或主题，先按本技能的 `references/research-guide.md` 调研并写入
+`work_dir/background_research.json`。视频理解会把人物名和剧情背景折入 VLM 上下文，避免只得到“黑衣男子”一类模糊描述。无法识别来源时可跳过。
+
+### 4.2 分析并暂停创作
+
+```bash
+python3 scripts/recap.py <video> --work-dir <work_dir> --context "背景"
+```
+
+命令完成视频理解、写出 `agent_narration_brief.md`，然后暂停。此时按以下顺序执行 `video-script`：
+
+1. 查看创作 brief 与原片故事板。
+2. 写 `recap_story_plan.json` 和 `visual_audio_board.json`。
+3. full 模式写 `narration.json`；cut 模式第一阶段只写 `clip_plan.json`。
+4. cut 模式第二阶段查看剪后故事板，补充输出时间与声音分工，再写 `narration.json`。
+
+不要从标题或旁白句子开始；先锁定故事体验和素材选择。
+
+时间线有两条不可降级的硬约束：原声只能在可靠句末/静音边界被切入、切出或恢复；旁白必须使用
+完整逐段音频，任何 clip 映射裁段、TTS 裁尾或剪映引用更长的加速前素材都阻断。Agent 收到
+`interrupts_source_sentence` / `unsafe_clip_sentence_boundary` / `no_safe_fit` /
+`timeline_audio_mismatch` 时，应移动边界、缩短整句或删除该块，而不是增加抢断 override。
+
+### 4.3 多视频与素材库
+
+多视频只支持 cut 模式。项目 brief 会列出稳定的 `source_id`，`clip_plan.json` 中每个片段都必须填写来源：
+
+```bash
+python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --target-duration 10m --work-dir work_dir_multi_ep
+```
+
+可选文件系统素材库：
+
+```bash
+python3 scripts/recap.py ep1.mp4 --material-library-dir .video-materials --save-materials
+python3 scripts/recap.py ep1.mp4 ep2.mp4 --edit-mode cut --material-library-dir .video-materials --use-materials
+```
+
+素材检索只是对 JSON / MD / JSONL 做 grep，例如 `grep -R "keyword" .video-materials`。当前版本不复制原始媒体，也不提供数据库、向量或语义搜索。
+
+### 4.4 继续生成成片
+
+写好所需产物后，重复同一条命令：
+
+```bash
+python3 scripts/recap.py <video> --work-dir <work_dir>  # 可追加 --edit-mode cut / --no-burn-subtitles
+```
+
+流程会校验当前阶段的硬输入（`clip_plan.json` / `narration.json`）；两份创作计划仍是 Agent 与建议型评审使用的工作记录，不是渲染门禁。cut 模式随后生成 `edited_source.mp4`，再合成旁白并输出 `recap_<name>.mp4`。
+
+若需要建议型 MiMo 复核：
+
+```bash
+python3 scripts/recap.py <video> --work-dir <work_dir> --mimo-qc both
+```
+
+合成前复核会读取脚本、计划和 TTS 元数据；成片后还会读取最多六张临时 JPEG。相同输入命中内容缓存，`--mimo-qc-refresh` 可强制刷新。帧的 base64 与凭证不会写入磁盘。
+
+### 4.5 字幕与克隆旁白
+
+若要把旁白字幕固定在原片字幕区域，先在仓库根目录运行：
+
+```bash
+python3 tools/measure_subtitle.py <video>
+```
+
+再传入测得的 `--subtitle-y-top/--subtitle-y-bot`。坐标基于 ffmpeg 自动旋转后的显示画布，区间为半开 `[top, bot)`，并要求底对齐 ASS 样式；显式设置后，该区域默认使用 60% 透明度的旁白窗口遮罩。
+
+解说模式如需克隆参考声音，使用 `--voice-ref <audio>`；它与 dub 模式不同。
+
+### 4.6 最终观看与交付复核
+
+脚本、接点检测、样帧和 QC 报告都不能替代观看。每轮准备交付前，必须检查**本轮实际要交付的最终文件**，而不是旧别名、无字幕母版或中间代理：
+
+1. 正常速度完整播放一次短片，不边看边改；先记录真实观看问题。
+2. 播放每个拼接点前后约 0.5–1 秒，检查闪帧、原片叠化被截断、动作跳变和半句原声。
+3. 完整只听声音一次，检查旁白是否碎成一句一停、场景间声音是否接得上、关键原声是否完整。
+4. 单独复看开头、核心情绪/表演点和结尾，确认进入时机、回报停留和收束都成立。
+5. REVISION 分别验证本轮修改项已经改变、冻结项没有意外变化；然后再做解码、时长、音画规格等机械检查。
+
+scene score、亮度统计、contact sheet 与自动 QC 只负责定位候选问题；最终判断以真实播放为准。短时间内出现密集候选时，必须判断每个切点来自原片还是本次拼接：原片无关短镜头整段删，相关短镜头扩展到完整动作/反应；人工拼接点优先移动边界、恢复同源连续运动或合并片段，能消除就不保留。修复失败时回到剪点、声音或文案层，不用更多包装掩盖。
+
+## 5. 英译中原声复刻模式
+
+`--edit-mode dub` 把英文视频翻译为中文，并用原说话者的克隆音色替换人声；它不是在压低原声上叠加解说。
+
+```bash
+python3 scripts/recap.py <video> --edit-mode dub --work-dir <work_dir>
+```
+
+准备阶段会转写英文、提取一段参考音频，并写出 `dub_brief.md` 与 `dub_transcript.json`。Agent 随后写：
+
+```json
+[{"start": 0.0, "end": 2.0, "zh": "中文译文"}]
+```
+
+要求：
+
+- 逐句忠实翻译，不删钩子、不合并、不擅自压缩；原文重复，译文也按时间重复。
+- 每句沿用原声 `[start, end]`，相邻句不重叠。
+- 译文尽量控制在约 5 字/秒，使其能在原时间窗内说完。
+
+重复同一命令后输出 `dub_<name>.mp4`。每句单独克隆并贴回原时间线；只有即将覆盖下一句时才局部加速。当前版本只支持单说话者、整轨替换，不分离背景音乐。
+
+## 6. 自检命令
+
+```bash
+python3 scripts/recap.py --doctor
+```
+
+## 7. 输出与参数
+
+主要输出：
+
+- `recap_<video>.mp4`：最终成片。
+- `subtitles.srt` / `subtitles.ass`：字幕。
+- `work_dir/`：全部中间产物，契约见 `references/data-schema.md`。
+- `work_dir/recap_story_plan.json` / `visual_audio_board.json`：Agent 创作意图与剪辑决定。
+- `work_dir/mimo_qc.json`：可选的建议型复核，不作为发布门禁。
+
+可透传参数：
+
+`--context`、`--scene-threshold`、`--style`、`--edit-mode {full,cut,dub}`、`--target-duration`、
+`--skip-asr`、`--mimo-video-overview`、`--mimo-qc {off,pre-assemble,post-render,both}`、
+`--mimo-qc-refresh`、`--consolidate`、`--consolidate-asr`、`--tts-provider`、`--mimo-tts-voice`、`--voice-ref`、
+`--allow-partial-tts`、`--review-narration`、`--no-review-narration`、`--require-narration-review`、
+`--subtitle-y-top`、`--subtitle-y-bot`、`--no-burn-subtitles`、`--output-dir`、
+`--export-jianying`、`--jianying-bundle-media`、`--jianying-no-bundle-media`、
+`--material-library-dir`、`--use-materials`、`--save-materials`。
+
+`--style` 是原样传给 Agent 的自由文本指导，不是 preset、枚举、开关或有限风格分类。
+
+## 8. 能力边界
+
+- 编排器不代替 Agent 写 `narration.json` / `clip_plan.json`；具体写作遵循创作 brief 与写作阶段契约。
+- 语义评审默认建议型、失败开放；只有调用方显式启用严格解说评审时，事实矛盾、残句或评审不可用才会在 TTS 前阻断。确定性校验阶段始终负责硬校验。
+- MiMo QC 不能阻断、自动修复或改变退出状态，只提供定位建议。
+- 建立内容质量基线不依赖平台分析、留存遥测或发布接入。
+- 本技能不是无人值守调度器，不会向任何平台发布内容。
+- 各阶段技能不共享代码，只通过 `work_dir` 产物通信。

package/lib/video-recap/skills/video-recap/references/config-playbook.md

@@ -0,0 +1,61 @@
+# Config playbook (override-only)
+
+The bundle runs **zero-config** with sensible defaults. To change behavior, set the
+environment variables below (or pass the noted CLI flags) — they **override** the defaults.
+Nothing here is required; this is documentation only. No tool reads a config file, and the
+bundle ships no root `CLAUDE.md` (so it never collides with your project/global instructions).
+Defaults below are bundle-level defaults unless a note scopes them to a specific stage.
+
+| Concern | Env var / flag | Default | Notes |
+|---|---|---|---|
+| MiMo API key | `MIMO_API_KEY` | — | **required for the default pipeline**; one key drives ASR + VLM + default MiMo TTS. `tp-*` Token-Plan keys auto-route to the cluster base URL; `sk-*` keys support pay-as-you-go without a subscription |
+| Token-Plan cluster | `MIMO_TOKEN_PLAN_CLUSTER` | `cn` | `cn` / `sgp` / `ams` (only for `tp-*` keys) |
+| VLM / chat model | `MIMO_MODEL` | `mimo-v2.5` | frame VLM + reviewer + consolidate |
+| ASR model | `MIMO_ASR_MODEL` | `mimo-v2.5-asr` | speech-to-text |
+| ASR language | `MIMO_ASR_LANGUAGE` | `auto` | `auto` / `zh` / `en` |
+| ASR window | `ASR_SEGMENT_SECONDS` | `15` | smaller → finer dialogue timestamps (stays under MiMo's 10MB base64 cap) |
+| TTS provider | `TTS_PROVIDER` / `--tts-provider {auto,mimo-tts,fish-audio}` | `auto` | `auto` prefers configured MiMo, then Fish Audio; explicit selection is recommended for repeatable runs |
+| MiMo TTS model | `MIMO_TTS_MODEL` | `mimo-v2.5-tts` | MiMo provider only |
+| MiMo voice | `MIMO_TTS_VOICE` / `--mimo-tts-voice` | `冰糖` | |
+| Cloned narration voice | `VOICE_REF` / `--voice-ref` | off | MiMo full/cut only; lazily normalize once, then use `mimo-v2.5-tts-voiceclone`; mutually exclusive with `--mimo-tts-voice`; requires authorization and sends the reference to MiMo |
+| Fish Audio key | `FISH_API_KEY` | — | required when Fish Audio is selected; never written to artifacts or cache metadata |
+| Fish Audio model | `FISH_TTS_MODEL` | `s2.1-pro-free` | current free model; Fair Use/no SLA and free availability is currently announced through 2026-08-31 |
+| Fish Audio voice | `FISH_TTS_REFERENCE_ID` | `5653cea4ac83480aaf2bf45406556185`（娱乐扒妹） | optional override for the built-in narration voice; participates in segment cache identity |
+| Fish Audio endpoint | `FISH_TTS_API_URL` | `https://api.fish.audio/v1/tts` | returns WAV directly to the existing voiceover pipeline |
+| TTS transport | `TTS_TIMEOUT` / `TTS_WORKERS` / `TTS_RETRIES` | `300` / `4` / `3` | request timeout, parallel segments, and per-segment retries for both providers |
+| Advisory MiMo QC | `MIMO_QC` / `--mimo-qc {off,pre-assemble,post-render,both}` | `off` | optional subjective review at the selected stage(s), one request per stage. Always fail-open: results only point the agent/user to `mimo_qc.json`, never block or auto-repair |
+| MiMo QC refresh/model | `MIMO_QC_REFRESH` / `--mimo-qc-refresh`; `MIMO_QC_MODEL` | cache on / VLM fallback | content-keyed cache excludes absolute paths. Post-render temporarily samples at most 6 JPEGs (≤768px); base64 is never persisted. The standalone adapter requires explicit `mimo_qc.py --live` for network access |
+| Narration block coverage | `NARRATION_COVERAGE_TARGET` / `NARRATION_BLOCK_SECONDS` | `0.7` / `9.0` | current block-recap density controls; old `TARGET_SEGMENTS_PER_MINUTE` applies only to legacy single-pass cut mapping reports |
+| Narration speed | `NARRATION_SPEED` | `1.15` | global atempo on the voiceover; set `1.0` for long-form/documentary |
+| Narration authored start | `NARRATION_DELAY_SECONDS` | `0` | the renderer uses the Agent-authored `start` exactly. Set a non-zero value only for legacy drafts; hidden delay can move a validated sentence-boundary entry back into source speech |
+| Source sentence boundary detector | `SOURCE_BOUNDARY_NOISE_THRESHOLD` / `SOURCE_BOUNDARY_MIN_PAUSE` / `SOURCE_BOUNDARY_MAX_ALIGNMENT_ERROR` | `-18dB` / `0.12` / `2.1` | aligns ASR terminal punctuation to short acoustic pauses and writes `speech_boundary_anchors.json`; unsafe narration entries and cut in/out points are blocked. There is no intentional-interrupt override |
+| Cut sentence snapping | `SNAP_CLIP_LINE_END` / `CLIP_START_SNAP_MAX_PREPEND` / `CLIP_START_SNAP_MAX_TRIM` / `CLIP_SNAP_MAX_EXTEND` | on / `1.8` / `0.35` / `2.0` | scene-cut cleanup runs first; reliable sentence/quiet snapping runs last. An ASR-owned edge still inside speech produces `unsafe_clip_sentence_boundary` instead of a half sentence |
+| Mask source subs | `MASK_SOURCE_SUBTITLES` / `SOURCE_SUBTITLE_MASK_POLICY` / `SOURCE_SUBTITLE_MASK_RATIO` | off / `off` / `0.14` | masking requires an explicit policy (`opt_in`, `safe`, or `forced`) and burned recap subtitles. Passing measured `--subtitle-y-top/--subtitle-y-bot` opts in automatically. With `--no-burn-subtitles`, the MP4 stays unmasked |
+| Measured subtitle band | `SUBTITLE_Y_TOP` / `SUBTITLE_Y_BOT`; `--subtitle-y-top/--subtitle-y-bot` | off | half-open `[top, bot)` ffmpeg auto-rotated display-frame pixel coordinates; square-pixel video and bottom ASS alignment (1/2/3) only; use `tools/measure_subtitle.py` to generate source-identified previews and suggestions |
+| Subtitle mask look | `SUBTITLE_MASK_OPACITY` / `SOURCE_SUBTITLE_MASK_TIMING` / `SUBTITLE_MASK_PADDING` | `0.6` / `narration` / `4` | generic ratio masks stay translucent by default; an explicitly measured `--subtitle-y-top/--subtitle-y-bot` band defaults to opaque so source glyphs cannot show through. Set `SUBTITLE_MASK_OPACITY` to override; timing `all` restores full-time masking |
+| Original ducking | `IDLE_ORIG_VOLUME` / `SPEECH_DUCKING_VOLUME` | `1.0` / `0.2` | the original returns to full-volume `IDLE` in deliberate gaps/original blocks, and ducks to `SPEECH` under narration. Inter-beat gaps shorter than `DUCK_BRIDGE_SECONDS` stay ducked so a single narration block does not swell between sentences. `DUCKING_ORIG_VOLUME` (`0.3`) is only the fallback when beats carry no placement info |
+| Foreign source audio | `FOREIGN_SOURCE_AUDIO` | off | set when the original audio is in a language the narration is **not** (e.g. a Japanese drama recapped in Chinese). The under-narration original (`SPEECH_DUCKING_VOLUME` / `ZONE_DUCKING_VOLUME`) drops from `0.2`/`0.12` to `0.05` so the foreign speech doesn't bleed under the narration as 怪音; original-audio gap blocks still play full-volume (`IDLE_ORIG_VOLUME`). Explicit `SPEECH_DUCKING_VOLUME`/`ZONE_DUCKING_VOLUME` still override. Pairs with bring-your-own `user_subtitles.*` for the foreign dialogue |
+| Duck fade | `DUCK_FADE_SECONDS` | `0.3` | attack ramp target. Sentence-safe source restore is shortened to fit wholly inside the measured acoustic pause (`pause_start`→anchor), so it never reveals the previous source sentence tail |
+| Duck bridge | `DUCK_BRIDGE_SECONDS` | `1.5` | inter-beat gaps shorter than this stay ducked inside one narration block; gaps >= this are treated as intentional original-audio blocks and return to `IDLE_ORIG_VOLUME` |
+| Background music | `BGM_PATH` / `BGM_VOLUME` / `BGM_DUCKING_VOLUME` | off / `0.18` / `0.10` | optional looped music bed mixed as its own track; point `BGM_PATH` at any audio file. It ducks to `BGM_DUCKING_VOLUME` under narration |
+| Final loudness | `FINAL_LOUDNORM` / `TARGET_LUFS` | `true` / `-14` | end-of-pipeline normalize |
+| Output compression | `OUTPUT_CRF` / `OUTPUT_PRESET` / `OUTPUT_MAX_HEIGHT` | `18` / `veryfast` / `0` | x264 re-encode controls, applied whenever the final mux re-encodes (burning subtitles / masking / scaling / `FORCE_VIDEO_REENCODE`). Higher `OUTPUT_CRF` = smaller file/lower quality (18≈visually lossless, 23–26 much smaller); `slow`/`slower` preset shrinks more at the same CRF; `OUTPUT_MAX_HEIGHT>0` downscales the final height (keeps aspect, even width), e.g. `720` to halve 1080p pixels. Subtitles/mask render at native res then downscale, so they stay crisp |
+| Style | `--style` | `纪录片` | freeform verbatim guidance passed into the agent brief. The agent synthesizes voice/pacing from this exact text plus evidence; it is not a fixed option list, preset, switch, or finite style taxonomy |
+| Edit mode | `EDIT_MODE` / `--edit-mode` | `full` | `full`, `cut`, or `dub`; multi-source input supports `cut` only |
+| Cut target | `TARGET_DURATION` / `--target-duration` | — | e.g. `10m` (cut mode) |
+| Scene threshold | `--scene-threshold` | `0.1` | scene-cut sensitivity |
+| Shot-change-aware cut | `SCENE_CUT_SNAP` / `SCENE_CUT_SNAP_MARGIN` / `SCENE_CUT_DETECT_THRESHOLD` | on / `0.5` / `0.4` | cut mode: nudge each clip boundary off the original footage's hard cuts so the edit point doesn't flash a sliver of the adjacent shot (闪烁). source_start moves forward onto / source_end back onto any shot-change within the margin; boundaries already on a cut, or that would shrink a clip below ~0.5s, are left as-is. Set `SCENE_CUT_SNAP=0` to disable |
+| VLM workers | `VLM_WORKERS` | `8` | lower to 1 if a proxy/WAF rate-limits |
+| Subtitle size | `SUBTITLE_FONT_SIZE` / `SUBTITLE_MARGIN_V` | `42` / `48` | look & placement |
+| 整理 / index | `--no-consolidate` / `--consolidate-asr` | on | build the understanding index (and optionally clean ASR); use `--no-consolidate` to skip |
+| Advisory / strict narration review | `REVIEW_NARRATION` / `--review-narration` / `--no-review-narration`; strict: `REQUIRE_NARRATION_REVIEW` / `--require-narration-review` | advisory on, strict off | runs the narration review stage after validation and before TTS. Default advisory mode is fail-open; strict mode blocks TTS on review failure, parse error, or error-severity findings. In cut mode the reviewer uses `clip_plan_validated.json` to remap VLM/ASR grounding onto the output timeline |
+| 剪映 export (optional) | `--export-jianying` / `EXPORT_JIANYING` | off | after rendering, also write a 剪映/JianYing draft from `timeline.json`. Decoupled — the core render never needs it |
+| 剪映 draft dir | `JIANYING_DRAFT_DIR` | work_dir | parent folder for the exported draft (point it at 剪映's drafts root to open in-app) |
+| 剪映 bundle media | `JIANYING_BUNDLE_MEDIA` / `--jianying-no-bundle-media` | **on** | copies video/audio/photo into `Resources/local/*`, uses draft-placeholder paths, and writes the type-0 material index in `draft_meta_info.json`. This makes a cloned/moved draft self-contained and is required on sandboxed macOS. Use `--jianying-no-bundle-media` only if 剪映 can reach the original paths |
+| Source video | `--source-video` | — | original video (cut mode) so `timeline.json` / 剪映 export reference the real source clips instead of the concatenated `edited_source.mp4`; direct `video-assemble` runs intentionally ignore ambient `SOURCE_VIDEO` unless `--source-video` is passed |
+
+`video-assemble` always writes `timeline.json` — a backend-neutral multi-track model
+(video / original-audio / narration / BGM / subtitle, with ducking automation). The
+canonical renderer is ffmpeg; the 剪映 exporter is an optional consumer of the same file. Subtitle text in `timeline.json` is display-ready and follows the same terminal-punctuation policy as SRT/ASS.
+
+See each stage skill's SKILL.md for the full per-stage option list.

package/lib/video-recap/skills/video-recap/references/creative-editing-playbook.md

@@ -0,0 +1,225 @@
+# 创作剪辑工作法
+
+本参考只规定 Agent 的创作判断，不增加渲染模块。进入剪辑或写稿前，先完成这里的决策，再写 `clip_plan.json` 或 `narration.json`。
+
+## 先判断创作控制模式
+
+- **CREATE**：没有既定成片方向，可以比较故事/剪辑假设并选择。
+- **DIRECTED**：用户已经指定结构、镜头、台词或表达，目标是准确落实而不是展示替代创意。
+- **REVISION**：基于已有版本看片修改。最新反馈覆盖旧决定；本轮未点名内容默认冻结。
+
+REVISION 先列本轮修改项与冻结项。表达、节奏、字幕意见写回 `style_card.json`，镜头与声音意见写回 `visual_audio_board.json`；只有故事主线改变才更新 `recap_story_plan.json`。删除内容时也删除过期的计划描述。完成后分别验证“该变的确实变了”和“不该变的没有漂移”。
+
+## 决策优先级
+
+硬约束先于审美：
+
+1. **证据真实**：人物、关系、因果和结果必须由画面、对白、可靠背景或用户上下文支撑。
+2. **声音可懂**：关键原声不能被截成半句，旁白不能把必须听见的对白完全盖住。
+
+硬约束满足后，发生冲突时按以下顺序取舍：
+
+1. 情绪与人物；
+2. 故事推进；
+3. 节奏；
+4. 视线与画面连续；
+5. 技术上的“绝对工整”。
+
+不要为了连续而牺牲人物反应，也不要为了快而删掉真正改变观众感受的瞬间。
+
+## 五次专业判断
+
+### 1. 导演：先决定观众经历什么
+
+先回答，而不是先写开场文案：
+
+- 观众承诺：看完具体会理解、担心或感受到什么？
+- POV：这条内容主要跟随谁的经历？谁不是主视角？
+- 戏剧问题：观众一直想知道的那个问题是什么？
+- 情绪路径：开头的情绪如何变成结尾的情绪？
+- 隐瞒与揭示：什么信息暂时不说，何时揭示才最有力量？
+- 结尾余味：答案落地后，观众最后应留下什么感受？
+
+CREATE 至少提出两个可成立的剪辑假设，再选一个。比较的是叙事效果，不是措辞：例如“按主角认知逐步揭示”与“先展示后果再追问原因”。DIRECTED / REVISION 沿用用户指定或已确认的主线，不为满足模板重新发散。只记录当前选择与理由，不输出冗长思维过程。
+
+### 2. 故事编辑：把素材组织成变化
+
+beat 不是固定秒数、场景名或一句旁白；beat 是一次可感知的变化。每个保留 beat 至少改变一项：
+
+- 观众知道了什么；
+- 人物想要什么；
+- 谁占上风；
+- 关系如何移动；
+- 情绪如何转向；
+- 风险或代价如何升级。
+
+如果移除一个 beat 后，因果、人物或情绪都没有损失，它通常不值得占用成片时间。钩子必须提出这条故事真正会兑现的问题，不能制造正文不回答的夸张承诺。
+
+### 3. 画面剪辑：选择时刻，而不只选择事件
+
+对每个 beat 做以下判断：
+
+- **入点**：能否晚一点进入，跳过已经能推断的铺垫？
+- **出点**：信息或情绪落地后，能否早一点离开？
+- **表演**：说话者与倾听者谁更能承载此刻？动作与反应谁更重要？
+- **不可替代瞬间**：停顿、迟疑、失误、眼神、动作声音中，哪一个让人物变得真实？
+- **节奏**：这一拍需要冲过去，还是需要多停半秒让含义落地？
+- **边界**：优先完整动作、完整台词和自然声音边界；不要机械地把每个片段切成同一长度。
+
+进入 `clip_plan.json` 的不是“发生过的所有重要事件”，而是最能让观众经历这条主线的具体时刻。
+
+目标不是绝对最短，而是**最短但完整**：晚进不能丢掉理解动作所需的前提，早出不能吃掉表演的回报。建立空间和事实的镜头通常可以短；关键对视、亲吻、受伤反应、决定落地或沉默可以多停一点，让观众先感受到再离开。
+
+场景之间的 IN / OUT 也要有任务：
+
+- 新人物、地点或情绪场景，先给画面一个可感知的建立时刻，再让旁白进入；旁白不必与画面同帧起跑。
+- OUT 优先落在动作完成、反应落地、台词句末、沉默结束或干净硬切前。
+- 不要在原片叠化、闪白或其他转场的中间再切一次。转场至少由画面变化、动作延续、声音接力或叙事跨越中的一项驱动。
+
+scene-change score、逐帧亮度和接点 contact sheet 只用于诊断：检查每个接点前后约 0.5–1 秒，定位硬切、白闪或曝光叠化候选。修复优先收进稳定镜头、保留原片完整转场的一侧、扩展源素材，或用相邻有效镜头补足时长；不能为了视觉干净切断台词。最终必须真实播放接点，不能把检测分数当成观看结论。
+
+对短时间频繁切镜头的段落，先用 ffmpeg scene filter 输出候选时间，例如：
+
+```bash
+ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
+```
+
+阈值只用于召回候选，闪白、叠化和大幅运动都可能误报。把候选映射回 source 区间和成片拼接边界后再分类处理：
+
+- **原片切点**：无关的短镜头按完整 source shot 删除；相关但停留过短、看起来像闪一下的镜头，向前/后扩展到完整动作、反应、台词或下一个干净切点。这里的“拉长”是多保留真实源素材，不默认用定格或慢放制造不存在的表演。
+- **本次剪辑制造的切点**：优先移动 IN / OUT、恢复同一源镜头的连续运动、合并相邻片段，或换成有叙事任务的连接镜头；能消除就不保留。溶解、闪白和包装不能用来遮掩坏接点。
+- **有意的原片蒙太奇**：只有当每个短镜头都提供新信息、动作或节奏回报，且正常播放仍清楚可读时才保留；否则按无关或过短镜头处理。
+
+密集度不是单一固定秒数门槛。先找同一短窗内的连续候选，再以正常速度播放判断观众感受到的是有效节奏还是闪烁。
+
+### 4. 声音与旁白：先分工，再写字
+
+每个 beat 先指定一个主要 `audio_owner`：
+
+- `original_dialogue`：原对白本身就是事件或表演；
+- `action_sound`：动作声音承担冲击、因果或空间感；
+- `ambience` / `music`：环境或音乐承担情绪；
+- `silence`：沉默、停顿或呼吸是内容；
+- `narration`：画面和原声无法独自交代必要的上下文、因果或预期。
+
+只有当旁白有明确工作时才写。`narration_job` 只能从以下任务中选择：
+
+- `context`：补充看不见但必要的背景；
+- `causal_link`：连接被压缩掉的因果；
+- `foreshadow`：建立稍后会兑现的预期；
+- `interpretation`：基于证据指出人物选择、关系或代价；
+- `transition`：跨越时间、地点或素材来源；
+- `none`：画面、原声或沉默已经足够。
+
+`7:3` 只可作为没有更好判断时的粗略首稿参考，不是质量目标或覆盖配额。强对白可以让一个 beat 完全没有旁白；信息密集的压缩段也可以由旁白主导。
+
+旁白拥有一个 beat 时，先写成一个连续思路，常见推进是“前提 → 触发动作 → 变化/意义”。句子数量不是目标；一个完整长句或少量相连句都可以，关键是一次 TTS 能自然说完而不是一句一停。字幕可以为阅读拆成多个 cue，但不能反过来把朗读稿切成碎 utterance。
+
+“不是 A，而是 B”只在素材确实需要纠正一个可能的旧判断时有价值。不要先虚构错误判断，再用肯定句制造洞察；能直接写动作、因果和后果时就直接写。
+
+### 5. 观众复核：从第一次观看出发
+
+完成草案后做三次反事实检查：
+
+1. **静音旁白**：只看画面和原声，人物、变化和关键情绪是否仍可感知？
+2. **只听声音**：旁白是否形成一条可听懂的主线，而不是字幕腔或画面复述？
+3. **第一次观看**：开头承诺了什么、每一拍又打开了什么问题、结尾是否真正回答？
+
+再逐 beat 追问：
+
+- 删除它，什么会坏？什么都不坏就删。
+- 换成反应镜头，情绪是否更强？
+- 旁白改成原声或沉默，含义是否更好？
+- 提前揭示或延后揭示，哪一个更符合 POV？
+- 能否晚进、早出，而不损失理解？
+
+只优先处理 1–3 个最高回报修改，避免用大量低价值润色掩盖结构问题。
+
+准备交付时，把抽象的“第一次观看”落实成动作：正常速度完整播放实际最终文件；逐个播放接点前后；完整只听声音；再单独复看开头、核心情绪点和结尾。脚本、样帧与自动 QC 只能辅助定位，不能替代完整观看。
+
+## Agent 创作产物
+
+这些是简洁的决策记录，不是公开的完整思维过程。CLI 可以忽略它们，但后续 Agent 与建议型评审会使用它们保持创作一致。
+
+### `recap_story_plan.json`
+
+```json
+{
+  "schema_version": 1,
+  "director_intent": {
+    "viewer_promise": "观众最终得到的具体体验",
+    "pov": "主要跟随谁，以及为什么",
+    "dramatic_question": "贯穿全片的问题",
+    "emotional_start": "起始情绪",
+    "emotional_end": "结束情绪",
+    "ending_aftertaste": "最后余味",
+    "withhold_reveal": "保留什么，何时揭示"
+  },
+  "hypotheses": [
+    {"id": "h1", "spine": "方案一主线", "opening": "如何进入", "ending": "如何落地", "risk": "主要风险"},
+    {"id": "h2", "spine": "方案二主线", "opening": "如何进入", "ending": "如何落地", "risk": "主要风险"}
+  ],
+  "chosen_hypothesis": "h1",
+  "choice_reason": "为什么它更符合素材中的人物、故事和情绪",
+  "beats": [
+    {
+      "beat_id": "b01",
+      "source_id": "可选，多视频时填写",
+      "source_start": 12.0,
+      "source_end": 20.0,
+      "function": "hook|setup|turn|escalation|payoff",
+      "event": "可观察到的事件",
+      "change": "knowledge|power|emotion|goal: before -> after",
+      "audience_question_in": "进入前观众想知道什么",
+      "audience_question_out": "离开时答案或新问题是什么",
+      "character_focus": "此拍由谁承载",
+      "must_keep_moment": "不可替代的动作/表情/台词/声音",
+      "evidence": ["visual", "asr"]
+    }
+  ]
+}
+```
+
+上例是 CREATE 形态。DIRECTED / REVISION 可以只保留用户指定或当前采用的假设；不要复制一个虚假备选来凑数量。
+
+### `visual_audio_board.json`
+
+```json
+{
+  "schema_version": 1,
+  "items": [
+    {
+      "beat_id": "b01",
+      "source_id": "可选，多视频时填写",
+      "source_start": 12.0,
+      "source_end": 20.0,
+      "output_start": null,
+      "output_end": null,
+      "picture_job": "orientation|evidence|performance|reaction|action|contrast",
+      "preferred_moment": "具体要保留的画面时刻",
+      "entry_reason": "为什么从这里进入",
+      "exit_reason": "为什么在这里离开",
+      "audio_owner": "original_dialogue|action_sound|ambience|music|silence|narration",
+      "original_audio_anchor": "要完整保留的对白/动作声/停顿",
+      "narration_job": "none|context|causal_link|foreshadow|interpretation|transition",
+      "handoff": "前后画面、原声与旁白如何接力"
+    }
+  ]
+}
+```
+
+cut 第一阶段先用原片时间写；`edited_source.mp4` 产生后，在第二阶段补上输出时间并重新确认 `audio_owner` / `narration_job`。
+
+## 内容质量基线
+
+进入 TTS 前，以下问题都必须能用具体 beat 回答；否则先改计划或脚本：
+
+1. **承诺**：开头提出的真实问题，结尾是否兑现？
+2. **主线**：是否有一个明确 POV 和一条主导因果/关系线？
+3. **变化**：每个 beat 是否改变知识、权力、目标、关系、情绪或风险？
+4. **人物**：是否保留了至少一个不能由剧情概述替代的表演/反应瞬间？
+5. **视听分工**：每个 beat 是否明确由画面、原声、沉默或旁白中的谁主导？
+6. **必要性**：旁白是否都在增加信息或期待，而不是复述像素？
+7. **完整观看**：实际最终文件是否完整看过、逐接点看过并只听声音检查过？
+
+这套基线与抖音、YouTube 或任何平台数据无关。先让内容本身成立，再讨论标题、封面、时长档位和发布优化。