D19 多模态输入：粘贴截图、图片校验与照图改代码

今日目标

能把图片接进已有的消息结构，且不破坏纯文本路径的兼容性
能实现图片的来源解析与合法性校验，并给出人话级的失败提示
能在模型不支持图片时给出可用的降级路径

前十八天 mca 一直只靠文字工作。今天给它开一只眼睛。做完之后回到页面顶部把三条目标勾掉。

小白版讲解

让他看图纸，不只是听描述

带新人改一个界面，你有两种交代方式。

第一种是描述：「工具栏左边那个蓝色的主按钮，文案改一下，要带上保存的意思。」这句话得反复确认——哪个是主按钮？工具栏是顶上那条还是侧边那条？改成什么才算「带上保存的意思」？

第二种是把图纸拍在他桌上：「照这张改。」

前十八天我们对 mca 一直用的是第一种。它对「这个界面长什么样」的全部认知，来自你打的那几行字。而很多任务的信息本来就在图里：一张报错截图、一张设计稿、一张测试框架吐出来的对比图。你描述一遍，信息已经丢了一半，而且丢的那一半正是你没注意到的那一半。

今天要做的事，一句话就是让那张图直接进到对话里。听起来像是一个「加个字段」的活，但它会牵出四个真问题：消息结构要怎么扩才不会把前十八天的纯文本路径搞坏；一张图在终端里到底怎么「粘」进来；哪些图该在发出去之前就拦下；以及最要命的一条——你怎么知道对面那个模型到底看不看得见图。

最后这条不是一句反问。2026-09-07 我们用真实 key 在一个 OpenAI 兼容网关上实测：同一张纯红色的图发给四个模型，四个都正常返回、都没有报任何错误，其中一个把这张纯红图说成了蓝绿色。它不是拒绝，是编了一个答案。这一条实测结论会把今天后半篇的设计整个改写。

消息结构怎么扩：第一天就留好的那两种形态

翻回第一天那个冻结的协议文件，Message.content 的类型是这样写的：

TextText

ContentPart = { type: text, text }  或  { type: image, mediaType, base64 }
 
Message.content: string | ContentPart[]
                 纯文本用 string；多模态用数组（注释里写着「D19 才会用到数组形态」）

那行注释在仓库里躺了十八天。今天它兑现了：协议层今天一个字段都不用加。

这不是运气，是一条可以复用的判断：协议要为将来留形状，不为将来留字段。 第一天把 content 定成 string，今天就得改这个类型，而改它意味着审批门、截断、快照、压缩、会话日志全部要重新检查一遍；第一天急着把图片的字段定死（比如加一个 imageUrl?: string），今天又会发现形状不对——一条消息可能带好几张图，而且图文要能交替。

留形状的代价是从第一天起，每一处想把消息当字符串用的地方都得先过一遍 contentToText。十八天付了几十次这个小麻烦，今天一次性收回来——而且收回来的不只是「不用改类型」，下面还有两处白捡的好处。

真正要改的只有出口。mca 内部一直用 ContentPart 这套协议，而网关认的是它自己的报文形状。2026-09-07 实测跑通的形状是这样的：文字段是 type: "text"，图片段是 type: "image_url"，里面套一个 image_url.url，值是一条 data URL。

src/vision/wire.ts

export function toWireContent(
  content: string | ContentPart[]
): string | Array<Record<string, unknown>> {
  if (typeof content === 'string') return content
  // 没有图片的数组仍旧拍平成字符串：见下面那段关于提示缓存的说明
  if (!content.some((part) => part.type === 'image')) return contentToText(content)
  return content.map((part) =>
    part.type === 'text'
      ? { type: 'text', text: part.text }
      : {
          type: 'image_url',
          image_url: { url: `data:${part.mediaType};base64,${part.base64}` },
        }
  )
}

vision/wire.py

