impeccable：AI coding agent 前端设计审查的 CLI 与浏览器扩展实践

1. 从“impeccable”这个词说起：它到底在解决什么问题

第一次看到“impeccable”这个词，很多人会以为是某个新出的前端框架或者设计系统。实际上，它跟 AI coding agents 的代码质量把控有关，更准确地说，它是一套围绕 CLI 工具链和浏览器扩展构建的“前端设计审查”思路。你如果最近在折腾 codex cli、zcode cli、openspec cli 这类命令行工具，大概率已经感受到一个痛点：AI 帮你写代码很快，但写出来的前端界面往往“能用但不好看”，间距、对齐、配色、层级关系总差那么一口气。

impeccable 要解决的就是这“一口气”的问题。它的核心主张是：在 AI coding agent 完成代码生成之后，不要直接交付，而是通过一套可复用的检查流程，把前端设计的细节标准固化下来，让 agent 自己或者由人来执行一轮“设计层面的 lint”。这听起来有点像 ESLint，但检查的不是语法，而是视觉呈现的合理性。

适合谁来参考？三类人最受益。第一类是正在用 codex cli 或类似 CLI 工具做前端项目的开发者，你们已经尝到了 AI 写代码的甜头，但被设计细节拖了后腿；第二类是团队里负责 UI 规范落地的前端负责人，你们需要一套能塞进 CI 流程的检查机制；第三类是对 browser extension 感兴趣、想通过扩展来辅助设计审查的工程师。不管你是哪一类，下面这些内容都是从实际项目里摸出来的，不是纸上谈兵。

2. 整体设计思路：为什么要在 CLI 和浏览器扩展之间做文章

2.1 核心矛盾：AI 生成速度与设计质量之间的落差

用 codex cli 生成一个登录页，可能只需要十几秒。但生成出来的东西，你打开浏览器一看，按钮和输入框之间的间距是 12px 还是 16px，它不管；卡片阴影是 0 2px 4px 还是 0 4px 8px，它也不管。这些细节单看无所谓，堆在一起就会让页面显得“廉价”。impeccable 的思路不是让 AI 一次性写出完美代码，而是承认 AI 在审美一致性上天然不稳定，然后用工具链去补这个短板。

具体来说，它把检查分成两层。第一层是 CLI 层面的静态检查，在代码生成之后、提交之前运行，扫描 CSS 和组件文件里的“设计异味”。第二层是 browser extension 层面的运行时检查，在真实渲染出来的页面上做视觉比对。两层配合，才能覆盖从源码到呈现的完整链路。

2.2 为什么选 CLI 作为主要入口

你可能会问，为什么不做成一个纯 Web 工具？原因很直接：AI coding agents 的工作流本身就是命令行的。codex cli、zcode cli、openspec cli 这些工具，用户已经习惯了在终端里敲命令。如果 impeccable 的检查需要跳出终端去打开网页，流程就断了。把检查能力做成 CLI 子命令，才能无缝嵌入现有的 agent 工作流。

另一个考虑是自动化。CLI 工具天然适合放进 pre-commit hook 或者 CI pipeline。你可以在 codex cli 完成代码生成后，自动触发 impeccable 检查，发现问题就阻断提交。这种“生成-检查-修复”的闭环，比人工事后审查效率高得多。

2.3 浏览器扩展的角色：补上运行时这一环

CLI 检查的是源码，但源码里的margin: 0 auto在真实布局中可能因为父容器宽度而失效。浏览器扩展的作用就是在页面渲染完成后，读取计算样式和实际几何信息，做一轮“所见即所得”的检查。比如检查所有可点击元素的点击区域是否小于 44x44 像素，检查文本对比度是否达到 WCAG AA 标准，检查同一视觉层级内的圆角值是否统一。

这两层检查的分工可以用一个表格说清楚：

注意：两层检查不是二选一，而是互补。只做静态检查会漏掉布局计算问题，只做运行时检查则无法在提交前阻断问题。

3. 核心细节解析：impeccable 检查规则的设计逻辑

