Omni 媒体工具与模型访问

选择转换、裁剪、抽帧和模型理解工具，限制参数与额外调用。

这些策略工具属于 omni 实验分支。默认仅固定策略可调用，对模型隐藏；需要模型主动补证据时，再逐工具开启 modelAccess。

图像与视频

工具	参数与用途
omni_downsample_image	JPEG 降采样；maxDimension 默认 1568、quality 75；tokenBudget 支持 256/1024/2048 档位并按 28px patch 网格处理
omni_convert_image	转 JPEG/PNG/WebP；format 默认 jpeg，quality 90
omni_clip_image	按必填 x、y、width、height 裁剪 PNG；与模型直接使用的 zoom_image 区分
omni_caption_image	调用视觉模型输出 caption，可配置 prompt
omni_ocr_image	提取可见文字，language 默认自动，文本角色 ocr
omni_downscale_video	输出 MP4；maxHeight 480、fps 10、crf 28
omni_clip_video	截时间片段；startSec 默认 0、durationSec 默认到结尾、crf 23
omni_extract_keyframes	多 JPEG；maxFrames 8、sceneThreshold 0.2、maxDimension 768；支持 scene/uniform、时间范围与 frameTokenBudget
omni_understand_video_segments	分段重编码后并行理解，输出带时间范围的 summary；segmentSeconds 默认 30、范围 5–60，maxParallelSegments 8，maxSegmentBytes 10MiB

关键帧默认覆盖全片分桶，uniform 按时长调整采样率；少量帧只用于建立整体线索，不能证明帧间没有发生重要事件。caption、OCR 和分段理解包含模型调用，与本地转码成本不同。

音频

工具	参数与用途
omni_extract_audio	从视频抽音轨，format 默认 wav，sampleRateHz 16000，channels 1；也支持 MP3/M4A
omni_downsample_audio	输出 M4A，bitrateKbps 默认 64，sampleRateHz 16000，channels 1
omni_clip_audio	用 startMs、durationMs 截取，durationMs 最少 1000、默认到结尾；format 默认 m4a
omni_transcribe_audio	文本转写；chunkSeconds 180、maxInputBytes 10MiB；长音频分段并发 3，共享时间预算
omni_caption_audio	语义、音色、事件等描述，不是逐字转写；chunkSeconds 默认 180

转写按时间段拼接，单段失败会在文本中标记，不一定让整个结果失败；也会检测并截断重复退化。使用结果前检查缺失段和识别误差，不能只看调用成功状态。

工具设置与墙钟超时

工具级默认参数放在 omni.processing.policyTools 下：

{
  "omni": {
    "enabled": true,
    "processing": {
      "policyTools": {
        "omni_transcribe_audio": {
          "settings": {"maxInputBytes": 33554432, "chunkSeconds": 300},
          "runtime": {"timeoutMs": 1800000},
          "modelAccess": {
            "enabled": true,
            "defaultArguments": {"chunkSeconds": 180},
            "lockedArguments": {}
          }
        }
      }
    }
  }
}

这是扩大转写文件上限、延长超时并开放模型调用的示例，不是默认配置。runtime.timeoutMs 必须小于一小时 staging 清扫宽限窗，否则启动失败；长任务不能靠无限增大超时绕过清理边界。

模型可见参数

defaultArguments 为每次调用注入默认值，模型可覆盖；lockedArguments 从可见 schema 中移除并由运行环境注入，模型执意传入会被拒绝。同一键不能同时出现在两处。

parameterSchema 可选，只能收窄原 schema，不能添加原工具没有的属性。baseUrl、apiKeyEnv 等运维字段不会暴露给模型；相关工具的独立模型配置仍可能带来额外模型请求。

结果读取

成功调用会列出每个产物的绝对路径，模型可通过 read_file 读取结果。关键帧逐张作为独立产物入库；transcript、caption、ocr、summary 使用文本通道并保留对应 role，供后续策略与媒体记忆查询。

开放工具会在媒体理解指引中列出可用补证据方式；没有开放任何工具时，模型应明确证据不足，而不是声称已查看原始完整媒体。