让 Agent 自己改前端:设计稿到像素级还原的自动化闭环
让 Agent 自己改前端:设计稿到像素级还原的自动化闭环
AI 写前端早已不是瓶颈,卡住的是“最后 10%”:间距写成 20px 而设计稿是 24px,字号 14px 而不是 16px,flex 换行后整块错位。社区里关于 agent-browser 的高热讨论也集中在这件事上——掘金一篇《Codex + Agent Browser:让 AI 精准还原前端 UI 的新范式》拿到三千多次阅读,核心论点其实很朴素:模型不缺生成能力,缺的是视觉反馈回路。它写完代码之后,没有任何机制告诉它“你写错了 4 个像素”。
本文不复述“AI 自动调样式”的愿景,而是回到仓库源码,拆开 agent-browser 真正提供了哪几种可度量的证据、这些证据的口径有哪些坑,以及如何把它压缩成一次可接受的提交前检查。
闭环的真实缺口:Agent 会写样式,但没有眼睛
传统流程里,验证环节是人:AI 生成代码 → 开发者打开浏览器 → 发现问题 → 回去改。Agent 被排除在验证之外,所以它永远在“盲写”。
agent-browser 的定位就是把这个验证环节交回给 Agent。它用 Rust 写 CLI,通过 CDP 直接驱动 Chrome,守护进程常驻,因此命令之间浏览器不重启——这一点对“改一轮、看一轮”的短周期循环至关重要。它的入口契约写在 core SKILL 里,是一个四拍循环:
agent-browser open <url> # 1. 打开页面
agent-browser snapshot -i # 2. 看页面有什么(仅可交互元素)
agent-browser click @e3 # 3. 用快照里的 ref 操作
agent-browser snapshot -i # 4. 页面变化后重新快照
快照把 DOM 压成带 @eN 引用的无障碍树。仓库内的 snapshot-refs 参考 给出了量级对比:整页 HTML → 解析 → CSS 选择器 大约 3000–5000 token,而紧凑快照 → ref → 直接操作大约 200–400 token。这正是社区反复引用的“节省 90%+ 上下文”的来源,它是设计取舍,不是营销数字。
但要注意:快照只描述结构和可交互性,不描述几何与样式。snapshot 里的 [level=1]、[checked=false] 是语义属性,不是 margin-top: 24px。所以“像素级还原”不能只靠快照,必须叠加另外三类度量。
五拍闭环:从改代码到再改代码
把上面的四拍扩展到前端还原场景,实际是五拍:
- 改代码:Agent 修改组件与样式。
- 起页面:
open到本地 dev server,并用条件等待替代固定 sleep。 - 截快照:同时对“结构”(snapshot)和“样式”(box / computed style)取样。
- 比对:与基线做结构化 diff、像素 diff,或与期望值做数值断言。
- 再改:把 diff 结果作为下一轮的输入。
其中第 2 步最容易被写坏。仓库在 commands 文档 里明确反对把 wait --load networkidle 当通用 SPA 等待——SSE、WebSocket、轮询会让它永远不 idle。对 UI 校验场景,更可靠的是“等到布局稳定”的条件:
agent-browser wait --fn "document.fonts.status === 'ready'"
agent-browser wait --fn "Array.from(document.images).every(i => i.complete)"
字体没加载完就截图,是像素比对出现大面积伪差异的头号原因。等字体、等图片,比等网络安静更贴近“渲染完成”这个真实语义。
另一个工程细节是会话隔离。默认匿名 session 是全机器共享的,多个 Agent 并行时会互相抢页面。SKILL 给出的做法是先取一个稳定会话名,再在每条命令上带上:
SESSION="$(agent-browser session id --scope worktree --prefix ui-check)"
agent-browser --session "$SESSION" open http://localhost:3000/pricing
--scope worktree 让同一个工作区重复执行得到同一个名字,这正好适配“每条命令都在新 shell 里跑”的 Agent 运行时。
把“像素级”拆成四类证据
“还原度”是个模糊词。工程上必须拆成能判定真假的具体量。仓库里可用的证据有四层,可靠性和代价各不相同。
结构证据:snapshot diff
diff snapshot 比较的是无障碍树的行级文本差异,输出 + / - 与新增、删除、未变行计数(diffing 文档)。它的关键实现细节在 diff.rs:Myers 算法走 similar crate,但对相同输入开了快速路径,直接返回 unchanged = 行数,不构造 diff 对象——这个优化是专门为“Agent 在重试循环里反复比较同一快照”准备的。
更重要的是引用归一化。snapshot_comparison_text() 会剥掉形如 ref=e12 的自动生成属性,但保留引号内文本里出现的 [ref=e3]:
if !quoted && ch == '[' && output.ends_with(' ') {
// 逐字段过滤 ref=eN,只保留 checked=false 之类的语义属性
}
这段逻辑解决了一个非常实际的噪声源:同一份 DOM 重新快照后 ref 编号会变,如果不归一化,每次 diff 都会报“全页改动”。归一化之后,“按钮从可点击变成 disabled”才会被识别成真变更。
几何证据:get box
get box <sel> 走的是 getBoundingClientRect(),返回 x / y / width / height(element.rs):
function() {
const r = this.getBoundingClientRect();
return { x: r.x, y: r.y, width: r.width, height: r.height };
}
两个坑必须写进口径说明里。第一,这是视口相对坐标且带亚像素浮点,滚动位置会直接改变 y,所以跨轮次比较绝对 y 基本没有意义;正确做法是在同一个容器内比较相对间距,或者固定滚动位置(scrollintoview 之后不要再滚)。第二,宽度高度也可能出现 247.99998 这类值,断言必须带容差,不能 == 248。
样式证据:get styles 与它的 token 陷阱
get styles <sel> 返回 getComputedStyle 的解析结果。源码里能清楚看到两条分支:传入 properties 列表时只取指定属性,否则遍历整个 CSSStyleDeclaration,把几百个属性全部导出:
None => r#"function() {
const s = window.getComputedStyle(this);
const result = {};
for (let i = 0; i < s.length; i++) {
const p = s[i];
result[p] = s.getPropertyValue(p);
}
return result;
}"#
而 CLI 的参数解析(commands.rs)只接受一个 selector,没有属性过滤开关。也就是说,一句 agent-browser get styles "#hero" 会把整份计算样式倒进上下文——对于一个本该节省 token 的工具,这是最容易被误用成“反向优化”的地方。
正确姿势是用 eval --stdin 一次性精确取字段,一个 heredoc 换一次往返:
cat <<'EOF' | agent-browser eval --stdin
(() => {
const pick = (sel, props) => {
const el = document.querySelector(sel);
const s = getComputedStyle(el);
const out = {};
for (const p of props) out[p] = s.getPropertyValue(p);
return out;
};
return {
hero: pick("#hero", ["font-size","font-weight","line-height","color","padding-top","padding-left"]),
title: pick("h1", ["font-size","line-height","letter-spacing","margin-bottom"]),
card: pick(".card", ["gap","padding","border-radius","box-shadow"]),
};
})()
EOF
这比连发三条 get styles 快得多,也不会把噪声灌进模型上下文。
还必须记住:计算样式返回的是已解析但未必可直接比较的值。line-height 可能是 normal,width 可能是 auto,padding 可能是 1.5rem 换算后的 24px(取决于是否命中 root font-size)。凡是出现 normal、auto、none 的字段,都不该进自动断言,只能进人工评审清单。
像素证据:diff screenshot
diff screenshot --baseline <file> 在 Rust 侧做逐像素比较(diff.rs)。它先把基准图和当前图解码成 RGBA,逐像素算 RGB 欧氏距离:
let max_color_distance = threshold * 255.0 * (3.0_f64).sqrt();
let dist = (dr * dr + dg * dg + db * db).sqrt();
if dist > max_color_distance { different += 1; /* 标红 */ }
超过阈值的像素标红,未超阈值的像素转灰度并压暗到 30%,输出一张 diff 图;同时回报 match、mismatchPercentage、totalPixels、differentPixels。
尺寸不等时它不试图缩放对齐,而是直接返回 dimension_mismatch,并把 mismatch_percentage 设为 100。这个选择很硬,但正确——缩放后比对会掩盖真实的布局溢出。代价是:跑像素比对之前必须锁死视口:
agent-browser set viewport 1440 900 1
1 是设备像素比。多轮之间 DPR 变化会让所有图尺寸翻倍,直接触发 100% mismatch。
最容易踩的口径陷阱:两个 --threshold
这是本文最想强调的一点,因为它在实际使用中会安静地给出错误结论。
screenshot --threshold 0.01 和 diff screenshot --threshold 0.01 看起来是同一个概念,实际语义完全不同:
| 命令 | 阈值含义 | 源码位置 |
|---|---|---|
screenshot --if-changed --threshold <0-1> |
像素变化比例:变化像素数 / 总像素数 | actions.rs changed_pixel_ratio |
diff screenshot --threshold <0-1> |
单像素颜色距离上限,默认 0.1 | diff.rs max_color_distance |
前者是“整张图有超过 1% 的像素动了才算变”;后者是“单个像素的 RGB 距离超过 44.2 才算不同”。把后者的 0.01 当成前者用,你会得到一张几乎全红的 diff 图——因为 0.01 × 255 × √3 ≈ 4.4,抗锯齿级别的抖动就足以越线。
另外三个来自源码的坑,值得写进团队文档:
其一,--baseline 指向不存在的文件不会报错。 actions.rs 里的处理是:路径存在就读文件,不存在就把这个字符串当基准文本用:
Some(b) if std::path::Path::new(b).exists() => { /* 读文件,去掉一个尾随换行 */ }
Some(b) => b.to_string(), // 路径字面量成了基线
于是第一次跑基线还没生成时,你不会看到错误,只会看到一份“整页都变了”的 diff。CI 脚本必须显式前置检查基线文件是否存在。
其二,--if-changed 的基线是“上一次返回过的图”,不是“上一帧”。 被抑制的截图不会覆盖基线,所以细微变化可以累积到越过阈值再触发;同一 tag 下历史按 (session, selector|fullPage|annotate) 分组,最多保留 32 组,超出按插入顺序淘汰。首次截取永远是 changed: true,且未变化时响应里不包含 path——靠“有没有 path”判断是否有新图,比解析文本更稳。
其三,像素证据只能证明“变了”,不能证明“变对了”。 mismatchPercentage 是两个渲染结果之间的距离,如果你的基线本身就和设计稿不一致,闭环会稳定地收敛到错误答案。
收进提交前检查:把一轮成本压到可接受
把上面拼起来,一个可落地的检查脚本大致是这样。要点是:单会话、固定视口、条件等待、batch --bail 减少进程往返、用 JSON 而非文本做判定。
#!/usr/bin/env bash
set -euo pipefail
SESSION="$(agent-browser session id --scope worktree --prefix ui-check)"
BASE=".ui-baseline"
mkdir -p "$BASE"
agent-browser --session "$SESSION" batch --bail \
"open http://localhost:3000/pricing" \
"set viewport 1440 900 1" \
"wait --fn document.fonts.status === 'ready'" \
"wait --fn Array.from(document.images).every(i => i.complete)"
# 每轮只产出一张图;未见变化则省略 path,token 与磁盘都省
agent-browser --session "$SESSION" screenshot --full --if-changed --threshold 0.002 "$BASE/pricing.png"
# 尺寸不一致会直接 100% mismatch,出图前先确认基线存在
test -f "$BASE/pricing.baseline.png" || cp "$BASE/pricing.png" "$BASE/pricing.baseline.png"
agent-browser --session "$SESSION" --json diff screenshot \
--baseline "$BASE/pricing.baseline.png" \
--output "$BASE/pricing.diff.png" \
--threshold 0.1
判定逻辑放在外层,读 --json 的 match、mismatchPercentage、dimensionMismatch 三个字段,不要把 Images match 这类人类可读文本当契约。--bail 保证第一步失败就停,避免在错误页面上跑完整轮截图。
耗时控制上有几个真正起作用的手段,都不是“调参玄学”:
- 守护进程常驻:浏览器只启动一次,后续每条命令只是 CDP 往返。这是把“一轮几秒”压到“一轮几百毫秒”的主要原因。
snapshot -i -s "#main" -d 6:限定到局部子树并限深,快照体积可直接降一个数量级,diff 也随之变便宜。--max-output:全局截断页面输出,防止某次 diff 把整棵树灌进上下文。screenshot --if-changed:无变化时既不落盘也不返回路径,是循环里最划算的一档。
至于“哪些能自动判定、哪些必须人看”,建议按下面的边界划线,不要越界:
| 维度 | 可自动判定 | 必须人工评审 |
|---|---|---|
| 布局几何 | 容器宽高、元素间距、栅格列数与断点 | 视觉重心、留白节奏是否“好看” |
| 排版 | font-size、font-weight、letter-spacing 的数值 |
字体渲染、抗锯齿、line-height: normal 的实际观感 |
| 颜色 | color、background-color 的精确值 |
阴影、渐变、半透明叠加后的最终观感 |
| 结构 | 无障碍树新增/删除/属性变化 | 语义是否合理(div 堆砌 vs 正确 landmark) |
| 像素 | 变化区域定位、差异百分比 | 变化是否“应该发生” |
诚实的边界:这个闭环不能替代审美判断
回到社区热度最高那个说法——“设计稿到像素级实现”。必须指出,agent-browser 提供的是测量与比对原语,它不解析 Figma,也不理解设计意图。所谓闭环要成立,前提是有人(或另一个模型)已经把设计稿翻译成了可比较的期望值:一张基准截图,或者一份 {"#hero": {"font-size": "40px", "padding-top": "64px"}} 的断言清单。没有这个“规范层”,Agent 只是在和自己上一轮的输出对齐,会稳定地自我确认。
它也不擅长动效与合成层。transition、transform、filter: blur()、Canvas/WebGL 内容,在单帧像素 diff 里要么不可见,要么全是噪声。悬停态、聚焦态需要显式触发后再单独取基线,这属于“多状态基线”,不是一次截图能覆盖的。
更现实的价值在于:它把“回归”这件事变得便宜。改一个按钮的 padding,可能让下面三个区块整体位移 6px,人工评审很难发现,diff screenshot 一眼就能指出红色区域在哪。把这种机械比对交给 Agent,人才有余量去看真正需要判断的部分——这才是“让 Agent 自己改前端”在当前阶段最站得住的解释。