3.1 间距系统的检查：为什么是 4px 基准

前端设计里最容易被 AI 搞乱的就是间距。你让 codex cli 生成一个卡片组件，它可能给你padding: 13px、margin-bottom: 7px这种值。单看没问题，但整个页面如果有二十个组件，间距值五花八门，视觉上就会显得杂乱。impeccable 的静态检查里有一条核心规则：所有间距值必须是 4 的倍数。

为什么是 4 而不是 8 或 5？因为 4px 基准在主流设计系统里兼容性最好。8px 基准太粗，很多微调场景用不上；5px 基准则跟常见的屏幕密度适配不友好。4px 既能覆盖 4、8、12、16、24、32 这些常用值，又能在需要更细粒度时用 2px 作为半档。检查逻辑很简单，扫描 CSS 里的margin、padding、gap属性，提取数值，判断是否能被 4 整除。不能整除的就标记为“间距异味”。

实际操作中，你可以在项目根目录放一个.impeccablerc配置文件，把基准值改成 8 或者自定义的数值。但根据我经手的项目，4px 基准的误报率最低，团队接受度也最高。

3.2 颜色使用的检查：硬编码与设计令牌

AI 生成代码时特别喜欢直接写十六进制颜色值，比如color: #3b82f6。这在单文件里没问题，但项目一旦大起来，同一个品牌色可能在十几个文件里以不同形式出现：#3b82f6、#3B82F6、rgb(59, 130, 246)、hsl(217, 91%, 60%)。impeccable 的检查规则是：除了设计令牌定义文件，其他任何地方出现硬编码颜色值都报警。

这条规则的实现需要一点技巧。你不能简单地用正则匹配#开头的字符串，因为 SVG 里可能有合法的颜色引用。比较稳妥的做法是结合 AST 解析，只检查 CSS 声明块和 JSX 的 style 属性。对于 Tailwind 项目，则检查是否使用了bg-blue-500这类预设类名，而不是bg-[#3b82f6]这种任意值写法。

实操心得：刚开始推行这条规则时，建议把硬编码颜色设为警告级别而非错误级别。团队里总有一些历史代码需要渐进式迁移，一刀切会导致大量误报，反而让人抵触。

3.3 组件一致性的检查：圆角、阴影、边框

圆角和阴影是另一个重灾区。AI 生成的按钮可能用border-radius: 6px，生成的卡片用border-radius: 8px，生成的输入框用border-radius: 4px。用户说不清哪里不对，但就是觉得“不统一”。impeccable 的做法是维护一个“设计常量表”，在配置文件里定义好项目允许的圆角值集合、阴影值集合、边框宽度集合。检查时，任何不在集合内的值都会被标记。

这个常量表怎么定？我的经验是从现有设计稿里提取。如果项目已经有一套成型的 UI，直接统计所有组件的圆角值，取出现频率最高的三到四个作为允许集合。如果是新项目，就参考主流设计系统的默认值：圆角用 0、4、8、12、16、9999（全圆），阴影用三档（sm、md、lg），边框用 1px 和 2px。

3.4 可访问性检查：对比度与点击区域

运行时检查里最重要的两条是可访问性规则。第一条是对比度：正文文本与背景的对比度至少 4.5:1，大号文本至少 3:1。浏览器扩展会遍历页面上的所有文本节点，读取计算后的颜色和背景色，计算对比度比值。第二条是点击区域：所有可交互元素的点击热区不得小于 44x44 像素。这条规则在移动端尤其重要，但桌面端同样适用，因为鼠标点击也需要足够的容错空间。

计算对比度的公式看起来复杂，但实现起来就是几行代码。先把 RGB 值转成相对亮度，再用(L1 + 0.05) / (L2 + 0.05)算出比值。浏览器扩展里可以直接用getComputedStyle拿到颜色值，不需要自己解析 CSS 文件。

4. 实操过程：从零搭建 impeccable 检查流程

4.1 环境准备与 CLI 工具安装

