一次图片管线改造:缩放时机从“存进来的时候”改到“路由选定模型之后”,同时把缩了多少告诉模型,并给它一把按原图坐标取局部的放大镜。

1. 一刀切压缩的问题:它不知道图会发给谁⌗

多模型 agent 系统里,一张图的生命周期大概是这样:用户贴进来,或者某个工具(截图、读文件、渲染预览)吐出来,存进历史;之后每一轮请求都把它重新带上,发给当时被路由选中的那个模型。

问题在于:“当时”是谁,存图的那一刻并不知道。主力模型可能一会儿撞上限流被 fallback 到另一家,线程可能中途切到便宜的小模型,过两天又切回来。可是传统做法是在入口处做一次压缩——定一个“安全”的尺寸,存一份缩好的副本,以后谁来都发这一份。

MaxClaw 之前也是这么做的。旧的 image-store.ts 在规范化送模副本时,按一个固定预算缩放:

// 旧代码(已删除)
const MODEL_PATCH_GRID = 32
const MODEL_PATCH_BUDGET = 28000   // 某家 32px patch 硬限 30000 减余量

体积超 3.5 MiB 时,还有一条“几何阶梯”:先降质量(q85 → q75 → q65),不够再把尺寸乘 0.85 / 0.70 / 0.55 / 0.40。缩完的这份字节被冻结进库,跨回合原样回放。

这个预算是按最宽松那一家的接口硬上限定的。它对其他模型同时犯了两种错:

情况旧做法的结果
图比接收模型能看清的大得多照样发过去,由对方服务端静默缩小,模型不知道自己看到的是缩略图
图超过接收模型的接口硬限请求直接 400
图被几何阶梯缩过冻结副本永远是小图,换个能看清大图的模型也拿不回细节

拿一张 1280×29658 的长截图(约 38 MP)按旧逻辑复算:patch 预算把它缩到 1104×25595 存下。Claude 系的接口单边硬限是 8000 px——这份副本发过去的结局是 400。为了补这类洞,Anthropic provider 里还长出过一个专门的旁路:一次请求超过 20 张图时,把每张图单边压到 2000。一条规则一个补丁,补丁还只认一家。

根子在于:缩多小,是“图 × 接收者”的函数,不是“图”自己的属性。 存储那一刻只有前一半参数。

2. 两个数:模型“能看清”多大⌗

这次改动先给每个 provider 配置加了两个可选字段(src/shared/provider-fields.ts):

字段含义
imageMaxLongEdge这个模型能看清的长边上限(px)
imageMaxPixels这个模型能看清的总像素上限(宽×高)

关键词是“能看清”,不是“接口收得下”。厂商文档里这两件事通常是两层:接口校验上限决定请求会不会被拒,模型的原生分辨率决定它实际看到多少——超过后者但没超过前者的图,会在服务端被悄悄缩小。拿接口上限当预算,等于把一张注定被缩的图完整地运过去,还让模型对缩放一无所知。

docs/image-limits.md 记录了每个启用的视觉模型取什么值、出处是哪份官方文档(只采信官方文档,推断的标“推断”):

模型家族长边总像素依据
Claude 5.x 系25763,750,656高分辨率档:长边 2576 且 ≤ 4784 visual token,每 token 28×28 px
某 GPT-6 系模型(默认 detail)—30,000,00032×32 patch、≤ 30000 patch,取整留余量
DeepSeek V4.1 Flash—1,690,000总像素缩到约 1300×1300 量级
LongCat 2.551205,242,880官方没给有效分辨率,填接口接收上限
一个 Qwen 基座微调模型—2,621,440取基座默认 max_pixels(推断)
某官方没给任何尺寸规则的模型——不缩放

两个字段都可以缺。只限面积的模型(DeepSeek)对长图很宽容,只限长边的模型对方图宽容,两个都有的模型两项同时生效。都不填,就完全不缩——宁可不动,也不拍脑袋编一个数。

值放在 src/storage/provider-image-limits.ts,由一个数据迁移写进库里的 provider 配置。这里有个小插曲写在第三个提交里:分支内迁移号在落地时会被改号,测试按分支号 import 迁移文件,落地后就 TS2307 了。于是表格挪到独立文件,迁移和测试都从那里读——数据不该依赖它被搬运时的门牌号。

3. 缩放挪到路由之后⌗

有了两个数,核心逻辑就很短。src/images/image-fit.ts 的 fitImageSize:

export function fitImageSize(size: ImageSize, limits: ImageFitLimits): ImageSize {
  let scale = 1
  if (limits.maxLongEdge !== undefined) scale = Math.min(scale, limits.maxLongEdge / Math.max(width, height))
  if (limits.maxPixels !== undefined)   scale = Math.min(scale, Math.sqrt(limits.maxPixels / (width * height)))
  if (scale >= 1) return size          // 没超:同一个对象原样返回
  // …取整,并处理极端长宽比下一条边被夹到 1px 的情况
}

