@oh-story/dsh 0.1.9 → 0.1.11

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

@@ -13,7 +13,7 @@ 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_fingerprint, stable_hash
+from lib import log, api_call, load_prompt, mimo_video_api_call, run_cmd, file_identity
 
 # ── Step 4: VLM 视觉分析 ─────────────────────────────────────────────
 
@@ -55,8 +55,8 @@ def _parse_vlm_depth_response(raw_text):
 def _max_frames_for_duration(duration):
     """Frames the VLM sees for one scene: ~1 per `vlm_seconds_per_frame`, floor 3, capped by
     `vlm_max_frames`. Replaces the old hard cap of 6 that starved long/merged scenes."""
-    spf = float(CONFIG.get("vlm_seconds_per_frame", 4.0) or 4.0)
-    ceiling = int(CONFIG.get("vlm_max_frames", 16) or 16)
+    spf = float(CONFIG["vlm_seconds_per_frame"])
+    ceiling = int(CONFIG["vlm_max_frames"])
     return max(3, min(ceiling, round(max(0.0, float(duration)) / spf)))
 
 
@@ -64,24 +64,33 @@ def _vlm_scene_cache_path(work_dir):
     return Path(work_dir) / "vlm_scene_cache.json"
 
 
-def _load_vlm_scene_cache(work_dir):
-    """Per-scene VLM resume cache (scene_key -> analysis). Tolerant: {} if absent/corrupt."""
+def _load_vlm_scene_cache(work_dir, settings):
+    """Per-scene VLM resume cache (scene_key -> analysis) written under `settings`.
+
+    Tolerant: {} if absent/corrupt, and {} when the stored request settings differ, so a
+    partial-failure cache is never resumed after an output-affecting setting changed."""
     path = _vlm_scene_cache_path(work_dir)
     if not path.exists():
         return {}
     try:
         data = json.loads(path.read_text(encoding="utf-8"))
-        return data if isinstance(data, dict) else {}
     except (OSError, ValueError):
         return {}
+    if not isinstance(data, dict) or data.get("settings") != settings:
+        return {}
+    scenes = data.get("scenes")
+    return scenes if isinstance(scenes, dict) else {}
 
 
-def _flush_vlm_scene_cache(work_dir, cache):
+def _flush_vlm_scene_cache(work_dir, settings, cache):
     """Persist the resume cache atomically (temp + rename) so an abort/crash never corrupts it."""
     path = _vlm_scene_cache_path(work_dir)
     try:
         tmp = path.with_name(path.name + ".tmp")
-        tmp.write_text(json.dumps(cache, ensure_ascii=False), encoding="utf-8")
+        tmp.write_text(
+            json.dumps({"settings": settings, "scenes": cache}, ensure_ascii=False),
+            encoding="utf-8",
+        )
         tmp.replace(path)
     except OSError as exc:
         log(f"VLM 场景缓存写入失败（忽略）: {exc}")
@@ -114,7 +123,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
     if not vlm_prompt:
         vlm_prompt = "仔细观察这些视频帧。分两部分输出：\n【描述】不超过80字，描述画面中正在发生什么。\n【深层分析】不超过120字，分析角色情绪、关系动态、潜台词。"
 
-    ctx = CONFIG.get("context_info", "")
+    ctx = CONFIG["context_info"]
     if ctx:
         vlm_prompt = f"已知信息：{ctx}\n\n{vlm_prompt}"
 
@@ -132,7 +141,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
     # 相邻场景才会复用同一帧，容量取「并发数 × 单场景最大帧数」就够，再多也命中不了。
     b64_capacity = max(
         8,
-        int(CONFIG.get("vlm_max_frames", 16) or 16) * max(1, int(CONFIG.get("vlm_workers", 4) or 4)),
+        int(CONFIG["vlm_max_frames"]) * int(CONFIG["vlm_workers"]),
     )
     b64_cache = OrderedDict()
     b64_lock = Lock()
@@ -184,7 +193,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
         payload = {
             "model": CONFIG["vlm_model"],
             "messages": [{"role": "user", "content": content_parts}],
-            "max_tokens": int(CONFIG.get("vlm_max_tokens", 1500) or 1500),
+            "max_tokens": int(CONFIG["vlm_max_tokens"]),
         }
 
         log(f"VLM 分析场景 {i+1}/{len(scenes)} ({len(scene_frames)} 帧)...")