假设你已经有了 Node.js 环境，并且正在使用 codex cli 作为主要的 AI coding agent。第一步是安装 impeccable 的 CLI 包。目前它可以通过 npm 全局安装，也可以作为项目依赖本地安装。我建议本地安装，因为不同项目可能需要不同的检查配置。

# 在项目根目录执行 npm install --save-dev impeccable-cli # 或者全局安装 npm install -g impeccable-cli

安装完成后，运行npx impeccable init会在项目根目录生成一个.impeccablerc.json配置文件。这个文件里包含了所有可配置的检查规则和阈值。默认配置已经覆盖了前面提到的间距、颜色、圆角、阴影、对比度、点击区域这六类检查。

注意：如果你用的是 codex cli 的/compact命令来压缩上下文，建议在压缩之前先跑一遍 impeccable 检查。因为压缩后的上下文可能丢失部分设计细节，检查结果会不准确。

4.2 配置文件详解与参数调优

.impeccablerc.json的结构不复杂，但每个参数都值得推敲。下面是一个典型的配置示例：

{ "spacing": { "base": 4, "allowHalf": true, "severity": "error" }, "colors": { "allowHardcoded": false, "ignoreFiles": ["**/tokens/**", "**/theme/**"], "severity": "warn" }, "radius": { "allowed": [0, 4, 8, 12, 16, 9999], "severity": "warn" }, "shadow": { "allowed": ["none", "sm", "md", "lg"], "severity": "warn" }, "a11y": { "contrastRatio": 4.5, "minClickArea": 44, "severity": "error" } }

spacing.allowHalf这个参数控制是否允许 2px 这样的半档值。我建议在项目初期设为true，给团队一个适应期，等大家都习惯了 4px 基准后再关掉。colors.ignoreFiles用来排除设计令牌文件，这些文件里出现硬编码颜色是合理的。a11y相关的检查默认是 error 级别，因为可访问性问题直接影响用户体验，不应该妥协。

4.3 在 codex cli 工作流中嵌入检查

codex cli 的工作流通常是：输入提示词 -> 生成代码 -> 人工审查 -> 提交。impeccable 的嵌入点是在“生成代码”之后、“人工审查”之前。你可以在 codex cli 的配置里加一个 post-generation hook，让它在每次生成代码后自动运行npx impeccable check。

具体操作是在项目根目录的.codex/config.json里添加：

{ "hooks": { "postGeneration": "npx impeccable check --staged" } }

--staged参数表示只检查本次生成涉及的文件，而不是全量扫描。这样检查速度很快，不会打断工作流。如果检查发现问题，CLI 会输出具体的文件、行号和问题描述，你可以直接把这段输出喂回给 codex cli，让它根据检查结果修复代码。

4.4 浏览器扩展的安装与使用

浏览器扩展的安装方式取决于你用的浏览器。以 Chrome 为例，在扩展管理页面开启开发者模式，选择“加载已解压的扩展程序”，指向 impeccable 扩展的构建目录。安装完成后，打开任意页面，点击扩展图标，会弹出一个面板，显示当前页面的检查结果。

扩展面板里会按严重程度分组展示问题。错误级别的问题用红色标记，警告级别用黄色。点击某个问题，页面会自动滚动到对应的元素并高亮显示。这个功能在调试复杂布局时特别有用，比在 DevTools 里手动找元素快得多。

实操心得：浏览器扩展的检查结果可以导出为 JSON 文件。我习惯在每次 UI 走查前导出一次，跟上一版做对比，这样能清楚看到哪些问题被修复了，哪些是新引入的。

4.5 检查结果的解读与修复优先级

impeccable 输出的检查结果不是所有都需要立刻修复。我的经验是按这个优先级处理：

1. 可访问性错误：对比度不足、点击区域过小，这些必须修，没有商量余地。
2. 间距错误：非 4 倍数的间距值，批量修复，通常改几个变量就能解决。
3. 硬编码颜色警告：如果项目已经有设计令牌体系，逐步替换；如果没有，先建立令牌体系再替换。
4. 圆角和阴影警告：统一到允许集合内，通常改几个组件库的默认值就能覆盖大部分场景。

