@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-recap/references/resource-library.md

@@ -0,0 +1,151 @@
+# 资源库、模板与样片
+
+资源库是你自己的目录，与素材库共用同一个根目录（`--material-library-dir` / `VIDEO_RECAP_MATERIAL_LIBRARY_DIR`）。
+仓库不内置任何真实 BGM、音效、音色、字体或包装；合成示例见仓库的 `examples/resource-library/`。
+
+```text
+<library>/
+  library.json                                     # {"schema": "video-recap.library.v1", "name": "…"}
+  materials/…                                      # 理解分析库（见 data-schema.md），不变
+  resources/<kind>/<id>/resource.json (+ 文件)
+  templates/<kind>/<id>/v<version>/template.json
+  samples/<id>/sample.json (+ 样片文件，或指向库外的绝对路径)
+```
+
+只读工具（本技能目录下）：
+
+```bash
+python3 scripts/library.py --library-dir <library> check          # 有错误时退出码 1；--json 输出机器可读报告
+python3 scripts/library.py --library-dir <library> list [--kind bgm]
+python3 scripts/library.py --library-dir <library> show <id|id@vN>
+```
+
+浏览资源、模板与样片（含图片、音频与样片预览）可用只读 dashboard：`python3 scripts/dashboard_server.py --root <library 或其上层目录>`。
+
+工具从不写库。新增或修改记录时直接编辑 JSON，再跑 `check`。**错误**表示该条目不能用；**警告**表示能用但需要人看一眼
+（授权未确认、声音授权未确认、样片不在本机、模板采用后资源文件已变化）。
+
+## 通用规则
+
+- `id` 与所在目录名一致，只用小写字母、数字和 `. _ -`；模板目录名为 `v<version>`。
+- 顶层字段严格：出现未列出的字段即报错，避免拼错的字段被静默忽略。
+- 文件路径相对记录所在目录，解析后必须仍在库根目录内（`..` 越界、绝对路径和指向库外的符号链接都报错）。
+  唯一例外是样片可以写绝对路径，因为成片常放在别的盘上。
+- 文件身份是 `{size, mtime_ns}`，不计算内容哈希。
+- 派生文件（归一化 WAV、转码片段）只出现在 work_dir，不回写为资源。
+
+## 资源 `resource.json`
+
+```json
+{
+  "schema": "video-recap.resource.v1",
+  "id": "pulse-demo",
+  "kind": "bgm",
+  "title": "合成脉冲底噪（演示）",
+  "files": [{"role": "main", "path": "pulse-demo.wav"}],
+  "origin": {"creator": "…", "url": "…"},
+  "license": {"status": "owned", "terms": "…", "evidence": "…"},
+  "tags": ["低频"],
+  "notes": ""
+}
+```
+
+| `kind` | 文件 | 额外字段 |
+|---|---|---|
+| `bgm` / `sfx` | 至少一个音频文件（wav / mp3 / m4a / aac / flac / ogg） | — |
+| `voice` | 可选参考音频 | `voice.provider` ∈ `mimo-tts` / `fish-audio` / `index-tts`，以及 `voice.voice_id` 或一个参考音频；有参考音频时必须写 `consent.status` ∈ `unknown` / `granted` / `denied` |
+| `font` | 至少一个字体文件（ttf / otf / ttc） | 可选 `font.family`、`font.index` |
+| `image` | 至少一个图片（png / jpg / webp），用于 logo、包框、片尾卡 | — |
+
+`license.status` ∈ `unknown` / `owned` / `licensed` / `restricted`，只能由人填写；工具不会因为文件放在库里就认为有授权。
+`unknown` 与 `restricted` 在 `check` 中是警告。
+
+## 模板 `template.json`
+
+```json
+{
+  "schema": "video-recap.template.v1",
+  "id": "clean-white",
+  "version": 1,
+  "kind": "subtitle_style",
+  "title": "白字细描边",
+  "canvas": {"width": 900, "height": 1600},
+  "params": {
+    "font": {"family": "Arial"},
+    "size_px": {"value": 52, "provenance": "specified"},
+    "max_chars": {"value": 15, "provenance": "measured"},
+    "band": {"value": {"y_top": 1280, "y_bot": 1440}, "provenance": "measured"}
+  },
+  "samples": ["demo-sample"],
+  "status": "adopted",
+  "adoption": {"date": "2026-09-27", "by": "user", "statement": "用户原话", "scope": "适用范围"}
+}
+```
+
+- 模板只对 `canvas` 声明的画布有效；换画幅就是新模板，不自动缩放套用。
+- 任何带 `provenance` 的参数都要有 `value`，`provenance` ∈ `measured`（从成片实测）/ `fitted`（反复调出来的）/
+  `specified`（人直接给的数值）/ `unknown`。编辑器面板上的读数不是像素，按 `specified` 或 `unknown` 记。
+- 引用资源写 `{"resource": "<id>"}`：`params.font` 必须指向 `font` 资源，图层的 `image` 必须指向 `image` 资源。
+- `subtitle_style` 需要 `params.font`（`resource` 或 `family`）、`params.size_px` 与 `params.max_chars`（每行最多字数，用最长一行在这块画布上校准）；
+  `size_px × max_chars` 超过画布宽减去两侧各 40px 默认边距时报错。可选 `outline_px`、`shadow_px`、`primary_color`、`outline_color`、`max_lines`、`band`，其他参数名报错；`params.band.value` 若给出，需满足
+  `0 <= y_top < y_bot <= canvas.height`。
+- `packaging` 需要非空 `params.layers`，每层有唯一 `name`、`image` 引用与画布内的整数 `rect {x, y, width, height}`；
+  可选 `params.safe_rect`。
+- `status` ∈ `draft` / `adopted` / `retired`。`adopted` 必须有 `adoption.date`（YYYY-MM-DD）、`by`、`statement`（用户原话）
+  与 `scope`。可选 `adoption.resources` 记录采用时所用资源文件的身份：
+
+  ```json
+  "resources": {"frame-demo": [{"path": "resources/image/frame-demo/frame-demo.png", "size": 6063, "mtime_ns": 0}]}
+  ```
+
+  之后文件的大小或修改时间变化，`check` 给出 `changed_since_adoption` 警告：重新采用，或出一个新版本。
+  修改时间是本机事实，把库拷到另一台机器会让所有快照都显示为已变化。
+
+## 样片 `sample.json`
+
+```json
+{
+  "schema": "video-recap.sample.v1",
+  "id": "demo-sample",
+  "title": "纯色演示片",
+  "file": {"path": "demo-sample.mp4"},
+  "canvas": {"width": 900, "height": 1600},
+  "demonstrates": ["字幕带位置", "画布尺寸"],
+  "not_reusable": "这条样片里哪些东西不能照搬",
+  "templates": ["clean-white@v1"]
+}
+```
+
+样片是证据，不是模板：`demonstrates` 写它示范了什么，`not_reusable` 写不能照搬什么（人物、字幕内容、时间码……）。
+`templates` 用 `id@vN` 指回它所示范的模板版本。
+
+## 项目绑定 `recap_project.json`
+
+```json
+{
+  "schema": "video-recap.project.v1",
+  "name": "某系列竖屏解说",
+  "library": "../video-library",
+  "bindings": {"subtitle_style": "clean-white@v1", "voice": "narrator-demo", "bgm": "pulse-demo"}
+}
+```
+
+`python3 scripts/recap.py <video> --project <recap_project.json 或所在目录> …` 在任何阶段开始前解析绑定：`library` 相对项目文件；
+模板必须是 `adopted`；资源与模板必须通过 `check`。解析结果只以各阶段已有的设置下发，阶段技能不读资源库：
+
+| 绑定 | 下发为 |
+|---|---|
+| `subtitle_style` | `SUBTITLE_PLAY_RES_X/Y` = 模板画布，`SUBTITLE_FONT_SIZE` ← `size_px`，`SUBTITLE_OUTLINE` ← `outline_px`，`SUBTITLE_SHADOW` ← `shadow_px`，`SUBTITLE_PRIMARY_COLOR` / `SUBTITLE_OUTLINE_COLOR`（ASS `&HAABBGGRR`），`SUBTITLE_MAX_CHARS` / `SUBTITLE_MAX_LINES`；`band` → 底对齐 `SUBTITLE_ALIGNMENT=2` 且 `SUBTITLE_MARGIN_V` = 画布高 − `y_bot`；`font.family` → `SUBTITLE_FONT_NAME`，字体资源 → 再加 `SUBTITLE_FONT_FILE` |
+| `voice` | provider → `--tts-provider`；MiMo 预置音色 → `--mimo-tts-voice`，参考音频 → `--voice-ref`；Fish Audio → `FISH_TTS_REFERENCE_ID`；index-tts → `INDEX_TTS_VOICE` |
+| `bgm` | `BGM_PATH` ← 该资源的第一个文件 |
+| `packaging` | 合成前写出 `work_dir/packaging_layers.json`：每个图层的图片资源第一个文件 + `rect`，由 video-assemble 叠加到成片并写进 `timeline.json` 的 image 轨 |
+
+- 你已经显式设置的参数或环境变量与绑定不一致时，运行在开始前停止并指出是哪一项，不会静默覆盖。
+- 合成前核对模板画布与实际成片画布；不一致即停止——换画幅要用另一个模板。
+- 参考音频的 `consent.status` 为 `denied` 时拒绝绑定；dub 模式与本地采用三件套不接受 `--project`。
+- 续跑命令只带 `--project`，不重复写出由绑定得到的值，改了绑定后续跑会按新绑定解析。
+
+## 运行记录
+
+每次 full / cut 合成后，`work_dir/resource_lock.json` 记下这次用到的原片、音色、BGM 与字幕字体，并对上资源库里的登记和授权状态；
+格式见 `data-schema.md` 的 resource_lock.json 一节。

