@oh-story/dsh 0.1.11 → 0.1.13

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

@@ -73,11 +73,6 @@ def _env_number(name, default, cast, minimum):
     return value
 
 
-def env_int(name, default, *, minimum=None):
-    """Read an integer env var, rejecting malformed or below-minimum values."""
-    return _env_number(name, default, int, minimum)
-
-
 def env_bool(name, default=False):
     """Read common boolean env var forms."""
     raw = os.environ.get(name)
@@ -120,9 +115,6 @@ CONFIG = {
     "quiet_overlap_min_ratio": 0.8,  # 解说段至少多少比例落在安静窗口内才标记为非对白重叠
     "visual_beat_max_seconds": 18.0,  # 单段解说超过该时长且跨多个帧锚点时给 lint 提醒
     "visual_beat_max_facts": 3,  # 单段解说最多建议覆盖的 frame_facts 锚点数量
-    "asr_chunk_min_chars": env_int("ASR_CHUNK_MIN_CHARS", 500, minimum=1),  # brief 中 ASR 写作分块最小字数/词数
-    "asr_chunk_max_chars": env_int("ASR_CHUNK_MAX_CHARS", 800, minimum=1),  # brief 中 ASR 写作分块最大字数/词数
-    "edit_mode": os.environ.get("EDIT_MODE", "full"),  # full | cut
 }
 
 def log(msg):
@@ -165,9 +157,8 @@ def _sanitize_api_error(value, limit=500):
     text = _ERROR_KEY_RE.sub("<redacted-key>", text)
     return text[:limit]
 
-def _api_headers(api_provider=None, api_url=None, api_key=None):
+def _api_headers(api_key=None):
     """Build MiMo auth headers (OpenAI-compatible chat/completions with an api-key header)."""
-    del api_provider, api_url  # MiMo is the only provider; signature kept for call sites
     key = CONFIG["api_key"] if api_key is None else api_key
     return {
         "Content-Type": "application/json",
@@ -175,9 +166,8 @@ def _api_headers(api_provider=None, api_url=None, api_key=None):
         "api-key": key,
     }
 
-def _prepare_api_payload(payload, api_provider=None, api_url=None):
+def _prepare_api_payload(payload):
     """Normalize payload fields for MiMo's OpenAI-compatible chat/completions API."""
-    del api_provider, api_url
     normalized = dict(payload)
     if "max_tokens" in normalized and "max_completion_tokens" not in normalized:
         normalized["max_completion_tokens"] = normalized.pop("max_tokens")
@@ -192,15 +182,15 @@ def _prepare_api_payload(payload, api_provider=None, api_url=None):
         normalized["thinking"] = {"type": "disabled"}
     return normalized
 
-def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key=None, api_env_var=None):
+def api_call(payload, max_retries=8, *, api_url=None, api_key=None, api_env_var=None):
     """调用 OpenAI-compatible API，带重试。
 
     集群的 429 限流是常态而非错误，所以重试更耐心（更多次数 + 退避封顶 60s + 遵从 Retry-After），
     避免一次瞬时限流就中止整个阶段。配额窗口常以分钟计，所以 429 在没有 Retry-After 时也至少等 10s。
     """
     endpoint = normalize_api_url(api_url if api_url is not None else CONFIG["api_url"])
-    headers = _api_headers(api_provider=api_provider, api_url=endpoint, api_key=api_key)
-    data = json.dumps(_prepare_api_payload(payload, api_provider=api_provider, api_url=endpoint)).encode("utf-8")
+    headers = _api_headers(api_key=api_key)
+    data = json.dumps(_prepare_api_payload(payload)).encode("utf-8")
 
     for attempt in range(max_retries):
         try:

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

