@oh-story/dsh 0.1.11 → 0.1.13

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

@@ -154,6 +154,44 @@ def _remap_frame_facts_for_brief(frame_facts, overlap):
     return out
 
 
+# A time the VLM quoted in its prose: "12.0s" (the frame-tag form), "12秒", "01:05",
+# "1:02:03". Only a value inside the scene's own source range counts as a source timestamp;
+# anything else (a duration, an on-screen clock) is left as written.
+_PROSE_TIME_RE = re.compile(
+    r"(?<![\d.:])(?:(?:(\d+):)?(\d{1,2}):(\d{2}(?:\.\d+)?)(?![\d:])"
+    r"|(\d+(?:\.\d+)?)\s*(?:s|秒)(?![A-Za-z]))"
+)
+_PROSE_TIME_SLACK = 0.25
+_CUT_AWAY_TIME = "[cut-away moment]"
+
+
+def _remap_prose_times_for_brief(text, scene, overlap):
+    """Rewrite source timestamps quoted in VLM prose onto the OUTPUT clock.
+
+    A time inside this part's kept source range becomes its output time ("3.2s"); a time
+    elsewhere in the scene was cut away and is replaced by a marker, so an OUTPUT section
+    never quotes a source-clock time."""
+
+    def replace(match):
+        hours, minutes, secs, bare = match.groups()
+        if bare is not None:
+            when = float(bare)
+        else:
+            when = int(hours or 0) * 3600 + int(minutes) * 60 + float(secs)
+        if not (scene["start"] - _PROSE_TIME_SLACK <= when <= scene["end"] + _PROSE_TIME_SLACK):
+            return match.group(0)
+        if not (
+            overlap["source_start"] - _PROSE_TIME_SLACK
+            <= when
+            <= overlap["source_end"] + _PROSE_TIME_SLACK
+        ):
+            return _CUT_AWAY_TIME
+        out = overlap["output_start"] + (when - overlap["source_start"])
+        return f"{min(max(out, overlap['output_start']), overlap['output_end']):.1f}s"
+
+    return _PROSE_TIME_RE.sub(replace, text) if isinstance(text, str) else text
+
+
 def _remap_scenes_to_output_for_brief(scenes, spans):
     out = []
     for scene in scenes:
@@ -165,6 +203,9 @@ def _remap_scenes_to_output_for_brief(scenes, spans):
             item["frame_facts"] = _remap_frame_facts_for_brief(
                 scene.get("frame_facts", {}), overlap
             )
+            for field in ("description", "depth_analysis"):
+                if field in item:
+                    item[field] = _remap_prose_times_for_brief(item[field], scene, overlap)
             if len(overlaps) > 1:
                 item["scene_id"] = f"{scene['scene_id']}.{part_idx}"
             out.append(item)
@@ -186,6 +227,38 @@ def _remap_segments_to_output_for_brief(segments, spans):
     return out
 
 
+_COVERAGE_SLACK = 0.05
+# No "." inside: the ASR chunker splits sentences on it.
+_PARTIAL_WINDOW_TEXT = "[partial ASR window: only part of it is in the cut, text withheld]"
+
+
+def _remap_asr_to_output_for_brief(segments, spans):
+    """ASR rows on the OUTPUT clock for the brief's writing evidence.
+
+    A coarse window the cut keeps only part of cannot say which of its words survived, so
+    each kept piece shows a partial-window marker instead of the window's text: the
+    brief never quotes dialogue that may not be in the cut. A window the kept clips cover
+    completely (even across a seam) keeps its text. `speech_spans` in
+    speech_boundary_anchors_output.json are remapped separately and keep the raw text."""
+    out = []
+    for seg in segments:
+        overlaps = _source_output_overlaps_for_brief(seg["start"], seg["end"], spans)
+        kept = sum(o["source_end"] - o["source_start"] for o in overlaps)
+        window = seg["end"] - seg["start"]
+        partial = bool(str(seg.get("text") or "").strip()) and kept < window - _COVERAGE_SLACK
+        for overlap in overlaps:
+            item = dict(seg)
+            item["start"] = round(overlap["output_start"], 3)
+            item["end"] = round(overlap["output_end"], 3)
+            if "duration" in item:
+                item["duration"] = round(item["end"] - item["start"], 3)
+            if partial:
+                item["text"] = _PARTIAL_WINDOW_TEXT
+            out.append(item)
+    out.sort(key=lambda x: (x["start"], x["end"]))
+    return out
+
+
 def _remap_brief_evidence_to_output_timeline(
     work_dir, scenes_analysis, asr_result, silence_periods, *, required=False
 ):