package/lib/video-recap/skills/video-recap/references/shift-left-qc-schema.md

@@ -9,7 +9,7 @@
 - `stage`：只能是 `pre_cut`、`post_cut`、`pre_tts`、`post_tts`、`pre_assemble`、`post_render`、`golden`。
   - 不得使用 `pre_voiceover`、`post_voiceover`、`pre_export`、`post_export`、`final`、`golden_eval` 或 `mimo_qc` 作为阶段值。
   - `mimo_qc.json` 是产物名；MiMo finding 必须挂在 `post_tts`、`pre_assemble` 等真实阶段上。
-- `findings[]`：每项必须包含 `finding_id`、`stage`、`severity`、`blocking`、`deterministic`、`confidence`、`rule_id`、`decision_reason`、`location`、`evidence`、`sample_policy`、`model_used`、`artifact_fingerprints` 与 `next_action`。
+- `findings[]`：每项必须包含 `finding_id`、`stage`、`severity`、`blocking`、`deterministic`、`confidence`、`rule_id`、`decision_reason`、`location`、`evidence`、`sample_policy`、`model_used` 与 `next_action`。
 - `sample_policy`：至少包含 `type`；其值只能是 `all`、`deterministic`、`sampled`、`semantic` 或 `aesthetic`。
 - `location.timecode` 与 `location.source_span` 必须存在；剪辑前阶段可以把任一字段设为 `null`。
 - 为兼容与诊断，当前辅助函数还可能写出 `id`、`category`、`code`、`message`、`source` 与 `objective_corroboration`。

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

