导读

质量检查这件事，能不能往前挪一挪？

通过前置的审查、运行时验证、视觉验证等系统化能力建设，让Agent在开发过程中就按项目工程规范完成自检和修复。提高上游交付质量，减少返工——这是现在真正值得投入的方向。

背景

AI Coding确实把开发速度提上来了，但速度快不等于交付质量高。

Agent写得快，也错得快——它不清楚项目的工程约定，写完代码也不会自己打开浏览器看一眼页面到底能不能跑。

传统质量保障依赖提交后的人工CR和QA测试。但在Agent高频产出代码的场景下，所有问题都等到后面环节才发现，协作成本只会越来越高。

所以我们做的事是：把质量检查嵌入Agent的工作过程本身，将验证流程左移，提高上游交付质量，减少下游返工。

整条链路是这样的：

Agent Operating Rules定义操作协议，约束Agent在项目里怎么干活
↓
Code Validation写完代码当场CR，不等提交
↓
Runtime Verify改了UI就连浏览器验证
↓
Figma To Verify重点页面对设计稿做视觉走查
↓
Pipeline Code Review提交后大规模复审
↓
问题结构化 → Agent辅助修复 → 重新验证
↓
沉淀为Skill / Rules，持续复用

下面按这条链路，逐个讲每个节点都做了哪些事情。

01 Agent Operating Rules：把工程规范变成执行协议

Agent靠通用知识写代码，但不知道项目自己的规矩。Prompt是一次性的，聊完就丢。项目规则是长期的、稳定的、每个任务都要遵守的。

我们在项目根目录的rules下维护索引文件，作为Agent在这个项目里的操作协议，包含：

渐进式加载规则

不同类型的改动需要遵守不同的工程约定，比如状态管理的规范、业务统一的请求类封装、构建配置有多少地方需要同步修改。

这些约定分散在各自的rules文件里，作为项目的私域知识，让Agent可以在执行对应类型的任务时加载进来补充上下文。

关键时机触发验证Skill

协议里定义了两道门禁：

• 所有代码改动完成后，必须启动独立subagent执行code-validation Skill做即时CR，不能被跳过，不能用lint或build替代。

• 如果任务涉及UI（组件变更、样式修改、交互调整），必须通过CDP连接真实浏览器执行visual-verify Skill。CDP不可用时不能假装验证。

02 Code Validation：让Agent写完即CR

传统Code Review发生在提交后，问题已经进入协作链路。但Agent开发时，很多问题可以在“刚写完”的时候立刻发现——没按约定的方式引入依赖、用了项目已经废弃的写法、新增代码和项目既有的工程约束冲突、改了一处配置但没同步关联的其他配置。

而且因为有任务的上下文，这些问题的修复能变得十分准确，不用去猜“当时代码为啥这样，我应该改成啥样”。

这些问题如果等到流水线CR才暴露，再经历修复，时间和成本都更大了。

2.1 具体实现

code-validation是一个指导模型CR关注哪些内容的Skill，提高开发阶段产出的代码质量。

Agent完成一批代码改动
↓
启动独立subagent（不是主Agent自己检查）
↓
subagent加载rules.md（项目验证规则合约）
↓
只审查changed lines + 必要上下文
↓
按CR风格输出问题报告（Error / Warning / Info）
↓
主Agent修复问题
↓
通过后才允许继续

这里用独立subagent的原因：Agent会倾向于给自己的代码打高分。独立subagent相当于切换视角，用新的上下文、站在reviewer的位置审查，减少“自己写的看着都对”的盲区。

2.2 项目验证规则合约

在skill中定义了这个项目里什么是对的、什么是错的，分两层：

通用检查：包括但不限于类型安全、生命周期、组件边界、错误处理等通用内容，同时让模型积极地探索其他可能存在的问题并报告。

项目专属的阻塞规则：这层规则对应的是团队自己的工程约定，比如用哪个UI库、样式写法是否符合规范要求、数据请求走哪个封装、多套构建配置之间怎么保持同步。针对每个特殊规则都附带了具体的判断标准和正确写法的示例，告诉模型什么是对的。

2.3 复用

同一个code-validation Skill在两个场景下使用：开发期作为Agent的即时CR，流水线上作为Pipeline项目特定的Code Review的规则注入，两边维护一套规则即可。

03 Browser Use：让Agent在真实浏览器里工作

代码没报错不等于页面没问题。页面打不开、弹窗被裁切、控制台报错、接口失败、布局在某些条件下塌陷了，只靠看代码是发现不了的。