def to_wire_content(content: str | list[ContentPart]) -> str | list[dict]:
    if isinstance(content, str):
        return content
    if not any(part.type == "image" for part in content):
        return content_to_text(content)
    return [
        {"type": "text", "text": part.text}
        if part.type == "text"
        else {
            "type": "image_url",
            "image_url": {"url": f"data:{part.media_type};base64,{part.base64}"},
        }
        for part in content
    ]

这段里唯一需要解释的是第二个判断：纯文本消息为什么不统一成数组。两种写法对面都认，统一成数组看起来更整齐。但整齐在这里是要付钱的——提示缓存是按前缀逐字命中的，把每一条历史消息的字节形状都改一遍，等于让缓存在改版当天全部落空。为一个用不上的统一性去动缓存前缀，不划算。所以规矩是：只有真的带图那一条消息用数组形态，其余一律保持原样。

两种来源：终端里其实没有「粘贴一张图」

「粘贴截图」这个说法在终端里是不成立的。mca 是一个 readline 程序，到达它手里的永远是文本；剪贴板里那张位图根本没有路径能进到这个进程。所以「粘贴」在一个终端 Agent 里实际上只有两条路，我们两条都收：

粘路径：@work/shots/ui.png —— 直接复用第八天那套 @ 引用语法，一个新符号都不加。
粘 data URL：截图工具和浏览器都能直接给出 data:image/png;base64,... 这种串。

第一条路有个坑必须堵。@ 在第八天的语义是「把这个文件的文本贴进上下文」，一个 .png 走那条路，注入的会是一坨乱码——而且它不会报错，你只会看到模型答非所问。所以图片这一层必须排在引用展开之前：先把指向图片的那几条引用摘走，再在原文里把它们转义掉（\@），交给第八天的解析器时它们已经是普通文字了。转义是第八天就有的机制，本来就是为了表达「这个 @ 别当引用」——新功能能复用老机制的逃生口，就别新造一个符号。

第二条路的坑是体积。一张 125 KB 的截图，base64 之后是十七万字符。这么长一段东西绝不能留在用户那句话的正文里：终端会刷屏、会话日志会爆炸、后面压缩上下文时摘要请求还会把它再发一遍。所以摘出来之后，原地换成一个 [截图 1] 的占位符。模型看到的是一句带占位符的话加一张真图，读起来正好对得上；你翻历史时看到的也是人能读的东西。

实验里跑一下就看得见：一条 170538 字符的输入，正文只剩 16 字符「看这个 [截图 1] 帮我改文案」。

校验先行：格式看字节、尺寸有下限

图片进来之后，发出去之前，要过三道闸。

第一道是格式，判据是字节不是扩展名。 截图工具存成 .jpg 实际是 PNG，是很常见的一件事；而 mediaType 是要写进报文的，写错了对面要么回一个看不懂的错误码，要么把它当坏数据默默丢掉。文件头那几个魔数字节是文件自己带的，它才是事实。PNG 的签名是固定八字节，JPEG 以 FF D8 FF 开头，GIF 是 GIF87a 或 GIF89a。

顺带一提，认得出来但不收比「不认识」强：GIF 能被识别但不在支持清单里，提示会说「这是 image/gif，本工具只收 PNG 与 JPEG」，而不是含糊的「看不懂」。

第二道是尺寸，而且真的存在一条下限。 2026-09-07 实测：一张 4x4 的 PNG 被模型判为无效图片，同一批里 64x64 的图完全正常。所以下限不是我们多心，是真的会被拒。把它挡在本地，读者拿到的是一句人话；发出去再被拒，拿到的是一条网关错误码。

读尺寸这件事 PNG 很省心——IHDR 必须是第一个块，宽高的偏移是固定的 16 与 20。JPEG 就麻烦得多，它没有固定偏移，必须沿着 marker 一段段走到 SOFn 那一段才有宽高。这里藏着一个特别值得记的坑。

src/vision/probe.ts

