@lemoncat7/dsh-partner 2.8.1 → 2.8.3

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

@@ -0,0 +1,320 @@
+"""Shared shift-left QC report contract for video-recap artifacts.
+
+This module is intentionally standalone: it defines a small schema and local
+validation helpers only. It does not call MiMo, read credentials, connect the
+pipeline, or attempt automatic fixes.
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any
+from collections.abc import Mapping, Sequence
+from urllib.parse import urlsplit, urlunsplit
+
+
+SCHEMA_VERSION = 1
+
+STAGES = frozenset({
+    "pre_cut",
+    "post_cut",
+    "pre_tts",
+    "post_tts",
+    "pre_assemble",
+    "post_render",
+    "golden",
+})
+SEVERITIES = frozenset({"info", "advisory", "warning", "blocker"})
+CONFIDENCES = frozenset({"low", "medium", "high", "objective"})
+SAMPLE_POLICIES = frozenset({"all", "deterministic", "sampled", "semantic", "aesthetic"})
+ARTIFACTS = frozenset({"final_qc.json", "golden_eval.json", "mimo_qc.json", "preflight_qc.json"})
+
+DETERMINISTIC_CATEGORIES = frozenset({
+    "missing_artifact",
+    "duration",
+    "stream",
+    "subtitle",
+    "tts_placement",
+    "schema_invalid",
+    "placement",
+})
+NON_DETERMINISTIC_CATEGORIES = frozenset({"semantic", "aesthetic", "mimo_semantic", "mimo_aesthetic"})
+BLOCKING_SEVERITIES = frozenset({"blocker"})
+_SECRET_KEY_RE = re.compile(r"(?i)(api[_-]?key|token|secret|password|authorization|credential)")
+_SECRET_VALUE_RE = re.compile(r"\b(?:sk|tp)-[A-Za-z0-9_-]{6,}\b")
+_URL_SCHEMES_TO_SCRUB = frozenset({"http", "https", "ws", "wss"})
+REDACTED = "<redacted>"
+
+
+def _redact_url(value: str) -> str:
+    """Strip URL credentials, query, and fragment while preserving useful host/path."""
+    try:
+        parts = urlsplit(value)
+    except ValueError:
+        return value
+    if parts.scheme.lower() not in _URL_SCHEMES_TO_SCRUB or not parts.netloc:
+        return value
+    host = parts.hostname or ""
+    if not host:
+        return value
+    if ":" in host and not host.startswith("["):
+        host = f"[{host}]"
+    netloc = host
+    try:
+        port = parts.port
+    except ValueError:
+        port = None
+    if port is not None:
+        netloc = f"{netloc}:{port}"
+    return urlunsplit((parts.scheme, netloc, parts.path, "", ""))
+
+
+def redact_secrets(value: Any) -> Any:
+    """Return a JSON-safe copy with likely credentials removed.
+
+    Centralized for all video-recap QC reports: redacts secret-looking keys,
+    common synthetic key/token values, and URL userinfo/query/fragment fields.
+    """
+    if isinstance(value, Mapping):
+        redacted: dict[str, Any] = {}
+        for key, item in value.items():
+            key_s = str(key)
+            redacted[key_s] = REDACTED if _SECRET_KEY_RE.search(key_s) else redact_secrets(item)
+        return redacted
+    if isinstance(value, list):
+        return [redact_secrets(item) for item in value]
+    if isinstance(value, tuple):
+        return [redact_secrets(item) for item in value]
+    if isinstance(value, Path):
+        return str(value)
+    if isinstance(value, str):
+        return _SECRET_VALUE_RE.sub(REDACTED, _redact_url(value))
+    return value
+
+
+_REQUIRED_FINDING_FIELDS = frozenset({
+    "finding_id",
+    "stage",
+    "severity",
+    "blocking",
+    "deterministic",
+    "confidence",
+    "rule_id",
+    "decision_reason",
+    "location",
+    "evidence",
+    "sample_policy",
+    "model_used",
+    "next_action",
+    # Helper fields kept for current rule semantics and compatibility.
+    "category",
+    "code",
+    "message",
+    "source",
+    "objective_corroboration",
+})
+_REQUIRED_LOCATION_FIELDS = frozenset({"timecode", "source_span"})
+_REQUIRED_REPORT_FIELDS = frozenset({
+    "schema_version",
+    "artifact",
+    "stage",
+    "ok",
+    "blocker_count",
+    "finding_count",
+    "findings",
+})
+
+
+class QCContractError(ValueError):
+    """Raised when a QC report or finding violates the shared contract."""
+
+
+def build_finding(
+    *,
+    stage: str,
+    severity: str,
+    confidence: str,
+    sample_policy: str | Mapping[str, Any],
+    category: str,
+    code: str,
+    message: str,
+    finding_id: str | None = None,
+    id: str | None = None,
+    rule_id: str | None = None,
+    decision_reason: str | None = None,
+    model_used: str | None = None,
+    next_action: str | None = None,
+    deterministic: bool | None = None,
+    blocking: bool | None = None,
+    source: Mapping[str, Any] | None = None,
+    location: Mapping[str, Any] | None = None,
+    evidence: Mapping[str, Any] | None = None,
+    objective_corroboration: Mapping[str, Any] | None = None,
+    **extra: Any,
+) -> dict[str, Any]:
+    """Build and validate one normalized QC finding.
+
+    Deterministic objective findings may block. MiMo semantic/aesthetic findings
+    default to advisory and may never block. Objective checks belong in the
+    deterministic QC producers instead of upgrading subjective model findings.
+    """
+    if finding_id is None:
+        finding_id = id
+    if finding_id is None:
+        raise QCContractError("finding_id is required")
+    if rule_id is None:
+        rule_id = code
+    if decision_reason is None:
+        decision_reason = message
+    if model_used is None:
+        model_used = "local_deterministic"
+    if next_action is None:
+        next_action = "manual_review"
+    if isinstance(sample_policy, str):
+        sample_policy = {"type": sample_policy}
+
+    if deterministic is None:
+        deterministic = category in DETERMINISTIC_CATEGORIES
+    if source is None:
+        source = {}
+    source = redact_secrets(source)
+    if location is None:
+        location = {"timecode": None, "source_span": None}
+    else:
+        location = {"timecode": location.get("timecode"), "source_span": location.get("source_span")}
+    if evidence is None:
+        evidence = {}
+    evidence = redact_secrets(evidence)
+    objective_corroboration = redact_secrets(objective_corroboration or {})
+
+    is_non_deterministic = (not deterministic) or category in NON_DETERMINISTIC_CATEGORIES
+    if is_non_deterministic and blocking is None:
+        blocking = False
+    elif blocking is None:
+        blocking = severity in BLOCKING_SEVERITIES
+
+    if is_non_deterministic and blocking:
+        raise QCContractError(f"non-deterministic blocking finding is not allowed: {category}/{code}")
+
+    finding = {
+        "finding_id": finding_id,
+        "id": finding_id,
+        "stage": stage,
+        "severity": severity,
+        "blocking": bool(blocking),
+        "deterministic": bool(deterministic),
+        "confidence": confidence,
+        "rule_id": rule_id,
+        "decision_reason": decision_reason,
+        "location": dict(location),
+        "evidence": dict(evidence),
+        "sample_policy": dict(sample_policy),
+        "model_used": model_used,
+        "next_action": next_action,
+        "category": category,
+        "code": code,
+        "message": message,
+        "source": dict(source),
+        "objective_corroboration": dict(objective_corroboration),
+    }
+    finding.update(redact_secrets(extra))
+    _validate_finding(finding)
+    return finding
+
+
+def build_report(
+    *,
+    artifact: str,
+    stage: str,
+    findings: Sequence[Mapping[str, Any]] | None = None,
+    metadata: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Build and validate a minimal report for a supported QC artifact."""
+    normalized_findings = [redact_secrets(dict(f)) for f in (findings or [])]
+    blocker_count = sum(1 for f in normalized_findings if f.get("blocking") is True)
+    report = {
+        "schema_version": SCHEMA_VERSION,
+        "artifact": artifact,
+        "stage": stage,
+        "ok": blocker_count == 0,
+        "blocker_count": blocker_count,
+        "finding_count": len(normalized_findings),
+        "findings": normalized_findings,
+        "metadata": redact_secrets(dict(metadata or {})),
+    }
+    validate_report(report)
+    return report
+
+
+def validate_report(report: Mapping[str, Any]) -> bool:
+    """Validate report shape, value domains, and blocking semantics."""
+    if not isinstance(report, Mapping):
+        raise QCContractError("report must be an object")
+    missing = _REQUIRED_REPORT_FIELDS - set(report)
+    if missing:
+        raise QCContractError(f"report missing required fields: {sorted(missing)}")
+    if report["schema_version"] != SCHEMA_VERSION:
+        raise QCContractError(f"unsupported schema_version: {report['schema_version']!r}")
+    if report["artifact"] not in ARTIFACTS:
+        raise QCContractError(f"unsupported artifact: {report['artifact']!r}")
+    if report["stage"] not in STAGES:
+        raise QCContractError(f"unsupported stage: {report['stage']!r}")
+    if not isinstance(report["findings"], list):
+        raise QCContractError("findings must be a list")
+    for finding in report["findings"]:
+        _validate_finding(finding)
+    blocker_count = sum(1 for f in report["findings"] if f.get("blocking") is True)
+    if report["blocker_count"] != blocker_count:
+        raise QCContractError("blocker_count does not match findings")
+    if report["finding_count"] != len(report["findings"]):
+        raise QCContractError("finding_count does not match findings")
+    if report["ok"] != (blocker_count == 0):
+        raise QCContractError("ok must be true exactly when blocker_count is zero")
+    return True
+
+
+def _validate_finding(finding: Mapping[str, Any]) -> None:
+    if not isinstance(finding, Mapping):
+        raise QCContractError("finding must be an object")
+    missing = _REQUIRED_FINDING_FIELDS - set(finding)
+    if missing:
+        raise QCContractError(f"finding missing required fields: {sorted(missing)}")
+    if finding["stage"] not in STAGES:
+        raise QCContractError(f"unsupported finding stage: {finding['stage']!r}")
+    if finding["severity"] not in SEVERITIES:
+        raise QCContractError(f"unsupported severity: {finding['severity']!r}")
+    if finding["confidence"] not in CONFIDENCES:
+        raise QCContractError(f"unsupported confidence: {finding['confidence']!r}")
+    sample_policy = finding["sample_policy"]
+    if not isinstance(sample_policy, Mapping):
+        raise QCContractError("sample_policy must be an object")
+    sample_policy_type = sample_policy.get("type")
+    if sample_policy_type not in SAMPLE_POLICIES:
+        raise QCContractError(f"unsupported sample_policy.type: {sample_policy_type!r}")
+    if not isinstance(finding["deterministic"], bool):
+        raise QCContractError("deterministic must be boolean")
+    if not isinstance(finding["blocking"], bool):
+        raise QCContractError("blocking must be boolean")
+    if finding["blocking"] and finding["severity"] != "blocker":
+        raise QCContractError("blocking findings must use severity='blocker'")
+    location = finding["location"]
+    if not isinstance(location, Mapping):
+        raise QCContractError("location must be an object")
+    missing_location = _REQUIRED_LOCATION_FIELDS - set(location)
+    if missing_location:
+        raise QCContractError(f"location missing required fields: {sorted(missing_location)}")
+    if finding["source"] is None or not isinstance(finding["source"], Mapping):
+        raise QCContractError("source must be an object")
+    if finding["evidence"] is None or not isinstance(finding["evidence"], Mapping):
+        raise QCContractError("evidence must be an object")
+    if finding["objective_corroboration"] is None or not isinstance(finding["objective_corroboration"], Mapping):
+        raise QCContractError("objective_corroboration must be an object")
+    for field in ("finding_id", "rule_id", "decision_reason", "model_used", "next_action"):
+        if not isinstance(finding[field], str) or not finding[field]:
+            raise QCContractError(f"{field} must be a non-empty string")
+
+    is_non_deterministic = (not finding["deterministic"]) or finding["category"] in NON_DETERMINISTIC_CATEGORIES
+    if is_non_deterministic and finding["blocking"]:
+        raise QCContractError(
+            f"non-deterministic blocking finding is not allowed: {finding['category']}/{finding['code']}"
+        )

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

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+"""CLI entrypoint for the self-contained video-recap orchestrator."""
+
+from recap_runner import main
+
+__all__ = ["main"]
+
+if __name__ == "__main__":
+    main()

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