@@ -1,15 +1,18 @@
 #!/usr/bin/env python3
 """Environment doctor for the video-recap skill bundle.
 
-The pipeline runs on ffmpeg + MiMo for understanding; voiceover may use MiMo or Fish Audio.
+The pipeline runs on ffmpeg + MiMo for understanding; voiceover may explicitly use
+MiMo, Fish Audio, or a privately configured Index TTS endpoint.
 """
 from __future__ import annotations
 
 import argparse
 import json
+import os
 import shutil
 import subprocess
 import sys
+import urllib.parse
 from pathlib import Path
 
 from lib import CONFIG
@@ -17,7 +20,7 @@ from lib import CONFIG
 
 SCRIPT_DIR = Path(__file__).resolve().parent
 DEGRADED_GROUP = "warnings/degraded"
-TTS_PROVIDERS = {"auto", "mimo-tts", "fish-audio"}
+TTS_PROVIDERS = ("auto", "mimo-tts", "fish-audio", "index-tts")
 
 
 def _command_path(name: str) -> str | None:
@@ -25,6 +28,10 @@ def _command_path(name: str) -> str | None:
 
 
 def _ffmpeg_filters() -> set[str]:
+    """Filters the installed ffmpeg lists; empty when ffmpeg is absent.
+
+    A present ffmpeg whose `-filters` fails or hangs is an environment fault and raises,
+    so it is never misreported downstream as "filter absent"."""
     ffmpeg = _command_path("ffmpeg")
     if not ffmpeg:
         return set()
