impeccable：为AI coding agents打造的前端设计质量检查工具

1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的画面前端开发者对着 AI 生成的代码皱眉头——功能是能跑但间距忽大忽小、颜色差一点点、圆角不统一、响应式断点乱成一锅粥。AI coding agents 写业务逻辑越来越靠谱可一旦涉及前端设计的“手感”产出往往离“impeccable”无可挑剔还差着十万八千里。这个项目就是冲着这个痛点来的。它把自己定位成一个围绕AI coding agents的前端设计质量工具形态上同时提供CLI和browser extension两条入口。说白了它想做的事情是让 AI 写出来的界面不只是“能用”而是“挑不出毛病”。适合谁来参考三类人最该关注——一是天天用 AI 辅助写前端的独立开发者二是带团队、需要统一 UI 产出质量的技术负责人三是想搞清楚“AI 生成代码如何做质量兜底”这个命题的工程效率爱好者。我先把结论摆前面impeccable 的价值不在于它替你写代码而在于它给 AI 产出的前端代码建立了一套可检查、可量化、可复现的审美与规范标准。这跟传统 linter 只查语法和潜在 bug 是两码事它查的是“设计意图有没有被正确执行”。下面我按自己实际折腾这类工具的经验把它的设计思路、核心机制、CLI 与浏览器扩展的配合方式、以及一堆踩坑点掰开揉碎讲清楚。2. 整体设计思路拆解为什么是 CLI 加浏览器扩展的组合拳2.1 为什么单靠 CLI 不够单靠扩展也不够先想一个问题如果只做一个 CLI会怎样CLI 的优势是能进 CI/CD、能批量跑、能对着一整个代码仓库做静态扫描。但它有个致命短板——它看不到渲染后的真实效果。前端设计的问题很多是运行时才暴露的flex 布局在某个视口下塌了、字体加载失败导致 fallback 字体撑破了容器、暗色模式下对比度不达标。这些光看源码是看不出来的。那如果只做一个 browser extension 呢扩展能看到真实渲染能拿到 computed style能截图对比但它的短板是无法规模化。你不可能让设计师手动打开一百个页面挨个点扩展检查也没法把它塞进自动化流程里卡住合并请求。impeccable 选择两条腿走路逻辑就很清楚了CLI 负责“批量和流程”扩展负责“真实渲染和交互态”。CLI 在本地或 CI 里跑对代码和构建产物做第一轮筛查扩展在浏览器里跑对真实页面做第二轮验证。两者共享同一套规则定义保证标准一致。这个设计我在其他工具上见过类似思路但 impeccable 把“设计规范”作为一等公民而不是把可访问性检查当附属品这是它比较特别的地方。2.2 规则引擎是核心CLI 和扩展只是外壳不管从哪个入口进真正干活的是中间那层规则引擎。我推测它的规则大致分几类这也是这类工具通用的分层方式设计令牌一致性颜色、间距、字号、圆角、阴影是否都来自预定义的设计令牌有没有硬编码的魔法值。布局健壮性栅格对齐、溢出处理、断点行为是否符合预期。视觉可访问性对比度、焦点可见性、点击热区尺寸。AI 产出特征检测这一条最有意思专门识别 AI 生成代码里常见的“坏味道”比如过度嵌套的 div、无意义的 class 命名、重复的样式块。提示规则引擎和入口解耦意味着你可以只装 CLI 不装扩展也可以反过来。但要想拿到完整覆盖两个都上。2.3 和 AI coding agents 的协作定位这里必须说清楚一个容易误解的点impeccable 不是 AI coding agent 的替代品它是agent 的下游质检环节。典型工作流是——你用 codex cli 或者别的 agent 把功能代码生成出来然后让 impeccable 去挑刺把问题反馈回去让 agent 修或者你自己手动修。它扮演的是“验收员”角色。我实测下来这种“生成—检查—修复”的闭环比指望 agent 一次生成完美代码要现实得多。AI 写代码的本质是概率采样你不可能靠提示词让它每次都精确命中你的设计系统但你可以用工具把偏差稳定地抓出来。3. 核心细节解析CLI 与浏览器扩展各自的关键能力3.1 CLI 的安装与基础用法CLI 类工具的安装行业里基本就那几种方式我按最常见实践给你梳理。假设它走的是主流包管理器分发路线# 全局安装方便在任何项目里调用 npm install -g impeccable-cli # 或者作为项目开发依赖锁定版本更稳妥 npm install --save-dev impeccable-cli装完之后第一件事是初始化配置。这类工具通常需要一个配置文件来声明你的设计令牌来源和规则开关impeccable init这条命令一般会生成一个类似impeccable.config.json的文件。我建议你初始化后立刻打开看一眼重点确认三个字段设计令牌的路径指向你的 tokens 文件或 CSS 变量定义、扫描范围哪些目录要查、哪些要忽略、规则严重级别哪些是 error 卡流程哪些是 warning 只提示。{ tokens: ./src/styles/tokens.css, include: [src/**/*.{tsx,jsx,vue,css}], exclude: [**/*.test.*, node_modules], rules: { no-hardcoded-color: error, spacing-scale: warning, contrast-check: error } }注意exclude一定要把测试文件和第三方依赖排掉否则扫描结果会被噪音淹没第一次跑你会被几千条告警吓到。3.2 浏览器扩展的安装与授权流程浏览器扩展的安装正规渠道就是走浏览器的扩展商店或者开发者模式下加载已解压的扩展。安装完成后第一次使用通常需要授权和配对。热词里提到的“enter the code from your two-factor authentication app or browser extension”这类流程本质上是账号体系下的安全校验——工具需要确认是你本人在操作同时把浏览器端和 CLI 端关联到同一个工作区。我按通用流程给你还原一下在 CLI 里执行登录命令比如impeccable login它会生成一个配对码或打开一个授权页面。浏览器扩展点开后会提示你输入配对码或者直接检测到本地 CLI 会话自动关联。如果开了两步验证就从你的验证器应用里读取动态码填入。配对成功后扩展会显示当前关联的工作区和项目名。这个流程的设计意图是把浏览器里的实时检查结果和代码仓库绑定起来这样你在页面上看到的问题能直接定位到源码里的具体文件和行号而不是只给你一个“这里对比度不够”的模糊提示。3.3 设计令牌整个体系的锚点我反复强调设计令牌因为它是 impeccable 这类工具能不能真正发挥作用的地基。如果你的项目里颜色、间距全是散落各处的硬编码值那工具再强也只能告诉你“这里有个魔法值”却没法告诉你“应该改成什么”。一个规范的设计令牌文件大概长这样:root { --color-primary: #2563eb; --color-text: #1f2937; --space-1: 4px; --space-2: 8px; --space-3: 12px; --space-4: 16px; --radius-sm: 4px; --radius-md: 8px; }有了这套令牌impeccable 才能做语义化检查它不只知道#2563eb是个颜色还知道它是“主色”于是当你在某个次要按钮上误用了主色时它能给出有意义的提示而不是干巴巴地说“检测到硬编码颜色”。3.4 规则的分级与误报控制任何静态检查工具最大的敌人都是误报。误报一多团队就会集体无视告警工具形同虚设。impeccable 用严重级别分级来缓解这个问题但真正管用的是按规则粒度做白名单。我的经验是新项目接入时先把所有规则设成 warning跑一周统计哪些规则误报率高针对性调整或关闭等告警收敛到可接受范围再把关键规则升级成 error 卡流程。这个渐进式接入策略比一上来就全开 error 要务实得多。规则类型建议初始级别稳定后级别说明硬编码颜色warningerror误报低值得卡间距不在刻度上warningwarning存在合理例外保持提示对比度不足errorerror直接影响可用性必须卡嵌套层级过深warningwarning视项目复杂度调整4. 实操过程把 impeccable 接进真实工作流4.1 本地开发时的即时反馈闭环我推荐的本地工作流是这样的开着 dev server浏览器里打开页面扩展常驻。你每改一次代码热更新一刷新扩展就自动重跑检查有问题直接在页面上高亮标注。这个反馈速度是最快的比等 CI 跑完再回来修要高效得多。具体操作上扩展一般会提供一个悬浮面板列出当前页面的所有问题点击某一条能跳到对应元素再点一下能复制出源码位置。我习惯把面板固定在侧边改代码的时候余光扫一眼红色数字涨了就说明刚改的东西引入了新问题。提示扩展的实时检查会消耗一些性能页面元素特别多的时候可能卡顿。可以在扩展设置里把检查范围限制在当前视口或者调低检查频率。4.2 CI 流水线里的卡点配置本地靠自觉CI 靠强制。把 impeccable 接进 CI 的核心命令通常是impeccable check --reporterjson --outputreport.json用 JSON 格式输出方便后续解析和生成报告。然后在流水线里加一步判断如果 error 级别的规则有命中就让这一步失败阻断合并。# 以通用 CI 配置为例 - name: Run impeccable check run: impeccable check --fail-onerror--fail-onerror这个参数很关键它决定了什么级别的问题会导致构建失败。我建议只让 error 级别卡流程warning 级别生成报告但不阻断否则团队会被频繁的红色构建搞到崩溃。4.3 用 AI agent 生成代码后的验收流程这是我觉得最值得展开的一环。假设你用 codex cli 生成了一批组件代码别急着提交先跑一遍impeccable check src/components/NewFeature/拿到问题清单后有两种修复路径。一是手动改适合问题少、你清楚该怎么改的情况。二是把问题清单喂回给 AI agent让它按清单修以下是我用 impeccable 检查出的前端设计问题请逐条修复 1. src/components/Card.tsx 第 42 行使用了硬编码颜色 #3b82f6应替换为 var(--color-primary) 2. src/components/Card.tsx 第 58 行间距 13px 不在设计刻度上应改为 var(--space-3) ...我实测这种“结构化反馈 agent 修复”的循环通常两三轮就能把 error 级别的问题清干净。比你自己一行行找要快也比让 agent 盲改要准。4.4 参数计算间距和对比度怎么算才靠谱工具报出来的问题你得能判断它对不对。举两个最常见的计算。间距刻度校验假设你的设计系统基于 4px 基准刻度是 4、8、12、16、24、32。那么 13px 就不在刻度上工具会报。但 13px 到底该归到 12 还是 16这取决于上下文——紧凑的表单控件用 12宽松的卡片内边距用 16。工具只能告诉你“不在刻度上”具体归到哪一档得你结合设计意图判断。对比度计算WCAG 标准下正文文本对比度至少要 4.5:1大号文本18pt 以上或 14pt 加粗可以放宽到 3:1。对比度的计算基于相对亮度公式是(L1 0.05) / (L2 0.05)其中 L 是较亮和较暗颜色的相对亮度。你不用手算但要知道工具报的“对比度 3.8:1”意味着什么——它意味着这段文字在标准下不达标视力不佳的用户可能看不清。5. 常见问题与排查技巧实录5.1 扩展装了但页面上没反应这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法扩展图标灰色未授权或未登录点开扩展重新登录页面无高亮当前域名不在授权范围检查扩展的站点权限设置面板空白与 CLI 未配对重新执行配对流程检查结果为空页面是 iframe 或动态渲染确认扩展是否支持该渲染方式我踩过最坑的一次是页面用了微前端架构主应用和子应用不同源扩展默认只检查主应用子应用里的问题全漏了。解决办法是在扩展设置里手动把子应用域名加进检查范围。5.2 CLI 扫描结果和扩展不一致这个问题的根源通常是扫描对象不同。CLI 扫的是源码扩展扫的是渲染后的 DOM。源码里写的是classNamebtn渲染后可能被 CSS-in-JS 库改成了带哈希的类名。两者对不上很正常。我的处理原则是以扩展的结果为准来判断视觉问题以 CLI 的结果为准来定位源码位置。如果两边报的问题数量差很多先检查 CLI 的扫描范围有没有漏掉某些文件类型或者扩展有没有把动态生成的样式算进去。5.3 误报太多导致团队抵触前面提过渐进式接入这里补充一个具体技巧给规则加行内豁免注释。比如某处确实需要硬编码一个颜色比如品牌 logo 的固定色你可以在那一行加注释让工具跳过.brand-logo { color: #ff6b00; /* impeccable-disable-next-line no-hardcoded-color */ }关键是豁免要留痕。谁豁免的、为什么豁免最好在注释里写清楚。否则半年后没人知道这行为什么被跳过技术债就这么攒下来了。5.4 和现有 linter 的职责边界很多人会问我已经有 ESLint、Stylelint 了还要 impeccable 干嘛答案是职责不同。ESLint 管的是代码逻辑和语法Stylelint 管的是 CSS 语法和部分规范而 impeccable 管的是设计意图的落地质量。三者可以共存配置上注意别让规则重叠导致重复告警就行。我的做法是把 Stylelint 里跟设计令牌相关的规则关掉交给 impeccable 统一管避免两套标准打架。5.5 性能优化大项目怎么跑得快项目一大全量扫描能跑好几分钟。几个提速手段一是用--changed-only只扫改动过的文件如果工具支持二是把node_modules和构建产物彻底排除三是 CI 里做缓存没改动的目录直接跳过。我实测在一个中型项目上加上缓存后扫描时间从三分钟压到了一分半。6. 我对这类工具的一点个人判断折腾完 impeccable 这套东西我最大的体会是AI 时代的前端质量保障正在从“人盯人”转向“规则盯人”。以前靠 code review 里资深工程师的眼睛去挑设计问题现在可以沉淀成规则让工具 7x24 小时盯着。这不是要取代人的审美判断而是把人从重复的、机械的检查里解放出来去做真正需要判断力的设计决策。另一个感受是工具再好设计令牌没建好都是白搭。我见过太多团队兴冲冲装了检查工具结果因为项目里全是硬编码值工具报了一堆问题却给不出修复建议最后不了了之。所以如果你打算上 impeccable先把设计令牌梳理清楚这一步的投入回报比最高。最后分享一个我自己的小习惯每次让 AI agent 生成完前端代码我不急着看效果先跑一遍 impeccable把 error 清完再看。这个顺序能帮我省下大量“看着不对但说不清哪不对”的时间。工具给的是清单你给的是判断两者配合起来才真的离“impeccable”近一点。