AI Agent改坏代码？用视觉前后对比提升可观测性

如果你的 AI 助手把项目代码改坏了，你应该先看什么？大多数开发者的第一反应是打开终端翻日志，第二反应是执行git diff看代码变更。但这里有一个致命盲区：代码层面的 diff 只能告诉你“改了什么”，无法告诉你“屏幕上的效果变成了什么样”。尤其是当 AI Agent 修改的是前端页面样式、组件交互、自动化脚本的执行结果，或者是一批图片资源时，几十行 diff 输出根本不足以让你快速判断“这次改动是不是真的符合预期”。

SightDiff 这个项目想解决的正是这个问题。它没有去重复造一个代码 diff 工具，而是把注意力放在了一个更直观、也更容易被忽略的维度：用前后对比的视觉证据，证明 AI Agent 到底改变了什么。

这篇文章会从 AI Agent 开发的可观测性痛点出发，拆解 SightDiff 这类“前后对比视觉证明”工具的设计思路、适用场景、实现路径，以及你在自己项目里接入时需要避开的坑。读完以后，你不仅能理解它为什么在 Hacker News 上引起讨论，也能判断它到底适不适合你的团队。

1. 这篇文章真正要解决的问题

先说一个很多人都遇到过的场景：你给 AI Agent 下了一个任务——调整某个后台管理页面的布局、优化几个按钮的间距、或者让某个自动化流程生成新的报告文件。Agent 运行得很快，日志也显示“全部完成”。但当你真正打开页面时，发现样式乱了、图片错位了、按钮被挤到了页面外面。

这时候你会想：Agent 到底是哪一步操作导致了这种结果？

传统的排查方式基本靠三样东西：

1. 日志：能记录 Agent 执行了哪些动作，但记录不了屏幕上的视觉效果。
2. 代码 diff：能展示文本层面的增删改，但面对样式调整、截图、文件生成这类任务，代码 diff 的语义信息非常有限。
3. 运行结果：如果 Agent 生成了文件，你可以对比前后文件；但如果你根本不知道输出目录里多了一个文件，可能连对比的入口都没有。

SightDiff 的切入点非常直接：在 Agent 执行任务之前拍一张“before”快照，在 Agent 执行完任务之后再拍一张“after”快照，然后把两张快照放在一起，用视觉对比的方式让开发者一目了然地看到变化。

这个思路不算惊天动地，但它命中了一个非常重要的需求——AI Agent 时代需要新的可观测性手段。传统可观测性强调的是指标、日志、链路追踪，对象是系统内部状态；而 AI Agent 的行为结果往往体现在外部世界的变化上，这种变化最自然的表达方式就是“前后对照”。

这篇文章适合以下读者：

• 正在开发或接入 AI Agent 的开发者，希望更清楚地掌握 Agent 的改动内容。
• 负责前端自动化测试、UI 回归测试的测试工程师，需要更高效的视觉验证手段。
• 关注 AI 工程化落地的技术负责人，想了解 Agent 可观测性这个方向的最新探索。

2. 为什么传统的 diff 和日志兜不住 AI Agent 场景

要理解 SightDiff 的价值，先要理解传统工具在 AI Agent 场景下有哪些具体局限。

2.1 代码 diff 解决的只是“文本层”问题

git diff擅长展示文本变化，但它有一个隐含假设：代码文本的变化能被开发者直接理解。对于函数逻辑修改、配置文件变更，这个假设基本成立。但 AI Agent 经常做的事远超文本层面：

• 修改 CSS 间距，从 10px 变成 16px。看 diff 你能发现数值变了，但你看不出页面整体观感是否协调。
• 调用图像处理 API 生成新图片，代码 diff 只有几行，真正的变化发生在生成的文件里。
• 通过命令行执行一个爬虫脚本，Agent 的逻辑没变，但网页结构变了，导致抓取结果不同。这类变化很难通过代码 diff 发现。

