@lemoncat7/dsh-partner 2.8.1 → 2.8.3

package/resources/skills/video-recap-production/upstream/skills/video-recap/scripts/resource_lock.py

@@ -0,0 +1,162 @@
+"""Record every resource and template a finished run used: ``work_dir/resource_lock.json``.
+
+Facts come from artifacts the stages already wrote (run manifest, ``tts_meta.json``,
+``assembly_manifest.json``) plus the optional project binding. When a library is
+configured, each file-backed entry is matched to a registered resource by resolved path
+so its licence and consent status travel with the run. Nothing here changes a render.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+
+import library as library_lib
+from materials import file_identity
+
+LOCK_NAME = "resource_lock.json"
+LOCK_SCHEMA = "video-recap.resource-lock.v1"
+
+
+def _read(path: Path):
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+def _file_entry(role: str, path, detail=None) -> dict:
+    entry = {"role": role, "path": None, "size": None, "mtime_ns": None,
+             "detail": detail or {}, "library": None}
+    if path:
+        resolved = Path(path).expanduser().resolve()
+        entry["path"] = str(resolved)
+        if resolved.is_file():
+            entry.update(file_identity(resolved))
+    return entry
+
+
+def _source_entries(work_dir: Path) -> list[dict]:
+    manifest = _read(work_dir / "recap_run_manifest.json") or {}
+    if manifest.get("mode") == "multi_source":
+        return [_file_entry("source_video", s.get("source_path"), {"source_id": s.get("source_id")})
+                for s in manifest.get("sources", [])]
+    if manifest.get("source_video"):
+        return [_file_entry("source_video", manifest["source_video"])]
+    return []
+
+
+def _voice_entry(work_dir: Path) -> dict | None:
+    meta = _read(work_dir / "tts_meta.json")
+    if not isinstance(meta, dict):
+        return None
+    voice = meta.get("voice") or {"provider": meta.get("engine")}
+    reference = voice.get("reference") or {}
+    entry = _file_entry("voice", reference.get("path"), {
+        "provider": voice.get("provider"), "model": voice.get("model"),
+        "voice_id": voice.get("voice_id"),
+    })
+    return entry
+
+
+def _assembly_entries(work_dir: Path) -> list[dict]:
+    manifest = _read(work_dir / "assembly_manifest.json") or {}
+    settings = manifest.get("assembly_settings") or {}
+    entries = []
+    bgm = (settings.get("audio_mix") or {}).get("bgm_path")
+    if bgm:
+        entries.append(_file_entry("bgm", bgm))
+    packaging = (settings.get("video_filters") or {}).get("packaging_layers") or {}
+    for layer in packaging.get("layers", []):
+        entries.append(_file_entry("packaging_layer", layer.get("path"), {"name": layer.get("name")}))
+    style = settings.get("subtitle_style")
+    if isinstance(style, dict):
+        entries.append(_file_entry("subtitle_font", style.get("font_file"),
+                                   {"family": style.get("font_name")}))
+    return entries
+
+
+def _match_library(entries: list[dict], index: dict) -> None:
+    by_path = {}
+    for resource in index["resources"]:
+        for f in resource["files"]:
+            by_path[str(Path(f["path"]).resolve())] = resource
+    voices = [r for r in index["resources"] if r["kind"] == "voice"]
+    records = {r["id"]: json.loads(Path(r["record"]).read_text(encoding="utf-8"))
+               for r in index["resources"]}
+    for entry in entries:
+        resource = by_path.get(entry["path"]) if entry["path"] else None
+        if (resource is None and entry["role"] == "voice" and not entry["path"]
+                and isinstance(entry["detail"].get("voice_id"), str) and entry["detail"]["voice_id"]):
+            detail = entry["detail"]
+            resource = next((v for v in voices
+                             if (records[v["id"]].get("voice") or {}).get("provider") == detail.get("provider")
+                             and (records[v["id"]].get("voice") or {}).get("voice_id") == detail.get("voice_id")), None)
+        if resource is None:
+            continue
+        record = records[resource["id"]]
+        entry["library"] = {"id": resource["id"], "kind": resource["kind"],
+                            "license": resource["license"],
+                            "consent": (record.get("consent") or {}).get("status")}
+
+
+def _attention(entries: list[dict], library_configured: bool) -> list[dict]:
+    items = []
+    for entry in entries:
+        role, lib = entry["role"], entry["library"]
+        if role == "source_video":
+            continue
+        if lib is None:
+            if library_configured and (entry["path"] or role == "voice"):
+                items.append({"code": "unregistered", "role": role,
+                              "message": "资源库中没有登记这项资源，授权状态未知"})
+            continue
+        if lib["license"] in {"unknown", "restricted"}:
+            items.append({"code": f"license_{lib['license']}", "role": role,
+                          "message": f"{lib['id']} 的授权状态为 {lib['license']}，交付前需要人工确认"})
+        if role == "voice" and entry["path"] and lib.get("consent") != "granted":
+            items.append({"code": f"consent_{lib.get('consent') or 'unknown'}", "role": role,
+                          "message": f"{lib['id']} 的参考音频声音授权未确认"})
+    return items
+
+
+def build_resource_lock(work_dir, *, library_dir=None, project=None) -> dict:
+    """Assemble the lock payload from a finished work_dir; ``project`` is a resolved binding."""
+    work_dir = Path(work_dir)
+    entries = _source_entries(work_dir)
+    voice = _voice_entry(work_dir)
+    if voice:
+        entries.append(voice)
+    entries += _assembly_entries(work_dir)
+    entries += list((project or {}).get("resources", []))
+    library_root = None
+    if library_dir and Path(library_dir).is_dir():
+        library_root = str(Path(library_dir).resolve())
+        index, _ = library_lib.scan_library(library_root)
+        _match_library(entries, index)
+    return {
+        "schema": LOCK_SCHEMA,
+        "generated_at": datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z"),
+        "work_dir": str(work_dir.resolve()),
+        "library": library_root,
+        "project": ({"path": project["path"], "name": project.get("name", "")} if project else None),
+        "templates": list((project or {}).get("templates", [])),
+        "resources": entries,
+        "attention": _attention(entries, library_root is not None),
+    }
+
+
+def write_resource_lock(work_dir, *, library_dir=None, project=None) -> dict:
+    lock = build_resource_lock(work_dir, library_dir=library_dir, project=project)
+    path = Path(work_dir) / LOCK_NAME
+    path.write_text(json.dumps(lock, ensure_ascii=False, indent=2), encoding="utf-8")
+    return lock
+
+
+def summary_line(lock: dict) -> str:
+    registered = sum(1 for e in lock["resources"] if e["library"])
+    text = (f"[video-recap] 资源记录: {LOCK_NAME}（{len(lock['resources'])} 项，"
+            f"资源库已登记 {registered} 项）")
+    if lock["attention"]:
+        text += "\n" + "\n".join(f"[video-recap]    ⚠ {a['role']}: {a['message']}" for a in lock["attention"])
+    return text

package/resources/skills/video-recap-production/upstream/skills/video-script/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: video-script
+description: >
+ 对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验；也处理已有短片的
+ 宣发标题、花字修订和外部文案回填。普通策划输入 work_dir 的 agent_narration_brief.md 与
+ vlm_analysis.json；文案返修输入当前成片的工程与内容证据。策划输出 recap_story_plan.json、visual_audio_board.json、
+ 可选 style_card.json、cut 模式需要的 clip_plan.json，以及通过校验的 narration.json；仅宣发文案任务交付提案或回填既有包装计划。
+ 触发词：解说词、写解说、视频旁白、宣发标题、花字修订、文案回填、
+ narration script、写稿、解说文案、剪辑思路、导演思路。
+---
+
+## 1. 定位
+
+只改宣发标题、封面、花字或回填外部文案时，直接读 `references/promotional-copy.md`，
+按当前短片的观看理由和兑现位置处理指定文字层，不重做下述策划/旁白链。
+普通解说写作不因此增加平台调研或包装任务。
+
+本技能负责：创作方向、画面/声音计划、旁白写作与校验。Agent 不是 JSON 填写器，而要依次扮演：
+
+1. 导演
+2. 故事编辑
+3. 画面剪辑师
+4. 声音/旁白编辑
+5. 第一次观看的观众
+
+Agent 先记录简洁决定，再写时间线产物。`validate.py` 负责对理解索引做机械校验；full 模式默认还会执行预算整理并计算旁白的原声重叠。已有批准稿应加 `--preserve-approved-text`，保留段落顺序、数量、时间、文本、停顿和扩展元数据，仅允许依据现有声音证据更新 `overlaps_speech`。
+
+下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。
+
+### 1.1 创作控制模式
+
+先根据用户要求和 `work_dir` 判断本轮模式；它不是 `full|cut|dub` 渲染模式：
+
+- **CREATE**：首次创作。比较至少两个真正可行的故事/剪辑假设后再选择。
+- **DIRECTED**：用户已指定结构、镜头、台词或表达。忠实落实，不为满足“创作流程”虚构替代方案。
+- **REVISION**：用户针对已有版本看片修改。最新反馈是当前事实来源；未点名部分默认冻结。
+
+REVISION 先明确本轮修改项与冻结项，再编辑对应层：表达、口语节奏、字幕反馈更新 `style_card.json`；镜头、入出点、表演和声音分工更新 `visual_audio_board.json`；只有观众承诺、POV、主线或 beat 改变时才更新 `recap_story_plan.json`。被删除的镜头、原声或文案也要从相关计划中删除，不能保留过期锚点。不要把看片修改重新做成一次 CREATE。
+
+## 2. 读取素材并确认状态
+
+首先阅读：
+
+- `work_dir/agent_narration_brief.md`：场景、时长、安静窗口与字数预算。
+- `asr_writing_chunks.json`：长对白的写作分块。
+- `timeline_fusion.json`：判断某段是否有对白或静音槽。
+- `vlm_analysis.json` / `asr_result.json`：核对具体画面与原声证据。
+- brief 顶部列出的 contact sheet：不要只依赖场景摘要；反应、走位、静止和台词前后的具体时刻常常更重要。
+
+full 模式使用原片时间。cut 模式第一阶段只写 `clip_plan.json`；`edited_source.mp4` 产生后，第二阶段才按输出时间写 `narration.json`。
+
+写任何创作产物前，直接读取 `work_dir` 判断当前阶段：
+
+- `recap_run_manifest.json`：确认 `edit_mode`、源视频和本轮设置。
+- full 模式：没有 `narration.json` 时进入写稿；存在时先复核再校验。
+- cut 第一阶段：尚无 `clip_plan_validated.json` / `edited_source.mp4`，只写 `clip_plan.json`。
+- cut 第二阶段：两者都存在，按 `clip_plan_validated.json.clips[]` 中的 `source_start/end` 与 `output_start/end` 核对映射，再写输出时间的旁白。
+
+必须确认旁白没有跨越错误剪辑边界，也没有落进已删除区间。整个判断只依赖 `work_dir` 产物。
+
+## 3. 制定创作方案
+
+先阅读 `references/creative-editing-playbook.md`，再按创作控制模式写或更新工作产物：
+
+1. **`recap_story_plan.json`**：导演意图、CREATE 中至少两个剪辑假设、选定的 POV / 主线，以及由“变化”定义的 beats。DIRECTED / REVISION 不强行新增假设。
+2. **`visual_audio_board.json`**：每拍的画面任务、具体表演/反应、入点/出点、`audio_owner`、原声锚点与 `narration_job`。
+3. **`style_card.json`（适用时）**：用户当前认可的声音、口语节奏、字幕阅读姿态和明确禁忌。收到表达或字幕反馈后更新原文件，而不是只改最终文案。
+
+只记录决定、证据锚点、被放弃的备选方案和简短理由，不写冗长思维过程。
+
+### 3.1 导演判断
+
+锁定：
+
+- 观众承诺
+- POV
+- 戏剧问题
+- 起始与结束情绪
+- 隐瞒与揭示
+- 结尾余味
+
+### 3.2 故事编辑
+
+CREATE 比较两个真正可行的结构后选择一个；DIRECTED / REVISION 沿用用户指定或已确认的结构，除非最新反馈明确改变故事方向。每个 beat 至少改变一项：知识、权力、目标、关系、情绪或风险。若删除后因果、人物和情绪都没有损失，该 beat 通常不应保留。
+
+### 3.3 画面剪辑
+
+选择具体时刻，而不是只选择事件。比较：
+
+- 说话者与倾听者
+- 动作与反应
+- 早进与晚进
+- 早出与多停半秒
+
+在不破坏理解的前提下晚进早出，同时保留不可替代的表演、停顿、失误、动作声和完整台词。
+
+### 3.4 声音与旁白分工
+
+先指定 `audio_owner`，再写字。旁白只允许承担以下 `narration_job`：
+
+- `context`
+- `causal_link`
+- `foreshadow`
+- `interpretation`
+- `transition`
+- `none`
+
+画面、原声或沉默已经足够时使用 `none`，不要默认铺旁白。
+
+### 3.5 cut 模式第一阶段
+
+cut 模式先根据 `recap_story_plan.json` 与 `visual_audio_board.json` 写原片时间的 `clip_plan.json`，此时不要写 `narration.json`：
+
+```json
+{
+  "target_duration": "10m",
+  "clips": [
+    {
+      "start": 12.0,
+      "end": 38.0,
+      "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
+    }
+  ]
+}
+```
+
+`reason` 统一使用：
+
+```text
+beat_id | function | change | POV | preferred moment | 入点 | 出点
+```
+
+片段顺序必须构成一条完整故事线，而不是无序高光。可使用 0–1 个 cold open，随后回到因果清楚的 setup → turn → escalation → payoff。片段长度服从具体时刻，不使用统一秒数模板；片尾必须保留完整台词或动作。密集 scene-change 候选的来源判断与处理规则由剪辑阶段定义，写计划时遵循同一规则，不制造人工闪切。
+
+## 4. 撰写旁白
+
+full 模式直接按原片时间写；cut 第二阶段先查看 `edited_source.mp4` 与剪后故事板，补充 `visual_audio_board.json` 的输出时间并重新确认 `audio_owner` / `narration_job`，再按输出时间写：
+
+```json
+[
+  {
+    "start": 5.0,
+    "end": 12.0,
+    "narration": "解说文本。",
+    "pause_after_ms": 250,
+    "overlaps_speech": true,
+    "emotion": "紧张"
+  }
+]
+```
+
+字段说明：
+
+| 字段 | 含义 |
+|------|------|
+| `start` / `end` | full 模式为原片时间；cut 第二阶段为输出时间 |
+| `narration` | 解说文本 |
+| `pause_after_ms` | 段后停顿，默认 250ms |
+| `overlaps_speech` | 是否与原对白重叠；连续铺底窗口通常为 `true`，真正静音槽才为 `false` |
+| `emotion` | 整个解说块的 MiMo TTS 情绪/语气标签 |
+
+### 4.1 写作规则
+
+1. **先有 `narration_job`，后有句子**：没有明确任务就不写；旁白不是默认音轨。
+2. **按连续思路写**：旁白拥有一个 beat 时，用一个或少量完整句子完成“前提 → 触发动作 → 变化/意义”，并在一次 TTS 中合成。句号服从口语思路和呼吸，不服从字幕换行；不要固定句数，也不要“一句一停”。
+3. **7:3 不是配额**：只在素材判断不足时作为避免墙到墙旁白的粗略首稿参考。实际比例服从 `audio_owner`；强对白、动作声或沉默可以完整拥有一个 beat。
+4. **视听接力**：旁白若引出原声，块尾要让观众想听；原声结束后的下一块要承接它造成的变化。
+5. **按有效语速控量**：用 `字数 / brief 头部 speech budget` 估算窗口；装不下时删减或拆分叙事任务，不用加速堆字。
+6. **不看图说话**：旁白只增加上下文、因果、预期、证据支持的解释或跨越。
+7. **人物与证据优先**：优先使用已知角色名；关系、动机、潜台词和结果必须指向 visual / ASR / research / user context，且不能把背景资料伪装成当前画面事实。
+8. **写给耳朵听**：使用具体名词和动词，句子完整、口语可听；避免字幕腔、半句、空泛拔高和破折号。TTS 文本先保证听感连续，字幕再按阅读宽度拆分，不能反过来把朗读稿切碎。
+9. **避免模板化纠偏**：“不是 A，而是 B”只在确实存在一个观众可能相信、而素材又要纠正的判断时使用。它不是禁句，但不能靠先否定再肯定制造假洞察；优先直接写人物的动作、因果和后果。
+
+### 4.2 解说结构
+
+- **钩子**：提出正文会真实兑现的问题或利害，不用无关留存话术。
+- **主线**：围绕选定 POV 与主线推进，不在每个场景重新开篇。
+- **递进**：后续 beat 必须提高风险、改变关系或提供新信息。
+- **悬念缺口**：只预告之后真的会回收的后果。
+- **收尾**：回答或有意转化开头问题，留下明确余味。
+- **衔接**：旁白块与相邻原声属于同一个 beat，前者铺垫、后者呈现、下一块承接。
+
+### 4.3 原声留白字幕
+
+可选写 `original_subtitles.json`，使用成片输出时间：
+
+```json
+[{"start": 15.0, "end": 17.0, "text": "原声台词"}]
+```
+
+只写留白中实际听得到的台词，订正 ASR 错字与人名，每条尽量控制在一行；被旁白盖住或已经剪掉的句子不要写。省略时，合成阶段会使用保守的 ASR 映射兜底，并在成片中用 `「」` 区分原声对白与旁白。
+
+## 5. 创作自审
+
+在调用 LLM 评审前做以下**反事实检查**：
+
+1. 删除每个 beat：若因果、人物、情绪或承诺没有损失，就删除。
+2. 比较说话者/动作与倾听者/反应：保留更符合 POV 和情绪的时刻。
+3. 静音旁白：画面与原声仍应承载可见行动、人物行为和关键情绪。
+4. 只听声音：旁白应形成可听懂的主线，而不是画面字幕。
+5. 把旁白换成原声或沉默：若场景自身更有力量，就让出声音所有权。
+6. 检查开头问题是否真实，结尾是否回答或转化它。
+7. 检查相邻短句能否合成一个连续思路；字幕分行不得成为 TTS 断句理由。
+
+只记录并优先修复 1–3 个回报最高的问题；先改结构，再润色句子。
+
+REVISION 还要逐项确认：用户点名的问题已经改变，未点名的冻结项没有意外变化，相关 `style_card.json` / `visual_audio_board.json` 中不存在旧镜头或旧表达。除非用户要求备选版本，不额外扩展新方向。
+
+## 6. 评审与校验
+
+### 6.1 建议型语义评审
+
+```bash
+python3 scripts/review.py --work-dir <work_dir>
+```
+
+评审会自动识别 cut 模式，并在存在已校验剪辑计划时按输出时间线核对；`--timeline source` 可强制使用原片时间。打开 `narration_review.md`，逐项处理 `error`，尤其是 `category=hallucination`。
+
+重复修改并评审，直到：
+
+- `verdict` 为 `PASS` / `OK` 且没有 `error`；或
+- 对仍保留的问题做明确 override。
+
+覆盖决定追加到 `work_dir/narration_review_override.md`：
+
+```markdown
+### 覆盖记录 — <date>
+- 问题：segment 4 / category=hallucination
+- 评审意见：“他早已知情”缺少画面/对白依据
+- 决定：KEEP — 该事实来自用户提供的当前集背景，而非未来剧情
+- 签署：<agent/human>
+```
+
+`review.py` 本身只写报告，默认调用策略为建议型、失败开放；若调用方显式开启严格评审，事实矛盾、残句、解析失败或评审不可用可在 TTS 前阻断。覆盖记录只用于审计，`review.py` / `validate.py` 不读取它。
+
+### 6.2 确定性硬校验
+
+```bash
+python3 scripts/validate.py --work-dir <work_dir> --mode full
+python3 scripts/validate.py --work-dir <work_dir> --mode full --preserve-approved-text
+# cut 输出时间线由编排器使用 --mode cut_output
+```
+
+命令写出 `narration_lint.json`。full 模式默认执行字符预算整理、去重合并并依据安静窗口计算 `overlaps_speech`，但不会把时间段移动到安静窗口；`--preserve-approved-text` 则保留批准稿的原始时间、文本、停顿、顺序与扩展元数据，只允许更新实测 `overlaps_speech`。修复所有 error 后重复运行，直到校验干净，再继续 TTS 与合成。
+
+片名或题材明确但缺少剧情上下文时，先按本技能的 `references/research-guide.md` 写 `background_research.json`。若理解素材偏薄，brief 中的数量只能当上限：宁可少写、写实，也不要为凑数复述画面。
+
+## 7. 能力边界
+
+- 不运行 ASR / VLM，不合成 TTS，不渲染视频；只消费视频理解索引。
+- 平台研究仅用于明确的宣发任务；不替代当前片内事实，也不默认改变解说和剪辑。

package/resources/skills/video-recap-production/upstream/skills/video-script/references/creative-editing-playbook.md

@@ -0,0 +1,229 @@
+# 创作剪辑工作法
+
+本参考只规定 Agent 的创作判断，不增加渲染模块。进入剪辑或写稿前，先完成这里的决策，再写 `clip_plan.json` 或 `narration.json`。
+
+## 先判断创作控制模式
+
+- **CREATE**：没有既定成片方向，可以比较故事/剪辑假设并选择。
+- **DIRECTED**：用户已经指定结构、镜头、台词或表达，目标是准确落实而不是展示替代创意。
+- **REVISION**：基于已有版本看片修改。最新反馈覆盖旧决定；本轮未点名内容默认冻结。
+
+REVISION 先列本轮修改项与冻结项。表达、节奏、字幕意见写回 `style_card.json`，镜头与声音意见写回 `visual_audio_board.json`；只有故事主线改变才更新 `recap_story_plan.json`。删除内容时也删除过期的计划描述。只提能定位到 beat、镜头边界或句子的具体局部修法，未点名层继续冻结；完成后分别验证“该变的确实变了”和“不该变的没有漂移”。
+
+## 决策优先级
+
+硬约束先于审美：
+
+1. **证据真实**：人物、关系、因果和结果必须由画面、对白、可靠背景或用户上下文支撑。
+2. **声音可懂**：关键原声不能被截成半句，旁白不能把必须听见的对白完全盖住。
+
+硬约束满足后，发生冲突时按以下顺序取舍：
+
+1. 情绪与人物；
+2. 故事推进；
+3. 节奏；
+4. 视线与画面连续；
+5. 技术上的“绝对工整”。
+
+不要为了连续而牺牲人物反应，也不要为了快而删掉真正改变观众感受的瞬间。
+
+## 五次专业判断
+
+### 1. 导演：先决定观众经历什么
+
+先回答，而不是先写开场文案：
+
+- 观众承诺：看完具体会理解、担心或感受到什么？
+- POV：这条内容主要跟随谁的经历？谁不是主视角？
+- 戏剧问题：观众一直想知道的那个问题是什么？
+- 情绪路径：开头的情绪如何变成结尾的情绪？
+- 隐瞒与揭示：什么信息暂时不说，何时揭示才最有力量？
+- 结尾余味：答案落地后，观众最后应留下什么感受？
+
+CREATE 至少提出两个可成立的剪辑假设，再选一个。比较的是叙事效果，不是措辞：例如“按主角认知逐步揭示”与“先展示后果再追问原因”。DIRECTED / REVISION 沿用用户指定或已确认的主线，不为满足模板重新发散。只记录当前选择与理由，不输出冗长思维过程。
+
+### 2. 故事编辑：把素材组织成变化
+
+beat 不是固定秒数、场景名或一句旁白；beat 是一次可感知的变化。每个保留 beat 至少改变一项：
+
+- 观众知道了什么；
+- 人物想要什么；
+- 谁占上风；
+- 关系如何移动；
+- 情绪如何转向；
+- 风险或代价如何升级。
+
+如果移除一个 beat 后，因果、人物或情绪都没有损失，它通常不值得占用成片时间。精简不能只保“发生了什么”：还要保住人物动机、接受条件，以及人物为何犹豫或行动；缺前提时回到源证据，用更短的原声或解说补齐，不恢复无关长铺垫。钩子必须提出这条故事真正会兑现的问题，不能制造正文不回答的夸张承诺。
+
+准备移交剪辑时，把这类不可删除的具体源时刻写入同一 `clip_plan.json.required_evidence`：`nodes` 每项记录唯一 `id`、实际文件绝对路径 `source`、原片秒 `start/end`、`track`（audio/video）和 `content`；多源可补 `source_id`。`before` 用 `[前提id, 回应id]` 登记本片必需的顺序。只锁必要区间，不锁整个 beat；不依赖 `reason` 里的“保留前提”一句话。剪辑执行器会在吸附剪点后核对这些要求，缺段时先修选择，再配音包装。
+
+### 3. 画面剪辑：选择时刻，而不只选择事件
+
+对每个 beat 做以下判断：
+
+- **入点**：能否晚一点进入，跳过已经能推断的铺垫？
+- **出点**：信息或情绪落地后，能否早一点离开？
+- **表演**：说话者与倾听者谁更能承载此刻？动作与反应谁更重要？
+- **不可替代瞬间**：停顿、迟疑、失误、眼神、动作声音中，哪一个让人物变得真实？
+- **节奏**：这一拍需要冲过去，还是需要多停半秒让含义落地？
+- **边界**：优先完整动作、完整台词和自然声音边界；不要机械地把每个片段切成同一长度。
+- **兑现**：以某个可见结果为看点时，只写证据已呈现的结果，不推断更强的结果（例：证据只到受击，就不能写成倒地或胜负）。
+
+进入 `clip_plan.json` 的不是“发生过的所有重要事件”，而是最能让观众经历这条主线的具体时刻。
+
+目标不是绝对最短，而是**最短但完整**：晚进不能丢掉理解动作所需的前提，早出不能吃掉表演的回报。建立空间和事实的镜头通常可以短；关键对视、亲吻、受伤反应、决定落地或沉默可以多停一点，让观众先感受到再离开。有情感回应或知情变化的反应镜不是冗余，不能仅因它是反打或停留较短就机械删除。
+
+场景之间的 IN / OUT 也要有任务：
+
+- 新人物、地点或情绪场景，先给画面一个可感知的建立时刻，再让旁白进入；旁白不必与画面同帧起跑。
+- OUT 优先落在动作完成、反应落地、台词句末、沉默结束或干净硬切前。
+- 不要在原片叠化、闪白或其他转场的中间再切一次。转场至少由画面变化、动作延续、声音接力或叙事跨越中的一项驱动。
+- 跨场镜头只能作明确的并置或主题呼应，不得拼成同场出手、接触、反应的虚假因果；花字只能补有证据的必要前提，不能替补源证据或提前宣布结果。
+
+scene-change score、逐帧亮度和接点 contact sheet 只用于诊断：检查每个接点前后约 0.5–1 秒，定位硬切、白闪或曝光叠化候选。修复优先收进稳定镜头、保留原片完整转场的一侧、扩展源素材，或用相邻有效镜头补足时长；不能为了视觉干净切断台词。最终必须真实播放接点，不能把检测分数当成观看结论。
+
+对短时间频繁切镜头的段落，先用 ffmpeg scene filter 输出候选时间，例如：
+
+```bash
+ffmpeg -i input.mp4 -vf "select='gt(scene,0.35)',showinfo" -an -f null -
+```
+
+阈值只用于召回候选，闪白、叠化和大幅运动都可能误报。把候选映射回 source 区间和成片拼接边界后再分类处理：
+
+- **原片切点**：无关的短镜头按完整 source shot 删除；相关但停留过短、看起来像闪一下的镜头，向前/后扩展到完整动作、反应、台词或下一个干净切点。这里的“拉长”是多保留真实源素材，不默认用定格或慢放制造不存在的表演。
+- **本次剪辑制造的切点**：优先移动 IN / OUT、恢复同一源镜头的连续运动、合并相邻片段，或换成有叙事任务的连接镜头；能消除就不保留。溶解、闪白和包装不能用来遮掩坏接点。
+- **有意的原片蒙太奇**：只有当每个短镜头都提供新信息、动作或节奏回报，且正常播放仍清楚可读时才保留；否则按无关或过短镜头处理。
+
+密集度不是单一固定秒数门槛。反打是否保留取决于它有没有新增信息，例如关系、情感回应、知情变化或空间/动作结果，而不是是否达到统一时长；先找同一短窗内的连续候选，再以正常速度播放判断观众感受到的是有效节奏还是闪烁。
+
+### 4. 声音与旁白：先分工，再写字
+
+每个 beat 先指定一个主要 `audio_owner`：
+
+- `original_dialogue`：原对白本身就是事件或表演；
+- `action_sound`：动作声音承担冲击、因果或空间感；
+- `ambience` / `music`：环境或音乐承担情绪；
+- `silence`：沉默、停顿或呼吸是内容；
+- `narration`：画面和原声无法独自交代必要的上下文、因果或预期。
+
+只有当旁白有明确工作时才写。`narration_job` 只能从以下任务中选择：
+
+- `context`：补充看不见但必要的背景；
+- `causal_link`：连接被压缩掉的因果；
+- `foreshadow`：建立稍后会兑现的预期；
+- `interpretation`：基于证据指出人物选择、关系或代价；
+- `transition`：跨越时间、地点或素材来源；
+- `none`：画面、原声或沉默已经足够。
+
+`7:3` 只可作为没有更好判断时的粗略首稿参考，不是质量目标或覆盖配额。强对白可以让一个 beat 完全没有旁白；信息密集的压缩段也可以由旁白主导。
+
+旁白拥有一个 beat 时，先写成一个连续思路，常见推进是“前提 → 触发动作 → 变化/意义”。句子数量不是目标；一个完整长句或少量相连句都可以，关键是一次 TTS 能自然说完而不是一句一停。字幕可以为阅读拆成多个 cue，但不能反过来把朗读稿切成碎 utterance。
+
+“不是 A，而是 B”只在素材确实需要纠正一个可能的旧判断时有价值。不要先虚构错误判断，再用肯定句制造洞察；能直接写动作、因果和后果时就直接写。
+
+### 5. 观众复核：从第一次观看出发
+
+完成草案后做三次反事实检查：
+
+1. **静音旁白**：只看画面和原声，人物、变化和关键情绪是否仍可感知？
+2. **只听声音**：旁白是否形成一条可听懂的主线，而不是字幕腔或画面复述？
+3. **第一次观看**：开头承诺了什么、每一拍又打开了什么问题、结尾是否真正回答？
+
+再逐 beat 追问：
+
+- 删除它，什么会坏？什么都不坏就删。
+- 删除或换掉反应镜头后，是否丢失情感回应、知情变化或新的动作结果？
+- 旁白改成原声或沉默，含义是否更好？
+- 提前揭示或延后揭示，哪一个更符合 POV？
+- 能否晚进、早出，而不损失理解？
+
+只优先处理 1–3 个最高回报修改，避免用大量低价值润色掩盖结构问题。
+
+准备交付时，把抽象的“第一次观看”落实成动作：正常速度完整播放实际最终文件；逐个播放接点前后；完整只听声音；再单独复看开头、核心情绪点和结尾。脚本、样帧与自动 QC 只能辅助定位，不能替代完整观看。
+
+## Agent 创作产物
+
+这些是简洁的决策记录，不是公开的完整思维过程。CLI 可以忽略它们，但后续 Agent 与建议型评审会使用它们保持创作一致。
+
+### `recap_story_plan.json`
+
+```json
+{
+  "schema_version": 1,
+  "director_intent": {
+    "viewer_promise": "观众最终得到的具体体验",
+    "pov": "主要跟随谁，以及为什么",
+    "dramatic_question": "贯穿全片的问题",
+    "emotional_start": "起始情绪",
+    "emotional_end": "结束情绪",
+    "ending_aftertaste": "最后余味",
+    "withhold_reveal": "保留什么，何时揭示"
+  },
+  "hypotheses": [
+    {"id": "h1", "spine": "方案一主线", "opening": "如何进入", "ending": "如何落地", "risk": "主要风险"},
+    {"id": "h2", "spine": "方案二主线", "opening": "如何进入", "ending": "如何落地", "risk": "主要风险"}
+  ],
+  "chosen_hypothesis": "h1",
+  "choice_reason": "为什么它更符合素材中的人物、故事和情绪",
+  "beats": [
+    {
+      "beat_id": "b01",
+      "source_id": "可选，多视频时填写",
+      "source_start": 12.0,
+      "source_end": 20.0,
+      "function": "hook|setup|turn|escalation|payoff",
+      "event": "可观察到的事件",
+      "change": "knowledge|power|emotion|goal: before -> after",
+      "audience_question_in": "进入前观众想知道什么",
+      "audience_question_out": "离开时答案或新问题是什么",
+      "character_focus": "此拍由谁承载",
+      "must_keep_moment": "不可替代的动作/表情/台词/声音",
+      "evidence": ["visual", "asr"]
+    }
+  ]
+}
+```
+
+上例是 CREATE 形态。DIRECTED / REVISION 可以只保留用户指定或当前采用的假设；不要复制一个虚假备选来凑数量。
+
+### `visual_audio_board.json`
+
+```json
+{
+  "schema_version": 1,
+  "items": [
+    {
+      "beat_id": "b01",
+      "source_id": "可选，多视频时填写",
+      "source_start": 12.0,
+      "source_end": 20.0,
+      "output_start": null,
+      "output_end": null,
+      "picture_job": "orientation|evidence|performance|reaction|action|contrast",
+      "preferred_moment": "具体要保留的画面时刻",
+      "entry_reason": "为什么从这里进入",
+      "exit_reason": "为什么在这里离开",
+      "audio_owner": "original_dialogue|action_sound|ambience|music|silence|narration",
+      "original_audio_anchor": "要完整保留的对白/动作声/停顿",
+      "narration_job": "none|context|causal_link|foreshadow|interpretation|transition",
+      "handoff": "前后画面、原声与旁白如何接力"
+    }
+  ]
+}
+```
+
+cut 第一阶段先用原片时间写；`edited_source.mp4` 产生后，在第二阶段补上输出时间并重新确认 `audio_owner` / `narration_job`。
+
+## 内容质量基线
+
+进入 TTS 前，以下问题都必须能用具体 beat 回答；否则先改计划或脚本：
+
+1. **承诺**：开头提出的真实问题，结尾是否兑现？
+2. **主线**：是否有一个明确 POV 和一条主导因果/关系线？
+3. **变化**：每个 beat 是否改变知识、权力、目标、关系、情绪或风险？
+4. **人物**：是否保留了至少一个不能由剧情概述替代的表演/反应瞬间？
+5. **视听分工**：每个 beat 是否明确由画面、原声、沉默或旁白中的谁主导？
+6. **必要性**：旁白是否都在增加信息或期待，而不是复述像素？
+7. **完整观看**：实际最终文件是否完整看过、逐接点看过并只听声音检查过？
+
+这套基线与抖音、YouTube 或任何平台数据无关。先让内容本身成立，再讨论标题、封面、时长档位和发布优化。