@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/video-recap-production/upstream/skills/video-assemble/scripts/visual_render.py

@@ -0,0 +1,448 @@
+"""Visual overlays, subtitle layout QC, masking, and video filter helpers."""
+
+import json
+import re
+from pathlib import Path
+
+from assemble_constants import (
+    SUBTITLE_STYLE_REF_H,
+    VISUAL_OVERLAYS,
+    VISUAL_QC,
+    _SUPPORTED_VISUAL_OVERLAY_TYPES,
+)
+from audio_automation import coalesce_duck_windows
+from audio_mix import _seg_place_window
+from lib import CONFIG
+from source_subtitles import (
+    _combined_subtitle_entries,
+    _original_gap_subtitle_entries,
+    _source_subtitle_mask_policy,
+)
+from subtitles.core import (
+    _measured_subtitle_band,
+    _measured_subtitle_safe_area,
+    _normalize_subtitle_text,
+    _style_for_measured_subtitle_band,
+    _subtitle_style_config,
+)
+
+_OVERFLOW_KINDS = {
+    "max_lines_exceeded": "line_count",
+    "safe_width_exceeded": "line_width",
+    "safe_height_exceeded": "safe_area",
+}
+
+
+def _visual_text_units(text):
+    """Approximate visual text width in em units for deterministic geometry QC."""
+    units = 0.0
+    for ch in text:
+        if ch.isspace():
+            units += 0.35
+        elif ord(ch) < 128:
+            units += 0.56
+        else:
+            units += 1.0
+    return units
+
+
+def _subtitle_layout_qc(entries, style, safe_area=None):
+    """Machine-check subtitle safe-area/multiline/overflow facts for visual_qc.json."""
+    play_x = int(style["play_res_x"])
+    play_y = int(style["play_res_y"])
+    margin_l = int(style["margin_l"])
+    margin_r = int(style["margin_r"])
+    margin_v = int(style["margin_v"])
+    font_size = float(style["font_size"])
+    max_lines = CONFIG["subtitle_max_lines"]
+    if safe_area is None:
+        safe_area = {
+            "x": margin_l,
+            "y": margin_v,
+            "width": max(1, play_x - margin_l - margin_r),
+            "height": max(1, play_y - 2 * margin_v),
+            "bottom_margin": margin_v,
+        }
+    usable_w = float(safe_area["width"])
+    line_h = font_size * 1.25
+    overflow_entries = []
+    violations = []
+    multi_line_entries = []
+    max_observed_lines = 0
+    entry_facts = []
+    for i, entry in enumerate(entries):
+        raw_text = _normalize_subtitle_text(entry["text"])
+        lines = [ln for ln in re.split(r"(?:\\N|\n)+", raw_text) if ln != ""] or [""]
+        line_count = len(lines)
+        max_observed_lines = max(max_observed_lines, line_count)
+        max_w = max(_visual_text_units(line) * font_size for line in lines)
+        band_h = line_count * line_h + float(style["outline"]) * 2 + float(style["shadow"])
+        overflow_reasons = []
+        if line_count > max_lines:
+            overflow_reasons.append("max_lines_exceeded")
+        if max_w > usable_w + 1e-6:
+            overflow_reasons.append("safe_width_exceeded")
+        if band_h > safe_area["height"] + 1e-6:
+            overflow_reasons.append("safe_height_exceeded")
+        fact = {
+            "index": i,
+            "start": round(float(entry["start"]), 3),
+            "end": round(float(entry["end"]), 3),
+            "line_count": line_count,
+            "max_line_width": round(max_w, 2),
+            "safe_width": round(usable_w, 2),
+            "band_height": round(band_h, 2),
+            "overflow": bool(overflow_reasons),
+            "overflow_reasons": overflow_reasons,
+        }
+        entry_facts.append(fact)
+        if line_count > 1:
+            multi_line_entries.append(i)
+        if overflow_reasons:
+            overflow_entries.append(fact)
+            violations.extend(
+                {"index": i, "kind": _OVERFLOW_KINDS[reason], "reason": reason}
+                for reason in overflow_reasons
+            )
+    return {
+        "enabled": CONFIG["burn_subtitles"],
+        "renderer": "ass" if CONFIG["burn_subtitles"] else "sidecar_srt",
+        "style": {
+            "font_size": int(font_size),
+            "max_chars": int(style["max_chars"]),
+            "max_lines": max_lines,
+            "play_res_x": play_x,
+            "play_res_y": play_y,
+            "alignment": int(style["alignment"]),
+            "margin_l": margin_l,
+            "margin_r": margin_r,
+            "margin_v": margin_v,
+        },
+        "safe_area": safe_area,
+        "entries": len(entry_facts),
+        "max_lines": max_observed_lines,
+        "max_observed_lines": max_observed_lines,
+        "multi_line": bool(multi_line_entries),
+        "multi_line_entries": multi_line_entries,
+        "overflow": bool(overflow_entries),
+        "overflow_entries": overflow_entries,
+        "violations": violations,
+        "entry_facts": entry_facts,
+    }
+
+
+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)}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"{path}: JSON 无效") from exc
+    if (
+        not isinstance(data, dict)
+        or type(data.get("schema_version")) is not int
+        or data["schema_version"] != 1
+        or not isinstance(data.get("overlays"), list)
+        or not all(isinstance(item, dict) for item in data["overlays"])
+    ):
+        raise ValueError(f"{path}: visual_overlays.json schema 无效")
+    source = {
+        "present": True,
+        "path": str(path),
+        "schema_version": 1,
+    }
+    return data["overlays"], source
+
+
+def _escape_drawtext_text(text):
+    return (
+        text
+        .replace("\\", "\\\\")
+        .replace(":", "\\:")
+        .replace("'", "\\'")
+        .replace("%", "\\%")
+        .replace("\n", "\\n")
+    )
+
+
+def _overlay_time_window(overlay, video_duration):
+    start = float(overlay.get("start", 0.0))
+    end = float(overlay.get("end", video_duration))
+    return start, max(start, end)
+
+
+def _overlay_bbox(overlay, canvas, *, default_y):
+    width = canvas["width"]
+    height = canvas["height"]
+    text = overlay["text"]
+    font_size = int(overlay.get("font_size", max(18, round(height * 0.045))))
+    lines = [ln for ln in text.splitlines() if ln.strip()] or [text]
+    max_w = max(_visual_text_units(ln) * font_size for ln in lines)
+    text_h = len(lines) * font_size * 1.25
+    if overlay["type"] == "top_title":
+        x = max(0.0, (width - max_w) / 2)
+        y = float(overlay.get("y", default_y))
+    else:
+        # Fractions of the canvas in [0, 1] are normalized coordinates; larger values are pixels.
+        x = float(overlay.get("x", 0.08))
+        y = float(overlay.get("y", 0.25))
+        if 0.0 <= x <= 1.0:
+            x *= width
+        if 0.0 <= y <= 1.0:
+            y *= height
+    return {
+        "x": round(x, 2),
+        "y": round(y, 2),
+        "width": round(max_w, 2),
+        "height": round(text_h, 2),
+        "font_size": font_size,
+        "line_count": len(lines),
+        "overflow": x < 0 or y < 0 or x + max_w > width or y + text_h > height,
+    }
+
+
+def _visual_overlay_filters(work_dir, canvas, video_duration):
+    """Render the first-release canonical visual_overlays.json contract.
+
+    Only two semantic renderers are supported: top_title and inline_label_or_callout.
+    Unsupported types are QC-blocking and deliberately do not silently render.
+    """
+    overlays, source = _load_visual_overlays(work_dir)
+    default_top_y = max(24, round(canvas["height"] * 0.05))
+    filters = []
+    facts = []
+    unsupported = []
+    overflow = []
+    for idx, overlay in enumerate(overlays):
+        typ = overlay.get("type")
+        text = overlay.get("text", "").strip()
+        if typ not in _SUPPORTED_VISUAL_OVERLAY_TYPES:
+            unsupported.append({"index": idx, "type": typ, "reason": "unsupported_overlay_type"})
+            continue
+        if not text:
+            unsupported.append({"index": idx, "type": typ, "reason": "missing_text"})
+            continue
+        start, end = _overlay_time_window(overlay, video_duration)
+        bbox = _overlay_bbox(overlay, canvas, default_y=default_top_y)
+        if bbox["overflow"]:
+            overflow.append({"index": idx, "type": typ, "bbox": bbox})
+        font_size = bbox["font_size"]
+        safe_text = _escape_drawtext_text(text)
+        enable = f"between(t\\,{start:.3f}\\,{end:.3f})"
+        if typ == "top_title":
+            filt = (
+                "drawtext="
+                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"{_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}'"
+            )
+        filters.append(filt)
+        facts.append({
+            "index": idx,
+            "type": typ,
+            "text_chars": len(text),
+            "start": round(start, 3),
+            "end": round(end, 3),
+            "bbox": bbox,
+        })
+    qc = {
+        "source": source,
+        "supported_types": sorted(_SUPPORTED_VISUAL_OVERLAY_TYPES),
+        "present": source["present"],
+        "count": len(overlays),
+        "rendered": len(facts),
+        "facts": facts,
+        "unsupported": unsupported,
+        "overflow": overflow,
+    }
+    return filters, qc
+
+
+def _build_visual_qc(tts_segments, work_dir, video_duration, canvas, *, overlay_qc=None, mask_filter=None):
+    entries = _combined_subtitle_entries(tts_segments, work_dir, video_duration)
+    style = _style_for_measured_subtitle_band(_subtitle_style_config(canvas), canvas)
+    subtitle_layout = _subtitle_layout_qc(
+        entries, style, safe_area=_measured_subtitle_safe_area(style, canvas)
+    )
+    mask = _source_subtitle_mask_policy(work_dir)
+    mask.update({
+        "ratio": min(0.5, CONFIG["source_subtitle_mask_ratio"]) if mask["active"] else None,
+        "filter": "drawbox" if mask_filter else None,
+        "opacity": CONFIG["subtitle_mask_opacity"],
+        "timing": CONFIG["source_subtitle_mask_timing"],
+        "subtitle_y_top": CONFIG["subtitle_y_top"],
+        "subtitle_y_bot": CONFIG["subtitle_y_bot"],
+    })
+    if overlay_qc is None:
+        overlay_qc = _visual_overlay_filters(work_dir, canvas, video_duration)[1]
+    blocking_codes = []
+    if mask["blocking"]:
+        blocking_codes.append("mask_policy_not_explicit")
+    if subtitle_layout["overflow"]:
+        blocking_codes.append("subtitle_overflow")
+    if overlay_qc["unsupported"]:
+        blocking_codes.append("unsupported_visual_overlay")
+    if overlay_qc["overflow"]:
+        blocking_codes.append("visual_overlay_overflow")
+    return {
+        "schema_version": 1,
+        "artifact": VISUAL_QC,
+        "verdict": "FAIL" if blocking_codes else "PASS",
+        "blocking": bool(blocking_codes),
+        "blocking_codes": blocking_codes,
+        "geometry": {
+            "canvas": {
+                "width": canvas["width"],
+                "height": canvas["height"],
+                "fps": canvas["fps"],
+            },
+            "storage": {
+                "width": canvas["storage_width"],
+                "height": canvas["storage_height"],
+            },
+            "rotation": canvas["rotation"],
+            "sample_aspect_ratio": canvas["sample_aspect_ratio"],
+            "display_aspect_ratio": canvas["display_aspect_ratio"],
+        },
+        "subtitles": subtitle_layout,
+        "mask": mask,
+        "overlays": overlay_qc,
+        "summary": {
+            "subtitle_entries": subtitle_layout["entries"],
+            "subtitle_overflow": subtitle_layout["overflow"],
+            "subtitle_multi_line": subtitle_layout["multi_line"],
+            "mask_policy": mask["policy"],
+            "mask_active": mask["active"],
+            "overlay_rendered": overlay_qc["rendered"],
+            "overlay_unsupported": len(overlay_qc["unsupported"]),
+        },
+    }
+
+
+def _write_visual_qc(work_dir, qc):
+    path = Path(work_dir) / VISUAL_QC
+    path.write_text(json.dumps(qc, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path
+
+
+def _escape_subtitle_filter_path(path):
+    """Escape a path for ffmpeg subtitle/ass video filter arguments."""
+    text = str(path).replace("\\", "/")
+    for raw, escaped in (
+        ("\\", "\\\\"),
+        (":", "\\:"),
+        ("'", "\\'"),
+        (",", "\\,"),
+        ("[", "\\["),
+        ("]", "\\]"),
+    ):
+        text = text.replace(raw, escaped)
+    return text
+
+
+def _subtitle_burn_filter(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):
+    """Lanczos downscale that forces BOTH output dimensions even (libx264/yuv420p need it).
+
+    -2 keeps the aspect ratio with an even width; 2*trunc(min(ih,H)/2) caps the height at H
+    yet forces it even, so an odd OUTPUT_MAX_HEIGHT (e.g. 721) cannot produce an odd height
+    that makes libx264 abort with an empty output file. 'min(ih,H)' only ever shrinks.
+    """
+    return f"scale=-2:'2*trunc(min(ih,{max_h})/2)':flags=lanczos"
+
+
+def _source_subtitle_mask_filter(canvas, work_dir, tts_segments, video_duration):
+    """Return source-subtitle drawbox filters, optionally scoped to narration windows.
+
+    Many source videos (e.g. 庆余年) ship hardcoded subtitles; without this the recap
+    shows the original subs AND our narration subs stacked. Once masking is explicitly enabled,
+    the enhanced default is a measured, translucent narration-only band; opacity and timing
+    remain configurable.
+    """
+    policy = _source_subtitle_mask_policy(work_dir)
+    if not policy["active"]:
+        return None
+    opacity = CONFIG["subtitle_mask_opacity"]
+    timing = CONFIG["source_subtitle_mask_timing"]
+    if timing not in {"all", "narration"}:
+        raise ValueError(f"SOURCE_SUBTITLE_MASK_TIMING 必须是 all 或 narration，当前为 {timing!r}")
+
+    band = _measured_subtitle_band(canvas)
+    if band is not None:
+        y_top, y_bot = band
+        padding = CONFIG["subtitle_mask_padding"]
+        mask_top = max(0, y_top - padding)
+        mask_bot = min(canvas["height"], y_bot + padding)
+        geometry = f"x=0:y={mask_top}:w=iw:h={mask_bot - mask_top}"
+    else:
+        # Our subtitle cues are one line. Keep the mask large enough for that line and its
+        # margin, but never regress to the old two-line bar that hid ~23% of the image.
+        style = _subtitle_style_config(canvas)
+        play_res_y = float(style["play_res_y"])
+        line_h = float(style["font_size"]) * 1.25
+        pad = 10.0 * play_res_y / SUBTITLE_STYLE_REF_H
+        sub_band = (float(style["margin_v"]) + line_h + pad) / play_res_y
+        ratio = min(0.5, max(CONFIG["source_subtitle_mask_ratio"], sub_band))
+        geometry = f"x=0:y=ih-ih*{ratio:.3f}:w=iw:h=ih*{ratio:.3f}"
+
+    base = f"drawbox={geometry}:color=black@{opacity:.2f}:t=fill"
+    filters = []
+    if opacity > 0:
+        if timing == "all":
+            filters.append(base)
+        else:
+            windows = [
+                (start, end, 0.0)
+                for start, end in map(_seg_place_window, tts_segments)
+                if end > start
+            ]
+            # Avoid overlapping drawboxes: stacking two 60%-black masks would darken the
+            # overlap to 84%. Coalescing also keeps long filter chains smaller.
+            filters.extend(
+                f"{base}:enable='between(t,{start:.3f},{end:.3f})'"
+                for start, end, _ in coalesce_duck_windows(windows, bridge=0.001)
+            )
+
+    # A translucent mask deliberately leaves the source glyphs visible. Whenever we burn a
+    # replacement original-dialogue subtitle into a gap, cover that exact window opaquely first;
+    # otherwise the source hard-sub and replacement text are stacked on top of each other.
+    if not (timing == "all" and opacity >= 1.0 - 1e-9):
+        replacement_windows = [
+            (entry["start"], entry["end"], 0.0)
+            for entry in _original_gap_subtitle_entries(tts_segments, work_dir, video_duration)
+        ]
+        opaque = f"drawbox={geometry}:color=black@1.00:t=fill"
+        filters.extend(
+            f"{opaque}:enable='between(t,{start:.3f},{end:.3f})'"
+            for start, end, _ in coalesce_duck_windows(replacement_windows, bridge=0.001)
+        )
+    return ",".join(filters) if filters else None

package/resources/skills/video-recap-production/upstream/skills/video-cut/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: video-cut
+user-invocable: false
+description: >
+ 把长视频按 Agent 选择的原片区间剪成短片。作为两阶段创作流程中的剪辑环节，读取 clip_plan.json 与源视频，
+ 输出 edited_source.mp4；随后 Agent 按输出时间线写 narration.json。支持单视频与多视频（sources manifest）拼剪，
+ 本工具不读取、不映射旁白。
+ 触发词：视频剪辑、剪辑式解说、video cut、clip plan、拼剪。
+---
+
+## 1. 定位
+
+本技能只执行 Agent 已经做出的剪辑决定：
+
+1. 校验并补全 `clip_plan.json`，写出带 `clip_id`、原片/输出时间与时长的 `clip_plan_validated.json`。
+2. 先避开原片硬切附近的闪帧风险，最后把边界吸附到可靠句末/自然停顿；声音完整性拥有最终优先级。
+3. 拼接选定区间，输出 `edited_source.mp4`。
+4. 到此停止，由 Agent 按真实输出时间线写 `narration.json`；本工具不读取旁白，也不做原片→输出映射。
+
+相同输入会得到相同输出。`edited_source.mp4.meta.json` 记录标准化 clips、渲染设置和每个源文件的 `size`/`mtime_ns`；三者与当前一致且 `edited_source.mp4` 存在非空才复用，任一不同即重渲染。只有 sidecar 而没有媒体文件不复用。
+
+## 2. 输入契约
+
+`work_dir/clip_plan.json` 可以是数组，也可以是 `{"clips": [...]}`：
+
+```json
+{"start": 12.0, "end": 28.5, "reason": "b02 | turn | power: A→B | POV=女主 | 保留反应 | 入点=问题落下 | 出点=沉默结束"}
+```
+
+- `start` / `end` 是原片秒数；也接受 `source_start` / `source_end` 或 `in` / `out`。
+- 顶层可选 `target_duration`，例如 `"10m"`。
+- 多视频项目的每个片段还必须填写 `source_id`。
+- `speech_boundary_anchors.json` 与 ASR 时间段由理解阶段提供；Agent 先写大致区间，工具会尝试吸附并把仍在讲话区间内的入/出点作为 blocker 返回。
+
+## 3. 剪辑意图契约
+
+工具不会替 Agent 做创作选择。写片段前先完成本节的剪辑意图检查，并让每个区间映射到 `recap_story_plan.json` 的一个 beat。
+
+使用现有自由文本 `reason` 保存简洁决定：
+
+```text
+beat_id | function | change | POV | preferred moment | 入点 reason | 出点 reason
+```
+
+不要因为“事件重要”就保留整段；要保留最能让 change 成立的具体表演、反应、动作或揭示。理解与情绪允许时晚进早出，同时保证台词、动作和技术边界完整。
+
+对不能删去的问答、反应或动作兑现，先核源证据，再在同一 `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. 运行命令
+
+```bash
+python3 scripts/cut.py <video> --work-dir <work_dir> \
+  [--target-duration 10m] [--clip-padding 0] [--allow-overlap]
+```
+
+## 5. 输出契约
+
+- `clip_plan_validated.json`：标准化片段，包含 `clip_id`、`source_start/end`、`output_start/end` 与 `duration`。
+- `edited_source.mp4`：按计划拼接后的短视频。
+- `shot_review.json`：仅 `--review-shots` 开启后生成的实际视频短镜/密集切镜候选；不会更改计划。
+
+下游把 `edited_source.mp4` 当作视频，把 Agent 按输出时间写的 `narration.json` 当作旁白。
+
+## 6. 边界与时间线规则
+
+- `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`。
+- 连续同源片段的无损连接不做句中双侧音频淡出；非连续片段仍在安全停顿内做防爆音淡入淡出。
+
+需要检查短时间频繁切镜时，先用 ffmpeg scene filter 召回候选时间：
+
+```bash
+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. 能力边界
+
+- 不做语义理解，不写旁白，不替 Agent 选择片段；scene filter 只承担技术边界候选检测。
+- 只做生成 `edited_source.mp4` 所需的剪切、拼接与一次中间编码，不承担字幕包装或最终交付压缩。

package/resources/skills/video-recap-production/upstream/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/resources/skills/video-recap-production/upstream/skills/video-cut/scripts/cut.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""Public API and CLI entrypoint for the self-contained video-cut skill."""
+
+from cut_cli import main
+from cut_contract import (
+    edited_source_render_cache_payload,
+    normalize_clip_plan,
+    normalize_multi_source_clip_plan,
+    parse_duration_seconds,
+    should_reuse_edited_source,
+)
+from cut_render import build_edited_source_video
+from media_geometry import VideoGeometry
+from narration_mapping import update_cut_qc
+from sentence_boundaries import (
+    enforce_clip_sentence_boundaries,
+    snap_clip_ends_to_lines,
+    snap_clip_starts_to_lines,
+    snap_clips_off_shot_changes,
+    snap_multi_source_clips,
+)
+
+__all__ = [
+    "VideoGeometry",
+    "build_edited_source_video",
+    "edited_source_render_cache_payload",
+    "enforce_clip_sentence_boundaries",
+    "main",
+    "normalize_clip_plan",
+    "normalize_multi_source_clip_plan",
+    "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",
+    "update_cut_qc",
+]
+
+if __name__ == "__main__":
+    main()