换句话说，代码 diff 是“因”的层面，不是“果”的层面。开发者真正关心的往往是“果”——页面长什么样、文件内容是什么、流程跑完的结果是什么。

2.2 日志记录的是“过程”，不是“结果”

日志的关键字段通常是时间戳、级别、消息、上下文。它非常适合回答“Agent 做了什么”，但不太擅长回答“Agent 造成了什么影响”。

举个例子，Agent 执行了三条指令：

执行 shell 命令: cp /data/old_report.pdf /data/new_report.pdf 执行 shell 命令: python3 generate_chart.py 执行 shell 命令: rm -f /tmp/cache/*

日志能告诉你这些命令都成功执行了，但 report 长什么样、图表是否正确、缓存删除是否影响了正在运行的服务，日志一无所知。你只能在事后逐一检查，效率很低。

2.3 人工验证的覆盖范围有限

理想情况下，每个 AI Agent 任务执行完，都应该由开发者完整检查一遍效果。但现实中，开发者不可能逐一查看每一个输出的视觉产物。如果 Agent 自动处理了上百个页面截图、十几个报表、几十个配置文件，人工检查根本不现实。

这就是视觉化前后对比的核心价值：它把“需要人工逐项确认”变成“一眼就能看出差异”。人的视觉系统对图像差异非常敏感，两张截图并排放置，任何细微变化都会被迅速捕捉到。相比逐行看代码 diff，这种方式更接近人类直觉。

3. SightDiff 的定位与适用场景

从项目名称和定位来看，SightDiff 并不是一个通用的代码对比工具，而是专门面向 AI Agent 场景的“视觉证明工具”。它的核心输出是：在 Agent 运行前后分别记录视觉快照，生成可对比的证明材料，让开发者快速确认 Agent 到底改变了什么。

需要注意，我这里说的更多是基于项目名称、发布渠道和描述信息的合理推断。SightDiff 目前公开的技术细节还不多，它的具体实现可能随着版本迭代变化，但这不影响我们理解它所代表的一类工具思路。

3.1 它解决的核心问题

SightDiff 这类工具想要解决的核心问题可以概括为一句话：让 AI Agent 的执行结果从“被告知”变成“被看见”。

Agent 完成一个任务后，会返回一段文字描述，例如“已成功调整页面布局”。这句话是 Agent 对自己的行为总结，而不是外部验证结果。SightDiff 的“before/after”视觉证据则是从系统层面记录的事实——两张截图摆在那里，改动与否一目了然，Agent 无法“撒谎”，开发者也不用盲信。

3.2 典型适用场景

从实际工程经验来看，这类“前后视觉对比”思路适合以下场景：

3.3 不适合的场景

同时也要说清楚边界。SightDiff 这类工具不适合以下场景：

• 纯后端逻辑变更：如果 Agent 只是改了一个内存缓存策略，没有产生任何视觉化产物，前后对比截图没有意义。
• 大量文本内容验证：如果 Agent 改了配置文件中的一百个参数，用截图对比反而不如用结构化 diff 清晰。
• 数据一致性校验：数据库字段值的变化不适合用视觉方式验证，这类场景需要的是 schema diff 和数据校验规则。

所以更稳妥的判断是：SightDiff 不是要取代现有的 diff 工具、日志系统和测试框架，而是在这些工具之间补上了一块“视觉可验证性”的拼图。

4. 前后对比视觉证明的核心设计难点

理解了 SightDiff 的定位之后，我们要深入一个更关键的问题：实现一套可靠的“before/after 视觉证明”系统，难点到底在哪里？

很多人第一反应是：不就是截图前后对比吗？用 Python 写个脚本，ImageChops.difference()一算，像素差异就出来了。但实际落地远没有这么简单。

4.1 难点一：如何定义“同一位置”的对比

前后对比截图要有效，两张图的观察对象必须处于可对比状态。如果 Before 截图是在页面加载完成前拍的，After 截图是在页面加载完成后拍的，那么即使页面内容完全没变，两张图的差异也会非常大。

一个成熟的方案需要处理：

• 页面加载完成事件。
• 动画执行中的状态判定。
• 动态内容（时间组件、随机广告、实时数据）带来的干扰。
• 不同分辨率、不同浏览器窗口大小的影响。

这些都属于“截图环境一致性”问题。环境不一致，前后对比就失去了意义。

4.2 难点二：像素级 diff 并不等于语义级 diff

像素差异是最底层的变化信号，但它没有语义。两张截图有 5000 个像素不同，可能是样式正常调整，也可能是整体布局完全错乱。开发者真正关心的不是“哪里不同”，而是“这个不同是否重要”。

从这个角度看，SightDiff 这类工具的价值不在于“跑出一个 diff 图”，而在于把 diff 结果组织成人类能快速理解的证据。比如：

• 标注出差异区域。
• 按差异面积排序。
• 结合 Agent 的任务描述，判断变化是否符合预期。
• 生成一份可以直接分享给团队或上游复核的对比报告。

4.3 难点三：记录时机和触发方式

AI Agent 不是一个单体程序，它由多步操作组成，可能在十几分钟内执行几十个动作。SightDiff 的开发者在设计时必然要面对一个问题：在哪个时间点拍 before？在哪个时间点拍 after？

• 如果整个任务只拍两次，颗粒度太粗，无法定位问题出在哪一步。
• 如果每一步都拍一次，数据量爆炸，而且很多步骤根本不产生视觉变化。

更合理的思路可能是分层记录：任务开始时记录基线快照，每个关键节点记录中间快照，任务结束时记录最终快照，然后由上层逻辑决定展示哪一组对比。

4.4 难点四：非确定性内容干扰

AI Agent 常常处理动态页面。一个后台系统的右上角有时间显示、有最新的日志滚动、有随机用户头像——这些内容的轻微变化都会造成视觉 diff 的“假阳性”。

常见的缓解手段包括：

• 在截图前冻结或隐藏动态内容区域。
• 对差异区域做忽略配置。
• 使用语义化对比，不是比较每个像素，而是比较结构化元素的位置和大小。

这类问题没有完美解，只能根据具体项目做权衡。

5. 一个可落地的视觉前后对比工作流设计

SightDiff 的公开细节有限，但它所代表的工作流完全可以迁移到自己的项目里。下面我会给出一个不依赖特定框架的通用实现思路，代码部分用 Python 演示从截图到差异报告的核心流程。这段逻辑的目地是帮助你理解视觉对比系统的组成，而不是还原 SightDiff 的内部实现。

5.1 工作流总览

一个完整的“视觉前后对比证明”系统由四个阶段组成：

1. 基线采集：在 Agent 任务启动前，采集目标页面或产物的视觉快照。
2. 过程记录：Agent 任务执行中，按策略在关键节点采集中间快照。
3. 结果采集：Agent 任务结束后，再次采集目标页面或产物的视觉快照。
4. 差异报告：对比 before/after 快照，生成带标注的差异图和一个可读的报告。

5.2 环境准备

以下示例偏向实验验证思路，使用 Python 3.9+ 环境：

pip install pillow numpy playwright

如果没有安装 Playwright 浏览器内核，还需要执行：

playwright install chromium

说明：Playwright 在这个示例里负责打开页面并截图，Pillow 负责图像读取和像素统计，NumPy 负责差异矩阵计算。

如果你不需要浏览器截图，只对比两张本地图片文件，可以跳过 Playwright 部分。

5.3 核心代码：生成前后对比报告

下面这段代码实现了一个最小可用的视觉对比报告生成器。它会把两张图片缩放为相同尺寸，计算差异区域，并输出一张标注了差异位置的对比图。

# 文件路径：visual_diff_report.py from pathlib import Path from PIL import Image, ImageDraw, ImageChops import numpy as np def generate_visual_diff_report(before_path, after_path, output_path, diff_threshold=30): """ 生成 before/after 视觉对比报告。 参数： before_path: 任务执行前的截图路径 after_path: 任务执行后的截图路径 output_path: 对比报告输出路径（PNG 格式） diff_threshold: 像素差异阈值，0-255，值越大越宽松 """ before_img = Image.open(before_path).convert("RGB") after_img = Image.open(after_path).convert("RGB") # 统一尺寸，避免分辨率差异导致对比失效 target_size = (1280, 720) if before_img.size != target_size: before_img = before_img.resize(target_size) if after_img.size != target_size: after_img = after_img.resize(target_size) before_arr = np.array(before_img, dtype=np.int16) after_arr = np.array(after_img, dtype=np.int16) # 计算 RGB 三个通道的差异绝对值 diff_arr = np.abs(before_arr - after_arr) # 找出差异超过阈值的像素点 max_diff = diff_arr.max(axis=2) diff_mask = max_diff > diff_threshold diff_count = int(diff_mask.sum()) total_pixels = diff_mask.size diff_ratio = diff_count / total_pixels * 100 # 生成标注图 diff_visual = before_img.copy() draw = ImageDraw.Draw(diff_visual, "RGBA") # 用红色半透明遮罩标注差异区域 overlay = Image.new("RGBA", diff_visual.size, (255, 0, 0, 0)) overlay_draw = ImageDraw.Draw(overlay) # 为了性能，将差异像素按 10x10 块聚合，避免逐像素绘制太慢 y_step, x_step = 10, 10 h, w = diff_mask.shape for y in range(0, h, y_step): for x in range(0, w, x_step): block = diff_mask[y:min(y + y_step, h), x:min(x + x_step, w)] if block.any(): overlay_draw.rectangle( [x, y, min(x + x_step, w), min(y + y_step, h)], fill=(255, 0, 0, 100) ) diff_visual = Image.alpha_composite(diff_visual.convert("RGBA"), overlay) diff_visual.convert("RGB").save(output_path) return { "diff_count": diff_count, "total_pixels": total_pixels, "diff_ratio": round(diff_ratio, 2), "report_path": output_path, } if __name__ == "__main__": result = generate_visual_diff_report( before_path="artifacts/before.png", after_path="artifacts/after.png", output_path="artifacts/diff_report.png", ) print(f"差异像素数: {result['diff_count']}") print(f"差异比例: {result['diff_ratio']}%") print(f"报告路径: {result['report_path']}")

这段代码的关键逻辑有三点：

1. 统一尺寸减少了图片长宽不一致带来的干扰。
2. 阈值判定避免了 JPG 压缩、抗锯齿等微小像素波动产生大量假差异。
3. 块状标注把差异区域用半透明红色遮罩叠加在原图上，开发者一眼就能看到位置。

5.4 结合 Playwright 的截图采集

如果想对浏览器页面做前后对比，需要先解决“如何保证两次截图环境一致”的问题。下面给出一个 Playwright 截图辅助函数，重点是等待页面加载稳定后再截图。

# 文件路径：capture.py from playwright.sync_api import sync_playwright def capture_page_screenshot(url, output_path, wait_ms=2000, viewport_size=(1280, 720)): """ 打开指定 URL 并等待页面稳定后截图。 注意：先等待网络空闲，再额外等待固定时间，尽量减少动态内容干扰。 """ with sync_playwright() as p: browser = p.chromium.launch(headless=True) page = browser.new_page(viewport={"width": viewport_size[0], "height": viewport_size[1]}) page.goto(url, wait_until="networkidle") page.wait_for_timeout(wait_ms) page.screenshot(path=output_path, full_page=False) browser.close() print(f"截图已保存: {output_path}") if __name__ == "__main__": # 在 Agent 运行前执行一次 capture_page_screenshot("https://example.com/admin", "artifacts/before.png") # 这里模拟 Agent 执行任务... # 在 Agent 运行后再次执行 capture_page_screenshot("https://example.com/admin", "artifacts/after.png")

使用这个脚本时要注意：两次调用必须使用相同的 viewport_size，否则得到的截图尺寸不一致，后续对比结果会失真。

5.5 模拟 Agent 调用并输出报告

为了让流程更完整，下面用一个简易命令行脚本把 Agent 执行和视觉对比串起来。

# 文件路径：run_with_visual_proof.py import subprocess import sys from pathlib import Path from visual_diff_report import generate_visual_diff_report AGENT_CMD = sys.argv[1:] # 假设通过命令行传入 Agent 调用命令 WORK_DIR = Path("artifacts") WORK_DIR.mkdir(exist_ok=True) BEFORE = WORK_DIR / "before.png" AFTER = WORK_DIR / "after.png" REPORT = WORK_DIR / "diff_report.png" def main(): print("[1/3] 采集 before 基线...") subprocess.run( ["python", "capture.py", "https://example.com/admin", str(BEFORE)], check=True, ) print("[2/3] 执行 Agent 任务...") subprocess.run(AGENT_CMD, check=True) print("[3/3] 采集 after 结果并生成对比报告...") subprocess.run( ["python", "capture.py", "https://example.com/admin", str(AFTER)], check=True, ) result = generate_visual_diff_report( before_path=str(BEFORE), after_path=str(AFTER), output_path=str(REPORT), ) print(f"差异比例: {result['diff_ratio']}%") print(f"报告文件: {REPORT}") if __name__ == "__main__": main()

这个脚本的目地是把流程自动化：先拍基线，再跑 Agent，最后出报告。实际项目中，你可以把这三个步骤挂到 CI 流水线，或者封装成 Python 函数供 Agent 调用。

运行命令示例：

python run_with_visual_proof.py python run_my_agent_task.py

输出预期：

[1/3] 采集 before 基线... 截图已保存: artifacts/before.png [2/3] 执行 Agent 任务... ... [3/3] 采集 after 结果并生成对比报告... 差异比例: 8.35% 报告文件: artifacts/diff_report.png

如果差异比例为 0%，说明页面没有视觉变化；如果差异比例很大，就要打开报告图查看差异区域是否合理。

6. 这类工具在真实开发中的效果验证方式

接入视觉前后对比工具后，如何验证它真的提高了效率？这里给出几个实际项目中常见的验证思路。

6.1 用“故障注入”验证工具灵敏性

一种有效的验证方式是故意让 Agent 执行一个会引发视觉问题的任务，比如把某个 CSS 类的颜色值改错。如果视觉对比报告能快速定位到颜色变化区域，说明工具是可用的。

故障注入测试的价值在于：先证明工具能发现“已知问题”，再讨论它能不能发现“未知问题”。如果连已知问题都发现不了，说明对比阈值、截图时机等配置需要调整。

6.2 建立差异比例基线

不同页面的正常差异比例差异很大。一个纯静态页面在多次截图之间差异应该为 0%；一个带实时数据的仪表盘页面，即便没有任何代码改动，差异比例也可能有 5%。

因此，接入这类工具后要做的一件事是：为关键页面建立正常差异基线。没有基线，就没法判断一次差异报告上的数字是否异常。

6.3 人工复核 + 渐进式自动化

初期不要追求完全自动化判定。更稳妥的做法是：Agent 跑完任务后自动生成视觉对比报告，由开发者在 pull request 附件或 Web 面板中人工复核。等积累了足够多的历史数据，再尝试用规则或机器学习模型自动判断差异是否属于预期变化。

7. 常见问题与排查思路

下面是在实现视觉前后对比工作流时最常遇到的几个问题，以及对应的排查思路。

还有一个容易踩的坑：不要用 PNG 和 JPG 混合保存的截图做对比。两种格式的编码方式不同，即使内容完全一样，像素值也可能有微小出入，最终导致误报。项目里最好统一截图输出格式。

8. 最佳实践与工程建议

SightDiff 这类工具真正改变的不是“如何截图”，而是 Agent 工作流的反馈闭环。从工程角度看，以下几点值得重视。

8.1 把视觉对比作为一种“人工复核入口”

AI Agent 自动化程度越高，人工复核越重要。视觉对比报告就是人工复核的低成本入口。它的目标不是让开发者看每一张图，而是让开发者能在报告里快速找到“需要关注的异常变化”。

建议把对比报告接入到 Agent 任务通知里。Agent 执行完任务后，在消息中附带差异比例和报告链接。开发者扫一眼数字，就能决定是直接放行还是深入查看。

8.2 先建立基线，再谈自动化判定

视觉对比的“正常/异常”边界高度依赖具体项目、具体页面。不要一上来就预设统一的差异比例阈值。更合理的路线是：

1. 先记录一批正常运行任务的视觉对比数据。
2. 根据页面类型分组，统计差异比例分布。
3. 把阈值设置为基线的 3 倍或 5 倍标准差。
4. 随着数据积累，持续调整阈值。

8.3 注意安全和权限边界

如果在 AI Agent 中接入截图和视觉对比能力，要特别注意以下几点：

• 截图可能包含敏感信息，存储和访问必须纳入权限控制。
• Agent 修改页面或执行任务时，应使用最小权限账号，避免高权限账号的无意破坏。
• 视觉对比报告文件应设置合理的访问控制，不能随意公开。
• 在自动化流程中执行rm、mv等操作时，应先在测试环境验证，使用绝对路径并做好备份。

8.4 记录 Agent 行为上下文

纯粹的视觉对比能告诉你“变了什么”，但不能直接告诉你“为什么变”。好的工程实践是在生成视觉对比报告的同时，附上 Agent 的关键操作日志。例如：

• Agent 执行了哪些命令。
• Agent 修改了哪些文件。
• Agent 在哪个步骤之后截取了 after 快照。

这样，开发者看到异常差异时，可以直接从日志中定位到具体操作，而不是对着两张图猜原因。

8.5 版本兼容与多环境支持

视觉对比系统对环境稳定性要求很高。在实际项目中，最好固定浏览器版本、依赖版本、截图工具版本。否则，浏览器升级导致渲染引擎变化，也可能产出“非 Agent 造成的视觉差异”。

推荐做法是在项目目录下维护requirements.txt或使用容器化环境，保证 Agent 任务执行环境和截图对比环境一致。

9. 总结与后续学习方向

SightDiff 值得关注，不是因为“截图对比”这个技术动作有多新颖，而是因为它代表了一类正在出现的工具思路：AI Agent 的执行结果需要被外部验证，而视觉验证是“外部验证”里最直观、最容易被非技术角色理解的形式。

如果你正在做 AI Agent 的工程化，可以考虑沿着以下方向继续深入：

1. 语义化视觉对比：不再逐像素比较，而是识别页面中的按钮、卡片、图片、表格等元素，对比元素的位置和属性变化。
2. 多步骤 Agent 的节点级验证：不只对比任务开始和结束，而是把每个关键 Agent 步骤的视觉变化都纳入记录。
3. AI 辅助差异分类：用多模态模型自动判断差异属于“预期修改”还是“回归问题”，降低人工审核成本。
4. CI/CD 集成：将视觉对比报告集成到代码评审流程中，作为 AI 提交的扩展证据。

SightDiff 这类工具的成熟度目前仍处于早期阶段，具体实现还在快速迭代。但方向已经足够明确：AI Agent 越强大，我们越需要可靠的“证明手段”来验证它真的做对了事。视觉前后对比，是最直接的一种证明。

如果你正在构建自己的 AI Agent 工作流，建议先从最小可用方案开始：一个截图工具、一个像素差异脚本、一份对比报告。跑通之后，再逐步补充语义化分析和自动化判定。这套基础能力，迟早会用在你的下一个 Agent 项目里。