@oh-story/dsh 0.1.9 → 0.1.11

package/lib/video-recap/skills/video-script/scripts/validate.py

@@ -2,8 +2,9 @@
 """video-script validation entrypoint.
 
 Validate an agent-written narration.json against the local understanding index.
-Writes narration_lint.json and, in full mode, rewrites only normalized fields plus
-the measured overlaps_speech flag; authored start/end timing is preserved exactly.
+Legacy full mode performs budget cleanup/deduplication and derives speech ownership.
+Protected mode keeps the approved timeline and metadata exact except for measured
+``overlaps_speech`` ownership.
 """
 
 import argparse
@@ -11,7 +12,7 @@ import json
 import math
 from pathlib import Path
 
-from lib import CONFIG, log, stable_hash
+from lib import CONFIG, log
 from narration_lint import (
     _validate_narration_budget,
     validate_narration_or_raise,
@@ -33,47 +34,27 @@ def _load_cut_clip_plan(work_dir):
     if not raw_plan.exists():
         return _load(validated_plan)
 
-    raw = _load(raw_plan)
-    validated = _load(validated_plan)
-    if isinstance(validated, dict) and validated.get(
-        "raw_plan_fingerprint"
-    ) == stable_hash(raw):
-        return validated
-    # Validation may run before the cut stage refreshes clip_plan_validated.json.
-    # Without a matching raw-plan provenance fingerprint, lint against the current
-    # raw plan even when mtimes are equal or misleading.
-    return raw
+    # Validation may run before the cut stage refreshes clip_plan_validated.json;
+    # a validated plan older than the raw plan is stale, so lint against the raw plan.
+    if validated_plan.stat().st_mtime_ns >= raw_plan.stat().st_mtime_ns:
+        return _load(validated_plan)
+    return _load(raw_plan)
 
 
-def _validate_output_timeline_bounds(narration, output_duration, tolerance=0.05):
-    """Hard-gate cut_output narration against the rendered output timeline.
+def _validate_output_timeline_bounds(narration, duration, tolerance=0.05):
+    """Hard-gate lint-validated cut_output narration against the rendered output timeline.
 
     cut_output narration is authored in edited_source.mp4 time. If any segment falls outside
     that media duration, fail before TTS/render instead of spending time on unusable audio.
     """
-    try:
-        duration = float(output_duration)
-    except (TypeError, ValueError):
-        raise SystemExit(f"output_duration must be numeric, got {output_duration!r}")
     if not math.isfinite(duration) or duration <= 0:
         raise SystemExit(
             f"output_duration must be finite and positive, got output_duration={duration:.3f}"
         )
-    if not isinstance(narration, list):
-        return
 
     problems = []
     for idx, seg in enumerate(narration):
-        if not isinstance(seg, dict):
-            continue
-        try:
-            start = float(seg.get("start"))
-            end = float(seg.get("end"))
-        except (TypeError, ValueError):
-            continue
-        if not math.isfinite(start) or not math.isfinite(end):
-            problems.append(f"segment {idx} has non-finite time [{start!r},{end!r}]")
-            continue
+        start, end = seg["start"], seg["end"]
         if end <= -tolerance or start >= duration + tolerance:
             problems.append(
                 f"segment {idx} [{start:.3f},{end:.3f}] fully outside output_duration={duration:.3f}"
@@ -106,6 +87,11 @@ def main():
         default=None,
         help="cut_output: rendered edited_source.mp4 duration in seconds",
     )
+    ap.add_argument(
+        "--preserve-approved-text",
+        action="store_true",
+        help="validate approved narration without rewriting, truncating, merging, or reordering it",
+    )
     args = ap.parse_args()
 
     work_dir = Path(args.work_dir)
@@ -118,17 +104,33 @@ def main():
     silence_periods = _load(work_dir / "silence_periods.json") or []
     if args.mode == "cut_output":
         # Two-pass cut: narration is authored in OUTPUT time against edited_source.mp4 — there is
-        # no source-time clip membership check. Derive speech ownership from the mapped output
-        # evidence, then persist that measured flag for voiceover/assemble instead of trusting JSON.
+        # no source-time clip membership check. Lint the authored shape first, then derive speech
+        # ownership from the mapped output evidence and persist that measured flag for
+        # voiceover/assemble instead of trusting JSON.
+        report = validate_narration_or_raise(
+            narration, None, clip_plan=None, mode="cut_output", work_dir=work_dir,
+            require_chronological=args.preserve_approved_text,
+        )
         narration = measure_narration_speech_ownership(
             narration, work_dir, mode="cut_output"
         )
-        validate_narration_or_raise(
-            narration, None, clip_plan=None, mode="cut_output", work_dir=work_dir
-        )
-        if args.output_duration is None:
-            raise SystemExit("--output-duration is required when --mode cut_output")
-        _validate_output_timeline_bounds(narration, args.output_duration)
+        try:
+            if args.output_duration is None:
+                raise SystemExit("--output-duration is required when --mode cut_output")
+            _validate_output_timeline_bounds(narration, args.output_duration)
+        except SystemExit as exc:
+            report["errors"].append({
+                "level": "error",
+                "index": None,
+                "code": "invalid_output_timeline",
+                "message": str(exc),
+            })
+            report["ok"] = False
+            report["error_count"] = len(report["errors"])
+            (work_dir / "narration_lint.json").write_text(
+                json.dumps(report, ensure_ascii=False, indent=2), encoding="utf-8"
+            )
+            raise
         narration_path.write_text(
             json.dumps(narration, ensure_ascii=False, indent=2), encoding="utf-8"
         )
@@ -137,12 +139,21 @@ def main():
         validate_narration_or_raise(
             narration, vlm_analysis, clip_plan=clip_plan, mode="cut", work_dir=work_dir
         )
-        narration = _validate_narration_budget(narration, vlm_analysis)
+        if not args.preserve_approved_text:
+            narration = _validate_narration_budget(narration, vlm_analysis)
     else:
         validate_narration_or_raise(
-            narration, vlm_analysis, clip_plan=None, mode="full", work_dir=work_dir
+            narration, vlm_analysis, clip_plan=None, mode="full", work_dir=work_dir,
+            require_chronological=args.preserve_approved_text,
         )
-        narration = _align_narration_to_quiet(narration, vlm_analysis, silence_periods)
+        if args.preserve_approved_text:
+            narration = measure_narration_speech_ownership(
+                narration, work_dir, mode="full"
+            )
+        else:
+            narration = _align_narration_to_quiet(
+                narration, vlm_analysis, silence_periods
+            )
         narration_path.write_text(
             json.dumps(narration, ensure_ascii=False, indent=2), encoding="utf-8"
         )

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

@@ -21,7 +21,8 @@ description: >
 
 1. **场景检测**：写 `scenes.json`，包含切点、时长和废片段过滤结果。
 2. **抽帧**：为视觉分析提取代表帧。
-3. **ASR**：通过 `mimo-v2.5-asr` 写时间戳对白 `asr_result.json`。
+3. **ASR**：通过 `mimo-v2.5-asr` 写粗分段对白 `asr_result.json`，并写
+   `asr_timing_evidence.json` 说明可用性、有限时间精度与文本修正来源。
 4. **静音检测**：写 `silence_periods.json`，标注安静窗口与 `has_speech`。
 5. **VLM 观察**：写 `vlm_analysis.json`，包含场景描述、深层分析和 `frame_facts`。
 6. **时间线融合与创作 brief**：写 `timeline_fusion.json`、`asr_writing_chunks.json` 和 `agent_narration_brief.md`。
@@ -39,7 +40,7 @@ ASR 使用 `mimo-v2.5-asr`；VLM 使用 `mimo-v2.5`。`--skip-asr` 可跳过对
 
 若 `work_dir/background_research.json` 存在，本技能会把剧情梗概和角色名折入 VLM 上下文；`--context` 可补充一条简短提示。
 
-下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的视频、参数与 `work_dir` 产物。
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
 
 ## 4. 运行命令
 
@@ -54,6 +55,7 @@ python3 scripts/understand.py <video> --work-dir <work_dir> \
 |------|------|
 | `scenes.json` | 场景切点、起止时间与时长 |
 | `asr_result.json` | `[{start, end, text}]` 时间戳对白 |
+| `asr_timing_evidence.json` | ASR 可用性状态、粗窗口精度、glossary 前后文本，以及它所描述的源视频/音频/结果文件（路径存在性 + size/mtime） |
 | `vlm_analysis.json` | 逐场景描述、深层分析与 `frame_facts` |
 | `silence_periods.json` | `[{start, end, duration, has_speech}]` 安静窗口 |
 | `timeline_fusion.json` | VLM、ASR 与静音信息的统一时间线 |
@@ -70,6 +72,6 @@ python3 scripts/understand.py <video> --work-dir <work_dir> \
 ## 7. 能力边界
 
 - 不写解说词，也不做解说评分；只负责生成理解索引与创作简报。
-- 不剪辑、不配音、不合成视频。
 - 不编造信号无法支持的剧情；当 ASR / VLM 过薄时输出素材警告。
-- 不发布、不调度，只向 `work_dir` 写产物并停止。
+- MiMo ASR 的 `start/end` 是固定分片形成的**粗窗口**，不是词级对齐；空文本只表示原因未知，
+  不能当作已证实静音。`asr_timing_evidence.json` 的状态字段见 `references/data-schema.md`。

package/lib/video-recap/skills/video-understanding/references/data-schema.md

@@ -41,6 +41,52 @@
 ]
 ```
 
+`start/end` 仅表示送入 MiMo ASR 的固定粗分片窗口。该列表为兼容产物，不能据此声称词级
+时间、准确对白边界或静音证明；空 `text` 的原因未知。
+
+## asr_timing_evidence.json
+
+ASR 的独立证据 sidecar，不改变 `asr_result.json` 的既有数组结构。它记录自己描述的是哪一份源视频、
+`audio.wav`（存在时）和 `asr_result.json`（各自的 `size` + `mtime_ns`），并明确当前精度边界：
+
+```json
+{
+  "schema_version": 2,
+  "status": "AVAILABLE_COARSE",
+  "source_video": {"size": 123456, "mtime_ns": 1700000000000000000},
+  "audio": {"size": 2048, "mtime_ns": 1700000001000000000},
+  "asr_result": {"size": 512, "mtime_ns": 1700000002000000000},
+  "glossary": {
+    "names": ["叶轻眉"],
+    "name_count": 1
+  },
+  "precision": {
+    "window_timing": "COARSE_SEGMENT_WINDOWS",
+    "dialogue_boundaries": "NOT_VERIFIED",
+    "word_alignment": "NOT_PERFORMED",
+    "empty_text_meaning": "UNKNOWN_NOT_PROVEN_SILENCE"
+  },
+  "windows": [{
+    "index": 0,
+    "start": 0.0,
+    "end": 3.5,
+    "text_availability": "AVAILABLE",
+    "observed_text": "她叫叶青眉",
+    "post_glossary_text": "她叫叶轻眉",
+    "glossary_modified": true
+  }]
+}
+```
+
+`status` 可为 `AVAILABLE_COARSE`、`EXPLICITLY_SKIPPED`、`UNAVAILABLE_NO_KEY`、
+`UNAVAILABLE_NO_DURATION`、`FAILED_AUDIO_EXTRACTION`、`FAILED_PROVIDER`、`EMPTY_UNKNOWN`
+或 `LEGACY_UNVERIFIED`。`LEGACY_UNVERIFIED` 标记没有旧 sidecar 的兼容缓存，可离线复用但
+`observed_text`/`glossary_modified` 为 `null`，且始终保持 legacy 身份；非 legacy sidecar 记录
+当时参与修正的人名/别名列表（`glossary.names`），人名表变化或所描述的文件被重写（size/mtime 不再
+一致）都会使 ASR 缓存失效。
+`UNAVAILABLE_NO_DURATION` 与 `EMPTY_UNKNOWN` 是可重试的不可用结果，不作为缓存命中；写作
+brief 会校验 sidecar 并打印当前状态，缺失或与当前文件不一致时显示 `MISSING_OR_STALE`。
+
 ## asr_writing_chunks.json
 
 由 CLI 在生成 `agent_narration_brief.md` 时自动写出。它把长 ASR 按句子边界拆成适合 Agent 消化的语义块；中文按字符计数，非 CJK 文本按词数计数，并尽量保留 scene 对齐。
@@ -97,77 +143,6 @@
 ]
 ```
 
-## narration.json
-
-Agent 撰写的解说词。full 模式下使用原视频时间；**两阶段 cut 编排流程**在第二次暂停前已经剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长），不会再生成或消费 `narration_mapped.json`。只有旧版直接单阶段剪辑路径才会把原视频时间的 narration remap 成 `narration_mapped.json`：
-
-```json
-[
-  {"start": 2.5, "end": 7.0, "narration": "解说文本", "pause_after_ms": 250, "overlaps_speech": true}
-]
-```
-
-## narration_lint.json
-
-续跑验证 `narration.json` 时生成的预检结果。它检查写稿、时间安全和解说覆盖。`metrics` 为 full 模式下的诊断指标（cut 模式为空对象），不是要求命中某个旁白比例的创作配额；低覆盖 warning 应检查是否为有意的原声/沉默选择。
-
-```json
-{
-  "ok": false,
-  "error_count": 1,
-  "warning_count": 1,
-  "metrics": {
-    "segment_count": 12,
-    "narration_coverage": 0.68,
-    "narration_seconds": 61.2,
-    "timeline_seconds": 90.0,
-    "avg_block_chars": 48,
-    "original_block_count": 4
-  },
-  "errors": [
-    {"level": "error", "index": 2, "code": "time_overlap", "message": "Segment overlaps the previous narration segment"}
-  ],
-  "warnings": [
-    {"level": "warning", "index": 0, "code": "over_budget", "budget_chars": 28, "actual_chars": 42}
-  ]
-}
-```
-
-常见 code：`invalid_time`、`empty_narration`、`time_overlap`、`outside_clip_plan`、`over_budget`、`incomplete_sentence`、`slot_too_short`、`under_narrated`、`over_narrated`、`fragmented_beats`、`no_original_blocks`。
-
-## style_card.json（Agent 撰写，可选/按 brief 要求）
-
-`style_card.json` 是表达层契约：由 Agent 根据 `--style`、`--context`、素材证据、ASR 和用户偏好信号综合撰写。`--style` 是 freeform verbatim guidance（原样自由文本指导），不是枚举、preset、switch，也不是一组可穷举风格名；不要把它翻译成固定档位。它是当前版本的活动契约：用户对声音、节奏、字幕阅读或禁忌提出新反馈后，更新原文件并移除过期偏好，不要只改 `narration.json`。
-
-这个文件记录声音、节奏、回收意图和证据支撑的表达判断；字段可以随项目增减，下游只把它当 JSON object 读取，不要求固定键名。它不负责标题、封面、首句承诺或卖点包装。
-
-```json
-{
-  "voice": "冷静但有压迫感，少讲大道理，多用人物动作和台词里的证据推进",
-  "pacing": "前 15 秒紧凑建立冲突，每个 beat 连续说完一个思路；中段留原声喘息，结尾回收开头疑问",
-  "payoff_intent": "让观众先看到误会，再看到人物选择的代价",
-  "subtitle_read_posture": "TTS 保持连续口语，字幕按阅读宽度拆 cue，不用字幕换行切碎朗读",
-  "evidence_intent": ["优先引用画面动作", "关键转折保留原声"]
-}
-```
-
-## packaging_plan.json（Agent 撰写，可选）
-
-`packaging_plan.json` 是内容锁定后的可选包装层契约：标题、封面帧/视觉钩子、首句、观众承诺、卖点和发布包装信息。它帮助 review 判断“包装承诺”和正文前 15 秒是否对齐；不应反过来驱动故事取舍。
-
-它不是文风策略，不覆盖 `style_card.json` 的声音、节奏或表达规则；如果包装需要某个承诺，正文仍要用素材证据兑现。
-
-```json
-{
-  "title": "一句能对外展示的标题",
-  "cover_frame": {"time": 12.4, "reason": "人物第一次正面做出关键选择"},
-  "first_line": "开场第一句解说",
-  "viewer_promise": "观众看完会明白的冲突/反转/信息增量",
-  "selling_points": ["强冲突", "原声高光"],
-  "packaging_notes": "发布侧备注，不写文风规则"
-}
-```
-
 ## deslop_qc_requirements.json（工具/brief 生成的运行契约）
 
 `deslop_qc_requirements.json` 是 tool/brief generated run contract：工具或 brief 生成本次运行的 QC 要求，供 `deslop_qc` 读取，不由 Agent 手写。字段为 `schema_version` 与 `style_card_required`。
@@ -185,91 +160,6 @@ Agent 撰写的解说词。full 模式下使用原视频时间；**两阶段 cut
 }
 ```
 
-## deslop_qc.json（CLI 生成，报告型 QC）
-
-`deslop_qc.json` 由本地 deterministic scanner 生成，Agent 不手写。它只是 report-only QC：不是 AIGC detector，不判断文本是不是 AI 写的，不会自动改写。修改仍由 Agent/人工根据报告回到 `narration.json`、`style_card.json` 或字幕源里处理。
-
-报告分两层：
-
-- `blockers`：客观阻断项，会并入 `narration_lint.json` 的 error，例如 requirements 要求但缺少/损坏 `style_card.json`、破折号、占位符泄漏。
-- `advisories`：建议项，只提示可读性/口语化风险，例如模板化“不是……而是……”转折、套话密度、抽象总结词、解释链、比喻标记、过长段落；它们不自动阻断，也不自动改写。
-
-```json
-{
-  "ok": false,
-  "contract": "Local readability/QC report only: this is not an AIGC detector, does not claim AI-generation accuracy, and never rewrites text. Corrections remain human/agent rewrite work.",
-  "scanner": "deslop_qc.py",
-  "style_card_required": true,
-  "blocker_count": 1,
-  "advisory_count": 1,
-  "blockers": [
-    {"severity": "blocker", "code": "missing_style_card", "source": "style_card", "index": null, "message": "style_card.json is required by this expression/packaging run but is missing"}
-  ],
-  "advisories": [
-    {"severity": "advisory", "code": "cliche_density", "source": "narration", "index": null, "message": "套话/高频抽象词偏密，建议换成具体行动、选择和后果"}
-  ],
-  "metrics": {"segments_scanned": 12, "text_units": 860, "sentence_count": 38}
-}
-```
-
-## clip_plan.json
-
-cut 模式下 Agent 选择要保留的原片片段，数组或 `{ "clips": [...] }` 都可接受。默认片段不能重叠，避免同一原片时间映射到多个输出位置：
-
-```json
-{
-  "target_duration": "10m",
-  "clips": [
-    {"start": 12.0, "end": 38.0, "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"}
-  ]
-}
-```
-
-| 字段 | 类型 | 说明 |
-|------|------|------|
-| `start` | float | 原视频片段开始秒数 |
-| `end` | float | 原视频片段结束秒数 |
-| `reason` | string | 选择该片段的剧情/信息原因 |
-
-## clip_plan_validated.json
-
-CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
-
-```json
-{
-  "clips": [
-    {
-      "clip_id": 0,
-      "source_start": 12.0,
-      "source_end": 38.0,
-      "output_start": 0.0,
-      "output_end": 26.0,
-      "duration": 26.0,
-      "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
-    }
-  ],
-  "total_duration": 26.0,
-  "target_duration": 600.0
-}
-```
-
-## narration_mapped.json
-
-仅旧版直接单阶段剪辑路径会生成。两阶段 cut 编排流程不使用它：Agent 在第二阶段直接按剪后成片 OUTPUT 时间轴写 `narration.json`。启用旧版路径时，`start/end` 已变成短视频输出时间，`source_start/source_end` 保留原视频时间：
-
-```json
-[
-  {
-    "start": 2.0,
-    "end": 7.0,
-    "source_start": 14.0,
-    "source_end": 19.0,
-    "source_clip_id": 0,
-    "narration": "解说文本"
-  }
-]
-```
-
 ## background_research.json
 
 可选的背景调研结果（由 Agent 使用任意可用搜索/浏览方式整理）：
@@ -297,3 +187,7 @@ CLI 校验 `clip_plan.json` 后写出，额外包含输出时间轴：
 ```
 
 > `character_details`、`plot_arcs`、`cultural_notes` 为（可选，新增）字段。仅含 `synopsis`、`characters`、`worldbuilding`、`episode_context` 四个原始字段的旧 JSON 仍然有效。
+
+## 其他产物
+
+`narration.json`、`narration_lint.json`、`style_card.json`、`packaging_plan.json`、`deslop_qc.json`、`clip_plan.json`、`clip_plan_validated.json` 由后续的写稿与剪辑阶段读写，本技能既不生成也不校验它们；其格式以本技能生成的 `agent_narration_brief.md` 和编排器的中间产物契约为准。

package/lib/video-recap/skills/video-understanding/references/research-guide.md

@@ -1,6 +1,6 @@
 # 背景调研指南（可选）
 
-Agent 在跑视频理解（video-understanding）**之前**先做背景调研，确认作品名、角色关系、剧情背景或科普概念，写入 `work_dir/background_research.json`。理解阶段会把它并入 VLM 的画面分析上下文，让场景描述能直接叫出人物名字、带着剧情读画面，而不是把人都标成「黑衣男子」。**调研不是必需步骤**；没有浏览器工具、网络不可用或用户未提供明确片名时，直接跳过，不阻塞视频生成。
+Agent 在开始视频理解**之前**先做背景调研，确认作品名、角色关系、剧情背景或科普概念，写入 `work_dir/background_research.json`。理解阶段会把它并入 VLM 的画面分析上下文，让场景描述能直接叫出人物名字、带着剧情读画面，而不是把人都标成「黑衣男子」。**调研不是必需步骤**；没有浏览器工具、网络不可用或用户未提供明确片名时，直接跳过，不阻塞视频生成。
 
 ## 工具选择
 
@@ -17,7 +17,7 @@ Agent 在跑视频理解（video-understanding）**之前**先做背景调研，
 2. 搜索 1-3 个高价值问题，不要过度调研。
 3. 只记录对解说有帮助的事实：人物关系、剧情前提、世界观、当前集上下文、术语解释。
 4. 写入 `work_dir/background_research.json`。
-5. 如果查不到可靠信息，跳过并继续写 `narration.json`。
+5. 如果查不到可靠信息，跳过调研并继续视频理解；不要在理解索引生成前提前写 `narration.json`。
 
 ## 按视频类型搜索策略
 
@@ -66,8 +66,8 @@ Agent 在跑视频理解（video-understanding）**之前**先做背景调研，
 
 | 场景 | 处理 |
 |------|------|
-| 没有浏览器 / 搜索工具 | 跳过调研，直接写解说词 |
-| 搜索无结果 | 换一组关键词重试一次，仍无结果则跳过 |
+| 没有浏览器 / 搜索工具 | 跳过调研，继续视频理解 |
+| 搜索无结果 | 换一组关键词重试一次，仍无结果则继续视频理解 |
 | 结果互相矛盾 | 只使用用户提供的上下文或画面/ASR 可验证的信息 |
 | 信息可能剧透后续 | 只用于理解人物关系，不在解说里剧透用户没要求的后续剧情 |