@@ -32,10 +39,11 @@ def _ffmpeg_filters() -> set[str]:
         result = subprocess.run(
             [ffmpeg, "-hide_banner", "-filters"], text=True, capture_output=True, timeout=20
         )
-    except (OSError, subprocess.SubprocessError):
-        return set()
+    except (OSError, subprocess.SubprocessError) as exc:
+        raise RuntimeError(f"`ffmpeg -filters` failed or hung: {exc}") from exc
     if result.returncode != 0:
-        return set()
+        detail = (result.stderr or result.stdout or "").strip()[:300]
+        raise RuntimeError(f"`ffmpeg -filters` failed (exit {result.returncode}): {detail}")
     filters = set()
     for line in result.stdout.splitlines():
         parts = line.split()
@@ -62,11 +70,44 @@ def _asr_status() -> dict[str, object]:
         "mimo_asr_api_url": CONFIG["mimo_asr_api_url"],
         "mimo_asr_api_url_source": CONFIG["mimo_asr_api_url_source"],
         "mimo_asr_language": CONFIG["mimo_asr_language"],
-        "mimo_asr_api_key_source": CONFIG["mimo_asr_api_key_source"],
+        "mimo_asr_env_var": CONFIG["mimo_asr_env_var"],
         "note": "ASR uses MiMo (mimo-v2.5-asr); set MIMO_API_KEY, or run with --skip-asr.",
     }
 
 
+def _index_tts_status() -> dict[str, object]:
+    """Validate private Index settings locally without exposing or contacting them."""
+    endpoint = os.environ.get("INDEX_TTS_ENDPOINT", "")
+    voice = os.environ.get("INDEX_TTS_VOICE", "").strip()
+    has_forbidden_control = any(
+        ord(char) < 32 or ord(char) == 127 for char in endpoint
+    )
+    try:
+        parsed = urllib.parse.urlsplit(endpoint) if endpoint else None
+        port = parsed.port if parsed else None
+    except ValueError:
+        parsed = None
+        port = None
+    endpoint_format_valid = bool(
+        parsed
+        and not has_forbidden_control
+        and parsed.scheme in {"http", "https"}
+        and parsed.hostname
+        and "@" not in parsed.netloc
+        and not parsed.query
+        and not parsed.fragment
+        and (port is None or 1 <= port <= 65535)
+    )
+    return {
+        "index_tts_endpoint_set": bool(endpoint),
+        "index_tts_endpoint_format_valid": endpoint_format_valid,
+        "index_tts_voice_set": bool(voice),
+        "index_tts_configured": endpoint_format_valid and bool(voice),
+        "connectivity_checked": False,
+        "validation_scope": "offline configuration only; connectivity and acoustic quality not checked",
+    }
+
+
 def _capability(name: str, summary: str, *, detail: str = "", action: str = "") -> dict[str, str]:
     item = {"name": name, "summary": summary}
     if detail:
@@ -126,7 +167,7 @@ def _build_capability_menu(checks: dict) -> dict[str, list[dict[str, str]]]:
             _capability(
                 "mimo_credentials",
                 "MiMo API key is configured",
-                detail=f"Source: {api['api_key_source']}",
+                detail=f"Source: {api['api_env_var']}",
             )
         )
     else:
@@ -156,24 +197,37 @@ def _build_capability_menu(checks: dict) -> dict[str, list[dict[str, str]]]:
         )
 
     tts_provider = tts["provider"]
