用途
grok-video-edit 用于需要生成式改动的镜头编辑：给物体重新着色、添加物理特效（烟雾、火焰、发光）、对场景重新风格化，或改变画面中的内容。若目标只是把已知素材（logo、文字、PNG／动画图形）合成到视频上，应改用 video-overlay 技能——它是确定性的，并且更便宜。
前置条件
需要在 .env 中提供 XAI_API_KEY。
核心原则：先裁剪目标区域
grok-edit full_video.mp4 即使带 --splice-into 也会把整段视频切块处理。不要发送整段视频。工作流是：
- 找到精确边界。在大致窗口内运行 detect，参数 --step 1 --cell-w 384，定位主体首帧与末帧的帧级精确位置，再按该边界裁剪，避免 Grok 重绘无关上下文。
uv run video-agent trim source.mp4 --start X --end Y -o segment.mp4
- 编辑该片段：
uv run video-agent grok-edit segment.mp4 --prompt "..." -o edited.mp4
- 混回原始音频（Grok 只输出视频，并会丢失约 0.2–0.3 秒帧）：
ffmpeg -i edited.mp4 -i segment.mp4 -map 0:v -map 1:a -c copy -shortest out.mp4
务必加 -shortest——否则音频会超过较短的视频轨，导致下游全部不同步。
- 最终用 filter_complex concat 拼接（会重新编码，避免关键帧冻结与漂移）：
ffmpeg -i a.mp4 -i b.mp4 \
-filter_complex "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]" \
-map "[v]" -map "[a]" -c:v h264_videotoolbox -b:v 8M -c:a aac -ar 44100 out.mp4
不要在 Grok 编辑过的片段之后使用 stream-copy 方式拼接——非关键帧接缝会造成画面冻结。
--splice-into 参数会自动完成切块、base64 上传、拼接与音频缝合，但仍只应在已裁剪好的区域上使用。
切块与接缝
代码中 GROK_MAX_SECONDS = 8.0：每个块独立编辑，Grok 会对每块重新构想场景。块越短，接缝与风格跳变越多，默认 8 秒，不要低于 3 秒。
切块应落在自然镜头切换处，而不是任意间隔；可用 detect 网格找剪切点，逐镜头单独裁剪。跨镜头切换的块会出现第二个镜头被重新风格化的问题。
块会被降采样到 720p／2Mbps（gRPC 4MB 限制）。AV1 源会自动处理（PyAV 解码 → h264 块）。
Grok 无论源帧率如何都按约 24fps 重新编码，输出比输入少几帧。对高帧率源（如 120fps），编辑片段会与周围片段不匹配，需在最终拼接时归一化帧率——在 filter_complex 中为每个输入加 fps=<原帧率>（如 [1:v]fps=120,setsar=1,...），否则接缝会卡顿或时长对不齐。绝不要把 Grok 片段 stream-copy 回更高帧率的片段。
带余波的特效
如果添加的特效留下比其来源动作更久的画面余波，它会在裁剪边界处仍在屏幕上。硬切回未编辑片段会让它在一帧内消失，形成生硬跳变。两种处理方式：
- 延长编辑区域以覆盖余波，使特效在 Grok 素材内自然结束。代价是更长的区域意味着 Grok 重绘更多帧（主体／角色漂移风险更高），所以只延到够用为止。
- 用短 xfade（约 0.25–0.4 秒）溶解接缝，让特效淡出而不是跳变。由于两侧是同一主体的近乎相同姿势，溶解看起来像特效消散，而不是转场。
在音频静音处可以随意 xfade。xfade 会因重叠缩短视频，从而让混入的音频不同步——但仅当语音跨越接缝时才如此。当特效落在静音段时，可以随意溶解，并用 -shortest 重新混入原始音频。可用 speech-segments（filler-removal 技能）查看哪些段落是静音。
角色与一致性漂移
Grok 无法在块之间保持角色一致性。系统约束常量（_GROK_CONSTRAINT）是通用的，应保持这样；把角色／主体描述放在用户提示词里，而不是约束里。
提示词要点
- 说清要改什么，而不是要保留什么——Grok 对正向指令的处理好于负向约束。
- 避免无关词语，如 "shockwave rings"、"portal effects"，除非确实想要，Grok 会字面添加它们。
- 颜色更改时，指明要替换的确切源颜色与确切目标颜色。
- 添加特效时，描述方向与物理规律，而不只是特效本身——从哪里产生、往哪个方向运动、如何结束（例如先上升再飘散、向外辐射、沉降）。Grok 会渲染你指定的运动，并为你未说明的部分自行发明运动。
并行处理独立编辑
如果视频需要多处独立的 Grok 编辑（例如两个不同时刻），可分别裁剪各自区域并同时在后台运行 grok-edit 调用——它们是相互独立的网络任务。等两者都完成后，再混音并组装。
音频
Grok 只输出视频。最终组装时始终从原始素材重建音频（用 -vn -c:a copy 提取，再混流）。不要依赖 PyAV 裁剪出的音频来保持同步。