@oh-story/dsh 0.1.3 → 0.1.5

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

@@ -0,0 +1,534 @@
+# 数据格式（中间 JSON）
+
+所有中间文件均在 pipeline 工作目录（work_dir/）下。
+
+## vlm_analysis.json
+
+每场景的 VLM 分析结果，数组格式：
+
+```json
+[
+  {
+    "scene_id": 1,
+    "start": 5.0,
+    "end": 15.0,
+    "description": "男子闯入房间",
+    "depth_analysis": "角色情绪分析...",
+    "frame_facts": {
+      "5.0": ["男子闯入房间, 头发蓬乱表情紧张"],
+      "10.0": ["男子俯身盯着床上男孩, 男孩睁眼惊醒"]
+    }
+  }
+]
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `scene_id` | int | 场景编号 |
+| `start` | float | 开始时间（秒） |
+| `end` | float | 结束时间（秒） |
+| `description` | string | 画面简述（≤80字） |
+| `depth_analysis` | string | 深层分析（情绪/关系/潜台词） |
+| `frame_facts` | object | 帧级事实，key 为时间戳字符串 |
+
+## asr_result.json
+
+语音转文字结果：
+
+```json
+[
+  {"start": 0.0, "end": 3.5, "text": "What are you doing here?"}
+]
+```
+
+## asr_writing_chunks.json
+
+由 CLI 在生成 `agent_narration_brief.md` 时自动写出。它把长 ASR 按句子边界拆成适合 Agent 消化的语义块；中文按字符计数，非 CJK 文本按词数计数，并尽量保留 scene 对齐。
+
+```json
+[
+  {
+    "chunk_id": 0,
+    "start": 0.0,
+    "end": 28.5,
+    "scene_ids": [0, 1],
+    "char_count": 642,
+    "text": "第一段对白……",
+    "segments": [
+      {"start": 0.0, "end": 3.5, "text": "第一句。", "char_count": 4}
+    ]
+  }
+]
+```
+
+## silence_periods.json
+
+静音窗口列表（适合放解说）：
+
+```json
+[
+  {"start": 2.0, "end": 8.5, "duration": 6.5, "has_speech": false}
+]
+```
+
+`has_speech` 标记该窗口是否与检测到的 ASR 语音重叠；下游（pipeline / narration）只把 `has_speech=false` 的窗口当作可放解说的安静窗口。
+
+## speech_boundary_anchors.json
+
+原声句末安全切入点。脚本把 ASR 终止标点的估算时间吸附到短声学停顿；它与
+`silence_periods.json` 分开，因为约 0.1–0.5 秒的停顿适合作为旁白入口，却不足以容纳整段旁白。
+
+```json
+{
+  "schema_version": 1,
+  "sentence_anchors": [
+    {
+      "time": 5.809,
+      "confidence": "high",
+      "text_tail": "带你重走詹姆斯的二十一年。",
+      "pause_start": 5.222,
+      "pause_end": 5.809
+    }
+  ]
+}
+```
+
+当 `overlaps_speech=true` 且旁白不是从 0 秒冷开场时，`narration` lint 要求 `start`
+贴近 `high`/`medium` 锚点。否则在 TTS 前用 `interrupts_source_sentence` 阻断，并返回
+`suggested_start` 与 `source_text_tail` 给 Agent 调整。常规块使用
+`source_entry_policy: "sentence_boundary"`；原声语句完整性没有抢断 override。最后一个可靠
+锚点之后又进入已声明的原声讲话区时，`suggested_start` 可为 `null`，Agent 必须移动、缩短或删除该旁白块。
+
+剪辑模式第二阶段会另外生成 `speech_boundary_anchors_output.json`，把锚点、ASR 语音区间和
+安静窗口映射到剪后 OUTPUT 时间轴，避免拿原片时间检查剪后旁白：
+
+```json
+{
+  "schema_version": 2,
+  "timeline": "cut_output",
+  "clip_plan_fingerprint": "md5-of-canonical-clip-plan",
+  "sentence_anchors": [{"time": 4.0, "pause_start": 3.8, "confidence": "high"}],
+  "speech_spans": [{"start": 0.0, "end": 3.8}],
+  "quiet_windows": [{"start": 3.8, "end": 4.1}]
+}
+```
+
+`clip_plan_fingerprint` 必须与当前 `clip_plan_validated.json` 一致。缺失、过期或畸形的
+output 证据一律 fail closed，不能回退到原片时钟或信任 Agent 写入的
+`overlaps_speech=false`。多来源剪辑的每条映射记录还保留 `source_id` 和原片起止时间。
+
+## timeline_fusion.json
+
+由 CLI 在生成 brief 时自动写出。它把 VLM 场景、ASR 对白和静音窗口按时间轴 overlap 合并，减少写稿时手工推断“这一幕有没有对白/能不能插解说”的成本。
+
+```json
+[
+  {
+    "scene_id": 0,
+    "time_range": [0.0, 10.0],
+    "visual_description": "两人在门口对峙",
+    "depth_analysis": "关系紧张",
+    "frame_facts": {"1.0": ["女子回头"]},
+    "dialogue_segments": [
+      {"start": 2.0, "end": 4.0, "overlap_seconds": 2.0, "text": "你到底是谁"}
+    ],
+    "dialogue_overlap_seconds": 2.0,
+    "narration_slots": [
+      {"start": 5.0, "end": 7.0, "duration": 2.0, "char_budget": 5}
+    ],
+    "recommended_mode": "ducked-bed"
+  }
+]
+```
+
+## narration.json
+
+Agent 撰写的解说词。full 模式下使用原视频时间；**orchestrated cut 模式（`video-recap --edit-mode cut`）下，第二次暂停时已经先剪出 `edited_source.mp4`，因此 `narration.json` 必须直接使用剪后成片的 OUTPUT 时间轴（0..成片总时长），不会再生成或消费 `narration_mapped.json`。只有 legacy direct `video-cut` 单 pass 路径才会把原视频时间的 narration remap 成 `narration_mapped.json`：
+
+```json
+[
+  {"start": 2.5, "end": 7.0, "narration": "解说文本", "pause_after_ms": 250, "overlaps_speech": true}
+]
+```
+
+## narration_lint.json
+
+`--step script` 或续跑验证 `narration.json` 时生成的预检结果。它检查写稿、时间安全和解说覆盖。`metrics` 为 full 模式下的诊断指标（cut 模式为空对象），不是要求命中某个旁白比例的创作配额；低覆盖 warning 应回到 `visual_audio_board.json` 检查是否为有意的原声/沉默选择。
+
+```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`。
+
+## recap_story_plan.json / visual_audio_board.json（Agent 创作工作产物）
+
+这两个 JSON 是 skill 层的创作决策记录：前者保存导演意图、备选剪辑假设、POV/主线和 change-based beats；后者保存每拍的画面/表演选择、入点/出点、原声锚点、`audio_owner` 与 `narration_job`。完整字段与工作流见本技能的 `creative-editing-playbook.md`。
+
+CLI 不以它们作为渲染硬门禁，也不新增解析服务；建议型解说评审在文件存在时读取它们，Agent 则用它们保证 cut、旁白和声音选择没有偏离同一个创作意图。
+
+## 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`。
+
+`style_card_required` 默认 `false`（advisory）：缺少 `style_card.json` 只是 warning，不阻断出片。将来的 opt-in 运行可把它设为 `true`，让 `style_card.json` 成为硬性要求——`deslop_qc` 只读这个字段判断缺少 `style_card.json` 是否是 blocker，不扫描 `agent_narration_brief.md` 的 prompt wording 来推断。如果 requirements 文件缺失或损坏，按 legacy/migration advisory 处理，不作为 hard failure。
+
+该契约不改变 `--style`：`--style` 仍是 freeform verbatim guidance，不增加固定风格档位。它也不改变 `deslop_qc` 边界：仍然是 report-only，不是 AIGC detector，不自动改写。
+
+最小示例：
+
+```json
+{
+  "schema_version": 1,
+  "style_card_required": false
+}
+```
+
+## 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}
+}
+```
+
+## multi_source_manifest.json（多视频 cut）
+
+多视频剪辑模式下，项目级 `work_dir/multi_source_manifest.json` 是编排、剪辑与合成阶段共用的来源契约。`source_id` 默认由源文件 SHA-256 派生为 `src_<fingerprint[:12]>`；同一项目里重复 fingerprint 的不同路径会追加短 path hash 后缀。
+
+```json
+{
+  "schema_version": 1,
+  "sources": [
+    {
+      "source_id": "src_0123456789ab",
+      "source_path": "/abs/episode1.mp4",
+      "source_name": "episode1.mp4",
+      "source_video_fingerprint": "0123456789abcdef...",
+      "source_work_dir": "sources/src_0123456789ab",
+      "material_id": "episode1-0123456789ab"
+    }
+  ]
+}
+```
+
+## 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 | 选择该片段的剧情/信息原因 |
+
+多视频 cut 的 `clip_plan.json` 必须给每个片段加 `source_id`；重叠检测按 `source_id` 分开计算，不同源视频的相同时间范围不互相冲突：
+
+```json
+{
+  "target_duration": "10m",
+  "clips": [
+    {"source_id": "src_0123456789ab", "start": 12.0, "end": 38.0, "reason": "b01 | setup | knowledge: unknown→clue | POV=主角 | 保留迟疑反应 | 入点=线索出现 | 出点=疑问成立"},
+    {"source_id": "src_fedcba987654", "start": 4.0, "end": 22.0, "reason": "b02 | payoff | power: suspect→hero | POV=主角 | 保留最终选择 | 入点=证据落下 | 出点=代价显现"}
+  ]
+}
+```
+
+## 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
+}
+```
+
+`qc.boundary_status.sentence_checks` 逐项记录每个片段 start/end 是 `safe`、`unchecked`
+还是 `blocking`。理解阶段已有 ASR 讲话时间时，任何未落到源头/源尾、可靠句末/静音窗，且
+不是同源无损连续连接的边界都会写入 `qc.blocking[].code=unsafe_clip_sentence_boundary`。
+切镜吸附先执行，句末吸附最后执行，保证视觉边界不会覆盖声音安全边界。
+
+多视频 validated clip 会额外保留来源字段，供 pass2 brief、timeline 和剪映导出追溯原素材：
+
+```json
+{
+  "clips": [
+    {
+      "clip_id": 0,
+      "source_id": "src_0123456789ab",
+      "source_path": "/abs/episode1.mp4",
+      "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=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
+    }
+  ]
+}
+```
+
+## material library（可选，grep 复用）
+
+`--material-library-dir <dir> --save-materials` 会把每个源视频的已分析小文件复制到 `<dir>/materials/<material_id>/`，不复制原始媒体。`--use-materials` 会在 fingerprint 和 settings fingerprint 匹配时把这些 JSON/MD 产物恢复到当前 per-source `work_dir`。
+
+```text
+.video-materials/
+  materials_index.jsonl          # 追加式 grep journal；旧行可保留为历史
+  materials/<material_id>/
+    material.json                # 当前权威 metadata
+    material.md                  # grep 友好摘要
+    artifacts/scenes.json
+    artifacts/asr_result.json
+    artifacts/asr_clean.json       # 启用 --consolidate-asr 时保留，恢复后 brief/review 优先使用
+    artifacts/vlm_analysis.json
+    artifacts/understanding_index.json
+```
+
+`materials_index.jsonl` 每次保存追加一行，字段包括 `schema_version`, `event`, `material_id`, `source_name`, `source_path`, `source_video_fingerprint`, `settings_fingerprint`, `summary`, `tags`, `material_dir`, `updated_at`。当前权威状态始终以 `materials/<material_id>/material.json` 为准。MVP 只承诺 `grep -R "关键词" <library>` 这类文件检索；没有 DB、embedding 或语义搜索。
+
+保存时会对凭证形态（`tp-`/`sk-`/`gh*_`/`AKIA`/JWT 与 `KEY=VALUE` 赋值）和凭证命名的 JSON key 做脱敏，但这只是**尽力而为**的兜底，不是保证：陌生格式的密钥仍可能漏过。请从源头避免把密钥写进分析产物——key 从环境变量/`.env` 读取，不需要落进 scenes/ASR/VLM/summary 等 JSON。
+
+## narration_mapped.json
+
+仅 legacy direct `video-cut` 单 pass 路径会生成。orchestrated cut 模式不使用它：Agent 在 pass2 直接按剪后成片 OUTPUT 时间轴写 `narration.json`。当 legacy 路径启用时，`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": "解说文本"
+  }
+]
+```
+
+## original_subtitles.json / user_subtitles.{json,srt,ass}（可选，原声留白字幕）
+
+解说块之间的原声留白会把【原声台词】烧成字幕（assemble 阶段用 `「」` 包裹以区分解说）。来源优先级（高→低）：
+
+1. **`work_dir/user_subtitles.json`**（用户自带，最准）— 数组 `[{start,end,text}]` 默认按**成片 OUTPUT** 时间轴直接使用；也可写成 `{"timeline": "source"|"output", "lines": [...]}`，`source` 表示按**原片**时间轴给出，由 assemble 依 `clip_plan_validated.json` 映射到成片。
+2. **`work_dir/user_subtitles.srt` / `.ass`**（用户自带）— 默认按**原片**时间轴解析后映射到成片。
+3. **`work_dir/original_subtitles.json`**（Agent 校对，cut pass2 写）— OUTPUT 时间轴 `[{start,end,text}]`，订正 ASR 错字/人名、只写留白里真正出声的句子。
+4. **ASR 兜底** — 无上述文件时，用 `asr_result.json` 按留白粗略映射（中点估时，可能偏多偏乱）。
+
+来源 1–3 为「精确来源」：每条按句**区间裁剪**落到所覆盖的留白边界（跨边界会拆分），不走 ASR 兜底的中点估时；over-dense 行截断显示而非丢弃。
+
+```json
+[
+  {"start": 2.0, "end": 5.0, "text": "原声台词一句"}
+]
+```
+
+## background_research.json
+
+可选的背景调研结果（由 Agent 使用任意可用搜索/浏览方式整理）：
+
+```json
+{
+  "synopsis": "剧情概要",
+  "characters": {"角色名": "角色简介"},
+  "worldbuilding": "世界观设定",
+  "episode_context": "集数上下文",
+  "character_details": {
+    "角色名": {
+      "aliases": ["别名/昵称"],
+      "role": "主角|配角|反派|次要角色",
+      "relationships": ["与XX是夫妻", "与YY是师徒"]
+    }
+  },
+  "plot_arcs": [
+    {"name": "线索名称", "description": "简要描述", "status": "进行中|已解决|伏笔"}
+  ],
+  "cultural_notes": [
+    {"item": "文化梗/典故/时代背景", "explanation": "解释"}
+  ]
+}
+```
+
+> `character_details`、`plot_arcs`、`cultural_notes` 为（可选，新增）字段。仅含 `synopsis`、`characters`、`worldbuilding`、`episode_context` 四个原始字段的旧 JSON 仍然有效。
+
+## narration_review.json
+
+解说评审阶段输出 LLM-as-judge 结果。旧字段 `verdict/summary/findings` 仍然有效；新增一份 **advisory** 的内容效果 scorecard 与改稿清单。**scorecard 不改变 verdict、也不作硬门禁**——硬门禁仍是 `findings` 里的 error（事实矛盾/残句）经 `--require-narration-review` 严格模式拦截。`verdict` 词表为 `PASS|REVISE|FAIL`，`OK` 作为旧值的兼容别名。
+
+```json
+{
+  "verdict": "PASS|REVISE|FAIL|OK",
+  "summary": "总体判断",
+  "scorecard": {
+    "promise_match": 4, "hook_3s": 4, "first_15s_delivery": 4, "spine_clarity": 4,
+    "stakes_escalation": 4, "information_gain": 4, "spoken_language": 4, "sentence_brevity": 4,
+    "tts_pacing": 4, "grounding": 4, "original_audio_use": 4, "subtitle_readability": 4
+  },
+  "hook_candidates_review": [{"candidate": "首句", "type": "suspense", "score": 4, "keep": true}],
+  "retention_risk_points": [{"time": "00:28", "risk": "信息重复可能掉人", "fix": "删掉复述画面的句子"}],
+  "highest_return_edits": ["最值得先改的一件事"],
+  "information_gain_notes": [{"segment": 0, "label": "motive|...|visual_restatement", "note": "证据/改法"}],
+  "spoken_language_rewrites": [{"segment": 0, "original": "原句", "rewrite": "口语改写", "why": "为什么更适合听"}],
+  "grounding_assertions": [{"segment": 0, "assertion": "人物/关系/因果断言", "source": "visual|asr|research|user_context|unsupported", "risk": "谨慎说明"}],
+  "findings": [{"segment": 0, "severity": "warning", "category": "weak_hook", "issue": "问题", "fix": "改法"}]
+}
+```
+
+> 若 `work_dir` 提供了 `packaging_plan.json` / `recap_story_plan.json` / `visual_audio_board.json`（可选、Agent 撰写），review 会把它们并入评估上下文；缺失时 review 仅基于解说与画面/对白证据评分，行为不受影响。
+
+## tts_meta.json（partial 失败可见性）
+
+`video-voiceover` 正常输出 `{segments, engine, narration}`。当显式允许 partial TTS（`--allow-partial-tts` / `ALLOW_PARTIAL_TTS=1`）让运行在部分段失败后继续时，失败段不会只埋在日志里，而会写入 `partial` 与 `failures[]`：
+
+```json
+{
+  "segments": [{"index": 0, "start": 0.0, "end": 1.0, "narration": "第一段。", "audio_path": "tts_segments/narr_000.wav"}],
+  "engine": "mimo-tts",
+  "narration": "narration.json",
+  "partial": true,
+  "failures": [{"index": 1, "start": 1.0, "end": 2.5, "text": "第二段。", "error": "network timeout"}]
+}
+```
+
+> 正常（无失败）运行也会带 `"partial": false, "failures": []`。partial 成片只适合预览，不建议直接发布。
+
+组装后，`assembly_manifest.json.audio_segments[]` 另外记录 `fit_status`、`truncated`、
+`truncate_reason`、`placed_audio_duration`、`placed_audio_path`、`source_duck_end`、
+`source_restore_at` 与 `source_handoff_status`。组装阶段从不按时间裁旁白尾音：放不下时用
+`no_safe_fit` 阻断。`placed_audio_path` 是实际写入 canonical `narration.wav` 的完整逐段 PCM；
+`timeline.json`/剪映必须引用它而不是更长的加速前文件。素材时长与序列化后的时间线段长不一致时，
+`assembly_qc.json` 用 `timeline_audio_mismatch` 阻断。原声恢复在 `pause_start` 前保持压低，
+只在实测停顿内渐强，并于 `source_restore_at` 完成，避免渐强提前泄露上一句尾音。
+
+## dub_lint.json / dub_review.json
+
+Dub 模式下，`dub_script.json` 在 voiceclone **之前**先经过 deterministic lint，把明显不可发布的脚本挡在昂贵的克隆 TTS 之前。空译文、相邻行重叠、时间越界、`room < 0.4s` 等 **error** 会 `verdict=FAIL` 并阻断 render；`fast_speech`、`trim_risk` 等是 warning，不阻断。
+
+每行 voiceclone 原始 WAV 会按模型、合成提示、中文台词和参考音频 SHA-256 写入相邻的 `*.wav.meta.json`。指纹完全匹配且 WAV 可读取时，dub render 直接复用并在 `dub_manifest.json.lines[].tts_cache` 记录 `hit`；台词、参考音频、模型或提示变化都会自动失效并重新合成。
+
+```json
+{
+  "schema_version": 1,
+  "verdict": "PASS|FAIL",
+  "blocking": false,
+  "errors": [],
+  "issues": [{"severity": "warning", "code": "fast_speech", "line": 2, "message": "translation is dense (8.4 chars/s)", "start": 1.0, "end": 2.0}],
+  "summary": {"lines": 12, "errors": 0, "warnings": 1, "max_chars_per_second": 8.4, "trim_risk_lines": []}
+}
+```
+
+`dub_review.json` 是脚本级 review scaffold（确定性派生自 lint，语义忠实/语气仍需 agent/人工判断）：
+
+```json
+{
+  "schema_version": 1,
+  "verdict": "PASS|REVISE|FAIL",
+  "checks": {"faithful_to_source": "needs_agent_review", "spoken_chinese": "PASS", "speaker_tone": "needs_agent_review", "timing_fit": "PASS", "platform_fit": "needs_agent_review"},
+  "highest_return_edits": [],
+  "coverage": {"transcript_windows": 8, "script_lines": 12}
+}
+```
+
+> CLI：`dub.py --stage lint|review`（无需 video）、`dub.py --print-schema` 打印以上全部 dub artifact 契约；`--stage render` 会在克隆前自动写 `dub_lint.json` / `dub_review.json`，lint 非 PASS 即中止。
+> 最终 `dub_<name>.mp4` 显式输出 48 kHz AAC；不能沿用 `loudnorm` 内部的 96 kHz 分析采样率。
+## shift-left QC artifacts
+
+`preflight_qc.json`、`final_qc.json`、`golden_eval.json`、`mimo_qc.json` 共用最小 QC 契约；stage 仅允许 `pre_cut` / `post_cut` / `pre_tts` / `post_tts` / `pre_assemble` / `post_render` / `golden`，其中 `mimo_qc.json` 是 artifact 而不是 stage。详见 `shift-left-qc-schema.md`。
+
+`recap.py` 可通过 `--mimo-qc pre-assemble|post-render|both`（默认 `off`）在组装前和/或成片后写 `mimo_qc.json`。每个 stage 最多一次 live request；相同素材/模型命中内容缓存，`--mimo-qc-refresh` 可刷新。`post_render` 最多临时抽取 6 张、最长边 768px 的 JPEG；base64 只进入请求，不写进 artifact。多 stage 报告聚合在 `metadata.stages`，状态为 `completed` / `cached` / `unavailable` / `failed`，任何状态都不阻断、也不自动修复。关闭功能会清理旧 `mimo_qc.json`，避免陈旧建议被误认为本轮结果。
+
+QC 证据把 `source_asr` 与 `generated_subtitles` 分开：前者只用于源事实/原声时序，后者是本轮旁白派生字幕，不能反过来充当事实证据。多视频项目从 `multi_source_manifest.json` 指向的逐源 work dir 汇集 ASR；`cut_output` 解说评审同样按 `source_id` 映射逐源 VLM/ASR，避免项目根目录没有单一 ASR 文件时产生空证据。
+
+渲染后，`recap.py` 先更新 `preflight_qc.json` 的 `post_render` stage，再运行可选 MiMo 提示，最后写 `final_qc.json` 和 `golden_eval.json`。`final_qc.json` 汇总最终 mp4、`assembly_manifest.json`、`assembly_qc.json`、`visual_qc.json`、`preflight_qc.json`、`mimo_qc.json` 的本地元数据；缺失/空成片、ffprobe 不可用或失败、以及 assembly/visual QC 的客观 blocker 会进入 deterministic blockers。MiMo 和其他 non-deterministic finding 永远不能成为 blocker；客观佐证必须由 deterministic producer 另发 finding。`golden_eval.json` 默认要求 `final_qc.json.ok=true`，也可用 golden fixture 做简单的时长、codec 和必需 artifact 断言。所有 QC metadata/evidence 写入前都经过 `qc_contract.redact_secrets`：secret-looking key/value 会被替换，URL userinfo/query/fragment 会被移除，仅保留必要 host/path 诊断信息。

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

