@oh-story/dsh 0.1.4 → 0.1.6

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

@@ -0,0 +1,512 @@
+"""Visual overlays, subtitle layout QC, masking, and video filter helpers."""
+
+import json
+import re
+from pathlib import Path
+
+from artifacts import _artifact_fingerprint
+from assemble_constants import (
+    SUBTITLE_STYLE_REF_H,
+    VISUAL_OVERLAYS,
+    VISUAL_QC,
+    _SUPPORTED_VISUAL_OVERLAY_TYPES,
+    _VISUAL_DELIVERY_FORBIDDEN_KEYS,
+)
+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 subtitle_core import (
+    _measured_subtitle_safe_area,
+    _normalize_subtitle_text,
+    _style_for_measured_subtitle_band,
+    _subtitle_style_config,
+    _validate_measured_subtitle_coordinate_domain,
+)
+
+def _visual_text_units(text):
+    """Approximate visual text width in em units for deterministic geometry QC."""
+    units = 0.0
+    for ch in str(text or ""):
+        if ch.isspace():
+            units += 0.35
+        elif ord(ch) < 128:
+            units += 0.56
+        else:
+            units += 1.0
+    return units
+
+
+def _subtitle_layout_qc(entries, canvas=None, style=None, safe_area=None):
+    """Machine-check subtitle safe-area/multiline/overflow facts for visual_qc.json."""
+    canvas = canvas or {}
+    style = style or _subtitle_style_config(canvas)
+    play_x = int(style.get("play_res_x") or canvas.get("width") or 1280)
+    play_y = int(style.get("play_res_y") or canvas.get("height") or 720)
+    margin_l = int(style.get("margin_l") or 0)
+    margin_r = int(style.get("margin_r") or 0)
+    margin_v = int(style.get("margin_v") or 0)
+    font_size = float(style.get("font_size") or 1)
+    max_lines = int(CONFIG.get("subtitle_max_lines", 2) or 2)
+    usable_w = max(1.0, play_x - margin_l - margin_r)
+    if safe_area:
+        safe_area = {
+            "x": int(safe_area.get("x", margin_l) or 0),
+            "y": int(safe_area.get("y", margin_v) or 0),
+            "width": int(safe_area.get("width", safe_area.get("w", play_x - margin_l - margin_r)) or 1),
+            "height": int(safe_area.get("height", safe_area.get("h", play_y - 2 * margin_v)) or 1),
+            "bottom_margin": margin_v,
+        }
+        usable_w = max(1.0, float(safe_area["width"]))
+    else:
+        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,
+        }
+    line_h = font_size * 1.25
+    overflow_entries = []
+    violations = []
+    multi_line_entries = []
+    max_observed_lines = 0
+    entry_facts = []
+    for i, entry in enumerate(entries or []):
+        raw_text = _normalize_subtitle_text(entry.get("text", ""))
+        lines = [ln for ln in re.split(r"(?:\\N|\n)+", raw_text) if ln != ""]
+        if not lines:
+            lines = [""]
+        line_count = len(lines)
+        max_observed_lines = max(max_observed_lines, line_count)
+        widths = [_visual_text_units(line) * font_size for line in lines]
+        max_w = max(widths or [0.0])
+        band_h = line_count * line_h + float(style.get("outline", 0)) * 2 + float(style.get("shadow", 0))
+        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.get("start", 0.0) or 0.0), 3),
+            "end": round(float(entry.get("end", 0.0) or 0.0), 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)
+            for reason in overflow_reasons:
+                kind = {
+                    "max_lines_exceeded": "line_count",
+                    "safe_width_exceeded": "line_width",
+                    "safe_height_exceeded": "safe_area",
+                }.get(reason, "safe_area")
+                violations.append({"index": i, "kind": kind, "reason": reason})
+    return {
+        "enabled": bool(CONFIG.get("burn_subtitles", False)),
+        "renderer": "ass" if CONFIG.get("burn_subtitles", False) else "sidecar_srt",
+        "style": {
+            "font_size": int(font_size),
+            "max_chars": int(style.get("max_chars") or 0),
+            "max_lines": max_lines,
+            "play_res_x": play_x,
+            "play_res_y": play_y,
+            "alignment": int(style.get("alignment") or 0),
+            "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, *, with_source=False):
+    path = Path(work_dir) / VISUAL_OVERLAYS
+    if not path.exists():
+        result = ([], {"present": False, "path": str(path), "fingerprint": None})
+        return result if with_source else result[0]
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError) as exc:
+        result = ([], {
+            "present": True,
+            "path": str(path),
+            "fingerprint": _artifact_fingerprint(path),
+            "load_error": "invalid_json",
+            "load_error_detail": str(exc),
+        })
+        return result if with_source else result[0]
+    source = {
+        "present": True,
+        "path": str(path),
+        "fingerprint": _artifact_fingerprint(path),
+        "schema_version": data.get("schema_version") if isinstance(data, dict) else None,
+    }
+    schema_version = data.get("schema_version") if isinstance(data, dict) else None
+    valid_schema_version = (
+        isinstance(schema_version, int)
+        and not isinstance(schema_version, bool)
+        and schema_version == 1
+    )
+    if isinstance(data, dict) and valid_schema_version and isinstance(data.get("overlays"), list):
+        overlays = data["overlays"]
+    else:
+        overlays = []
+        source["load_error"] = "invalid_schema"
+    return (overlays, source) if with_source else overlays
+
+
+def _escape_drawtext_text(text):
+    return (
+        str(text or "")
+        .replace("\\", "\\\\")
+        .replace(":", "\\:")
+        .replace("'", "\\'")
+        .replace("%", "\\%")
+        .replace("\n", "\\n")
+    )
+
+
+def _overlay_time_window(overlay, video_duration):
+    try:
+        start = float(overlay.get("start", 0.0) or 0.0)
+    except (TypeError, ValueError):
+        start = 0.0
+    try:
+        end = float(overlay.get("end", video_duration) or video_duration)
+    except (TypeError, ValueError):
+        end = float(video_duration or 0.0)
+    end = max(start, end)
+    return start, end
+
+
+def _overlay_bbox(overlay, canvas, *, default_y):
+    width = int((canvas or {}).get("width") or 1280)
+    height = int((canvas or {}).get("height") or 720)
+    text = str(overlay.get("text") or "")
+    font_size = int(overlay.get("font_size") or 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), default=0.0)
+    text_h = len(lines) * font_size * 1.25
+    if overlay.get("type") == "top_title":
+        x = max(0.0, (width - max_w) / 2)
+        y = float(overlay.get("y", default_y) or default_y)
+    else:
+        raw_x = overlay.get("x", 0.08)
+        raw_y = overlay.get("y", 0.25)
+        try:
+            x = float(raw_x)
+            if 0.0 <= x <= 1.0:
+                x *= width
+        except (TypeError, ValueError):
+            x = width * 0.08
+        try:
+            y = float(raw_y)
+            if 0.0 <= y <= 1.0:
+                y *= height
+        except (TypeError, ValueError):
+            y = height * 0.25
+    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, with_source=True)
+    height = int((canvas or {}).get("height") or 720)
+    default_top_y = max(24, round(height * 0.05))
+    filters = []
+    facts = []
+    unsupported = []
+    overflow = []
+    for idx, overlay in enumerate(overlays):
+        if not isinstance(overlay, dict):
+            unsupported.append({"index": idx, "type": None, "reason": "overlay_not_object"})
+            continue
+        typ = str(overlay.get("type") or "").strip()
+        text = str(overlay.get("text") or "").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"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"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,
+        "load_error": source.get("load_error"),
+        "supported_types": sorted(_SUPPORTED_VISUAL_OVERLAY_TYPES),
+        "present": bool(source.get("present")),
+        "count": len(overlays),
+        "rendered": len(facts),
+        "facts": facts,
+        "unsupported": unsupported,
+        "overflow": overflow,
+    }
+    return filters, qc
+
+
+def _visual_qc_has_forbidden_delivery_facts(value):
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if key in _VISUAL_DELIVERY_FORBIDDEN_KEYS:
+                return True
+            if _visual_qc_has_forbidden_delivery_facts(child):
+                return True
+    elif isinstance(value, list):
+        return any(_visual_qc_has_forbidden_delivery_facts(item) for item in value)
+    return False
+
+
+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, canvas, style, safe_area=_measured_subtitle_safe_area(style, canvas)
+    )
+    mask = _source_subtitle_mask_policy(work_dir)
+    ratio = None
+    if mask.get("active"):
+        ratio = max(0.0, min(0.5, float(CONFIG.get("source_subtitle_mask_ratio", 0.14) or 0.0)))
+    mask.update({
+        "ratio": ratio,
+        "filter": "drawbox" if mask_filter else None,
+        "opacity": float(CONFIG.get("subtitle_mask_opacity", 0.6)),
+        "timing": str(CONFIG.get("source_subtitle_mask_timing", "narration")),
+        "subtitle_y_top": int(CONFIG.get("subtitle_y_top", -1)),
+        "subtitle_y_bot": int(CONFIG.get("subtitle_y_bot", -1)),
+    })
+    overlay_qc = overlay_qc or _visual_overlay_filters(work_dir, canvas, video_duration)[1]
+    blocking_codes = []
+    if mask.get("blocking"):
+        blocking_codes.append("mask_policy_not_explicit")
+    if subtitle_layout.get("overflow"):
+        blocking_codes.append("subtitle_overflow")
+    if overlay_qc.get("load_error"):
+        blocking_codes.append("invalid_visual_overlays_json")
+    if overlay_qc.get("unsupported"):
+        blocking_codes.append("unsupported_visual_overlay")
+    if overlay_qc.get("overflow"):
+        blocking_codes.append("visual_overlay_overflow")
+    qc = {
+        "schema_version": 1,
+        "artifact": VISUAL_QC,
+        "verdict": "FAIL" if blocking_codes else "PASS",
+        "blocking": bool(blocking_codes),
+        "blocking_codes": blocking_codes,
+        "geometry": {
+            "canvas": {
+                "width": int(canvas.get("width", 1280)),
+                "height": int(canvas.get("height", 720)),
+                "fps": float(canvas.get("fps", 30.0)),
+            },
+            "storage": {
+                "width": int(canvas.get("storage_width", canvas.get("width", 1280))),
+                "height": int(canvas.get("storage_height", canvas.get("height", 720))),
+            },
+            "rotation": int(canvas.get("rotation", 0) or 0),
+            "sample_aspect_ratio": canvas.get("sample_aspect_ratio", "1:1"),
+            "display_aspect_ratio": canvas.get("display_aspect_ratio"),
+        },
+        "subtitles": subtitle_layout,
+        "mask": mask,
+        "overlays": overlay_qc,
+        "summary": {
+            "subtitle_entries": subtitle_layout.get("entries", 0),
+            "subtitle_overflow": bool(subtitle_layout.get("overflow")),
+            "subtitle_multi_line": bool(subtitle_layout.get("multi_line")),
+            "mask_policy": mask.get("policy"),
+            "mask_active": bool(mask.get("active")),
+            "overlay_rendered": int(overlay_qc.get("rendered", 0) or 0),
+            "overlay_unsupported": len(overlay_qc.get("unsupported") or []),
+        },
+    }
+    if _visual_qc_has_forbidden_delivery_facts(qc):
+        qc["verdict"] = "FAIL"
+        qc["blocking"] = True
+        qc["blocking_codes"].append("visual_qc_contains_delivery_fact")
+    return qc
+
+
+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."""
+    return f"subtitles=filename='{_escape_subtitle_filter_path(subtitle_path)}'"
+
+
+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=None, work_dir=None, tts_segments=None, video_duration=None
+):
+    """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.get("active"):
+        return None
+    opacity = max(0.0, min(1.0, float(CONFIG.get("subtitle_mask_opacity", 0.6))))
+
+    _validate_measured_subtitle_coordinate_domain(canvas)
+
+    canvas_h = int((canvas or {}).get("height", 0) or 0)
+    y_top = int(CONFIG.get("subtitle_y_top", -1))
+    y_bot = int(CONFIG.get("subtitle_y_bot", -1))
+    custom_band = canvas_h > 0 and 0 <= y_top < y_bot <= canvas_h
+    if custom_band:
+        padding = int(CONFIG.get("subtitle_mask_padding", 4) or 0)
+        mask_top = max(0, y_top - padding)
+        mask_bot = min(canvas_h, y_bot + padding)
+        geometry = f"x=0:y={mask_top}:w=iw:h={mask_bot - mask_top}"
+    else:
+        ratio = max(0.0, min(0.5, float(CONFIG.get("source_subtitle_mask_ratio", 0.14) or 0.0)))
+        # 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 = max(1.0, 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(ratio, sub_band))
+        if ratio <= 0:
+            return None
+        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"
+    timing = str(CONFIG.get("source_subtitle_mask_timing", "narration") or "narration").lower()
+    if timing not in {"all", "narration"}:
+        timing = "narration"
+    filters = []
+    if timing == "all" and opacity > 0:
+        filters.append(base)
+    elif timing == "narration" and opacity > 0:
+        windows = []
+        for seg in tts_segments or []:
+            if not isinstance(seg, dict):
+                continue
+            start, end = _seg_place_window(seg)
+            try:
+                start, end = float(start), float(end)
+            except (TypeError, ValueError):
+                continue
+            if end <= start:
+                continue
+            windows.append((start, end, 0.0))
+        # 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 video_duration is not None and not (timing == "all" and opacity >= 1.0 - 1e-9):
+        replacement_entries = _original_gap_subtitle_entries(
+            tts_segments or [], work_dir, video_duration
+        )
+        replacement_windows = [
+            (entry["start"], entry["end"], 0.0) for entry in replacement_entries
+        ]
+        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/lib/video-recap/skills/video-cut/SKILL.md

