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

第一次看到“impeccable”这个项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的画面：前端工程师对着 AI 生成的代码皱眉头——功能是能跑，但间距忽大忽小、颜色差一点点、圆角不统一、响应式断点乱成一锅粥。AI coding agents 写业务逻辑越来越靠谱，可一到“审美”这件事上，就经常掉链子。impeccable 这个项目，本质上就是冲着这个痛点来的。

它的定位可以概括成一句话：给 AI 编码代理装上一双“设计眼”。你给它一个前端界面，它帮你判断这个界面在视觉层面是否“无懈可击”——对齐、层级、对比、留白、一致性这些设计基本功有没有做到位。它不是一个 UI 框架，也不是一个组件库，而更像是一个设计质量的检查器与约束层，通过 CLI 和浏览器扩展两种形态，把“设计规范”这件事变成 AI 代理可以理解、可以执行的输入。

那它适合谁？我梳理了三类人。第一类是用 AI 代理写前端但自己设计功底一般的开发者，你让 AI 生成页面，生成完心里没底，不知道好不好看，impeccable 能给你一个相对客观的判断。第二类是团队里负责设计规范落地的人，你想让所有 AI 生成的界面都符合同一套设计语言，impeccable 可以当成一道自动化的“设计门禁”。第三类是对前端细节有强迫症的独立开发者，你一个人干活，没有设计 review，impeccable 相当于一个随叫随到的设计搭档。

关键词里出现的 CLI、browser extension、AI coding agents、frontend design，其实已经把它的技术轮廓勾出来了：命令行工具负责批量和集成，浏览器扩展负责实时和可视化，AI 代理是它的主要服务对象，前端设计是它的核心战场。接下来我会把这几个部分拆开，讲清楚它背后的设计思路、实操要点，以及我在实际折腾过程中踩过的坑。

2. 整体设计思路拆解：为什么是 CLI 加浏览器扩展这套组合

2.1 为什么不做成纯 Web 服务，而是 CLI 优先

很多人第一反应会问：设计检查这种东西，做个网页上传截图不就行了，为什么要搞 CLI？我一开始也这么想，但实际用下来才明白，CLI 优先是为了贴合 AI coding agents 的工作流。现在的 AI 代理大多在终端里跑，它们能执行命令、读文件、改代码，但不太擅长“打开一个网页、点按钮、看结果”这种交互。你把 impeccable 做成 CLI，代理就能在生成代码之后直接调用它，拿到结构化的检查结果，然后自己决定要不要改。

这背后的逻辑是把设计检查变成可编程的一步。传统设计 review 是人看人评，主观、慢、不可自动化。CLI 化之后，检查结果可以是 JSON、可以是退出码、可以是 diff，代理和 CI 都能消费。我实测下来，这种“机器可读”的设计反馈，才是 AI 代理真正能利用起来的形式。你给它一段自然语言说“这个页面不好看”，它无从下手；你给它“间距不一致，第 3 和第 5 个卡片的 padding 差 4px”，它立刻就能改。

另一个原因是可复现。浏览器里手动点出来的检查，换个环境、换个时间可能结果就不一样。CLI 跑的是同一套规则、同一份配置，结果稳定，适合放进流水线。这点对于团队协作特别重要——你不能今天说合格明天说不合格，标准得是钉死的。

2.2 浏览器扩展补的是哪块短板

CLI 强在自动化和集成，但它有个天然短板：看不见。设计这件事，很多问题是“看一眼就知道”的，比如某个元素明显偏了、某个颜色刺眼。CLI 输出的是文字和数字，你得在脑子里重建画面。浏览器扩展补的就是这块——它直接在你的页面上叠加可视化的标注，哪里对齐有问题、哪里间距不对，用高亮、辅助线、色块标出来。

我个人的使用习惯是：开发阶段用扩展实时看，提交前用 CLI 跑一遍做门禁。扩展负责“感觉”，CLI 负责“标准”。两者共享同一套规则引擎，所以扩展里看到的问题，CLI 里一定能复现，不会出现“扩展说没问题、CLI 报一堆错”这种割裂。这个设计我觉得挺聪明的，它没有让两个形态各搞一套，而是一个内核、两种外壳。

