@oh-story/dsh 0.1.12 → 0.1.14

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

@@ -1,11 +1,17 @@
 """Generate and cache source and edited storyboard sheets."""
 
+import json
 from pathlib import Path
 
 from lib import CONFIG, log
 
 
-from storyboard import build_source_storyboard, build_edited_storyboard
+from storyboard import (
+    _frame_index,
+    build_edited_storyboard,
+    build_source_storyboard,
+    work_dir_relative_pages,
+)
 
 
 from understanding_cache import (
@@ -25,6 +31,44 @@ def _storyboard_sample_policy():
     }
 
 
+def _relocated(payload):
+    """A cached storyboard whose stored paths still name the work_dir it was written in.
+
+    Sidecars written before 0.6.1 stored absolute page paths; a copied work_dir hits the
+    cache (identities are size + mtime) and would otherwise point the brief at the original
+    directory. Paths are re-derived from file names, so the copy names its own pages."""
+    if not isinstance(payload, dict):
+        return payload
+    payload = dict(payload)
+    payload["page_images"] = work_dir_relative_pages(payload.get("page_images"))
+    if payload.get("edited_video_path"):
+        payload["edited_video_path"] = "edited_source.mp4"  # the only edited output there is
+    return payload
+
+
+def _reuse_cached_storyboard(json_path, meta, label):
+    """The cached storyboard with work_dir-relative paths, or None when it is unreadable.
+
+    A legacy sidecar with absolute paths is rewritten (and re-stamped) once, so the JSON on
+    disk names this work_dir's pages too. Advisory: never raises."""
+    try:
+        cached = _load_json(json_path)
+    except (OSError, ValueError):
+        log(f"storyboard {label} 缓存命中但文件损坏，重建")
+        return None
+    relocated = _relocated(cached)
+    if relocated != cached:
+        try:
+            json_path.write_text(
+                json.dumps(relocated, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+            _write_stage_meta(json_path, meta)
+        except OSError as exc:
+            log(f"storyboard {label} 路径改写失败（忽略）: {exc}")
+    log(f"storyboard 跳过 {label}（缓存匹配）")
+    return relocated
+
+
 def _edited_storyboard_meta(clip_plan_validated_json, frames_manifest_path):
     """Cache key for the edited storyboard: clip plan + fps + frame-set all in the key, so an
     fps change OR a re-validated plan invalidates it. font availability is deliberately NOT in
@@ -41,6 +85,23 @@ def _edited_storyboard_meta(clip_plan_validated_json, frames_manifest_path):
     }
 
 
+def _multi_source_edited_storyboard_meta(clip_plan_validated_json, frame_sets):
+    """Cache key for a multi-source edited storyboard: the plan plus every used source's
+    frames-manifest identity and fps."""
+    return {
+        "schema_version": 1,
+        "stage": "edited_storyboard",
+        "inputs": {
+            "clip_plan_validated": _artifact_identity(clip_plan_validated_json),
+            "frames_manifests": {
+                sid: _artifact_identity(entry["manifest"]) for sid, entry in frame_sets.items()
+            },
+        },
+        "fps": {sid: entry["fps"] for sid, entry in frame_sets.items()},
+        "sample_policy": _storyboard_sample_policy(),
+    }
+
+
 def _generate_source_storyboard(
     work_dir, video_path, scenes, scenes_json, *, force=False
 ):
@@ -69,14 +130,8 @@ def _generate_source_storyboard(
         "sample_policy": _storyboard_sample_policy(),
     }
     if not force and _stage_cache_valid(json_path, meta):
-        try:
-            cached = _load_json(json_path)
-        except (OSError, ValueError):
-            log(
-                "storyboard source 缓存命中但文件损坏，重建"
-            )  # advisory: never raise out
-        else:
-            log("storyboard 跳过 source（缓存匹配）")
+        cached = _reuse_cached_storyboard(json_path, meta, "source")
+        if cached is not None:
             return cached
     result = build_source_storyboard(work_dir, video_path, scenes, CONFIG["fps"])
     if result is not None and json_path.exists():
@@ -84,53 +139,140 @@ def _generate_source_storyboard(
     return result
 
 
+def _multi_source_frame_sets(work_dir, plan_sources, clips=None):
+    """{source_id: {paths, numbers, fps, source_path}} for a multi-source validated plan.
+
+    Each source's frames live in its own work_dir (`sources.<id>.source_work_dir`, relative to
+    the project work_dir) at the fps recorded in that source's frames manifest — sources of
+    different lengths are extracted at different fps. A source without frames is left out, and
+    so is one no clip in `clips` uses (when given): it would not appear on the sheet, yet it
+    would enter the cache key.
+    """
+    used = None if clips is None else {
+        clip.get("source_id") for clip in clips if isinstance(clip, dict)
+    }
+    frame_sets = {}
+    for source_id, source in plan_sources.items():
+        if used is not None and source_id not in used:
+            continue
+        if not isinstance(source, dict):
+            log(f"storyboard edited：来源 {source_id} 不是对象，跳过")
+            continue
+        rel = source.get("source_work_dir")
+        if not rel:
+            log(f"storyboard edited：来源 {source_id} 未登记 source_work_dir，跳过")
+            continue
+        source_dir = Path(work_dir) / rel
+        manifest_path = _frames_manifest_path(source_dir)
+        try:
+            fps = float(_load_json(manifest_path)["fps"])
+        except (OSError, ValueError, TypeError, KeyError):
+            log(f"storyboard edited：来源 {source_id} 缺少可读的 frames_manifest.json，跳过")
+            continue
+        paths, numbers = _frame_index(source_dir)
+        if not paths or fps <= 0:
+            log(f"storyboard edited：来源 {source_id} 的 frames/ 缺失，跳过")
+            continue
+        frame_sets[source_id] = {
+            "paths": paths,
+            "numbers": numbers,
+            "fps": fps,
+            "source_path": source.get("source_path"),
+            "manifest": manifest_path,
+        }
+    return frame_sets
+
+
 def _generate_edited_storyboard(work_dir, source_video_path, *, force=False):
     """Generate (or reuse cached) the edited storyboard, GATED on clip_plan_validated.json
     file-presence (NOT on edit_mode — recap.py forwards --edit-mode cut in BOTH passes, so the
     validated plan presence is the only reliable pass2 signal). Advisory: returns dict|None.
+
+    A multi-source plan (one with `sources`) reads every source's frames from its own work_dir
+    under the project work_dir; the single-source plan reads work_dir/frames.
     """
     if not CONFIG["storyboard"]:
         return None
     clip_plan_validated_json = Path(work_dir) / "clip_plan_validated.json"
     if not clip_plan_validated_json.exists():
         return None  # pass1 (no validated plan yet) → no edited storyboard
-    frames_dir = Path(work_dir) / "frames"
-    if not frames_dir.is_dir() or not any(frames_dir.glob("frame_*.jpg")):
-        log("storyboard 跳过 edited：frames/ 缺失（缓存命中跳过了帧提取？）")
-        return None
-    json_path = Path(work_dir) / "storyboard" / "edited_storyboard.json"
-    meta = _edited_storyboard_meta(
-        clip_plan_validated_json, _frames_manifest_path(work_dir)
-    )
-    if not force and _stage_cache_valid(json_path, meta):
-        try:
-            cached = _load_json(json_path)
-        except (OSError, ValueError):
-            log(
-                "storyboard edited 缓存命中但文件损坏，重建"
-            )  # advisory: never raise out
-        else:
-            log("storyboard 跳过 edited（缓存匹配）")
-            return cached
     try:
         clip_plan_validated = _load_json(clip_plan_validated_json)
     except (OSError, ValueError):
         log("storyboard 跳过 edited：clip_plan_validated.json 无法解析")
         return None
+    if not isinstance(clip_plan_validated, dict):
+        log("storyboard 跳过 edited：clip_plan_validated.json 不是对象")
+        return None
+    plan_sources = clip_plan_validated.get("sources")
+    if isinstance(plan_sources, dict) and plan_sources:
+        clips = clip_plan_validated.get("clips")
+        if not isinstance(clips, list) or not clips:
+            log("storyboard 跳过 edited：clip_plan_validated 无 clips")
+            return None
+        frame_sets = _multi_source_frame_sets(work_dir, plan_sources, clips)
+        if not frame_sets:
+            log("storyboard 跳过 edited：剪辑用到的来源都没有 frames/")
+            return None
+        meta = _multi_source_edited_storyboard_meta(clip_plan_validated_json, frame_sets)
+    else:
+        frame_sets = None
+        frames_dir = Path(work_dir) / "frames"
+        if not frames_dir.is_dir() or not any(frames_dir.glob("frame_*.jpg")):
+            log("storyboard 跳过 edited：frames/ 缺失（缓存命中跳过了帧提取？）")
+            return None
+        meta = _edited_storyboard_meta(
+            clip_plan_validated_json, _frames_manifest_path(work_dir)
+        )
+    json_path = Path(work_dir) / "storyboard" / "edited_storyboard.json"
+    if not force and _stage_cache_valid(json_path, meta):
+        cached = _reuse_cached_storyboard(json_path, meta, "edited")
+        if cached is not None:
+            return cached
     result = build_edited_storyboard(
-        work_dir, source_video_path, clip_plan_validated, CONFIG["fps"]
+        work_dir, source_video_path, clip_plan_validated, CONFIG["fps"],
+        source_frames=frame_sets,
     )
     if result is not None and json_path.exists():
         _write_stage_meta(json_path, meta)
     return result
 
 
+_STORYBOARD_HEADING = "## Storyboard（先看 storyboard 再写；路径相对 work_dir）"
+# Also matches the pre-0.6.1 heading (no "路径相对 work_dir"), so a re-run replaces it too.
+_STORYBOARD_HEADING_PREFIX = "## Storyboard（先看 storyboard 再写"
+
+
+def _write_edited_storyboard_only(video, work_dir):
+    """--edited-storyboard-only: build the cut-output storyboard and point the brief at it.
+
+    For callers that write the pass-2 brief themselves (a multi-source orchestrator): no
+    extraction, ASR, VLM or API; the existing work_dir/agent_narration_brief.md, if any, gets
+    the same storyboard header a --brief-only rebuild would carry. Advisory: a storyboard
+    failure only logs.
+    """
+    work_dir = Path(work_dir)
+    edited = _generate_edited_storyboard(work_dir, video)
+    brief_path = work_dir / "agent_narration_brief.md"
+    if edited and brief_path.exists():
+        _prepend_storyboard_brief_header(brief_path, None, edited, cut_mode=True)
+    print(
+        json.dumps(
+            {
+                "status": "edited_storyboard" if edited else "edited_storyboard_skipped",
+                "work_dir": str(work_dir),
+                "page_images": (edited or {}).get("page_images", []),
+            },
+            ensure_ascii=False,
+        )
+    )
+
+
 def _prepend_storyboard_brief_header(
     brief_path, source_storyboard, edited_storyboard, *, cut_mode
 ):
     """Post-process the RETURNED brief markdown FILE (C1): prepend a short storyboard header.
 
-    Editing the brief FILE on disk (not brief.py) keeps the brief⇄narration twin byte-identical.
     Branches the edited-storyboard line on clip_plan_validated presence (edited_storyboard truthy)
     so pass1 never prints a not-yet-existing path. If labels_burned:false, point to inspect clip-map.
     """
@@ -138,7 +280,7 @@ def _prepend_storyboard_brief_header(
         return
     try:
         brief_path = Path(brief_path)
-        lines = ["## Storyboard（先看 storyboard 再写）", ""]
+        lines = [_STORYBOARD_HEADING, ""]
         any_labels_missing = False
         if source_storyboard:
             pages = source_storyboard.get("page_images") or []
@@ -155,6 +297,12 @@ def _prepend_storyboard_brief_header(
             )
             if not edited_storyboard.get("labels_burned", False):
                 any_labels_missing = True
+            sources = edited_storyboard.get("sources") or []
+            if sources:
+                lines.append(
+                    "- 来源标签: "
+                    + "，".join(f"{s['label']}={s['source_id']}" for s in sources)
+                )
         if any_labels_missing:
             lines.append(
                 "- 时间戳未烧入 → 用 `inspect clip-map` 查时间（JSON sidecar 仍为权威时间源）"
@@ -162,6 +310,10 @@ def _prepend_storyboard_brief_header(
         lines.append("")
         header = "\n".join(lines) + "\n"
         existing = brief_path.read_text(encoding="utf-8") if brief_path.exists() else ""
+        if existing.startswith(_STORYBOARD_HEADING_PREFIX):
+            # Re-running on the same brief replaces the earlier header instead of stacking.
+            end = existing.find("\n\n", existing.find("\n") + 2)
+            existing = existing[end + 2:] if end >= 0 else ""
         brief_path.write_text(header + existing, encoding="utf-8")
     except OSError as exc:
         log(f"storyboard brief 头部写入失败（忽略）: {exc}")

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

@@ -13,10 +13,25 @@ from extract import (
     parse_frame_number,
 )
 from lib import CONFIG
-from lib import log, api_call, load_prompt, mimo_video_api_call, run_cmd, file_identity
+from lib import (
+    log, api_call, load_prompt, mimo_video_api_call, run_cmd, file_identity, is_moderation_refusal,
+    is_usable_overview_chunk, offline_ignored_settings, settings_match,
+)
 
 # ── Step 4: VLM 视觉分析 ─────────────────────────────────────────────
 
+def vlm_prompt_payload():
+    """The exact prompt/context text the VLM stage sends; the VLM cache key compares it by
+    equality, so the prompt that is sent and the one that is keyed are built in one place."""
+    prompt = load_prompt("VLM_DEPTH_PROMPT")
+    if not prompt:
+        raise RuntimeError("references/prompt-templates.md 缺少 VLM_DEPTH_PROMPT 模板")
+    context = CONFIG.get("context_info", "")
+    if context:
+        prompt = f"已知信息：{context}\n\n{prompt}"
+    return {"prompt_text": prompt, "context_info": context}
+
+
 def _parse_vlm_depth_response(raw_text):
     """解析 VLM 深度分析响应，提取【描述】、【帧标签】和【深层分析】"""
     if not raw_text or not raw_text.strip():
@@ -119,13 +134,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
     if fps <= 0:
         raise ValueError("CONFIG['fps'] 必须大于 0；请先运行完整 pipeline 或指定 --fps")
 
-    vlm_prompt = load_prompt("VLM_DEPTH_PROMPT")
-    if not vlm_prompt:
-        vlm_prompt = "仔细观察这些视频帧。分两部分输出：\n【描述】不超过80字，描述画面中正在发生什么。\n【深层分析】不超过120字，分析角色情绪、关系动态、潜台词。"
-
-    ctx = CONFIG["context_info"]
-    if ctx:
-        vlm_prompt = f"已知信息：{ctx}\n\n{vlm_prompt}"
+    vlm_prompt = vlm_prompt_payload()["prompt_text"]
 
     # 构建帧时间映射 (frame_NNNNN.jpg -> time in seconds)。换算规则由 extract.py 独家定义：
     # ffmpeg 首帧在 t=0 而文件编号从 1 起，所以是 (n-1)/fps，不是 n/fps。
@@ -223,8 +232,14 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
         if not raw_response.strip():
             raise RuntimeError("VLM 连续 3 次返回空内容")
 
+        refused = is_moderation_refusal(raw_response)
+        if refused:
+            # A moderation refusal is not a scene description; record the scene as unreadable.
+            log(f"  场景 {i+1} 被 MiMo 内容审核拒绝，记为无法识别")
         # 解析 【描述】、【帧标签】和【深层分析】
-        description, depth_analysis, frame_facts = _parse_vlm_depth_response(raw_response)
+        description, depth_analysis, frame_facts = _parse_vlm_depth_response(
+            "" if refused else raw_response
+        )
 
         result = {
             "scene_id": i,
@@ -235,6 +250,8 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
         }
         if frame_facts:
             result["frame_facts"] = frame_facts
+        if refused:
+            result["analysis_status"] = "moderation_refused"
 
         return i, result
 
@@ -511,11 +528,12 @@ def mimo_video_overview_cache_fresh(overview_path, video_path, scenes):
         return False
     if not isinstance(overview, dict) or overview.get("input") != "scene_chunks":
         return False
-    if overview.get("settings") != mimo_video_settings():
+    ignored = offline_ignored_settings(CONFIG.get("mimo_video_api_key"), "mimo_video_api_url")
+    if not settings_match(overview.get("settings"), mimo_video_settings(), ignored):
         return False
     chunks = overview.get("chunks")
     if not isinstance(chunks, list) or not all(
-        isinstance(chunk, dict) and _is_mimo_chunk_usable(chunk.get("content"))
+        isinstance(chunk, dict) and is_usable_overview_chunk(chunk.get("content"))
         for chunk in chunks
     ):
         return False  # a moderation-rejected chunk is retried, never served from cache
@@ -566,21 +584,6 @@ def _analyze_mimo_video_chunk(chunk_path, chunk):
     }
 
 
-_MIMO_REJECTION_MARKERS = (
-    "request was rejected", "considered high risk", "high risk",
-    "content policy", "cannot process", "无法处理", "内容审核", "违规",
-)
-
-
-def _is_mimo_chunk_usable(content):
-    """A chunk is usable only if MiMo returned real analysis (not empty / a moderation refusal)."""
-    text = str(content or "").strip()
-    if not text:
-        return False
-    low = text.lower()
-    return not any(marker in low for marker in _MIMO_REJECTION_MARKERS)
-
-
 def analyze_video_overview(video_path, work_dir, scenes=None):
     """Use MiMo video understanding over local ffmpeg scene chunks."""
     if not CONFIG["mimo_video_overview"]:
@@ -620,7 +623,7 @@ def analyze_video_overview(video_path, work_dir, scenes=None):
             f"{chunk['start']:.1f}-{chunk['end']:.1f}s"
         )
         chunk_result = _analyze_mimo_video_chunk(chunk_path, chunk)
-        if _is_mimo_chunk_usable(chunk_result["content"]):
+        if is_usable_overview_chunk(chunk_result["content"]):
             chunk_results.append(chunk_result)
             done[cache_key] = chunk_result
             _save_mimo_partial(partial_path, done, video_path, scenes)

package/lib/video-recap/skills/video-voiceover/SKILL.md

@@ -5,6 +5,9 @@ description: >
  把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）或
  Fish Audio（s2.1-pro-free）或显式配置的通用 IndexTTS HTTP 服务逐段生成语音，
  按时间窗动态适配语速并处理响度；输入输出时间线上的旁白，产出 tts_segments 与 tts_meta.json。
+ 外发说明：每段旁白文字会发给所选 TTS 服务（MiMo / Fish Audio / 用户自托管的 IndexTTS），--voice-ref 的参考音频会发给 MiMo。
+ 另含实验性的英译中 dub 路径：只在显式选择 dub 模式并传 --confirm-voice-rights 时运行，会把源视频音频发到 MiMo ASR，
+ 并以原说话人的声音为参考经 MiMo voiceclone 克隆配音；只可用于用户有权使用、且说话人同意被克隆声音的内容。
  触发词：配音、语音合成、TTS、解说配音、
  voiceover、text to speech、旁白配音。
 ---
@@ -14,7 +17,21 @@ description: >
 本技能读取带时间戳的旁白稿，为每一段生成独立音频，并把语音适配到对应时间窗，随后记录下游合成所需的放置元数据。
 默认引擎是 MiMo TTS（`mimo-v2.5-tts`）；也可显式选择 Fish Audio（默认模型 `s2.1-pro-free`）。
 
-## 2. 环境要求
+## 2. 远程服务与数据外发
+
+本技能只在下表中被选中的路径上联网，每条路径发出的内容如下。实读文本指 `narration.json` 段落去掉格式与舞台提示后的文字。
+
+| 路径 | 服务与凭据 | 发送内容 |
+|------|------------|----------|
+| 默认解说 TTS（`--tts-provider auto\|mimo-tts`） | MiMo chat 接口 `<MIMO_TTS_API_URL 或 MIMO_API_URL>/chat/completions`，`MIMO_TTS_API_KEY` 或 `MIMO_API_KEY`，模型 `mimo-v2.5-tts` | 每段实读文本、一句自然语言语气/语速指令（由段的 `emotion` 与时间窗算出）、内置音色名（默认 `冰糖`）；`auto` 下 MiMo key 缺失且设置了 `FISH_API_KEY` 时改走 Fish Audio 行 |
+| 解说声音克隆（`--voice-ref <audio>` / `VOICE_REF`） | 同上，模型 `mimo-v2.5-tts-voiceclone` | 上述内容，外加参考音频（转成 24 kHz 单声道 WAV，最长 30 秒）的 base64，每段请求都带 |
+| Fish Audio（`--tts-provider fish-audio`） | `FISH_TTS_API_URL`（默认 `https://api.fish.audio/v1/tts`），`FISH_API_KEY` | 每段实读文本、数值语速、音色 ID `FISH_TTS_REFERENCE_ID`；不发送本地音频 |
+| 自托管 IndexTTS（`--tts-provider index-tts`） | 用户自己部署、由 `INDEX_TTS_ENDPOINT` 指定的 HTTP(S) 服务 | `{"voice": INDEX_TTS_VOICE, "text": 实读文本}`；不发送本地音频 |
+| 实验性 dub（见 §8） | MiMo ASR（`MIMO_API_URL`，`MIMO_API_KEY`，`mimo-v2.5-asr`）与 MiMo voiceclone（TTS 接口与凭据，`mimo-v2.5-tts-voiceclone`） | 源视频整条音轨按 6 秒分窗送 ASR；每句中文译文连同从源音频截取的约 10 秒原说话人声音（克隆参考）送 voiceclone |
+
+`--voice-ref` 与 dub 都会把一个真实人物的声音发给 MiMo 用于克隆：只在用户有权使用该音频、且声音主人同意被克隆时使用。
+
+## 3. 环境要求
 
 ```bash
 export MIMO_API_KEY=***  # 也可使用仅供 TTS 的 MIMO_TTS_API_KEY
@@ -30,25 +47,25 @@ export TTS_PROVIDER=index-tts
 
 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
 
-## 3. 输入契约
+## 4. 输入契约
 
 默认输入为 `work_dir/narration.json`。每段必须包含 `start`、`end` 与 `narration`，可选字段包括
 `pause_after_ms` 和 `overlaps_speech`。时间统一表示音频最终放置的**输出时间线秒数**。
 
 cut 流程先剪后配：`narration.json` 本身就是按剪后成片的输出时间写的，不存在另一份映射稿。
 
-## 4. 运行命令
+## 5. 运行命令
 
 ```bash
 python3 scripts/voiceover.py --work-dir <work_dir> --narration <narration.json> \
   [--tts-provider auto|mimo-tts|fish-audio|index-tts] \
   [--mimo-voice 冰糖 | --voice-ref <reference-audio>] \
-  [--preserve-approved-text]
+  [--preserve-approved-text] [--allow-partial-tts]
 ```
 
 单独运行且省略 `--narration` 时，默认读取 `work_dir/narration.json`；`--narration` 只用于指定其他路径的同格式稿件。
 
-## 5. 输出契约
+## 6. 输出契约
 
 - `tts_segments/*.wav`：每段旁白对应一个音频文件。
 - `tts_meta.json`：包含 `segments`、`engine`、`voice`（实际使用的 provider、模型、音色或参考音频）与 `narration`。每段记录 `audio_path`、时间、
@@ -63,29 +80,45 @@ python3 scripts/voiceover.py --work-dir <work_dir> --narration <narration.json>
   `--allow-partial-tts` 降级为可交付的部分成功；异常记录标为 `required: true` 并带策略 ID。
   仅含 `[停顿]` 等清理标记、清理后无实读文本的作者段也属于必需段错误。
 
-## 6. 运行规则
+## 7. 运行规则
 
-- 重跑只复用分段 sidecar 中记录的文本、TTS 设置与该 WAV 的 `size`/`mtime_ns` 均与当前相等的分段音频；
-  修改旁白或合成参数后，只重生成受影响的 WAV。
-- 批准稿保护策略属于缓存设置：严格模式不会命中旧的自动缩稿缓存；只有同一严格策略下、
-  `spoken_text` 完整匹配且 WAV 存在非空的缓存才可离线复用。
+- 分段音频按内容缓存在 `tts_segments/cache/`：键是实读文本、实际发给供应商的语气请求（MiMo 是那句自然语言指令，语速只在 ≥+6% 或 ≤-3% 时改变措辞；Fish Audio 是数值 speed；index-tts 没有段级控制）与 TTS 设置，不含段序号和时间窗；因此段位变化让名义语速从 +5% 变成 -2% 时，MiMo 不重新合成；
+  缓存 WAV 的 `size`/`mtime_ns` 变了即失效。`narr_NNN.wav` 是指向缓存的硬链接（不支持时为副本），`tts_meta.json`
+  照旧引用它。删掉、插入或挪动某段后，只重生成文本或发给供应商的请求变了的段（名义语速随首段、末两段的位置变化）；
+  旧版的 `narr_NNN.wav.cache.json` 不再读取。
+- 批准稿保护策略属于缓存设置：严格模式往缓存键里加入策略与原稿，与默认策略（`report-over-budget-v2`，不进键）互不命中；旧版逐段缓存（含自动缩稿音频）不再读取；只有同一严格策略下、
+  `spoken_text` 完整匹配且 WAV 存在非空的缓存才可离线复用；复用时仍按当前时间窗检查，放不下照样失败。
 - 严格 CLI 在本轮合成前把旧 `tts_meta.json` 按时间戳归档至 `tts_meta.history/`，因此失败时
   当前路径不会继续冒充本轮成功；成功元数据通过同目录临时文件原子替换。
 - `auto` 优先使用已配置的 MiMo，MiMo key 缺失且设置了 `FISH_API_KEY` 时使用 Fish Audio；需要可复现的 provider 选择时显式传 `--tts-provider`。
 - 自托管 index-tts 端点只能由 `--tts-provider index-tts` 或 `TTS_PROVIDER=index-tts` 显式选择，`auto`
   永不兜底选择它。协议、请求体、receipt 语义与缓存失效规则见 `references/index-tts.md`。
-- Fish Audio 直接请求 WAV；默认使用“娱乐扒妹”音色（`5653cea4ac83480aaf2bf45406556185`），`FISH_TTS_REFERENCE_ID` 可覆盖。模型、音色 ID、API URL、动态语速或归一化设置变化时会重新生成缓存。当前免费模型无 SLA，受 Fair Use 和官方免费期限约束。
+- Fish Audio 直接请求 WAV；默认使用“娱乐扒妹”音色（`5653cea4ac83480aaf2bf45406556185`），`FISH_TTS_REFERENCE_ID` 可覆盖。模型、音色 ID、API URL、归一化设置或按内容计算出的语速变化时会重新生成缓存（Fish 不接收音高和情绪，它们变了不重新生成）。当前免费模型无 SLA，受 Fair Use 和官方免费期限约束。
 - `--voice-ref` 仅用于 full/cut 解说克隆，切换到 `mimo-v2.5-tts-voiceclone`。仅在确需新合成时惰性规范化一次；
-- dub voiceclone 原始 WAV 也会按模型、提示、台词和参考音频的 `size`/`mtime_ns` 缓存；匹配重跑不再重复请求或计费，`dub_manifest.json` 逐行记录 `tts_cache=hit|miss`；
-  参考音频文件变化会使旧缓存失效。仅在获得授权后使用，参考音频会发送到 MiMo。
+  参考音频的路径、`size`/`mtime_ns` 或预处理版本变化会使旧缓存失效。仅在获得授权后使用，参考音频会发送到 MiMo。
+- dub voiceclone 原始 WAV 也会按模型、提示、台词和参考音频的 `size`/`mtime_ns` 缓存；匹配重跑不再重复请求或计费，
+  `dub_manifest.json` 逐行记录 `tts_cache=hit|miss`。
+- 合成出的段音频比按 `TTS_MIN_SPEECH_RATE`（默认 2.5 字/秒，英文按每词 1.5 字）读完全文、再加停顿与首尾静音的上限还长时，
+  视为 TTS 幻读（读完原稿后又编出一段话），按失败重试，不缓存也不交给 assemble；重试用尽则该段失败，报错写明时长与上限，
+  最后一次被拒的音频留在 `tts_segments/narr_NNN.rejected.wav` 供试听。数字（半角/全角）逐个计 1 字，`%` 计 3 字（百分之）。
+  dub 的 voiceclone 台词走同一道检查与重试（被拒的留在 `dub_tts/line_NNN_raw.rejected.wav`）。
+  旧版本缓存下的这类 WAV 在重跑时不再复用，会重新合成。设为 `0` 关闭这道检查。
 - `TTS_WORKERS`、`TTS_TIMEOUT`、`TTS_RETRIES`、`ALLOW_PARTIAL_TTS` 用于调整并发、超时、重试与部分成功策略。
-- dub 模式有独立的确定性门禁：`dub_lint.json` 会在语音克隆前阻止空行、重叠或越界译文；
-  `dub_review.json` 用于记录忠实度、语气、时长和平台适配复核。可通过
-  `dub.py --stage lint|review` 或 `dub.py --print-schema` 单独调用。
 
-## 7. 能力边界
+## 8. 实验性 dub 配音（英译中、克隆原声）
+
+`dub.py` 是实验功能：把英文原声翻译成中文，并用原说话人的克隆音色整轨替换人声。它与上面的解说配音是两条独立路径，`voiceover.py` 从不调用它。
+
+- **触发**：只在用户明确要求英译中配音时，由编排入口以 `--edit-mode dub --confirm-voice-rights` 运行；编排入口把确认参数原样转给 `dub.py` 的准备和渲染两个阶段。没有单独的手动阶段。
+- **确认门禁**：`dub.py` 的两个阶段都必须带 `--confirm-voice-rights`，缺少时在抽取音频和发出任何请求之前退出，并说明会外发什么。编排入口在 dub 模式下同样拒绝缺少该参数的运行，在其他模式下拒绝该参数。
+- **外发内容**：准备阶段把源视频音轨按 6 秒分窗发给 MiMo ASR（`mimo-v2.5-asr`）转写英文；渲染阶段把每句中文译文和从源音频第 2 秒起截取的约 10 秒原说话人声音（`dub_reference.wav`）一起发给 MiMo voiceclone（`mimo-v2.5-tts-voiceclone`）。
+- **权利与同意**：只能用于用户有权使用的视频与音频，且被克隆声音的说话人已同意。Agent 必须先向用户确认这两点，用户确认后才能加 `--confirm-voice-rights`；无法确认时不要运行 dub，也不要用它冒充他人发言。
+- **确定性门禁**：渲染阶段在语音克隆前写 `dub_lint.json`，空行、重叠或越界译文即中止，不发 voiceclone 请求。
+- **本地产物**：`dub_source.wav`、`dub_transcript.json`、`dub_brief.md`、`dub_reference.wav`、Agent 写的 `dub_script.json`、`dub_lint.json`、`dub_tts/`、`dub_manifest.json` 与 `dub_<name>.mp4`，都只写在 `work_dir`。
+
+## 9. 能力边界
 
-- 超窗时默认在句界自动缩稿并在 `spoken_text/truncated` 留痕；批准稿加 `--preserve-approved-text`。
+- 超窗时保留原稿并记录日志；assemble 有界提速放不下则在渲染前以 `no_safe_fit` 阻断。批准稿加 `--preserve-approved-text`，超窗即在 TTS 阶段失败。
 - 不混流、不压低原声、不渲染字幕。
 - 不分析视频，也不选择时间点；只为输入稿件中的既定分段配音。
 - Fish Audio 与 IndexTTS 路径都不接受本地 `--voice-ref`；前者用已创建的 `FISH_TTS_REFERENCE_ID` 选择音色。

package/lib/video-recap/skills/video-voiceover/references/index-tts.md

@@ -26,6 +26,6 @@ export INDEX_TTS_VOICE=<authorized-voice-name>
 每段的 `provider_receipt` 只记录 `provider` 与“请求的 voice”（`requested_voice`）。它说明请求参数，
 不是该声线的声学验证，也不代表已做人耳听审或音色身份验证。endpoint 不写入任何文件。
 
-缓存复用条件：sidecar 中的文本与设置（含 `index_tts_voice`）与当前相等、WAV 的 `size`/`mtime_ns` 未变，
-且 sidecar 的 receipt 对应当前 voice；缓存命中复用 sidecar 中的 receipt，不能现场补造。
-服务端模型或部署变化不会被自动察觉；更换声线实现后请删除 `tts_segments/*.cache.json` 强制重合成。
+缓存复用条件：`tts_segments/cache/` 中按文本与设置（含 `index_tts_voice`）寻址的条目存在、缓存 WAV 的
+`size`/`mtime_ns` 未变，且 sidecar 的 receipt 对应当前 voice；缓存命中复用 sidecar 中的 receipt，不能现场补造。
+服务端模型或部署变化不会被自动察觉；更换声线实现后请删除 `tts_segments/cache/` 强制重合成。

package/lib/video-recap/skills/video-voiceover/scripts/approved_text_policy.py

@@ -7,7 +7,9 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 
-LEGACY_TEXT_POLICY = "legacy-auto-truncate-v1"
+# Recorded per block in tts_meta.json; not part of the TTS cache key (only the strict policy
+# adds fields there), so renaming it invalidates no cached audio.
+LEGACY_TEXT_POLICY = "report-over-budget-v2"
 PRESERVE_APPROVED_TEXT_POLICY = "preserve-approved-text-v1"