@@ -0,0 +1,184 @@
+"""Render a narration lint report as the compact lines the author reads on the console.
+
+narration_lint.json keeps every field; this summary repeats, per flagged block, the
+numbers needed to fix it without opening that file. Errors (failed lint) and warnings
+(passed lint) use the same line format. Block numbers are 1-based ("段 N",
+the block's position in narration.json); the report's `index` fields stay 0-based. A
+deslop blocker found in original_subtitles.json carries `source: "original_subtitles"`
+and an index into that file, so it is labelled "原声字幕第 N 条", never "段 N".
+"""
+
+MAX_LISTED_ERRORS = 12
+
+_HINTS = {
+    "over_budget": "缩短文字，或放宽/挪动时间窗",
+    "interrupts_source_sentence": "把整块（时长不变）挪到建议的时间窗；没有建议入点时缩短、挪走或删掉这块",
+    "source_sentence_anchors_unavailable": "挪走或删掉这块，或重新生成含句尾锚点的语音证据",
+    "time_overlap": "调整时间窗，让两块不重叠",
+    "out_of_order": "按 start 从小到大排列各块",
+    "outside_clip_plan": "把这块挪进某个选中片段的时间范围",
+    "ambiguous_source_clip": "给这块写 source_clip_id",
+    "em_dash": "删掉破折号，改用逗号、句号或把句子拆开",
+    "placeholder_leakage": "把示例占位（如【主角】）换成真实人名或内容",
+    "slot_too_short": "放宽时间窗，或把这块并进相邻块",
+    "incomplete_sentence": "用句号、问号或感叹号收尾",
+    "outside_scene": "核对时间，确认这块对应哪段画面",
+    "crosses_scene_boundary": "把这块收进所在场景，或在场景切换处拆成两块",
+    "visual_beat_too_broad": "拆块或收紧时间窗，让旁白贴着当前画面",
+    "crosses_clip_boundary": "把这块收进所在片段，超出部分会被裁掉",
+    "no_original_blocks": "在几个强原声时刻不写旁白，让原声满音量播放",
+    "under_narrated": "确认每个长空档都有意交给原声；只在有明确解说任务时加块",
+    "no_original_breaks": "在块之间留几个多秒的空档给原声",
+    "fragmented_beats": "把相邻、讲同一件事的短句并成一块",
+}
+
+_ORIGINAL_SUBTITLE_HINTS = {
+    "em_dash": "在 original_subtitles.json 里删掉这条的破折号（不是改 narration.json）",
+    "placeholder_leakage": "在 original_subtitles.json 里替换这条的示例占位（不是改 narration.json）",
+}
+_ORIGINAL_SUBTITLE_FALLBACK_HINT = "改 original_subtitles.json 里的这一条，不是 narration.json"
+
+
+def block_label(index):
+    """'段 N' for a 0-based block index; '整体' for a file-level issue."""
+    return "整体" if index is None else f"段 {index + 1}"
+
+
+def _label(e):
+    if e.get("source") == "original_subtitles":
+        index = e.get("index")
+        return "原声字幕" if index is None else f"原声字幕第 {index + 1} 条"
+    return block_label(e.get("index"))
+
+
+def _hint(e):
+    code = e.get("code")
+    if e.get("source") == "original_subtitles":
+        return _ORIGINAL_SUBTITLE_HINTS.get(code, _ORIGINAL_SUBTITLE_FALLBACK_HINT)
+    return _HINTS.get(code)
+
+
+def _seconds(value):
+    return f"{value:.2f}s" if isinstance(value, (int, float)) else "?"
+
+
+def _window(e):
+    return f"{_seconds(e.get('start'))}-{_seconds(e.get('end'))}"
+
+
+def _over_budget(e):
+    head = f"{_window(e)} 写了 {e.get('actual_chars')} 字，窗口约 {e.get('budget_chars')} 字"
+    if "limit_chars" in e:  # the full-mode error
+        return f"{head}（硬上限 {e.get('limit_chars')}，超出 {e.get('over_chars')} 字）"
+    return (
+        f"{head}，估计读完 {_seconds(e.get('estimated_tts_seconds'))}，"
+        f"可用 {_seconds(e.get('slot_seconds'))}"
+    )
+
+
+def _interrupts(e):
+    text = f"入点 {_seconds(e.get('entry_time'))} 落在原声句子中间"
+    if e.get("suggested_start") is None:
+        shift = e.get("max_shift_seconds")
+        within = f"前后 {shift:g} 秒内" if isinstance(shift, (int, float)) else "附近"
+        return text + f"，{within}没有能整块挪过去、留在前后两块之间又不与其他块重叠或相接的句尾锚点"
+    tail = e.get("source_text_tail")
+    tail = f"，句尾「{tail}」" if tail else ""
+    target = _seconds(e["suggested_start"])
+    if e.get("suggested_end") is not None:
+        target += f"-{_seconds(e['suggested_end'])}"
+    return (
+        f"{text}，建议入点 {target}"
+        f"（锚点 {e.get('anchor_confidence')}/{e.get('anchor_boundary_use')}{tail}）"
+    )
+
+
+def _ratio(value):
+    return f"{value:.0%}" if isinstance(value, (int, float)) else "?"
+
+
+_WARNING_DETAILS = {
+    "slot_too_short": lambda e: f"{_window(e)} 只容得下约 {e.get('budget_chars')} 字，TTS 可能放不下",
+    "incomplete_sentence": lambda e: f"结尾「{e.get('text_tail', '')}」没有句末标点",
+    "outside_scene": lambda e: f"{_window(e)} 的中点不在任何检测到的场景里",
+    "crosses_scene_boundary": lambda e: (
+        f"{_window(e)} 超出所在场景 "
+        f"{_seconds(e.get('scene_start'))}-{_seconds(e.get('scene_end'))}"
+    ),
+    "visual_beat_too_broad": lambda e: (
+        f"{_window(e)} 共 {_seconds(e.get('duration'))}，"
+        f"跨过 {e.get('frame_fact_count', '?')} 个画面锚点"
+    ),
+    "crosses_clip_boundary": lambda e: (
+        f"{_window(e)} 超出所在片段 {_seconds(e.get('clip_start'))}-{_seconds(e.get('clip_end'))}"
+    ),
+    "no_original_blocks": lambda e: (
+        f"旁白覆盖率 {_ratio(e.get('narration_coverage'))}，超过上限 {_ratio(e.get('coverage_max'))}"
+    ),
+    "under_narrated": lambda e: (
+        f"旁白覆盖率 {_ratio(e.get('narration_coverage'))}，低于下限 {_ratio(e.get('coverage_min'))}"
+    ),
+    "no_original_breaks": lambda e: (
+        f"块与块之间没有 ≥{_seconds(e.get('original_block_min_seconds'))} 的原声段"
+    ),
+    "fragmented_beats": lambda e: (
+        f"平均每块 {e.get('avg_block_chars')} 字，少于 {e.get('block_min_chars')} 字"
+    ),
+}
+
+
+def _details(e):
+    code = e.get("code")
+    if code == "over_budget" and "budget_chars" in e:
+        return _over_budget(e)
+    if code == "interrupts_source_sentence":
+        return _interrupts(e)
+    if code == "source_sentence_anchors_unavailable":
+        return f"入点 {_seconds(e.get('entry_time'))} 压在原声上，但没有已验证的句尾锚点"
+    if code == "time_overlap":
+        return (
+            f"{_seconds(e.get('start'))}-{_seconds(e.get('end'))} 与"
+            f"{block_label(e.get('previous_index'))}（结束于 {_seconds(e.get('previous_end'))}）重叠"
+        )
+    if code == "out_of_order":
+        return f"start {_seconds(e.get('start'))} 早于上一块的 {_seconds(e.get('previous_start'))}"
+    if code in _WARNING_DETAILS:
+        return _WARNING_DETAILS[code](e)
+    return str(e.get("message", "")).strip()
+
+
+def _issue_line(e):
+    line = f"- {_label(e)} {e.get('code')}：{_details(e)}"
+    hint = _hint(e)
+    if hint:
+        line += f"。改法：{hint}"
+    return line
+
+
+def _warning_lines(report):
+    """One line per warning, every warning listed: they never block, so none is cut."""
+    return [_issue_line(w) for w in report.get("warnings", [])]
+
+
+def format_lint_warnings(report, lint_path=None):
+    """The console summary of a lint that passed with warnings."""
+    lines = [f"narration lint：通过，{len(report.get('warnings', []))} 个 warning（不阻塞）"]
+    lines.extend(_warning_lines(report))
+    if lint_path is not None:
+        lines.append(f"完整报告：{lint_path}")
+    return "\n".join(lines)
+
+
+def format_lint_failure(report, lint_path=None):
+    errors = report.get("errors", [])
+    lines = [f"narration.json 预检失败：{len(errors)} 个 error，修改后重跑 validate。"]
+    lines.extend(_issue_line(e) for e in errors[:MAX_LISTED_ERRORS])
+    if len(errors) > MAX_LISTED_ERRORS:
+        lines.append(f"- …另有 {len(errors) - MAX_LISTED_ERRORS} 个 error 未列出")
+    warnings = _warning_lines(report)
+    if warnings:
+        lines.append(f"另有 {len(warnings)} 个 warning（不阻塞）：")
+        lines.extend(warnings)
+    if lint_path is not None:
+        lines.append(f"完整报告（含全部字段）：{lint_path}")
+    return "\n".join(lines)

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