从技术实现角度推测（这部分是基于常见实践的合理补全），扩展大概率是通过 content script 注入页面，读取计算后的样式（computed style）和布局盒模型（getBoundingClientRect 之类），然后跑规则。CLI 则可能是通过无头浏览器加载页面，拿到同样的数据再跑同一套规则。这样规则只写一遍，两边复用，维护成本低。

2.3 它和普通 linter 的本质区别

有人会说，ESLint、Stylelint 不也能查样式问题吗？区别在于层次不同。Stylelint 查的是“你的 CSS 写得规不规范”，比如有没有用未知属性、有没有重复选择器。impeccable 查的是“你渲染出来的界面好不好看”，比如两个本应对齐的元素实际差了 2px、标题和正文的对比度不够、一组卡片的圆角不统一。

打个比方，Stylelint 像是检查你作文的语法和错别字，impeccable 像是检查你这篇作文读起来顺不顺、有没有逻辑断层。前者是规则层面的，后者是效果层面的。这也是为什么它必须依赖真实渲染——不渲染出来，你根本不知道最终长什么样。这个定位决定了它不能只做静态分析，必须能跑起来页面，这也是它同时需要 CLI（无头渲染）和扩展（真实浏览器渲染）的原因。

3. 核心能力解析：impeccable 到底检查哪些东西

3.1 对齐与间距：设计的地基

对齐和间距是设计里最基础、也最容易被 AI 忽略的东西。AI 生成代码时，经常这里写个margin: 13px，那里写个padding: 17px，单看每个值都“差不多”，放一起就乱了。impeccable 这类工具的核心能力之一，就是检测视觉节奏的一致性。

具体来说，它会看几个维度。第一是同组元素的对齐，比如一排卡片的左边缘是不是在同一条垂直线上，标题和它下面的正文是不是左对齐。第二是间距的规律性，比如所有卡片之间的间距是不是同一个值，或者是不是某个基准值的整数倍（常见的是 4px 或 8px 网格）。第三是边距的对称性，比如一个容器左右 padding 是不是相等。

我实测过一个典型场景：让 AI 生成一个三列卡片布局，它给每个卡片写了不同的 margin，结果渲染出来卡片宽度参差不齐。CLI 跑一遍，直接报出“卡片间距不一致，检测到 12px、16px、20px 三种值”。这种反馈对 AI 代理来说就是明确的修改指令，它拿到之后会把间距统一成基准值。这就是把模糊的“不好看”翻译成了精确的“哪里不对”。

注意：间距检查一定要结合设计系统来配。如果你的项目本来就用 4px 网格，那基准值就设 4；如果用的是 8px，就设 8。配错了会导致大量误报，反而干扰判断。

3.2 对比度与可读性：不只是无障碍

对比度检查很多工具都有，但 impeccable 的侧重点不太一样。常规工具查的是 WCAG 标准，比如正文对比度要达到 4.5:1。impeccable 除了这个，还会看视觉层级的对比是否合理——标题是不是明显比正文重、次要信息是不是明显比主要信息弱。

这个区别很关键。WCAG 达标不代表视觉层级清晰。我见过不少 AI 生成的页面，标题和正文颜色都达标了，但两者灰度太接近，扫一眼分不出主次。impeccable 会检测这种“层级塌陷”，提示你标题和正文的对比度差距不够，需要拉开。

实操上，我建议把对比度检查分成两档：硬性档是 WCAG 标准，不达标直接报错；软性档是层级建议，不达标给警告。这样既保证了无障碍底线，又不会因为层级建议太严格而让代理频繁改动。这个分档思路是我自己加的，原工具不一定内置，但你可以通过配置规则严重级别来实现。

3.3 一致性：颜色、圆角、阴影的统一