@@ -0,0 +1,74 @@
+# 背景调研指南（可选）
+
+Agent 在开始视频理解**之前**先做背景调研，确认作品名、角色关系、剧情背景或科普概念，写入 `work_dir/background_research.json`。理解阶段会把它并入 VLM 的画面分析上下文，让场景描述能直接叫出人物名字、带着剧情读画面，而不是把人都标成「黑衣男子」。**调研不是必需步骤**；没有浏览器工具、网络不可用或用户未提供明确片名时，直接跳过，不阻塞视频生成。
+
+## 工具选择
+
+使用当前环境里可用的任意检索方式即可，例如：
+
+- Codex / Claude 自带的联网搜索或网页浏览工具
+- 用户已经配置好的浏览器自动化或页面读取工具
+- 普通浏览器手动查找后把结果整理进 JSON
+- 已知资料、用户给的剧情背景或项目内已有文档
+
+## 通用流程
+
+1. 从 `--context`、文件名或用户描述里提取可搜索关键词。
+2. 搜索 1-3 个高价值问题，不要过度调研。
+3. 只记录对解说有帮助的事实：人物关系、剧情前提、世界观、当前集上下文、术语解释。
+4. 写入 `work_dir/background_research.json`。
+5. 如果查不到可靠信息，跳过调研并继续视频理解；不要在理解索引生成前提前写 `narration.json`。
+
+## 按视频类型搜索策略
+
+### 短剧 / 电视剧
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{作品名} 剧情 介绍 人物` | synopsis, characters |
+| `{作品名} 人物 关系` | characters |
+| `{作品名} 第{N}集 剧情` | episode_context |
+
+### 电影
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{电影名} 剧情 简介` | synopsis |
+| `{电影名} 影评 解读` | cultural_notes |
+
+### 纪录片 / 科普视频
+
+| 搜索关键词 | 目标字段 |
+|-----------|---------|
+| `{主题} 背景 知识` | worldbuilding |
+| `{核心概念} 解释` | synopsis |
+| `{主题} 最新 进展` | cultural_notes |
+
+## 写入格式
+
+写入 `work_dir/background_research.json`，只填搜到的字段，未搜到的字段省略，不要写 `null` 或空字符串。
+
+```json
+{
+  "synopsis": "...",
+  "characters": {
+    "角色名": "简介或关系"
+  },
+  "worldbuilding": "...",
+  "episode_context": "...",
+  "cultural_notes": [
+    {"item": "...", "explanation": "..."}
+  ]
+}
+```
+
+## 错误处理
+
+| 场景 | 处理 |
+|------|------|
+| 没有浏览器 / 搜索工具 | 跳过调研，继续视频理解 |
+| 搜索无结果 | 换一组关键词重试一次，仍无结果则继续视频理解 |
+| 结果互相矛盾 | 只使用用户提供的上下文或画面/ASR 可验证的信息 |
+| 信息可能剧透后续 | 只用于理解人物关系，不在解说里剧透用户没要求的后续剧情 |
+
+**原则**：背景资料只能补上下文，不能替代 `vlm_analysis.json` / `asr_result.json` 里的画面和对白证据。

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

