企业官网建设流程全解析

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 文本日志和视觉对比的差别在哪里

文本日志解决的是"发生过什么"，视觉对比解决的是"最终长什么样"。两者互补，但不能互相替代。

如果只用日志，出了问题要花很长时间脑补当时画面。如果是视觉对比，直接打开前后的对比图，一眼就能看出 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 页面中的标题颜色，或者生成一张固定尺寸的图片。

流程可以拆成这样：

1. 准备一个固定输入文件。
2. 在 agent 执行前调用一次快照逻辑，保存为 before 图片。
3. 让 agent 执行修改任务。
4. 在 agent 执行后再次调用快照逻辑，保存为 after 图片。
5. 把 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(f"shots/{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 没有输出对比图先查什么

如果一切配置完成，但最终没有对比图，先不要怀疑对比算法。按顺序排查：

1. 检查快照是否真的被调用了。可以在快照函数里加日志，打印保存路径。
2. 检查保存目录是否存在，是否有写权限。路径不存在是高频原因。
3. 检查 before 和 after 的命名是否一致，避免任务 ID 对不上。
4. 检查是否有覆盖逻辑，比如多个任务复用同一个文件名，后执行的任务把前一个任务的结果覆盖了。
5. 检查输出目录是否被清理脚本删了。

这里有个经验：很多"对比失败"其实不是工具本身的问题，而是任务脚本里快照顺序不对。比如 after 快照在 agent 任务真正完成前就触发，或者 before 和 after 抓的是不同页面状态。

5.2 对比错位、误报差异怎么处理

视觉对比最常见的误报，是页面内容没变，但截图看起来差异很大。原因通常是：

• 浏览器窗口尺寸变化，导致布局位移。
• 页面滚动位置不一致，截取的内容区域不同。
• 字体渲染、图片加载、动画导致的微小像素差异。
• 动态广告、时间组件、随机内容造成的干扰。

处理方式也比较明确：

• 统一浏览器窗口大小和缩放比例。
• 快照前强制滚动到固定位置，或直接截取整个页面。
• 等待网络请求完成，静态资源加载完毕再截图。
• 对比时设置忽略区域，把动态元素排除在外。
• 适当降低像素级要求，改看较大区域的差异比例。

如果是图片文件类的 before/after，也要注意格式差异。比如 before 是 PNG，after 被转成了 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 工作流里的可信证据层。