@@ -208,7 +217,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
                 payload = {
                     "model": CONFIG["vlm_model"],
                     "messages": [{"role": "user", "content": retry_parts}],
-                    "max_tokens": int(CONFIG.get("vlm_max_tokens", 1500) or 1500),
+                    "max_tokens": int(CONFIG["vlm_max_tokens"]),
                 }
 
         if not raw_response.strip():
@@ -230,29 +239,34 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
         return i, result
 
     # 断点续传：逐场景持久化分析结果，避免少数场景失败（多为 429 限流）时整批画面理解全部作废。
-    cache = _load_vlm_scene_cache(work_dir) if resume else {}
-    prompt_fp = stable_hash(vlm_prompt)
+    # The resume cache is valid only under the SAME output-affecting settings the outer stage
+    # gate tracks (understanding_cache._vlm_cache_payload). vlm_prompt already folds in
+    # context_info (and background_research). The request/endpoint settings below are NOT in
+    # vlm_prompt, so they are stored explicitly — otherwise a partial-failure cache reused after
+    # flipping e.g. mimo_disable_thinking would yield a stale/mixed analysis.
+    cache_settings = {
+        "vlm_prompt": vlm_prompt,
+        "vlm_model": CONFIG.get("vlm_model"),
+        "vlm_max_tokens": CONFIG.get("vlm_max_tokens"),
+        "vlm_seconds_per_frame": CONFIG.get("vlm_seconds_per_frame"),
+        "vlm_max_frames": CONFIG.get("vlm_max_frames"),
+        "fps": round(float(fps), 3),
+        "frame_time_convention": FRAME_TIME_CONVENTION_VERSION,
+        "api_url": CONFIG.get("api_url"),
+        "mimo_disable_thinking": CONFIG.get("mimo_disable_thinking", True),
+        "mimo_media_resolution": CONFIG.get("mimo_media_resolution"),
+    }
+    cache = _load_vlm_scene_cache(work_dir, cache_settings) if resume else {}
 
     def _scene_cache_key(i, scene):
-        # Must invalidate on the SAME output-affecting settings the outer stage gate tracks
-        # (understand.py:_vlm_cache_payload). prompt_fp already covers vlm_prompt + context_info
-        # (which folds in background_research). The three below change the request/endpoint but
-        # are NOT in vlm_prompt, so they must be keyed explicitly — otherwise a partial-failure
-        # cache reused after flipping e.g. mimo_disable_thinking yields a stale/mixed analysis.
         return "|".join(str(x) for x in (
             i, round(float(scene["start"]), 3), round(float(scene["end"]), 3),
-            CONFIG.get("vlm_model"), prompt_fp, CONFIG.get("vlm_max_tokens"),
-            CONFIG.get("vlm_seconds_per_frame"), CONFIG.get("vlm_max_frames"),
-            round(float(fps), 3), FRAME_TIME_CONVENTION_VERSION,
-            CONFIG.get("api_url"), CONFIG.get("mimo_disable_thinking", True),
-            CONFIG.get("mimo_media_resolution"),
         ))
 
     analyses = [None] * len(scenes)
     todo = []
     for i, s in enumerate(scenes):
-        cached = cache.get(_scene_cache_key(i, s))
-        analyses[i] = cached if isinstance(cached, dict) else None
+        analyses[i] = cache.get(_scene_cache_key(i, s))
         if analyses[i] is None:
             todo.append(i)
     if todo and len(todo) < len(scenes):
@@ -282,7 +296,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
                         cache[_scene_cache_key(idx, scenes[idx])] = result
                         pending += 1
                         if pending >= flush_every:
-                            _flush_vlm_scene_cache(work_dir, cache)
+                            _flush_vlm_scene_cache(work_dir, cache_settings, cache)
                             pending = 0
                     except Exception as e:  # noqa: BLE001 - 单个场景失败不能拖垮其余已完成的
                         log(f"VLM 场景 {i+1} 分析失败: {e}")
@@ -290,10 +304,10 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
             finally:
                 # 无论正常结束、失败还是中断，都把这一轮已完成的场景落盘。
                 if pending:
-                    _flush_vlm_scene_cache(work_dir, cache)
+                    _flush_vlm_scene_cache(work_dir, cache_settings, cache)
         return failures
 
