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 自己检查自己”的关键闭环。没有 CLI，AI 就是个闭眼画画的，画完不知道好坏。

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 agents

4.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 工作流为例，逻辑是这样的：

1. Agent 生成或修改前端代码
2. Agent 调用npx impeccable check --format json
3. Agent 读取 JSON 报告，识别出自己引入的新问题
4. Agent 针对新问题修改代码
5. 重复 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 的关键。没有 diff，agent 会被历史问题干扰；有了 diff，agent 的注意力就聚焦在自己身上。我在实际项目里用这套流程，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 20

gate命令的作用是：如果报告里的 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 常见问题速查表

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 生成的代码，第一轮都是有硬伤的，先让工具筛一遍，人只看筛过的，效率翻倍。