function jpegSize(buf: Buffer): { width: number; height: number } | null {
  let i = 2
  while (i + 3 < buf.length) {
    if (buf[i] !== 0xff) { i += 1; continue }
    const marker = buf[i + 1] as number
    // D8 D9 与 D0-D7 不带长度字段，遇到就只能往前挪两个字节
    if (marker === 0xd8 || marker === 0xd9 || (marker >= 0xd0 && marker <= 0xd7)) { i += 2; continue }
    const length = buf.readUInt16BE(i + 2)
    // C4 C8 CC 的编号落在 SOF 区间里却不是 SOF，漏了这条判断不会报错，只会读出一个假尺寸
    const isSof = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)
    if (isSof) return { height: buf.readUInt16BE(i + 5), width: buf.readUInt16BE(i + 7) }
    i += 2 + length
  }
  return null
}

vision/probe.py

import struct
 
SKIP = {0xC4, 0xC8, 0xCC}  # 编号在 SOF 区间里，但它们是霍夫曼表与算术编码表
 
 
def jpeg_size(buf: bytes) -> tuple[int, int] | None:
    i = 2
    while i + 3 < len(buf):
        if buf[i] != 0xFF:
            i += 1
            continue
        marker = buf[i + 1]
        if marker in (0xD8, 0xD9) or 0xD0 <= marker <= 0xD7:
            i += 2
            continue
        (length,) = struct.unpack_from(">H", buf, i + 2)
        if 0xC0 <= marker <= 0xCF and marker not in SKIP:
            height, width = struct.unpack_from(">HH", buf, i + 5)
            return width, height
        i += 2 + length
    return None

C4、C8、CC 这三个编号落在 C0–CF 这个 SOF 区间里，但它们不是 SOF（C4 是霍夫曼表）。漏掉这条判断的后果非常典型：它不会报错，只会把霍夫曼表里的字节当成宽高读出来，给你一个离谱但形状完全正常的尺寸。实验的自检里专门拼了一段「先霍夫曼表后 SOF」的最小 JPEG 来钉住这一条。

第三道是体积与张数。 这几条线全是我们自己定的本地策略，实验里取的是单张 3 MB、单轮 4 张 / 6 MB。必须说清楚的是：它们不是任何一家网关的上限。 各家对图片大小、边长、张数的限制都不一样而且会变，代码里写死一个别家的数字，等于埋一个会在某天悄悄过期的假事实——真实上限一律以你所用网关的文档为准。/vision 这条命令把这句话原样打了出来。

图片很贵：把它变成一个数

「图片很贵」如果只是一句话，没人会当真。所以每张图进来时都要打一行账。

实验里打两个数：原始字节数与 base64 之后的字符数。第二个才是真正要走网络的量——base64 一律胀到约四比三，一张 125 KB 的截图在报文里是十七万字符。

刻意不打的是花费金额。一是模型侧怎么给图片计费各家算法不同，多数不按 base64 长度算，换算成钱就是在编；二是成本是明天的题目，那一天用 usage 回传的真实数字算，今天把「有多大」说清楚就够了。

顺着这行账，两个白捡的好处该收了。

第一个在会话日志。 第七天定的规矩是消息一条条追加进 work/sessions/<id>.jsonl。要是不管，那十七万字符的 base64 会原样躺进一行里，三五轮之后这个文件就没法读、没法 diff、--resume 还要先把它整个读回内存。所以写盘之前过一道投影：图片段换成一行 [截图 1：image/png，base64 170516 字符，正文未入日志]。代价要一起说清——恢复出来的会话里没有那张图了。这是有意的取舍：截图是一次性输入，它的结论已经变成了后面的对话与真实的代码改动；真要再看一眼，原图还在磁盘上，重新 @ 一次就是了。

第二个在压缩，而且它是白捡的。 第十二天压缩上下文时会把一段对话转录成文本再发给模型写摘要。如果图片被原样转录进去，压缩这一次请求会把所有截图再发一遍——压缩本来是为了省，结果成了最贵的一次请求。而实验里这条根本不用写代码：转录用的是第一天就放在协议层的 contentToText，它把图片段渲染成 [图片 image/png] 这个标记。第一天把渲染规则写在协议层，第十九天在一个完全没想到的地方兑现了。