-    base_workers = min(len(todo) or 1, int(CONFIG.get("vlm_workers", 4) or 4))
+    base_workers = min(len(todo) or 1, int(CONFIG["vlm_workers"]))
     log(f"VLM 并行分析 {len(todo)} 个场景 (workers={base_workers})...")
     failures = _run_pass(todo, base_workers)
     if failures:
@@ -323,7 +337,7 @@ def analyze_scenes(scenes, frames, work_dir, *, resume=True):
 
 def _video_data_url(video_path):
     """Return a MiMo-compatible data URL for a local video chunk, or None when too large."""
-    max_bytes = int(float(CONFIG.get("mimo_video_base64_max_mb", 45.0)) * 1024 * 1024)
+    max_bytes = int(float(CONFIG["mimo_video_base64_max_mb"]) * 1024 * 1024)
     encoded_size = int(video_path.stat().st_size * 4 / 3) + 128
     if encoded_size > max_bytes:
         log(
@@ -342,18 +356,15 @@ def _mimo_video_chunks(scenes):
     if not scenes:
         raise RuntimeError("MiMo 视频分片理解需要 scenes；请先运行 ffmpeg scene/scdet 场景检测")
 
-    max_seconds = float(CONFIG.get("mimo_video_chunk_max_seconds", 20.0) or 20.0)
-    min_seconds = float(CONFIG.get("mimo_video_chunk_min_seconds", 1.0) or 1.0)
+    max_seconds = float(CONFIG["mimo_video_chunk_max_seconds"])
+    min_seconds = float(CONFIG["mimo_video_chunk_min_seconds"])
     chunks = []
     for scene_index, scene in enumerate(scenes):
-        try:
-            start = float(scene.get("start", 0.0))
-            end = float(scene.get("end", start))
-        except (TypeError, ValueError, AttributeError):
-            continue
+        start = float(scene["start"])
+        end = float(scene["end"])
         if end <= start:
             continue
-        scene_id = scene.get("scene_id", scene_index) if isinstance(scene, dict) else scene_index
+        scene_id = scene.get("scene_id", scene_index)
         cursor = start
         while cursor < end:
             chunk_end = min(end, cursor + max_seconds)
@@ -376,7 +387,7 @@ def _extract_video_chunk(video_path, chunk, output_path):
     """Cut one scene-based chunk into a compact local MP4 for MiMo video_url data URL."""
     start = float(chunk["start"])
     duration = max(0.1, float(chunk["end"]) - start)
-    fps = float(CONFIG.get("mimo_video_fps", 2.0) or 2.0)
+    fps = float(CONFIG["mimo_video_fps"])
     cmd = [
         "ffmpeg", "-y",
         "-ss", f"{start:.3f}",
@@ -392,7 +403,7 @@ def _extract_video_chunk(video_path, chunk, output_path):
         "-movflags", "+faststart",
         str(output_path),
     ]
-    result = run_cmd(cmd, timeout=CONFIG.get("mimo_video_chunk_timeout", 180))
+    result = run_cmd(cmd, timeout=CONFIG["mimo_video_chunk_timeout"])
     if result.returncode != 0:
         raise RuntimeError(f"MiMo 视频分片裁剪失败: {result.stderr[-500:]}")
     return output_path
@@ -402,7 +413,7 @@ def _mimo_chunk_prompt(chunk):
     return (
         f"这是原视频 {chunk['start']:.1f}s-{chunk['end']:.1f}s 的场景分片，"
         f"scene_id={chunk['scene_id']}。"
-        f"{CONFIG.get('mimo_video_prompt', '请用中文概括这个视频分片。')}"
+        f"{CONFIG['mimo_video_prompt']}"
     )
 
 
@@ -411,7 +422,7 @@ def _mimo_video_model():
     return CONFIG.get("mimo_video_model") or CONFIG.get("mimo_model") or CONFIG["vlm_model"]
 
 
-def mimo_video_settings_fingerprint():
+def mimo_video_settings():
     """Return non-secret MiMo video-overview settings that affect generated content."""
     return {
         "model": _mimo_video_model(),
@@ -434,19 +445,9 @@ def _mimo_chunk_cache_key(chunk):
     )
 
 
-def _mimo_cached_chunks_fingerprint(done):
-    return stable_hash(done)
-
-
-def _mimo_overview_payload_fingerprint(overview):
-    payload = dict(overview)
-    payload.pop("overview_fingerprint", None)
-    return stable_hash(payload)
-
-
 def _mimo_partial_provenance(video_path, scenes):
     return {
-        "source_video_fingerprint": file_fingerprint(video_path),
+        "source_video_identity": file_identity(video_path),
         "chunks": [_mimo_chunk_cache_key(chunk) for chunk in _mimo_video_chunks(scenes)],
     }
 
@@ -465,7 +466,7 @@ def _load_mimo_partial(partial_path, video_path=None, scenes=None):
         return {}
     if not isinstance(partial, dict):
         return {}
-    if partial.get("settings") != mimo_video_settings_fingerprint():
+    if partial.get("settings") != mimo_video_settings():
         return {}
     if video_path is not None or scenes is not None:
         try:
@@ -474,20 +475,14 @@ def _load_mimo_partial(partial_path, video_path=None, scenes=None):
         except (OSError, RuntimeError, TypeError, ValueError):
             return {}
     done = partial.get("chunks")
-    if not isinstance(done, dict):
-        return {}
-    recorded = partial.get("chunks_fingerprint")
-    if not recorded or recorded != _mimo_cached_chunks_fingerprint(done):
-        return {}
-    return done
+    return done if isinstance(done, dict) else {}
 
 
 def _save_mimo_partial(partial_path, done, video_path=None, scenes=None):
     """Persist completed chunk results incrementally so paid chunks survive a mid-loop failure."""
     payload = {
-        "settings": mimo_video_settings_fingerprint(),
+        "settings": mimo_video_settings(),
         "chunks": done,
-        "chunks_fingerprint": _mimo_cached_chunks_fingerprint(done),
     }
     if video_path is not None or scenes is not None:
         payload["provenance"] = _mimo_partial_provenance(video_path, scenes)
@@ -507,7 +502,7 @@ def _mimo_chunks_match(cached_chunks, expected_chunks):
 
 def mimo_video_overview_cache_fresh(overview_path, video_path, scenes):
     """Return True only when the final MiMo overview matches current inputs/settings."""
-    overview_path = Path(overview_path) if not hasattr(overview_path, "read_text") else overview_path
+    overview_path = Path(overview_path)
     if not overview_path.exists():
         return False
     try:
@@ -516,24 +511,16 @@ 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_fingerprint():
-        return False
-    overview_fingerprint = overview.get("overview_fingerprint")
-    if not overview_fingerprint or overview_fingerprint != _mimo_overview_payload_fingerprint(overview):
-        return False
-    recorded = overview.get("chunks_fingerprint")
-    if not recorded:
+    if overview.get("settings") != mimo_video_settings():
         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"))
         for chunk in chunks
     ):
