Qwen Code 改进建议

April 5, 2026 · View on GitHub

核心洞察：随着多模态大模型的普及，让 Agent “看图写代码”（例如通过一张设计稿截图生成 React 组件，或者将一段难以名状的 UI 错位截图发给 Agent 求助）成为了高频场景。然而，大模型的 API 对 Base64 图片有着极其严格的大小限制（例如 Claude API 单张图片编码后不得超过几 MB）。如果开发者粘贴了一张 Retina 高清大图，Qwen Code 目前往往只能任由其塞爆 Token 或者直接被 API 拒绝；而 Claude Code 实现了一套叹为观止的“多策略阶梯降级压缩流水线”，确保任意图片都能在不损失核心代码细节的前提下被安全吞下。

返回 改进建议总览

一、高清截图带来的 API 拒收危机

1. Qwen Code 现状：直接丢给大模型

在目前 Qwen Code（包括很多开源 Agent 工具）中，如果用户通过特定的手段附加了一张本地的图片。

  • 痛点一（Token 暴涨与 API 拒载）：通常的做法是将图片转成 Base64 直接发出去。一张 4K 屏幕的截图很容易达到 10MB。当它到达模型服务端时，立刻会触发 Payload Too Large 或者 image size exceeds maximum allowed 的 400 错误。
  • 痛点二（极度粗暴的预处理）：如果在客户端为了防超限而强制粗暴缩放（比如一律缩放到 500x500 像素），对于代码截图来说是致命的——大模型会彻底看不清图片里的错误代码字母，产生严重幻觉。

2. Claude Code 的极客解法：保真度的极限拉扯

在 Claude Code 的 utils/imageResizer.ts 中，作者为了在“满足 API 大小红线”和“让大模型看清代码字迹”之间找到最优解，设计了多达 5 个阶段的阶梯降级策略。

机制一：Magic Bytes 原生识别

在不依赖庞大的 C++ 图像库（如 sharp）的情况下，纯用 Node.js 的 Buffer 嗅探文件开头的魔数（Magic Bytes），精准识别它是 PNG、JPEG、GIF 还是 WebP，避免后缀名欺骗。

机制二：阶梯递减压缩流水线 (Cascade Downgrading)

如果图片转成 Base64 后超出了 API_IMAGE_MAX_BASE64_SIZE，它不会立刻暴力 Resize（调整长宽），而是采用优先保全分辨率的策略：

  1. 策略 A (转码与温和压缩)：尝试将 PNG 转为 JPEG，且 Quality 设为 80。这通常能将截屏体积缩小 70%，且对代码字母几乎无损。
  2. 策略 B (极限画质压缩)：如果还是超限，将 Quality 阶梯下调：60 -> 40 -> 20。
  3. 策略 C (温和缩放)：如果到了 Quality 20 依然超标（比如是一张几亿像素的巨长网页滚动截图），才开始启动等比例缩小分辨率（Resize 75% -> 50% -> 25%）。
  4. 策略 D (兜底)：最后手段，强制裁剪到 1000x1000 以下的 Box 内。

在每应用一种策略后，系统都会重新计算 Base64 体积。只要一旦小于阈值，立刻中断流水线并将其发送给大模型！

二、Qwen Code 的改进路径 (P2 优先级)

赋予多模态 Agent 一副既能看清细节又不会被撑爆的眼睛。

阶段 1：引入轻量级图像处理库

  1. 考虑到 Node.js 原生不带图片处理，可以按需引入 sharp 或者更轻量的纯 JS 方案（如 jimp 或仅在浏览器端处理）。
  2. 在 packages/core/src/utils/ 下封装 imageResizer.ts。

阶段 2：开发 Token 与 Bytes 换算器

  1. 基于通义千问 VL（Vision Language）模型的计费或限制标准（例如最高允许多少 Pixels 或者 Base64 大小），编写 compressImageBufferWithTokenLimit() 方法。
  2. 设定硬阈值（如限制不超过 3MB 原始体积）。

阶段 3：建立降级流水线

在读取用户附加的图像文件流准备向 messages 数组压入时：

  • 先过一遍检测。如果超限，进入一个 while 循环或者迭代器。
  • 按照 PNG转JPEG -> 调低画质 -> 缩小分辨率 的优先顺序，逐步榨取空间。
  • 同时在终端控制台向用户打出一行微弱的提示：[Image compressed from 15MB to 2.1MB to meet API limits]。

三、改进收益评估

  • 实现成本：中等。核心是引入图像库（可能导致产物变大），以及编写细致的 Buffer 到 Base64 的探测逻辑，代码量 200 行左右。
  • 直接收益：
    1. 零配置的多模态体验：开发者以后随手圈出一块高清大图或者报错截图直接粘贴给 Agent，再也不会因为“图片太大”而吃闭门羹。
    2. 最大化保护 OCR 精度：优先降画质而不是降分辨率的策略，是对代码截图、报错日志截图最完美的压缩方案，极大提升了模型阅读包含文字图片的准确率。