@@ -5,21 +5,26 @@ timing and text checks live here, and every later consumer trusts its result.
 """
 
 import json
-import math
 from pathlib import Path
 
 from lib import CONFIG, log
 from agent_text import (
-    _clean_narration_punctuation,
+    TTS_UTTERANCE_OVERHEAD_SECONDS,
     _find_scene_for_midpoint,
-    _normalise_narration_segment,
-    _post_dedup_narration,
-    _recommended_char_budget,
+    _lint_char_budget,
     _scene_available_seconds,
     _text_char_count,
-    _truncate_at_sentence,
 )
 from deslop_qc import analyze_deslop_qc
+from entry_suggestion import (
+    SUGGESTED_ANCHOR_MAX_SHIFT_SECONDS,
+    _has_connected_predecessor,
+    _is_number,
+    _nearest_safe_anchor,
+    _other_block_spans,
+    _suggestion_window,
+)
+from lint_summary import format_lint_failure, format_lint_warnings
 from speech_ownership import (
     entry_overlaps_source_speech,
     load_source_sentence_evidence,
@@ -32,14 +37,6 @@ def _lint_issue(level, index, code, message, **extra):
     return issue
 
 
-def _is_number(value):
-    return (
-        isinstance(value, (int, float))
-        and not isinstance(value, bool)
-        and math.isfinite(value)
-    )
-
-
 def _visual_overlay_issues(index, seg):
     """Shape-check the renderer handoff recap reads verbatim from a validated segment.
 