@@ -0,0 +1,209 @@
+"""Define the video-recap command-line contract."""
+
+import argparse
+import os
+
+from lib import env_bool
+from recap_source import AUDIO_MODES
+
+TTS_PROVIDERS = ("auto", "mimo-tts", "fish-audio", "index-tts")
+
+
+class _RecordExplicit:
+    """Record the option argparse actually consumed, not the raw argv spelling."""
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        if option_string is not None:
+            recorded = getattr(namespace, "_explicit_options", None)
+            if recorded is None:
+                recorded = set()
+                setattr(namespace, "_explicit_options", recorded)
+            recorded.add(option_string)
+        super().__call__(parser, namespace, values, option_string)
+
+
+def _record_explicit_options(parser):
+    """Make every optional action report itself, so guards never re-parse sys.argv."""
+    tracked = {}
+    for action in parser._actions:
+        if not action.option_strings:
+            continue
+        base = type(action)
+        if not issubclass(base, _RecordExplicit):
+            action.__class__ = tracked.setdefault(
+                base, type(base.__name__, (_RecordExplicit, base), {})
+            )
+
+
+def parse_args(argv=None):
+    parser = argparse.ArgumentParser(
+        description="Full video recap orchestrator (video-* skill bundle).",
+        allow_abbrev=False,
+    )
+    parser.add_argument("video", nargs="*")
+
+    core = parser.add_argument_group("核心流程")
+    core.add_argument("--work-dir", default=None)
+    core.add_argument("--context", default="")
+    core.add_argument("--scene-threshold", type=float, default=None)
+    core.add_argument("--style", default="纪录片")
+    core.add_argument(
+        "--edit-mode",
+        default=os.environ.get("EDIT_MODE", "full"),
+        choices=["full", "cut", "dub"],
+    )
+    core.add_argument(
+        "--target-duration", default=os.environ.get("TARGET_DURATION") or None
+    )
+    core.add_argument(
+        "--allow-duration-drift",
+        action="store_true",
+        help="cut mode: accept clip duration drift from --target-duration (primary override)",
+    )
+    core.add_argument("--output-dir", default=None)
+    core.add_argument("--skip-asr", action="store_true")
+    core.add_argument("--mimo-video-overview", action="store_true")
+    core.add_argument(
+        "--consolidate",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="build the understanding story index (Pass B); default ON, --no-consolidate to skip",
+    )
+    core.add_argument(
+        "--consolidate-asr", action="store_true", help="also clean ASR (Pass A)"
+    )
+
+    voice = parser.add_argument_group("声音策略与配音")
+    voice.add_argument("--audio-mode", choices=AUDIO_MODES, default="narration")
+    voice.add_argument("--audio-stream-index", type=int, default=0)
+    voice.add_argument(
+        "--tts-provider",
+        default=os.environ.get("TTS_PROVIDER", "auto"),
+        choices=TTS_PROVIDERS,
+        help="voiceover provider; auto prefers configured MiMo, then Fish Audio; Index is explicit",
+    )
+    voice.add_argument("--mimo-tts-voice", default=None, help="MiMo TTS voice")
+    voice.add_argument(
+        "--voice-ref",
+        default=None,
+        help="reference audio for cloned narration voice (mimo-v2.5-tts-voiceclone)",
+    )
+    voice.add_argument(
+        "--preserve-approved-text",
+        action="store_true",
+        help="forward strict approved-text preservation to narration voiceover",
+    )
+    voice.add_argument(
+        "--allow-partial-tts",
+        action="store_true",
+        help="allow video-voiceover to continue when some narration segments fail TTS",
+    )
+    voice.add_argument(
+        "--burn-subtitles",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="burn narration subtitles into the video (default on; --no-burn-subtitles to disable)",
+    )
+    voice.add_argument(
+        "--subtitle-y-top",
+        type=int,
+        default=None,
+        help="inclusive auto-rotated display-frame Y at the top of the measured subtitle band",
+    )
+    voice.add_argument(
+        "--subtitle-y-bot",
+        type=int,
+        default=None,
+        help="exclusive auto-rotated display-frame Y at the bottom of the measured subtitle band",
+    )
+
+    adoption = parser.add_argument_group("本地采用三件套（assembly-only）")
+    adoption.add_argument(
+        "--tts-meta", default=None,
+        help="local adopted tts_meta.json; requires both adoption flags",
+    )
+    adoption.add_argument(
+        "--narration-adoption", default=None,
+        help="local narration_adoption v1; requires --tts-meta and --audio-mix-adoption",
+    )
+    adoption.add_argument(
+        "--audio-mix-adoption", default=None,
+        help="local audio_mix_adoption v1 for assembly-only full-sound rendering",
+    )
+
+    review = parser.add_argument_group("评审、QC 与导出")
+    review.add_argument(
+        "--review-narration",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help="run advisory narration quality review before TTS (default on; fail-open)",
+    )
+    review.add_argument(
+        "--require-narration-review",
+        action="store_true",
+        help="make narration review a strict pre-TTS gate (also REQUIRE_NARRATION_REVIEW=1)",
+    )
+    review.add_argument(
+        "--mimo-qc",
+        default=os.environ.get("MIMO_QC", "off"),
+        choices=["off", "pre-assemble", "post-render", "both"],
+        help="optional advisory MiMo QC stage(s); never blocks the pipeline",
+    )
+    review.add_argument(
+        "--mimo-qc-refresh",
+        action="store_true",
+        default=env_bool("MIMO_QC_REFRESH", False),
+        help="ignore a matching MiMo QC stage cache",
+    )
+    review.add_argument(
+        "--require-final-qc",
+        action="store_true",
+        help="full/cut: require literal passing final_qc and golden_eval summaries",
+    )
+    review.add_argument(
+        "--export-jianying",
+        action="store_true",
+        help="also export an OPTIONAL 剪映/JianYing draft (decoupled; never required)",
+    )
+    review.add_argument(
+        "--jianying-bundle-media",
+        action="store_true",
+        help="copy media into the 剪映 draft (default on; portable to another machine)",
+    )
+    review.add_argument(
+        "--jianying-no-bundle-media",
+        action="store_true",
+        help="reference media in place instead of copying it into the draft",
+    )
+
+    materials = parser.add_argument_group("素材库")
+    materials.add_argument(
+        "--material-library-dir",
+        default=None,
+        help="filesystem material library dir (or VIDEO_RECAP_MATERIAL_LIBRARY_DIR)",
+    )
+    materials.add_argument(
+        "--use-materials",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="restore compatible analyzed artifacts from the material library",
+    )
+    materials.add_argument(
+        "--save-materials",
+        action="store_true",
+        help="save analyzed JSON/MD artifacts into the material library",
+    )
+
+    materials.add_argument(
+        "--project",
+        default=None,
+        help="recap_project.json（或其所在目录）：绑定资源库里已采用的字幕样式、包装模板、音色与 BGM",
+    )
+
+    selfcheck = parser.add_argument_group("自检")
+    selfcheck.add_argument("--doctor", action="store_true")
+
+    _record_explicit_options(parser)
+    args = parser.parse_args(argv)
+    args._explicit_options = frozenset(getattr(args, "_explicit_options", ()))
+    return parser, args