+    if tts_provider == "index-tts":
+        capability_name = "index_tts_configuration"
+        action = "Set valid INDEX_TTS_ENDPOINT and INDEX_TTS_VOICE values before voiceover."
+    elif tts_provider == "fish-audio":
+        capability_name = "fish_audio_tts"
+        action = "Set FISH_API_KEY before voiceover."
+    else:
+        capability_name = "mimo_tts"
+        action = "Set MIMO_TTS_API_KEY or the shared MIMO_API_KEY before voiceover."
     if tts_ready:
         menu["ready"].append(
             _capability(
-                "fish_audio_tts" if tts_provider == "fish-audio" else "mimo_tts",
-                f"{tts_provider} is configured",
-                detail=f"Model: {tts['model']}",
+                capability_name,
+                (
+                    "index-tts configuration is present"
+                    if tts_provider == "index-tts"
+                    else f"{tts_provider} is configured"
+                ),
+                detail=(
+                    tts["validation_scope"]
+                    if tts_provider == "index-tts"
+                    else f"Model: {tts['model']}"
+                ),
             )
         )
     elif api_key_set:
         menu["blocked"].append(
             _capability(
-                "fish_audio_tts" if tts_provider == "fish-audio" else "mimo_tts",
+                capability_name,
                 f"{tts_provider} is not configured",
-                action=(
-                    "Set FISH_API_KEY before voiceover."
-                    if tts_provider == "fish-audio"
-                    else "Set MIMO_TTS_API_KEY or the shared MIMO_API_KEY before voiceover."
-                ),
+                action=action,
             )
         )
 
@@ -217,7 +271,19 @@ def _build_capability_menu(checks: dict) -> dict[str, list[dict[str, str]]]:
         )
     elif asr_ready and subtitles_ready:
         menu["ready"].append(
-            _capability("default_recap_pipeline", "Default recap run is ready", detail="ASR, VLM, TTS, and media tools are configured.")
+            _capability(
+                "default_recap_pipeline",
+                (
+                    "Recap prerequisites are configured"
+                    if tts_provider == "index-tts"
+                    else "Default recap run is ready"
+                ),
+                detail=(
+                    "ASR, VLM, and media tools are configured; Index TTS passed offline configuration checks only."
+                    if tts_provider == "index-tts"
+                    else "ASR, VLM, TTS, and media tools are configured."
+                ),
+            )
         )
     else:
         actions = []
@@ -259,15 +325,25 @@ def build_report(*, tts_provider: str | None = None) -> dict[str, object]:
     mimo_video_configured = bool(CONFIG["mimo_video_api_key"])
     mimo_tts_configured = bool(CONFIG["mimo_tts_api_key"])
     fish_tts_configured = bool(CONFIG["fish_api_key"])
+    index_tts = _index_tts_status()
     requested_tts_provider = tts_provider or CONFIG["tts_provider"]
     effective_tts_provider = requested_tts_provider
     if requested_tts_provider == "auto":
         effective_tts_provider = (
             "mimo-tts" if mimo_tts_configured or not fish_tts_configured else "fish-audio"
         )
