1. 从“impeccable”这个词说起为什么前端圈突然都在聊它第一次看到“impeccable”这个词是在几个前端群里有人甩出一张截图配文是“这玩意儿生成的界面比我手写的还干净”。点进去一看是一个跟 AI coding agents 配合使用的工具主打前端设计的自动化生成与校验。说实话2024 年到 2025 年这段时间AI 辅助编程的工具多如牛毛从 CLI 到浏览器扩展从代码补全到整项目生成几乎每周都有新东西冒出来。但“impeccable”这个词本身就很有意思——它的意思是“无可挑剔的、完美的”一个工具敢用这个词当名字要么是狂妄要么是真有两把刷子。我花了大概两周时间把 impeccable 跟目前主流的几个 AI coding agents 工作流都跑了一遍包括通过 CLI 调用的方式、浏览器扩展的交互方式以及它跟 codex cli、zcode cli 这类命令行工具的配合逻辑。结论先放在这里它解决的不是“能不能生成代码”的问题而是“生成的前端代码能不能直接用”的问题。这两者之间的差距做过前端的人都知道可能是十分钟和十小时的差距。这篇文章适合几类人看一是已经在用 AI coding agents 写前端、但总觉得产出质量不稳定的开发者二是刚接触 CLI 工具链、想搞清楚 codex cli 安装和常用命令的新手三是团队里负责前端规范、想找一个自动化设计校验方案的技术负责人。我会从核心思路、实操步骤、参数配置、常见坑几个维度展开尽量把每个环节的“为什么”讲清楚而不是只丢一堆命令让你抄。需要提前说明的是impeccable 本身并不是一个孤立的工具它更像是嵌在 AI coding agents 工作流里的一个“质量层”。你单独用它也能跑但配合 CLI 和浏览器扩展一起用才能发挥出完整价值。下面我会按照实际操作的顺序一层一层拆开讲。2. impeccable 到底在解决什么问题核心思路与方案选型2.1 前端 AI 生成的“最后一公里”困境用过 AI coding agents 的人应该都有体会让模型生成一个登录页、一个数据看板、一个表单组件它能在几秒内给你吐出几百行代码。但问题在于这些代码往往存在几个通病。第一是样式冗余同一个间距值可能用了三种不同的写法margin 和 padding 混着来。第二是响应式断点随意有时候用 768px有时候用 800px完全没有体系。第三是交互状态缺失hover、focus、disabled 这些状态要么没写要么写得不一致。第四是语义化标签乱用该用 button 的地方用了 div该用 nav 的地方用了 section。这些问题单独看都不致命但累积起来就导致一个结果生成的代码能跑但不敢直接上生产。你得花大量时间做 code review、手动调整、统一规范。这个“最后一公里”的成本往往比生成代码本身还高。impeccable 的思路就是把这个“最后一公里”自动化掉。它不是重新训练一个模型而是在 AI coding agents 的输出和最终交付之间插入一个设计规范校验与自动修正的环节。你可以把它理解成一个“前端设计的 linter formatter”但它的规则不是简单的代码风格而是更高层的设计系统一致性。2.2 为什么选择 CLI 浏览器扩展的双入口设计impeccable 提供了两种使用方式CLI 和浏览器扩展。这个设计不是拍脑袋决定的而是对应了两类完全不同的使用场景。CLI 方式适合批量处理、CI/CD 集成、以及跟 codex cli 这类工具链配合。比如你在终端里用 codex cli 生成了一批组件代码可以直接通过管道把输出传给 impeccable 做校验和修正。这种方式的好处是可脚本化、可自动化适合团队统一规范。浏览器扩展方式则适合实时预览和交互式调整。你在浏览器里打开一个页面扩展会实时分析 DOM 结构和样式给出优化建议甚至可以一键应用修正。这种方式更适合设计师和前端开发者在开发过程中即时反馈。两种方式共享同一套规则引擎所以校验结果是一致的。区别只在于触发时机和交互方式。我个人的习惯是开发阶段用浏览器扩展做实时检查提交代码前用 CLI 做一次全量扫描确保没有遗漏。2.3 跟 codex cli、zcode cli 的关系不是替代是互补很多人容易把 impeccable 和 codex cli 搞混觉得都是命令行工具是不是功能重叠。实际上它们的定位完全不同。codex cli 是一个 AI coding agent 的命令行入口负责“生成”代码impeccable 负责“校验和修正”代码。一个是生产者一个是质检员。在实际工作流里典型的链路是这样的你用 codex cli 执行一个生成任务比如“创建一个带搜索功能的用户列表页”codex cli 会调用模型生成代码并写入文件。然后你用 impeccable 的 CLI 命令扫描这些文件它会输出一份设计规范报告指出哪些地方不符合预设规则并给出修正建议。如果你开启了自动修正模式它会直接修改文件。最后你再跑一遍测试确认功能正常。zcode cli 也是类似的定位不同的 AI coding agent 工具在生成能力上各有侧重但 impeccable 对它们都是兼容的。它不关心你的代码是哪个模型生成的只关心生成的结果是否符合设计规范。这种解耦设计让它可以灵活嵌入各种工作流。3. 核心细节解析规则引擎、配置体系与实操要点3.1 规则引擎的底层逻辑从设计令牌到代码约束impeccable 的核心是一个规则引擎它的输入是设计令牌design tokens和代码文件输出是校验报告和修正后的代码。设计令牌这个概念在前端领域已经比较成熟了简单说就是把颜色、间距、字体、圆角、阴影这些设计决策抽象成变量。impeccable 的做法是你先把设计令牌定义好它会自动把这些令牌转换成代码层面的约束规则。举个例子假设你在配置里定义了间距令牌spacing-sm: 8px、spacing-md: 16px、spacing-lg: 24px。impeccable 会生成一条规则所有 margin 和 padding 的值必须是这三个令牌之一不允许出现 10px、12px、20px 这种“野生值”。如果检测到违规它会标记出来并在自动修正模式下替换成最接近的合法值。这个逻辑听起来简单但实际实现起来要考虑很多边界情况。比如负 margin 怎么处理百分比值怎么处理calc() 表达式怎么处理impeccable 的策略是对于无法直接映射到令牌的值它会给出警告但不自动修正避免误伤。这个设计很务实因为自动修正的前提是“修正结果一定比原结果好”如果做不到这一点宁可不动。3.2 配置文件的结构与关键参数说明impeccable 的配置文件通常是一个 JSON 或 YAML 文件放在项目根目录下命名为.impeccable.json或impeccable.config.yaml。我以 JSON 格式为例拆解一下关键字段。{ tokens: { spacing: { sm: 8px, md: 16px, lg: 24px, xl: 32px }, colors: { primary: #2563eb, secondary: #64748b, danger: #dc2626 }, radius: { sm: 4px, md: 8px, full: 9999px } }, rules: { spacing-consistency: error, color-palette: error, responsive-breakpoints: warn, interactive-states: error, semantic-html: warn }, autoFix: { enabled: true, safeMode: true, excludePatterns: [**/vendor/**, **/*.min.css] }, breakpoints: [640, 768, 1024, 1280, 1536] }tokens字段定义设计令牌这是整个规则体系的基础。rules字段定义每条规则的严重级别error表示必须修正warn表示建议修正但不阻塞。autoFix控制自动修正行为safeMode开启后只会做“确定性修正”比如把 10px 改成 8px 或 12px 中更接近的那个而不会做主观判断。breakpoints定义允许的响应式断点任何不在这个列表里的断点值都会被标记。这里有个实操心得safeMode建议一直开着除非你对项目非常熟悉。我试过关闭 safeMode结果 impeccable 把一个刻意设计的 10px 间距改成了 8px虽然符合规则但破坏了视觉节奏。自动修正再智能也不如人了解设计意图。3.3 浏览器扩展的安装与实时校验机制浏览器扩展的安装方式跟普通扩展一样从扩展商店搜索 impeccable 即可。安装后你需要在扩展设置里填入项目的配置文件路径或者直接粘贴配置内容。扩展会自动检测当前页面是否匹配项目规则如果匹配就会在开发者工具里注入一个 impeccable 面板。这个面板会实时显示当前页面的校验结果按严重级别分组。点击某一条问题会高亮对应的 DOM 元素并显示具体的违规原因和修正建议。如果开启了自动修正面板上会有一个“应用全部安全修正”的按钮点击后扩展会通过 content script 修改页面样式你可以立即看到效果。这里要注意一点浏览器扩展的实时校验是基于当前渲染后的 DOM而不是源代码。这意味着它能看到动态生成的元素和运行时样式这是 CLI 做不到的。但反过来它无法直接修改源文件只能修改运行时样式。所以扩展适合“发现问题”CLI 适合“修复问题”。两者配合使用效果最好。3.4 跟 AI coding agents 的集成方式impeccable 跟 AI coding agents 的集成有两种模式前置校验和后置校验。前置校验是在生成代码之前把设计令牌和规则注入到 prompt 里让模型在生成时就遵循规范。后置校验是在生成代码之后用 impeccable 扫描并修正。前置校验的优点是减少返工缺点是会占用 prompt 长度而且模型不一定完全遵守。后置校验的优点是确定性高缺点是如果生成质量太差修正成本可能很高。我的建议是两者结合在 prompt 里简要说明关键约束比如“使用 8px 基准间距体系”然后用后置校验兜底。具体操作上如果你用的是 codex cli可以在命令里加一个--post-process参数指定 impeccable 作为后处理工具。这样 codex cli 生成完代码后会自动调用 impeccable 做校验和修正。如果你用的是其他 CLI 工具也可以通过 shell 管道实现类似效果codex generate --prompt 创建用户列表页 --output ./src/pages/user-list.tsx impeccable check ./src/pages/user-list.tsx --fix这个链路跑通之后你的工作流就变成了描述需求 - AI 生成 - 自动校验修正 - 人工确认。中间两个环节完全自动化你只需要关注输入和输出。4. 完整实操流程从零搭建 impeccable 工作流4.1 环境准备与 CLI 安装第一步是确认你的 Node.js 环境。impeccable 的 CLI 是基于 Node.js 的建议版本在 18 以上。如果你还没装 Node.js去官网下载 LTS 版本即可。安装完成后用node -v确认版本。接下来安装 impeccable CLI。官方推荐用 npm 全局安装npm install -g impeccable-cli如果你在国内网络环境下觉得慢可以换用镜像源或者用 pnpm、yarn 等包管理器。安装完成后运行impeccable --version确认安装成功。如果提示命令找不到检查一下 npm 全局 bin 目录是否在 PATH 里。这里有个常见坑有些人之前装过 codex cli 或其他 AI coding agents 的 CLI 工具可能会有命令名冲突。impeccable 的命令名就是impeccable一般不会冲突但如果你之前装过同名工具建议先卸载再装。另外如果你用的是 Windows 系统建议在 WSL 或 Git Bash 里操作原生 CMD 和 PowerShell 对某些 shell 管道的支持不够好。4.2 初始化项目配置进入你的项目根目录运行impeccable init这个命令会引导你创建一个配置文件。它会问你几个问题项目类型React、Vue、原生 HTML 等、是否使用 TypeScript、设计令牌的来源手动定义、从 Figma 导入、从现有 CSS 提取。根据你的实际情况选择即可。如果你选择“从现有 CSS 提取”impeccable 会扫描你的样式文件自动识别出常用的颜色、间距、字体值生成一份初始令牌配置。这个功能很实用尤其是对于已经有一定规模的项目不需要从零开始定义令牌。初始化完成后你会得到一个.impeccable.json文件。建议先不要急着改规则先用默认配置跑一遍全量扫描看看项目当前的健康状况。4.3 执行首次全量扫描与报告解读运行以下命令对整个项目做一次扫描impeccable check ./src --report--report参数会生成一份详细的 HTML 报告放在.impeccable/report.html。打开报告你会看到几个维度的数据违规总数、按规则分类的分布、按文件分类的分布、以及每条违规的具体位置和修正建议。我第一次跑的时候报告显示有 300 多条违规主要集中在间距不一致和颜色值硬编码上。这个数字看起来很吓人但仔细看会发现大部分违规是重复的比如同一个颜色值在多个文件里硬编码。这种情况下优先修正高频问题收益最大。报告里有一个“影响范围”指标表示某条规则违规影响的文件数量。建议按这个指标排序先处理影响范围大的问题。另外报告支持导出为 JSON 格式方便你集成到 CI 流程里做自动化门禁。4.4 自动修正与人工复核的配合确认报告后可以执行自动修正impeccable check ./src --fix这个命令会修改源文件把所有“安全修正”应用上去。执行前建议先提交一次代码或者确保有备份方便对比修正前后的差异。修正完成后用git diff查看变更。你会发现大部分变更是把硬编码值替换成了 CSS 变量或令牌引用。比如margin: 10px变成了margin: var(--spacing-sm)。这种变更在功能上是等价的但可维护性提升很大。不过要注意自动修正不是万能的。有些违规它只能标记不能修正比如“缺少 hover 状态”这种需要补充代码逻辑的问题。这些需要人工处理。我的做法是先跑自动修正把能自动化的部分处理掉然后人工处理剩下的警告最后再跑一次扫描确认没有新增问题。4.5 集成到 CI/CD 流程如果你想让 impeccable 成为团队规范的一部分可以把它集成到 CI 流程里。在 GitHub Actions 或 GitLab CI 的配置文件里加一个步骤- name: Run impeccable check run: | npm install -g impeccable-cli impeccable check ./src --ci --threshold error--ci参数会让 impeccable 以非交互模式运行--threshold error表示只有 error 级别的违规才会导致 CI 失败。这样既能保证代码质量又不会因为 warn 级别的建议阻塞合并。这里有个经验刚开始推行的时候建议把阈值设为error给团队一个适应期。等大家习惯了之后再逐步收紧到warn。如果一上来就卡得太严容易引起抵触情绪。5. 常见问题与排查技巧实录5.1 安装与配置阶段的典型问题问题一impeccable命令找不到。这个通常是因为 npm 全局 bin 目录不在 PATH 里。解决方法是用npm config get prefix查看全局目录然后把这个目录下的 bin 文件夹加到 PATH。Windows 用户尤其容易遇到这个问题建议用npm install -g impeccable-cli后重启终端。问题二初始化时无法识别项目类型。如果你用的是比较新的框架比如 Astro、SvelteKitimpeccable 可能没有对应的预设。这时候选择“手动配置”然后在配置文件里手动指定文件匹配模式。比如include: [**/*.astro, **/*.svelte]。问题三从现有 CSS 提取令牌时结果混乱。如果项目里的样式值本身就很随意提取出来的令牌也会很乱。建议先手动整理一份最小令牌集比如只定义 5 个间距值、5 个颜色值然后用这份令牌去扫描而不是让工具自动提取。5.2 扫描与修正阶段的常见异常问题四扫描速度慢。如果项目很大全量扫描可能需要几分钟。可以通过--include和--exclude参数缩小扫描范围或者用--cache开启缓存只扫描变更过的文件。问题五自动修正后样式错乱。这通常是因为某些值被错误地映射到了令牌。比如margin: 12px被改成了margin: var(--spacing-sm)8px视觉上就变了。解决办法是开启safeMode或者在配置里把某些文件加入excludePatterns让 impeccable 跳过这些文件。问题六跟 codex cli 配合时输出被截断。如果你用管道把 codex cli 的输出直接传给 impeccable可能会因为缓冲区大小限制导致截断。建议先把输出写入临时文件再让 impeccable 扫描文件。5.3 跟其他 CLI 工具链的兼容性排查问题七codex cli 安装很慢。这是网络问题跟 impeccable 无关。可以尝试换用国内镜像源或者用--registry参数指定镜像。如果还是慢考虑用离线安装包。问题八多个 CLI 工具的命令冲突。比如你同时装了 codex cli、zcode cli、minimax cli它们可能都依赖同一个底层库的不同版本。建议用 nvm 或 volta 管理 Node.js 版本给不同项目隔离环境。问题九浏览器扩展跟 CLI 的校验结果不一致。这通常是因为扩展读取的配置跟 CLI 读取的不是同一份。检查扩展设置里的配置文件路径是否正确以及是否有缓存。扩展一般有一个“重新加载配置”的按钮点一下即可。5.4 独家避坑技巧汇总问题类型典型表现排查思路解决方式安装失败命令找不到检查 PATH 和全局 bin 目录手动添加 PATH 或重装扫描慢全量扫描耗时过长检查项目文件数量用 include/exclude 缩小范围修正错误样式视觉变化检查令牌映射关系开启 safeMode 或排除文件结果不一致CLI 和扩展结果不同检查配置文件路径统一配置来源清除缓存CI 失败阈值设置过严检查违规级别分布调整 threshold 参数还有一个我踩过的坑impeccable 的规则引擎默认会检查所有 CSS 属性包括一些实验性的属性。如果你的项目用了比较新的 CSS 特性可能会被误报。解决办法是在配置里加一个ignoreProperties列表把不需要检查的属性排除掉。另外如果你在团队里推行 impeccable建议先在一个小项目上试点收集反馈后再推广。直接在全公司范围强制推行阻力会很大。我见过一个团队因为强制开启 autoFix导致一次提交修改了上千个文件code review 根本没法做。后来改成“只检查不修正”让大家手动处理反而推进得更顺利。6. 关于 AI coding agents 工作流的一些个人体会用了这段时间的 impeccable我最大的感受是AI 生成代码的质量瓶颈往往不在模型本身而在约束条件。你给模型的约束越明确、越结构化它的产出就越稳定。impeccable 本质上就是把“设计规范”这个约束条件结构化了让模型有章可循。另一个体会是工具链的整合比单个工具的能力更重要。codex cli 生成能力强impeccable 校验能力强但只有把它们串起来才能形成完整的闭环。单独用任何一个都只是半成品。我现在的工作流基本固定下来了用 codex cli 做批量生成用 impeccable 做质量兜底用浏览器扩展做实时反馈。三个环节各司其职效率比之前纯手写提升了大概三到四倍。最后分享一个小技巧impeccable 的配置文件可以继承。你可以定义一个基础配置放在项目根目录然后在子目录里放一个覆盖配置只修改需要差异化的部分。这样在多包仓库monorepo里特别好用不同包可以共享基础规则又有各自的灵活性。这个功能文档里没怎么提是我翻源码的时候发现的实测很稳。 
长河君 · 2026/10/27 14:57:42 · 阅读 1.2k impeccable 实战：AI 生成前端代码的自动化校验与修正
1. 从“impeccable”这个词说起为什么前端圈突然都在聊它第一次看到“impeccable”这个词是在几个前端群里有人甩出一张截图配文是“这玩意儿生成的界面比我手写的还干净”。点进去一看是一个跟 AI coding agents 配合使用的工具主打前端设计的自动化生成与校验。说实话2024 年到 2025 年这段时间AI 辅助编程的工具多如牛毛从 CLI 到浏览器扩展从代码补全到整项目生成几乎每周都有新东西冒出来。但“impeccable”这个词本身就很有意思——它的意思是“无可挑剔的、完美的”一个工具敢用这个词当名字要么是狂妄要么是真有两把刷子。我花了大概两周时间把 impeccable 跟目前主流的几个 AI coding agents 工作流都跑了一遍包括通过 CLI 调用的方式、浏览器扩展的交互方式以及它跟 codex cli、zcode cli 这类命令行工具的配合逻辑。结论先放在这里它解决的不是“能不能生成代码”的问题而是“生成的前端代码能不能直接用”的问题。这两者之间的差距做过前端的人都知道可能是十分钟和十小时的差距。这篇文章适合几类人看一是已经在用 AI coding agents 写前端、但总觉得产出质量不稳定的开发者二是刚接触 CLI 工具链、想搞清楚 codex cli 安装和常用命令的新手三是团队里负责前端规范、想找一个自动化设计校验方案的技术负责人。我会从核心思路、实操步骤、参数配置、常见坑几个维度展开尽量把每个环节的“为什么”讲清楚而不是只丢一堆命令让你抄。需要提前说明的是impeccable 本身并不是一个孤立的工具它更像是嵌在 AI coding agents 工作流里的一个“质量层”。你单独用它也能跑但配合 CLI 和浏览器扩展一起用才能发挥出完整价值。下面我会按照实际操作的顺序一层一层拆开讲。2. impeccable 到底在解决什么问题核心思路与方案选型2.1 前端 AI 生成的“最后一公里”困境用过 AI coding agents 的人应该都有体会让模型生成一个登录页、一个数据看板、一个表单组件它能在几秒内给你吐出几百行代码。但问题在于这些代码往往存在几个通病。第一是样式冗余同一个间距值可能用了三种不同的写法margin 和 padding 混着来。第二是响应式断点随意有时候用 768px有时候用 800px完全没有体系。第三是交互状态缺失hover、focus、disabled 这些状态要么没写要么写得不一致。第四是语义化标签乱用该用 button 的地方用了 div该用 nav 的地方用了 section。这些问题单独看都不致命但累积起来就导致一个结果生成的代码能跑但不敢直接上生产。你得花大量时间做 code review、手动调整、统一规范。这个“最后一公里”的成本往往比生成代码本身还高。impeccable 的思路就是把这个“最后一公里”自动化掉。它不是重新训练一个模型而是在 AI coding agents 的输出和最终交付之间插入一个设计规范校验与自动修正的环节。你可以把它理解成一个“前端设计的 linter formatter”但它的规则不是简单的代码风格而是更高层的设计系统一致性。2.2 为什么选择 CLI 浏览器扩展的双入口设计impeccable 提供了两种使用方式CLI 和浏览器扩展。这个设计不是拍脑袋决定的而是对应了两类完全不同的使用场景。CLI 方式适合批量处理、CI/CD 集成、以及跟 codex cli 这类工具链配合。比如你在终端里用 codex cli 生成了一批组件代码可以直接通过管道把输出传给 impeccable 做校验和修正。这种方式的好处是可脚本化、可自动化适合团队统一规范。浏览器扩展方式则适合实时预览和交互式调整。你在浏览器里打开一个页面扩展会实时分析 DOM 结构和样式给出优化建议甚至可以一键应用修正。这种方式更适合设计师和前端开发者在开发过程中即时反馈。两种方式共享同一套规则引擎所以校验结果是一致的。区别只在于触发时机和交互方式。我个人的习惯是开发阶段用浏览器扩展做实时检查提交代码前用 CLI 做一次全量扫描确保没有遗漏。2.3 跟 codex cli、zcode cli 的关系不是替代是互补很多人容易把 impeccable 和 codex cli 搞混觉得都是命令行工具是不是功能重叠。实际上它们的定位完全不同。codex cli 是一个 AI coding agent 的命令行入口负责“生成”代码impeccable 负责“校验和修正”代码。一个是生产者一个是质检员。在实际工作流里典型的链路是这样的你用 codex cli 执行一个生成任务比如“创建一个带搜索功能的用户列表页”codex cli 会调用模型生成代码并写入文件。然后你用 impeccable 的 CLI 命令扫描这些文件它会输出一份设计规范报告指出哪些地方不符合预设规则并给出修正建议。如果你开启了自动修正模式它会直接修改文件。最后你再跑一遍测试确认功能正常。zcode cli 也是类似的定位不同的 AI coding agent 工具在生成能力上各有侧重但 impeccable 对它们都是兼容的。它不关心你的代码是哪个模型生成的只关心生成的结果是否符合设计规范。这种解耦设计让它可以灵活嵌入各种工作流。3. 核心细节解析规则引擎、配置体系与实操要点3.1 规则引擎的底层逻辑从设计令牌到代码约束impeccable 的核心是一个规则引擎它的输入是设计令牌design tokens和代码文件输出是校验报告和修正后的代码。设计令牌这个概念在前端领域已经比较成熟了简单说就是把颜色、间距、字体、圆角、阴影这些设计决策抽象成变量。impeccable 的做法是你先把设计令牌定义好它会自动把这些令牌转换成代码层面的约束规则。举个例子假设你在配置里定义了间距令牌spacing-sm: 8px、spacing-md: 16px、spacing-lg: 24px。impeccable 会生成一条规则所有 margin 和 padding 的值必须是这三个令牌之一不允许出现 10px、12px、20px 这种“野生值”。如果检测到违规它会标记出来并在自动修正模式下替换成最接近的合法值。这个逻辑听起来简单但实际实现起来要考虑很多边界情况。比如负 margin 怎么处理百分比值怎么处理calc() 表达式怎么处理impeccable 的策略是对于无法直接映射到令牌的值它会给出警告但不自动修正避免误伤。这个设计很务实因为自动修正的前提是“修正结果一定比原结果好”如果做不到这一点宁可不动。3.2 配置文件的结构与关键参数说明impeccable 的配置文件通常是一个 JSON 或 YAML 文件放在项目根目录下命名为.impeccable.json或impeccable.config.yaml。我以 JSON 格式为例拆解一下关键字段。{ tokens: { spacing: { sm: 8px, md: 16px, lg: 24px, xl: 32px }, colors: { primary: #2563eb, secondary: #64748b, danger: #dc2626 }, radius: { sm: 4px, md: 8px, full: 9999px } }, rules: { spacing-consistency: error, color-palette: error, responsive-breakpoints: warn, interactive-states: error, semantic-html: warn }, autoFix: { enabled: true, safeMode: true, excludePatterns: [**/vendor/**, **/*.min.css] }, breakpoints: [640, 768, 1024, 1280, 1536] }tokens字段定义设计令牌这是整个规则体系的基础。rules字段定义每条规则的严重级别error表示必须修正warn表示建议修正但不阻塞。autoFix控制自动修正行为safeMode开启后只会做“确定性修正”比如把 10px 改成 8px 或 12px 中更接近的那个而不会做主观判断。breakpoints定义允许的响应式断点任何不在这个列表里的断点值都会被标记。这里有个实操心得safeMode建议一直开着除非你对项目非常熟悉。我试过关闭 safeMode结果 impeccable 把一个刻意设计的 10px 间距改成了 8px虽然符合规则但破坏了视觉节奏。自动修正再智能也不如人了解设计意图。3.3 浏览器扩展的安装与实时校验机制浏览器扩展的安装方式跟普通扩展一样从扩展商店搜索 impeccable 即可。安装后你需要在扩展设置里填入项目的配置文件路径或者直接粘贴配置内容。扩展会自动检测当前页面是否匹配项目规则如果匹配就会在开发者工具里注入一个 impeccable 面板。这个面板会实时显示当前页面的校验结果按严重级别分组。点击某一条问题会高亮对应的 DOM 元素并显示具体的违规原因和修正建议。如果开启了自动修正面板上会有一个“应用全部安全修正”的按钮点击后扩展会通过 content script 修改页面样式你可以立即看到效果。这里要注意一点浏览器扩展的实时校验是基于当前渲染后的 DOM而不是源代码。这意味着它能看到动态生成的元素和运行时样式这是 CLI 做不到的。但反过来它无法直接修改源文件只能修改运行时样式。所以扩展适合“发现问题”CLI 适合“修复问题”。两者配合使用效果最好。3.4 跟 AI coding agents 的集成方式impeccable 跟 AI coding agents 的集成有两种模式前置校验和后置校验。前置校验是在生成代码之前把设计令牌和规则注入到 prompt 里让模型在生成时就遵循规范。后置校验是在生成代码之后用 impeccable 扫描并修正。前置校验的优点是减少返工缺点是会占用 prompt 长度而且模型不一定完全遵守。后置校验的优点是确定性高缺点是如果生成质量太差修正成本可能很高。我的建议是两者结合在 prompt 里简要说明关键约束比如“使用 8px 基准间距体系”然后用后置校验兜底。具体操作上如果你用的是 codex cli可以在命令里加一个--post-process参数指定 impeccable 作为后处理工具。这样 codex cli 生成完代码后会自动调用 impeccable 做校验和修正。如果你用的是其他 CLI 工具也可以通过 shell 管道实现类似效果codex generate --prompt 创建用户列表页 --output ./src/pages/user-list.tsx impeccable check ./src/pages/user-list.tsx --fix这个链路跑通之后你的工作流就变成了描述需求 - AI 生成 - 自动校验修正 - 人工确认。中间两个环节完全自动化你只需要关注输入和输出。4. 完整实操流程从零搭建 impeccable 工作流4.1 环境准备与 CLI 安装第一步是确认你的 Node.js 环境。impeccable 的 CLI 是基于 Node.js 的建议版本在 18 以上。如果你还没装 Node.js去官网下载 LTS 版本即可。安装完成后用node -v确认版本。接下来安装 impeccable CLI。官方推荐用 npm 全局安装npm install -g impeccable-cli如果你在国内网络环境下觉得慢可以换用镜像源或者用 pnpm、yarn 等包管理器。安装完成后运行impeccable --version确认安装成功。如果提示命令找不到检查一下 npm 全局 bin 目录是否在 PATH 里。这里有个常见坑有些人之前装过 codex cli 或其他 AI coding agents 的 CLI 工具可能会有命令名冲突。impeccable 的命令名就是impeccable一般不会冲突但如果你之前装过同名工具建议先卸载再装。另外如果你用的是 Windows 系统建议在 WSL 或 Git Bash 里操作原生 CMD 和 PowerShell 对某些 shell 管道的支持不够好。4.2 初始化项目配置进入你的项目根目录运行impeccable init这个命令会引导你创建一个配置文件。它会问你几个问题项目类型React、Vue、原生 HTML 等、是否使用 TypeScript、设计令牌的来源手动定义、从 Figma 导入、从现有 CSS 提取。根据你的实际情况选择即可。如果你选择“从现有 CSS 提取”impeccable 会扫描你的样式文件自动识别出常用的颜色、间距、字体值生成一份初始令牌配置。这个功能很实用尤其是对于已经有一定规模的项目不需要从零开始定义令牌。初始化完成后你会得到一个.impeccable.json文件。建议先不要急着改规则先用默认配置跑一遍全量扫描看看项目当前的健康状况。4.3 执行首次全量扫描与报告解读运行以下命令对整个项目做一次扫描impeccable check ./src --report--report参数会生成一份详细的 HTML 报告放在.impeccable/report.html。打开报告你会看到几个维度的数据违规总数、按规则分类的分布、按文件分类的分布、以及每条违规的具体位置和修正建议。我第一次跑的时候报告显示有 300 多条违规主要集中在间距不一致和颜色值硬编码上。这个数字看起来很吓人但仔细看会发现大部分违规是重复的比如同一个颜色值在多个文件里硬编码。这种情况下优先修正高频问题收益最大。报告里有一个“影响范围”指标表示某条规则违规影响的文件数量。建议按这个指标排序先处理影响范围大的问题。另外报告支持导出为 JSON 格式方便你集成到 CI 流程里做自动化门禁。4.4 自动修正与人工复核的配合确认报告后可以执行自动修正impeccable check ./src --fix这个命令会修改源文件把所有“安全修正”应用上去。执行前建议先提交一次代码或者确保有备份方便对比修正前后的差异。修正完成后用git diff查看变更。你会发现大部分变更是把硬编码值替换成了 CSS 变量或令牌引用。比如margin: 10px变成了margin: var(--spacing-sm)。这种变更在功能上是等价的但可维护性提升很大。不过要注意自动修正不是万能的。有些违规它只能标记不能修正比如“缺少 hover 状态”这种需要补充代码逻辑的问题。这些需要人工处理。我的做法是先跑自动修正把能自动化的部分处理掉然后人工处理剩下的警告最后再跑一次扫描确认没有新增问题。4.5 集成到 CI/CD 流程如果你想让 impeccable 成为团队规范的一部分可以把它集成到 CI 流程里。在 GitHub Actions 或 GitLab CI 的配置文件里加一个步骤- name: Run impeccable check run: | npm install -g impeccable-cli impeccable check ./src --ci --threshold error--ci参数会让 impeccable 以非交互模式运行--threshold error表示只有 error 级别的违规才会导致 CI 失败。这样既能保证代码质量又不会因为 warn 级别的建议阻塞合并。这里有个经验刚开始推行的时候建议把阈值设为error给团队一个适应期。等大家习惯了之后再逐步收紧到warn。如果一上来就卡得太严容易引起抵触情绪。5. 常见问题与排查技巧实录5.1 安装与配置阶段的典型问题问题一impeccable命令找不到。这个通常是因为 npm 全局 bin 目录不在 PATH 里。解决方法是用npm config get prefix查看全局目录然后把这个目录下的 bin 文件夹加到 PATH。Windows 用户尤其容易遇到这个问题建议用npm install -g impeccable-cli后重启终端。问题二初始化时无法识别项目类型。如果你用的是比较新的框架比如 Astro、SvelteKitimpeccable 可能没有对应的预设。这时候选择“手动配置”然后在配置文件里手动指定文件匹配模式。比如include: [**/*.astro, **/*.svelte]。问题三从现有 CSS 提取令牌时结果混乱。如果项目里的样式值本身就很随意提取出来的令牌也会很乱。建议先手动整理一份最小令牌集比如只定义 5 个间距值、5 个颜色值然后用这份令牌去扫描而不是让工具自动提取。5.2 扫描与修正阶段的常见异常问题四扫描速度慢。如果项目很大全量扫描可能需要几分钟。可以通过--include和--exclude参数缩小扫描范围或者用--cache开启缓存只扫描变更过的文件。问题五自动修正后样式错乱。这通常是因为某些值被错误地映射到了令牌。比如margin: 12px被改成了margin: var(--spacing-sm)8px视觉上就变了。解决办法是开启safeMode或者在配置里把某些文件加入excludePatterns让 impeccable 跳过这些文件。问题六跟 codex cli 配合时输出被截断。如果你用管道把 codex cli 的输出直接传给 impeccable可能会因为缓冲区大小限制导致截断。建议先把输出写入临时文件再让 impeccable 扫描文件。5.3 跟其他 CLI 工具链的兼容性排查问题七codex cli 安装很慢。这是网络问题跟 impeccable 无关。可以尝试换用国内镜像源或者用--registry参数指定镜像。如果还是慢考虑用离线安装包。问题八多个 CLI 工具的命令冲突。比如你同时装了 codex cli、zcode cli、minimax cli它们可能都依赖同一个底层库的不同版本。建议用 nvm 或 volta 管理 Node.js 版本给不同项目隔离环境。问题九浏览器扩展跟 CLI 的校验结果不一致。这通常是因为扩展读取的配置跟 CLI 读取的不是同一份。检查扩展设置里的配置文件路径是否正确以及是否有缓存。扩展一般有一个“重新加载配置”的按钮点一下即可。5.4 独家避坑技巧汇总问题类型典型表现排查思路解决方式安装失败命令找不到检查 PATH 和全局 bin 目录手动添加 PATH 或重装扫描慢全量扫描耗时过长检查项目文件数量用 include/exclude 缩小范围修正错误样式视觉变化检查令牌映射关系开启 safeMode 或排除文件结果不一致CLI 和扩展结果不同检查配置文件路径统一配置来源清除缓存CI 失败阈值设置过严检查违规级别分布调整 threshold 参数还有一个我踩过的坑impeccable 的规则引擎默认会检查所有 CSS 属性包括一些实验性的属性。如果你的项目用了比较新的 CSS 特性可能会被误报。解决办法是在配置里加一个ignoreProperties列表把不需要检查的属性排除掉。另外如果你在团队里推行 impeccable建议先在一个小项目上试点收集反馈后再推广。直接在全公司范围强制推行阻力会很大。我见过一个团队因为强制开启 autoFix导致一次提交修改了上千个文件code review 根本没法做。后来改成“只检查不修正”让大家手动处理反而推进得更顺利。6. 关于 AI coding agents 工作流的一些个人体会用了这段时间的 impeccable我最大的感受是AI 生成代码的质量瓶颈往往不在模型本身而在约束条件。你给模型的约束越明确、越结构化它的产出就越稳定。impeccable 本质上就是把“设计规范”这个约束条件结构化了让模型有章可循。另一个体会是工具链的整合比单个工具的能力更重要。codex cli 生成能力强impeccable 校验能力强但只有把它们串起来才能形成完整的闭环。单独用任何一个都只是半成品。我现在的工作流基本固定下来了用 codex cli 做批量生成用 impeccable 做质量兜底用浏览器扩展做实时反馈。三个环节各司其职效率比之前纯手写提升了大概三到四倍。最后分享一个小技巧impeccable 的配置文件可以继承。你可以定义一个基础配置放在项目根目录然后在子目录里放一个覆盖配置只修改需要差异化的部分。这样在多包仓库monorepo里特别好用不同包可以共享基础规则又有各自的灵活性。这个功能文档里没怎么提是我翻源码的时候发现的实测很稳。