@oh-story/dsh 0.1.10 → 0.1.11

package/lib/video-recap/skills/video-assemble/scripts/timeline_emit.py

@@ -7,6 +7,7 @@ from lib import CONFIG, log
 from media import _build_video_clips
 from source_subtitles import _combined_subtitle_entries
 from timeline import build_timeline, save_timeline
+import packaging
 
 def _timeline_subtitle_segments(tts_segments, work_dir, duration_s):
     """Display-ready subtitle cues for timeline/export text tracks.
@@ -25,10 +26,32 @@ def _timeline_subtitle_segments(tts_segments, work_dir, duration_s):
     ]
 
 
-def _emit_timeline(input_video, tts_segments, work_dir, duration_s, canvas, has_bgm):
+def _emit_timeline(input_video, tts_segments, work_dir, duration_s, canvas, has_bgm, *,
+                   audio_mode="narration", selected_audio_stream=0,
+                   explicit_audio_mix=None):
     """Build and persist the backend-neutral multi-track timeline.json."""
-    video_clips = _build_video_clips(input_video, work_dir, duration_s)
+    if audio_mode == "narration" and explicit_audio_mix is None:
+        video_clips = _build_video_clips(input_video, work_dir, duration_s)
+    else:
+        # Non-narration sound comes from the actual current picture input as one
+        # complete interval. Re-expanding an old cut plan would substitute different
+        # source sound and make the optional editor project misrepresent the render.
+        video_clips = [{
+            "source_path": str(Path(input_video)),
+            "source_start": 0.0,
+            "source_end": float(duration_s),
+            "timeline_start": 0.0,
+            "timeline_end": float(duration_s),
+        }]
+    # Mix segments are 1:1 with the UNFILTERED narration list, so they must be looked
+    # up by their own index; a skipped beat would otherwise shift every later gain and
+    # sample bound onto the wrong segment.
+    mix_by_index = (
+        {item["index"]: item for item in explicit_audio_mix["segments"]}
+        if explicit_audio_mix is not None else {}
+    )
     narration_segments = []
+    placed_indices = []
     for seg in tts_segments:
         s, e = _seg_place_window(seg)
         if e <= s:
@@ -40,16 +63,20 @@ def _emit_timeline(input_video, tts_segments, work_dir, duration_s, canvas, has_
             "source_path": seg["placed_audio_path"],
             "timeline_start": s, "timeline_end": e,
             "text": seg["narration"],
-            "overlaps_speech": seg.get("overlaps_speech", True),
-            "gain": 1.0,
+            "overlaps_speech": seg["overlaps_speech"],
+            "gain": (
+                mix_by_index[seg["index"]]["gain"]
+                if explicit_audio_mix is not None else 1.0
+            ),
         }
         for key in ("source_duck_end", "source_restore_at", "source_handoff_status", "source_entry_status"):
             if key in seg:
                 narration_item[key] = seg[key]
         narration_segments.append(narration_item)
+        placed_indices.append(seg["index"])
     fade = CONFIG["duck_fade_seconds"]
     bgm = None
-    if has_bgm:
+    if has_bgm and explicit_audio_mix is None:
         bgm = {"source_path": CONFIG["bgm_path"],
                "volume": CONFIG["bgm_volume"],
                "ducking_volume": CONFIG["bgm_ducking_volume"],
@@ -57,7 +84,8 @@ def _emit_timeline(input_video, tts_segments, work_dir, duration_s, canvas, has_
     # carry ducking automation whenever ducking is on at all; even under sidechain
     # mode the draft gets editable volume keyframes (ffmpeg stays the canonical mix)
     ducking = None
-    if CONFIG["ducking_mode"] != "none":
+    if audio_mode == "narration" and explicit_audio_mix is None \
+            and CONFIG["ducking_mode"] != "none":
         ducking = {"idle": CONFIG["idle_orig_volume"],
                    "speech": CONFIG["speech_ducking_volume"],
                    "quiet": CONFIG["zone_ducking_volume"],
@@ -66,7 +94,63 @@ def _emit_timeline(input_video, tts_segments, work_dir, duration_s, canvas, has_
     subtitle_segments = _timeline_subtitle_segments(tts_segments, work_dir, duration_s)
     timeline = build_timeline(canvas, duration_s, video_clips,
                               narration_segments, bgm=bgm, ducking=ducking,
-                              subtitle_segments=subtitle_segments)
+                              subtitle_segments=subtitle_segments,
+                              image_segments=packaging.timeline_image_segments(
+                                  packaging.load_packaging_layers(work_dir, canvas),
+                                  canvas, duration_s))
+    if explicit_audio_mix is not None:
+        for clip in timeline["tracks"][0]["clips"]:
+            clip["audio"] = {
+                "role": "picture_audio_not_consumed", "base_gain": 0.0,
+                "volume_keyframes": [],
+            }
+        narration_track = next(
+            (track for track in timeline["tracks"] if track.get("name") == "narration"), None
+        )
+        if narration_track:
+            for segment, index in zip(narration_track["segments"], placed_indices):
+                adopted = mix_by_index[index]
+                segment.update({
+                    "gain": adopted["gain"],
+                    "output_start_sample": adopted["output_start_sample"],
+                    "output_end_sample": adopted["output_end_sample"],
+                    "sample_rate": 48_000,
+                })
+        timeline["tracks"].append({
+            "kind": "audio", "name": "prepared_bed", "role": "prepared_bed",
+            "segments": [{
+                "source_path": explicit_audio_mix["prepared"]["prepared_bed.wav"]["path"],
+                "timeline_start": 0.0, "timeline_end": float(duration_s), "gain": 1.0,
+            }],
+        })
+        timeline["audio_delivery"] = {
+            "mode": "explicit_adopted_full_sound", "sample_rate": 48_000,
+            "total_samples": explicit_audio_mix["format"]["total_samples"],
+            "master_gain_db": explicit_audio_mix["master_gain_db"],
+            "canonical_renderer": "ffmpeg_explicit_mix",
+            "reconstructable": False,
+            "reconstructable_reason": (
+                "optional editor export does not implement the adopted 48 kHz "
+                "prepared-bed, per-segment gain, and fixed-master chain"
+            ),
+        }
+    if audio_mode != "narration":
+        source_gain = 1.0 if audio_mode == "adopted-packet-copy" else CONFIG["idle_orig_volume"]
+        for clip in timeline["tracks"][0]["clips"]:
+            clip["audio"].update({
+                "base_gain": round(float(source_gain), 4),
+                "selected_stream": selected_audio_stream,
+                "mode": audio_mode,
+            })
+        timeline["audio_delivery"] = {
+            "mode": audio_mode,
+            "selected_stream": selected_audio_stream,
+            "packet_frozen": audio_mode == "adopted-packet-copy",
+            "reconstructable": (
+                audio_mode == "adopted-packet-copy" and selected_audio_stream == 0
+            ),
+            "canonical_renderer": "stream_copy" if audio_mode == "adopted-packet-copy" else "ffmpeg_mix",
+        }
     degraded = [
         {"source_path": clip["source_path"], "reason": clip["provenance_reason"]}
         for clip in video_clips

package/lib/video-recap/skills/video-assemble/scripts/visual_render.py

@@ -4,7 +4,6 @@ import json
 import re
 from pathlib import Path
 
-from artifacts import _artifact_fingerprint
 from assemble_constants import (
     SUBTITLE_STYLE_REF_H,
     VISUAL_OVERLAYS,
@@ -19,7 +18,7 @@ from source_subtitles import (
     _original_gap_subtitle_entries,
     _source_subtitle_mask_policy,
 )
-from subtitle_core import (
+from subtitles.core import (
     _measured_subtitle_band,
     _measured_subtitle_safe_area,
     _normalize_subtitle_text,
@@ -136,7 +135,7 @@ def _load_visual_overlays(work_dir):
     """Return (overlays, source) from the canonical visual_overlays.json handoff."""
     path = Path(work_dir) / VISUAL_OVERLAYS
     if not path.exists():
-        return [], {"present": False, "path": str(path), "fingerprint": None}
+        return [], {"present": False, "path": str(path)}
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
     except json.JSONDecodeError as exc:
@@ -152,7 +151,6 @@ def _load_visual_overlays(work_dir):
     source = {
         "present": True,
         "path": str(path),
-        "fingerprint": _artifact_fingerprint(path),
         "schema_version": 1,
     }
     return data["overlays"], source
@@ -236,14 +234,14 @@ def _visual_overlay_filters(work_dir, canvas, video_duration):
         if typ == "top_title":
             filt = (
                 "drawtext="
-                f"text='{safe_text}':x=(w-text_w)/2:y={int(bbox['y'])}:"
+                f"{_drawtext_font_option()}text='{safe_text}':x=(w-text_w)/2:y={int(bbox['y'])}:"
                 f"fontsize={font_size}:fontcolor=white:borderw=2:bordercolor=black@0.85:"
                 f"box=1:boxcolor=black@0.35:boxborderw=12:enable='{enable}'"
             )
         else:
             filt = (
                 "drawtext="
-                f"text='{safe_text}':x={int(bbox['x'])}:y={int(bbox['y'])}:"
+                f"{_drawtext_font_option()}text='{safe_text}':x={int(bbox['x'])}:y={int(bbox['y'])}:"
                 f"fontsize={font_size}:fontcolor=white:borderw=2:bordercolor=black@0.85:"
                 f"box=1:boxcolor=black@0.45:boxborderw=8:enable='{enable}'"
             )
@@ -352,8 +350,24 @@ def _escape_subtitle_filter_path(path):
 
 
 def _subtitle_burn_filter(subtitle_path):
-    """Build the ffmpeg video filter used for hard-sub rendering."""
-    return f"subtitles=filename='{_escape_subtitle_filter_path(subtitle_path)}'"
+    """Build the ffmpeg video filter used for hard-sub rendering.
+
+    With SUBTITLE_FONT_FILE set, libass also loads the fonts in that file's directory so
+    the ASS style's family name resolves to the declared file instead of a system font.
+    """
+    filt = f"subtitles=filename='{_escape_subtitle_filter_path(subtitle_path)}'"
+    font_file = CONFIG["subtitle_font_file"]
+    if font_file:
+        fonts_dir = Path(font_file).expanduser().resolve().parent
+        filt += f":fontsdir='{_escape_subtitle_filter_path(fonts_dir)}'"
+    return filt
+
+
+def _drawtext_font_option():
+    font_file = CONFIG["subtitle_font_file"]
+    if not font_file:
+        return ""
+    return f"fontfile='{_escape_subtitle_filter_path(Path(font_file).expanduser().resolve())}':"
 
 
 def _output_downscale_filter(max_h):

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

@@ -3,8 +3,8 @@ name: video-cut
 user-invocable: false
 description: >
  把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节，读取 clip_plan.json 与源视频，
- 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。单独调用且未传 --no-narration-map 时，
- 仍支持旧版单阶段路径，把原片时间的 narration.json 映射为 narration_mapped.json。
+ 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。支持单视频与多视频（sources manifest）拼剪，
+ 本工具不读取、不映射旁白。
  触发词：视频剪辑、剪辑式解说、video cut、clip plan、拼剪。
 ---
 
@@ -15,10 +15,9 @@ description: >
 1. 校验并补全 `clip_plan.json`，写出带 `clip_id`、原片/输出时间与时长的 `clip_plan_validated.json`。
 2. 先避开原片硬切附近的闪帧风险，最后把边界吸附到可靠句末/自然停顿；声音完整性拥有最终优先级。
 3. 拼接选定区间，输出 `edited_source.mp4`。
-4. 编排流程默认到此停止，由 Agent 按真实输出时间线写 `narration.json`。
-5. 旧版单阶段路径还会把原片时间的旁白映射为 `narration_mapped.json`。
+4. 到此停止，由 Agent 按真实输出时间线写 `narration.json`；本工具不读取旁白，也不做原片→输出映射。
 
-相同输入会得到相同输出。缓存仅表示：当 `edited_source.mp4` 新于 `clip_plan.json` 时复用成片。
+相同输入会得到相同输出。`edited_source.mp4.meta.json` 记录标准化 clips、渲染设置和每个源文件的 `size`/`mtime_ns`；三者与当前一致且 `edited_source.mp4` 存在非空才复用，任一不同即重渲染。只有 sidecar 而没有媒体文件不复用。
 
 ## 2. 输入契约
 
@@ -33,8 +32,6 @@ description: >
 - 多视频项目的每个片段还必须填写 `source_id`。
 - `speech_boundary_anchors.json` 与 ASR 时间段由理解阶段提供；Agent 先写大致区间，工具会尝试吸附并把仍在讲话区间内的入/出点作为 blocker 返回。
 
-`work_dir/narration.json` 只在旧版单阶段路径中可选读取；该路径要求旁白使用原片时间。若允许重复或重叠片段，旁白可带 `source_clip_id` 消歧。
-
 ## 3. 剪辑意图契约
 
 工具不会替 Agent 做创作选择。写片段前先完成本节的剪辑意图检查，并让每个区间映射到 `recap_story_plan.json` 的一个 beat。
@@ -47,7 +44,26 @@ beat_id | function | change | POV | preferred moment | 入点 reason | 出点 re
 
 不要因为“事件重要”就保留整段；要保留最能让 change 成立的具体表演、反应、动作或揭示。理解与情绪允许时晚进早出，同时保证台词、动作和技术边界完整。
 
-下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的视频、参数与 `work_dir` 产物。
+对不能删去的问答、反应或动作兑现，先核源证据，再在同一 `clip_plan.json` 登记精确区间：
+
+```json
+{
+  "clips": [{"start": 12, "end": 18}],
+  "required_evidence": {
+    "nodes": [
+      {"id": "refusal", "source": "/media/episode.mp4", "start": 12.25, "end": 14.5, "track": "audio", "content": "对方拒绝请求"},
+      {"id": "response", "source": "/media/episode.mp4", "start": 15, "end": 17.5, "track": "video", "content": "听到拒绝后的反应与决定"}
+    ],
+    "before": [["refusal", "response"]]
+  }
+}
+```
+
+`source` 使用实际源文件绝对路径，`start/end` 是原片秒；多源可另填 `source_id` 消歧。只登记确实需要保留的具体时刻，不将整个 beat 默认锁死。`before` 只登记本片必需的先后关系；无需约束顺序时写 `before: []`。
+
+工具在全部画面/句界吸附后检查每个必保时刻至少有一处完整连续保留、来源和先后；音频节点还检查源音轨是否存在。每次结果出现（包括局部片段）都需满足其声明的前提，不能用后面的完整段替开头缺前提的片段过关。结果写入 `clip_plan_validated.json.qc.required_evidence`；缺段、错序或无效声明会在预检、缓存复用和渲染前阻断，时长放宽选项不会跳过。该结果验证选段保留，实际语义与最终混音仍按审片步骤核对。
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
 
 ## 4. 运行命令
 
@@ -60,20 +76,19 @@ python3 scripts/cut.py <video> --work-dir <work_dir> \
 
 - `clip_plan_validated.json`：标准化片段，包含 `clip_id`、`source_start/end`、`output_start/end` 与 `duration`。
 - `edited_source.mp4`：按计划拼接后的短视频。
-- `narration_mapped.json`：仅旧版单阶段路径生成；编排流程使用 `--no-narration-map`，不会生成该文件。
+- `shot_review.json`：仅 `--review-shots` 开启后生成的实际视频短镜/密集切镜候选；不会更改计划。
 
-编排流程下游把 `edited_source.mp4` 当作视频，把 Agent 按输出时间写的 `narration.json` 当作旁白。
+下游把 `edited_source.mp4` 当作视频，把 Agent 按输出时间写的 `narration.json` 当作旁白。
 
 ## 6. 边界与时间线规则
 
-- 旧版路径中，`clip_plan.json` 与 `narration.json` 都使用原片时间；本工具负责原片 → 输出映射。
-- 编排路径中，`narration.json` 直接使用剪后输出时间，不再映射。
-- 默认禁止重叠或重复原片区间；`--allow-overlap` 开启后，旁白应填写 `source_clip_id`。
+- `clip_plan.json` 使用原片时间；`narration.json` 直接使用剪后输出时间，不存在原片 → 输出的旁白映射。
+- 默认禁止重叠或重复原片区间；`--allow-overlap` 开启后才允许。
 - 片段起点只能位于源头、可靠句末/静音窗，或与上一片段构成无损同源连续连接；片段终点同理。ASR 判定仍在讲话且无法吸附时写入 `unsafe_clip_sentence_boundary` 并阻断。
 - `SCENE_CUT_SNAP` 默认开启：先按画面把 source start 向后、source end 向前吸附到附近硬切，随后句末吸附再做最终修正，避免视觉修正重新制造半句原声。默认范围为 `SCENE_CUT_SNAP_MARGIN=0.5` 秒，检测阈值为 `SCENE_CUT_DETECT_THRESHOLD=0.4`。
 - scene-change score 只提供接点候选，不证明接点自然。先检查短时间窗内是否出现密集候选，再区分来源：原片自带的无关短镜头整段删除；相关但短到像闪帧的镜头通过扩展 IN/OUT 保留完整动作、反应或台词，不用定格/慢放伪造时长；由本次拼接制造的切点则优先移动边界、恢复同源连续运动、合并相邻片段或改用更自然的连接，尽量消除。成片后仍要逐个播放接点前后约 0.5–1 秒；白闪或曝光叠化再结合逐帧亮度定位，不能为了通过视觉检测切断完整台词，也不能用转场遮掩坏接点。
+- 修短残镜时不得仅为压低 scene 分数而对接点附近施加与所属镜头不连续的极端放大或位移；取景复核与修复验证流程见 `references/shot-review.md`。
 - 连续同源片段的无损连接不做句中双侧音频淡出；非连续片段仍在安全停顿内做防爆音淡入淡出。
-- 旧版旁白映射若跨越 clip 边界，不再裁短后继续：`clamped_beats` 永久阻断，`--allow-sparse-cut` 也不能绕过旁白句子完整性。
 
 需要检查短时间频繁切镜时，先用 ffmpeg scene filter 召回候选时间：
 
@@ -83,8 +98,11 @@ ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
 
 `0.35` 是起始阈值，不是质量判据；大幅运动、闪白和叠化都可能误报。把候选映射回原片 shot 与本次拼接边界后，按上面的来源分类处理，并以正常速度播放决定是否保留。
 
+需要精确到实际帧、检查长区间内部残镜并记录所用计划路径时，使用
+`scripts/shot_review.py` 或 `cut.py --review-shots`（有黑边或包装时加 `--roi` / `--shot-roi`）；
+详见 `references/shot-review.md`。
+
 ## 7. 能力边界
 
-- 不重新转写，也不做人物、剧情或情绪等语义理解；scene filter 只承担技术边界候选检测。
-- 不写旁白，也不替 Agent 选择片段；只消费 `clip_plan.json`。
+- 不做语义理解，不写旁白，不替 Agent 选择片段；scene filter 只承担技术边界候选检测。
 - 只做生成 `edited_source.mp4` 所需的剪切、拼接与一次中间编码，不承担字幕包装或最终交付压缩。

package/lib/video-recap/skills/video-cut/references/shot-review.md

@@ -0,0 +1,50 @@
+# 成片内部短镜头与密集切镜召回
+
+`shot_review.py` 是只读检查器，不改剪点、不触发吸附、不重编码视频，也不把短镜头自动删掉。
+EDL 的一个长区间内仍可能藏着 2、12、14 帧反打；因此检查对象是**本轮实际渲染的视频**，不是只看计划里每段有多长。
+
+```bash
+# 默认 --threshold 0.35：
+python3 scripts/shot_review.py edited_source.mp4 --output review/shot_review.json
+# 只有当前 video-cut 的输出与 sidecar 齐全，才额外关联当前剪辑计划：
+python3 scripts/shot_review.py edited_source.mp4 --plan clip_plan_validated.json \
+  --output review/shot_review_planned.json
+# 怀疑漏检时另跑一轮更低阈值做对照；0.08 只是一个更高召回的取值示例，不是规定的第二遍：
+python3 scripts/shot_review.py edited_source.mp4 \
+  --threshold 0.08 --output review/shot_review_sensitive.json
+# 有黑边/包装时，按实测主画窗填入像素坐标，保持阈值不变做对照：
+python3 scripts/shot_review.py packaged.mp4 --roi "$X" "$Y" "$WIDTH" "$HEIGHT" \
+  --output review/shot_review_picture.json
+# 正常 cut 后显式开启；缓存命中也查实际文件；normalize-only 不扫描：
+python3 scripts/cut.py source.mp4 --work-dir work --review-shots
+# 同一画窗/阈值参数也可传给 cut.py --review-shots --shot-roi X Y WIDTH HEIGHT --shot-scene-threshold T
+```
+
+`--roi` 仅裁检测输入，不改视频文件或剪辑计划。坐标采用 FFmpeg 自动转正后的原生像素，
+不是播放器按 SAR 拉伸后的显示尺寸；矩形需完整位于画布内。报告的 `scene_roi` 保存实际
+检测范围，未指定时为 `null`（全画布）。先排除黑边及标题/花字区，再调召回阈值；
+同时保留全画布或更大范围的对照，不能通过缩小范围隐藏问题。画窗随镜头变化时，
+一个固定 ROI 只能覆盖该区域，不能据此宣称已检查所有画面。
+
+## 精度和边界
+
+- `ffprobe` 完整解码收集真实帧 PTS；scene filter 使用整数 PTS 与过滤器 timebase，不用 seek 后的浮点 `pts_time` 反推帧号。
+- 帧号从 0 开始，区间半开 `[start_frame,end_frame)`；首镜、末镜也检查。VFR 同时记录真实 rational PTS 时长，不能用平均 fps 乘秒数。
+- 默认候选规则：镜头不超过 **1 秒**，或 **2 秒内至少 4 个切点**。帧数上限缺省由实测帧钟换算（`round(fps × max_short_seconds)`），不写死某个帧率；需要固定帧数时用 `--max-short-frames` 显式覆盖。参数只控制召回，不是统一剪辑标准。
+- `0.35` 是默认 scene 起始阈值。加黑边、包装占比大、低反差的画面会系统性少报。**某个阈值下零候选不是没有闪帧的证据。** 用一段已知有坏短镜的窗口校准阈值，保留每一轮的报告，不静默换阈值只报告“通过”。降低阈值也可能增加曝光、运动和动效误报。
+- 未提供计划时来源为 `UNKNOWN`。提供计划时先核对计划 clips、渲染设置与 `edited_source.mp4.meta.json` 一致、源文件 `size`/`mtime_ns` 未变、输出存在非空；失配直接失败，不猜“最新版本”。报告 `plan_binding.path` 只记录所用计划路径。
+- 靠近量化后 EDL 拼接点一帧以内仅标 `EDIT_JOIN_CANDIDATE`。内部候选可以标所在已绑定 clip、估计原片秒数，但仍为 `UNKNOWN`；没有独立源片证据，不能认定是原片自带切镜。
+- 未知时码、末帧时长无法覆盖到流末尾、解码失败均阻断扫描。报告先置 `SCANNING`，失败写 `SCAN_FAILED`，不留下旧成功报告冒充本轮结果。仅新路径或可识别为本工具 schema 的旧报告可写；报告路径不能覆盖计划与元数据双方声明的视频/源文件，即使二者已经过期失配。
+
+## 如何处理候选
+
+对每个候选看前后 0.5–1 秒，核对角色表演、完整动作、对白与原片切镜；未实际播放就保留 `NEEDS_DYNAMIC_REVIEW`。
+先对照源画面和取景参数：同一原生镜头中途换 crop/画窗，或曝光闪光，都可能产生切点分数；两个候选间的帧数不一定是一段真实短镜头。
+修复后用同样参数重跑对照：候选消失才算真的修掉；仍被保留的短镜逐个判断，不因“短”就判错。
+判断无关残镜后，在作者计划里删除整个无关镜头或恢复同源连续画面；相关反应可回原片扩完整，不能用定格补长、转场掩盖或只修导出文件。
+
+## 修短残镜时的取景复核
+
+修短残镜时，同时核对原片镜头变化与输出 `crop/window` 变化。不得仅为压低 scene 分数，对接点前后少量帧施加与所属镜头不连续的极端放大或位移，造成关键表情、动作被裁或清晰度明显下降。先在原片自然切点上分别确定相邻镜头各自连续、清晰、主体完整的取景；不同镜头不要求景别或裁幅一致，但尺度变化、主体位置及视线/运动方向须在正常速度下复核。保存修复前后相同输出帧号的邻帧对照，再核声音、字幕、总帧数与播放速度。候选数量或 scene 分数下降，只说明检测结果改变，不证明接点已经修复；没有正常速度观看能力时保留未检查状态。
+
+`NO_CANDIDATES` 仅表示该阈值下没有短镜/密集切镜候选；不代表故事、听感、动态观感或发布授权通过。报告始终保留 `normal_speed_review=NOT_CHECKED`，不会写入已有 `clip_plan_validated.json['qc']`。

package/lib/video-recap/skills/video-cut/scripts/cut.py

@@ -3,30 +3,15 @@
 
 from cut_cli import main
 from cut_contract import (
-    cut_plan_fingerprint,
     edited_source_render_cache_payload,
-    edited_source_render_fingerprint,
-    file_fingerprint,
-    load_clip_plan,
     normalize_clip_plan,
     normalize_multi_source_clip_plan,
-    normalize_sources_manifest,
     parse_duration_seconds,
     should_reuse_edited_source,
-    value_fingerprint,
-)
-from cut_render import (
-    build_edited_source_video,
-    update_delivery_qc,
-    write_cut_delivery_qc,
 )
+from cut_render import build_edited_source_video
 from media_geometry import VideoGeometry
-from narration_mapping import (
-    lint_mapped_narration,
-    map_narration_to_clips,
-    source_time_to_output_time,
-    update_cut_qc,
-)
+from narration_mapping import update_cut_qc
 from sentence_boundaries import (
     enforce_clip_sentence_boundaries,
     snap_clip_ends_to_lines,
@@ -38,29 +23,18 @@ from sentence_boundaries import (
 __all__ = [
     "VideoGeometry",
     "build_edited_source_video",
-    "cut_plan_fingerprint",
     "edited_source_render_cache_payload",
-    "edited_source_render_fingerprint",
     "enforce_clip_sentence_boundaries",
-    "file_fingerprint",
-    "lint_mapped_narration",
-    "load_clip_plan",
     "main",
-    "map_narration_to_clips",
     "normalize_clip_plan",
     "normalize_multi_source_clip_plan",
-    "normalize_sources_manifest",
     "parse_duration_seconds",
     "should_reuse_edited_source",
     "snap_clip_ends_to_lines",
     "snap_clip_starts_to_lines",
     "snap_clips_off_shot_changes",
     "snap_multi_source_clips",
-    "source_time_to_output_time",
     "update_cut_qc",
-    "update_delivery_qc",
-    "value_fingerprint",
-    "write_cut_delivery_qc",
 ]
 
 if __name__ == "__main__":

package/lib/video-recap/skills/video-cut/scripts/cut_cli.py

@@ -1,11 +1,13 @@
 """Command-line orchestration for the video-cut skill."""
 
 import json
+import math
 
 
 from pathlib import Path
 
 from lib import CONFIG, get_video_duration, log
+import shot_review
 
 from cut_contract import (
     _write_edited_source_meta,
@@ -14,19 +16,15 @@ from cut_contract import (
     normalize_multi_source_clip_plan,
     parse_duration_seconds,
     should_reuse_edited_source,
-    value_fingerprint,
 )
 from cut_render import (
     build_edited_source_video,
     update_delivery_qc,
     write_cut_delivery_qc,
 )
-from media_geometry import _select_output_geometry
-from narration_mapping import (
-    lint_mapped_narration,
-    map_narration_to_clips,
-    update_cut_qc,
-)
+from media_geometry import _has_audio_stream, _select_output_geometry
+from narrative_selection import check_required_evidence
+from narration_mapping import update_cut_qc
 from sentence_boundaries import (
     _combine_boundary_windows,
     _load_sentence_boundary_windows,
@@ -44,13 +42,13 @@ def main():
     import argparse
 
     parser = argparse.ArgumentParser(
-        description="video-cut: build an edited source video from an agent clip plan and map narration onto the cut timeline."
+        description="video-cut: build edited_source.mp4 from an agent clip plan; narration is authored afterwards on the output timeline."
     )
     parser.add_argument("video", help="source video path")
     parser.add_argument(
         "--work-dir",
         required=True,
-        help="dir holding clip_plan.json (and optionally narration.json)",
+        help="dir holding clip_plan.json",
     )
     parser.add_argument(
         "--clip-plan",
@@ -62,11 +60,6 @@ def main():
         default=None,
         help="multi-source manifest json mapping source_id values to source media",
     )
-    parser.add_argument(
-        "--narration",
-        default=None,
-        help="narration json to map (default: <work-dir>/narration.json)",
-    )
     parser.add_argument(
         "--target-duration",
         default=None,
@@ -86,19 +79,20 @@ def main():
     parser.add_argument(
         "--normalize-only",
         action="store_true",
-        help="only normalize the clip plan -> clip_plan_validated.json (no render/map); "
-        "lets validate lint the SAME padded/pruned plan the mapper uses",
+        help="only normalize the clip plan -> clip_plan_validated.json (no render); "
+        "lets validate lint the SAME padded/pruned plan the render uses",
     )
     parser.add_argument(
-        "--no-narration-map",
-        action="store_true",
-        help="render edited_source.mp4 but do NOT map narration.json onto the cut "
-        "(cut-first/narrate-second: narration is authored in OUTPUT time, no mapping)",
+        "--review-shots", action="store_true",
+        help="scan actual rendered/reused video for internal short-shot and dense-cut candidates; never repair",
     )
     parser.add_argument(
-        "--allow-sparse-cut",
-        action="store_true",
-        help="do not block on heavy narration drop / sparse output (e.g. an intentional montage)",
+        "--shot-scene-threshold", type=float, default=None,
+        help="explicit scene recall threshold for --review-shots (default 0.35; not an acceptance criterion)",
+    )
+    parser.add_argument(
+        "--shot-roi", nargs=4, type=int, metavar=("X", "Y", "WIDTH", "HEIGHT"),
+        help="scan only this pixel rectangle with --review-shots; never crop the rendered video",
     )
     parser.add_argument(
         "--allow-duration-drift",
@@ -106,6 +100,15 @@ def main():
         help="do not block when validated clip duration is far from --target-duration",
     )
     args = parser.parse_args()
+    if args.shot_scene_threshold is not None and (
+        not args.review_shots or not math.isfinite(args.shot_scene_threshold)
+        or not 0 <= args.shot_scene_threshold <= 1
+    ):
+        parser.error("--shot-scene-threshold requires --review-shots and a finite value in [0,1]")
+    if args.shot_roi is not None and (
+        not args.review_shots or min(args.shot_roi[:2]) < 0 or min(args.shot_roi[2:]) <= 0
+    ):
+        parser.error("--shot-roi requires --review-shots, nonnegative X/Y and positive WIDTH/HEIGHT")
 
     # CLIP_PADDING is declared in every skill's CONFIG, but video-cut is the only place that
     # implements padding — and it used to read the CLI flag alone, so setting the env var did
@@ -201,7 +204,6 @@ def main():
             start_max_trim=CONFIG["clip_start_snap_max_trim"],
         )
 
-    validated_plan["raw_plan_fingerprint"] = value_fingerprint(raw_plan)
     validated_plan.setdefault("qc", {})["join_fade_ms"] = round(
         CONFIG["clip_join_audio_fade_ms"], 3
     )
@@ -214,17 +216,30 @@ def main():
     _, _, _, geometry_qc = _select_output_geometry(source_paths, validated_plan["clips"])
     validated_plan["qc"]["output_geometry"] = geometry_qc
     validated_plan["qc"]["output_geometry_reason"] = geometry_qc["reason"]
-    allow_duration_drift = bool(args.allow_duration_drift or args.allow_sparse_cut)
-    drift_source = (
-        "--allow-duration-drift"
-        if args.allow_duration_drift
-        else ("--allow-sparse-cut" if args.allow_sparse_cut else None)
-    )
     update_cut_qc(
         validated_plan,
-        allow_duration_drift=allow_duration_drift,
-        duration_drift_allowed_by=drift_source,
+        allow_duration_drift=bool(args.allow_duration_drift),
+        duration_drift_allowed_by="--allow-duration-drift" if args.allow_duration_drift else None,
     )
+    if isinstance(raw_plan, dict) and 'required_evidence' in raw_plan:
+        # Re-evaluate the final snapped ranges even when the media cache can be reused.
+        # A prior rendered receipt must not survive a failed revision preflight.
+        (work_dir / 'cut_delivery_qc.json').unlink(missing_ok=True)
+        contract = raw_plan['required_evidence']
+        plan_sources = {str(Path(path).resolve()): path for path in source_paths}
+        source_audio = {}
+
+        def has_source_audio(source):
+            # Probed lazily, once per source, only for validated audio nodes.
+            if source not in source_audio:
+                source_audio[source] = source in plan_sources and _has_audio_stream(plan_sources[source])
+            return source_audio[source]
+
+        report = check_required_evidence(contract, validated_plan, input_video=args.video,
+                                         source_audio=has_source_audio)
+        validated_plan['qc']['required_evidence'] = {**report, 'contract': contract}
+        if report['selection_status'] == 'BLOCK':
+            validated_plan['qc'].setdefault('blocking', []).extend(report['findings'])
     update_delivery_qc(
         validated_plan,
         source_paths=source_paths,
@@ -235,7 +250,7 @@ def main():
     )
     if validated_plan["qc"].get("blocking"):
         raise SystemExit(
-            "clip_plan QC blocking: fix unsafe sentence boundaries or target-duration drift. "
+            "clip_plan QC blocking: fix required source evidence, unsafe sentence boundaries or target-duration drift. "
             "Only duration drift can be explicitly accepted with --allow-duration-drift; "
             "sentence truncation is never allowed. See clip_plan_validated.json['qc']."
         )
@@ -277,36 +292,17 @@ def main():
             json.dumps(validated_plan, ensure_ascii=False, indent=2), encoding="utf-8"
         )
 
-    narration_path = (
-        Path(args.narration) if args.narration else work_dir / "narration.json"
-    )
-    if narration_path.exists() and not args.no_narration_map:
-        narration = json.loads(narration_path.read_text(encoding="utf-8"))
-        mapped = map_narration_to_clips(narration, validated_plan)
-        if not mapped:
-            raise SystemExit("narration 没有落入 clip_plan 片段内的有效解说")
-        (work_dir / "narration_mapped.json").write_text(
-            json.dumps(mapped, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
-        log(f"映射解说 {len(mapped)} 段 → narration_mapped.json")
-        report = lint_mapped_narration(
-            mapped, len(narration), validated_plan["total_duration"]
+    if args.review_shots:
+        review_options = {"plan_path": work_dir / "clip_plan_validated.json"}
+        if args.shot_scene_threshold is not None:
+            review_options["threshold"] = args.shot_scene_threshold
+        if args.shot_roi is not None:
+            review_options["roi"] = args.shot_roi
+        shot_review.write_scan(
+            edited_source_path, work_dir / "shot_review.json",
+            **review_options,
         )
-        (work_dir / "narration_mapped_lint.json").write_text(
-            json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
-        for w in report["warnings"]:
-            log(f"  ⚠️ 剪后解说同步: {w['message']} [{w['code']}]")
-        if report["clamped_count"]:
-            raise SystemExit(
-                "剪后解说有句子被 clip 边界裁断。移动 clip_plan 边界或重写整句后重跑；"
-                "--allow-sparse-cut 不能跳过语句完整性门禁。详见 narration_mapped_lint.json"
-            )
-        if report["blocking"] and not args.allow_sparse_cut:
-            raise SystemExit(
-                "剪后解说与保留片段对不上：丢弃过多或成片过稀疏。改 narration.json / clip_plan.json "
-                "让解说落在保留片段内后重跑，或加 --allow-sparse-cut 接受当前映射。详见 narration_mapped_lint.json"
-            )
+
     log(
         f"剪辑模式: {len(validated_plan['clips'])} 个片段 → {validated_plan['total_duration']:.1f}s"
     )