# Crab AI 视频剪辑功能对接调研

日期：2026-09-06  
目标：判断视频剪辑功能应如何作为独立工具接入 Crab AI，并选择适合餐厅短视频模板的开源技术路线。

## 一、直接结论

1. **视频能力应归 Crab AI 调度，不应继续做成 Hera 内部的孤立功能。** Crab AI 负责理解用户意图、读取店铺/品牌/素材上下文、选择模板、发起任务和返回结果；真正的视频分析与渲染放在独立的 `Video Tool Service`。
2. **第一版不要做 AE，也不要做通用视频编辑器。** 只完成一个可反复使用的餐厅快剪闭环：上传 8–12 条素材 → 选择一个固定模板/BGM → 自动卡点和替换素材 → 低清预览 → 用户确认 → 高清导出。
3. **推荐首版底座：自有模板 JSON + FFmpeg；节拍分析使用 librosa。** 这条路线依赖少、资源相对可控，也最容易封装成 Crab AI 的异步工具。
4. **如果团队必须要“设计人员可视化制作模板，再由 API 批量渲染”，优先做 OpenShot 小型验证。** OpenShot Desktop 与 Cloud API 使用同一项目格式，可在桌面做模板、在服务端替换素材并导出；但 Cloud API 是商业授权，且官方建议每个 worker 配置 8GB、最好 16GB 内存，并按单任务排队运行。
5. **Remotion 适合作为第二阶段动效层，不建议未经压测直接成为整个剪辑后端。** 它的 React 组件生态、文字动效和预览体验最好，但服务端渲染会运行浏览器/渲染进程，并且商用自动化产品需核对授权成本。
6. **Natron 虽然最像 AE/Nuke，但不适合作为餐厅快剪主引擎。** 它适合节点合成、抠像、复杂特效和渲染农场；普通的裁切、卡点、转场、推拉运镜交给 FFmpeg/MLT 更简单。

## 二、目前能确认与不能确认的 Crab AI 状态

### 已确认

- 先前产品截图中可见 `Assets`、`Video`、`AI Brain`、`AI Command` 等模块，产品结构上具备把视频做成 Agent 工具的合理入口。
- Crab AI 更适合作为统一命令入口，而不是再增加一个独立视频 UI。
- 当前工作区中存在 Crab AI 的竞品研究站点和产品规划材料，但**没有发现 Ethan 的 Crab AI 主代码仓库或实际工具协议代码**。

### 尚未确认

- Crab AI 当前使用哪种 Agent/tool calling 协议。
- 是否已经有文件上传、素材库 ID、任务队列、Webhook、对象存储和权限隔离。
- `Video` 菜单当前是可用功能、占位页面，还是另一套服务。
- Hera 已完成的第一版代码位于哪里、哪些部分可以迁移。
- “CheckCut” 的准确产品名称和链接。公开检索没有找到能够与描述唯一对应的产品，不能把它作为已验证参考。

因此，现在可以确定目标架构，但不能声称“Crab AI 已经可以直接接入”。Ethan 需要先提供仓库/API 文档或做一次接口走查。

## 三、推荐架构

```text
用户 / Crab AI 对话
        │
        ▼
Crab AI Agent
  - 理解目标
  - 读取 store / brand / assets
  - 选择模板
  - 请求用户确认关键参数
        │ tool call
        ▼
Video Tool API
  - 输入校验与权限校验
  - 创建异步 job
  - 模板参数展开
        │
        ├── 音频分析：librosa → BPM / beat timestamps
        ├── 素材分析：ffprobe → 时长 / 尺寸 / fps / 音轨
        ├── 可选 AI：镜头分类、质量评分、菜品标签
        ▼
Job Queue → Render Worker
  - FFmpeg / MLT
  - 可选 Remotion 动效片段
        │
        ▼
对象存储
  - preview.mp4
  - final.mp4
  - manifest.json
        │ webhook / polling
        ▼
Crab AI 返回预览、状态、错误或下载链接
```

关键原则：Agent 请求不能一直等待视频渲染。工具调用只负责创建任务并立即返回 `jobId`；Crab AI 之后通过状态查询或 Webhook 获取结果。

### 动效台与自动叠加：推荐的判断链路

这里不需要让 AI 生成整条视频，也不需要让大模型逐帧输出坐标。更稳的实现是把“剪辑”“动效选择”“空间定位”“最终合成”拆开：

