Agentic Video Editing

核心基元优先的边界 (Primitive-First Boundary)

ScreenKite 让 agent 编辑保持简单：应用程序暴露确定的编辑基元 (primitives)，而 agent 负责处理计划、转录文本推理和编辑策略。

这样的边界划分很重要。ScreenKite 应该回答像“当前的布局是什么？”、“剪切这个范围”或“在 12.5s 到 17.0s 之间应用这个场景布局”等问题。而 agent 应该决定哪些节奏点 (beats) 比较关键、要在哪里进行剪辑、是否要插入视觉素材，以及何时停止迭代。

从事实状态开始 (Start With Facts)

使用这些读取出的数据作为你的基准：

• 将 getProjectState(scope: "summary") 视为获取时间、轨道和整体项目状态的轻量级索引
• 将 getProjectState(scope: "layout") 视为场景状态的事实来源 (source of truth)
• 使用 getProjectResources() 以确认哪些媒体实际存在
• 当说话时间点和词汇边界的剪辑很重要时，使用 exportTranscript(...)

如果转录文本中包含了英文产品名称、API 或其他专有名词，在创建视觉素材或字幕前请务必进行校对。一旦产品名称错误，这个错误将会蔓延至每一个下游素材中。

建议的工作循环 (Recommended Loop)

1. 在计划任何事之前，先读取 summary、layout 以及资源 (resources)。
2. 如果时间或旁白内容很重要，导出并审阅转录文本。
3. 先计划节奏点，再决定哪些范围需要剪辑、调整布局、添加字幕或视觉素材。
4. 在更改高宽比前运行 setCanvas(..., dryRun: true)；在进行较复杂的布局工作前，运行 setSceneLayout(..., dryRun: true)。
5. 使用 editTimeline、setSceneLayout 和 manageEffects 来应用改变。
6. 在每一批次处理后，通过 getProjectState(scope: "visual") 或输出的快照 (snapshots) 来进行验证。
7. 如果变更调用 (mutating call) 发生超时，重试前请先重新读取一次项目状态。

何时使用各种基元 (When to Use Each Primitive)

• editTimeline 用于剪切、修剪和清理词汇边界
• setSceneLayout 用于带有时间范围的场景布局变更，包含高级的布局 DSL
• manageEffects 用于字幕、缩放及其他特效处理
• 在外部渲染往返的工作流中，使用 vfxExportVideoSegment 搭配 vfxOverlayProcessedClip
• exportArtifact 用于交付文件、快照、SRT 以及范围输出

高级布局与 B-Roll (Advanced Layout and B-Roll)

在 ScreenKite 的视觉呈现中，屏幕录制依然是主角。高级布局与 B-roll 通常应为简短的辅助段落，而非全面覆盖画面的内容。

如果你打算渲染一个外部的视觉素材，并通过 <ScreenKite.Visual /> 来放置它，请遵守以下原则：

• 渲染素材时，请使其完全对齐目标的宽度、高度、fps 和帧时长
• 请将渲染出来的文件当成一个完整的画中画 (PiP frame) 来处理，而不是当作漂浮在空旷背景视频中的小卡片
• 视觉动画的设计应符合 入场 (entry) -> 稳定静止 (settled hold) -> 无内部退出效果 (no internal exit) 模式
• 将不同片段间的退场过渡效果直接交给 ScreenKite 的 magicMove 来处理

如果你将较短的高级布局时间区间，重新覆盖到前面较长的时间区间上，请确保把多余的部分清除并恢复为 pictureInPicture 模式。否则前面残留的高级布局片段，可能会在超出你预期的范围内继续播放。

安全护栏 (Guardrails)

• 绝对不要从单词中间进行剪辑。当说话时间的精确度很重要时，请务必使用转录文本提供的词汇边界。
• 在超时后要重试变更状态操作前，一定要再次读取项目状态。
• 在把自定义覆盖画面放进时间轴前，务必确认渲染输出的宽度、高度、fps 和帧时长与目标绝对吻合。
• 确保所有生成的文件内容都保存在 .skbundle 目录之外。
• 为自我验证的循环设置上限。当经历几回合后视觉验证如果依然失败，请立即停止，并转为直接检查布局设计或原始媒体。