修复完成后，重新运行检查，确认问题数量下降。如果某些警告确实无法修复（比如第三方组件库的样式），可以在配置文件里加ignore规则，把对应的文件或选择器排除掉。

5. 常见问题与排查技巧实录

5.1 检查速度太慢怎么办

全量检查一个中型项目可能需要十几秒，如果每次生成代码都跑一遍，确实会影响效率。解决办法有三个。第一，用--staged只检查变更文件。第二，在配置文件里设置cache: true，impeccable 会缓存未变更文件的检查结果。第三，把检查拆成两个阶段：提交前只跑快速检查（间距、颜色），CI 里跑全量检查（包括可访问性）。

5.2 误报太多导致团队抵触

这是推行任何检查工具都会遇到的问题。我的处理方式是：第一周只开启 error 级别的检查，而且只检查最核心的两条规则（间距和对比度）。等团队适应了，再逐步开启警告级别的规则。另外，在配置文件里给每个规则加severity字段，让团队可以自己决定哪些规则是 error、哪些是 warn、哪些是 off。控制权交给团队，抵触情绪会小很多。

5.3 与现有 ESLint 规则冲突

impeccable 的检查跟 ESLint 有重叠但不完全相同。ESLint 关注代码质量和语法规范，impeccable 关注设计一致性。如果发现冲突，比如 ESLint 要求某种写法而 impeccable 要求另一种，优先满足 impeccable，因为设计一致性的问题更难通过人工审查发现。你可以在 ESLint 配置里关掉冲突的规则，或者用eslint-disable注释临时忽略。

5.4 浏览器扩展在某些页面上不工作

最常见的原因是页面使用了 Shadow DOM 或者 iframe。Shadow DOM 里的元素不会被扩展的遍历逻辑覆盖到，需要在扩展代码里显式处理shadowRoot。iframe 则需要配置all_frames: true并处理跨域限制。另一个原因是页面加载时机，如果扩展在 DOM 完全渲染前就执行检查，会漏掉动态加载的内容。解决办法是监听MutationObserver，在 DOM 稳定后再执行检查。

5.5 检查结果与设计稿不一致

有时候 impeccable 说没问题，但设计稿上明显不对。这通常是因为检查规则覆盖不到某些视觉问题，比如元素之间的视觉对齐、留白的节奏感、图标的视觉重量平衡。这些属于“审美判断”，很难用规则描述。我的做法是把这类问题留给人工走查，impeccable 只负责那些可以量化的部分。不要试图让工具解决所有问题，工具解决 80% 的机械问题，人解决 20% 的判断问题。

5.6 常见问题速查表

注意：如果你在 codex cli 里用/model切换了模型，建议重新跑一遍 impeccable 检查。不同模型生成的设计细节风格差异很大，之前的检查结果可能不再适用。

6. 把 impeccable 融入日常开发流的几个建议

6.1 建立设计令牌的单一事实来源

impeccable 的检查效果很大程度上取决于项目有没有清晰的设计令牌体系。如果所有颜色、间距、圆角都定义在tokens.css或theme.js里，检查规则就能精准地判断哪些是合法引用、哪些是硬编码。我的建议是在项目初期就建立这个文件，哪怕一开始只有几个变量。随着项目迭代，令牌会自然增长，检查规则也跟着调整。

6.2 把检查结果纳入代码审查清单

代码审查时，除了看逻辑正确性，也看一眼 impeccable 的检查报告。如果报告里有新增的警告，让提交者解释原因。是确实需要例外，还是疏忽了？这种习惯一旦养成，团队对设计一致性的敏感度会明显提升。我见过不少团队，引入检查工具后，前端界面的“廉价感”在两周内就有肉眼可见的改善。

6.3 定期回顾检查规则的阈值

设计系统不是一成不变的。半年前定的圆角允许集合，可能随着品牌升级需要调整。建议每个季度回顾一次.impeccablerc.json，看看哪些规则太松、哪些太紧、哪些已经过时。回顾时拉上设计师一起，因为很多阈值本质上是设计决策，不是技术决策。