1. 设计人员先制作并审核透明背景的动效组件；每个组件同时保存结构化元数据，例如持续时间、允许出现的候选区域、尺寸范围、是否跟随主体、能否遮挡人物/菜品、进出场规则。
2. 对剪好的每个镜头检测人脸、人物、主要物体、字幕、Logo 和画面安全区，生成一张“不可遮挡区域图”。
3. 对左上、右上、顶部中央、下三分之一等有限候选位置打分，优先选择遮挡最少、边距足够、连续镜头中位置最稳定的区域。普通贴纸和文字包装不需要大模型。
4. 如果动效需要指向或跟随人物、菜品，检测器只负责找到目标框，跟踪器负责在后续帧维持同一目标 ID；坐标经过平滑后再交给渲染器。NVIDIA DeepStream 的 tracker 可提供跨帧目标 ID 和跟踪框。
5. 只有“这一段发生了什么、该配哪个动效”这类语义判断，才抽取少量关键帧或联系表交给视觉模型。模型返回动效类别、主体和置信度，不直接控制逐帧位置。
6. 最后由 FFmpeg/Remotion 按已确定的时间、锚点和轨迹把透明动效叠到主视频上。

按复杂度可分三类：全屏边框、光效和转场只需绑定镜头边界；角标和字幕只需安全区评分；箭头、标签等跟随动效才需要检测与跟踪。这样绝大多数任务都可以本地确定，只有低置信度语义场景才调用云端模型。

### GPT 与成本边界

- GPT-6 Astra、GPT-5.6 Sol 和 GPT-5.6 Luna 当前都支持图片输入，但不支持原生视频输入，因此必须先抽取关键帧，不能把整条视频直接交给模型逐帧分析。
- GPT-6 Astra 官方标准价为每百万输入 token 10 美元、输出 token 50 美元；不适合成为每条视频的默认判断器。
- 推荐生产链路先用本地规则、检测和跟踪；再用成本较低的视觉模型分析 6–12 张关键帧，并只在低置信度时升级模型。GPT-6 更适合用于新模板设计、离线审核或疑难案例。
- 实际单条成本必须用真实素材做 token 与运行时压测。模型调用成本之外，还要分别核算解码、检测/跟踪、预览渲染、高清渲染和失败重试，不能只用 API 单价推算总成本。

## 四、Crab AI 最小工具协议

建议只暴露四个工具，而不是让 Agent 直接拼 FFmpeg 命令。

### 1. `list_video_templates`

输入：`storeId`、用途、比例、预计时长。  
输出：允许使用的模板、素材槽位要求、BGM 授权状态、预计成本。

### 2. `create_video_job`

```json
{
  "storeId": "store_123",
  "templateId": "food-fastcut-v1",
  "assetIds": ["asset_1", "asset_2", "asset_3"],
  "musicId": "music_licensed_07",
  "format": {"width": 1080, "height": 1920, "fps": 30},
  "renderMode": "preview",
  "idempotencyKey": "crab-command-id"
}
```

立即返回：

```json
{
  "jobId": "video_job_456",
  "status": "queued",
  "estimatedClass": "short_vertical_preview"
}
```

### 3. `get_video_job`

状态必须区分：`queued`、`analyzing`、`rendering`、`needs_input`、`preview_ready`、`completed`、`failed`、`cancelled`。

失败结果不能只返回“生成失败”，必须带结构化错误，例如：

- `ASSET_TOO_SHORT`
- `UNSUPPORTED_CODEC`
- `MISSING_LICENSED_MUSIC`
- `INSUFFICIENT_SLOTS`
- `RENDER_TIMEOUT`
- `WORKER_OUT_OF_MEMORY`

### 4. `approve_video_render`

预览确认后才发起高清渲染。第一版禁止自动发布社媒；输出进入 `Review`，由人确认。

## 五、候选方案比较