等比缩到“同时满足两项的最大整数尺寸”。真正重要的是它在哪里被调用——src/llm/router.ts 的 messagesFor:

 历史(原图文件 + 冻结的送模副本,像素尺寸不缩)
        │
        ▼
  router 选候选 provider ──► 候选 A ──► fitMessagesToLimits(messages, A 的上限) ──► 发包
        │                       │ 失败 / fallback
        │                       ▼
        │                   候选 B ──► fitMessagesToLimits(messages, B 的上限) ──► 发包
        │
        └─ 候选没有视觉能力 ──► 走图片旁白(另一条路径,不在本文范围)

每个候选 provider 在发包前各自适配一次。fallback 链上前一家是 Claude、后一家是 DeepSeek,同一份历史会以两种尺寸分别出去。countInputTokens 也走同一个函数——算 token 时用的图和真正发出去的图是同一个尺寸,估算不会因为图片而偏离。

存储那一侧相应地“退化”了:loadModelImage 仍然负责规范化(EXIF 方向烘焙、alpha 铺白底、转 sRGB、输出 JPEG),但不再改像素尺寸。体积超限只走质量阶梯,档位加深到 q85 → q35;质量用尽还超就拒绝这张图,绝不用缩尺寸去凑。测试把这条写成了规格:

image-store.test.ts
  ✓ 超大像素图不缩尺寸(按模型缩放不在这里),落盘件保持原样
  ✓ 极端长宽比(1280×29658 长图)同样保持尺寸
  ✓ 体积预算:只降质量不缩尺寸——q85 超限时落到更低质量档
  ✓ 质量阶梯用尽仍超字节上限 → 抛错拒绝,不用缩尺寸去凑

Anthropic provider 里那个“>20 张图压到 2000”的旁路连同它的五个测试一起删掉了:2576 这个“能看清”的值本来就低于文档里多图请求的单边校验上限(当前 3000),专门的补丁不再有存在理由。

同一张 1280×29658 长图,新规则下各模型拿到的尺寸:

接收方规则送出
Claude 系长边 2576 起作用111×2576
DeepSeek面积 1.69 MP 起作用约 270×6257
没配上限的模型不缩1280×29658

一张 3840×2160 的 4K 截图则是:Claude 系 2576×1449,DeepSeek 约 1733×975。

4. 确定性:缩放不落库,但前缀逐字节稳定⌗

“每次出站现算”听起来和 prompt cache 冲突:如果每轮缩出来的字节不一样,请求前缀就变了,缓存全废。

设计上用三件事保住它:

  1. 缩放是纯函数。 同样的输入字节、同样的目标尺寸,经过同一条 sharp 管线输出同样的 JPEG q85。测试 shrinking is deterministic: same input, byte-identical output 直接比较两次结果的 JSON。
  2. 进程内 LRU 缓存。 key 是 sha256(源字节)|目标宽x高,按总字符数限 64 MiB。省的是 CPU,不是正确性。
  3. 冻结的是源,不是结果。 库里冻结的是规范化后、未缩尺寸的送模副本;按模型缩放的产物永不落库。

端到端的规格在 image-fit.wire.test.ts:真实 router + 真实 Anthropic codec,只 mock 掉 fetch,一条线程连发四轮,模型依次是“类 Claude → 只限面积的小模型 → 无上限模型 → 切回类 Claude”。断言是:

第 1 轮  长边 ≤ 2576,面积 ≤ 3,750,656,带缩小说明,说明里的送出尺寸 = 实际字节尺寸
第 2 轮  面积 ≤ 1,690,000,且高度比第 1 轮更大(只限面积的模型对长图更宽容)
第 3 轮  1280×29658 原样,不带任何缩小说明
第 4 轮  图片 base64 与第 1 轮逐字节相同

第 4 条是这套设计相对“存一份缩好的”最实在的优势:换模型不是单向的有损操作。切到小模型时历史图被缩小,切回来,大模型拿回的是它自己那一档的完整细节,而且和第一次发的字节一模一样,缓存照样命中。

还有一类历史包袱:改动之前存下的副本已经被旧规则缩过。处理方式是把它们当作“原图”参与新一轮适配——超过新上限就继续缩,没超过就原样发,但说明里写的是记录下的真实原始尺寸。测试 a history copy already shrunk by the old rules: refit, and the note names the true original 就是这条。

5. 告诉模型缩了多少⌗

缩图本身不难,难的是让模型知道它看到的不是原图。服务端静默缩放最伤人的地方在于坐标:模型看着 1449 像素高的图说“按钮在 y=800”,调用方拿去在 2160 像素高的原图上点,偏得离谱,而且谁都没报错。

