SightDiff：用前后视觉对比为AI Agent行为提供可审计证据

SightDiff 这个名字看起来像一个截图小工具但它实际解决的问题是很多 AI agent 开发者跑完任务之后最头疼的一句话刚才那个 agent 到底改了哪些东西它的定位是从 agent 执行过程里抽取出前后对比的视觉证据用 before/after 图像、差异标注和报告把 agent 改了什么、改到哪里、效果是否可控展示出来。如果你正在做 agent 开发、接 agent 处理自动化任务或者需要给 agent 的行为做验收这个方向很值得先看一遍。接下来我按实际落地顺序拆开讲先说什么场景需要它再讲怎么设计 before/after 快照流程然后是批量任务和排查思路最后是我的落地建议。1. 先搞清楚 SightDiff 到底解决什么问题1.1 AI agent 跑完任务后你知道它改了什么吗很多 agent 任务的痛点不是跑不通而是跑完没人知道发生了什么。命令输出是文本、日志是文本、模型返回也是文本一旦 agent 修改了网页布局、替换了图片、生成了新的前端页面、调整了配置文件你很难通过字符串 diff 判断最终效果。我见过不少项目agent 自己觉得任务已经完成实际页面上按钮位置跑偏了或者生成的图片尺寸不对。这时候你需要的不只是有没有报错而是改动前后的视觉状态对比。SightDiff 这类方案的价值就在这个环节它把 agent 行为的验证从看日志升级为看证据。有一种常见误解是agent 开发主要看代码能不能跑通。实际上代码跑通只完成一半另一半是验证结果是否符合预期。尤其涉及 UI 生成、图像处理、文档排版、网页抓取后重构的场景视觉对比往往比代码 inspect 更直接。1.2 文本日志和视觉对比的差别在哪里文本日志解决的是发生过什么视觉对比解决的是最终长什么样。两者互补但不能互相替代。对比维度文本日志视觉对比记录内容tool 调用顺序、参数、返回值、报错信息页面、图片、界面、布局、渲染效果的状态变化排查方式靠脑补还原当时画面直接看前后对比图一眼定位变化区域适合场景确认任务流程是否正常确认最终视觉效果是否符合预期主要缺点长日志阅读成本高难以描述视觉变化需要设计快照时机和存储策略如果只用日志出了问题要花很长时间脑补当时画面。如果是视觉对比直接打开前后的对比图一眼就能看出 agent 把哪块改了。所以SightDiff 的定位不是替代调试工具而是给 agent 的执行结果补一层可审核的视觉证据。1.3 什么样的改动才值得做可视化对比不是所有 agent 改动都适合截图对比。纯 API 调用、只改数据库字段、只生成 JSON 数据这类任务文本 diff 和结构化 diff 更高效截图反而增加资源成本和干扰。更适合视觉对比的场景我一般看三个特征结果最终要给人看网页、图片、海报、PPT、文档排版这些交付物本身就有视觉属性。改动容易产生局部影响比如一个按钮颜色变了、一个图片被替换、一段文字溢出文字日志很难表达清楚。人工检查成本高任务一多不可能每次都肉眼比对需要自动生成前后差异图。判断标准很简单如果任务结果最终是要给人看的视觉对比大概率值得做如果任务结果只是一份数据或一个状态日志和结构化 diff 更直接。2. SightDiff 适合放进哪一类 agent 工作流2.1 典型使用场景从项目定位来看SightDiff 面向的是 AI agent 场景但它并不是只适合一个 agent 跑一次任务的简单玩法。实际能落地的场景大致分成三类。第一类agent 开发调试。开发者在本地跑 agent 时经常需要判断某次 Prompt、某个 tool、某个参数调整后输出效果是不是真的变好了。如果每次调整都重新肉眼观察效率太低。用 before/after 视觉对比可以直接比较两次运行的差异。第二类自动化任务验收。agent 帮你去生成海报、改网页、整理 PPT、批量处理图片时最终交付物长什么样、有没有破坏原版式需要一份可留档的证明。视觉对比报告可以当作验收记录。第三类团队协作审核。多个人一起开发 agent 产品时不能每个人都在本地跑一遍看效果。把 before/after 结果输出成图片或报告放在共享目录、项目文档或任务评论区整个团队都能快速确认这次改动是否可接受。2.2 和 agent 框架、MCP、skill 的关系现在 agent 周边概念很多比如 agent 框架、MCP、agent skill、多 agent 设计。这里要说明一下SightDiff 这类工具跟它们不是竞争关系更像是一层审计和可视化外壳。agent 框架负责编排任务和 tool 调用MCP 负责让 agent 连接外部能力skill 负责封装可复用的能力而 SightDiff 关心的是执行前后状态是否可视化可验证。你可以把视觉对比能力接在 agent 的 tool 调用前后也可以放在整体任务跑完的前后。如果你用的是已有的 agent 框架接入思路一般是找到 agent 执行任务的入口和出口。在入口前抓一次 before 快照。在出口后抓一次 after 快照。对比并输出报告。这个思路不依赖具体框架属于通用接入方式。具体到某个框架怎么接要看框架是否支持 hook、中间件、tool 回调。从当前公开信息看SightDiff 的具体接入接口还不算完整落地的时候先看官方 README 里的例子确认它默认假设你用什么方式触发快照。2.3 接入前需要确认的条件使用视觉对比方案不能等到 agent 任务开始后再临时抓快照。建议先确认几个条件。快照来源是什么是网页截图、屏幕截图、图片文件还是文档渲染图。快照能力由谁提供SightDiff 自己抓还是依赖你的脚本在 agent 执行前后调用。对比方式是什么两张图直接并排还是输出带差异高亮标记的图片。输出保存到哪本地目录、对象存储还是项目附带报告。运行环境是什么本地命令行、服务端定时任务还是接进 CI/CD。这些条件决定你要准备多少代码和配置。如果只是本地验证最简单的流程是自己写两个快照函数任务前调一次任务后调一次再把两张图交给对比层生成结果。如果你希望直接拿到一体化的体验就要看它是否自带截图能力和报告模板。3. 本地跑通 before/after 对比的最小路径3.1 规划快照点在 agent 执行前后分别抓取状态我建议第一次测试先把范围压缩到最小。不要一上来就测多文件批量任务也不要同时追十几个 tool 调用。先选一个可以稳定复现的小任务比如让 agent 修改一个 HTML 页面中的标题颜色或者生成一张固定尺寸的图片。流程可以拆成这样准备一个固定输入文件。在 agent 执行前调用一次快照逻辑保存为 before 图片。让 agent 执行修改任务。在 agent 执行后再次调用快照逻辑保存为 after 图片。把 before 和 after 交给对比层生成并排对比结果。这里的关键点在于快照点要选择视觉状态稳定的时机。如果目标是网页一定要等页面加载完成、字体渲染完成后截图如果目标是图片文件直接对文件内容做渲染图即可。如果 agent 执行过程中页面有动画、弹窗、滚动加载就要在快照前做一次等待或复位。3.2 生成对比结果两张图并排、差异标注、报告保存对比结果的形式通常有三种。左右并排最简单适合人工判断。差异高亮把变化区域用颜色标记出来适合快速定位。像素级差异数值适合自动化判断是否发生明显变化。如果只是调试用左右并排加差异高亮就够了。如果要做自动化测试可以在对比层加一个阈值超过多少变化量就判定为改动过大。输出报告我一般建议包括任务 ID、快照时间、before 图、after 图、差异标记图、差异面积比例。如果它支持导出 HTML 报告那就更便于查看和归档。这里我补充一个思路层面的示意具体 API 以项目文档为准# 示意一个最小化的 before/after 快照流程 task_id task-demo-001 def take_snapshot(tag, task_id): # 按照当前输入文件渲染可视快照 save_image(fshots/{task_id}_{tag}.png) take_snapshot(before, task_id) agent.run_task(modify_html, task_id) take_snapshot(after, task_id) generate_diff_report(shots/, task_id)这段代码只是帮你理解流程怎么组合不是官方调用方式。实际使用时优先看项目 README 里的例子确认提供的接口和你自己代码之间怎么对接。3.3 先验证单条任务再看批量单条任务跑通不等于批量任务能跑。我见过不少情况是单条任务时 before/after 都很正常一开批量就出现覆盖写入、命名冲突、磁盘空间不足、对比结果错乱。所以验证顺序非常重要第一步只跑一条任务确认 before、after、对比图都正常生成。第二步跑三条不同输入的任务确认任务之间不会互相覆盖。第三步再加循环连续跑 20 条观察耗时、磁盘占用、失败重试。如果在单条阶段都没看到对比结果先不要急着调并发、调参数回到快照逻辑和目录权限上排查。注意这里不要一上来就开最大并发先用一条样例确认输入、输出和日志都正常。4. 批量任务和复杂场景下的稳定性设计4.1 输入、输出、命名、存储四个维度都要有规则批量跑视觉对比最容易踩的坑就是文件命名和存储规则。很多对比失败不是算法问题而是 before 和 after 被存到了不是同一批的地方。我建议按这个思路设计输入规则每个任务有一个独立输入目录或者一个 task id。输出规则所有快照和报告都以 task id 为前缀。命名规则建议使用任务 ID_阶段_序号.png不要只叫 before.png / after.png。存储规则同一个任务的 before、after、diff、report 放在同一层目录或者用子目录区分。例如output/ task-001/ before.png after.png diff.png report.md task-002/ before.png after.png diff.png report.md这样即使跑几百个任务也能快速定位某个任务的结果。另一个容易被忽略的问题是清理策略。每次任务都生成多张截图长时间跑下来占用会很大。建议按需保留调试阶段保留全部快照正式跑批量时可以只保留 diff 图和报告before/after 图按策略归档。4.2 多 agent、多步骤任务如何定位差异在多 agent 场景下使用 before/after 视觉对比时最需要明确的一点是你对比的是整个任务的前后还是某个 agent 步骤的前后。两种粒度各有用途整体任务粒度适合验收最终效果简单直接。步骤粒度适合定位到底哪个 agent、哪一次 tool 调用导致变化异常。如果你的系统里有多个 subagent 协作建议在整体对比之外额外给关键步骤做一个轻量快照。步骤粒度不需要做到每一步都截图否则会产生大量图片。只对高风险步骤记录比如文件写入、页面生成、图片合成、配置修改。定位差异时可以按顺序回放每个步骤的 before/after 图找到变化发生的那一步。这一步再结合日志就能比较准确判断是 Prompt 问题、tool 参数问题还是输入数据问题。4.3 何时把对比结果交给接口或自动化测试如果视觉对比只是给人看那它可以停留在辅助验收层面。但如果你想长期维护 agent 任务质量就应该把对比结果接进自动化流程。一个比较实用的做法是每个任务生成一份结构化结果包含差异面积、差异图路径、耗时、是否通过。设定判断规则比如差异面积超过 15% 就标记为需要人工确认。把判断结果写入测试报告方便在持续集成里展示。这样做的好处是agent 改动引出的视觉回归可以尽早被发现。特别适合那些每天要自动更新页面、自动批量生成素材、自动排版文档的团队。5. 常见问题和排查顺序5.1 没有输出对比图先查什么如果一切配置完成但最终没有对比图先不要怀疑对比算法。按顺序排查检查快照是否真的被调用了。可以在快照函数里加日志打印保存路径。检查保存目录是否存在是否有写权限。路径不存在是高频原因。检查 before 和 after 的命名是否一致避免任务 ID 对不上。检查是否有覆盖逻辑比如多个任务复用同一个文件名后执行的任务把前一个任务的结果覆盖了。检查输出目录是否被清理脚本删了。这里有个经验很多对比失败其实不是工具本身的问题而是任务脚本里快照顺序不对。比如 after 快照在 agent 任务真正完成前就触发或者 before 和 after 抓的是不同页面状态。5.2 对比错位、误报差异怎么处理视觉对比最常见的误报是页面内容没变但截图看起来差异很大。原因通常是浏览器窗口尺寸变化导致布局位移。页面滚动位置不一致截取的内容区域不同。字体渲染、图片加载、动画导致的微小像素差异。动态广告、时间组件、随机内容造成的干扰。处理方式也比较明确统一浏览器窗口大小和缩放比例。快照前强制滚动到固定位置或直接截取整个页面。等待网络请求完成静态资源加载完毕再截图。对比时设置忽略区域把动态元素排除在外。适当降低像素级要求改看较大区域的差异比例。如果是图片文件类的 before/after也要注意格式差异。比如 before 是 PNGafter 被转成了 JPEG颜色空间不同对比时会出现大量无关差异。最好在任务开始前约定统一的图片格式和分辨率。5.3 资源占用和运行时间问题截图类任务通常比较吃资源。尤其是网页截图浏览器实例、内存占用、磁盘写入都会叠加。批量跑时发现速度变慢一般不是模型变慢了而是截图和文件存储占了大量时间。如果遇到这个问题可以考虑降低快照分辨率。不是所有对比都需要 2K 截图长边 1280 通常够用。限制并发数量。不要一次开太多浏览器实例。减少历史快照保留数量设置保留最近 N 个任务。把快照生成和对比计算拆开先抓图空闲时再异步生成 diff。记住一个原则默认配置适合先跑通和验证结果一旦进入批量生产就必须考虑资源上限和清理策略。6. 我建议的落地顺序和扩展方向6.1 先做 Audit 层再考虑可视化如果你的 agent 系统还不够完善我建议先不要急着把视觉对比做成一个重模块。先在系统里加一层轻量 Audit 层记录每次任务的输入、输出、关键文件路径、状态变化。有了这个基础再接 before/after 可视化会自然很多。Audit 层解决的是数据可追溯可视化解决的是结果可读。没有前者只靠截图过几天就不知道某张图对应的代码版本、Prompt 版本和数据来源是什么。有了前者哪怕视觉对比暂时不完善也能靠结构和文件线索做排查。6.2 从一次性脚本到持续验证第一次使用可以是一次性脚本跑一个任务生成一组对比图人工看一眼结束。这是验证工具是否适合你的最快方式。如果确认有效建议按三个阶段扩展第一阶段每次 agent 任务完成后自动生成对比报告。第二阶段把对比结果汇总到项目文档或测试记录里。第三阶段接入自动化判断规则让系统在改动异常时自动标记。到第三阶段视觉对比已经从看效果的工具变成了agent 行为质量的一道检查闸门。这也是我更推荐的方向因为单靠人肉看截图不可能每天覆盖大量任务。6.3 边界和最终建议不是所有 agent 任务都适合做视觉对比。像纯 API 调用、纯文本转换、只修改少量配置数据的任务文本 diff 或结构化 diff 就够用了截图反而增加资源成本和干扰。更适合视觉对比的场景包括网页生成和页面修改。图片处理和素材生成。文档排版和 PPT 类输出。需要交付视觉效果符合预期的 agent 任务。从当前公开信息看SightDiff 的具体接口和部署方式还需要以项目文档为准。我建议先在你的环境里用最小样例亲手复现一次完整的 before、agent 执行、after、对比报告流程。这一步跑通之后再考虑批量任务、多 agent 分支和自动化判断。如果只是学习 agent 开发这个方向尤其值得动手试它不需要复杂的模型训练也不需要改 agent 的核心逻辑只要在任务前后加一层快照和对比就能让整个 agent 工作流变得可审计、可复盘。踩过几次之后你会发现很多视觉对比问题的根源不是工具能力不够而是快照时机、文件命名和运行环境没有提前处理干净。把这三样管好SightDiff 才能真正成为 agent 工作流里的可信证据层。