6.4 用检查结果反向优化 AI 提示词

这是一个进阶技巧。如果你发现 codex cli 生成的代码频繁触发某条检查规则，比如总是用 6px 圆角而不是允许集合里的 4px 或 8px，那就在提示词里明确写“圆角使用 4px 或 8px”。AI 对提示词里的具体数值很敏感，明确约束后，生成代码的合规率会大幅提升。这比事后修复高效得多。

6.5 浏览器扩展的快捷键配置

浏览器扩展默认没有快捷键，但你可以自己在扩展管理页面配置。我习惯把检查当前页面的快捷键设为Ctrl+Shift+I（跟 DevTools 的快捷键区分开）。这样在调试页面时，按一下就能看到检查结果，不用去点扩展图标。这个配置在 Chrome 和 Edge 里都支持，Firefox 需要额外安装一个快捷键管理扩展。

6.6 处理第三方组件的检查豁免

项目里总会用到第三方 UI 库，这些库的样式不受你控制，检查时会产生大量误报。解决办法是在配置文件里加ignore规则，把node_modules和第三方组件相关的路径排除掉。但要注意，排除之后，你自己封装的组件如果继承了第三方库的样式，仍然需要检查。所以ignore规则要写得精确，不能一刀切。

{ "ignore": [ "node_modules/**", "src/components/third-party/**", "**/*.min.css" ] }

6.7 检查报告的可视化

CLI 输出的文本报告适合快速浏览，但不适合追踪趋势。我建议把每次检查的结果导出为 JSON，然后用一个简单的脚本统计问题数量，画成折线图。这样能直观看到项目设计质量的变化趋势。如果某次提交后问题数量突然上升，就能快速定位到是哪个改动引入的。这个脚本不需要多复杂，几十行 Node.js 代码就够了。

6.8 与 openspec cli 的配合

如果你在用 openspec cli 管理项目规范，可以把 impeccable 的检查规则作为规范的一部分写进去。openspec cli 支持自定义检查器，你可以在它的配置文件里引用 impeccable 的 CLI 命令，让规范检查和设计检查在同一个流程里执行。这样开发者只需要记住一个命令，就能完成所有检查。

7. 一些踩过的坑和最后的经验分享

我在多个项目里推行过 impeccable 这套流程，踩过的坑不少。最大的一个坑是：一开始就把所有规则设为 error 级别，结果第一次全量检查报了三百多个错误，团队直接放弃使用。后来改成渐进式推行，先开两条规则，等大家习惯了再加，接受度就高多了。工具再好，如果推行方式不对，也会被抵触。

第二个坑是忽略了检查性能。早期版本没有缓存机制，每次检查都要重新解析所有文件，一个中型项目要跑半分钟。后来加了文件哈希缓存，只检查变更文件，速度降到两秒以内。如果你打算在 CI 里跑全量检查，一定要确保检查时间在可接受范围内，否则开发者会想办法绕过它。

第三个坑是浏览器扩展的权限问题。有些页面因为 CSP 限制，扩展无法注入脚本。这种情况只能退回到 CLI 检查，或者让开发者在本地开发环境里手动运行扩展。不要试图绕过 CSP，那会带来安全问题。

最后分享一个小技巧：impeccable 的检查规则支持自定义扩展。你可以写一个简单的 JavaScript 文件，导出一个检查函数，然后在配置文件里引用它。比如我们团队加了一条规则：检查所有按钮组件的font-weight是否在允许集合内（400 或 600）。这条规则用内置检查覆盖不到，但用自定义扩展几行代码就搞定了。自定义扩展的 API 文档在项目的docs/custom-rules.md里，写得还算清楚。

这套东西说到底就是一个思路：把设计一致性从“靠人盯”变成“靠工具查”。AI coding agents 负责生成，impeccable 负责检查，人负责判断那些工具判断不了的部分。三者配合，前端交付的质量和速度都能上一个台阶。