所以每一张被缩小的图旁边都会有一行:

[图片已缩小:原图 1280×29658,送出 111×2576]
  • 用户消息里的图:紧跟在图后插一个文本块;
  • 工具结果里的图:追加到结果正文末尾;一个结果里有多张时写成 [第 2 张图片已缩小:…],只给真被缩的那张编号;
  • 没缩的图什么都不写——说明只在有信息量时出现,不给每张图都套一句废话。

“原图”尺寸要靠送模块自己携带:modelImageBlock() 构造图片块时把 origin 挂上去,并且按 EXIF 方向换算到呈现方向。手机拍的竖图在文件里可能是 4000×3000 加一个“旋转 90°”标记,模型看到的却是竖的;说明里写 4000×3000 就会把坐标系弄反。为此 alignAxes 还额外处理了“记录的原始尺寸在未旋转坐标系里、副本在旋转后坐标系里”的情况——测试里那条是 原图 3000×4000,送出 1500×2000。

这一行字的价值很具体:模型拿到比例,就能把自己看到的坐标乘回原图;更重要的是,它知道自己可能漏看了东西。

6. 放大镜:按原图坐标取一块⌗

光知道“看到的是 111×2576 的缩略”还不够——一张 1280 宽的长截图缩到 111 像素宽,正文基本是一条灰带。模型需要的是能按需看清某一块。

read_file 因此多了一个 region 参数:

{ "path": "/path/to/long.png", "region": { "x": 0, "y": 5152, "width": 1280, "height": 2576 } }

语义被测试钉得很死:

输入行为
区域在图内按原始分辨率裁出,坐标即原图坐标
部分越界夹到图内,返回实际裁出的矩形
整块在图外失败,错误信息带上整图尺寸,方便重试
比整张图还大就是整张图
对文本文件用 region拒绝
EXIF 旋转过的图坐标按呈现方向计算

JPEG 源裁出后用 q95 输出,其他格式输出 PNG,不在裁剪这一步叠加有损。不带 region 时,read_file 返回整图并附上 imageWidth / imageHeight,让模型一开始就知道原图有多大。

这里有一个很顺的组合:裁出来的块同样会经过 router 的适配。 模型如果贪心地要了一块比自己能看清的还大的区域,它会再次被缩小,旁边照样有那行说明——工具描述里直接写着“那就要更小的块”。放大镜和缩放规则不是两套机制,而是同一条出站路径上的两个用法。

按上限算一下读那张长图要几刀:

接收方不被缩小的最大整宽条带读完 29658 px 需要
Claude 系(2576 / 3.75 MP)1280×2576(3.30 MP)12 次
DeepSeek(1.69 MP)1280×132023 次

模型自己能算出这张表:它知道原图尺寸、知道自己的送出尺寸,region 又是原图坐标。这比任何“智能预切图”都简单,也不需要系统猜模型想看哪里。

7. 没做的事,和这样做的代价⌗

几处刻意留白,文档里都写明了:

  • 桌面截图工具的固定 1568 不动。 它自己缩图、自己换算坐标、自己用 region 放大,是一个闭环;对 Claude 系来说 1568 比能看清的小,细字会比必要的糊一点,这笔账记下了,没有顺手改。
  • 只限面积的模型遇到极端长宽比。 DeepSeek 只限总像素,一张长宽比超过约 10:1 的图适配后长边仍可能超过 4096,而一次带 ≥ 15 张图时那是它的单边上限。这是按文档数值推算的、没有真实请求触发过,所以没有为它预先加规则。
  • 没有数据的模型不缩放。 宁可把选择权留给对方服务端,也不编一个数。

代价也很明确:

代价量级
库里冻结的副本变大(不再缩像素)仍受 3.5 MiB 体积上限约束,只是靠降质量而不是缩尺寸
每次出站可能要做一次解码 + 缩放同字节同尺寸命中 64 MiB LRU;没配上限时连解码都省了(返回同一个数组),没超限的图原样返回同一个块
每个视觉模型要维护两个数新增模型时按其文档填写,来源写进配置修订说明

8. 小结⌗

这次改动的思路可以压成三句话:

  1. 尺寸是接收者的属性。 在路由决定之后、发包之前按那个模型能看清的上限适配,存储只做格式规范化,原图始终在。
  2. 缩了就要说。 每张被缩的图旁写明原尺寸和送出尺寸,模型才能换算坐标、才知道自己可能漏看。
  3. 给模型取细节的手段。 read_file 的 region 按原图坐标取块,取出的块再走同一条适配路径。

和“入口处压一刀”比,它多了一点出站计算,换来的是:换模型不再是有损的单行道,模型不再对自己看到的东西有误解,而“看不清”从一个静默的失败变成了一个模型可以自己处理的、有提示的状态。