@oh-story/dsh 0.1.12 → 0.1.13

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

@@ -94,8 +94,8 @@ def env_float(name, default, *, minimum=None):
     return _env_number(name, default, float, minimum)
 
 
-# Single MiMo credential powers ASR + VLM + TTS. Per-capability overrides
-# (MIMO_VIDEO_API_KEY / MIMO_TTS_API_KEY / MIMO_ASR_API_KEY and their *_API_URL forms)
+# Single MiMo credential powers ASR + VLM. Per-capability overrides
+# (MIMO_VIDEO_API_KEY / MIMO_ASR_API_KEY and their *_API_URL forms)
 # are optional and fall back to MIMO_API_KEY / MIMO_API_URL. Token-Plan keys (tp-*) auto-
 # route to the Token-Plan cluster base URL; pay-as-you-go keys use api.xiaomimimo.com.
 _mimo_api_key = os.environ.get("MIMO_API_KEY", "")
@@ -121,6 +121,7 @@ CONFIG = {
     "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_video_env_var": "MIMO_VIDEO_API_KEY" if os.environ.get("MIMO_VIDEO_API_KEY") else "MIMO_API_KEY",
     "mimo_asr_api_url": normalize_api_url(_raw_mimo_asr_api_url),
     "mimo_asr_api_key": _mimo_asr_api_key,
     "mimo_asr_env_var": "MIMO_ASR_API_KEY" if os.environ.get("MIMO_ASR_API_KEY") else "MIMO_API_KEY",
@@ -164,19 +165,12 @@ CONFIG = {
     # 生成解说时使用 speech_rate * safety_margin 作为约束
     "speech_rate": env_float("SPEECH_RATE", 3.9, minimum=0.5),  # 旧值 3.5 系统性偏低 ~10-17%
     "speech_safety_margin": env_float("SPEECH_SAFETY_MARGIN", 0.85, minimum=0.1),  # 保守系数：TTS 实际语速有 ±20% 波动
-    # Block-coverage lint thresholds — promoted from inline .get() literals to real CONFIG keys (tunable; defaults unchanged)
+    # Block-coverage targets the brief derives its first-draft block count from
     "narration_coverage_target": 0.7,   # rough first-draft/diagnostic fallback; content-led audio decisions may differ (not a quota)
-    "narration_coverage_max": 0.85,     # above this coverage → no_original_blocks (narration is wall-to-wall)
-    "narration_coverage_min": 0.5,      # below this coverage → under_narrated
     "narration_block_seconds": 9.0,     # block cadence used to derive target block count
-    "original_block_min_seconds": 2.5,  # a deliberate original-audio gap must be at least this long
-    "narration_block_min_chars": 16,    # below this avg block size → fragmented_beats
     "breath_ms": 250,  # 段间呼吸空间(ms)；block recap 块内连贯、块间留原声呼吸
     "narration_speed": env_float("NARRATION_SPEED", 1.15, minimum=0.5),  # 解说整体提速(atempo)，默认回到可懂区间；长片可设 1.0
     "narration_tail_pad_seconds": 0.1,  # 解说尾部最少留白；短 slot 会自动压低 delay 避免截断
-    "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 写作分块最大字数/词数
     "silence_noise_threshold": "-25dB",  # ffmpeg silencedetect 噪声阈值
@@ -250,6 +244,57 @@ def load_background_research(work_dir):
         raise ValueError("background_research.json 顶层必须是 JSON 对象（{...}）")
     return data
 
+# MiMo refusal detection, defined once for this skill. Two deliberately different tests:
+#
+# - Narrow (`is_moderation_refusal`): ASR windows and per-scene VLM replies. MiMo answers a
+#   moderated request with the English sentence "The request was rejected because it was
+#   considered high risk" as the reply content. Only the provider's own wording is matched:
+#   a false positive here blanks real dialogue or a real scene description.
+# - Broad (`is_usable_overview_chunk`): only the optional MiMo video overview. A false
+#   positive there just retries the chunk and falls back to the frame description, so it also
+#   rejects generic refusal phrasing ("违规", "content policy", ...) that would be too
+#   aggressive for transcripts.
+MODERATION_REFUSAL_MARKERS = ("request was rejected", "considered high risk")
+OVERVIEW_REJECTION_MARKERS = MODERATION_REFUSAL_MARKERS + (
+    "high risk", "content policy", "cannot process", "无法处理", "内容审核", "违规",
+)
+
+
+def is_moderation_refusal(text):
+    """True when a MiMo reply is a moderation refusal, not a transcript or description.
+
+    Both markers must appear in a short reply: one of them alone ("my request was rejected")
+    is plausible English dialogue, and a 15 s transcript window must not be blanked for it.
+    """
+    low = " ".join(str(text or "").lower().split())
+    return len(low) <= 200 and all(marker in low for marker in MODERATION_REFUSAL_MARKERS)
+
+
+def is_usable_overview_chunk(content):
+    """A MiMo overview chunk is usable only if it is non-empty and carries no refusal phrasing."""
+    low = str(content or "").strip().lower()
+    return bool(low) and not any(marker in low for marker in OVERVIEW_REJECTION_MARKERS)
+
+
+def offline_ignored_settings(api_key, endpoint_key):
+    """Cache-settings keys not compared when no credential is set.
+
+    The default endpoint URL is derived from the key prefix (tp-* → Token Plan cluster), so
+    unsetting the key changes it although the provider output did not change, and nothing can
+    be recomputed without a key anyway: an offline rerun must reuse the paid artifact, not
+    discard it. With a key every setting is compared."""
+    return () if api_key else (endpoint_key,)
+
+
+def settings_match(cached, current, ignore=()):
+    """True when two cache-settings dicts are equal outside the `ignore` keys."""
+    if not isinstance(cached, dict) or not isinstance(current, dict):
+        return False
+    return {k: v for k, v in cached.items() if k not in ignore} == {
+        k: v for k, v in current.items() if k not in ignore
+    }
+
+
 def file_identity(path):
     """{"size", "mtime_ns"} of a file: the cache identity recorded instead of content hashes."""
     st = os.stat(os.fspath(path))
@@ -286,9 +331,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",
@@ -296,9 +340,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")
@@ -314,10 +357,9 @@ def _prepare_api_payload(payload, api_provider=None, api_url=None):
     return normalized
 
 def _mimo_endpoint(kind):
-    """Return per-capability MiMo endpoint settings (video understanding / TTS / ASR)."""
+    """Return per-capability MiMo endpoint settings (video understanding / ASR)."""
     by_kind = {
         "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:
@@ -326,7 +368,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_env_var": CONFIG.get(src_key, "MIMO_API_KEY"),
+        "api_env_var": CONFIG[src_key],
     }
 
 def _call_mimo_endpoint(kind, payload, max_retries=10):
@@ -334,7 +376,6 @@ def _call_mimo_endpoint(kind, payload, max_retries=10):
     return api_call(
         payload,
         max_retries=max_retries,
-        api_provider="mimo",
         api_url=settings["api_url"],
         api_key=settings["api_key"],
         api_env_var=settings["api_env_var"],
@@ -348,7 +389,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_env_var=None):
+def api_call(payload, max_retries=8, *, api_url=None, api_key=None, api_env_var=None):
     """调用 OpenAI-compatible API，带重试。
 
     长视频理解会发出数百次 VLM/ASR 调用，集群的 429 限流是常态而非错误，所以重试更耐心
@@ -356,8 +397,8 @@ def api_call(payload, max_retries=8, *, api_provider=None, api_url=None, api_key
     集群的配额窗口常以分钟计，所以 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-understanding/scripts/storyboard.py

@@ -8,8 +8,9 @@ one image instead of opening dozens of frames:
   - edited_storyboard.{jpg,json}  — one row per kept clip over the cut OUTPUT timeline,
                                     each tile dual-labelled (output time / source time).
 
-Both reuse the frames already extracted by understand.py (frames/frame_*.jpg at CONFIG["fps"]).
-Nothing here re-extracts video. Every function returns dict|None and degrades to
+Both reuse the frames already extracted by understand.py (frames/frame_*.jpg at CONFIG["fps"];
+a multi-source edited sheet reads each source's own work_dir frames at the fps its frames
+manifest records). Nothing here re-extracts video. Every function returns dict|None and degrades to
 None + log(...) on ANY failure (no frames, ffmpeg missing/non-zero, font probe raises),
 so a storyboard quirk can NEVER block the pipeline (Principle 1: advisory, never blocking).
 
@@ -19,6 +20,7 @@ when no font is available (or drawtext errors) the sheet is still produced UNLAB
 """
 import json
 import math
+import re
 import shutil
 import subprocess
 from pathlib import Path
@@ -156,30 +158,82 @@ def _scene_anchor_timestamps(scenes, max_tiles):
     return anchors
 
 
-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.
+def _frame_size(frame_path):
+    """(width, height) of one extracted frame via ffprobe, or None on any failure."""
+    cmd = [
+        "ffprobe", "-v", "error", "-select_streams", "v:0",
+        "-show_entries", "stream=width,height", "-of", "csv=p=0:s=x", str(frame_path),
+    ]
+    try:
+        result = run_cmd(cmd)
+        width, height = (int(v) for v in result.stdout.strip().split("x"))
+    except Exception:  # noqa: BLE001 - an unreadable size only means "normalise this tile"
+        return None
+    if result.returncode != 0 or width <= 0 or height <= 0:
+        return None
+    return width, height
+
 
-    None signals the caller to fall back to the original frame (and flip labels_burned off).
-    A drawtext failure here is non-fatal: the unlabelled frame still tiles fine.
+def _prepared_frame(frame_path, label, font_path, fit, scratch_dir, out_name):
+    """Copy frame_path through ffmpeg, letterboxed into `fit` and/or labelled; path or None.
+
+    `fit` = (w, h) letterboxes a frame into one tile size and pixel format. A sheet mixing
+    sources needs both: the tile filter's input is re-initialised whenever frame size or
+    pixel format changes mid-sequence (a 4:4:4 source next to a 4:2:0 one), which silently
+    drops the tiles already placed, and mixed sizes would otherwise be squashed to the first.
+    `font_path=None` skips the label. None signals the caller to degrade; a failure here is
+    never fatal to the pipeline.
     """
+    filters = []
+    if fit is not None:
+        width, height = fit
+        filters.append(
+            f"scale={width}:{height}:force_original_aspect_ratio=decrease,"
+            f"pad={width}:{height}:(ow-iw)/2:(oh-ih)/2,format=yuvj420p"
+        )
+    if font_path:
+        safe_label = label.replace("\\", "\\\\").replace(":", "\\:").replace("'", "’")
+        filters.append(
+            f"drawtext=fontfile='{font_path}':text='{safe_label}':"
+            "x=8:y=8:fontsize=28:fontcolor=white:"
+            "box=1:boxcolor=black@0.55:boxborderw=6"
+        )
     out_path = scratch_dir / out_name
-    safe_label = label.replace("\\", "\\\\").replace(":", "\\:").replace("'", "’")
-    drawtext = (
-        f"drawtext=fontfile='{font_path}':text='{safe_label}':"
-        "x=8:y=8:fontsize=28:fontcolor=white:"
-        "box=1:boxcolor=black@0.55:boxborderw=6"
-    )
-    cmd = ["ffmpeg", "-y", "-i", str(frame_path), "-vf", drawtext, "-frames:v", "1", str(out_path)]
+    cmd = [
+        "ffmpeg", "-y", "-i", str(frame_path), "-vf", ",".join(filters),
+        "-frames:v", "1", str(out_path),
+    ]
     try:
         result = run_cmd(cmd)
-    except Exception as exc:  # noqa: BLE001 - a label render must never abort the sheet
-        log(f"storyboard drawtext 异常（降级为不烧时间戳）: {exc}")
+    except Exception as exc:  # noqa: BLE001 - a tile render must never abort the sheet
+        log(f"storyboard 帧处理异常（降级）: {exc}")
         return None
     if result.returncode != 0 or not out_path.exists():
         return None
     return out_path
 
 
+def _prepare_frames(tiles, font_path, scratch_dir, out_stem):
+    """Frames to tile, labelled when font_path is set; None as soon as one render fails.
+
+    A tile with neither a label nor a `fit` uses its extracted frame as-is (no ffmpeg).
+    """
+    frames = []
+    for idx, tile in enumerate(tiles):
+        fit = tile.get("fit")
+        if not font_path and fit is None:
+            frames.append(Path(tile["frame_file"]))
+            continue
+        prepared = _prepared_frame(
+            Path(tile["frame_file"]), tile["label"], font_path, fit, scratch_dir,
+            f"lbl_{out_stem}_{idx:05d}.jpg",
+        )
+        if prepared is None:
+            return None
+        frames.append(prepared)
+    return frames
+
+
 def _tile_pages(frame_paths, columns, out_dir, out_stem, scratch_dir):
     """Tile frame_paths into one or more contact-sheet pages; return the list of page paths.
 
@@ -225,11 +279,24 @@ def _tile_pages(frame_paths, columns, out_dir, out_stem, scratch_dir):
     return pages
 
 
+_PATH_SEPARATORS = re.compile(r"[\\/]")
+
+
+def work_dir_relative_pages(pages):
+    """Page images as work_dir-relative POSIX paths ("storyboard/<name>").
+
+    Pages always live in <work_dir>/storyboard/, so only the file name is kept: an absolute
+    path would keep naming the original work_dir after the directory is copied or moved."""
+    # Split on both separators: a sidecar written on Windows may be read on POSIX and back.
+    return ["storyboard/" + _PATH_SEPARATORS.split(str(page))[-1] for page in pages or []]
+
+
 def _render_storyboard(work_dir, tiles, out_stem):
     """Shared render path: optionally burn labels, tile to pages, return (page_paths, labels_burned).
 
-    `tiles` is a list of dicts that ALREADY carry a resolved `frame_file` (absolute path) and a
-    `label` string. Returns (None, _) on hard failure so callers degrade to None.
+    `tiles` is a list of dicts that ALREADY carry a resolved `frame_file` (absolute path), a
+    `label` string and optionally a `fit` tile size. Returns (None, _) on hard failure so
+    callers degrade to None.
     """
     if not _ffmpeg_available():
         log("storyboard 跳过：未找到 ffmpeg")
@@ -242,27 +309,22 @@ def _render_storyboard(work_dir, tiles, out_stem):
     scratch_dir.mkdir(parents=True, exist_ok=True)
 
     font_path = _probe_font()
-    labels_burned = bool(font_path)
-    render_frames = []
-    if labels_burned:
-        for idx, tile in enumerate(tiles):
-            labelled = _labelled_frame(
-                Path(tile["frame_file"]), tile["label"], font_path, scratch_dir,
-                f"lbl_{out_stem}_{idx:05d}.jpg",
-            )
-            if labelled is None:
-                # First failure → abandon labelling entirely so the WHOLE sheet is consistent
-                # (no half-labelled pages). The JSON sidecar still carries every timestamp.
-                labels_burned = False
-                break
-            render_frames.append(labelled)
-    if not labels_burned:
-        render_frames = [Path(tile["frame_file"]) for tile in tiles]
-
     try:
-        pages = _tile_pages(
-            render_frames, CONFIG["storyboard_columns"],
-            storyboard_dir, out_stem, scratch_dir,
+        render_frames = (
+            _prepare_frames(tiles, font_path, scratch_dir, out_stem) if font_path else None
+        )
+        labels_burned = render_frames is not None
+        if render_frames is None:
+            # First label failure → abandon labelling for the WHOLE sheet (no half-labelled
+            # pages). The JSON sidecar still carries every timestamp.
+            render_frames = _prepare_frames(tiles, None, scratch_dir, out_stem)
+        pages = (
+            _tile_pages(
+                render_frames, CONFIG["storyboard_columns"],
+                storyboard_dir, out_stem, scratch_dir,
+            )
+            if render_frames is not None
+            else []
         )
     finally:
         shutil.rmtree(scratch_dir, ignore_errors=True)
@@ -320,7 +382,7 @@ def build_source_storyboard(work_dir, video_path, scenes, fps):
             "video_path": str(video_path),
             "fps": float(fps) if fps else None,
             "labels_burned": labels_burned,
-            "page_images": [str(p) for p in pages],
+            "page_images": work_dir_relative_pages(pages),
             "sample_policy": {
                 "max_tiles": max_tiles,
                 "columns": columns,
@@ -354,7 +416,23 @@ def _source_to_output(source_time, clip):
     return round(max(out_start, min(mapped, out_end)), 3)
 
 
-def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fps):
+def _multi_source_tile_size(frame_sets):
+    """One tile size for a multi-source sheet: the first source's frame size rounded down to
+    even numbers (640x360 when no frame can be probed). Every multi-source tile is re-encoded
+    into it — see _prepared_frame. Odd sizes are real (frames keep storage resolution, e.g.
+    853x480) and ffmpeg's scale rounds a 4:2:0 frame up to even, so an odd pad target would
+    be smaller than its input and every tile would fail."""
+    for entry in frame_sets.values():
+        size = _frame_size(entry["paths"][0])
+        if size:
+            width, height = size
+            return max(2, width - width % 2), max(2, height - height % 2)
+    return 640, 360
+
+
+def build_edited_storyboard(
+    work_dir, source_video_path, clip_plan_validated, fps, *, source_frames=None
+):
     """OUTPUT-timeline contact sheet: one row per kept clip over the cut. Returns dict|None.
 
     For each kept clip, samples source start / mid / (end − 0.5s), maps each to the nearest
@@ -362,13 +440,37 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
     dedupes so a ≤1s clip yields 1-2 tiles (not 3 identical). Each tile is dual-labelled with
     both `output_timestamp` and `source_timestamp` (+ `source_clip_id`). Writes
     storyboard/edited_storyboard.json. Returns None + log on any failure.
+
+    Single-source plans read work_dir/frames at `fps`. A multi-source plan passes
+    `source_frames` = {source_id: {"paths", "numbers", "fps"[, "source_path"]}} built from each
+    source's own work_dir; its tiles also carry `source_id` and a short `S<n>` label listed
+    under `sources`, and `frame_file` keeps the full path (frame names repeat across sources).
     """
     try:
         work_dir = Path(work_dir)
-        paths, numbers = _frame_index(work_dir)
-        if not paths:
-            log("storyboard 跳过 edited：frames/ 为空或缺失")
-            return None
+        if source_frames is None:
+            paths, numbers = _frame_index(work_dir)
+            if not paths:
+                log("storyboard 跳过 edited：frames/ 为空或缺失")
+                return None
+            frame_sets = {None: {"paths": paths, "numbers": numbers, "fps": fps}}
+            tile_size = None
+        else:
+            # Only sources a clip uses: an unused one must not take an S<n> label, be listed
+            # under `sources`, or set the tile size.
+            used = {
+                clip.get("source_id") for clip in clip_plan_validated["clips"]
+                if isinstance(clip, dict)
+            }
+            frame_sets = {
+                sid: entry for sid, entry in source_frames.items()
+                if entry["paths"] and sid in used
+            }
+            if not frame_sets:
+                log("storyboard 跳过 edited：剪辑用到的来源都没有 frames/")
+                return None
+            tile_size = _multi_source_tile_size(frame_sets)
+        short_labels = {sid: f"S{n}" for n, sid in enumerate(frame_sets, start=1)}
         clips = clip_plan_validated["clips"]
         if not clips:
             log("storyboard 跳过 edited：clip_plan_validated 无 clips")
@@ -388,10 +490,16 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
                 continue
             if source_end <= source_start:
                 continue
+            source_id = clip.get("source_id") if source_frames is not None else None
+            frame_set = frame_sets.get(source_id)
+            if frame_set is None:
+                continue  # this source has no extracted frames (e.g. a material restore)
             mid = (source_start + source_end) / 2.0
             end_sample = max(source_start, source_end - 0.5)
             for src_ts in (source_start, mid, end_sample):
-                frame = _nearest_existing_frame(src_ts, fps, paths, numbers)
+                frame = _nearest_existing_frame(
+                    src_ts, frame_set["fps"], frame_set["paths"], frame_set["numbers"]
+                )
                 if frame is None:
                     continue
                 key = (clip_id, str(frame))
@@ -399,14 +507,20 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
                     continue  # same clip resolving to the same frame → drop the duplicate tile
                 seen_frames.add(key)
                 out_ts = _source_to_output(src_ts, clip)
-                tiles.append({
+                src_label = "src" if source_id is None else short_labels[source_id]
+                tile = {
                     "tile_id": tile_id,
                     "output_timestamp": out_ts,
                     "source_timestamp": round(float(src_ts), 3),
                     "source_clip_id": clip_id,
-                    "label": f"out {_fmt_mmss(out_ts)} / src {_fmt_mmss(src_ts)}",
+                    "label": f"out {_fmt_mmss(out_ts)} / {src_label} {_fmt_mmss(src_ts)}",
                     "frame_file": str(frame),
-                })
+                }
+                if source_id is not None:
+                    tile["source_id"] = source_id
+                if tile_size is not None:
+                    tile["fit"] = tile_size
+                tiles.append(tile)
                 tile_id += 1
         if not tiles:
             log("storyboard 跳过 edited：未解析到任何帧")
@@ -420,15 +534,20 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
             return None
 
         for tile in tiles:
-            tile["frame_file"] = Path(tile["frame_file"]).name
+            tile["frame_file"] = (
+                Path(tile["frame_file"]).name
+                if source_frames is None
+                else str(tile["frame_file"])
+            )
+            tile.pop("fit", None)
         edited_source = Path(work_dir) / "edited_source.mp4"
         payload = {
             "schema_version": 1,
             "timeline": "output",
-            "source_video_path": str(source_video_path),
-            "edited_video_path": str(edited_source) if edited_source.exists() else None,
+            "source_video_path": str(source_video_path) if source_frames is None else None,
+            "edited_video_path": edited_source.name if edited_source.exists() else None,
             "labels_burned": labels_burned,
-            "page_images": [str(p) for p in pages],
+            "page_images": work_dir_relative_pages(pages),
             "sample_policy": {
                 "max_tiles": max_tiles,
                 "columns": columns,
@@ -436,6 +555,17 @@ def build_edited_storyboard(work_dir, source_video_path, clip_plan_validated, fp
             },
             "tiles": tiles,
         }
+        if source_frames is not None:
+            on_sheet = {tile.get("source_id") for tile in tiles}
+            payload["sources"] = [
+                {
+                    "label": short_labels[sid],
+                    "source_id": sid,
+                    "source_path": frame_sets[sid].get("source_path"),
+                }
+                for sid in frame_sets
+                if sid in on_sheet
+            ]
         json_path = work_dir / "storyboard" / "edited_storyboard.json"
         json_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
         log(f"storyboard edited: {len(tiles)} tiles → {len(pages)} page(s), labels_burned={labels_burned}")

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

@@ -1,38 +1,12 @@
 """Fuse scenes, ASR, and quiet windows for narration planning."""
 
-from lib import CONFIG
 from agent_text import _overlap_seconds, _recommended_char_budget
-from narration_lint import _validate_narration_budget
 
 
 def _quiet_windows(silence_periods):
     return [qp for qp in silence_periods if not qp["has_speech"]]
 
 
-def _align_narration_to_quiet(narration, scenes_analysis, silence_periods):
-    """Recompute overlaps_speech from real quiet windows; keep the agent's timing.
-
-    The dense continuous-bed design places narration ON the pictured beat over a
-    ducked original bed, so segments are never relocated into silence gaps. Only
-    the overlaps_speech flag that the ducking stage consumes is corrected, leaving
-    the agent's start/end (and text) intact.
-
-    Budget/dedup runs FIRST so a dedup-merged beat's overlaps_speech reflects its
-    extended timing, not its original shorter span.
-    """
-    aligned = _validate_narration_budget(narration, scenes_analysis)
-    quiet_windows = _quiet_windows(silence_periods)
-    quiet_ratio_min = CONFIG["quiet_overlap_min_ratio"]
-    for n in aligned:
-        seg_dur = n["end"] - n["start"]
-        quiet_overlap = sum(
-            _overlap_seconds(n["start"], n["end"], qw["start"], qw["end"])
-            for qw in quiet_windows
-        )
-        n["overlaps_speech"] = quiet_overlap < max(0.3, seg_dur * quiet_ratio_min)
-    return aligned
-
-
 def _scene_asr_lines(asr_result, scene):
     lines = []
     for seg in asr_result:

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

@@ -8,10 +8,11 @@ from lib import CONFIG, log, load_background_research
 from asr_timing_evidence import asr_evidence_summary_for_brief
 
 
-from detect import detect_speech_boundary_anchors
+from detect import ensure_speech_boundary_anchors
 
 
-from brief import build_agent_brief, assess_understanding_substrate
+from briefing.builder import build_agent_brief
+from briefing.context import assess_understanding_substrate
 
 
 from understanding_cache import _load_json, _merge_overview_into_scenes
@@ -136,23 +137,44 @@ def _write_brief_from_existing_artifacts(video, work_dir, args, video_duration):
     scenes, asr_result, silence_periods = _load_understanding_artifacts_for_brief(
         work_dir
     )
-    if not (Path(work_dir) / "speech_boundary_anchors.json").exists():
-        detect_speech_boundary_anchors(work_dir, asr_result)
+    ensure_speech_boundary_anchors(work_dir, asr_result)
     overview_path = Path(work_dir) / "mimo_video_overview.json"
     if CONFIG["mimo_video_overview"]:
         scenes = _merge_overview_into_scenes(scenes, overview_path)
 
+    _finish_brief(
+        video, work_dir, args, video_duration,
+        storyboard_scenes=scenes, brief_scenes=scenes,
+        asr_result=asr_result, silence_periods=silence_periods,
+        status="brief_only", done_label="brief-only 完成", force=False,
+    )
+
+
+def _finish_brief(
+    video, work_dir, args, video_duration, *, storyboard_scenes, brief_scenes,
+    asr_result, silence_periods, status, done_label, force,
+):
+    """Storyboards, substrate banner, writing brief and the JSON status line.
+
+    Shared by the full analysis run and --brief-only. The full run passes the detected
+    scenes to the storyboard and the VLM analysis to the brief; --brief-only has only the
+    VLM analysis, so it passes that for both.
+    """
+    work_dir = Path(work_dir)
+    # Storyboard contact sheets (advisory, never blocking). Source uses scene anchors over the
+    # source timeline; edited is gated on clip_plan_validated.json file-presence (NOT edit_mode —
+    # recap.py forwards --edit-mode cut in BOTH passes, so the validated plan is the only reliable
+    # pass2 signal). Both cache via _write_stage_meta/_stage_cache_valid with fps + frame-set in the key.
     source_storyboard = None
-    edited_storyboard = None
-    scenes_json = Path(work_dir) / "scenes.json"
+    scenes_json = work_dir / "scenes.json"
     if scenes_json.exists():
         source_storyboard = _generate_source_storyboard(
-            work_dir, Path(video), scenes, scenes_json, force=False
+            work_dir, Path(video), storyboard_scenes, scenes_json, force=force
         )
-    edited_storyboard = _generate_edited_storyboard(work_dir, video, force=False)
-    cut_mode = (Path(work_dir) / "clip_plan_validated.json").exists()
+    edited_storyboard = _generate_edited_storyboard(work_dir, video, force=force)
+    cut_mode = (work_dir / "clip_plan_validated.json").exists()
 
-    substrate = assess_understanding_substrate(scenes, asr_result)
+    substrate = assess_understanding_substrate(brief_scenes, asr_result)
     if substrate["level"] != "rich":
         banner = "理解素材为空" if substrate["level"] == "empty" else "理解素材偏薄"
         log(
@@ -160,7 +182,7 @@ def _write_brief_from_existing_artifacts(video, work_dir, args, video_duration):
             f"带 frame_facts 的场景 {substrate['scenes_with_frame_facts']} | 平均画面描述 {substrate['avg_description_len']} 字"
         )
     brief_path = build_agent_brief(
-        scenes,
+        brief_scenes,
         asr_result,
         silence_periods,
         video_duration,
@@ -170,19 +192,20 @@ def _write_brief_from_existing_artifacts(video, work_dir, args, video_duration):
         mimo_overview_video_path=video,
         asr_evidence=asr_evidence_summary_for_brief(work_dir, video),
     )
+    # C1: prepend a storyboard header to the returned brief file, pointing the agent at the sheet(s).
     _prepend_storyboard_brief_header(
         brief_path, source_storyboard, edited_storyboard, cut_mode=cut_mode
     )
     log("=" * 50)
-    log(f"brief-only 完成。写作 brief: {brief_path}")
+    log(f"{done_label}。写作 brief: {brief_path}")
     print(
         json.dumps(
             {
-                "status": "brief_only",
+                "status": status,
                 "work_dir": str(work_dir),
                 "brief": str(brief_path),
                 "substrate": substrate["level"],
-                "scenes": len(scenes),
+                "scenes": len(storyboard_scenes),
                 "asr_segments": len(asr_result),
             },
             ensure_ascii=False,