@@ -134,11 +131,16 @@ def _clip_matches_for_segment(seg, clip_plan, requested_clip_id):
     ]
 
 
-def _source_sentence_entry_issue(index, start, anchors, speech_owned):
+def _source_sentence_entry_issue(
+    index, start, end, anchors, speech_owned, other_spans=(), window=(None, None),
+):
     """Return a blocking issue when narration enters midway through source speech.
 
     The validator reports a correction instead of silently moving audio. Source
     sentence integrity is invariant; an editorial policy string cannot bypass it.
+    `other_spans` are the other blocks' (start, end) and `window` the open range between
+    the neighbours (see _nearest_safe_anchor): the suggested entry never moves this block
+    onto, flush against, or past one of them.
     """
     if not speech_owned:
         return None
@@ -165,45 +167,81 @@ def _source_sentence_entry_issue(index, start, anchors, speech_owned):
         if pause_start - 0.05 <= start <= when + 0.08:
             return None
 
-    suggested = next(
-        (anchor for anchor in anchors if anchor["time"] > start + 0.08), None
-    )
+    suggested = _nearest_safe_anchor(start, end, anchors, other_spans, window)
     return _lint_issue(
         "error",
         index,
         "interrupts_source_sentence",
-        "Narration enters before the source sentence finishes. Move this block to the suggested "
-        "sentence-end anchor, or shorten/move/remove it when there is no later verified anchor, "
-        "then rerun lint before TTS. Source sentence interruption has no override.",
+        "Narration enters before the source sentence finishes. Move the whole block (same "
+        "duration) to the suggested sentence-end anchor, or shorten/move/remove it when no "
+        f"anchor within {SUGGESTED_ANCHOR_MAX_SHIFT_SECONDS:g}s keeps it between its neighbours "
+        "and clear of the other blocks, then rerun lint before TTS. The window stays inside the "
+        "block's clip (cut) or the output duration (cut_output); full mode does not know the "
+        "video's end, so keep it inside the video. Source sentence interruption has no override.",
         entry_time=round(start, 3),
         suggested_start=round(suggested["time"], 3) if suggested else None,
+        suggested_end=round(suggested["time"] + end - start, 3) if suggested else None,
+        max_shift_seconds=SUGGESTED_ANCHOR_MAX_SHIFT_SECONDS,
         source_text_tail=str(suggested.get("text_tail", "")).strip() if suggested else "",
         anchor_confidence=suggested["confidence"] if suggested else None,
+        anchor_boundary_use=(
+            suggested.get("boundary_use")
+            or ("unverified" if suggested["confidence"] in {"high", "medium"} else "none")
+        )
+        if suggested
+        else None,
     )
 
 
