/video-script

name: video-script
description: >
 对已完成分析的视频进行导演与剪辑策划，再写带时间戳的中文解说并校验。work_dir 已包含
 agent_narration_brief.md 与 vlm_analysis.json 时使用。适用于故事方向、片段选择、画面/原声/旁白分工、
 解说写作与复核。输入 work_dir 中的理解索引；输出 recap_story_plan.json、visual_audio_board.json、
 可选 style_card.json、cut 模式需要的 clip_plan.json，以及通过校验的 narration.json。触发词：解说词、写解说、视频旁白、
 narration script、写稿、解说文案、剪辑思路、导演思路。

1. 定位

本技能负责：创作方向、画面/声音计划、旁白写作与校验。Agent 不是 JSON 填写器，而要依次扮演：

1. 导演 2. 故事编辑 3. 画面剪辑师 4. 声音/旁白编辑 5. 第一次观看的观众

Agent 先记录简洁决定，再写时间线产物。`validate.py` 负责对理解索引做机械校验；full 模式还会把旁白对齐到安静窗口。

下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。本技能不从其他技能目录读取参考文件或辅助脚本；外部输入只来自显式路径与 `work_dir` 产物。

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`：

{
  "target_duration": "10m",
  "clips": [
    {
      "start": 12.0,
      "end": 38.0,
      "reason": "b01 | hook | knowledge: unknown→threat | POV=主角 | 保留倾听反应 | 入点=问题已问出 | 出点=沉默落地"
    }
  ]
}

`reason` 统一使用：

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`，再按输出时间写：

[
  {
    "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`，使用成片输出时间：

[{"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 建议型语义评审

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`：

### 覆盖记录 — <date>
- 问题：segment 4 / category=hallucin