catimation-subagents

name

catimation-subagents

description

Look at images and videos WITHOUT burning the main context, and delegate batch work. Trigger when more than one image/frame/board needs looking at, when a contact sheet or reference set must be judged, or when several independent jobs could run side by side (多图分析 / 批量看图 / 分头去做 / 并行 / 委派 / 子代理). Media analysis lands as a `.vision.json` + `.vision.md` sidecar next to the file, so the next session reads text instead of re-opening pixels.

看图不烧上下文 · 委派与旁挂

一张图进主上下文的代价远高于它携带的信息。 九宫格、参考图组、一板卡片的产物—— 挨个 view_image 会把主上下文塞满,后面所有推理都在一个被稀释的窗口里进行。

解决办法不是「少看几张」(那是在用信息换预算),而是让别人去看,把结论以文本带回来, 并且把结论落在图片旁边,下次直接读文本。

硬上限:一次 5 张

主 agent 直接 view_image 的上限是 5 张。 第 6 张起一律走下面两条路 —— 并发 MCP 理解或子代理,拿文本回来,不再往主上下文里塞像素。

这个数不是拍脑袋:五张之内还看得清彼此关系(参考图组、一组分镜的头几格),再多就只是 在稀释后面每一步推理可用的窗口。

例外(这些本来就不该看):

• 自己刚生成的产物不看。 用户已经在聊天里看着它了,再 view_image 一遍纯属浪费。 需要判断质量时走下面的路,拿文字结论。
• 宫格图(contact sheet)算一张。它本来就是为「一张看完整段」拼的,别再拆开逐格看。

别在 view_image 前面加压缩(实测,2026-08-08)

view_image 已经自己压过了,而且本 app 把原图那条路关死了。 codex 侧「一律缩图」 现在是无条件的内建行为(resize_all_images),本 app 又额外开了 unified_image_budget ——统一按 6000 像素 / 10000 patch 预处理,并把 detail 控件整个藏掉,所以模型连 「传 detail:"original" 要原图」这个动作都做不出来。结论:在 view_image 之前再跑 一遍 ffmpeg 压到 2K,是多一次工具往返去重复它已经做完的事,只会更慢。

那 view_image 贵在哪?贵在两件压缩解决不了的事:

1. 每次都是一次独立往返。 模型发出调用后停下来等,五张就是五次停顿。
2. 图会留在对话历史里,之后每一轮都重放。 这才是复利成本 —— 第 10 轮时你还在为 第 2 轮看的那张图付钱。

所以省时间的正确杠杆是别让图进历史:只要问题是「这张图里有什么 / 是不是同一个人 / 质量过不过关」,就走下面的路 A(understand_document 回文本),而不是先压缩再 view_image。 压缩省的是像素,而像素本来就不是瓶颈。

唯一值得做代理图的场景:同一张巨图要反复看。 一张 6000×6000 的设定图要在多轮里 翻来覆去核对时,用 ffmpeg-win 生成一次 2K 代理图存在原图旁边,之后都看代理图 —— 省的是每次重新解码那 14MB 的本地开销,不是模型那一侧。出图 / 出视频一律用原图, 代理图只用于「看」。看一次就完的图不值得做代理,那一次 ffmpeg 就把省下的时间花掉了。

两条路,按「看完还要不要干活」选

路 A(默认):MCP 理解工具并发

超过 5 张、或看一眼就够只要一个结论时走这条。 图不进主上下文,回来的是中文文本。

素材	工具	说明
图片(png/jpg/webp/gif/avif)	understand_document	⚠️ 名字带 document,但它就是看图那条路 —— 图片 mime 在它的白名单里。别被名字骗过去
多张图一起看	同上 + file_urls / file_paths	见下方「跨图比较」——问题只要牵涉一张以上,就必须一次传完
视频	understand_video	只看画面,听不见声音——见下方「千问没有音频通道」。fps 可调抽帧密度(0.1–10,默认 2):快动作调高,静态长片调低省 token
音频 / 配音 / BGM	没有工具	千问这条线不收音频,见下方
画布上的视频	understand_canvas_video	不用先找路径
PDF	understand_document	直接传 .pdf,上游原生解析里面的文字和图片。别自己先渲成图(150MB / 500 页以内)

跨图比较:一次传完,不要拆成多次

file_urls(公网 URL)/ file_paths(本机路径)可以在同一次调用里追加更多图,两者能混用。

这不是省调用次数的问题,是能不能做到的问题。 模型把同一次请求里的多张图当成一组来看,所以才答得了「这两张里是同一个人吗」「这版和上版差在哪」「这角色跨镜一致吗」。拆成多次调用,每次它只看得见一张,彼此之间的对比无从谈起 —— 你会得到两段各说各话的描述,然后自己去猜。

• 顺序即身份:file_url 是第 1 张,file_urls 按序往后排。提问里写「第二张」,指的就是 file_urls 的第一项。
• 一张都不会被悄悄丢掉:任何一张中转失败,整条调用报错。少一张会让后面所有序号前移,而模型察觉不到。
• 上限 2048 张(公网 URL),真到那个量级应该先自己聚合。

千问没有音频通道

understand_video 是抽帧看画面,音轨从头到尾没被读过。它能认出烧进画面的字幕, 但听不见台词、音乐、音效和语气。所以:

• 「这段台词说了什么」——只有字幕在画面上时才答得了。
• 永远不要说「我听到……」。 需要靠听才能回答的问题,就直说「画面里没有可读字幕, 这个工具听不了声音」。编一段听起来合理的对白,比说不知道糟得多。
• 别把音频包成 MP4(配波形图或占位画面)再传进来。 模型只会去描述那张波形图, 然后开始编内容 —— 一个看起来有答案、实则全是杜撰的回复。

这不是我们的限制,是模型的:qwen3.7 / qwen3.8 的输入模态是文本 + 图片 + 视频, 音频输入只存在于 qwen3.5-omni 那条线,而理解工具没有路由到它。要处理语音得走转写, 这里没有那个能力。

三件事让这条路便宜:

1. 返回文本,不返回像素。 主上下文只涨一段话。
2. 同一轮可以并发发多个调用。 九张图就是九个 understand_document,一起发出去。 这不是子代理,没有 agents.max_threads 的限制。
3. 默认 qwen3.7-plus(便宜)。硬骨头才传 model="max";失败时渲染层会自动回退一次。

问题要问具体。 question 决定这次调用值不值:

❌ "这张图怎么样"
✅ "这张图里的人物:发型、上衣款式与颜色、下装、鞋、随身道具各是什么?
    有没有多指/断肢/脸部崩坏/文字乱码?背景里有几个人在动?"

问得含糊,拿回来的就是一段没法用的观感;问得具体,拿回来的直接能写进锚点或质检结论。

路 B:子代理

看完还要接着干活时才用这条 —— 需要独立的工具权限和推理预算,而不只是一个答案。 典型:「把这九张分镜逐张核对锚点,不符的直接改提示词并重生成」。

• 上限 8 路并发(agents.max_threads=8),深度 1(子代理不能再开子代理)。
• 理解类的重活可以把子代理钉到 qwen:modelProvider="qwen",model="qwen3.7-max-dashscope" (详见 catimation-understand 的 Path B;未配 Miau 令牌时该 provider 不可用)。
• 交接要写全。 子代理看不到你的对话历史。派活时必须带上:要看哪个文件的绝对路径、 判据是什么(锚点原文 / 质检四项 / 具体要找的穿帮)、产物写到哪、以什么格式回话。 少一样,它就得靠猜,你拿回来的东西没法直接用。
• 别为了拆而拆。 一张图、一个问题,用路 A;子代理的启动成本比一次 qwen 调用高得多。

旁挂:结论落在图片旁边

不管走哪条路,分析结果都写成两份旁挂文件,和图同目录、同名前缀:

assets/video/S01_station_wide.png
assets/video/S01_station_wide.png.vision.json    ← 给 agent 读
assets/video/S01_station_wide.png.vision.md      ← 给人读

这不是留档癖。它换来三件事:下次不用重看(省一次调用和一次上下文)、跨会话可复用 (明天接着做的人直接读)、可 diff(改了参考图,旧结论一眼看出过期)。

.vision.json 字段

{
  "source": "assets/video/S01_station_wide.png",
  "analyzedAt": "2026-08-03T10:12:00Z",
  "by": "understand_document/qwen3.7-plus",
  "question": "本次问的问题原文",
  "subjects": [
    { "role": "主角", "face": "…", "build": "…", "outfit": "…", "markers": "…" }
  ],
  "composition": "景别 / 机位 / 前中后景",
  "lighting": "主光方向 / 色温 / 软硬",
  "palette": ["#…", "#…"]
    
   
   

用不到的字段直接省掉,不要留空占位 —— 空字段会让下一个读它的人以为「看过了没问题」。 subjects 只在画面里有人时才写;issues 为空数组表示看过且没发现问题,与「没看」不同。

.vision.md

同一份内容的人读版:一段话讲清这张图是什么、一个列表列出问题、最后一行给 verdict。 给人看的东西不要塞 JSON。

复用规则

动手看之前先查旁挂文件:存在、且 analyzedAt 晚于图片的 mtime → 直接读它,不重看。 图比它新(重生成过)→ 旧结论作废,重看并覆盖。

常见错误

错误	纠正
挨个 view_image 九宫格里的每一格	宫格图本来就是为「一张看完整段」拼的,看那一张(算 1 张);要逐格判就走路 A 并发
十几张卡的产物挨张 view_image	超过 5 张就走路 A;主上下文只涨十几段文本,而不是十几张图
用 view_image 开 MP4	开不了。先用 ffmpeg-win 抽帧拼宫格,或直接 understand_video
看图前先用 ffmpeg 压一遍「省 token」	view_image 自己就缩到 2048×768 了,再压一遍纯属多一次往返。要省就别让图进历史 —— 走路 A
为了省事把代理图也拿去出图	代理图只用于「看」。出图 / 出视频一律用原图,拿 2K 代理去生成等于自己先降一档画质
因为工具名叫 document 就不用它看图	它就是看图的路,图片 mime 在白名单里
为了省预算只看代表性一张、其余靠猜	那是用信息换预算。走路 A,九张都看,主上下文只涨九段话
派子代理却不给绝对路径和判据	它看不到你的历史,交接不全等于让它猜
看完不落盘	下次(或下个人)得重看一遍,那次调用是白花的
旁挂文件留一堆空字段	空字段读起来像「看过没问题」,比没有更糟