-def _has_connected_predecessor(narration, idx, start):
-    """A back-to-back narration handoff (<=150ms gap) does not expose the source track,
-    so the next TTS block is not a new source-speech entry."""
-    for other_idx, other in enumerate(narration):
-        if other_idx == idx or not isinstance(other, dict):
-            continue
-        other_start, other_end = other.get("start"), other.get("end")
-        if not _is_number(other_start) or not _is_number(other_end):
-            continue
-        if other_start < start and -0.001 <= start - other_end <= 0.15:
-            return True
-    return False
+def _suggestion_limits(seg, clip_plan, mode, output_duration):
+    """Closed range a suggested move must stay in: the block's one clip (cut mode, source
+    time), or [0, output_duration] when that is known (cut_output)."""
+    if mode == "cut" and clip_plan:
+        requested = seg.get("source_clip_id")
+        try:
+            requested = None if requested is None else int(requested)
+        except (TypeError, ValueError):
+            return None, None
+        matches = _clip_matches_for_segment(seg, clip_plan, requested)
+        return _clip_span(matches[0]) if len(matches) == 1 else (None, None)
+    usable = _is_number(output_duration) and output_duration > 0
+    return 0.0, output_duration if usable else None
+
+
+# Full-mode hard text budget: a segment longer than this multiple of its recommended
+# character budget cannot be spoken in its window, so lint returns it to the author
+# instead of anything downstream shortening it.
+OVER_BUDGET_ERROR_RATIO = 1.25
+
+
+def _over_budget_error(index, start, end, char_count, budget):
+    limit = int(budget * OVER_BUDGET_ERROR_RATIO)
+    return _lint_issue(
+        "error",
+        index,
+        "over_budget",
+        f"段 {index + 1} [{start:.2f}-{end:.2f}s] has {char_count} chars; the window holds "
+        f"about {budget} (hard limit {limit}), {char_count - limit} over the limit. "
+        "Shorten the text or widen/move the window, then rerun validate; "
+        "validation never shortens approved text.",
+        start=start,
+        end=end,
+        budget_chars=budget,
+        limit_chars=limit,
+        actual_chars=char_count,
+        over_chars=char_count - limit,
+        tts_overhead_seconds=TTS_UTTERANCE_OVERHEAD_SECONDS,
+    )
 
 
 def lint_narration(
     narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None,
-    require_chronological=False,
+    output_duration=None,
 ):
     """Preflight-check agent narration before TTS; write narration_lint.json when work_dir is set.
 
-    Segments are sorted by start for the timing checks; ``require_chronological`` (the
-    --preserve-approved-text contract) additionally rejects input that is not already in order."""
+    Segments must already be in chronological order; validation never reorders them.
+    `output_duration` (cut_output) bounds where interrupt suggestions may move a block."""
     scenes_analysis = scenes_analysis or []
     errors = []
     warnings = []
@@ -221,6 +259,8 @@ def lint_narration(
         )
     else:
         previous_start = None
+        # Suggested (start, end) of blocks already told to move; later blocks keep clear.
+        suggested_spans = {}
         for idx, seg in enumerate(narration):
             if not isinstance(seg, dict):
                 errors.append(
@@ -240,7 +280,7 @@ def lint_narration(
                     )
                 )
                 continue
-            if require_chronological and previous_start is not None and start < previous_start:
+            if previous_start is not None and start < previous_start:
                 errors.append(
                     _lint_issue(
                         "error",
@@ -304,12 +344,18 @@ def lint_narration(
                 continue
 
             char_count = _text_char_count(text)
-            budget = _recommended_char_budget(start, end)
+            budget = _lint_char_budget(start, end)
             # estimate at the REAL playback rate (after the narration_speed atempo); otherwise a
-            # beat sized to its 1.3x-sped slot looks "over budget" when it actually fits.
+            # beat sized to its 1.3x-sped slot looks "over budget" when it actually fits. The
+            # utterance's TTS edge silence takes room too.
             play_rate = CONFIG["speech_rate"] * CONFIG["narration_speed"]
-            estimated_tts_seconds = char_count / play_rate
+            estimated_tts_seconds = char_count / play_rate + TTS_UTTERANCE_OVERHEAD_SECONDS
             slot_seconds = _scene_available_seconds(start, end)
+            over_limit = (
+                mode == "full" and char_count > budget * OVER_BUDGET_ERROR_RATIO
+            )
+            if over_limit:
+                errors.append(_over_budget_error(idx, start, end, char_count, budget))
             if budget < 5:
                 warnings.append(
                     _lint_issue(
@@ -322,7 +368,9 @@ def lint_narration(
                         budget_chars=budget,
                     )
                 )
-            elif estimated_tts_seconds > slot_seconds:
+            # Independent of slot_too_short: a short slot can also be overfilled, and the
+            # author needs both numbers.
+            if not over_limit and estimated_tts_seconds > slot_seconds:
                 warnings.append(
                     _lint_issue(
                         "warning",
@@ -352,15 +400,25 @@ def lint_narration(
                 entry_issue = _source_sentence_entry_issue(
                     idx,
                     start,
+                    end,
                     source_sentence_anchors,
                     entry_overlaps_source_speech(
                         start,
                         source_evidence,
                         authored_overlap=seg.get("overlaps_speech", True),
                     ),
+                    _other_block_spans(narration, idx),
+                    _suggestion_window(
+                        narration, idx, suggested_spans,
+                        _suggestion_limits(seg, clip_plan, mode, output_duration),
+                    ),
                 )
                 if entry_issue:
                     errors.append(entry_issue)
+                    if entry_issue.get("suggested_end") is not None:
+                        suggested_spans[idx] = (
+                            entry_issue["suggested_start"], entry_issue["suggested_end"],
+                        )
 
             scene_bounds = _scene_bounds_for_midpoint(scenes_analysis, start, end)
             if scenes_analysis and not scene_bounds:
@@ -404,6 +462,7 @@ def lint_narration(
                         end=end,
                         duration=round(end - start, 2),
                         frame_fact_times=[round(ts, 2) for ts in frame_fact_times[:8]],
+                        frame_fact_count=len(frame_fact_times),
                     )
                 )
 
@@ -603,11 +662,9 @@ def lint_narration(
                 )
             )
 
+    # Unfiltered, so narration-sourced blocker indices are narration.json positions.
     deslop_qc = analyze_deslop_qc(
-        [seg for seg in narration if isinstance(seg, dict)]
-        if isinstance(narration, list)
-        else [],
-        work_dir=work_dir,
+        narration if isinstance(narration, list) else [], work_dir=work_dir,
     )
     for blocker in deslop_qc["blockers"]:
         errors.append(
@@ -632,76 +689,39 @@ def lint_narration(
         "warnings": warnings,
     }
     if work_dir is not None:
-        Path(work_dir, "deslop_qc.json").write_text(
-            json.dumps(deslop_qc, ensure_ascii=False, indent=2), encoding="utf-8"
-        )
         Path(work_dir, "narration_lint.json").write_text(
             json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
         )
     return report
 
 
+class NarrationLintError(ValueError):
+    """Lint found blocking errors: an ordinary result for the author to fix, not a crash.
+
+    str() is the compact per-block summary; `report` is the full lint report."""
+
+    def __init__(self, report, lint_path=None):
+        self.report = report
+        super().__init__(format_lint_failure(report, lint_path))
+
+
 def validate_narration_or_raise(
     narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None,
-    require_chronological=False,
+    output_duration=None,
 ):
     report = lint_narration(
         narration, scenes_analysis, clip_plan=clip_plan, mode=mode, work_dir=work_dir,
-        require_chronological=require_chronological,
+        output_duration=output_duration,
     )
     if report["errors"]:
-        sample = "; ".join(
-            f"#{e['index']}: {e['code']}" for e in report["errors"][:3]
+        raise NarrationLintError(
+            report, None if work_dir is None else Path(work_dir, "narration_lint.json")
         )
-        raise ValueError(f"narration.json 预检失败: {sample}; 详见 narration_lint.json")
     if report["warnings"]:
-        log(
-            f"narration lint: {len(report['warnings'])} warnings (see narration_lint.json)"
-        )
+        log(format_lint_warnings(
+            report, None if work_dir is None else Path(work_dir, "narration_lint.json")
+        ))
     else:
-        log("narration lint: ok")
+        log("narration lint：通过")
     return report
 
-
-def _validate_narration_budget(narration, scenes_analysis):
-    """Trim lint-validated narration to its timing budgets; drop what cannot be spoken."""
-    del scenes_analysis  # scene boundaries are advisory (lint warns); authored timing is kept
-    cleaned = []
-    for raw in narration:
-        item = _normalise_narration_segment(raw)
-        max_chars = _recommended_char_budget(item["start"], item["end"])
-        if max_chars < 5:
-            log(f"  丢弃过短解说段 {item['start']:.1f}-{item['end']:.1f}s")
-            continue
-        if _text_char_count(item["narration"]) > max_chars * 1.25:
-            truncated = _truncate_at_sentence(item["narration"], max_chars)
-            if truncated and _text_char_count(truncated) >= 5:
-                log(f"  解说超预算，已截短: {item['start']:.1f}-{item['end']:.1f}s")
-                item["narration"] = truncated
-            else:
-                log(
-                    f"  解说超预算且无法安全截断，已丢弃: {item['start']:.1f}-{item['end']:.1f}s"
-                )
-                continue
-        item["narration"] = _clean_narration_punctuation(item["narration"])
-        stripped = item["narration"].strip()
-        if stripped and stripped[-1] in "，：、；,—":
-            item["narration"] = stripped.rstrip("，：、；,—") + "。"
-        cleaned.append(item)
-
-    cleaned.sort(key=lambda n: n["start"])
-    deduped = []
-    for item in cleaned:
-        if deduped and item["start"] < deduped[-1]["end"]:
-            prev = deduped[-1]
-            log(
-                f"  解说时间重叠: {item['start']:.1f}-{item['end']:.1f}s vs "
-                f"{prev['start']:.1f}-{prev['end']:.1f}s"
-            )
-            if _text_char_count(item["narration"]) > _text_char_count(
-                prev["narration"]
-            ):
-                deduped[-1] = item
-        else:
-            deduped.append(item)
-    return _post_dedup_narration(deduped)

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

@@ -1,40 +1,9 @@
 #!/usr/bin/env python3
-"""Public API and CLI entrypoint for narration review."""
+"""CLI entrypoint for narration review."""
 
-from evidence_bundle import (
-    build_evidence_bundle,
-    build_review_coverage_metadata,
-    coverage_policy_v1,
-    filter_evidence_by_ranges,
-    render_evidence_bundle,
-)
-from review_grounding import remap_grounding_to_output_timeline
-from review_response import (
-    build_grounding_qc,
-    build_review_messages,
-    format_review_md,
-    merge_review_findings,
-    parse_review_response,
-    write_grounding_qc,
-)
-from review_runner import main, review_narration
+from review_runner import main
 
-__all__ = [
-    "build_evidence_bundle",
-    "build_grounding_qc",
-    "build_review_coverage_metadata",
-    "build_review_messages",
-    "coverage_policy_v1",
-    "filter_evidence_by_ranges",
-    "format_review_md",
-    "main",
-    "merge_review_findings",
-    "parse_review_response",
-    "remap_grounding_to_output_timeline",
-    "render_evidence_bundle",
-    "review_narration",
-    "write_grounding_qc",
-]
+__all__ = ["main"]
 
 if __name__ == "__main__":
     main()