18. 多模态代码 Agent：视觉输入加入代码生成的工作流

多模态输入打开了哪些场景

纯文本的代码 Agent 只能处理文字描述的需求。一旦引入视觉能力（GPT-4V、Claude 3.5+、Gemini Pro Vision 等），几类原本难以处理的任务变得可行：

1. 设计稿到代码

设计师给一张 Figma 截图，Agent 输出 HTML/CSS 或 React 组件。

2. 屏幕截图驱动的 UI 自动化

Agent 看到当前页面截图，决定下一步点哪里、输入什么。

3. 图表/图形理解

数据可视化的截图、流程图、架构图作为输入，Agent 理解后生成相关代码。

4. 视觉调试

测试失败时的截图对比、UI 渲染异常的诊断。

5. 文档中的图示

API 文档、教程、论文里的图片也能被 Agent 读懂，作为代码生成的参考。

设计稿到代码

这是多模态代码 Agent 较早被关注的场景。代表性工作包括 Vercel 的 v0、Galileo AI、以及各家大模型自带的"screenshot to code"能力。

典型工作流：

[输入]
- 一张 UI 设计图（PNG/JPG）
- 目标技术栈说明（React + Tailwind / Vue / 纯 HTML）
- 可选：现有组件库说明

[Agent 内部步骤]
1. 视觉理解：识别布局结构（header / sidebar / main / footer）
2. 元素识别：按钮、输入框、卡片、列表
3. 样式提取：颜色、间距、字体、圆角
4. 层级关系：嵌套结构、对齐方式
5. 代码生成：根据上述结构生成代码

[输出]
组件代码 + 样式代码

目前的局限：

复杂动效几乎无法从静态截图推断
响应式断点需要额外的多份截图
交互逻辑（点击后发生什么）截图不包含，需要额外说明
设计稿里的占位文字可能被当成真实内容

比较实际的用法：

把设计稿到代码当成"生成初稿"，而不是"一步到位"。初稿质量在 60-80% 之间，剩下的部分人工调整。这种工作流在简单页面、营销落地页等场景已经有实际生产力，复杂业务应用还需要更多人工介入。

浏览器/桌面 Agent 的视觉决策

这是更复杂的场景：Agent 不是一次性生成代码，而是持续看屏幕、做操作、再看屏幕、再做操作。

代表性工作：

WebArena / VisualWebArena：基于浏览器的 Agent 评测环境
OSWorld：覆盖完整桌面操作的 benchmark
Claude Computer Use（Anthropic）
Operator（OpenAI）

典型工作循环：

1. 截屏当前屏幕
2. 模型理解屏幕内容（页面结构、可点击元素、当前焦点）
3. 决定下一步动作（点击坐标 X,Y / 输入文字 / 滚动）
4. 执行动作
5. 等待页面响应
6. 回到第 1 步

每一步都需要模型的视觉理解 + 决策能力。代码在这里的角色变成了"执行层"——Agent 的决策最终翻译成 Playwright 或 PyAutoGUI 的代码调用：

# Agent 决策：点击页面上的"登录"按钮
import pyautogui
pyautogui.click(x=820, y=145)

# Agent 决策：在用户名输入框输入文字
pyautogui.click(x=400, y=300)  # 先聚焦
pyautogui.write("[email protected]")

或者用更高层的 API：

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    page.click("text=Sign in")
    page.fill("input[name='email']", "[email protected]")

视觉 vs DOM 的选择

浏览器场景下，有两种感知方式：

视觉：截屏，靠模型理解像素
DOM：直接读 HTML 结构，靠模型理解节点

DOM 的优势：信息精确，节点 ID 唯一，操作不依赖坐标。视觉的优势：通用，不依赖网页的具体实现，桌面应用也能用。

实际系统经常两者结合：DOM 作主，视觉作辅。能用 DOM 定位的就用 DOM，DOM 信息不足或者操作是 canvas / 图像时降级到视觉。

视觉调试

测试失败、UI 渲染异常的场景下，视觉信息能提供文字日志给不出的信息。

例子 1：UI 测试失败

[测试期望]：点击"下一步"按钮后页面跳转到第二步

[实际结果]：测试断言失败，期望的元素未找到

[传统调试]：看日志、看 DOM，但不知道页面长什么样

