@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/video-recap-production/upstream/skills/video-script/references/promotional-copy.md

@@ -0,0 +1,68 @@
+# 宣发标题、花字与文案返修
+
+用户要求宣发选题、标题/封面/发布稿、花字优化，或把外部模型的文案回填时使用。
+只写解说或精修剪点时不增加这一步。
+
+## 先确定这条片卖什么
+
+从当前短片而不是整部剧提炼一个具体观看理由：人物做了什么选择、付出什么代价，
+观众将看懂什么或感受到什么。先标出片内兑现的画面/原声位置，再写承诺。
+同一批可以分别卖关系、选择、笑点、动作或推理，不把每条都套成反转或复仇。
+
+用户需要案例研究时，按发行状态选来源：
+
+- **已播剧**：看本剧社媒的真实讨论、传播切片与观众关注点，再判断当前短片能否承接。
+- **未发布剧**：用剧本特色和片内证据形成受众假设，参考近期成功宣发案例；不假设本剧已有热度。
+
+记录参考物料的发布者、链接、发布日期、采集日期、具体做法及可借部分。
+单条播放、整剧热度、话题聚合量分开写；有数字也不等于证明某句标题带来了成绩。
+旧研究需要更新时再查证；未查到的效果不补数字，离线方案明确只依据已有材料。
+
+## 给其他模型的任务包
+
+按共同剧情与观看理由分组，让每组有足够上下文，但每条分别交付。直接用短 Markdown
+任务包即可，不另造视频时间线。每条提供：
+
+1. **当前版本**：具体工程、对应成片和待渲染修改；有版本号时沿用已有值。
+2. **片内内容**：正文结束点、故事起因与回报、当前选镜、原声/解说字幕、时间属于哪版成片。
+3. **现有文案**：两行标题、花字及其位置/时间、时空提示；封面和发布稿存在时一并给出。
+4. **本轮范围**：允许修改的文字层，以及保留的剪点、字幕、旁白、声音、样式和片尾。
+5. **证据缺口**：角色所说与已发生事实的差别、未出现的结果、模糊专名和未核时码。
+
+附一段可直接使用的要求：
+
+> 先解释这条短片为什么值得点开、看完得到什么，再给主推文案；需要备选时按不同观看理由区分，
+> 不只替换近义词。两行常驻标题、封面字和发布标题各司其职。花字、时空提示分别列修改；
+> 每处给原文、建议、成片位置和片内依据。没有必要就不加花字。只看到工程/字幕时，
+> 时间窗是提案，不能声称已看片。若问题只能靠改镜头或声音解决，单列出来，不用加字掩盖。
+
+## 写字时的分工
+
+| 层 | 工作 | 常见修法 |
+|---|---|---|
+| 常驻标题 | 让陌生观众理解人物处境与本片回报 | 用动作和代价降低人名/术语门槛；不提前宣布未呈现的胜负 |
+| 封面字 | 在封面画面上聚焦一个看点 | 不再塞一遍两行标题；文字需与所选封面帧一致 |
+| 发布标题 | 补关系、背景或观看邀请 | 不把解说全文搬过来，不冒充角色原话 |
+| 花字 | 补必要理解、观察方向或克制的情绪批注 | 不重复对白、不遮关键动作；拥挤时优先撤花字 |
+| 时空提示 | 说明当前/往事、地点或画外判断来源 | 跟随画面切换，不跟跨场旁白提前切换 |
+| 对白/旁白字幕 | 忠实承载当前可听见的话 | 不属于宣发改字范围，不拿新花字覆盖或替代 |
+
+“却”“不是……而是……”不是禁词；当素材没有需要纠正的预期时，直接写行动和后果。
+人物许诺不等于事情已成，单向凝望不等于双方相爱，受伤不等于死亡。
+批量检查重复的是观看理由和句式，不把共享镜头但回报不同的片子合并成同题。
+
+## 回填到当前工程
+
+- 先核任务包对应的工程是否仍是本轮采用基础；已有新剪点、换序、换声或待渲染字幕时，
+  把建议重新对到新版本，不把旧全文覆盖回去，也不凭文件修改时间决定采用。
+- 复制当前工程为新候选，只改本轮采用项；未明确改动的文字、ID、时码、位置和可见性保留。
+  **没提到不等于删除**。`notes=[]` 在提案中可表示不新增；回填完整工程时则是清空整轨，
+  必须先把“保留/新增/替换/删除”逐项说明白。
+- 新增或明确调整花字/时空标的时间时，先对照当前成片的真实画面/台词和帧钟确定出入点；
+  CFR核实际帧，VFR用真实PTS找到对应帧号。建议窗只到小数三位时，不当作已核准的帧级锚点。
+- 使用已有包装工程的字段，不再造一套对白轨：标题、花字、时空提示各写回它们原本所在的层，
+  时间最终写整数半开区间的帧号，不是浮点秒数；工程里指向素材、字幕和样式的引用原样保留。
+  封面与发布稿仍放文案交付，不塞进画面渲染计划。
+- 回填后比较修改前后：逐项核已采用的文字变化、未改层一致、时窗未超正文。已有制作工具先做
+  计划校验；用户只要改轨时到此停止。渲染后再核新字实际出现、遮挡和阅读负担，不能把
+  工程已改叫成片已更新。