-        return False
-    if recorded != _mimo_cached_chunks_fingerprint(chunks):
-        return False
+        return False  # a moderation-rejected chunk is retried, never served from cache
     try:
-        if overview.get("source_video_fingerprint") != file_fingerprint(video_path):
+        if overview.get("source_video_identity") != file_identity(video_path):
             return False
         expected_chunks = _mimo_video_chunks(scenes)
     except (OSError, RuntimeError, TypeError, ValueError):
@@ -550,8 +537,8 @@ def _analyze_mimo_video_chunk(chunk_path, chunk):
         {
             "type": "video_url",
             "video_url": {"url": video_url},
-            "fps": CONFIG.get("mimo_video_fps", 2.0),
-            "media_resolution": CONFIG.get("mimo_media_resolution", "default"),
+            "fps": CONFIG["mimo_video_fps"],
+            "media_resolution": CONFIG["mimo_media_resolution"],
         },
         {"type": "text", "text": _mimo_chunk_prompt(chunk)},
     ]
@@ -596,9 +583,9 @@ def _is_mimo_chunk_usable(content):
 
 def analyze_video_overview(video_path, work_dir, scenes=None):
     """Use MiMo video understanding over local ffmpeg scene chunks."""
-    if not CONFIG.get("mimo_video_overview", False):
+    if not CONFIG["mimo_video_overview"]:
         return None
-    if not CONFIG.get("mimo_video_api_key"):
+    if not CONFIG["mimo_video_api_key"]:
         log("MiMo 视频概览已启用，但未设置 MIMO_VIDEO_API_KEY/MIMO_API_KEY，跳过")
         return None
 