一致性是 AI 生成代码的重灾区。同一个页面里，主色可能出现了#3b82f6、#3B82F6、rgb(59,130,246)三种写法，虽然渲染出来一样，但代码层面已经乱了。更麻烦的是圆角，有的卡片border-radius: 8px，有的6px，有的10px，肉眼能看出细微差别，但说不清哪里不对。

impeccable 的一致性检查会聚类相似值。比如它发现页面上有 6px、7px、8px 三种圆角，就会提示“圆角值不统一，建议归并到 8px”。颜色同理，它会把视觉上接近的颜色归为一组，提示你统一。这个能力对 AI 代理特别有用，因为代理很容易在生成多个组件时“各写各的”，一致性检查相当于一个事后收口。

我踩过的一个坑是：一致性检查的阈值设太严会误伤。比如设计上故意用两种圆角区分主次卡片，工具可能误判为不一致。解决办法是在配置里加白名单，把有意为之的差异排除掉。这个配置过程有点繁琐，但配好之后一劳永逸。

3.4 响应式断点：AI 最容易翻车的地方

响应式是 AI 生成前端时最容易出问题的地方。它经常只考虑桌面端，或者断点设得乱七八糟，导致中间尺寸下布局崩坏。impeccable 的响应式检查会在多个视口宽度下渲染页面，对比布局变化，找出断点设置不合理的地方。

具体检查什么？比如某个断点下元素溢出了容器、某个断点下文字换行导致高度突变、某个断点下本该隐藏的元素还显示着。这些在单一视口下看不出来，必须多视口对比。CLI 形态在这里优势明显，因为它可以脚本化地跑多个宽度，扩展形态则更适合手动拖动窗口实时看。

我一般会配一组标准断点：320、375、768、1024、1440。这五个宽度覆盖了主流设备。impeccable 在这五个宽度下各跑一遍，输出每个宽度的问题列表。代理拿到之后，就能针对性地加媒体查询。这一步能挡掉大量“桌面好看、手机稀烂”的问题。

4. 实操过程：从安装到跑通第一条检查

4.1 环境准备与安装

impeccable 的安装，按常见 CLI 工具的惯例，大概率是通过包管理器分发。我以 npm 生态为例说明（如果你的项目用的是别的生态，思路类似，换对应的包管理器即可）。

# 全局安装，方便在任何项目里调用 npm install -g impeccable # 或者作为项目开发依赖，锁定版本，适合团队协作 npm install --save-dev impeccable

我推荐项目内安装而不是全局安装。原因有两个：一是版本锁定，团队每个人跑出来的结果一致；二是可以写进 package.json 的 scripts，CI 里直接调用。全局安装适合你个人快速试用，但正式项目别这么干。

安装完之后，跑一下版本命令确认装好了：

impeccable --version

如果提示命令找不到，八成是全局 bin 目录没在 PATH 里。这时候别急着改 PATH，先试试用npx impeccable --version，npx 会自动找本地或临时安装的包，能省掉很多环境折腾。

提示：如果你所在的环境对包管理器有代理或镜像配置要求，记得先配好 registry，否则安装会卡住。这部分按你所在团队的标准配置来就行。

4.2 初始化配置文件

impeccable 这类工具通常需要一个配置文件来定义规则和阈值。按惯例，初始化命令会生成一个默认配置：

impeccable init

这会生成一个类似impeccable.config.json的文件。默认配置一般比较宽松，我建议第一次先跑默认配置，看看报什么，再逐步收紧。一上来就配一堆严格规则，结果满屏报错，反而不知道从哪下手。

配置文件里我通常会关注这几项：

这个表是我根据常见实践整理的，具体字段名以你装到的版本为准。核心思路是：基准值跟设计系统对齐，检查级别分硬软两档，忽略项把不可控的部分排除掉。

4.3 跑第一条检查

配置好之后，跑检查的命令通常是这样的：

# 检查本地开发服务器上的页面 impeccable check http://localhost:3000 # 或者检查构建产物里的静态页面 impeccable check ./dist/index.html