@@ -0,0 +1,90 @@
+---
+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。
+ 触发词：视频剪辑、剪辑式解说、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`。
+5. 旧版单阶段路径还会把原片时间的旁白映射为 `narration_mapped.json`。
+
+相同输入会得到相同输出。缓存仅表示：当 `edited_source.mp4` 新于 `clip_plan.json` 时复用成片。
+
+## 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 返回。
+
+`work_dir/narration.json` 只在旧版单阶段路径中可选读取；该路径要求旁白使用原片时间。若允许重复或重叠片段，旁白可带 `source_clip_id` 消歧。
+
+## 3. 剪辑意图契约
+
+工具不会替 Agent 做创作选择。写片段前先完成本节的剪辑意图检查，并让每个区间映射到 `recap_story_plan.json` 的一个 beat。
+
+使用现有自由文本 `reason` 保存简洁决定：
+
+```text
+beat_id | function | change | POV | preferred moment | 入点 reason | 出点 reason
+```
+
+不要因为“事件重要”就保留整段；要保留最能让 change 成立的具体表演、反应、动作或揭示。理解与情绪允许时晚进早出，同时保证台词、动作和技术边界完整。
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的视频、参数与 `work_dir` 产物。
+
+## 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`：按计划拼接后的短视频。
+- `narration_mapped.json`：仅旧版单阶段路径生成；编排流程使用 `--no-narration-map`，不会生成该文件。
+
+编排流程下游把 `edited_source.mp4` 当作视频，把 Agent 按输出时间写的 `narration.json` 当作旁白。
+
+## 6. 边界与时间线规则
+
+- 旧版路径中，`clip_plan.json` 与 `narration.json` 都使用原片时间；本工具负责原片 → 输出映射。
+- 编排路径中，`narration.json` 直接使用剪后输出时间，不再映射。
+- 默认禁止重叠或重复原片区间；`--allow-overlap` 开启后，旁白应填写 `source_clip_id`。
+- 片段起点只能位于源头、可靠句末/静音窗，或与上一片段构成无损同源连续连接；片段终点同理。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 秒；白闪或曝光叠化再结合逐帧亮度定位，不能为了通过视觉检测切断完整台词，也不能用转场遮掩坏接点。
+- 连续同源片段的无损连接不做句中双侧音频淡出；非连续片段仍在安全停顿内做防爆音淡入淡出。
+- 旧版旁白映射若跨越 clip 边界，不再裁短后继续：`clamped_beats` 永久阻断，`--allow-sparse-cut` 也不能绕过旁白句子完整性。
+
+需要检查短时间频繁切镜时，先用 ffmpeg scene filter 召回候选时间：
+
+```bash
+ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
+```
+
+`0.35` 是起始阈值，不是质量判据；大幅运动、闪白和叠化都可能误报。把候选映射回原片 shot 与本次拼接边界后，按上面的来源分类处理，并以正常速度播放决定是否保留。
+
+## 7. 能力边界
+
+- 不重新转写，也不做人物、剧情或情绪等语义理解；scene filter 只承担技术边界候选检测。
+- 不写旁白，也不替 Agent 选择片段；只消费 `clip_plan.json`。
+- 只做生成 `edited_source.mp4` 所需的剪切、拼接与一次中间编码，不承担字幕包装或最终交付压缩。

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

@@ -0,0 +1,67 @@
+#!/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 (
+    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 media_geometry import VideoGeometry
+from narration_mapping import (
+    lint_mapped_narration,
+    map_narration_to_clips,
+    source_time_to_output_time,
+    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",
+    "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__":
+    main()