@@ -613,20 +600,16 @@ def analyze_video_overview(video_path, work_dir, scenes=None):
     log(f"MiMo 视频理解：按 ffmpeg scene 分片分析 {len(chunks)} 段...")
     chunk_results = []
     unusable_chunks = []
-    removed_stale_cache = False
     for chunk in chunks:
         cache_key = _mimo_chunk_cache_key(chunk)
         cached = done.get(cache_key)
-        if cached is not None:
-            if _is_mimo_chunk_usable(cached.get("content")):
-                log(
-                    f"  MiMo 分片 {chunk['chunk_id'] + 1}/{len(chunks)}: "
-                    f"{chunk['start']:.1f}-{chunk['end']:.1f}s（命中增量缓存，跳过）"
-                )
-                chunk_results.append(cached)
-                continue
-            done.pop(cache_key, None)
-            removed_stale_cache = True
+        if cached is not None:  # the partial only ever stores usable chunks
+            log(
+                f"  MiMo 分片 {chunk['chunk_id'] + 1}/{len(chunks)}: "
+                f"{chunk['start']:.1f}-{chunk['end']:.1f}s（命中增量缓存，跳过）"
+            )
+            chunk_results.append(cached)
+            continue
         chunk_path = chunks_dir / (
             f"chunk_{chunk['chunk_id']:03d}_scene_{chunk['scene_id']}_"
             f"{chunk['start']:.2f}-{chunk['end']:.2f}.mp4"
@@ -637,7 +620,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.get("content")):
+        if _is_mimo_chunk_usable(chunk_result["content"]):
             chunk_results.append(chunk_result)
             done[cache_key] = chunk_result
             _save_mimo_partial(partial_path, done, video_path, scenes)
@@ -645,15 +628,9 @@ def analyze_video_overview(video_path, work_dir, scenes=None):
             unusable_chunks.append(chunk)
             log(f"  MiMo 分片 {chunk['chunk_id'] + 1}: 未返回有效内容，保留为待重试")
 
-    if removed_stale_cache:
-        _save_mimo_partial(partial_path, done, video_path, scenes)
-
     if not chunk_results:
         log(f"MiMo 视频概览：{len(chunks)} 段均无有效内容（疑似被内容审核拦截），跳过概览")
-        try:
-            partial_path.unlink()
-        except OSError:
-            pass
+        partial_path.unlink(missing_ok=True)
         return None
 
     if unusable_chunks:
@@ -680,23 +657,18 @@ def analyze_video_overview(video_path, work_dir, scenes=None):
         "content": content,
         "chunks": chunk_results,
         "chunk_count": len(chunk_results),
-        "fps": CONFIG.get("mimo_video_fps", 2.0),
-        "media_resolution": CONFIG.get("mimo_media_resolution", "default"),
+        "fps": CONFIG["mimo_video_fps"],
+        "media_resolution": CONFIG["mimo_media_resolution"],
         "input": "scene_chunks",
         "partial": bool(unusable_chunks),
         "unusable_chunk_count": len(unusable_chunks),
-        "source_video_fingerprint": file_fingerprint(video_path),
-        "chunk_max_seconds": CONFIG.get("mimo_video_chunk_max_seconds", 20.0),
-        "settings": mimo_video_settings_fingerprint(),
-        "chunks_fingerprint": _mimo_cached_chunks_fingerprint(chunk_results),
+        "source_video_identity": file_identity(video_path),
+        "chunk_max_seconds": CONFIG["mimo_video_chunk_max_seconds"],
+        "settings": mimo_video_settings(),
     }
-    overview["overview_fingerprint"] = _mimo_overview_payload_fingerprint(overview)
     overview_path = work_dir / "mimo_video_overview.json"
     overview_path.write_text(json.dumps(overview, ensure_ascii=False, indent=2), encoding="utf-8")
     # 所有分片完成后清理增量缓存，保持 work_dir 仅有规范产物
-    try:
-        partial_path.unlink()
-    except OSError:
-        pass
+    partial_path.unlink(missing_ok=True)
     log(f"MiMo 分片视频概览完成: {overview_path}")
     return overview

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

@@ -3,9 +3,9 @@ name: video-voiceover
 user-invocable: false
 description: >
  把带时间戳的 narration.json 合成为中文解说音频。使用 MiMo TTS（mimo-v2.5-tts）或