我建议先对着本地开发服务器跑，因为开发服务器有热更新，你改完代码刷新就能重跑，迭代快。等稳定了再对构建产物跑，作为提交前的门禁。

第一次跑的结果大概率会让你有点意外——报的问题可能比你想象的多。别慌，这是正常的。AI 生成的代码在细节上本来就粗糙，impeccable 只是把它量化了。我的做法是先按严重级别排序，从 error 开始修，warning 攒着批量处理。error 通常是硬伤，比如对比度不达标、元素溢出；warning 多是建议，比如间距可以更统一。

4.4 把检查接入 AI 代理的工作流

这是 impeccable 最有价值的一环。你要让 AI 代理在生成代码后自动跑检查，然后根据结果自我修正。实现方式取决于你用的代理框架，但核心逻辑是一样的：生成 → 检查 → 解析结果 → 修正 → 再检查。

我以常见的脚本化方式举例：

# 伪代码思路，具体命令按你的代理框架调整 impeccable check http://localhost:3000 --format json > report.json # 代理读取 report.json，针对每条问题生成修改 # 修改后重新跑 check，直到 error 清零

这里的关键是--format json。人类看文本输出舒服，但代理需要结构化数据。JSON 里每条问题包含位置、类型、当前值、建议值，代理拿到就能精确修改，不用猜。

我实测下来，这个闭环跑通之后，AI 生成的前端质量提升非常明显。以前要人工 review 半天的问题，现在代理自己就能修掉七八成。剩下的两三成通常是需要设计判断的，比如“这个留白是不是太大”，这种主观问题工具给不了答案，还得人来定。

注意：别让代理无限循环修正。设一个最大迭代次数，比如 3 次，超过就停下来人工介入。否则代理可能在一个问题上反复横跳，浪费时间和额度。

5. 浏览器扩展的使用与联动

5.1 扩展的安装与激活

浏览器扩展的安装，按惯例是从浏览器的扩展商店获取，或者加载开发者模式的解压包。装好之后，通常在浏览器工具栏会出现一个图标。点开它，它会检测当前页面，然后叠加可视化标注。

我第一次用的时候有个小困惑：扩展在哪些页面上生效。一般它只对本地开发地址（localhost、127.0.0.1）或者你显式授权的域名生效，不会在所有网页上乱跑。这是合理的设计，既保护隐私，也避免干扰正常浏览。如果你发现扩展没反应，先确认当前页面是不是在它的生效范围内。

激活之后，页面上会出现几种标注：对齐辅助线、间距色块、问题高亮。我建议先关掉所有标注，只开一类，比如只看对齐。全开的话页面会很花，反而看不清。一类一类看，改完一类再看下一类，效率更高。

5.2 扩展和 CLI 的配合节奏

我的使用节奏是这样的：写代码时扩展常开，实时看问题；提交前 CLI 跑一遍，确认清零。扩展的好处是即时，你改一行 CSS，刷新页面，标注立刻更新，反馈闭环很短。CLI 的好处是全面和可复现，它会把所有视口、所有规则都跑一遍，不漏。

有个细节值得说：扩展里看到的和 CLI 里跑出来的，理论上应该一致，但偶尔会有差异。差异通常来自两个地方：一是扩展用的是你当前浏览器窗口的尺寸，CLI 用的是配置里的固定视口；二是扩展可能受浏览器插件、字体渲染影响，CLI 用的是干净环境。遇到差异，以 CLI 为准，因为它是标准化的。

5.3 把扩展当成设计沟通工具

除了自己用，扩展还有个妙用：跟非技术同事沟通设计问题。你截个图，上面带着标注，说“这里对齐差了 2px”，比纯文字描述直观得多。我试过把扩展标注截图发给产品经理，对方一眼就懂了，省掉很多来回解释。

这个用法虽然不在工具的官方定位里，但实际价值很高。设计问题很多时候是“说不清”，可视化标注解决了这个沟通成本。如果你在团队里推 impeccable，不妨把它当成一个设计沟通的通用语言来推广。

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

6.1 检查结果太多，不知道从哪下手