@@ -0,0 +1,23 @@
+# 前置 QC 数据契约
+
+`final_qc.json`、`golden_eval.json`、`mimo_qc.json` 与 `preflight_qc.json` 共用一套最小结构，由本技能的 `scripts/qc_contract.py` 实现。
+
+## 字段契约
+
+- `schema_version`：整数 `1`。
+- `artifact`：只能是 `final_qc.json`、`golden_eval.json`、`mimo_qc.json` 或 `preflight_qc.json`。
+- `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`。
+- `sample_policy`：至少包含 `type`；其值只能是 `all`、`deterministic`、`sampled`、`semantic` 或 `aesthetic`。
+- `location.timecode` 与 `location.source_span` 必须存在；剪辑前阶段可以把任一字段设为 `null`。
+- 为兼容与诊断，当前辅助函数还可能写出 `id`、`category`、`code`、`message`、`source` 与 `objective_corroboration`。
+
+## 阻断语义
+
+只有确定性的客观规则可以阻断，例如产物缺失或过期、时长或媒体流错误、字幕与 TTS 放置错误、数据结构无效。
+
+MiMo 语义/审美 finding 以及其他所有非确定性 finding **始终只给建议，不能阻断**。若存在客观佐证，必须由确定性生产者单独写成确定性 finding；它不能把主观模型观察升级成 blocker。运行时不存在 allow-list 或规则表逃生口。
+
+`qc_contract.py` 只负责数据结构：不调用 MiMo、不连接流水线，也不自动修复。独立的 `mimo_qc.py` 只有在显式开启时，才会在 `pre_assemble` 和/或 `post_render` 各发起一次实时请求；它保持 fail-open，且不落盘凭证或抽帧 base64。所有报告构建器都通过 `qc_contract.redact_secrets` 处理元数据与证据：脱敏疑似密钥的键值，并从 URL 移除 userinfo、query 与 fragment，同时保留有用的 host/path 上下文。