用途
MGA Agent（Managed Manual Generation）用于把一段流程视频转换成带时间戳的有序操作手册。用户提供 .mp4 视频，平台采样视频帧、转写音频，并在一次处理中融合两者，返回可回溯到原始录像的步骤。
处理流程示意：
video ─► sample frames ─┐
├─► newton-fusion f1-0 ─► parse ─► steps + timestamps
whisper ASR ────┘
MGA V1 为零样本模式。mga 蓝图固定使用自己的模型（newton-fusion:1.0 和 whisper:large-v3），因此与 osm/red 不同，没有需要拟合的分类器，也不需要传递 artifacts 映射。一次运行即：上传 → 创建 bundle → 运行 → 下载。
主要能力
- 从视频中提取有序操作步骤，并为每个步骤附带时间戳。
- 同时利用画面与音频（语音旁白）信息，语音中的安全提示等内容会出现在输出中。
- 支持通过 prompt 控制覆盖范围（例如目标步骤数、每步字数上限、是否使用旁白）。
- 支持 max_frames、size、max_new_tokens、parser_compute_stats 等参数。
- 可通过日志与结果接口诊断运行状态。
使用方式
端点
Agents API 无版本前缀；files API 位于 /v0.5 下。
POST {endpoint}/v0.5/files upload the video
POST {endpoint}/agents/bundles create a bundle ← PLURAL
POST {endpoint}/agents/bundles/{bundle_id}/run start a run ← returns 202
GET {endpoint}/agents/instances/{agent_id}/logs the real log stream
GET {endpoint}/agents/instances/{agent_id}/results output refs
POST {endpoint}/agents/instances/{agent_id}/cancel stop a run
注意：POST /agents/bundle（单数）返回 404，部分旧客户端仍在使用。
两个关键值
- max_new_tokens：蓝图默认 16384，与模型的推理块共享。若在推理块内耗尽，会得到空手册但被报告为成功，需检查手册非空。
- prompt：省略时蓝图自带指令生效，会使手册步骤减半。切勿指定输出格式——解析器拥有模板，指定格式会返回零步骤。
需确认这两个值确实被蓝图接线（在 blueprint 的 values 中声明，并被某节点或连接器以 ${values.<key>} 引用）。未接线的值会返回 HTTP 201 并原样回显。
步骤 1 — 选择视频
- 时长约 5 分钟以内：更长视频会直接失败。
- 必须有音轨：AudioReaderNode → whisper → prompt.audio 是管线的一半。
- 准备参考步骤用于评分。
约 5 分钟上限不是上下文限制：max_frames: 16 时视频仅占 392 视觉 token，约为 F1-0 的 256K 窗口的 0.15%。
源分辨率影响不大——每帧都会缩放到 size × size（默认 224）。
更长视频需分块：
- 90 秒分块，15 秒重叠。
- 按关键帧切割，避免 ffmpeg -ss -c copy 回退到前一关键帧造成偏移。
- 从每个分块的实际起点计算，而非 i × stride。
- 每个分块一次运行，或用 source 数组一次运行（结果乱序且时间戳为分块局部，需加偏移）。
- 保守去重：仅当来自不同分块且时间跨度确实重叠时才合并。
步骤 2 — 上传视频
POST {endpoint}/v0.5/files # multipart/form-data, field name "file"
→ {"is_valid": true, "file_id": "clip.mp4", "file_uid": "fil_…"}
声明的 Content-Type 会按 MIME 允许列表校验，发送 video/mp4。运行负载中使用 file_id（文件名），而非 file_uid。
步骤 3 — 创建 bundle
无需 artifacts 映射——蓝图固定自己的模型。
POST {endpoint}/agents/bundles
{
"blueprint": "mga",
"name": "mga tire_i2JWkDyg26A mnt16384",
"values": {
"max_frames": 64,
"max_new_tokens": 16384,
"prompt": "Generate a concise, ordered list of every distinct step performed in this video, covering the procedure from the first action to the last. Include brief steps and steps that are repeated. Use up to 20 steps. Keep each step to at most 15 words. Use both what is shown and what is said."
}
}
→ 201 {"id": "bnd_…", "status": "ready", "is_canonical": false}
bundle 名称在创建时设定且不可更改（PATCH 和 PUT 均返回 405），建议在名称中编码所变化的参数值。
主要参数：
- max_frames：默认 16，全视频均匀采样。64 是 reader/预处理器批大小。无校验，16、512、1024、-1 均被接受为 ready。
- size：默认 224，每帧缩放为正方形。
- parser_compute_stats：默认 false，附加模板一致性统计。
- max_new_tokens：默认 16384，与推理块共享。
- prompt：默认使用蓝图自带指令；建议自行提供，省略会使手册减半。
关于 prompt：唯一硬性规则是说明要覆盖什么，绝不要说明如何格式化。ManualGenerationResultsParserNode 拥有输出模板，指定 markdown 标题或自定义步骤布局会让解析器返回零步骤且无错误。
适用场景
- 从维修视频生成维护手册。
- 从屏幕录制生成 SOP。
- 从装配片段生成作业指导。
- 任何需要将录像中的流程提取为书面步骤、且每步需绑定源视频时间范围的场景。
限制
- 视频时长超过约 5 分钟会失败，需先分块。
- 无音轨的视频会丢失语音信息。
- 输出可能为空（results: []），需显式检测并查看 /logs 中的 WARN。
- 生成内容确定但字节不确定（md5 不同），不要按哈希比对。
- 分块处理时结果乱序且时间戳为分块局部，需自行加偏移与去重。
- 平台侧失败（如 Newton generation event stream closed without a terminal event）应重试分块，而非进一步缩短。
不适用场景
- 需要对照已知流程验证任务是否正确：使用 tva（Task Verification）蓝图。
- 对片段提出单个问题、无状态：使用 atai-newton-fusion-model（/query）。
- 将传感器窗口分类为运行状态：使用 atai-operational-state-monitoring-agent。
- 视频长于约 5 分钟：先分块。