package/resources/skills/video-recap-production/upstream/skills/video-script/references/research-guide.md

@@ -0,0 +1,75 @@
+# 写稿前补充调研指南（可选）
+
+开始写稿时先读取已有的 `work_dir/background_research.json`。若理解索引不足以确认作品名、角色关系、剧情前提或科普概念，可在写稿前做一次补充调研，并把可靠结果写回该文件。**新写入的资料不会自动重跑或改写已有 VLM / ASR 产物**；本技能只把它作为 `context-only` 写作与建议型评审背景，当前画面事实仍以时间线证据为准。调研不是必需步骤；没有检索工具、网络不可用或来源不明确时直接跳过。
+
+## 工具选择
+
+使用当前环境里可用的任意检索方式即可，例如：
+
+- Codex / Claude 自带的联网搜索或网页浏览工具
+- 用户已经配置好的浏览器自动化或页面读取工具
+- 普通浏览器手动查找后把结果整理进 JSON
+- 已知资料、用户给的剧情背景或项目内已有文档
+
+## 通用流程
+
+1. 从 `--context`、文件名或用户描述里提取可搜索关键词。
+2. 搜索 1-3 个高价值问题，不要过度调研。
+3. 只记录对解说有帮助的事实：人物关系、剧情前提、世界观、当前集上下文、术语解释。
+4. 写入 `work_dir/background_research.json`。
+5. 把调研结果与 `vlm_analysis.json` / `asr_result.json` 分开使用：前者补背景，后两者证明当前画面与对白。
+6. 如果查不到可靠信息，跳过调研并回到当前创作阶段；若方案尚未完成，先写 `recap_story_plan.json` 与 `visual_audio_board.json`，再按当前 full / cut 阶段写 `narration.json` 或 `clip_plan.json`。
+
+## 按视频类型搜索策略
+
+### 短剧 / 电视剧
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{作品名} 剧情 介绍 人物` | synopsis, characters |
+| `{作品名} 人物 关系` | characters |
+| `{作品名} 第{N}集 剧情` | episode_context |
+
+### 电影
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{电影名} 剧情 简介` | synopsis |
+| `{电影名} 影评 解读` | cultural_notes |
+
+### 纪录片 / 科普视频
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{主题} 背景 知识` | worldbuilding |
+| `{核心概念} 解释` | synopsis |
+| `{主题} 最新 进展` | cultural_notes |
+
+## 写入格式
+
+写入 `work_dir/background_research.json`，只填搜到的字段，未搜到的字段省略，不要写 `null` 或空字符串。
+
+```json
+{
+  "synopsis": "...",
+  "characters": {
+    "角色名": "简介或关系"
+  },
+  "worldbuilding": "...",
+  "episode_context": "...",
+  "cultural_notes": [
+    {"item": "...", "explanation": "..."}
+  ]
+}
+```
+
+## 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| 没有浏览器 / 搜索工具 | 跳过调研，回到当前创作阶段 |
+| 搜索无结果 | 换一组关键词重试一次，仍无结果则回到当前创作阶段 |
+| 结果互相矛盾 | 只使用用户提供的上下文或画面/ASR 可验证的信息 |
+| 信息可能剧透后续 | 只用于理解人物关系，不在解说里剧透用户没要求的后续剧情 |
+
+**原则**：背景资料只能补上下文，不能替代 `vlm_analysis.json` / `asr_result.json` 里的画面和对白证据。

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

@@ -0,0 +1,301 @@
+"""Normalize, split, budget, and de-duplicate narration text."""
+
+import copy
+import re
+
+from lib import CONFIG, log
+from deslop_qc import _sentence_pieces, _text_units
+
+
+def _format_frame_facts(scene):
+    """将帧动作描述格式化为可注入 agent brief 的文本。"""
+    facts = scene.get("frame_facts", {})
+    if not facts:
+        return ""
+    lines = [f"    {ts}s: {'; '.join(facts[ts])}" for ts in sorted(facts, key=float)]
+    return "\n  帧动作:\n" + "\n".join(lines)
+
+
+def _text_char_count(text):
+    """计算文本的有效字数（去除标点和空白，这些不占 TTS 朗读时间）。"""
+    return len(
+        re.sub(
+            r'[，。！？、；：…“”‘’《》〈〉\s"\'「」『』（）()【】\[\]—～·,.!?;:\\-]',
+            "",
+            text,
+        )
+    )
+
+
+def _split_text_by_sentence_windows(text, min_chars=500, max_chars=800):
+    """Clipto-style three-tier sentence boundary splitting for long ASR text."""
+    text = re.sub(r"\s+", " ", text).strip()
+    if not text:
+        return []
+    if _text_units(text) <= max_chars:
+        return _sentence_pieces(text)
+
+    result = []
+    rest = text
+    sentence_marks = "。！？!?；;."
+    while _text_units(rest) > max_chars:
+        # The min/max thresholds are unit-based but punctuation is char-indexed.
+        # For Chinese (the dominant recap target) these are nearly identical; for
+        # non-CJK this remains a safe sentence-boundary heuristic around words.
+        char_min = min(len(rest), max(1, min_chars))
+        char_max = min(len(rest), max(1, max_chars))
+        window = rest[:char_max]
+        cut = max(window.rfind(mark) for mark in sentence_marks)
+        if cut + 1 < char_min:
+            outside = -1
+            for i, ch in enumerate(rest[char_max:], start=char_max):
+                if ch in sentence_marks:
+                    outside = i
+                    break
+            cut = outside if outside >= 0 and outside + 1 <= len(rest) else char_max - 1
+        piece = rest[: cut + 1].strip()
+        if not piece:
+            piece = rest[:char_max].strip()
+            cut = char_max - 1
+        result.append(piece)
+        rest = rest[cut + 1 :].strip()
+    if rest:
+        result.append(rest)
+    return result
+
+
+def _timed_sentence_pieces(seg, min_chars, max_chars):
+    """Split one ASR segment into timed sentence pieces with approximate spans."""
+    text = seg["text"].strip()
+    if not text:
+        return []
+    start, end = seg["start"], seg["end"]
+    pieces = []
+    for sentence in _sentence_pieces(text):
+        if _text_units(sentence) > max_chars:
+            pieces.extend(
+                _split_text_by_sentence_windows(
+                    sentence, min_chars=min_chars, max_chars=max_chars
+                )
+            )
+        else:
+            pieces.append(sentence)
+    total_units = sum(max(1, _text_units(piece)) for piece in pieces)
+    duration = end - start
+    cursor = start
+    timed = []
+    for idx, piece in enumerate(pieces):
+        units = max(1, _text_units(piece))
+        piece_end = end if idx == len(pieces) - 1 else cursor + duration * units / total_units
+        timed.append(
+            {
+                "start": round(cursor, 2),
+                "end": round(piece_end, 2),
+                "text": piece,
+                "char_count": _text_units(piece),
+            }
+        )
+        cursor = piece_end
+    return timed
+
+
+def _scene_ids_for_range(scenes, start, end):
+    duration = max(0.001, end - start)
+    scene_ids = []
+    for scene in scenes:
+        overlap = _overlap_seconds(start, end, scene["start"], scene["end"])
+        # Ignore tiny boundary tails from approximate ASR sentence timing. A
+        # scene id should mean the chunk materially belongs to that scene.
+        if overlap and (overlap >= duration * 0.2 or overlap >= 3.0):
+            scene_ids.append(scene["scene_id"])
+    return scene_ids
+
+
+def _chunk_asr_for_writing(segments, scenes_analysis, min_chars=None, max_chars=None):
+    """Chunk ASR into semantic windows before an agent writes long-dialogue recaps.
+
+    The strategy mirrors Clipto's segment splitter: accumulate a window, prefer
+    the last sentence boundary inside max length, allow a slightly longer first
+    boundary outside the window, and fall back to the remaining text. CJK text is
+    measured by characters; non-CJK text is measured by words.
+    """
+    min_chars = CONFIG["asr_chunk_min_chars"] if min_chars is None else min_chars
+    max_chars = CONFIG["asr_chunk_max_chars"] if max_chars is None else max_chars
+    pieces = [
+        piece
+        for seg in segments
+        for piece in _timed_sentence_pieces(seg, min_chars, max_chars)
+    ]
+
+    chunks = []
+    current = []
+    current_units = 0
+    current_scene_ids = set()
+
+    def flush():
+        nonlocal current, current_units, current_scene_ids
+        if not current:
+            return
+        chunks.append(
+            {
+                "chunk_id": len(chunks),
+                "start": current[0]["start"],
+                "end": current[-1]["end"],
+                "scene_ids": sorted(
+                    current_scene_ids, key=lambda sid: (isinstance(sid, str), sid)
+                ),
+                "char_count": current_units,
+                "text": " ".join(piece["text"] for piece in current).strip(),
+                "segments": current,
+            }
+        )
+        current = []
+        current_units = 0
+        current_scene_ids = set()
+
+    for piece in pieces:
+        units = max(1, piece["char_count"])
+        piece_scene_ids = set(
+            _scene_ids_for_range(scenes_analysis, piece["start"], piece["end"])
+        )
+        crosses_scene = (
+            current
+            and current_scene_ids
+            and piece_scene_ids
+            and not (current_scene_ids & piece_scene_ids)
+        )
+        if crosses_scene and current_units >= min_chars:
+            flush()
+        if current and current_units >= min_chars and current_units + units > max_chars:
+            flush()
+        current.append(piece)
+        current_scene_ids.update(piece_scene_ids)
+        current_units += units
+        if current_units >= max_chars:
+            flush()
+    flush()
+    return chunks
+
+
+def _truncate_at_sentence(text, max_chars):
+    """在句子边界截断，不产生残句。max_chars 按有效字符计（不含标点空白）。"""
+    if _text_char_count(text) <= max_chars:
+        return text
+    eff = 0
+    cutoff = len(text)
+    for i, ch in enumerate(text):
+        eff += 1 if _text_char_count(ch) else 0
+        if eff > max_chars:
+            cutoff = i + 1
+            break
+    idx = max(text[:cutoff].rfind(sep) for sep in ["。", "！", "？", "!", "?"])
+    if idx > 0:
+        return text[: idx + 1]
+    idx = max(text[:cutoff].rfind(sep) for sep in ["，", "、", "；", ","])
+    if idx > 3:
+        return text[:idx] + "。"
+    return ""
+
+
+def _char_bigrams(text):
+    return {text[i : i + 2] for i in range(len(text) - 1) if text[i : i + 2].strip()}
+
+
+def _post_dedup_narration(narration):
+    """去除相邻相似解说段（bigram 重叠 >60% 则合并）。"""
+    if len(narration) < 2:
+        return narration
+    result = [narration[0]]
+    for seg in narration[1:]:
+        prev = result[-1]
+        set_a, set_b = _char_bigrams(prev["narration"]), _char_bigrams(seg["narration"])
+        if not set_a or not set_b:
+            result.append(seg)
+            continue
+        overlap = len(set_a & set_b) / min(len(set_a), len(set_b))
+        # Only merge near-identical adjacent beats. Short Chinese beats share many
+        # bigrams by chance, so a low threshold collapses intentional parallel beats
+        # ("他不再试探" / "他直接赌上全力") and silently drops density below target.
+        if overlap > 0.6:
+            # Validation is also the handoff boundary for renderer metadata: keep the
+            # overlays authored on either merged beat.
+            merged_overlays = copy.deepcopy(
+                prev.get("visual_overlays", []) + seg.get("visual_overlays", [])
+            )
+            if len(seg["narration"]) > len(prev["narration"]):
+                prev["narration"] = seg["narration"]
+            prev["end"] = seg["end"]
+            prev["pause_after_ms"] = seg["pause_after_ms"]
+            if merged_overlays:
+                prev["visual_overlays"] = merged_overlays
+            log(f"  去重合并: {prev['start']:.0f}-{prev['end']:.0f}s")
+        else:
+            result.append(seg)
+    removed = len(narration) - len(result)
+    if removed:
+        log(f"  去重: {len(narration)} → {len(result)} 段 (合并 {removed} 段)")
+    return result
+
+
+def _scene_available_seconds(start, end):
+    return max(0.0, end - start - CONFIG["narration_tail_pad_seconds"])
+
+
+def _recommended_char_budget(start, end):
+    # account for the global narration atempo (CONFIG['narration_speed']) so a beat's text
+    # is budgeted against the FINAL sped-up audio, not the raw TTS rate — otherwise windows
+    # are over-sized and the bed shows long silent gaps between sentences.
+    effective_rate = (
+        CONFIG["speech_rate"] * CONFIG["speech_safety_margin"] * CONFIG["narration_speed"]
+    )
+    return int(_scene_available_seconds(start, end) * effective_rate)
+
+
+def _find_scene_for_midpoint(scenes_analysis, start, end):
+    mid = (start + end) / 2
+    for scene in scenes_analysis:
+        if scene["start"] <= mid <= scene["end"]:
+            return scene
+    return None
+
+
+def _normalise_narration_segment(seg):
+    """Normalize one lint-validated narration segment for the full-mode rewrite.
+
+    Authored timing is a delivery contract: scene boundaries are approximate
+    visual-analysis buckets, so start/end are never clamped here.
+    """
+    item = {
+        "start": round(seg["start"], 2),
+        "end": round(seg["end"], 2),
+        "narration": str(seg["narration"]).strip(),
+        "pause_after_ms": int(seg.get("pause_after_ms", CONFIG["breath_ms"])),
+        "overlaps_speech": bool(seg.get("overlaps_speech", True)),
+    }
+    for optional_key in (
+        "source_start",
+        "source_end",
+        "source_clip_id",
+        "source_entry_policy",
+        "source_entry_reason",
+    ):
+        if optional_key in seg:
+            item[optional_key] = seg[optional_key]
+    # carry the per-beat emotion/tone tag (MiMo TTS instruct) through lint untouched
+    if seg.get("emotion"):
+        item["emotion"] = seg["emotion"].strip()
+    # Renderer-owned metadata survives the validation rewrite; the recap orchestrator
+    # filters supported overlay kinds later.
+    if "visual_overlays" in seg:
+        item["visual_overlays"] = copy.deepcopy(seg["visual_overlays"])
+    return item
+
+
+def _clean_narration_punctuation(text):
+    text = re.sub(r"\s+", " ", text).strip()
+    text = re.sub(r'[，：、；,]["\']?[。！？]', "。", text)
+    return re.sub(r'["\']。$', "。", text)
+
+
+def _overlap_seconds(start, end, other_start, other_end):
+    return max(0.0, min(end, other_end) - max(start, other_start))

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

@@ -0,0 +1,211 @@
+"""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]:
+    """Split text into sentence-like pieces while keeping terminal punctuation."""
+    text = re.sub(r"\s+", " ", text).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:
+    """Length unit for prose: CJK characters, otherwise words."""
+    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: list[dict[str, Any]], *, source: str) -> list[dict[str, Any]]:
+    key = "narration" if source == "narration" else "text"
+    segments: list[dict[str, Any]] = []
+    for idx, item in enumerate(payload):
+        text = str(item.get(key, "")).strip()
+        if text:
+            segments.append({"source": source, "index": idx, "text": text})
+    return segments
+
+
+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 []
+    return _normalise_segments(json.loads(path.read_text(encoding="utf-8")), source="original_subtitles")
+
+
+def _style_card_requirement(work_dir: Path | None) -> tuple[bool, str]:
+    """Read the explicit requirements contract; workspaces without one are advisory-only."""
+    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 = json.loads(path.read_text(encoding="utf-8"))
+    return data["style_card_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
+    severity = "blocker" if required else "advisory"
+    path = work_dir / "style_card.json"
+    if not path.exists():
+        return {
+            "severity": severity,
+            "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 = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(data, dict) or not data:
+        return {
+            "severity": severity,
+            "code": "malformed_style_card",
+            "source": "style_card",
+            "index": None,
+            "message": (
+                "style_card.json is required but empty or not a JSON object"
+                if required else
+                "style_card.json is present but empty or not a JSON object; treat as migration warning unless the run requires it"
+            ),
+        }
+    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: list[dict[str, Any]], *, work_dir: str | Path | None = None, original_subtitles: list[dict[str, Any]] | None = 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]["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"]