| 方案 | 模板表达 | 调用方式 | 资源与扩展 | 适合度 | 结论 |
|---|---|---|---|---|---|
| FFmpeg + 自有 JSON | 自定义槽位、时间、转场、运镜 | CLI，容易封装 REST | 最可控；CPU 编解码为主；可水平扩展 | 很高 | **首版推荐** |
| MLT / `melt` | MLT XML，多轨、filter、transition | CLI / XML | 比 AE 类轻；语法较晦涩 | 高 | 可作为 FFmpeg 上层时间线备选 |
| OpenShot Desktop + Cloud API | 桌面工程 JSON、关键帧、图层 | 原生 REST、队列、Webhook | 官方建议 8GB RAM、16GB 更佳；单 worker 一次一单；横向扩容 | 高 | **适合做可视化模板 PoC**，但需商业授权 |
| Remotion | React/TypeScript 组件 | Node API / CLI / Lambda | 动效强、生态大；浏览器渲染和许可成本需压测 | 中高 | 第二阶段动效层 |
| Revideo | TypeScript 场景和变量 | CLI `/render` 或 API | 官方称单渲染建议至少 8–10GB RAM；支持分片并行 | 中 | MIT 备选，但首版偏重 |
| Editly | JSON/JSON5 | Node API / CLI / Docker | 使用方便，但 headless-gl 安装、内存和长期问题较多 | 中低 | 只借鉴 schema，不作为核心依赖 |
| Natron | `.ntp` 节点合成工程 | `NatronRenderer` CLI / Python | 适合复杂合成；部署、插件、字体、缓存和渲染资源更重 | 低 | 只用于少数复杂特效 |
| OpenTimelineIO | 剪辑决策/轨道交换格式 | Python/C++ API | 不渲染、不内嵌媒体 | 辅助 | 后期做 Premiere/Resolve 交付时使用 |
| OpenCut / Olive | 通用编辑器 | 尚不稳定或重写中 | 产品范围过大、稳定性风险高 | 低 | 不作为生产依赖 |

## 六、为什么不把“类似 AE”当主路线

AE/Natron 类系统解决的是复杂合成，而餐厅快剪第一版主要需要：

- 固定节拍上的裁切；
- 素材统一为 9:16、30fps；
- 轻量推拉、平移、模糊和闪白；
- 文字、Logo 与 BGM 混音；
- 批量稳定导出。

FFmpeg 官方 `xfade` 已提供 fade、wipe、slide、circle、pixelize、zoom 等多种转场并允许自定义表达式。音乐节拍可以由 librosa 输出时间戳。只有需要粒子、复杂蒙版、三维摄像机或高级抠像时，才值得调用 Remotion/Natron 生成一段透明动效，再叠加到主时间线。

## 七、资源与并发控制

不能先假设某个方案“省资源”；必须使用同一批素材做基准测试。建议固定三个样本：

- A：15 秒、8 个 1080p 素材、基础卡点转场；
- B：30 秒、15 个 1080p 素材、字幕、Logo、BGM；
- C：30 秒、混合 4K/1080p、复杂推拉和模糊转场。

每种引擎记录：

- 冷启动时间；
- 总渲染时间和 `render_time / video_duration`；
- 峰值 CPU、RSS 内存、GPU/显存；
- 临时磁盘峰值；
- 失败率与错误类型；
- 1、2、4 个并发任务时的吞吐量；
- 预览与高清的成本；
- 同一模板连续渲染 20 次是否稳定。

首版运行规则建议：

- 预览：540×960、24fps、低码率；
- 高清：用户批准后才渲染 1080×1920、30fps；
- 每个 worker 默认只跑 1 个任务；
- 通过队列扩容 worker，不在 Agent Web 服务进程里渲染；
- 设置 CPU、内存、磁盘和最长执行时间限制；
- 输入素材先转为统一代理文件，避免每次重复解码 4K 原片；
- 缓存 beat map、素材 metadata 和模板编译结果；
- 输出和临时文件设置生命周期，完成后自动清理。

## 八、第一版验收标准

第一版只验收 `food-fastcut-v1` 一个模板：

1. 三家不同餐厅、每家至少一组真实素材都能生成。
2. Crab AI 能创建任务、查进度、收到预览、发起高清导出。
3. 不需要开发人员逐镜头改代码。
4. 缺素材、素材过短、无授权音乐、编码异常时有明确提示。
5. 同一输入与模板可以重复得到一致结果。
6. 预览未经确认不会进入高清渲染，也不会自动发布。
7. 记录每次任务的模板版本、素材 ID、音乐许可证、渲染版本和资源消耗。

## 九、需要 Ethan 回答的 10 个问题