所以我们做了visual-verify，让Agent通过CDP连接真实浏览器，在里面做DOM断言、截图、检查console、给元素画标注框。

下面用三个真实案例讲这套能力怎么工作。

3.1 能力基础：visual-verify skill

visual-verify使用Contract模式工作：

1. Agent用JSON描述期望的页面状态（哪些元素存在、可见、在什么位置、点击后发生什么）。

2. 先跑contract-lint做静态校验，避免格式问题浪费浏览器执行。

3. 再跑dom-assert在真实浏览器里执行断言。

4. 所有结果写入contract.md作为验收记录。

除了断言，还有几个关键能力：

• 标注截图（annotate-screenshot）：在页面元素上画标注框并编号，用于空间问题的可视化诊断。标注框直接画在真实元素上，如果元素被裁切或遮挡，标注框也会被裁切，真实反映页面状态。

  截断的红框表明了元素无法完全展现

  修复后红框完整，问题被解决

• console检查（console-check）：监听CDP的console事件，捕获运行时错误。

• Memory机制：跨任务积累页面知识，稳定的选择器、已知的时序问题、可复用的检查脚本。新任务启动时先读memory，避免重复探索。

3.2 案例一：快捷回复功能，Agent完成交互需求闭环

背景：让Agent实现一个快捷回复功能，评论管理页面的回复框旁边加一个按钮，点击弹出面板，面板里有分类标签、搜索、短语卡片，点击短语回填到输入框。

Agent写完代码后，按Agent Operating Rules的要求进入visual-verify。接下来发生了三轮“发现问题 → 修复 → 再验证”的循环。

3.2.1 第一轮：页面直接崩了

Agent打开页面，看到的不是评论列表，而是Error Boundary——“服务器开了小差，请稍后重试！”。

代码有运行时错误导致React组件树崩溃。Agent通过console-check获取控制台错误信息，发现card/index.tsx里访问一个全局状态为undefined，Agent迅速定位问题是访问与请求数据顺序错乱，快速完成了修复。

修复后重新截图发现变成正常

不打开浏览器根本不知道页面已经崩了。在Agent开发场景下，如果没有浏览器验证这一步就会被直接跳过。

3.2.2 第二轮：面板被overflow:hidden裁切

页面恢复后，Agent点击快捷回复按钮，面板出现了，但上半部分被截断，搜索框和分类标签看不见，只露出短语卡片的下半截。

Agent用annotate-screenshot给面板区域画红色标注框，给回复框画蓝色标注框。截图上可以清楚地看到：面板的红框上半部分被父容器截断。

面板定位在回复框上方，但是这个面板超出它上层元素的部分被裁掉。Agent根据标注截图定位到具体的DOM层级和样式，修复后面板完整展示。

DOM断言会告诉你“元素存在”，但不会告诉你“元素被裁切了一半”。标注截图的价值就在这里：把“看起来不太对”变成可定位的视觉证据。

3.2.3 第三轮：功能逻辑验证

布局问题修完后，Agent继续验证全部功能点：

• 切换分类标签（“感谢类”→ 过滤出2条短语）

• 搜索关键词过滤

• 点击短语回填输入框（字数计数器17/500，回复按钮变蓝）

• 最近使用区出现

• 添加短语弹窗

• 删除前二次确认弹窗

• localStorage持久化

最终输出contract.md验收记录，约定的checkpoint全部通过。

3.2.4 小结

三轮验证分别抓到了三类问题：

把验证前移到Agent写完代码的当下，问题在几分钟内闭环，不用等到后面的环节才暴露。

3.3 案例二：RSpack HMR调试，让Agent独立完成工程诊断

背景：项目用RSpack + Module Federation构建。开发中发现两个问题：修改文件后页面不更新；即便HMR生效了，每次增量构建也要2秒以上。

只告诉Agent这两句话。它连接浏览器后，独立完成了全部定位和修复。

HMR不生效。Agent在控制台看到HMR消息到达了但UI没变化。检查React Refresh runtime挂载情况后，发现ReactRefreshPlugin的library参数和output.uniqueName不一致，Refresh runtime挂载到了错误的命名空间，组件静默跳过重渲染。对齐配置后修复。

构建时间虚高。控制台报2400ms，但Agent查看计时插件源码后发现其中1000ms是人为加的防抖延迟。去掉防抖后真实数据是480ms。

