@oh-story/dsh 0.1.10 → 0.1.12

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

@@ -1,7 +1,6 @@
 """Self-contained config + utilities for this skill (no cross-skill imports).
 Merged from the shared core; reads the same env vars as the rest of the bundle."""
 import json
-import hashlib
 import math
 import os
 import re
@@ -25,12 +24,11 @@ MIMO_TOKEN_PLAN_API_URLS = {
 }
 DEFAULT_MIMO_MODEL = "mimo-v2.5"          # VLM / chat (vision understanding)
 DEFAULT_MIMO_ASR_MODEL = "mimo-v2.5-asr"  # speech-to-text
-DEFAULT_MIMO_TTS_MODEL = "mimo-v2.5-tts"  # text-to-speech
 
 
 def normalize_api_url(raw_url):
     """Normalize a MiMo (OpenAI-compatible) base URL or chat/completions endpoint."""
-    url = (raw_url or DEFAULT_MIMO_API_URL).rstrip("/")
+    url = raw_url.rstrip("/")
     if url.endswith("/chat/completions"):
         return url
     return f"{url}/chat/completions"
@@ -118,14 +116,14 @@ _raw_mimo_asr_api_url = (
 CONFIG = {
     "api_url": normalize_api_url(_raw_api_url),
     "api_key": _mimo_api_key,
-    "api_key_source": "MIMO_API_KEY",
+    "api_env_var": "MIMO_API_KEY",
     "mimo_api_url": normalize_api_url(_raw_api_url),
     "mimo_api_key": _mimo_api_key,
     "mimo_video_api_url": normalize_api_url(_raw_mimo_video_api_url),
     "mimo_video_api_key": _mimo_video_api_key,
     "mimo_asr_api_url": normalize_api_url(_raw_mimo_asr_api_url),
     "mimo_asr_api_key": _mimo_asr_api_key,
-    "mimo_asr_api_key_source": "MIMO_ASR_API_KEY" if os.environ.get("MIMO_ASR_API_KEY") else "MIMO_API_KEY",
+    "mimo_asr_env_var": "MIMO_ASR_API_KEY" if os.environ.get("MIMO_ASR_API_KEY") else "MIMO_API_KEY",
     "mimo_model": os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
     "mimo_video_model": os.environ.get("MIMO_VIDEO_MODEL") or os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
     "vlm_model": os.environ.get("MIMO_MODEL", DEFAULT_MIMO_MODEL),
@@ -208,24 +206,6 @@ CONFIG = {
 SCRIPT_DIR = Path(__file__).parent
 PROMPTS_DIR = SCRIPT_DIR.parent / "references"
 
-def narration_tempo_budget(tts_rate_offset=0.0, *, config=None):
-    """Return the canonical tempo budget shared by voiceover and assemble."""
-    cfg = config or CONFIG
-    global_speed = max(0.01, float(cfg.get("narration_speed", 1.0) or 1.0))
-    rate_factor = max(0.01, 1.0 + float(tts_rate_offset or 0.0))
-    cumulative_max = max(1.0, float(cfg.get("narration_cumulative_tempo_max", 1.35) or 1.35))
-    hard_max = max(cumulative_max, float(cfg.get("narration_cumulative_tempo_hard_max", 1.40) or 1.40))
-    legacy_segment_cap = max(1.0, float(cfg.get("tts_segment_tempo_max", 1.20) or 1.20))
-    segment_tempo_max = max(1.0, min(legacy_segment_cap, cumulative_max / (global_speed * rate_factor)))
-    return {
-        "global_narration_speed": global_speed,
-        "tts_rate_factor": rate_factor,
-        "cumulative_tempo_max": cumulative_max,
-        "cumulative_tempo_hard_max": hard_max,
-        "segment_tempo_max": segment_tempo_max,
-        "max_raw_duration_factor": global_speed * segment_tempo_max,
-    }
-
 def log(msg):
     print(f"[video-recap] {msg}", flush=True)
 
@@ -250,64 +230,31 @@ def get_video_duration(video_path):
            "-of", "csv=p=0", str(video_path)]
     result = run_cmd(cmd)
     if result.returncode != 0:
-        return 0.0
+        raise RuntimeError(f"ffprobe 无法读取时长 {video_path}: {result.stderr.strip()[-500:]}")
     try:
         return float(result.stdout.strip())
-    except (TypeError, ValueError):
-        return 0.0
-
-def stable_json_dumps(value):
-    """Serialize values deterministically for non-secret cache fingerprints."""
-    return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
-
-def stable_hash(value):
-    """Return an md5 digest for deterministic JSON-serializable values."""
-    return hashlib.md5(stable_json_dumps(value).encode("utf-8")).hexdigest()
+    except ValueError as exc:
+        raise RuntimeError(f"ffprobe 时长输出无法解析 {video_path}: {result.stdout.strip()[:100]!r}") from exc
 
-_FILE_FINGERPRINT_MEMO = {}
 
+def load_background_research(work_dir):
+    """Load the agent-authored background_research.json: missing → {}, malformed → raise."""
+    path = Path(work_dir) / "background_research.json"
+    if not path.exists():
+        return {}
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        raise ValueError(f"background_research.json 不是合法 JSON，请修复后重试: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ValueError("background_research.json 顶层必须是 JSON 对象（{...}）")
+    return data
 
-def _file_identity(path):
-    """(device, inode, size, mtime_ns) — changes whenever the bytes could have changed."""
+def file_identity(path):
+    """{"size", "mtime_ns"} of a file: the cache identity recorded instead of content hashes."""
     st = os.stat(os.fspath(path))
-    return (st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns)
-
+    return {"size": st.st_size, "mtime_ns": st.st_mtime_ns}
 
-def file_fingerprint(path, chunk_size=1024 * 1024):
-    """Return a full-content fingerprint for cache-correct identity checks.
-
-    The digest covers CONTENT only — never the path or mtime — so a copied video or
-    artifact is still recognised as the same asset, while any byte change invalidates
-    the cache even if timestamps, size, head, or tail bytes are misleading.
-
-    Identity metadata is used ONLY to memoize within a single process. One understanding
-    run fingerprints the same source video 8-10 times and the whole extracted frame set
-    2-3 times; on a 40-minute video at fps=1 that is gigabytes of redundant reads before
-    any real work starts. A file rewritten in place gets a new (size, mtime_ns) and is
-    re-hashed, so the memo can never serve a stale digest.
-    """
-    key = _file_identity(path)
-    memoized = _FILE_FINGERPRINT_MEMO.get(key)
-    if memoized is not None:
-        return memoized
-    h = hashlib.sha256()
-    with open(os.fspath(path), "rb") as f:
-        for chunk in iter(lambda: f.read(chunk_size), b""):
-            h.update(chunk)
-    digest = h.hexdigest()
-    _FILE_FINGERPRINT_MEMO[key] = digest
-    return digest
-def video_fingerprint(video_path):
-    """Full video content fingerprint used as the root pipeline asset print."""
-    return file_fingerprint(video_path)
-
-def step_cache_key(video_path, step_name, params_fingerprint=""):
-    """Build a cache key from video content, step name and step parameters."""
-    params_digest = params_fingerprint
-    if not isinstance(params_digest, str):
-        params_digest = stable_hash(params_digest)
-    payload = f"{video_fingerprint(video_path)}_{step_name}_{params_digest}"
-    return hashlib.md5(payload.encode("utf-8")).hexdigest()
 
 def _retry_after_seconds(value, fallback):
     """Parse Retry-After seconds or HTTP-date; return fallback on malformed input."""
@@ -342,7 +289,7 @@ def _sanitize_api_error(value, limit=500):
 def _api_headers(api_provider=None, api_url=None, 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.get("api_key", "") if api_key is None else api_key
+    key = CONFIG["api_key"] if api_key is None else api_key
     return {
         "Content-Type": "application/json",
         "User-Agent": "video-recap/1.0",
@@ -357,7 +304,7 @@ def _prepare_api_payload(payload, api_provider=None, api_url=None):
         normalized["max_completion_tokens"] = normalized.pop("max_tokens")
     model = str(normalized.get("model") or "")
     if (
-        CONFIG.get("mimo_disable_thinking", True)
+        CONFIG["mimo_disable_thinking"]
         and not model.endswith(("-tts", "-asr"))
         and "thinking" not in normalized
     ):
@@ -369,9 +316,9 @@ def _prepare_api_payload(payload, api_provider=None, api_url=None):
 def _mimo_endpoint(kind):
     """Return per-capability MiMo endpoint settings (video understanding / TTS / ASR)."""
     by_kind = {
-        "video": ("mimo_video_api_url", "mimo_video_api_key", "mimo_video_api_key_source"),
-        "tts": ("mimo_tts_api_url", "mimo_tts_api_key", "mimo_tts_api_key_source"),
-        "asr": ("mimo_asr_api_url", "mimo_asr_api_key", "mimo_asr_api_key_source"),
+        "video": ("mimo_video_api_url", "mimo_video_api_key", "mimo_video_env_var"),
+        "tts": ("mimo_tts_api_url", "mimo_tts_api_key", "mimo_tts_env_var"),
+        "asr": ("mimo_asr_api_url", "mimo_asr_api_key", "mimo_asr_env_var"),
     }
     if kind not in by_kind:
         raise ValueError(f"Unsupported MiMo endpoint kind: {kind}")
@@ -379,7 +326,7 @@ def _mimo_endpoint(kind):
     return {
         "api_url": CONFIG.get(url_key) or CONFIG.get("mimo_api_url"),
         "api_key": CONFIG.get(key_key) or CONFIG.get("mimo_api_key"),
-        "api_key_source": CONFIG.get(src_key, "MIMO_API_KEY"),
+        "api_env_var": CONFIG.get(src_key, "MIMO_API_KEY"),
     }
 
 def _call_mimo_endpoint(kind, payload, max_retries=10):
@@ -390,7 +337,7 @@ def _call_mimo_endpoint(kind, payload, max_retries=10):
         api_provider="mimo",
         api_url=settings["api_url"],
         api_key=settings["api_key"],
-        api_key_source=settings["api_key_source"],
+        api_env_var=settings["api_env_var"],
     )
 
 def mimo_video_api_call(payload, max_retries=10):
@@ -401,7 +348,7 @@ def mimo_asr_api_call(payload, max_retries=10):
     """Call the MiMo speech-recognition (ASR) endpoint."""
     return _call_mimo_endpoint("asr", payload, max_retries=max_retries)
 
-def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key=None, api_key_source=None):
+def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key=None, api_env_var=None):
     """调用 OpenAI-compatible API，带重试。
 
     长视频理解会发出数百次 VLM/ASR 调用，集群的 429 限流是常态而非错误，所以重试更耐心
@@ -425,7 +372,7 @@ def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key
                 wait = _retry_after_seconds(retry_after, max(wait, 10))
                 log(f"API 速率限制 (尝试 {attempt+1}/{max_retries}), 等待 {wait}s")
             elif e.code == 401:
-                key_name = api_key_source or CONFIG.get("api_key_source", "MIMO_API_KEY")
+                key_name = api_env_var or CONFIG["api_env_var"]
                 raise RuntimeError(f"API 认证失败 (401)。请检查 {key_name} 和 API URL 是否匹配。")
             elif e.code == 403:
                 hint = "API 访问被拒绝 (403)。"
@@ -459,9 +406,6 @@ def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key
                 time.sleep(wait)
             else:
                 raise RuntimeError(f"API 调用失败 {max_retries} 次: {safe_error}")
-    # Unreachable for max_retries >= 1; guards against a silent `None` return (and the
-    # TypeError it would cause at the caller's resp["choices"]) if a caller passes 0.
-    raise ValueError(f"max_retries must be >= 1, got {max_retries}")
 
 def load_prompt(name):
     """加载 prompt 模板"""

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

@@ -5,6 +5,7 @@ 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
@@ -32,7 +33,11 @@ def _lint_issue(level, index, code, message, **extra):
 
 
 def _is_number(value):
-    return isinstance(value, (int, float)) and not isinstance(value, bool)
+    return (
+        isinstance(value, (int, float))
+        and not isinstance(value, bool)
+        and math.isfinite(value)
+    )
 
 
 def _visual_overlay_issues(index, seg):
@@ -115,17 +120,13 @@ def _clip_span(clip):
     return clip["start"], clip["end"]
 
 
-def _clip_matches_for_segment(seg, clip_plan):
+def _clip_matches_for_segment(seg, clip_plan, requested_clip_id):
     if not clip_plan:
         return []
     clips = clip_plan["clips"]
     midpoint = (seg["start"] + seg["end"]) / 2
-    if seg.get("source_clip_id") is not None:
-        try:
-            requested = int(seg["source_clip_id"])
-        except (TypeError, ValueError):
-            return []
-        clips = [clip for clip in clips if clip.get("clip_id") == requested]
+    if requested_clip_id is not None:
+        clips = [clip for clip in clips if clip.get("clip_id") == requested_clip_id]
     return [
         clip
         for clip in clips
@@ -196,9 +197,13 @@ def _has_connected_predecessor(narration, idx, start):
 
 
 def lint_narration(
-    narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None
+    narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None,
+    require_chronological=False,
 ):
-    """Preflight-check agent narration before TTS; write narration_lint.json when work_dir is set."""
+    """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."""
     scenes_analysis = scenes_analysis or []
     errors = []
     warnings = []
@@ -215,6 +220,7 @@ def lint_narration(
             )
         )
     else:
+        previous_start = None
         for idx, seg in enumerate(narration):
             if not isinstance(seg, dict):
                 errors.append(
@@ -230,33 +236,47 @@ def lint_narration(
             if not _is_number(start) or not _is_number(end):
                 errors.append(
                     _lint_issue(
-                        "error", idx, "invalid_time", "start/end must be numeric"
+                        "error", idx, "invalid_time", "start/end must be finite numbers"
                     )
                 )
                 continue
-            text = str(seg.get("narration", "")).strip()
-            try:
-                pause = int(seg.get("pause_after_ms", CONFIG["breath_ms"]))
-            except (TypeError, ValueError):
+            if require_chronological and previous_start is not None and start < previous_start:
                 errors.append(
                     _lint_issue(
                         "error",
                         idx,
-                        "invalid_pause",
-                        "pause_after_ms must be an integer number of milliseconds",
+                        "out_of_order",
+                        "Segments must be listed in chronological order",
+                        start=start,
+                        previous_start=previous_start,
+                    )
+                )
+            previous_start = start
+            text = seg.get("narration")
+            if not isinstance(text, str):
+                errors.append(
+                    _lint_issue(
+                        "error",
+                        idx,
+                        "invalid_narration",
+                        "narration must be a string",
+                        start=start,
+                        end=end,
                     )
                 )
                 continue
-            if pause < 0:
-                warnings.append(
+            text = text.strip()
+            pause = seg.get("pause_after_ms", CONFIG["breath_ms"])
+            if not isinstance(pause, int) or isinstance(pause, bool) or pause < 0:
+                errors.append(
                     _lint_issue(
-                        "warning",
+                        "error",
                         idx,
-                        "negative_pause",
-                        "pause_after_ms is negative; default should be used",
-                        pause_after_ms=pause,
+                        "invalid_pause",
+                        "pause_after_ms must be a non-negative integer number of milliseconds",
                     )
                 )
+                continue
             errors.extend(_visual_overlay_issues(idx, seg))
             if end <= start:
                 errors.append(
@@ -388,7 +408,21 @@ def lint_narration(
                 )
 
             if mode == "cut":
-                matches = _clip_matches_for_segment(seg, clip_plan)
+                requested_clip_id = seg.get("source_clip_id")
+                if requested_clip_id is not None:
+                    try:
+                        requested_clip_id = int(requested_clip_id)
+                    except (TypeError, ValueError):
+                        errors.append(
+                            _lint_issue(
+                                "error",
+                                idx,
+                                "invalid_source_clip_id",
+                                "source_clip_id must be an integer",
+                            )
+                        )
+                        continue
+                matches = _clip_matches_for_segment(seg, clip_plan, requested_clip_id)
                 if not matches:
                     errors.append(
                         _lint_issue(
@@ -400,7 +434,7 @@ def lint_narration(
                             end=end,
                         )
                     )
-                elif len(matches) > 1 and seg.get("source_clip_id") is None:
+                elif len(matches) > 1 and requested_clip_id is None:
                     errors.append(
                         _lint_issue(
                             "error",
@@ -426,18 +460,6 @@ def lint_narration(
                                 clip_end=round(clip_end, 3),
                             )
                         )
-                if seg.get("source_clip_id") is not None:
-                    try:
-                        int(seg["source_clip_id"])
-                    except (TypeError, ValueError):
-                        errors.append(
-                            _lint_issue(
-                                "error",
-                                idx,
-                                "invalid_source_clip_id",
-                                "source_clip_id must be an integer",
-                            )
-                        )
 
             normalized.append(
                 {"index": idx, "start": start, "end": end, "char_count": char_count}
@@ -620,10 +642,12 @@ def lint_narration(
 
 
 def validate_narration_or_raise(
-    narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None
+    narration, scenes_analysis=None, *, clip_plan=None, mode="full", work_dir=None,
+    require_chronological=False,
 ):
     report = lint_narration(
-        narration, scenes_analysis, clip_plan=clip_plan, mode=mode, work_dir=work_dir
+        narration, scenes_analysis, clip_plan=clip_plan, mode=mode, work_dir=work_dir,
+        require_chronological=require_chronological,
     )
     if report["errors"]:
         sample = "; ".join(

package/lib/video-recap/skills/video-understanding/scripts/speech_ownership.py

@@ -3,7 +3,7 @@
 import json
 from pathlib import Path
 
-from lib import CONFIG, stable_hash
+from lib import CONFIG, file_identity
 
 
 def _empty_evidence(mode):
@@ -21,11 +21,11 @@ def _read_json(path):
 
 
 def _output_payload_is_current(payload, work_dir):
-    plan = _read_json(Path(work_dir) / "clip_plan_validated.json")
+    plan_path = Path(work_dir) / "clip_plan_validated.json"
     return (
         payload is not None
-        and plan is not None
-        and payload["clip_plan_fingerprint"] == stable_hash(plan)
+        and plan_path.exists()
+        and payload["clip_plan_identity"] == file_identity(plan_path)
     )
 
 

package/lib/video-recap/skills/video-understanding/scripts/storyboard.py

@@ -24,12 +24,7 @@ import subprocess
 from pathlib import Path
 
 from extract import frame_number_for_time, parse_frame_number
-from lib import CONFIG, run_cmd, log
-
-try:  # file_fingerprint is the project's content-fingerprint helper; reuse when cheap.
-    from lib import file_fingerprint
-except ImportError:  # pragma: no cover - lib always ships it; degrade gracefully if not.
-    file_fingerprint = None
+from lib import CONFIG, run_cmd, log, get_video_duration
 
 
 # Candidate font files probed (in order) for burning mm:ss labels. The first that exists
@@ -138,14 +133,11 @@ def _scene_anchor_timestamps(scenes, max_tiles):
     long. Total is capped at max_tiles by evenly subsampling the ordered anchor list, so the
     sheet stays legible (D2: one bounded contact sheet, not dozens of frame reads).
     """
-    long_scene_seconds = float(CONFIG.get("storyboard_long_scene_seconds", 6.0) or 6.0)
+    long_scene_seconds = float(CONFIG["storyboard_long_scene_seconds"])
     anchors = []
     for scene_id, scene in enumerate(scenes or []):
-        try:
-            start = float(scene["start"])
-            end = float(scene["end"])
-        except (KeyError, TypeError, ValueError):
-            continue
+        start = float(scene["start"])
+        end = float(scene["end"])
         if end <= start:
             continue
         mid = (start + end) / 2.0
@@ -164,15 +156,6 @@ def _scene_anchor_timestamps(scenes, max_tiles):
     return anchors
 
 
-def _file_fp(path):
-    if file_fingerprint is None:
-        return None
-    try:
-        return file_fingerprint(path)
-    except (OSError, ValueError):
-        return None
-
-
 def _labelled_frame(frame_path, label, font_path, scratch_dir, out_name):
     """Burn `label` onto a copy of frame_path via drawtext; return the labelled path or None.
 
@@ -205,7 +188,7 @@ def _tile_pages(frame_paths, columns, out_dir, out_stem, scratch_dir):
     spill into _001.jpg, _002.jpg… Returns [] on any ffmpeg failure (caller degrades to None).
     """
     columns = max(1, int(columns))
-    rows_per_page = max(1, int(CONFIG.get("storyboard_rows_per_page", 5) or 5))
+    rows_per_page = int(CONFIG["storyboard_rows_per_page"])
     per_page = columns * rows_per_page
     pages = []
     total = len(frame_paths)
@@ -234,13 +217,9 @@ def _tile_pages(frame_paths, columns, out_dir, out_stem, scratch_dir):
             "-vf", f"tile={cols}x{rows}",
             str(page_path),
         ]
-        try:
-            result = run_cmd(cmd)
-        except Exception as exc:  # noqa: BLE001
-            log(f"storyboard tile 异常: {exc}")
-            return []
+        result = run_cmd(cmd)
         if result.returncode != 0 or not page_path.exists():
-            log(f"storyboard tile 失败: {getattr(result, 'stderr', '')[-300:]}")
+            log(f"storyboard tile 失败: {result.stderr[-300:]}")
             return []
         pages.append(page_path)
     return pages
@@ -282,7 +261,7 @@ def _render_storyboard(work_dir, tiles, out_stem):
 
     try:
         pages = _tile_pages(
-            render_frames, CONFIG.get("storyboard_columns", 6),
+            render_frames, CONFIG["storyboard_columns"],
             storyboard_dir, out_stem, scratch_dir,
         )
     finally:
@@ -305,8 +284,8 @@ def build_source_storyboard(work_dir, video_path, scenes, fps):
         if not paths:
             log("storyboard 跳过 source：frames/ 为空或缺失")
             return None
-        max_tiles = int(CONFIG.get("storyboard_max_tiles", 30) or 30)
-        columns = int(CONFIG.get("storyboard_columns", 6) or 6)
+        max_tiles = int(CONFIG["storyboard_max_tiles"])
+        columns = int(CONFIG["storyboard_columns"])
         anchors = _scene_anchor_timestamps(scenes, max_tiles)
         if not anchors:
             log("storyboard 跳过 source：无可用场景锚点")
@@ -339,7 +318,6 @@ def build_source_storyboard(work_dir, video_path, scenes, fps):
             "schema_version": 1,
             "timeline": "source",
             "video_path": str(video_path),
-            "video_fingerprint": _file_fp(video_path),
             "fps": float(fps) if fps else None,
             "labels_burned": labels_burned,
             "page_images": [str(p) for p in pages],
@@ -350,9 +328,10 @@ def build_source_storyboard(work_dir, video_path, scenes, fps):
             },
             "tiles": tiles,
         }