- Fish Audio（s2.1-pro-free）逐段生成语音，
+ Fish Audio（s2.1-pro-free）或显式配置的通用 IndexTTS HTTP 服务逐段生成语音，
  按时间窗动态适配语速并处理响度；输入输出时间线上的旁白，产出 tts_segments 与 tts_meta.json。
- 旧版直接剪辑路径也可显式传入 narration_mapped.json。触发词：配音、语音合成、TTS、解说配音、
+ 触发词：配音、语音合成、TTS、解说配音、
  voiceover、text to speech、旁白配音。
 ---
 
@@ -23,51 +23,61 @@ export MIMO_API_KEY=***  # 也可使用仅供 TTS 的 MIMO_TTS_API_KEY
 export TTS_PROVIDER=fish-audio
 export FISH_API_KEY=***
 export FISH_TTS_REFERENCE_ID=<voice-model-id>  # 可选；覆盖内置“娱乐扒妹”音色
+
+# 或显式选择自托管 index-tts 端点，配置见 references/index-tts.md
+export TTS_PROVIDER=index-tts
 ```
 
 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
-脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的稿件、音频、参数与 `work_dir` 产物。
 
 ## 3. 输入契约
 
 默认输入为 `work_dir/narration.json`。每段必须包含 `start`、`end` 与 `narration`，可选字段包括
 `pause_after_ms` 和 `overlaps_speech`。时间统一表示音频最终放置的**输出时间线秒数**。
 
-编排式 cut 流程直接使用输出时间的 `narration.json`。只有旧版直接剪辑路径需要显式传入
-`narration_mapped.json`。
+cut 流程先剪后配：`narration.json` 本身就是按剪后成片的输出时间写的，不存在另一份映射稿。
 
 ## 4. 运行命令
 
 ```bash
 python3 scripts/voiceover.py --work-dir <work_dir> --narration <narration.json> \