真实耗时仍偏慢。去掉防抖后继续排查，发现两个原因：SWC的polyfill分析在dev环境下无意义但每次HMR都在执行；Module Federation的manifest插件在每次增量构建时重新做资产分析。关掉这两项后，增量构建降到合理范围。

顺带发现端口冲突。排查过程中还发现MF的dts: { generateTypes: false }和dts: false语义不同——前者只是不写出类型文件，DTS插件本身和它的内部WebSocket server仍然启动并占用端口。

最终优化效果：

3.4 案例三：Figma To Verify，把“感觉不像”变成量化问题

3.4.1 问题

视觉走查是QA和前端协作中的老难题。设计稿和开发页面不是天然可比的——设计稿是局部，开发页是完整页面；图片、文案、数据都可能不同；直接截图做像素diff会产生大量无意义的红区。

人眼走查能发现明显问题，但容易漏掉间距差2px、字号差1px这种微妙差异。

我们想做的是：把视觉差异变成可确认、可量化、可标注的问题。

3.4.2 整体流程

Figma设计稿
↓
figma-to-html（将指定Node导出为高还原HTML）
设计稿HTML基准页
↓
chrome-cdp（两个独立Tab打开设计页和开发页）
↓
element-screenshot（只截取目标元素，排除无关内容）
双页元素截图
↓
vet-generator（生成VET并对齐颜色）
6张分析图（2原始 + 2 VET + 2 Diff）
↓
vet-investigation（识别候选问题）
N个候选问题
↓
visual-issue-clarification（每个问题单独subagent复核、量化、标注）
最终视觉走查报告

这条流程由7个Skill组合完成（chrome-cdp、element-screenshot、figma-to-html、vet-generator、vet-investigation、visual-issue-clarification、visual-diff作为顶层路由）。下面讲其中三个关键技术点。

3.4.3 技术点一：VET，把动态内容抹掉，只留结构

VET（Visual Expression Tree）将页面中有语义的元素标记为纯色色块，文字、图片、图标等动态内容全部替换，只保留元素的位置、大小和层级信息。

为什么需要它？设计稿和开发页面之间存在大量内容差异：图片不同、文案不同、数据不同、DOM结构也不同。直接对两张截图做diff，红区几乎覆盖整个页面，没有任何可用信息。VET把这些动态差异消除，让对比聚焦在布局和结构上。

原始截图DIFF，非常杂乱

VET的DIFF，更清晰的表达结构差异

3.4.4 技术点二：VET对齐，解决DOM深度不一致的问题

VET的自动着色基于DOM深度：深度7是紫色，深度14是青色。但设计稿导出的HTML和实际开发页面的DOM结构完全不同。同一个视觉元素（比如一个卡片），在设计页DOM深度7，在开发页因为多了Provider、Layout等包装组件变成了14。直接用自动着色，同一个语义元素在两边颜色不同，diff就会标为差异，这不是布局差异导致的，是DOM结构差异带来的噪声，应该被消除。

vet-generator的解法：先只在设计页上跑自动VET建立颜色方案，然后由Agent分析两边DOM、识别语义对应的元素，在开发页上手动注入相同颜色。这个过程是程序能力+浏览器操作+Agent语义理解的组合，不是纯算法能搞定的。

不同环境VET

3.4.5 技术点三：问题复核，看CSS看computed style

VET diff阶段会识别出一批候选问题（间距异常、对齐偏差、元素缺失、尺寸不一致等），但候选问题不一定都是真的。每个问题会启动一个独立Subagent做四件事：

1. 复核：回到DOM和运行时样式里确认问题是否真实存在。

2. 量化：用getComputedStyle()测量具体数值，包括间距、字号、颜色值、对齐偏差，精确到px。只看运行时最终生效的样式，不看静态CSS声明。

3. 标注：通过注入SVG在页面上画框、标数值、写说明，然后截图。让人一眼看懂问题出在哪。

4. 排查线索：记录是哪个DOM元素、哪个class、哪个嵌套层级导致的，为修复提供起点。

正确设计标注

对应开发也标注

3.4.6 Figma To Verify的价值

把“感觉不像”变成可确认的（排除误报）、可量化的（精确到px和色值）、可标注的（在页面上可视化）、可修复的（提供排查线索）问题。

04 Pipeline Code Review：提交后的大规模复审

开发期的code-validation关注当前任务的增量改动，Pipeline Code Review关注一次提交的完整变更。两道不同的关卡，分别覆盖不同的审查范围和时机。

