# Catimation Subagents

> 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.

- Skill: `2799662352/catimation-subagents` (Agent Skill)
- Install (CLI): `npx skillmds@latest add 2799662352/catimation-subagents`
- Raw SKILL.md: https://api.skillmd.com/api/skills/2799662352/catimation-subagents/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: 2799662352 (https://skillmd.com/u/2799662352)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/2799662352/catimation-subagents

---


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

<!-- skill-budget: standard -->

**一张图进主上下文的代价远高于它携带的信息。** 九宫格、参考图组、一板卡片的产物——
挨个 `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` 字段

```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": ["#…", "#…"],
  "issues": ["左手六指", "背景文字乱码"],
  "verdict": "pass | needs-fix | reject",
  "notes": "自由文本补充"
}
```

用不到的字段直接省掉,**不要留空占位** —— 空字段会让下一个读它的人以为「看过了没问题」。
`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,九张都看,主上下文只涨九段话 |
| 派子代理却不给绝对路径和判据 | 它看不到你的历史,交接不全等于让它猜 |
| 看完不落盘 | 下次(或下个人)得重看一遍,那次调用是白花的 |
| 旁挂文件留一堆空字段 | 空字段读起来像「看过没问题」,比没有更糟 |