1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI 帮你写一段前端代码它噼里啪啦吐出来一大坨结构看着像那么回事但真丢进项目里跑一遍间距不对、颜色不统一、响应式断点乱套、组件命名前后矛盾——能用但离“无懈可击”差着十万八千里。impeccable 这个词本身就是“无可挑剔、完美无瑕”的意思把它用作一个面向 AI coding agents 的前端设计工具野心其实写在了名字里它想让 AI 生成的前端界面从“能跑”变成“能看、能交付”。我先把结论摆在前面方便你对号入座。impeccable 本质上是一套围绕AI coding agents 的前端设计约束与校验体系它通过 CLI 和 browser extension 两种形态落地核心目标是给 AI 生成的前端代码套上一层“设计规范护栏”。它解决的不是“AI 会不会写代码”的问题而是“AI 写出来的前端代码符不符合设计标准”的问题。适合谁来用三类人最该关注一是天天用 AI coding agents 写页面的前端工程师二是想用 AI 快速出原型但被“AI 审美”折磨的产品和设计同学三是团队里负责统一前端规范、天天给别人的代码擦屁股的技术负责人。为什么这个话题现在值得聊因为 AI coding agents 已经过了“能不能生成代码”的阶段进入了“生成的东西能不能直接用”的阶段。前端恰恰是 AI 最容易翻车的领域之一——后端逻辑错了测试能抓出来前端设计丑了、乱了、不一致了测试是抓不出来的只能靠人眼和规范。impeccable 这类工具的出现本质上是把“设计 review”这件事从人肉流程里抽出来变成可自动化、可被 AI agent 调用的能力。下面我会从设计思路、核心机制、CLI 与 browser extension 的实操、以及踩坑排查几个角度把它拆开讲透。2. 核心设计思路拆解为什么是 CLI 加浏览器扩展这套组合2.1 前端设计的“不可测试性”才是真正的痛点要理解 impeccable 为什么这么设计得先理解前端设计为什么难管。后端代码有单元测试、集成测试接口返回对不对断言一写就清楚。前端呢一个按钮的圆角是 4px 还是 6px主色调是 #3B82F6 还是 #2563EB卡片间距是 16px 还是 24px这些东西没有“对错”只有“一致不一致”。而 AI coding agents 最大的问题恰恰是不一致同一个项目里它这次给你写padding: 16px下次可能就写padding: 1rem再下次直接上padding: 0.75rem 1.25rem。单看每一处都合理放一起就是灾难。impeccable 的设计思路就是把这层“一致性”变成机器可校验的规则。它不去评判你的设计好不好看——审美是主观的——它评判的是你的设计是否自洽。这个定位非常关键也是我认为它比那些“AI 生成 UI”工具更务实的地方。生成 UI 的工具是在做加法impeccable 是在做减法它约束 AI 别乱来。2.2 为什么同时要 CLI 和 browser extension很多人会问既然有 CLI为什么还要搞个浏览器扩展这不是重复造轮子吗我实际用下来这两者的分工非常清晰缺一不可。CLI 的定位是面向 AI agent 和 CI 流程的自动化入口。AI coding agents 干活的时候是在终端里跑的它能调用命令行工具但调不动浏览器扩展。所以 impeccable 必须有一个 CLI让 agent 在生成代码后能主动跑一次校验拿到结构化的反馈然后自我修正。这是“让 AI 自己检查自己”的关键闭环。没有 CLIAI 就是个闭眼画画的画完不知道好坏。browser extension 的定位是面向人的可视化审查入口。CLI 给你的是文本报告但设计问题很多时候是“看一眼就知道”的。浏览器扩展能直接在真实渲染的页面上把问题标出来——哪个元素间距不一致、哪个颜色偏离了设计 token、哪个断点下布局塌了高亮显示所见即所得。人做最终 review 的时候看扩展的标注比读 CLI 的日志快十倍。所以这套组合的本质是CLI 管机器闭环扩展管人的验收。AI 用 CLI 自检自修人用扩展做终审。这个分工想明白了后面所有的操作逻辑就都顺了。2.3 它和传统 lint 工具的根本区别你可能会说ESLint、Stylelint 不也能查样式问题吗区别在于抽象层级。Stylelint 查的是语法层面的东西比如“有没有用未定义的变量”“有没有重复的属性”。impeccable 查的是设计系统层面的东西比如“这个间距是否属于你定义的 spacing scale”“这个颜色是否在你的 palette 里”“这个组件的圆角是否和同类组件一致”。打个比方Stylelint 像是语文老师改错别字impeccable 像是主编审文章风格是否统一。前者保证你写的是通顺的中文后者保证你整本书的文风一致。AI 生成代码最容易犯的恰恰是后者——每一句都通顺合起来不像一个人写的。这就是 impeccable 存在的意义它填的是 lint 工具和设计系统之间的那块空白。3. 核心机制解析impeccable 到底在检查什么3.1 设计 token 的一致性校验impeccable 最核心的能力是围绕设计 token做一致性校验。所谓设计 token就是把颜色、间距、字号、圆角、阴影这些设计决策抽成命名变量比如--color-primary、--space-md、--radius-sm。规范的做法是所有样式都引用 token不写魔法数字。AI coding agents 的通病就是爱写魔法数字。你让它加个间距它直接margin-top: 18px而不是margin-top: var(--space-lg)。单看没问题但项目里如果有二十个地方都这么干间距就彻底失控了。impeccable 会扫描你的代码和渲染结果找出那些没有引用 token 的硬编码值并标记出来。这里有个实操细节值得说impeccable 判断一个值是否“合规”不是简单地看它是不是变量而是看它是否落在你定义的 token 集合里。比如你定义了 spacing scale 是 4/8/12/16/24/32那18px就算硬编码因为它不在 scale 里但16px即使写成字面量它也在 scale 内严重程度就低一档。这个分级判断很聪明避免了“一刀切”带来的噪音。3.2 组件级的一致性比对比 token 更进一层的是组件级一致性。同一个项目里按钮应该有统一的圆角、统一的 padding、统一的字号。但 AI 生成的时候这个按钮border-radius: 6px那个按钮border-radius: 8px肉眼几乎看不出来但设计系统就崩了。impeccable 的做法是识别出同类组件比如所有button或者所有带btn类名的元素然后横向比对它们的样式属性找出离群值。这个思路和数据分析里的异常检测是一样的大多数按钮都是 6px 圆角就你一个是 8px那你就是异常。这种“少数服从多数”的启发式规则在实际项目里命中率相当高。注意组件一致性校验依赖类名和标签的语义识别如果你的项目类名全是div1、div2这种无语义命名识别准确率会大幅下降。这也是为什么我一直建议 AI 生成代码时要求它用语义化类名。3.3 响应式断点的覆盖检查前端设计翻车的重灾区是响应式。AI 生成代码时往往只考虑了当前视口你让它写个卡片它给你写死width: 400px到了手机上直接溢出。impeccable 会检查你的样式是否覆盖了关键断点以及在不同断点下是否存在布局冲突。具体来说它会模拟几个标准视口比如移动端 375px、平板 768px、桌面 1280px检查元素是否溢出容器、是否发生重叠、文字是否被截断。这些检查在 CLI 里是静态分析加规则推断在 browser extension 里则是真实渲染后的测量后者更准。我实测下来扩展的断点检查比 CLI 靠谱因为真实渲染能抓到很多静态分析抓不到的动态问题。3.4 与 AI agent 的反馈闭环前面说的都是“检查”但 impeccable 真正的价值在于把检查结果喂回给 AI agent。它的 CLI 输出是结构化的通常是 JSON包含问题位置、问题类型、严重程度、建议修复方式。AI agent 拿到这个 JSON就能针对性地改代码改完再跑一次 CLI直到通过。这个闭环是它区别于普通 lint 工具的关键。普通 lint 工具的输出是给人看的impeccable 的输出是同时给人看也给机器看的。你在配置里可以指定输出格式agent 读 JSON人读可读版报告。这个设计思路我认为是未来所有“AI 辅助开发工具”的标配——工具必须能被 agent 调用否则就进不了自动化流程。4. CLI 实操从安装到接入 AI coding agents4.1 安装与初始化配置CLI 的安装走的是标准的包管理流程具体命令取决于你用的生态。假设它是 Node 生态前端工具绝大多数是典型安装方式是这样# 全局安装方便在任何项目里调用 npm install -g impeccable-cli # 或者作为项目开发依赖锁定版本更稳妥 npm install --save-dev impeccable-cli我个人强烈建议用项目本地依赖而不是全局安装。原因很简单全局安装的版本会随着你更新而变今天跑得好好的规则明天可能因为版本升级就报一堆新错团队里每个人环境还不一样。本地依赖锁在package.json里谁跑都是同一个版本结果可复现。这是踩过坑之后的血泪教训。安装完第一步是初始化配置npx impeccable init这个命令会在项目根目录生成一个配置文件通常叫impeccable.config.json或类似名字。配置文件里最关键的几块是设计 token 的来源是从 CSS 变量读还是从 Tailwind 配置读还是从 Figma 导出的 JSON 读、检查规则的开关和严重程度、以及输出格式。{ tokens: { source: css-variables, path: ./src/styles/tokens.css }, rules: { no-hardcoded-spacing: error, component-consistency: warn, responsive-coverage: error }, output: { format: json, path: ./impeccable-report.json } }这里有个关键决策点token 来源选哪个。如果你的项目用 Tailwind直接从tailwind.config.js读最省事因为 Tailwind 的配置本身就是一套 token 系统。如果你用的是原生 CSS 变量那就指向你的 tokens 文件。如果你是从设计工具同步过来的那就用导出的 JSON。选错了来源校验结果会全是误报这点务必先确认清楚。4.2 跑第一次校验与读懂报告配置好之后跑一次完整校验npx impeccable check --path ./src第一次跑报告大概率会很难看这是正常的。我建议第一次先别急着修先读懂报告的分布。报告通常按严重程度分三档error必须修、warn建议修、info提示。你要做的是看 error 集中在哪类问题上。假设报告显示 80% 的 error 都是no-hardcoded-spacing那说明你的项目里硬编码间距是主要矛盾优先解决这个。如果 error 分散在各类问题上那可能是你的 token 定义本身就不完整AI 找不到合适的 token 可用只能硬编码。这时候要先补全 token 体系而不是逐个改代码。# 只看 error 级别过滤掉噪音 npx impeccable check --path ./src --severity error # 输出成人类可读的表格形式 npx impeccable check --path ./src --format table提示第一次校验建议加--severity error过滤否则 warn 和 info 会把报告淹没你根本找不到重点。等 error 清零了再逐步处理 warn。4.3 把 CLI 接入 AI coding agent 的工作流这是 CLI 最有价值的用法。你要做的是在 AI agent 的工作流里插入一个“生成后自检”的步骤。以常见的 agent 工作流为例逻辑是这样的Agent 生成或修改前端代码Agent 调用npx impeccable check --format jsonAgent 读取 JSON 报告识别出自己引入的新问题Agent 针对新问题修改代码重复 2-4直到没有新增 error关键在于只关注新增问题。项目里可能本来就有一堆历史遗留问题如果让 agent 去修所有问题它会改得面目全非还可能引入新 bug。正确做法是让 agent 只对自己这次改动负责。实现方式是在改动前后各跑一次对比差异# 改动前存个基线 npx impeccable check --format json baseline.json # agent 改完代码后 npx impeccable check --format json current.json # 对比找出新增问题 npx impeccable diff baseline.json current.json这个 diff 能力是接入 agent 的关键。没有 diffagent 会被历史问题干扰有了 diffagent 的注意力就聚焦在自己身上。我在实际项目里用这套流程AI 生成的前端代码一次通过率从大概三成提到了七成以上剩下的三成也能在两次迭代内收敛。4.4 在 CI 里设置质量门禁CLI 的另一个重要用途是 CI 门禁。你可以在流水线里加一步如果新增的 error 超过阈值就阻断合并。这样能防止 AI 生成的烂代码悄悄溜进主分支。# 以通用 CI 配置为例 - name: impeccable check run: | npx impeccable check --format json report.json npx impeccable gate report.json --max-errors 0 --max-warnings 20gate命令的作用是如果报告里的 error 超过 0 个或者 warn 超过 20 个就返回非零退出码CI 判定失败。阈值怎么定我的经验是 error 必须为 0因为 error 都是硬伤warn 可以给个缓冲因为有些 warn 是历史遗留一刀切会让团队没法推进。等历史 warn 清理得差不多了再把阈值收紧。5. Browser Extension 实操可视化审查与人工终审5.1 安装与页面标注机制浏览器扩展的安装走的是浏览器商店或者开发者模式加载。装好之后打开你的项目页面点扩展图标它会在页面上叠加一层标注。标注的形式通常是有问题的元素加彩色边框鼠标悬停显示问题详情侧边栏列出所有问题。扩展的工作机制是注入脚本 读取计算样式。它不看你写的源码而是看浏览器最终渲染出来的计算样式computed style。这个视角很重要因为源码里写var(--space-md)计算出来是16px扩展看到的是16px然后判断这个16px是否在 token 集合里。所以扩展的检查结果和 CLI 可能有细微差异——CLI 看源码扩展看渲染结果。两者结合才能覆盖全。我实测下来扩展最擅长抓三类问题一是视觉不一致比如两个本该一样的按钮颜色差了一点点肉眼看不出来扩展一标就现形二是响应式塌陷拖动窗口大小扩展会实时提示哪个断点下布局出问题三是层级和对比度文字和背景的对比度是否达标这个对无障碍很重要。5.2 用扩展做人工终审的正确姿势扩展不是用来替代 CLI 的而是用来做人工终审的。我的工作流是这样的AI agent 用 CLI 自检通过后我在浏览器里打开页面用扩展过一遍。这时候我关注的不是“有没有 error”而是“这些通过校验的地方看起来对不对”。因为规则是死的设计是活的。有些东西规则查不出来但人一眼就知道不对。比如一个卡片间距、颜色、圆角全都合规但整体比例就是别扭留白太多或者太挤。这种“感觉不对”的问题只能靠人。扩展的价值在于它把机械的检查都做完了人的注意力可以全部放在审美和体验上而不是浪费在找硬编码上。注意扩展的标注会改变页面的视觉呈现加了边框和遮罩所以做视觉终审时记得先关掉标注层看原始效果。我见过有人对着带标注的页面调间距调完关掉标注发现全乱了就是因为标注层影响了视觉判断。5.3 扩展与 CLI 的结果对齐有时候你会发现扩展报的问题和 CLI 报的不一样别慌这通常是正常的。原因有几个一是前面说的源码视角 vs 渲染视角的差异二是扩展可能只检查当前视口而 CLI 检查所有断点三是动态内容比如 JS 渲染出来的元素扩展能看到CLI 静态分析看不到。处理原则是以扩展的结果为准做最终判断以 CLI 的结果为准做自动化门禁。因为扩展看到的是用户真正看到的东西更接近真相而 CLI 是为了让 agent 能自动化处理牺牲一点精度换效率是值得的。如果两者差异特别大那说明你的项目里有大量动态渲染或者构建时转换这时候要检查配置里的 token 来源是否和实际渲染一致。6. 常见问题与排查技巧实录6.1 误报太多怎么办这是新手最常遇到的问题一跑校验几百个 error仔细一看全是误报。原因通常是 token 来源配置错了或者 token 集合定义得太窄。排查步骤先确认配置文件里的tokens.source和tokens.path指向的是你项目真正在用的那套 token。如果你用 Tailwind但配置指向了一个空的 CSS 变量文件那所有 Tailwind 的类名都会被判为硬编码。确认来源对了之后再看 token 集合是否完整——如果你的设计系统里有 8 档间距但配置文件里只定义了 4 档那另外 4 档就会被误报。{ tokens: { source: tailwind, path: ./tailwind.config.js, spacingScale: [4, 8, 12, 16, 24, 32, 48, 64], colorPalette: [primary, secondary, neutral, danger, success] } }6.2 AI agent 反复改不对同一个问题有时候 agent 拿到报告改了一版问题还在再改还在。这通常是因为问题描述不够具体agent 不知道你到底要它改成什么。CLI 的 JSON 报告里每条问题应该包含问题位置文件行号选择器、当前值、期望值或期望范围、修复建议。如果报告里只有“间距不一致”这种模糊描述agent 就只能瞎猜。解决办法是在配置里开启详细模式让报告包含具体的建议值。比如不要只说“这个间距不在 scale 里”而要说“这个间距是 18px最接近的 scale 值是 16px 或 24px建议改为 16px”。给了具体建议agent 的修复成功率会大幅提升。6.3 扩展在某些页面上不工作扩展不工作常见原因有三个一是页面用了 Shadow DOM扩展的注入脚本进不去二是页面有严格的内容安全策略阻止了脚本注入三是页面是 iframe 嵌套的扩展默认只注入顶层文档。排查顺序先看控制台有没有报错如果有 CSP 相关的报错那就是内容安全策略的问题需要在扩展设置里把该域名加白名单。如果是 Shadow DOM目前多数扩展的支持有限只能退而求其次用 CLI 检查。iframe 的问题可以在扩展设置里开启“注入所有框架”选项。6.4 常见问题速查表问题现象可能原因排查方向解决方式误报大量硬编码token 来源配置错误检查 tokens.source 和 path指向真实的 token 文件agent 反复改不对报告描述太模糊查看 JSON 是否含建议值开启详细模式扩展不注入CSP 或 Shadow DOM看控制台报错加白名单或改用 CLICLI 和扩展结果不一致源码视角 vs 渲染视角对比两者检查范围以扩展为准做终审CI 门禁频繁失败阈值设置过严看历史遗留问题数量先放宽 warn 阈值响应式检查漏报只检查了当前视口确认断点配置补全断点列表6.5 几条踩坑心得第一条别追求一次清零。历史项目跑 impeccable第一次几百个问题很正常想一次全修完人会崩溃agent 也会改出 bug。正确做法是设个基线只保证新增问题为零历史问题分批慢慢还。第二条token 体系要先于工具建设。如果你的项目压根没有设计 token直接上 impeccable 就是自找麻烦。先把颜色、间距、字号抽成变量哪怕抽得不完美也比没有强。工具是放大器你得先有东西给它放大。第三条agent 的修复能力取决于你的提示词。同样的 CLI 报告你在提示词里说“根据报告修复问题”和说“只修复 error 级别、且是你本次改动引入的问题每修一个跑一次校验”效果天差地别。工具再好也得配合清晰的指令。7. 我对这套工具链的真实看法用了一段时间 impeccable 这套 CLI 加扩展的组合我最大的感受是它把“前端设计规范”这件事从靠人自觉变成了靠工具约束。以前团队里定规范全靠 code review 时人肉抓抓不抓得到看 reviewer 心情和眼力。现在有了自动化校验规范变成了可执行、可度量、可门禁的东西AI agent 也被纳入了这个约束体系。它当然不完美。规则是死的设计是活的有些审美层面的东西它永远查不出来。但它的定位本来就不是替代设计师而是把设计师和工程师从机械的一致性检查里解放出来去做真正需要人判断的事。这个定位我认为非常准。如果你现在正在用 AI coding agents 写前端我建议你先从 CLI 入手把它接进你的 agent 工作流感受一下“AI 自检自修”的闭环。等你习惯了这种模式再上浏览器扩展做人工终审。这个顺序别反了——先让机器把机械的活干了人再上场做判断效率最高。反过来先上扩展你会被人肉审查的工作量劝退。最后分享一个我自己的小习惯每次 agent 生成完前端代码我不急着看代码先跑一遍 CLI看报告里的 error 数量。如果 error 是零我才会打开浏览器看效果。这个习惯帮我省了大量时间因为大部分 AI 生成的代码第一轮都是有硬伤的先让工具筛一遍人只看筛过的效率翻倍。