-  [--tts-provider auto|mimo-tts|fish-audio] \
-  [--mimo-voice 冰糖 | --voice-ref <reference-audio>]
+  [--tts-provider auto|mimo-tts|fish-audio|index-tts] \
+  [--mimo-voice 冰糖 | --voice-ref <reference-audio>] \
+  [--preserve-approved-text]
 ```
 
-单独运行且省略 `--narration` 时，默认读取 `work_dir/narration.json`。旧版路径如需映射后的稿件，必须显式传入：
-
-```bash
-python3 scripts/voiceover.py --work-dir <work_dir> \
-  --narration <work_dir/narration_mapped.json>
-```
+单独运行且省略 `--narration` 时，默认读取 `work_dir/narration.json`；`--narration` 只用于指定其他路径的同格式稿件。
 
 ## 5. 输出契约
 
 - `tts_segments/*.wav`：每段旁白对应一个音频文件。
-- `tts_meta.json`：包含 `segments`、`engine` 与 `narration`。每段记录 `audio_path`、时间、
+- `tts_meta.json`：包含 `segments`、`engine`、`voice`（实际使用的 provider、模型、音色或参考音频）与 `narration`。每段记录 `audio_path`、时间、
   `pause_after_ms` 和放置字段。
 - 干净运行写入 `partial: false` 与 `failures: []`。
 - 使用 `--allow-partial-tts` 跳过失败段时，写入 `partial: true` 和
   `failures: [{index,start,end,text,error}]`，让缺失语音保持可见。
+- `--preserve-approved-text` 是显式的批准稿保护策略。每段保留原始 `authored_text`
+  证据；TTS 实际读取的 `spoken_text` 只经过既有的格式/舞台提示清理。若完整语音超过时间窗及
+  累计语速预算，命令失败并报告段序号、原稿、实读文本、语音时长和窗口证据，不写成功的
+  `tts_meta.json`。严格模式下任何必需段失败（包括供应商失败）都不能被
+  `--allow-partial-tts` 降级为可交付的部分成功；异常记录标为 `required: true` 并带策略 ID。
+  仅含 `[停顿]` 等清理标记、清理后无实读文本的作者段也属于必需段错误。
 
 ## 6. 运行规则
 
-- 重跑只复用内容与 TTS 设置均匹配的分段音频；修改旁白或合成参数后，只重生成受影响的 WAV。
+- 重跑只复用分段 sidecar 中记录的文本、TTS 设置与该 WAV 的 `size`/`mtime_ns` 均与当前相等的分段音频；
+  修改旁白或合成参数后，只重生成受影响的 WAV。
+- 批准稿保护策略属于缓存设置：严格模式不会命中旧的自动缩稿缓存；只有同一严格策略下、
+  `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 和官方免费期限约束。
 - `--voice-ref` 仅用于 full/cut 解说克隆，切换到 `mimo-v2.5-tts-voiceclone`。仅在确需新合成时惰性规范化一次；
-- dub voiceclone 原始 WAV 也会用模型、提示、台词和参考音频指纹缓存；匹配重跑不再重复请求或计费，`dub_manifest.json` 逐行记录 `tts_cache=hit|miss`；
-  参考音频内容或预处理指纹变化会使旧缓存失效。仅在获得授权后使用，参考音频会发送到 MiMo。
+- dub voiceclone 原始 WAV 也会按模型、提示、台词和参考音频的 `size`/`mtime_ns` 缓存；匹配重跑不再重复请求或计费，`dub_manifest.json` 逐行记录 `tts_cache=hit|miss`；
+  参考音频文件变化会使旧缓存失效。仅在获得授权后使用，参考音频会发送到 MiMo。
 - `TTS_WORKERS`、`TTS_TIMEOUT`、`TTS_RETRIES`、`ALLOW_PARTIAL_TTS` 用于调整并发、超时、重试与部分成功策略。
 - dub 模式有独立的确定性门禁：`dub_lint.json` 会在语音克隆前阻止空行、重叠或越界译文；
   `dub_review.json` 用于记录忠实度、语气、时长和平台适配复核。可通过
@@ -75,7 +85,7 @@ python3 scripts/voiceover.py --work-dir <work_dir> \
 
 ## 7. 能力边界
 
-- 不撰写或修改旁白文本。
+- 超窗时默认在句界自动缩稿并在 `spoken_text/truncated` 留痕；批准稿加 `--preserve-approved-text`。
 - 不混流、不压低原声、不渲染字幕。
 - 不分析视频，也不选择时间点；只为输入稿件中的既定分段配音。
-- Fish Audio 路径不接受本地 `--voice-ref`；使用已创建的 `FISH_TTS_REFERENCE_ID` 选择音色。
+- Fish Audio 与 IndexTTS 路径都不接受本地 `--voice-ref`；前者用已创建的 `FISH_TTS_REFERENCE_ID` 选择音色。

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

@@ -0,0 +1,31 @@
+# 自托管 IndexTTS 端点
+
+`--tts-provider index-tts` 或 `TTS_PROVIDER=index-tts` 显式选择自托管的 index-tts 协议服务（JSON→WAV）。
+`auto` 永不兜底选择它。
+
+## 配置
+
+```bash
+export TTS_PROVIDER=index-tts
+export INDEX_TTS_ENDPOINT=http://127.0.0.1:<port>/tts
+export INDEX_TTS_VOICE=<authorized-voice-name>
+```
+
+- 缺 `INDEX_TTS_ENDPOINT` 或 `INDEX_TTS_VOICE` 时在缓存/请求前失败。
+- endpoint 只接受无 userinfo/query/fragment 的 HTTP(S) URL，且请求禁止重定向，避免把批准文本转发至其他主机。
+- 不接受 `--voice-ref` / `--mimo-voice`。
+
+## 请求契约
+
+请求体固定为 `{"voice": voice, "text": spoken_text}`。当前段 schema 的可选 `emotion`
+以及额外 style、非默认 rate/pitch 控制会显式失败，不会静默忽略。原始合成使用 provider 默认速度，
+不按标点、长度或位置自动计算 rate；这不等于下游放置阶段的端到端 tempo 锁。
+
+## Receipt 与缓存
+
+每段的 `provider_receipt` 只记录 `provider` 与“请求的 voice”（`requested_voice`）。它说明请求参数，
+不是该声线的声学验证，也不代表已做人耳听审或音色身份验证。endpoint 不写入任何文件。
+
+缓存复用条件：sidecar 中的文本与设置（含 `index_tts_voice`）与当前相等、WAV 的 `size`/`mtime_ns` 未变，
+且 sidecar 的 receipt 对应当前 voice；缓存命中复用 sidecar 中的 receipt，不能现场补造。
+服务端模型或部署变化不会被自动察觉；更换声线实现后请删除 `tts_segments/*.cache.json` 强制重合成。