人的阅读量非常有限，大量diff人很难一次看过来；单Agent审大diff容易遗漏；分文件CR缺少上下文关联；历史遗留代码和多时代规范混杂会干扰模型判断；Review结果不可追踪，和修复链路断开。

4.1 核心思路

把大diff拆成小块，并发派发给多个AI子进程独立审查，最后合并结果。

整个流程分5个Phase：

Phase 0 — 拆Diff。逐行解析unified diff，按目录前3级分组（同模块的文件优先放在一起，保留上下文关联），再在模块内按行数做bin-packing，每个chunk控制在500行以内。

Phase 1 — 状态检查。用纯文本的task.log管理任务状态，支持中断恢复——跑到一半挂了，重启后只处理pending的任务。

Phase 2 — 并发派发。这里用CLI子进程而非subagent。CLI的prompt由脚本程序化生成，避免模型理解偏差和上下文抄写开销，并发数可以开到10个以上。每个chunk审查完写一个result JSON，用文件系统追踪进度（File as Progress）。进程收到终止信号时做优雅关闭，已完成的标completed，未完成的标failed，保证状态一致。

Phase 3-4 — 合并汇总。收集所有result，按文件维度聚合成最终review.json。

4.2 Prompt设计

几个要点：severity分三档（error / warn / style），每档用few-shots约束分类边界；输出强制6个结构化字段，便于后续程序化处理；子进程写完result后必须JSON.parse()回读验证，格式问题在单次CR内闭环修复，不透传到调度层。

4.3 后续链路

CR产出的结构化数据可以驱动后续修复流程：

• 可视化报告页面：展示issue，支持按severity过滤、批量选择。

• 唤起IDE修复：页面上拼接修复prompt，直接调起Comate IDE。

• 自动批量修复：按文件分组，每个文件一个独立git worktree + 一个子进程，互不干扰。按变更行数从小到大依次merge（小改动冲突概率低，优先合入），每次merge后跑构建验证，失败则revert。全部完成后git reset --soft消除中间commit历史。

• 闭环标记：收集修复结果，批量标记已修复的issue，完成CR → 修复 → 标记的全链路闭环。

• 现场集成：厂内开发者的CR是在iCode进行的，让他们直接在这个现场就能看到问题、快速修复无疑是最好的。我们已经基于OpenClaw + BrowserUse初步打通了iCode集成，经实验发现集成到iCode能极大地增加开发者接收问题解决问题的积极性。

超大量的CR例子

修复问题

集成openclaw review

05 从工具到工程资产

回到开头的全链路：

Agent Operating Rules→ 约束Agent怎么干活
Code Validation→ 写完即CR
Runtime Verify → 改了UI就看浏览器
Figma To Verify→ 对设计稿做视觉走查
Pipeline Code Review → 提交后大规模复审
问题结构化 → 修复 → 验证 → 沉淀

这些关卡能持续复用和迭代：

• 项目工程规范沉淀为Agent Operating Rules，每个任务自动生效。

• 代码审查经验沉淀为code-validation的rules.md，开发期和流水线共用。

• 页面验证经验沉淀为visual-verify的memory，跨任务积累。

• 视觉走查能力沉淀为Figma To Verify的Skill组合，可复用于任意页面。

• QA发现的高频问题可以反向写入Rules和Skill，下次Agent直接避免。

一次检查只是工具，能持续复用和沉淀的检查机制，才是团队工程化资产。

对RD和QA协作的意义

过去：RD写完代码 → QA测出问题 → RD修 → QA回归。低级问题和高价值测试混在一起。

现在：RD + Agent完成实现，QA将测试经验和能力赋能到开发环节，通过左移将质量控制前置。code-validation做开发期CR，visual-verify做运行时验证，Figma To Verify做视觉走查。RD带着验证结果交付，QA进一步在复杂业务风险和用户场景上配合Agent自动化，全面保障项目质量。

06 附录

OpenClaw配备review的Skill：bjh-fe-assets.cdn.bcebos.com/assets/icod…

browser相关的skill：github.com/hixuanxuan/…

安装方式：

1. 只安装visual-verify，用于日常开发的验证工作。

npx skills add hixuanxuan/browser-automation --skill visual-verify

2. 安装figma走查相关的skill。

npx skills add https://github.com/hixuanxuan/browser-automation/tree/main/figma-to-verify

3. 我只想用CDP，做基础的截图、获取DOM、获取HTML等工作，或者在此基础上封装其他的browser Skill。

npx skills add hixuanxuan/browser-automation --skill chrome-cdp