-        duration = get_video_duration_safe(video_path)
-        if duration:
-            payload["duration"] = round(duration, 3)
+        try:
+            payload["duration"] = round(get_video_duration(video_path), 3)
+        except RuntimeError as exc:
+            log(f"storyboard source：无法读取视频时长，sidecar 省略 duration（忽略）: {exc}")
         json_path = work_dir / "storyboard" / "source_storyboard.json"
         json_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
         log(f"storyboard source: {len(tiles)} tiles → {len(pages)} page(s), labels_burned={labels_burned}")
@@ -362,32 +341,6 @@ def build_source_storyboard(work_dir, video_path, scenes, fps):
         return None
 
 
-def get_video_duration_safe(video_path):
-    """Best-effort source duration via ffprobe; returns None on any failure (advisory)."""
-    if not shutil.which("ffprobe"):
-        return None
-    try:
-        result = subprocess.run(
-            ["ffprobe", "-v", "quiet", "-show_entries", "format=duration",
-             "-of", "csv=p=0", str(video_path)],
-            capture_output=True, text=True, timeout=30,
-        )
-        if result.returncode != 0:
-            return None
-        return float((result.stdout or "").strip())
-    except (ValueError, OSError, subprocess.SubprocessError):
-        return None
-
-
-def _clip_plan_clips(clip_plan_validated):
-    """Return the clips list from a validated plan (list or {"clips":[...]})."""
-    if isinstance(clip_plan_validated, dict):
-        clips = clip_plan_validated.get("clips", [])
-    else:
-        clips = clip_plan_validated
-    return clips if isinstance(clips, list) else []
-
-
 def _source_to_output(source_time, clip):
     """Forward affine source→output map for ONE clip (reimplements cut.py:319 locally).
 
@@ -416,12 +369,12 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
         if not paths:
             log("storyboard 跳过 edited：frames/ 为空或缺失")
             return None
-        clips = _clip_plan_clips(clip_plan_validated)
+        clips = clip_plan_validated["clips"]
         if not clips:
             log("storyboard 跳过 edited：clip_plan_validated 无 clips")
             return None
-        columns = int(CONFIG.get("storyboard_columns", 6) or 6)
-        max_tiles = int(CONFIG.get("storyboard_max_tiles", 30) or 30)
+        columns = int(CONFIG["storyboard_columns"])
+        max_tiles = int(CONFIG["storyboard_max_tiles"])
 
         tiles = []
         seen_frames = set()  # frame-identity dedupe (NOT luma de-dupe; that stays deferred)
@@ -474,7 +427,6 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
             "timeline": "output",
             "source_video_path": str(source_video_path),
             "edited_video_path": str(edited_source) if edited_source.exists() else None,
-            "clip_plan_fingerprint": _clip_plan_fingerprint(clip_plan_validated),
             "labels_burned": labels_burned,
             "page_images": [str(p) for p in pages],
             "sample_policy": {
@@ -491,17 +443,3 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
     except Exception as exc:  # noqa: BLE001 - advisory: never propagate
         log(f"storyboard edited 失败（忽略）: {exc}")
         return None
-
-
-def _clip_plan_fingerprint(clip_plan_validated):
-    """Stable fingerprint of the validated plan that drives the edited tiles."""
-    try:
-        return _stable_hash(clip_plan_validated)
-    except Exception:  # noqa: BLE001
-        return None
-
-
-def _stable_hash(value):
-    import hashlib
-    blob = json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
-    return hashlib.md5(blob.encode("utf-8")).hexdigest()