@oh-story/dsh 0.1.12 → 0.1.14

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

@@ -0,0 +1,125 @@
+"""Where an interrupting narration block may be told to move.
+
+`interrupts_source_sentence` suggests a sentence-end anchor the whole block can shift to.
+These helpers keep that suggestion between the block's neighbours and clear of every other
+block, and decide when a block is a back-to-back handoff that needs no entry check.
+"""
+
+import math
+
+
+def _is_number(value):
+    return (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+    )
+
+
+# A narration block that starts within this gap after another block's end is a
+# back-to-back handoff: the source track is never exposed between the two.
+CONNECTED_HANDOFF_SECONDS = 0.15
+# A suggested entry farther than this from the authored one moves the block off the
+# pictures it was written for; past it the author must rethink the block instead.
+SUGGESTED_ANCHOR_MAX_SHIFT_SECONDS = 10.0
+
+
+def _shift_is_clear(new_start, duration, other_spans):
+    """The block moved whole to new_start neither overlaps nor abuts another block."""
+    new_end = new_start + duration
+    gap = CONNECTED_HANDOFF_SECONDS
+    return all(
+        new_end < other_start - gap or new_start > other_end + gap
+        for other_start, other_end in other_spans
+    )
+
+
+def _nearest_safe_anchor(start, end, anchors, other_spans, window=(None, None)):
+    """The anchor closest to `start` the whole block can move to (duration kept) without
+    overlapping or abutting another block or leaving `window`, within
+    SUGGESTED_ANCHOR_MAX_SHIFT_SECONDS; a later anchor wins a tie. None when none qualifies.
+
+    `window` is the open (low, high) range the moved block must sit strictly inside: the
+    neighbours' ends with the handoff gap, so a block never jumps over a neighbour (story
+    order) and two adjacent blocks never get colliding suggestions. Either side may be None.
+    """
+    duration = end - start
+    low, high = window
+    candidates = [
+        anchor
+        for anchor in anchors
+        if abs(anchor["time"] - start) <= SUGGESTED_ANCHOR_MAX_SHIFT_SECONDS
+        and anchor["time"] >= 0
+        and (low is None or anchor["time"] > low)
+        and (high is None or anchor["time"] + duration < high)
+        and _shift_is_clear(anchor["time"], duration, other_spans)
+    ]
+    if not candidates:
+        return None
+    return min(candidates, key=lambda anchor: (abs(anchor["time"] - start), -anchor["time"]))
+
+
+def _valid_span(seg):
+    """(start, end) of a block with a usable numeric window, else None."""
+    if not isinstance(seg, dict):
+        return None
+    start, end = seg.get("start"), seg.get("end")
+    if _is_number(start) and _is_number(end) and end > start:
+        return start, end
+    return None
+
+
+def _other_block_spans(narration, idx):
+    """(start, end) of every other block with a usable numeric window."""
+    return [
+        span
+        for other_idx, other in enumerate(narration)
+        if other_idx != idx and (span := _valid_span(other))
+    ]
+
+
+# Clip/timeline edges are allowed positions; the open window bound sits this far outside.
+_EDGE_EPSILON = 1e-6
+
+
+def _suggestion_window(narration, idx, suggested_spans, limits=(None, None)):
+    """Open (low, high) range a suggested move of block `idx` must stay strictly inside.
+
+    Bounded by the previous and next valid blocks (narration is chronological) with the
+    handoff gap. The previous block counts at both its authored and its own suggested
+    window, so applying any subset of the suggestions keeps adjacent blocks apart and in
+    order. `limits` is the closed (first, last) range the block must stay in: its clip in
+    cut mode, the output duration in cut_output; either side may be None.
+    """
+    gap = CONNECTED_HANDOFF_SECONDS
+    low = high = None
+    for prev_idx in range(idx - 1, -1, -1):
+        span = _valid_span(narration[prev_idx])
+        if span:
+            low = max(span[1], suggested_spans.get(prev_idx, span)[1]) + gap
+            break
+    for next_idx in range(idx + 1, len(narration)):
+        span = _valid_span(narration[next_idx])
+        if span:
+            high = span[0] - gap
+            break
+    first, last = limits
+    if first is not None:
+        low = max(x for x in (low, first - _EDGE_EPSILON) if x is not None)
+    if last is not None:
+        high = min(x for x in (high, last + _EDGE_EPSILON) if x is not None)
+    return low, high
+
+
+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 <= CONNECTED_HANDOFF_SECONDS:
+            return True
+    return False

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

@@ -7,13 +7,11 @@ import re
 
 EVIDENCE_CONTRACT_VERSION = 1
 
-COVERAGE_POLICY_VERSION = "coverage_policy_v1"
-
 
 def _safe_time(item, key, default=0.0):
     try:
         value = float(item.get(key, default))
-    except (AttributeError, TypeError, ValueError):
+    except (TypeError, ValueError):
         return default
     return value if math.isfinite(value) else default
 
@@ -85,7 +83,6 @@ def coverage_policy_v1(
     duration = _overall_duration(scenes, asr_result, narration)
     if duration <= 0:
         return {
-            "coverage_policy_version": COVERAGE_POLICY_VERSION,
             "selected_ranges": [],
             "dropped_ranges": [],
             "dropped_range_count": 0,
@@ -162,7 +159,6 @@ def coverage_policy_v1(
     for r in merged + dropped:
         r.pop("priority", None)
     return {
-        "coverage_policy_version": COVERAGE_POLICY_VERSION,
         "selected_ranges": merged,
         "dropped_ranges": dropped,
         "dropped_range_count": len(dropped),
@@ -276,13 +272,11 @@ def _research_context_items(research):
 
 
 def filter_evidence_by_ranges(vlm_analysis, asr_result, ranges, *, timeline="source"):
-    """Pure compatibility seam: collect visual/ASR evidence items inside ranges."""
+    """Pure: collect visual/ASR evidence items inside ranges."""
     clock = "output" if timeline == "cut_output" else "source"
     items = []
     dropped = {"visual": 0, "asr": 0}
     for i, scene in enumerate(vlm_analysis or []):
-        if not isinstance(scene, dict):
-            continue
         start = _safe_time(scene, "start")
         end = _safe_time(scene, "end", start)
         if end <= start or not _in_ranges(start, end, ranges):
@@ -309,8 +303,6 @@ def filter_evidence_by_ranges(vlm_analysis, asr_result, ranges, *, timeline="sou
                 item[k] = scene.get(k)
         items.append(item)
     for i, seg in enumerate(asr_result or []):
-        if not isinstance(seg, dict):
-            continue
         text = str(seg.get("text", "")).strip()
         if not text:
             continue
@@ -346,22 +338,6 @@ def filter_evidence_by_ranges(vlm_analysis, asr_result, ranges, *, timeline="sou
     }
 
 
-def build_review_coverage_metadata(bundle):
-    """Summarize a build_evidence_bundle() bundle's coverage contract."""
-    coverage = bundle["coverage"]
-    metadata = bundle["metadata"]
-    return {
-        "coverage_policy_version": coverage["coverage_policy_version"],
-        "time_ranges": coverage["selected_ranges"],
-        "dropped_ranges": coverage["dropped_ranges"],
-        "dropped_range_count": coverage["dropped_range_count"],
-        "scene_count": metadata["reviewed_scene_count"],
-        "asr_count": metadata["reviewed_asr_count"],
-        "dropped_scene_count": metadata["dropped_scene_count"],
-        "dropped_asr_count": metadata["dropped_asr_count"],
-    }
-
-
 def build_evidence_bundle(
     vlm_analysis,
     asr_result,

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)