[多模态 Agent 调试]：
  截屏当前页面 → 模型识别 → "按钮被一个 modal 遮挡了"
  → 修改测试，先关闭 modal 再点击按钮

例子 2：跨浏览器渲染差异

Chrome 和 Safari 的渲染截图作为输入
模型对比 → "Safari 上 flexbox 的 gap 没有生效"
建议修改：用 margin 代替 gap，或者加 webkit 前缀

这种用法目前还偏研究性质，工程上常见的还是人工对照截图。但 Agent 化的趋势在出现。

工程挑战

1. 视觉理解的精度

模型对像素位置的判断有误差。"点击按钮的中心"听起来简单，模型可能给出偏离实际中心 20 像素的坐标。

应对：

给元素加 ID 或 data-testid，让 Agent 用文本定位而不是坐标
操作前先 hover 确认，看视觉反馈
失败后重新截屏判断状态

2. 截图的 token 成本

一张 1920x1080 的截图，按多模态模型的 tokenizer 通常消耗几千 token。如果 Agent 每步都截屏，一个长任务的 token 消耗会显著高于纯文本。

应对：

裁剪：只发送相关区域的截图
缩放：降低分辨率（注意识别精度的权衡）
关键帧：不是每步都截屏，只在状态变化时截

3. 动态内容的同步

页面加载、动画过渡期间截屏，Agent 看到的可能是中间状态，做出错误决策。

应对：

显式等待：操作后等几百毫秒再截屏
元素可见性检查：用 DOM 确认目标元素已渲染完成
重试机制：失败后等待并重试

4. 私密信息处理

截屏可能包含密码、token、个人信息。这些被发到云端模型存在隐私问题。

应对：

截屏前用规则遮挡敏感区域
用本地多模态模型（Qwen-VL、LLaVA 等）
对涉密页面禁用多模态 Agent

评测的特殊性

多模态代码 Agent 的评测比纯文本更难：

输入是图像，benchmark 的标准化困难
输出可能是代码、操作序列，或两者混合
"成功"的定义复杂（视觉相似度？功能等价？）

现有的相关 benchmark：

Benchmark	任务	评测方式
Design2Code	网页截图生成 HTML	视觉相似度 + 结构相似度
WebSRC	网页截图问答	答案准确率
WebArena	浏览器任务完成	任务完成率
OSWorld	桌面任务完成	任务完成率
ScreenSpot	UI 元素定位	坐标精度

这些 benchmark 的成绩往往波动很大，原因之一是视觉理解和文本理解的能力分布在不同任务上不一致。比如某个模型在 Design2Code 上很强，但在 WebArena 上可能很弱，反之亦然。

几个观察

视觉输入不是免费的补强：加入视觉能力会显著增加成本、延迟和错误模式。如果纯文本能解决，没必要加视觉。

精确操作 vs 灵活感知的权衡：DOM 操作精确但脆弱（页面改版就失效），视觉操作通用但不精确。混合使用通常比纯靠一种好。

人在回路仍然重要：多模态 Agent 在生产中（特别是涉及实际钱、账号操作的场景）通常仍然需要关键步骤的人工确认。完全自动化的多模态 Agent 风险较高。

模型差距明显：不同模型的视觉理解能力差距比文本理解大得多。选模型时要单独评测视觉任务，不能直接用文本任务的成绩外推。

小结

多模态代码 Agent 把 Agent 的能力从"处理文字"扩展到了"处理屏幕"。这打开了设计稿转代码、浏览器自动化、桌面操作等新场景，也带来了精度、成本、隐私等新的工程挑战。

目前这个方向还在快速发展。设计稿到代码已经有实际可用的产品，浏览器/桌面 Agent 还在早期。未来 1-2 年内，多模态能力的提升和工具链的成熟会让更多生产级应用出现，但完全替代人工的全自动 Agent 在可见的将来仍然不现实。

（采用 CC BY-NC-SA 4.0 许可协议进行授权）

本文标题:18. 多模态代码 Agent：视觉输入加入代码生成的工作流

本文链接:https://www.sshipanoo.com/blog/ai/code-agent-harness/18-多模态代码Agent/

本文最后一次更新为天前，文章中的某些内容可能已过时！