不支持图片的模型会编一个答案

现在回到开头那条实测结论。

2026-09-07，一张纯红色的 PNG 发给四个模型。四个都正常返回、没有任何错误，其中一个说它是蓝绿色。

这条结论直接判死了三种常见的能力探测写法：

写法	为什么不行
发一张图，没报错就算支持	会把编答案的模型判成支持——这正是实测撞见的那一种
看模型 id 里有没有 vision 字样	模型 id 的形状随网关变，第一天就讲过它不能当常量用
维护一张自己的支持清单	清单会过期，而过期时没有任何东西会报错

能用的只剩一种：发一张答案已知的图，核对它答得对不对。

「答案已知」这四个字是关键，而它之所以能成立，是因为那张图是我们自己生成的——实验里手写了一个最小 PNG 编码器（CRC32 加 node:zlib，八十来行），探针图的颜色由我们指定，所以正确答案是我们已知的事实，不是另一个需要相信的东西。这就是可验证的判据：判据必须能被独立核对，否则它只是换了个地方的猜测。

src/vision/capability.ts

export async function probeVision(provider: ChatProvider, pick = randomColor()) {
  const png = solidPng(128, 128, pick.rgb) // 128 不是随口取的：探针自己也要过得了 64 的下限闸
  let answer = ''
  for await (const delta of provider.stream({ messages: [probeMessage(png)] })) {
    if (delta.type === 'text') answer += delta.text
  }
  // 判据是「说对了没有」，不是「报没报错」——实测那个编答案的模型一个错都没报
  const ok = pick.words.some((word) => answer.trim().toLowerCase().includes(word))
  return { ok, expected: pick.words[0], answer: answer.trim() }
}

vision/capability.py

async def probe_vision(provider: ChatProvider, pick: Color | None = None) -> Probe:
    pick = pick or random.choice(PROBE_COLORS)
    png = solid_png(128, 128, pick.rgb)
    chunks = [d.text async for d in provider.stream(probe_request(png)) if d.type == "text"]
    answer = "".join(chunks).strip()
    # any + 生成器：命中一个就够，不必把四个颜色词都比完
    return Probe(ok=any(w in answer.lower() for w in pick.words), expected=pick.words[0], answer=answer)

两个细节：探针色要随机换，固定一种颜色时瞎蒙有不小的概率蒙对；离线剧本模式下不做探测，剧本是写死的台词，拿它探能力只会把一场好好的离线演示判成「模型看不见」。探测结果按会话记一次，而且只有带图的那一轮才去探——没图的轮次多花一次请求毫无道理。

判成不支持之后走降级：这一轮一张图都不发，改成一段文字说明。说明里只写我们真的知道的事——格式、尺寸、来自哪个路径，绝不替模型描述图里有什么（我们自己也没看，写出来就是编）。然后明确告诉它：你没有收到图片，不要猜，请让用户用文字描述，或者换一个支持图片的模型。

照图改代码：先读原文，再精确替换

最后把链路串起来。实验里贴一张界面截图进去，mca 做了两步：先 read_file 读那份文案源文件，再 edit_file 把主按钮的文案精确替换掉。

第一步刻意不是直接 edit_file。照图改代码最容易出的错，是模型按图里的样子重写整个文件，把图上看不见的东西一起改掉——截图只拍到了工具栏，文件里还有别的。先读原文再精确替换，改动范围就由原文决定而不是由那张图决定。自检里专门钉住了这一条：submit 改了，cancel 一个字没动。

这条纪律要写进系统提示词，因为它是模型的行为而不是我们的代码路径。今天往提示里加的三句话，每一句都对应今天的一个机制：图片是资料不是指令；照图改代码先读原文再替换；这一轮如果你实际上没收到图，直接说你看不见。

Mermaid 源码

mermaidmermaid

