@oh-story/dsh 0.1.3 → 0.1.5

package/lib/video-recap/skills/video-script/scripts/brief_timeline.py

@@ -0,0 +1,442 @@
+"""Remap cut evidence and format output-timeline brief directives."""
+
+import importlib.util
+
+
+import json
+
+import math
+
+import re
+
+from pathlib import Path
+
+from lib import CONFIG, stable_hash
+
+
+try:
+    from deslop_qc import analyze_deslop_qc
+except ModuleNotFoundError:
+    _deslop_qc_path = Path(__file__).with_name("deslop_qc.py")
+    _deslop_qc_spec = importlib.util.spec_from_file_location(
+        "deslop_qc", _deslop_qc_path
+    )
+    if _deslop_qc_spec is None or _deslop_qc_spec.loader is None:
+        raise
+    _deslop_qc_module = importlib.util.module_from_spec(_deslop_qc_spec)
+    _deslop_qc_spec.loader.exec_module(_deslop_qc_module)
+    analyze_deslop_qc = _deslop_qc_module.analyze_deslop_qc
+
+
+def _parse_target_seconds(value):
+    """Parse a cut-mode target duration ("30m" / "600" / "1h5m" / "00:30:00") to seconds.
+
+    Mirrors the local clip-plan contract closely enough to size the brief; returns None
+    on unparseable input so the brief simply falls back to the source duration.
+    """
+    if value is None:
+        return None
+    if isinstance(value, (int, float)):
+        return float(value) if value > 0 else None
+    text = str(value).strip().lower()
+    if not text:
+        return None
+    try:
+        if ":" in text:
+            parts = [float(p) for p in text.split(":")]
+            if any(p < 0 for p in parts):
+                return None
+            if len(parts) == 2:
+                seconds = parts[0] * 60 + parts[1]
+            elif len(parts) == 3:
+                seconds = parts[0] * 3600 + parts[1] * 60 + parts[2]
+            else:
+                return None
+            return seconds if seconds > 0 else None
+        factors = {"ms": 0.001, "s": 1, "m": 60, "h": 3600}
+        seconds = 0.0
+        matched = False
+        pos = 0
+        for m in re.finditer(r"([0-9]+(?:\.[0-9]+)?)(ms|s|m|h)?", text):
+            if m.start() != pos:
+                break
+            pos = m.end()
+            matched = True
+            seconds += float(m.group(1)) * factors[m.group(2) or "s"]
+        if not matched or pos != len(text):
+            return None
+        return seconds if seconds > 0 else None
+    except (ValueError, TypeError):
+        return None
+
+
+def _format_research_directive(work_dir, substrate):
+    """A loud, actionable research-first directive — but ONLY when the substrate is too thin
+    for real commentary (no dialogue/story spine) and no background_research.json exists yet.
+
+    The narration's quality ceiling is how much story context the agent has: with only frame
+    descriptions it can only narrate pixels, so research the title FIRST (see
+    references/research-guide.md). Fires only for thin/empty substrate — NOT merely because a
+    title was given — so a dialogue-rich titled run is never nagged.
+    """
+    if (Path(work_dir) / "background_research.json").exists():
+        return []  # already researched; _format_background_research surfaces it
+    if not (substrate and substrate.get("level") in ("thin", "empty")):
+        return []  # rich enough to write from dialogue/spine; do not nag
+    context = str(CONFIG.get("context_info") or "").strip()
+    return [
+        "## ⚑ Research the story FIRST (do this before writing narration)",
+        "",
+        "Reason: the understanding substrate is thin — no dialogue/story spine, only frame",
+        "descriptions, so without research the narration can only describe pixels.",
+        "1. Pull the title/keywords from `--context`, the filename, or the user's description"
+        + (f" (context: {context})." if context else "."),
+        "2. Use any available web-search/browser tool to look up synopsis, characters, and",
+        "   relationships (see `references/research-guide.md`).",
+        "3. Write `work_dir/background_research.json`, then re-read this brief and write narration",
+        "   that names people and reads the picture through the plot.",
+        "4. If no tool/network or nothing found: skip — keep beats sparse and strictly grounded in",
+        "   the visible ASR/frame evidence rather than inventing drama.",
+        "",
+    ]
+
+
+def _load_cut_output_spans_for_brief(work_dir, *, required=False):
+    """Load fresh source→output spans for cut pass 2 brief evidence.
+
+    Pass 2 narration is authored against edited_source.mp4's OUTPUT timeline, so
+    ASR chunks and timeline_fusion must use the same OUTPUT clock. Before pass 2
+    (no edited_source.mp4 yet), callers may fall back to source-time evidence; once
+    pass 2 exists, missing/stale validated spans are a hard contract failure.
+    """
+
+    def fail(reason):
+        if required:
+            raise SystemExit(
+                "cut pass2 brief requires fresh clip_plan_validated.json with explicit "
+                f"finite source/output spans ({reason})"
+            )
+        return None
+
+    work_dir = Path(work_dir)
+    if not (work_dir / "edited_source.mp4").exists():
+        return None
+    validated_path = work_dir / "clip_plan_validated.json"
+    if not validated_path.exists():
+        return fail("missing clip_plan_validated.json")
+    try:
+        plan = json.loads(validated_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return fail("invalid clip_plan_validated.json")
+    if not isinstance(plan, dict):
+        return fail("clip_plan_validated.json is not an object")
+    raw_path = work_dir / "clip_plan.json"
+    if raw_path.exists():
+        try:
+            raw_plan = json.loads(raw_path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return fail("invalid clip_plan.json")
+        if plan.get("raw_plan_fingerprint") != stable_hash(raw_plan):
+            return fail("stale clip_plan_validated.json")
+    clips = plan.get("clips")
+    if not isinstance(clips, list):
+        return fail("clips is not a list")
+    spans = []
+    for clip in clips:
+        if not isinstance(clip, dict):
+            continue
+        if not all(
+            key in clip
+            for key in ("source_start", "source_end", "output_start", "output_end")
+        ):
+            return fail("clip missing source/output span fields")
+        try:
+            ss = float(clip["source_start"])
+            se = float(clip["source_end"])
+            os_ = float(clip["output_start"])
+            oe = float(clip["output_end"])
+        except (TypeError, ValueError):
+            return fail("non-numeric clip span")
+        if not all(math.isfinite(x) for x in (ss, se, os_, oe)):
+            return fail("non-finite clip span")
+        if se <= ss or oe <= os_:
+            return fail("non-positive clip span")
+        spans.append(
+            {
+                "source_start": ss,
+                "source_end": se,
+                "output_start": os_,
+                "output_end": oe,
+            }
+        )
+    return spans or fail("no valid clips")
+
+
+def _source_output_overlaps_for_brief(start, end, spans):
+    overlaps = []
+    for span in spans or []:
+        source_start = max(float(start), span["source_start"])
+        source_end = min(float(end), span["source_end"])
+        if source_end <= source_start:
+            continue
+        output_start = span["output_start"] + (source_start - span["source_start"])
+        output_end = span["output_start"] + (source_end - span["source_start"])
+        overlaps.append(
+            {
+                "source_start": source_start,
+                "source_end": source_end,
+                "output_start": output_start,
+                "output_end": output_end,
+            }
+        )
+    return overlaps
+
+
+def _remap_frame_facts_for_brief(frame_facts, overlap):
+    if not isinstance(frame_facts, dict):
+        return frame_facts
+    out = {}
+    for raw_ts, vals in frame_facts.items():
+        try:
+            ts = float(raw_ts)
+        except (TypeError, ValueError):
+            continue
+        if not (overlap["source_start"] <= ts <= overlap["source_end"]):
+            continue
+        out_ts = overlap["output_start"] + (ts - overlap["source_start"])
+        out[f"{out_ts:.3f}"] = vals
+    return out
+
+
+def _remap_scenes_to_output_for_brief(scenes, spans):
+    if not spans:
+        return scenes or []
+    out = []
+    for scene in scenes or []:
+        if not isinstance(scene, dict):
+            continue
+        try:
+            start = float(scene.get("start", 0))
+            end = float(scene.get("end", start))
+        except (TypeError, ValueError):
+            continue
+        overlaps = _source_output_overlaps_for_brief(start, end, spans)
+        for part_idx, overlap in enumerate(overlaps):
+            item = dict(scene)
+            item["start"] = round(overlap["output_start"], 3)
+            item["end"] = round(overlap["output_end"], 3)
+            item["frame_facts"] = _remap_frame_facts_for_brief(
+                scene.get("frame_facts"), overlap
+            )
+            if len(overlaps) > 1:
+                item["scene_id"] = f"{scene.get('scene_id', '?')}.{part_idx}"
+            out.append(item)
+    out.sort(key=lambda x: (float(x.get("start", 0)), float(x.get("end", 0))))
+    return out
+
+
+def _remap_segments_to_output_for_brief(segments, spans):
+    if not spans:
+        return segments or []
+    out = []
+    for seg in segments or []:
+        if not isinstance(seg, dict):
+            continue
+        try:
+            start = float(seg.get("start", 0))
+            end = float(seg.get("end", start))
+        except (TypeError, ValueError):
+            continue
+        if end <= start:
+            continue
+        for overlap in _source_output_overlaps_for_brief(start, end, spans):
+            item = dict(seg)
+            item["start"] = round(overlap["output_start"], 3)
+            item["end"] = round(overlap["output_end"], 3)
+            if "duration" in item:
+                item["duration"] = round(item["end"] - item["start"], 3)
+            out.append(item)
+    out.sort(key=lambda x: (float(x.get("start", 0)), float(x.get("end", 0))))
+    return out
+
+
+def _remap_brief_evidence_to_output_timeline(
+    work_dir, scenes_analysis, asr_result, silence_periods, *, required=False
+):
+    spans = _load_cut_output_spans_for_brief(work_dir, required=required)
+    if not spans:
+        return scenes_analysis, asr_result, silence_periods
+    return (
+        _remap_scenes_to_output_for_brief(scenes_analysis, spans),
+        _remap_segments_to_output_for_brief(asr_result, spans),
+        _remap_segments_to_output_for_brief(silence_periods, spans),
+    )
+
+
+def _sentence_entry_anchors_for_brief(work_dir, edit_mode):
+    """Load sentence anchors and remap them to cut OUTPUT time when needed."""
+    work_dir = Path(work_dir)
+    source_path = work_dir / "speech_boundary_anchors.json"
+    try:
+        payload = json.loads(source_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        payload = {}
+    anchors = payload.get("sentence_anchors", []) if isinstance(payload, dict) else []
+    anchors = [dict(item) for item in anchors if isinstance(item, dict)]
+    if edit_mode != "cut" or not (work_dir / "edited_source.mp4").exists():
+        return anchors
+
+    spans = _load_cut_output_spans_for_brief(work_dir, required=True)
+    remapped = []
+    for anchor in anchors:
+        try:
+            source_time = float(anchor.get("time"))
+        except (TypeError, ValueError):
+            continue
+        for span in spans:
+            if span["source_start"] - 0.05 <= source_time <= span["source_end"] + 0.05:
+                item = dict(anchor)
+                item["source_time"] = round(source_time, 3)
+                item["time"] = round(
+                    span["output_start"] + source_time - span["source_start"], 3
+                )
+                try:
+                    source_pause_start = float(
+                        anchor.get("pause_start", source_time - 0.12)
+                    )
+                except (TypeError, ValueError):
+                    source_pause_start = source_time - 0.12
+                # Preserve the measured safe pause in OUTPUT time too. Leaving pause_start
+                # in SOURCE time made cut-mode lint compare two different clocks.
+                source_pause_start = max(
+                    span["source_start"], min(source_pause_start, source_time)
+                )
+                item["source_pause_start"] = round(source_pause_start, 3)
+                item["pause_start"] = round(
+                    span["output_start"] + source_pause_start - span["source_start"], 3
+                )
+                remapped.append(item)
+
+    speech_rows = []
+    for name in ("asr_result.json", "asr_clean.json"):
+        try:
+            raw = json.loads((work_dir / name).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(raw, dict):
+            raw = raw.get("segments", [])
+        if isinstance(raw, list):
+            candidate = [
+                item
+                for item in raw
+                if isinstance(item, dict) and str(item.get("text") or "").strip()
+            ]
+            if candidate:
+                speech_rows = candidate
+                break
+    try:
+        raw_quiet = json.loads(
+            (work_dir / "silence_periods.json").read_text(encoding="utf-8")
+        )
+    except (OSError, json.JSONDecodeError):
+        raw_quiet = []
+    quiet_rows = [
+        item
+        for item in raw_quiet
+        if isinstance(item, dict) and not bool(item.get("has_speech", False))
+    ] if isinstance(raw_quiet, list) else []
+    out_payload = {
+        "schema_version": 2,
+        "artifact": "speech_boundary_anchors_output.json",
+        "timeline": "cut_output",
+        "source_artifact": "speech_boundary_anchors.json",
+        "clip_plan_fingerprint": stable_hash(
+            json.loads((work_dir / "clip_plan_validated.json").read_text(encoding="utf-8"))
+        ),
+        "sentence_anchors": sorted(remapped, key=lambda item: float(item["time"])),
+        "speech_spans": _remap_segments_to_output_for_brief(speech_rows, spans),
+        "quiet_windows": _remap_segments_to_output_for_brief(quiet_rows, spans),
+    }
+    (work_dir / "speech_boundary_anchors_output.json").write_text(
+        json.dumps(out_payload, ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    return out_payload["sentence_anchors"]
+
+
+def _format_sentence_entry_anchors_for_brief(work_dir, edit_mode):
+    anchors = []
+    for anchor in _sentence_entry_anchors_for_brief(work_dir, edit_mode):
+        if anchor.get("confidence") not in {"high", "medium"}:
+            continue
+        try:
+            when = float(anchor.get("time"))
+        except (TypeError, ValueError):
+            continue
+        anchors.append((when, anchor))
+    if not anchors:
+        return []
+    lines = [
+        "## 原声句末安全切入点",
+        "",
+        "这些时间是 ASR 句末标点与短声学停顿对齐后的旁白安全入口。旁白在原声已开始后切入时，"
+        "必须从其中一个点开始；否则会在 TTS 前被 `interrupts_source_sentence` 硬阻断。",
+        "- 调整方式：优先把 `start` 移到建议锚点；放不下时缩短文本、移动整块或删除该旁白，不能让脚本静默挪音频。",
+        '- 原声句子完整性是硬约束：切入块写 `"source_entry_policy": "sentence_boundary"`；'
+        "不存在 `intentional_interrupt` 绕过方式。没有后续可靠句末锚点时，移动、缩短或删除旁白块。",
+    ]
+    for when, anchor in anchors:
+        tail = str(anchor.get("text_tail") or "").strip()
+        confidence = anchor.get("confidence", "unknown")
+        source_suffix = ""
+        if "source_time" in anchor:
+            source_suffix = f" (SOURCE {float(anchor['source_time']):.2f}s)"
+        lines.append(f"- {when:.2f}s [{confidence}]{source_suffix} {tail}")
+    lines.append("")
+    return lines
+
+
+def _format_output_clip_list(work_dir):
+    """List the kept clips on the OUTPUT timeline (cut-first/narrate-second pass 2), so the
+    agent narrates against the real rendered cut instead of the source timeline."""
+    path = Path(work_dir) / "clip_plan_validated.json"
+    if not path.exists():
+        return []
+    try:
+        plan = json.loads(path.read_text(encoding="utf-8"))
+    except (ValueError, OSError):
+        return []
+    clips = (plan.get("clips") if isinstance(plan, dict) else plan) or []
+    out = ["## Kept clips on the OUTPUT timeline", ""]
+    for c in clips:
+        if not isinstance(c, dict):
+            continue
+        try:
+            os_, oe = float(c.get("output_start")), float(c.get("output_end"))
+            ss, se = float(c.get("source_start")), float(c.get("source_end"))
+        except (TypeError, ValueError):
+            continue
+        reason = str(c.get("reason", "")).strip()
+        source_id = c.get("source_id", c.get("source", "0"))
+        clip_id = c.get("id", c.get("clip_id", "?"))
+        out.append(
+            f"- OUTPUT {os_:.1f}–{oe:.1f}s ← SOURCE[{source_id}] {ss:.1f}–{se:.1f}s (clip_id={clip_id})"
+            + (f" — {reason}" if reason else "")
+        )
+    out.append("")
+    return out if len(out) > 2 else []
+
+
+def _write_deslop_qc_requirements(work_dir):
+    """Write the stable deslop QC contract consumed by deslop_qc.py.
+
+    style_card_required defaults to False (advisory): a missing style_card.json is a
+    warning, not a render-blocking error. A future opt-in run can set it True to make
+    style_card.json a hard requirement — deslop_qc.py reads that field.
+    """
+    payload = {
+        "schema_version": 1,
+        "style_card_required": False,
+    }
+    path = Path(work_dir) / "deslop_qc_requirements.json"
+    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
+    return path

package/lib/video-recap/skills/video-script/scripts/deslop_qc.py

@@ -0,0 +1,237 @@
+"""Deterministic narration readability/QC scanner.
+
+This module is intentionally report-only. It flags local readability and
+packaging hygiene risks for video narration; it is not an AIGC detector and it
+never rewrites text.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+CONTRACT = (
+    "Local readability/QC report only: this is not an AIGC detector, does not "
+    "claim AI-generation accuracy, and never rewrites text. Corrections remain "
+    "human/agent rewrite work."
+)
+
+EM_DASH_RE = re.compile(r"——|—")
+NEGATIVE_FLIP_RE = re.compile(r"并?不是[^。！？!?；;\.]{0,40}而是")
+# Catch verbatim copy of the brief's example scaffolding without over-matching real text.
+# The bracketed role token 【主角】 is the placeholder; anchor the pronoun signal to the
+# example's exact phrase "TA要赌上" so the legitimate gender-neutral pronoun "TA" (他/她) +
+# 要 (idiomatic 解说 suspense device "凶手就在其中，TA要做的下一件事…") is NOT hard-blocked.
+PLACEHOLDER_RE = re.compile(r"【主角】|TA要赌上")
+
+CLICHE_TERMS = [
+    "命运的齿轮", "殊不知", "与此同时", "一场阴谋", "背后真相", "不为人知",
+    "故事就此展开", "命运", "真相", "秘密", "危机", "反转", "救赎",
+]
+ABSTRACT_TERMS = ["人性", "成长", "救赎", "命运", "时代", "宿命", "选择", "意义", "价值", "情感"]
+REASONING_MARKERS = ["因为", "所以", "因此", "也就是说", "换句话说", "这意味着", "原因是", "可见"]
+METAPHOR_MARKERS = ["像", "仿佛", "好似", "犹如", "如同", "一把", "一场", "一张", "棋局", "风暴"]
+CONNECTIVE_MARKERS = ["但", "却", "而", "于是", "随后", "直到", "结果", "因为", "所以", "这时", "最后"]
+
+
+def _sentence_pieces(text: str) -> list[str]:
+    text = re.sub(r"\s+", " ", str(text or "")).strip()
+    if not text:
+        return []
+    parts = re.split(r"([。！？!?；;\.])", text)
+    out: list[str] = []
+    for idx in range(0, len(parts), 2):
+        body = parts[idx].strip()
+        punct = parts[idx + 1] if idx + 1 < len(parts) else ""
+        if body or punct:
+            out.append((body + punct).strip())
+    return out or [text]
+
+
+def _text_units(text: str) -> int:
+    text = str(text or "")
+    if re.search(r"[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]", text):
+        return len(re.sub(r"\s+", "", text))
+    return len(re.findall(r"\b\w+\b", text))
+
+
+def _normalise_segments(payload: Any, *, source: str) -> list[dict[str, Any]]:
+    if isinstance(payload, str):
+        return [{"source": source, "index": None, "text": payload}]
+    if not isinstance(payload, list):
+        return []
+    segments: list[dict[str, Any]] = []
+    for idx, item in enumerate(payload):
+        if isinstance(item, dict):
+            key = "narration" if source == "narration" else "text"
+            text = str(item.get(key, item.get("text", item.get("narration", ""))) or "").strip()
+        else:
+            text = str(item or "").strip()
+        if text:
+            segments.append({"source": source, "index": idx, "text": text})
+    return segments
+
+
+def _load_json(path: Path) -> tuple[Any, str | None]:
+    try:
+        return json.loads(path.read_text(encoding="utf-8")), None
+    except Exception as exc:  # intentionally broad: malformed artifacts are QC findings
+        return None, str(exc)
+
+
+def _load_original_subtitles(work_dir: Path | None) -> list[dict[str, Any]]:
+    if work_dir is None:
+        return []
+    path = work_dir / "original_subtitles.json"
+    if not path.exists():
+        return []
+    data, err = _load_json(path)
+    if err:
+        return []
+    return _normalise_segments(data, source="original_subtitles")
+
+
+def _style_card_requirement(work_dir: Path | None) -> tuple[bool, str]:
+    """Read the explicit stable requirements contract.
+
+    Legacy/migration workspaces that do not have a valid requirements file are
+    advisory-only: they must not be hard-gated by prompt text in
+    agent_narration_brief.md.
+    """
+    if work_dir is None:
+        return False, "legacy_default"
+    path = work_dir / "deslop_qc_requirements.json"
+    if not path.exists():
+        return False, "legacy_default"
+    data, err = _load_json(path)
+    if err is not None or not isinstance(data, dict):
+        return False, "legacy_default"
+    required = data.get("style_card_required")
+    if not isinstance(required, bool):
+        return False, "legacy_default"
+    return required, "deslop_qc_requirements.json"
+
+
+def _style_card_issue(work_dir: Path | None, required: bool) -> dict[str, Any] | None:
+    if work_dir is None:
+        return None
+    path = work_dir / "style_card.json"
+    if not path.exists():
+        return {
+            "severity": "blocker" if required else "advisory",
+            "code": "missing_style_card",
+            "source": "style_card",
+            "index": None,
+            "message": (
+                "style_card.json is required by this expression/packaging run but is missing"
+                if required else
+                "style_card.json is absent; legacy/migration workspaces may continue, but new expression-special runs should author it"
+            ),
+        }
+    data, err = _load_json(path)
+    if err is not None or not isinstance(data, dict) or not data:
+        return {
+            "severity": "blocker" if required else "advisory",
+            "code": "malformed_style_card",
+            "source": "style_card",
+            "index": None,
+            "message": (
+                "style_card.json is required but missing, malformed, empty, or not a JSON object"
+                if required else
+                "style_card.json is present but malformed/empty; treat as migration warning unless the run requires it"
+            ),
+            "detail": err,
+        }
+    return None
+
+
+def _add_issue(bucket: list[dict[str, Any]], severity: str, code: str, source: str, index: int | None, message: str, **extra: Any) -> None:
+    issue = {"severity": severity, "code": code, "source": source, "index": index, "message": message}
+    issue.update({k: v for k, v in extra.items() if v is not None})
+    bucket.append(issue)
+
+
+def analyze_deslop_qc(narration: Any, *, work_dir: str | Path | None = None, original_subtitles: Any = None) -> dict[str, Any]:
+    """Return a structured report; never mutates or rewrites input text."""
+    work_path = Path(work_dir) if work_dir is not None else None
+    segments = _normalise_segments(narration, source="narration")
+    if original_subtitles is None:
+        segments.extend(_load_original_subtitles(work_path))
+    else:
+        segments.extend(_normalise_segments(original_subtitles, source="original_subtitles"))
+
+    blockers: list[dict[str, Any]] = []
+    advisories: list[dict[str, Any]] = []
+
+    required, requirement_source = _style_card_requirement(work_path)
+    style_issue = _style_card_issue(work_path, required)
+    if style_issue:
+        (blockers if style_issue["severity"] == "blocker" else advisories).append(style_issue)
+
+    all_text = "\n".join(seg["text"] for seg in segments)
+    total_units = max(1, _text_units(all_text))
+    sentences: list[str] = []
+    for seg in segments:
+        text = seg["text"]
+        if EM_DASH_RE.search(text):
+            _add_issue(blockers, "blocker", "em_dash", seg["source"], seg["index"], "破折号（—/——）不得出现在 narration/original_subtitles 中", matches=EM_DASH_RE.findall(text))
+        if PLACEHOLDER_RE.search(text):
+            _add_issue(blockers, "blocker", "placeholder_leakage", seg["source"], seg["index"], "示例占位内容泄漏到成稿中（如【主角】/TA要赌上）", matches=PLACEHOLDER_RE.findall(text))
+        for sentence in _sentence_pieces(text):
+            sentences.append(sentence)
+            if NEGATIVE_FLIP_RE.search(sentence):
+                _add_issue(advisories, "advisory", "negative_positive_flip", seg["source"], seg["index"], "“不是…而是…”模板化转折偏多，建议改成更具体的因果/行动表达", sentence=sentence[:120])
+
+    def term_count(terms: list[str]) -> int:
+        return sum(all_text.count(term) for term in terms)
+
+    cliche_count = term_count(CLICHE_TERMS)
+    abstract_count = term_count(ABSTRACT_TERMS)
+    reasoning_count = term_count(REASONING_MARKERS)
+    metaphor_count = term_count(METAPHOR_MARKERS)
+    connective_count = term_count(CONNECTIVE_MARKERS)
+
+    if cliche_count >= 4 or (cliche_count / total_units) > 0.025:
+        _add_issue(advisories, "advisory", "cliche_density", "narration", None, "套话/高频抽象词偏密，建议换成具体行动、选择和后果", count=cliche_count)
+    if abstract_count >= 5 or (abstract_count / total_units) > 0.03:
+        _add_issue(advisories, "advisory", "abstract_summary", "narration", None, "抽象总结词偏多，容易像概括论文；补足画面证据和具体抉择", count=abstract_count)
+    if reasoning_count >= 4:
+        _add_issue(advisories, "advisory", "reasoning_chain", "narration", None, "解释链标记偏多，建议减少“因为/所以/这意味着”等讲理口吻", count=reasoning_count)
+    if metaphor_count >= 4:
+        _add_issue(advisories, "advisory", "metaphor_markers", "narration", None, "比喻/包装化标记偏多，确认没有遮住剧情事实", count=metaphor_count)
+    if total_units >= 180 and connective_count <= 1:
+        _add_issue(advisories, "advisory", "low_connective_density", "narration", None, "长文本缺少转折/因果连接，可能像平铺摘要", connective_count=connective_count)
+
+    long_segments = [seg for seg in segments if seg["source"] == "narration" and _text_units(seg["text"]) > 180]
+    if long_segments:
+        _add_issue(advisories, "advisory", "overlong_narration_block", "narration", long_segments[0].get("index"), "单个解说块过长，建议拆成更可听的段落", max_units=max(_text_units(seg["text"]) for seg in long_segments))
+    long_sentences = [s for s in sentences if _text_units(s) > 90]
+    if long_sentences:
+        _add_issue(advisories, "advisory", "long_paragraph", "narration", None, "长句/长段落偏多，字幕阅读压力较大", max_units=max(_text_units(s) for s in long_sentences))
+
+    return {
+        "ok": not blockers,
+        "contract": CONTRACT,
+        "scanner": "deslop_qc.py",
+        "style_card_required": required,
+        "style_card_requirement_source": requirement_source,
+        "blocker_count": len(blockers),
+        "advisory_count": len(advisories),
+        "blockers": blockers,
+        "advisories": advisories,
+        "metrics": {
+            "segments_scanned": len(segments),
+            "text_units": total_units if all_text else 0,
+            "sentence_count": len(sentences),
+            "cliche_count": cliche_count,
+            "abstract_count": abstract_count,
+            "reasoning_marker_count": reasoning_count,
+            "metaphor_marker_count": metaphor_count,
+            "connective_count": connective_count,
+        },
+    }
+
+
+__all__ = ["CONTRACT", "analyze_deslop_qc"]