@@ -194,7 +267,7 @@ def _remap_brief_evidence_to_output_timeline(
         return scenes_analysis, asr_result, silence_periods
     return (
         _remap_scenes_to_output_for_brief(scenes_analysis, spans),
-        _remap_segments_to_output_for_brief(asr_result, spans),
+        _remap_asr_to_output_for_brief(asr_result, spans),
         _remap_segments_to_output_for_brief(silence_periods, spans),
     )
 
@@ -204,6 +277,13 @@ def _read_json(path, default):
     return json.loads(path.read_text(encoding="utf-8")) if path.exists() else default
 
 
+def _source_to_span_output(source_time, span):
+    """`source_time` on one clip span's OUTPUT clock, clamped to that span: the next span on
+    the output timeline plays a different source range."""
+    when = min(max(source_time, span["source_start"]), span["source_end"])
+    return round(min(span["output_start"] + when - span["source_start"], span["output_end"]), 3)
+
+
 def _sentence_entry_anchors_for_brief(work_dir, edit_mode):
     """Load sentence anchors and remap them to cut OUTPUT time when needed."""
     work_dir = Path(work_dir)
@@ -217,26 +297,41 @@ def _sentence_entry_anchors_for_brief(work_dir, edit_mode):
         return anchors
 
     spans = _load_cut_output_spans_for_brief(work_dir, required=True)
+    output_duration = max(span["output_end"] for span in spans)
     remapped = []
     for anchor in anchors:
         source_time = anchor["time"]
-        for span in spans:
-            if span["source_start"] - 0.05 <= source_time <= span["source_end"] + 0.05:
-                item = dict(anchor)
-                item["source_time"] = round(source_time, 3)
-                item["time"] = round(
-                    span["output_start"] + source_time - span["source_start"], 3
-                )
-                # Preserve the measured safe pause in OUTPUT time too, so cut-mode lint
-                # compares one clock.
-                source_pause_start = max(
-                    span["source_start"], min(anchor.get("pause_start", source_time - 0.12), source_time)
-                )
-                item["source_pause_start"] = round(source_pause_start, 3)
-                item["pause_start"] = round(
-                    span["output_start"] + source_pause_start - span["source_start"], 3
-                )
-                remapped.append(item)
+        # A pause end a few ms past a frame-snapped clip edge belongs to that clip, at the
+        # edge; only when no clip plays the instant itself.
+        owners = [span for span in spans
+                  if span["source_start"] <= source_time <= span["source_end"]] or [
+            span for span in spans
+            if span["source_start"] - 0.05 <= source_time <= span["source_end"] + 0.05]
+        for span in owners:
+            # The 0.05 s match slack can carry an anchor past the output's ends (a clip
+            # end frame-snapped 181.42 -> 181.40): narration cannot start there.
+            unclamped = round(span["output_start"] + source_time - span["source_start"], 3)
+            if not 0 <= unclamped <= output_duration:
+                continue
+            item = dict(anchor)
+            item["source_time"] = round(source_time, 3)
+            item["time"] = _source_to_span_output(source_time, span)
+            # Preserve the measured safe pause in OUTPUT time too, so cut-mode lint
+            # compares one clock.
+            source_pause_start = max(
+                span["source_start"], min(anchor.get("pause_start", source_time - 0.12), source_time)
+            )
+            item["source_pause_start"] = round(min(source_pause_start, span["source_end"]), 3)
+            item["pause_start"] = _source_to_span_output(source_pause_start, span)
+            # `time` IS the pause end; keep the source value apart so the artifact
+            # never mixes clocks.
+            item["source_pause_end"] = round(anchor.get("pause_end", source_time), 3)
+            item["pause_end"] = item["time"]
+            if "expected_time" in anchor:
+                expected = float(anchor["expected_time"])
+                item["source_expected_time"] = round(expected, 3)
+                item["expected_time"] = _source_to_span_output(expected, span)
+            remapped.append(item)
 
     speech_rows = [
         row for row in _read_json(work_dir / "asr_result.json", []) if row["text"]
@@ -262,19 +357,30 @@ def _sentence_entry_anchors_for_brief(work_dir, edit_mode):
     return out_payload["sentence_anchors"]
 
 
+def _anchor_boundary_use(anchor):
+    # Schema-1 anchors (no `boundary_use`) came from the old coarse estimator: high/medium
+    # labels there are usable but unverified.
+    return anchor.get("boundary_use") or (
+        "unverified" if anchor["confidence"] in {"high", "medium"} else "none"
+    )
+
+
 def _format_sentence_entry_anchors_for_brief(work_dir, edit_mode):
     anchors = [
         anchor
         for anchor in _sentence_entry_anchors_for_brief(work_dir, edit_mode)
-        if anchor["confidence"] in {"high", "medium"}
+        if _anchor_boundary_use(anchor) != "none"
     ]
     if not anchors:
         return []
     lines = [
         "## 原声句末安全切入点",
         "",
-        "这些时间是 ASR 句末标点与短声学停顿对齐后的旁白安全入口。旁白在原声已开始后切入时，"
+        "这些时间是 ASR 句末标点与短声学停顿对齐后的旁白入口。旁白在原声已开始后切入时，"
         "必须从其中一个点开始；否则会在 TTS 前被 `interrupts_source_sentence` 硬阻断。",
+        "- 标 `unverified` 的点是由粗粒度 ASR 窗口里的标点位置估计、再吸附到短停顿得到的："
+        "落在停顿里，不会切断单词，但不保证原声句子已经说完（误差上限见 `±`）。请自己听一下再定；"
+        "门禁本身照常生效。",
         "- 调整方式：优先把 `start` 移到建议锚点；放不下时缩短文本、移动整块或删除该旁白，不能让脚本静默挪音频。",
         '- 原声句子完整性是硬约束：切入块写 `"source_entry_policy": "sentence_boundary"`；'
         "不存在 `intentional_interrupt` 绕过方式。没有后续可靠句末锚点时，移动、缩短或删除旁白块。",
@@ -284,8 +390,17 @@ def _format_sentence_entry_anchors_for_brief(work_dir, edit_mode):
             f" (SOURCE {anchor['source_time']:.2f}s)" if "source_time" in anchor else ""
         )
         text_tail = str(anchor.get("text_tail", "")).strip()
+        if _anchor_boundary_use(anchor) == "verified":
+            label = anchor["confidence"]
+        else:
+            # Schema-1 anchors carry no error bound to print.
+            label = (
+                f"unverified ±{float(anchor['timing_bound_seconds']):.1f}s"
+                if "timing_bound_seconds" in anchor
+                else "unverified"
+            )
         lines.append(
-            f"- {anchor['time']:.2f}s [{anchor['confidence']}]{source_suffix} {text_tail}".rstrip()
+            f"- {anchor['time']:.2f}s [{label}]{source_suffix} {text_tail}".rstrip()
         )
     lines.append("")
     return lines
@@ -308,19 +423,3 @@ def _format_output_clip_list(work_dir):
         )
     out.append("")
     return out if len(out) > 2 else []
-
-
-def _write_deslop_qc_requirements(work_dir):
-    """Write the stable deslop QC contract consumed by deslop_qc.py.
-
-    style_card_required defaults to False (advisory): a missing style_card.json is a
-    warning, not a render-blocking error. A future opt-in run can set it True to make
-    style_card.json a hard requirement — deslop_qc.py reads that field.
-    """
-    payload = {
-        "schema_version": 1,
-        "style_card_required": False,
-    }
-    path = Path(work_dir) / "deslop_qc_requirements.json"
-    path.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
-    return path

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

@@ -10,7 +10,8 @@ Optional, synchronous, in-pipeline. Two independent LLM passes over the video's
     cleanup pass can never shift the timing-bearing spans downstream chunking depends on.
 
 Both passes are idempotent (a fresh artifact is reused); a failure raises and the runner
-records it in consolidation.status.json. Mirrors review.py's pure-seam + thin-driver shape so it is
+records it in consolidation.status.json. A cut-off or non-JSON model reply is a failure too
+(ConsolidateIncomplete), never an empty artifact reported as done. Mirrors review.py's pure-seam + thin-driver shape so it is
 unit-testable with a mocked api_call. NON-required: the pipeline runs unchanged without it.
 """
 
@@ -20,6 +21,7 @@ import re
 from pathlib import Path
 
 from lib import CONFIG, log, api_call, file_identity, load_background_research
+from index_normalize import coerce_character_aliases, normalize_index, scenes_end
 from understanding_cache import _fresh
 
 # Shared tolerance for the per-segment span check. The brief-side gate inlines the SAME
@@ -28,6 +30,29 @@ from understanding_cache import _fresh
 _ASR_SPAN_TOL = 0.05
 ASR_CLEAN_POSTPROCESS_VERSION = 2
 
+# Output budgets. A 5-min recap's index ran past 3000 tokens and came back cut off
+# (finish_reason=length); a cut-off reply parses to nothing, so it must never be written as
+# a finished artifact. One retry doubles the budget; a second cut-off raises.
+_CLEAN_MAX_TOKENS = 8000
+_INDEX_MAX_TOKENS = 8000
+_RETRY_BUDGET_FACTOR = 2
+
+
+class ConsolidateIncomplete(RuntimeError):
+    """The model reply was cut off or is not JSON; nothing was written for that pass."""
+
+
+class ConsolidateNoKey(RuntimeError):
+    """A pass needs the model but no API key is set; nothing was sent or written."""
+
+
+def _require_api_key(label):
+    """Offline runs reuse fresh artifacts; a pass that would call the model skips instead of
+    sending an unauthenticated request that can only 401."""
+    if not CONFIG["api_key"]:
+        log(f"consolidate({label}): 未设置 {CONFIG['api_env_var']}，跳过（不发送请求）")
+        raise ConsolidateNoKey(label)
+
 CLEAN_PROMPT = """你在清洗中文视频的 ASR 逐段转写。对【每一段】做：补标点、修明显同音/错别字、（能判断时）在句首轻标说话人，让长段连读文本变成清晰可读的句子。
 铁律：
 - 不要合并或拆分段落，输出段数必须与输入完全一致，顺序一致。
@@ -44,6 +69,7 @@ INDEX_PROMPT = """你在根据逐场景画面分析、ASR对白、background_res
 - visual/asr 是当前视频事实证据；每个人物、关系、剧情节点、物件尽量给 evidence_ids。
 - background_research 只能用于人名/别名/术语/身份消歧，默认 support=context_only；不能把后续剧情或未出现关系升级为当前画面事实。
 - ASR 中出现但画面描述未命名的人名，应进入 characters[*].asr_mentions。
+- 输出要紧凑、必须是完整 JSON：只收对解说有用的角色/关系/节点；description/relation/text 每条不超过 40 字；visual_descriptions 最多 3 条；每项 evidence_ids 最多 6 个；plot_points 最多 20 条。
 只返回 JSON：
 {"characters":[{"name":"角色名或外观指代","description":"身份/特征","aliases":[],"visual_descriptions":[],"asr_mentions":[],"research_role":"","evidence_ids":[],"confidence":"high|medium|low"}],
  "relationships":[{"a":"角色","b":"角色","relation":"关系","evidence_ids":[],"support":"direct|indirect|context_only"}],
@@ -339,6 +365,7 @@ def parse_index_response(text):
     ):
         val = data.get(key)
         out[key] = val if isinstance(val, list) else []
+    out["characters"] = coerce_character_aliases(out["characters"])
     for item in out["research_glossary"]:
         if isinstance(item, dict):
             item["support"] = "context_only"
@@ -479,15 +506,10 @@ def consolidate_transcript(work_dir):
         ):
             log("consolidate(asr): asr_clean.json 已最新，跳过")
             return existing
-    resp = api_call(
-        {
-            "model": CONFIG["vlm_model"],
-            "messages": build_clean_messages(asr_result),
-            "max_tokens": 4000,
-            "temperature": 0.2,
-        }
+    _require_api_key("asr")
+    content = _complete_json_reply(
+        "asr", build_clean_messages(asr_result), _CLEAN_MAX_TOKENS
     )
-    content = _response_text(resp)
     segments = parse_clean_response(content, asr_result)
     payload = {
         "source": _input_identity(work_dir, "asr_result.json"),
@@ -513,62 +535,124 @@ def consolidate_index(work_dir):
     if _fresh(out_path, work_dir / "vlm_analysis.json") and _index_cache_matches(
         work_dir, vlm_analysis
     ):
+        cached = _load(work_dir, "understanding_index.json")
+        repaired = _normalized_index(cached, vlm_analysis) if isinstance(cached, dict) else cached
+        if repaired != cached:
+            # An index written before the deterministic repairs existed: fix it in place
+            # instead of paying for a new model call.
+            _store_index(work_dir, repaired, vlm_analysis)
         log("consolidate(index): understanding_index.json 已最新，跳过")
-        return _load(work_dir, "understanding_index.json")
+        return repaired
+    _require_api_key("index")
     asr_result = _load(work_dir, "asr_result.json") or []
     asr_clean = _load(work_dir, "asr_clean.json") or {}
     background_research = load_background_research(work_dir)
-    resp = api_call(
-        {
-            "model": CONFIG["vlm_model"],
-            "messages": build_index_messages(
-                vlm_analysis,
-                asr_result=asr_result,
-                asr_clean=asr_clean,
-                background_research=background_research,
-            ),
-            "max_tokens": 3000,
-            "temperature": 0.2,
-        }
+    content = _complete_json_reply(
+        "index",
+        build_index_messages(
+            vlm_analysis,
+            asr_result=asr_result,
+            asr_clean=asr_clean,
+            background_research=background_research,
+        ),
+        _INDEX_MAX_TOKENS,
     )
-    index = parse_index_response(_response_text(resp))
+    index = parse_index_response(content)
     index = _apply_deterministic_asr_research_fallback(
         index,
         asr_result=asr_result,
         asr_clean=asr_clean,
         background_research=background_research,
     )
-    out_path.write_text(
+    index = _normalized_index(index, vlm_analysis)
+    _store_index(work_dir, index, vlm_analysis)
+    log(
+        f"consolidate(index): 写出 understanding_index.json（角色 {len(index['characters'])}）"
+    )
+    return index
+
+
+def _normalized_index(index, vlm_analysis):
+    """Merge split characters and canonicalize plot times (index_normalize)."""
+    index, repairs = normalize_index(index, duration=scenes_end(vlm_analysis))
+    if repairs["merged_characters"] or repairs["dropped_plot_times"]:
+        log(
+            f"consolidate(index): 合并重复角色 {repairs['merged_characters']} 个，"
+            f"丢弃无效剧情时间 {repairs['dropped_plot_times']} 个"
+        )
+    return index
+
+
+def _store_index(work_dir, index, vlm_analysis):
+    (work_dir / "understanding_index.json").write_text(
         json.dumps(index, ensure_ascii=False, indent=2), encoding="utf-8"
     )
     _write_index_meta(work_dir, vlm_analysis)
     (work_dir / "understanding_index.md").write_text(
         format_index_md(index), encoding="utf-8"
     )
-    log(
-        f"consolidate(index): 写出 understanding_index.json（角色 {len(index['characters'])}）"
-    )
-    return index
 
 
 def consolidate(work_dir, do_asr=False, do_index=True):
     """Default = index-only (Pass B, zero timing risk). Pass A (asr) is opt-in.
 
-    Failures propagate; understanding_runner catches them and writes the "failed" status."""
-    result = {}
-    if do_asr:
-        result["asr_clean"] = consolidate_transcript(work_dir)
+    Failures propagate; understanding_runner catches them and writes the "failed" status.
+    A pass that needs the model while no key is set is listed under "skipped_no_key"."""
+    result = {"skipped_no_key": []}
+    passes = [("asr", "asr_clean", consolidate_transcript)] if do_asr else []
     if do_index:
-        result["index"] = consolidate_index(work_dir)
+        passes.append(("index", "index", consolidate_index))
+    for label, key, run in passes:
+        try:
+            result[key] = run(work_dir)
+        except ConsolidateNoKey:
+            result[key] = None
+            result["skipped_no_key"].append(label)
     return result
 
 
 def _response_text(resp):
+    """(content, finish_reason) of the first choice; ("", None) on a malformed response."""
     try:
-        return resp["choices"][0]["message"]["content"]
-    except (KeyError, IndexError, TypeError):
+        choice = resp["choices"][0]
+        return choice["message"]["content"] or "", choice.get("finish_reason")
+    except (KeyError, IndexError, TypeError, AttributeError):
         log("consolidate: API 返回结构异常")
-        return ""
+        return "", None
+
+
+def _complete_json_reply(label, messages, max_tokens):
+    """Call the model and return a reply that is complete JSON, or raise ConsolidateIncomplete.
+
+    A cut-off reply (finish_reason=length) is retried once with a larger budget; an
+    unparseable reply is not retried (a bigger budget would not fix it)."""
+    budget = max_tokens
+    for attempt in range(2):
+        content, finish = _response_text(
+            api_call(
+                {
+                    "model": CONFIG["vlm_model"],
+                    "messages": messages,
+                    "max_tokens": budget,
+                    "temperature": 0.2,
+                }
+            )
+        )
+        if finish == "length":
+            if attempt == 0:
+                log(f"consolidate({label}): 输出被截断（max_tokens={budget}），加大预算重试一次")
+                budget *= _RETRY_BUDGET_FACTOR
+                continue
+            raise ConsolidateIncomplete(
+                f"consolidate({label}): 输出被截断（finish_reason=length，"
+                f"max_tokens={budget}），未写出结果"
+            )
+        if not isinstance(_extract_json(content), dict):
+            raise ConsolidateIncomplete(
+                f"consolidate({label}): 模型返回的不是可解析的 JSON"
+                f"（finish_reason={finish}），未写出结果"
+            )
+        return content
 
 
 def main():
@@ -583,7 +667,7 @@ def main():
     print(
         json.dumps(
             {
-                "status": "consolidated",
+                "status": "skipped_no_key" if res["skipped_no_key"] else "consolidated",
                 "index": bool(res.get("index")),
                 "asr_clean": bool(res.get("asr_clean")),
             },