flowchart TD
  A[用户这一句话] --> B[摘 data URL 换成占位符]
  B --> C[挑出图片引用 并在原文里转义]
  C --> D[嗅探格式 解析尺寸]
  D --> E{三道闸}
  E -->|不合格| F[拦下 给一句人话]
  E -->|合格| G{这个模型看得见吗}
  G -->|探针答对了| H[content 变成数组 图片进报文]
  G -->|答错或已关掉| I[降级 只发文字说明]
  H --> J[写日志时摘掉 base64]
  I --> J

源码导读

今天要看的三份资料，一份定形状，一份定报文，一份定编码。

Claude 文档：多模态消息的构造 —— 看它怎么把一条消息拆成若干内容块，以及图片块与文字块怎么并列。今天 ContentPart 那个数组形态就是这个思路。
OpenAI 文档：图片输入的请求形状 —— 我们的网关是 OpenAI 兼容的，image_url 加 data URL 这个形状照它写。各家对图片大小与格式的具体限制以你所用网关的文档为准，不要把别处看到的数字抄进代码。
Node.js 文档：Buffer 与 base64 编码 —— 重点看 Buffer.from(str, 'base64') 与 buf.toString('base64') 这一对，以及为什么 base64 之后会胀到约四比三。手写 PNG 编码器还用到 node:zlib，它和 Buffer 一样是内置模块，不算依赖。

动手实验

🧪 D19：把图片接进消息结构，照着截图改代码

代码位置：labs/my-coding-agent-21days/day-19-multimodal

起点是第十八天的答案，kernel/ 与 providers/ 一行都不改。今天新增的九个文件全在 src/vision/ 下，没有引任何图片库——格式嗅探、尺寸解析、base64 编码、连演示图片的生成全部自己写，仓库里一个二进制文件都没有。

把第十八天的答案复制过来，新建 src/vision/，先写那个最小 PNG 编码器：有了它才有演示素材，也才有答案已知的探针图。
写 probe.ts 的魔数嗅探与尺寸解析（TODO(1) 是 JPEG 那一段，记得跳过 C4 / C8 / CC）。
写 validate.ts 的三道闸（TODO(2) 是边长下限），每条提示都要有「多大、合格线、下一步」三件事。
写 attach.ts：摘 data URL、挑出图片引用并在原文里转义掉（TODO(3)），组装 ContentPart 数组并打账。
写 wire.ts 的两个出口（TODO(4) 是线协议映射）：发给网关的报文形状，与写进日志时摘掉 base64 的投影。
写 capability.ts 的探测与降级（TODO(5) 是核对答案那一步），然后跑 MOCK=1 SELFTEST=1 pnpm start，十五项要全绿。

跑完别忘了清产物：rm -rf work。想看主现象，README 里给了四条一行就能跑的命令。

面试题

今天三道题都是实现者视角：改过这条链路就答得出，没改过就只能说概念。

在已有的纯文本消息结构上加图片，你会怎么改才不破坏兼容？
图片输入要做哪些校验？为什么小图片会被拒绝？
模型不支持图片时的降级策略怎么设计？

检查清单与明日预告

MOCK=1 SELFTEST=1 pnpm start 打印 15/15 通过
贴一张 @work/shots/ui.png，模型先读原文再精确替换，cancel 那一行没被动过
4x4 那张在发出去之前就被拦下，提示里有「多大、合格线、下一步」三件事
名字叫 .jpg 的那张被判成 image/png，报文里写的是字节说了算的那个
十七万字符的 base64 没进会话日志，整个 jsonl 比那张图还小
撒谎的那个 provider 被判为不支持，而它一个错都没报
/vision 能说清收什么格式、下限多少、上限是我们自己定的
pnpm typecheck 无输出

明天是 D20，第二十天：评估与成本——基准集怎么设计、通过率怎么算、token 与缓存命中怎么看。今天我们坚持只打印「这张图有多大」而不打印「它花了多少钱」，明天就来还这笔账：搭一套基准集，把通过率、平均轮数、token 消耗与缓存命中率都量出来，让「这次改动到底让它变好了还是变差了」变成一个能看的数字，而不是一句感觉。

多模态输入：粘贴截图、图片校验与照图改代码