video-cut

## 1. 定位 本技能只执行 Agent 已经做出的剪辑决定： 1. 校验并补全 `clip_plan.json`，写出带 `clip_id`、原片/输出时间与时长的 `clip_plan_validated.json`。 2. 先避开原片硬切附近的闪帧风险，最后把边界吸附到可靠句末/自然停顿；声音完整性拥有最终优先级。 3. 拼接选定区间，输出 `edited_source.mp4`。 4. 编排流程默认到此停止，由 Agent 按真实输出时间线写 `narration.json`。 5. 旧版单阶段路径还会把原片时间的旁白映射为 `narration_mapped.json`。 相同输入会得到相同输出。缓存仅表示：当 `edited_source.mp4` 新于 `clip_plan.json` 时复用成片。 ## 2. 输入契约 `work_dir/clip_plan.json` 可以是数组，也可以是 `{"clips": [...]}`： ```json {"start": 12.0, "end": 28.5, "reason": "b02 | turn | power: A→B | POV=女主 | 保留反应 | 入点=问题落下 | 出点=沉默结束"} ``` - `start` / `end` 是原片秒数；也接受 `source_start` / `source_end` 或 `in` / `out`。 - 顶层可选 `target_duration`，例如 `"10m"`。 - 多视频项目的每个片段还必须填写 `source_id`。 - `speech_boundary_anchors.json` 与 ASR 时间段由理解阶段提供；Agent 先写大致区间，工具会尝试吸附并把仍在讲话区间内的入/出点作为 blocker 返回。 `work_dir/narration.json` 只在旧版单阶段路径中可选读取；该路径要求旁白使用原片时间。若允许重复或重叠片段，旁白可带 `source_clip_id` 消歧。 ## 3. 剪辑意图契约 工具不会替 Agent 做创作选择。写片段前先完成本节的剪辑意图检查，并让每个区间映射到 `recap_story_plan.json` 的一个 beat。 使用现有自由文本 `reason` 保存简洁决定： ```text beat_id | function | change | POV | preferred moment | 入点 reason | 出点 reason ``` 不要因为“事���重要”就保留整段；要保留最能让 change 成立的具体表演、反应、动作或揭示。理解与情绪允许时晚进早出，同时保证台词、动作和技术边界完整。 下面的 `scripts/...` 均相对于本技能目录。若执行器从仓库根目录启动，请给脚本路径加上本技能的绝对目录。脚本不从其他技能目录读取文件；外部输入仅限命令显式传入的视频、参数与 `work_dir` 产物。 ## 4. 运行命令 ```bash python3 scripts/cut.py <video> --work-dir <work_dir> \ [--target-duration 10m] [--clip-padding 0] [--allow-overlap] ``` ## 5. 输出契约 - `clip_plan_validated.json`：标准化片段，包含 `clip_id`、`source_s...