@lemoncat7/dsh-partner 2.8.1 → 2.8.3

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

@@ -0,0 +1,452 @@
+#!/usr/bin/env python3
+"""video-recap inspect — advisory, read-only orientation over a recap work_dir.
+
+Reads ONLY the JSON artifacts already in work_dir (no ffmpeg, no frame reads, no video
+probing, no new deps, no cross-skill import). A missing artifact is the legitimate
+"that stage has not run yet" state and is reported as such.
+
+Two subcommands:
+  state     summarize the work_dir: source video, full|cut mode, which stage
+            artifacts are present vs missing, which file is the NEXT pause the pipeline waits
+            on, stale-manifest risk, and storyboard path(s) if present.
+  clip-map  read clip_plan_validated.json and map a queried window between the OUTPUT and
+            SOURCE timelines using the SAME forward affine map cut.py uses
+            (output = clip.output_start + (src - clip.source_start), clamped to the clip),
+            reimplemented locally. Flags cross-clip boundaries and cut-out gaps.
+
+Output: markdown by default; --json for machine-readable; long free text is truncated
+unless --full is passed.
+"""
+import argparse
+import json
+from pathlib import Path
+
+
+def load_json(path):
+    return json.loads(Path(path).read_text(encoding="utf-8"))
+
+
+# --- artifact catalog --------------------------------------------------------
+# Stage artifacts probed by `state`. Order = rough pipeline order.
+_UNDERSTANDING_ARTIFACTS = [
+    "scenes.json",
+    "asr_result.json",
+    "silence_periods.json",
+    "speech_boundary_anchors.json",
+    "vlm_analysis.json",
+    "understanding_index.json",
+    "agent_narration_brief.md",
+]
+_CUT_ARTIFACTS = [
+    "multi_source_manifest.json",
+    "clip_plan.json",
+    "clip_plan_validated.json",
+    "edited_source.mp4",
+]
+_SCRIPT_ARTIFACTS = [
+    "narration.json",
+    "narration_lint.json",
+    "narration_review.json",
+    "original_subtitles.json",
+]
+_RENDER_ARTIFACTS = [
+    "tts_meta.json",
+    "timeline.json",
+    "subtitles.srt",
+    "subtitles.ass",
+    "assembly_manifest.json",
+]
+_STORYBOARD_ARTIFACTS = [
+    "storyboard/source_storyboard.json",
+    "storyboard/edited_storyboard.json",
+]
+
+_COMPACT_TEXT_LIMIT = 80
+
+
+def _truncate(text, compact):
+    text = str(text or "").strip()
+    if not compact or len(text) <= _COMPACT_TEXT_LIMIT:
+        return text
+    return text[: _COMPACT_TEXT_LIMIT - 1] + "…"
+
+
+def _load_optional(path):
+    """The artifact's JSON, or None when the stage that writes it has not run yet.
+
+    A present-but-corrupt artifact raises: every file probed here is written by this
+    pipeline or a sibling skill under its documented contract."""
+    path = Path(path)
+    return load_json(path) if path.exists() else None
+
+
+def _fmt_seconds(value):
+    """mm:ss.ss for a seconds value."""
+    sign = "-" if value < 0 else ""
+    total = abs(value)
+    return f"{sign}{int(total // 60):02d}:{total % 60:05.2f}"
+
+
+# --- source video discovery --------------------------------------------------
+def _discover_source(work_dir):
+    """Find the source video path by reading recap artifacts, most authoritative first.
+    Returns {path, origin} with path=None + origin="unknown" when nothing records it."""
+    work_dir = Path(work_dir)
+    # 1. recap_run_manifest.json — canonical: written before the first pause with both fields.
+    #    A multi-source manifest carries `sources` instead of `source_video`.
+    data = _load_optional(work_dir / "recap_run_manifest.json")
+    if data is not None and data.get("source_video"):
+        return {"path": data["source_video"], "origin": "recap_run_manifest.json"}
+    # 2. assembly_manifest.json — late stage; carries input_video (+ source_video in cut mode).
+    data = _load_optional(work_dir / "assembly_manifest.json")
+    if data is not None:
+        return {
+            "path": data.get("source_video") or data["input_video"],
+            "origin": "assembly_manifest.json",
+        }
+    # 3. edited_source.mp4.meta.json — video-cut records sources: {path: {size, mtime_ns}};
+    #    a single-source cut has exactly one entry.
+    data = _load_optional(work_dir / "edited_source.mp4.meta.json")
+    sources = data.get("sources") if isinstance(data, dict) else None
+    if isinstance(sources, dict) and len(sources) == 1:
+        (path,) = sources
+        return {"path": path, "origin": "edited_source.mp4.meta.json"}
+    return {"path": None, "origin": "unknown"}
+
+
+def _discover_multi_source(work_dir):
+    data = _load_optional(Path(work_dir) / "multi_source_manifest.json")
+    if data is None:
+        return None
+    return {"schema_version": data["schema_version"], "sources": data["sources"]}
+
+
+# --- forward affine map --------------------------------------------------------
+def _source_to_output(src, clip):
+    """The forward affine map cut.py uses, clamped to the clip's output span."""
+    mapped = clip["output_start"] + (src - clip["source_start"])
+    return round(max(clip["output_start"], min(mapped, clip["output_end"])), 3)
+
+
+def _output_to_source(out, clip):
+    """Inverse of the forward affine map (same slope, clamped to the clip's source span)."""
+    mapped = clip["source_start"] + (out - clip["output_start"])
+    return round(max(clip["source_start"], min(mapped, clip["source_end"])), 3)
+
+
+def _overlap(a0, a1, b0, b1):
+    """Intersection [lo, hi] of two closed ranges, or None when they do not overlap.
+
+    A zero-width query (a0 == a1, e.g. --output-start 10 --output-end 10) is treated as a
+    POINT lookup: it returns (a0, a0) when the point lies within [b0, b1], so a point that sits
+    inside a clip is reported instead of silently falling through to "not in any clip".
+    """
+    if a0 == a1:
+        return (a0, a0) if b0 <= a0 <= b1 else None
+    lo, hi = max(a0, b0), min(a1, b1)
+    return (lo, hi) if hi > lo else None
+
+
+# --- state subcommand --------------------------------------------------------
+def _present(work_dir, name):
+    return (Path(work_dir) / name).exists()
+
+
+def _detect_mode(work_dir):
+    """cut when any cut artifact is present, else full."""
+    if any(_present(work_dir, n) for n in _CUT_ARTIFACTS):
+        return "cut"
+    return "full"
+
+
+def _next_pause(work_dir, mode):
+    """The artifact the pipeline is currently waiting on the agent to write, or None when the
+    next-needed input is already present. Mirrors recap.py's two-pause cut flow / single-pause full
+    flow purely from file presence (advisory; the orchestrator owns the real decision)."""
+    if mode == "cut":
+        if not _present(work_dir, "clip_plan.json"):
+            return ("clip_plan.json", "pass1: 写剪辑计划（只写 clip_plan.json）")
+        if not _present(work_dir, "narration.json"):
+            return ("narration.json", "pass2: 对着剪好的成片用 OUTPUT 时间轴写解说")
+        return None
+    if not _present(work_dir, "narration.json"):
+        return ("narration.json", "写解说 narration.json")
+    return None
+
+
+def _stale_manifest_note(work_dir, mode):
+    """Advisory stale-manifest risks read purely from file presence. Surfaces the two desync traps recap.py guards: a cut
+    narration without the phase ledger that ties it to a clip_plan, and a missing run manifest."""
+    notes = []
+    if not _present(work_dir, "recap_run_manifest.json"):
+        notes.append("缺少 recap_run_manifest.json：无法证明 work_dir 属于当前视频/参数（resume 会被拒绝）。")
+    if mode == "cut" and _present(work_dir, "narration.json") and not _present(work_dir, "recap_phase.json"):
+        notes.append("有 narration.json 但缺少 recap_phase.json：无法判断解说是否对当前剪辑写的（可能 stale）。")
+    return notes
+
+
+def _present_storyboards(work_dir):
+    return [n for n in _STORYBOARD_ARTIFACTS if _present(work_dir, n)]
+
+
+def cmd_state(work_dir, compact=None):
+    del compact
+    work_dir = Path(work_dir)
+    if not work_dir.exists():
+        return {"error": f"work_dir 不存在: {work_dir}"}
+
+    mode = _detect_mode(work_dir)
+    groups = {
+        "understanding": _UNDERSTANDING_ARTIFACTS,
+        "cut": _CUT_ARTIFACTS,
+        "script": _SCRIPT_ARTIFACTS,
+        "render": _RENDER_ARTIFACTS,
+    }
+    artifacts = {
+        group: {
+            "present": [n for n in names if _present(work_dir, n)],
+            "missing": [n for n in names if not _present(work_dir, n)],
+        }
+        for group, names in groups.items()
+    }
+    pause = _next_pause(work_dir, mode)
+    return {
+        "work_dir": str(work_dir),
+        "mode": mode,
+        "source_video": _discover_source(work_dir),
+        "multi_source": _discover_multi_source(work_dir),
+        "next_pause": {"artifact": pause[0], "hint": pause[1]} if pause else None,
+        "artifacts": artifacts,
+        "storyboards": _present_storyboards(work_dir),
+        "stale_manifest_notes": _stale_manifest_note(work_dir, mode),
+    }
+
+
+def _render_state_md(state, compact):
+    if "error" in state:
+        return state["error"]
+    lines = [f"# recap work_dir 状态: {state['work_dir']}", ""]
+    lines.append(f"模式: **{state['mode']}**")
+    src = state["source_video"]
+    lines.append(f"源视频: {_truncate(src['path'] or 'unknown', compact)}  (来源 {src['origin']})")
+    if state["multi_source"]:
+        lines.append("多源素材:")
+        for s in state["multi_source"]["sources"]:
+            lines.append(
+                f"  - {s['source_id']}: {_truncate(s['source_path'], compact)} "
+                f"(work_dir {s['source_work_dir']}, material {s['material_id']})"
+            )
+    lines.append("")
+
+    if state["next_pause"]:
+        np = state["next_pause"]
+        lines.append(f"下一步暂停 → 等待写入 **{np['artifact']}**  ({np['hint']})")
+    else:
+        lines.append("下一步暂停 → 无（所需输入已就绪，可继续 voiceover/assemble）")
+    lines.append("")
+
+    lines.append("## 各阶段产物")
+    for group, label in (("understanding", "理解"), ("cut", "剪辑"),
+                         ("script", "解说"), ("render", "渲染")):
+        info = state["artifacts"][group]
+        lines.append(f"### {label}")
+        lines.append(f"  有: {', '.join(info['present']) or '（无）'}")
+        lines.append(f"  缺: {', '.join(info['missing']) or '（无）'}")
+    lines.append("")
+
+    if state["storyboards"]:
+        lines.append("## storyboard")
+        for s in state["storyboards"]:
+            lines.append(f"  - {s}")
+        lines.append("")
+
+    lines.append("## stale-manifest 风险")
+    if state["stale_manifest_notes"]:
+        for n in state["stale_manifest_notes"]:
+            lines.append(f"  ⚠️ {n}")
+    else:
+        lines.append("  无明显 stale 风险。")
+    return "\n".join(lines)
+
+
+# --- clip-map subcommand -----------------------------------------------------
+def cmd_clip_map(work_dir, output_start, output_end, source_start, source_end, compact):
+    work_dir = Path(work_dir)
+    validated = work_dir / "clip_plan_validated.json"
+    if not validated.exists():
+        return {"error": "clip_plan_validated.json 不存在：这不是 cut 运行，或剪辑计划尚未被 cut.py 校验。"
+                         "（full 模式没有源↔输出映射；cut 模式请先跑 video-cut。）"}
+    # video-cut writes {"clips": [{clip_id, source_start, source_end, output_start,
+    # output_end, duration, reason}]} (cut_contract); source_id/source_path only for
+    # multi-source cuts.
+    clips = load_json(validated)["clips"]
+    if not clips:
+        return {"error": "clip_plan_validated.json 没有有效的 clip。"}
+
+    have_output = output_start is not None or output_end is not None
+    have_source = source_start is not None or source_end is not None
+    if not have_output and not have_source:
+        return {"error": "请用 --output-start/--output-end 或 --source-start/--source-end 指定要查询的窗口。"}
+
+    result = {
+        "work_dir": str(work_dir),
+        "clip_count": len(clips),
+        "source_span": [clips[0]["source_start"], clips[-1]["source_end"]],
+        "output_span": [clips[0]["output_start"], clips[-1]["output_end"]],
+        "queries": [],
+    }
+    if have_output:
+        result["queries"].append(
+            _map_output_window(output_start, output_end, clips, compact))
+    if have_source:
+        result["queries"].append(
+            _map_source_window(source_start, source_end, clips, compact))
+    return result
+
+
+def _segment(clip, *, source, output, compact):
+    # source_id/source_path are only written for multi-source cuts.
+    return {
+        "clip_id": clip["clip_id"],
+        "source_id": clip.get("source_id"),
+        "source_path": clip.get("source_path"),
+        "output": output,
+        "source": source,
+        "reason": _truncate(clip["reason"], compact),
+    }
+
+
+def _map_output_window(out_start, out_end, clips, compact):
+    """Map a queried OUTPUT window to its SOURCE window(s), one per touched clip."""
+    out_lo = clips[0]["output_start"] if out_start is None else out_start
+    out_hi = clips[-1]["output_end"] if out_end is None else out_end
+    if out_hi < out_lo:
+        out_lo, out_hi = out_hi, out_lo
+    segments = []
+    for clip in clips:
+        ov = _overlap(out_lo, out_hi, clip["output_start"], clip["output_end"])
+        if not ov:
+            continue
+        segments.append(_segment(
+            clip,
+            output=[round(ov[0], 3), round(ov[1], 3)],
+            source=[_output_to_source(ov[0], clip), _output_to_source(ov[1], clip)],
+            compact=compact,
+        ))
+    return {
+        "direction": "output→source",
+        "query": [round(out_lo, 3), round(out_hi, 3)],
+        "clips_touched": [s["clip_id"] for s in segments],
+        "cross_clip_boundary": len(segments) > 1,
+        "segments": segments,
+        # An OUTPUT window can't fall outside any clip (output is contiguous), so no cut-out gaps.
+        "cut_out_source_gaps": [],
+    }
+
+
+def _map_source_window(src_start, src_end, clips, compact):
+    """Map a queried SOURCE window to its OUTPUT window(s), flagging source ranges in no clip."""
+    src_lo = clips[0]["source_start"] if src_start is None else src_start
+    src_hi = clips[-1]["source_end"] if src_end is None else src_end
+    if src_hi < src_lo:
+        src_lo, src_hi = src_hi, src_lo
+    segments = []
+    covered = []
+    for clip in clips:
+        ov = _overlap(src_lo, src_hi, clip["source_start"], clip["source_end"])
+        if not ov:
+            continue
+        covered.append(ov)
+        segments.append(_segment(
+            clip,
+            source=[round(ov[0], 3), round(ov[1], 3)],
+            output=[_source_to_output(ov[0], clip), _source_to_output(ov[1], clip)],
+            compact=compact,
+        ))
+    # Cut-out gaps: parts of [src_lo, src_hi] covered by NO kept clip (footage that was cut away).
+    gaps = []
+    cursor = src_lo
+    for lo, hi in sorted(covered):
+        if lo > cursor:
+            gaps.append([round(cursor, 3), round(lo, 3)])
+        cursor = max(cursor, hi)
+    if cursor < src_hi:
+        gaps.append([round(cursor, 3), round(src_hi, 3)])
+    return {
+        "direction": "source→output",
+        "query": [round(src_lo, 3), round(src_hi, 3)],
+        "clips_touched": [s["clip_id"] for s in segments],
+        "cross_clip_boundary": len(segments) > 1,
+        "segments": segments,
+        "cut_out_source_gaps": gaps,
+    }
+
+
+def _render_clip_map_md(result, compact):
+    if "error" in result:
+        return result["error"]
+    lines = [f"# clip-map: {result['work_dir']}", ""]
+    lines.append(
+        f"{result['clip_count']} clips · "
+        f"源 {_fmt_seconds(result['source_span'][0])}–{_fmt_seconds(result['source_span'][1])} · "
+        f"输出 {_fmt_seconds(result['output_span'][0])}–{_fmt_seconds(result['output_span'][1])}")
+    for q in result["queries"]:
+        lines.append("")
+        lines.append(f"## {q['direction']}  查询 "
+                     f"{_fmt_seconds(q['query'][0])}–{_fmt_seconds(q['query'][1])}")
+        if q["cross_clip_boundary"]:
+            lines.append(f"  ⚠️ 跨剪辑边界（涉及 clip {q['clips_touched']}）")
+        if not q["segments"]:
+            lines.append("  （该窗口不落在任何保留片段内）")
+        for s in q["segments"]:
+            src = f"{_fmt_seconds(s['source'][0])}–{_fmt_seconds(s['source'][1])}"
+            out = f"{_fmt_seconds(s['output'][0])}–{_fmt_seconds(s['output'][1])}"
+            reason = f"  〔{s['reason']}〕" if s["reason"] else ""
+            sid = f" {s['source_id']}" if s["source_id"] else ""
+            spath = f" `{_truncate(s['source_path'], compact)}`" if s["source_path"] else ""
+            lines.append(f"  clip {s['clip_id']}{sid}{spath}: 源 {src}  ↔  输出 {out}{reason}")
+        if q["cut_out_source_gaps"]:
+            lines.append("  ✂️ 被剪掉的源区间（不在成片里）:")
+            for g in q["cut_out_source_gaps"]:
+                lines.append(f"     {_fmt_seconds(g[0])}–{_fmt_seconds(g[1])}")
+    return "\n".join(lines)
+
+
+# --- CLI ---------------------------------------------------------------------
+def main(argv=None):
+    parser = argparse.ArgumentParser(
+        prog="recap_inspect.py",
+        description="Advisory read-only inspection of a video-recap work_dir (pure JSON).")
+    parser.add_argument("--work-dir", required=True, help="recap work_dir to inspect")
+    parser.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    parser.add_argument("--full", dest="compact", action="store_false", default=True,
+                        help="do not truncate long free text (truncated by default)")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("state", help="summarize work_dir + the next pause the pipeline is waiting on")
+
+    cm = sub.add_parser("clip-map", help="map a window between OUTPUT and SOURCE timelines")
+    cm.add_argument("--output-start", type=float, default=None)
+    cm.add_argument("--output-end", type=float, default=None)
+    cm.add_argument("--source-start", type=float, default=None)
+    cm.add_argument("--source-end", type=float, default=None)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "state":
+        result = cmd_state(args.work_dir)
+        rendered = _render_state_md(result, args.compact)
+    else:
+        result = cmd_clip_map(args.work_dir, args.output_start, args.output_end,
+                              args.source_start, args.source_end, args.compact)
+        rendered = _render_clip_map_md(result, args.compact)
+
+    if args.json:
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+    else:
+        print(rendered)
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -0,0 +1,70 @@
+"""Apply the optional or strict narration-review gate before TTS."""
+
+import json
+from pathlib import Path
+
+from lib import env_bool
+
+
+def review_narration_enabled(args):
+    if args.review_narration is not None:
+        return args.review_narration
+    return env_bool("REVIEW_NARRATION", True)
+
+
+def require_narration_review(args):
+    return args.require_narration_review or env_bool("REQUIRE_NARRATION_REVIEW", False)
+
+
+def review_result_status(work_dir):
+    """Gate on the review video-script wrote (findings: list of {severity in
+    error|warning|suggestion}, already normalised by review_response)."""
+    path = Path(work_dir) / "narration_review.json"
+    if not path.exists():
+        return {"ok": False, "reason": "missing narration_review.json"}
+    data = json.loads(path.read_text(encoding="utf-8"))
+    error_count = sum(1 for finding in data["findings"] if finding["severity"] == "error")
+    if data.get("parse_error"):
+        return {"ok": False, "reason": "parse_error", "review": data, "errors": error_count}
+    if error_count:
+        return {
+            "ok": False,
+            "reason": f"error {error_count}",
+            "review": data,
+            "errors": error_count,
+        }
+    # Strict mode gates only on parse errors or factual error findings. The model's
+    # holistic verdict stays advisory because craft-class findings are warnings.
+    return {"ok": True, "reason": "ok", "review": data, "errors": error_count}
+
+
+def clear_narration_review_artifacts(work_dir):
+    """Remove prior review artifacts before a fresh pre-TTS review run."""
+    for name in ("narration_review.json", "narration_review.md"):
+        (Path(work_dir) / name).unlink(missing_ok=True)
+
+
+def run_narration_review(work_dir, args, *, run, timeline="source"):
+    """Run the review gate using the caller's skill-command runner."""
+    strict = require_narration_review(args)
+    if not review_narration_enabled(args) and not strict:
+        return False
+    try:
+        clear_narration_review_artifacts(work_dir)
+        # Pin the grounding timeline so stale cut artifacts cannot alter auto-detection.
+        review_args = ["--work-dir", work_dir, "--timeline", timeline]
+        if strict and timeline == "cut_output":
+            review_args.append("--strict-evidence")
+        run("video-script", "review.py", *review_args)
+    except SystemExit as exc:
+        if strict:
+            raise SystemExit(f"严格解说评审失败，已阻止 TTS: {exc}") from exc
+        print(f"[video-recap] ⚠️ 建议性评审失败，继续执行 TTS: {exc}", flush=True)
+        return False
+
+    status = review_result_status(work_dir)
+    if strict and not status["ok"]:
+        raise SystemExit(f"严格解说评审未通过，已阻止 TTS: {status['reason']}")
+    if strict:
+        print("[video-recap] ✅ 严格解说评审通过，继续 TTS", flush=True)
+    return True