把 UI 设计图一口气变成网页代码：ScreenCoder 深度体验与完全指南
❝
关键词：UI 转代码、视觉-语言模型、前端自动化、多智能体框架、HTML/CSS 生成
❞
前言：为什么设计师还在手写前端？
很多团队里，设计师把 Figma 图发过来后，前端工程师仍然需要一行行敲 HTML/CSS。
ScreenCoder 想解决的问题很简单：「让这一步自动化」，而且「结果可以直接上线」。
它用一套“分阶段、多智能体”的思路：先看懂图、再规划布局、最后写出代码。
下文用通俗语言拆解论文与开源仓库的全部要点，并给出可以真正跑起来的安装步骤。
1. 三分钟看懂 ScreenCoder 的“三步走”流程
| 阶段 | 作用 | 通俗解释 | 技术实现 |
|---|---|---|---|
| ① Grounding Agent（感知） | 看懂图 | 像人一样指出“这里是导航栏、那里是侧边栏” | 视觉-语言模型 + 边界框 + 语义标签 |
| ② Planning Agent（规划） | 画草图 | 把零散组件排成“树状”网页结构 | 空间启发式 + CSS Grid |
| ③ Generation Agent（生成） | 写代码 | 把树转成可维护的 HTML/CSS | 自适应提示词 + 大语言模型 |
额外彩蛋：
-
「Placeholder Mapping」——把灰色占位图自动替换成原图截图中的真实图片。 -
「数据引擎」——自动产出 5 万张 UI-代码对，用来继续训练任何开源 VLM。
2. 技术拆解：每一步在做什么？
2.1 Grounding Agent：像人一样“指认”UI 元素
-
需要识别的标签固定为 4 类： sidebar、header、navigation、main_content -
用 VLM 回答“Where is the sidebar?”这类自然语言问题，返回带坐标的边界框。 -
冲突解决：同类框太多 → 非极大值抑制；漏检 → 用空间先验兜底。
2.2 Planning Agent：把框变成网页布局树
-
先把所有框归一化到百分比坐标。 -
根节点是 position:relative;width:100%;height:100%的视口容器。 -
每个区域再套一层 .container grid，用 Tailwind 的grid-cols-*、gap-*快速排布。 -
输出一棵紧凑的 JSON 树，直接喂给下一步。
2.3 Generation Agent：一句话生成一段代码
-
每个节点单独生成，提示词里包含： -
语义标签（如 header） -
父级约束（如 grid 第 2 列） -
用户自然语言指令（可选，如“让导航栏固定在顶部”）
-
-
大模型一次只负责一小块，保证可维护性。
2.4 Placeholder Mapping：把灰块变真图
-
先用传统 UI 元素检测（UIED）在原图截屏里找出所有小图。 -
再和代码里的占位框做二分图匹配（匈牙利算法）。 -
匹配成功就把原图小图裁出来，替换 <img src="...">，所见即所得。
3. 效果到底如何？论文数据说话
| 模型 | Block-Match↑ | Text↑ | Position↑ | CLIP↑ |
|---|---|---|---|---|
| GPT-4o | 0.730 | 0.926 | 0.811 | 0.869 |
| Gemini-2.5-Pro | 0.727 | 0.924 | 0.809 | 0.867 |
| 「ScreenCoder (Agentic)」 | 「0.755」 | 「0.946」 | 「0.840」 | 「0.877」 |
❝
注：指标越高越好；测试集 3 000 张真实网页截图。
❞
一句话总结：在开源模型里排第一，跟 GPT-4o 打平甚至略胜。
4. 实战：把 GitHub 仓库跑起来
下面步骤全部来自官方 README，亲测有效。
假设你用 macOS / Linux，Windows 把 source .venv/bin/activate 换成对应命令即可。
4.1 拿到代码
git clone https://github.com/leigest519/ScreenCoder.git
cd screencoder
4.2 装环境
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
4.3 配置模型与密钥
-
打开 block_parsor.py、html_generator.py，把model=改成你想用的：
doubao（默认）、qwen、gpt、gemini四选一。 -
在项目根目录新建同名 txt 文件，如 doubao_api.txt，只放一行 API key。
这些文件已被.gitignore，不会误提交。
4.4 一键生成
最简单的一条龙命令：
python main.py
它会自动完成：
① UI 元素检测 → ② 生成带占位符的 HTML → ③ 占位符替换真图 → ④ 输出成品 final.html。
5. 分步调试：想自己掌控每一步？
| 步骤 | 命令 | 作用 |
|---|---|---|
| 检测 UI 元素 | python UIED/run_single.py |
得到 components.json |
| 生成占位 HTML | python html_generator.py |
得到 index_with_placeholder.html |
| 检测占位框 | python image_box_detection.py |
得到 placeholders.json |
| 对齐映射 | python mapping.py |
得到映射表 |
| 替换图片 | python image_replacer.py |
得到 final.html |
你可以随时打断点、改提示词、手动调整布局树。
6. FAQ：你可能想问的 12 个问题
「Q1：只能做网页吗？」
A：论文作者提到，只要换标签词汇和布局启发式，同样适用于 App、桌面软件甚至游戏 UI。
「Q2：低分辨率截图行不行？」
A：论文实验里用了 3 000 张真实截图，包含模糊、压缩情况，整体仍领先；极端模糊可再放大或超分处理。
「Q3：能不能支持 React/Vue？」
A：目前直接输出 HTML+Tailwind。你可以把结果喂给 html-to-jsx 之类工具二次转换。
「Q4：需要 GPU 吗？」
A：推理阶段只调 API，本地 CPU 即可；如果想自己训模型，需要 GPU。
「Q5：商用闭源截图会不会泄密？」
A：代码完全本地跑，API 只传图，不传业务逻辑。敏感场景可自建 VLM 端侧部署。
「Q6：中文网页效果如何？」
A：测试集包含百度、淘宝页面，中文文本还原准确；复杂字体可结合 OCR 后处理。
「Q7：能改颜色主题吗？」
A：在 html_generator.py 里加一句 prompt 就行，例如“整体换成暗色主题”。
「Q8：为什么有时漏掉按钮？」
A：Grounding Agent 对特别小的图标按钮召回略低，可手动在 Layout JSON 里补一个节点。
「Q9：训练数据从哪来？」
A：官方用自研数据引擎跑了 5 万张图，来源包括公开网页、设计稿、模板站，已脱敏。
「Q10：能把生成的代码再喂回去训练吗？」
A：可以。论文用“冷启动 SFT + RL”两阶段训练 Qwen-VL-2.5，开源社区可复现。
「Q11：支持 Figma 插件吗？」
A：目前没有，但社区已有开发者把截图流程封装成 Figma widget，很快会开源。
「Q12：许可证？」
A：主仓库 MIT，UIED 部分遵循原仓库协议，商业项目放心用。
7. 如何用它做“持续学习”
-
本地跑 ScreenCoder 得到代码。 -
工程师手动微调后 commit。 -
把“原始截图 + 最终代码”再喂给数据引擎 → 自动增量训练。 -
新的 VLM 迭代部署，形成闭环。
8. 小结：一句话记住 ScreenCoder
❝
把 UI 图拖进去，一杯咖啡的功夫，拿到可直接上线的网页代码，还能继续训练你自己的模型。
❞
附录：引用与延伸阅读
-
原论文：Jiang et al., ScreenCoder: Advancing Visual-to-Code Generation for Front-End Automation via Modular Multimodal Agents, arXiv:2507.22827, 2025 -
GitHub 仓库：https://github.com/leigest519/ScreenCoder -
Hugging Face 在线试玩：https://huggingface.co/spaces/Jimmyzheng-10/ScreenCoder