1. Crab AI 主仓库和当前部署环境在哪里？
2. Agent 使用什么 tool calling / MCP / function calling 协议？
3. 现有工具是同步还是异步？有没有 `jobId + polling/webhook` 模式？
4. `Assets` 中的文件是否已经有稳定的对象存储 URL 和权限签名？
5. `Video` 页面当前完成到什么程度？是否只有 UI？
6. 是否已有队列、worker、重试、超时和取消机制？
7. 多客户/多门店的数据权限如何隔离？
8. Crab AI 是否能展示视频预览并接收“确认高清导出”动作？
9. Hera 第一版代码、模板和测试素材在哪里？哪些要迁移，哪些应废弃？
10. “CheckCut”的准确链接是什么，Crab AI 之前具体以什么方式嵌入或调用它？

## 十、需要 Gary 定义的范围

Gary 不需要先决定技术栈，只需给出以下产品答案：

- 第一位真实用户是谁：内部运营人员、Agency 员工，还是餐厅老板？
- 第一类视频是什么：菜品快剪、口播切片、活动广告，还是长视频转短视频？
- 用户提供什么：原始素材、照片、文案、BGM，还是只给一句话？
- 第一个模板的目标时长、比例、发布平台和参考样片是什么？
- 是否必须卡音乐节拍？是否需要保留原声/配音？
- 什么结果算成功：节省制作时间、一次通过率、模板复用率，还是发布后的线索？

在这些问题没有确定前，不应开发通用模板市场、完整时间线 UI、AI 自动选题、自动发布或 AE 级合成器。

## 十一、建议会议结论

建议会议只做三个决定：

1. 定死 `food-fastcut-v1` 的输入、输出和参考视频；
2. Ethan 在 Crab AI 提供 4 个工具接口和素材/任务能力；
3. 视频开发者用 FFmpeg JSON 路线完成独立服务，并同时用 OpenShot 做一个不超过两天的可视化模板 PoC，拿实际资源数据比较后再决定是否引入。

## 主要资料

- [FFmpeg xfade 官方文档](https://ffmpeg.org/ffmpeg-filters.html#xfade)
- [librosa beat tracker 官方文档](https://librosa.org/doc/main/api/generated/librosa.beat.beat_track.html)
- [MLT melt 命令行文档](https://www.mltframework.org/docs/melt/)
- [OpenShot Cloud API 总览](https://cloud.openshot.org/doc/)
- [OpenShot Cloud API 架构、资源与价格](https://cloud.openshot.org/doc/introduction.html)
- [OpenShot Cloud API 项目与导出接口](https://cloud.openshot.org/doc/api_endpoints.html)
- [NVIDIA DeepStream 元数据与检测/跟踪框](https://docs.nvidia.com/metropolis/deepstream/7.1/text/DS_plugin_metadata.html)
- [NVIDIA DeepStream 多目标跟踪器](https://docs.nvidia.com/metropolis/deepstream/dev-guide/text/DS_plugin_gst-nvtracker.html)
- [OpenAI GPT-6 Astra 模型与价格](https://developers.openai.com/api/docs/models/gpt-6-astra)
- [OpenAI GPT-5.6 Sol 模型与价格](https://developers.openai.com/api/docs/models/gpt-5.6-sol)
- [OpenAI GPT-5.6 Luna 模型与价格](https://developers.openai.com/api/docs/models/gpt-5.6-luna)
- [OpenAI 图片输入 token 计算器](https://developers.openai.com/api/docs/guides/image-cost-calculator)
- [Remotion GitHub](https://github.com/remotion-dev/remotion)
- [Remotion 当前授权与定价](https://www.remotion.dev/docs/license/pricing)
- [Revideo GitHub](https://github.com/redotvideo/revideo)
- [Revideo 生产渲染资源说明](https://docs.re.video/rendering-in-production)
- [Revideo CLI Render Endpoint](https://docs.re.video/render-endpoint/)
- [Editly GitHub](https://github.com/mifi/editly)
- [Natron 命令行渲染文档](https://natron.readthedocs.io/en/v2.3.15/devel/natronexecution.html)
- [OpenTimelineIO 官方说明](https://opentimelineio.readthedocs.io/en/latest/)
- [Auto-Editor GitHub](https://github.com/WyattBlue/auto-editor)