这是新手最常见的问题。第一次跑，报几百条，直接劝退。我的处理办法是分级 + 分批。先只看 error，把 error 清零；再看 warning 里出现频率最高的那类，批量修；最后处理零散的建议。

具体操作上，CLI 一般支持按级别过滤：

# 只看 error impeccable check http://localhost:3000 --level error # 只看某一类规则 impeccable check http://localhost:3000 --rule spacing

按规则类型过滤特别有用，因为同一类问题往往可以用同一个方法批量修。比如所有间距问题，你统一改成基准值的倍数，一次就能消掉一大片。

6.2 误报怎么处理

误报是任何静态检查工具都躲不开的。impeccable 的误报通常来自这几种情况：设计上故意的不一致（比如主次卡片用不同圆角）、第三方组件的样式（你控制不了）、动态内容导致的临时状态（比如加载中的骨架屏）。

处理误报的标准做法是加忽略规则。配置文件里一般有 ignore 字段，可以按选择器、按路径、按规则类型忽略。我建议忽略规则要写注释，说明为什么忽略，否则过几个月你自己都忘了当初为啥放过它。

{ "ignore": [ { "selector": ".third-party-widget", "reason": "第三方组件，样式不可控" }, { "rule": "consistency", "selector": ".hero-card", "reason": "主卡片故意用更大圆角区分层级" } ] }

提示：忽略规则要克制。每加一条忽略，就少一分检查覆盖。如果某个规则误报特别多，先想想是不是阈值配错了，而不是无脑忽略。

6.3 响应式检查跑得慢

多视口渲染确实耗时，尤其是页面复杂的时候。我试过跑一个重页面，五个视口跑下来要一两分钟。优化思路有几个：减少视口数量（如果项目只支持桌面和移动，就别跑五个）、只检查关键页面（不是每个页面都要全量跑）、并行跑（如果工具支持）。

还有一个技巧：开发阶段只跑当前正在改的视口，提交前再跑全量。这样日常迭代快，门禁又不漏。这个策略我在多个项目里用过，平衡了速度和覆盖。

6.4 和现有 lint 工具冲突怎么办

impeccable 和 Stylelint、ESLint 不是替代关系，是互补。但配置不当会互相干扰，比如 Stylelint 要求某种写法，impeccable 又建议另一种。解决办法是明确分工：Stylelint 管代码规范，impeccable 管渲染效果。两者规则不重叠，就不会冲突。

如果确实遇到冲突，比如某个属性 Stylelint 要求 A 值、impeccable 建议 B 值，那说明你的设计系统本身有矛盾，得先在设计层面统一，而不是在工具层面打补丁。这种情况我遇到过，最后是改了设计 token 才解决的。

6.5 常见问题速查表

这张表是我自己踩坑总结的，不一定覆盖所有情况，但能解决八成常见问题。遇到表里没有的，先看工具的日志输出，日志通常会告诉你哪一步出了问题。

7. 我个人的一些使用体会

折腾 impeccable 这段时间，最大的感受是：AI 生成前端的上限，取决于你给它多少结构化的约束。你光说“做好看点”，它做不好；你给它一套可执行的检查规则，它就能一步步逼近“好看”。impeccable 的价值不在于它自己多聪明，而在于它把设计这件事翻译成了机器能懂的语言。

另一个体会是，工具再好也替代不了设计判断。impeccable 能告诉你间距不一致、对比度不够，但它没法告诉你“这个页面应该是什么气质”。那些需要审美决策的部分，还是得人来。我的用法是让工具处理 80% 的机械问题，自己专注剩下 20% 的判断。这个分工我觉得挺舒服。

最后分享一个小技巧：把 impeccable 的检查结果当成 AI 代理的“设计记忆”。每次代理改完，把检查通过的状态存下来，下次生成类似组件时，把这份“合格样本”作为参考喂给代理。这样代理会逐渐学会你的设计偏好，生成的东西越来越接近你的标准。这个做法我还在摸索，但初步效果不错，值得一试。