-    tts_configured = (
-        fish_tts_configured if effective_tts_provider == "fish-audio" else mimo_tts_configured
-    )
+    if effective_tts_provider == "fish-audio":
+        tts_configured = fish_tts_configured
+    elif effective_tts_provider == "index-tts":
+        tts_configured = index_tts["index_tts_configured"]
+    else:
+        tts_configured = mimo_tts_configured
+    if effective_tts_provider == "fish-audio":
+        tts_model = CONFIG["fish_tts_model"]
+    elif effective_tts_provider == "index-tts":
+        tts_model = "provider-managed"
+    else:
+        tts_model = CONFIG["mimo_tts_model"]
     subtitle_filter = "subtitles" in filters
     checks = {
         "system_tools": {
@@ -294,11 +370,8 @@ def build_report(*, tts_provider: str | None = None) -> dict[str, object]:
             "fish_tts_model": CONFIG["fish_tts_model"],
             "fish_tts_reference_id_set": bool(CONFIG["fish_tts_reference_id"]),
             "fish_tts_reference_id_source": CONFIG["fish_tts_reference_id_source"],
-            "model": (
-                CONFIG["fish_tts_model"]
-                if effective_tts_provider == "fish-audio"
-                else CONFIG["mimo_tts_model"]
-            ),
+            **index_tts,
+            "model": tts_model,
             "available": tts_configured,
         },
         "asr": _asr_status(),
@@ -306,7 +379,7 @@ def build_report(*, tts_provider: str | None = None) -> dict[str, object]:
             "api_provider": CONFIG["api_provider"],
             "api_url": CONFIG["api_url"],
             "api_url_source": CONFIG["api_url_source"],
-            "api_key_source": CONFIG["api_key_source"],
+            "api_env_var": CONFIG["api_env_var"],
             "api_key_set": bool(CONFIG["api_key"]),
             "vlm_model": CONFIG["vlm_model"],
             "vlm_model_source": CONFIG["vlm_model_source"],
@@ -330,8 +403,17 @@ def build_report(*, tts_provider: str | None = None) -> dict[str, object]:
             failures.append(f"Missing system tool: {name}")
     if requested_tts_provider not in TTS_PROVIDERS:
         failures.append(
-            "TTS_PROVIDER must be one of: auto, mimo-tts, fish-audio"
+            "TTS_PROVIDER must be one of: " + ", ".join(TTS_PROVIDERS)
         )
+    elif requested_tts_provider == "index-tts":
+        if not index_tts["index_tts_endpoint_set"]:
+            failures.append("INDEX_TTS_ENDPOINT is not set")
+        elif not index_tts["index_tts_endpoint_format_valid"]:
+            failures.append(
+                "INDEX_TTS_ENDPOINT must be an http/https URL with a hostname and no credentials, query, or fragment"
+            )
+        if not index_tts["index_tts_voice_set"]:
+            failures.append("INDEX_TTS_VOICE is not set")
     if tools["ffmpeg"] and not tools["ffmpeg_subtitles_filter"]:
         warnings.append("ffmpeg lacks subtitles/libass filter; --burn-subtitles will fail")
     if not checks["api_config"]["api_key_set"]:
@@ -375,7 +457,7 @@ def _print_human(report: dict) -> None:
     print(f"✓ API URL: {api['api_url']} (source: {api['api_url_source']})")
     print(
         f"{_status_icon(api['api_key_set'])} "
-        f"{api['api_key_source']}: {'set' if api['api_key_set'] else 'not set'}"
+        f"{api['api_env_var']}: {'set' if api['api_key_set'] else 'not set'}"
     )
     print(f"✓ VLM model: {api['vlm_model']} (source: {api['vlm_model_source']})")
     print(f"✓ VLM_WORKERS: {api['vlm_workers']}")
@@ -385,7 +467,7 @@ def _print_human(report: dict) -> None:
     print(
         f"{_status_icon(asr['available'], warning=True)} "
         f"MiMo ASR: {'configured' if asr['available'] else 'not configured'} "
-        f"(key: {asr['mimo_asr_api_key_source']})"
+        f"(key: {asr['mimo_asr_env_var']})"
     )
     print(f"✓ ASR model: {asr['mimo_asr_model']}")
     print(f"✓ ASR API URL: {asr['mimo_asr_api_url']} (source: {asr['mimo_asr_api_url_source']})")
@@ -407,6 +489,17 @@ def _print_human(report: dict) -> None:
             f"(source: {tts['fish_tts_reference_id_source']})"
         )
         print(f"✓ TTS API URL: {tts['fish_tts_api_url']}")
+    elif tts["provider"] == "index-tts":
+        print(
+            f"{_status_icon(tts['index_tts_endpoint_format_valid'])} "
+            "Index TTS endpoint: "
+            f"{'configured with valid format' if tts['index_tts_endpoint_format_valid'] else 'missing or invalid'}"
+        )
+        print(
+            f"{_status_icon(tts['index_tts_voice_set'])} Index TTS voice: "
+            f"{'configured' if tts['index_tts_voice_set'] else 'not set'}"
+        )
+        print(f"! Validation scope: {tts['validation_scope']}")
     else:
         print(f"✓ TTS voice: {tts['mimo_tts_voice']} (source: {tts['mimo_tts_voice_source']})")
         print(f"✓ TTS API URL: {tts['mimo_tts_api_url']} (source: {tts['mimo_tts_api_url_source']})")
@@ -444,7 +537,7 @@ def main() -> int:
     parser.add_argument("--json", action="store_true", help="Print machine-readable JSON")
     parser.add_argument(
         "--tts-provider",
-        choices=("auto", "mimo-tts", "fish-audio"),
+        choices=TTS_PROVIDERS,
         default=None,
         help="override the TTS provider for this preflight report",
     )