1. 项目缘起与核心定位
1.1 一个被名字耽误的实用工具
第一次看到"impeccable"这个词，很多人会愣一下——这词儿在词典里是"无可挑剔的、完美的"意思，用作项目名多少有点自嘲或者高标准的意味。但真正用过之后你会发现，它其实是一个面向AI coding agents时代的前端设计辅助工具，核心形态是一个CLI 命令行工具，同时配套了一个browser extension浏览器扩展。它的定位非常明确：让开发者在跟 AI 编程助手协作时，前端代码的产出质量能真正达到"挑不出毛病"的水准。
说白了，现在用 AI 写前端代码的人越来越多，但普遍有个痛点——AI 生成的界面代码能跑，但不好看、不规范、不符合设计系统。impeccable 就是冲着这个痛点来的。它不替代 AI，而是给 AI 的产出加一道"设计质检"的关卡。
这个项目适合谁？三类人最该关注：一是天天用 AI 辅助写前端、但总在 UI 细节上返工的开发者；二是想给团队建立前端代码规范、又不想手动 review 每一行的技术负责人；三是做独立产品、没有专职设计师、需要工具帮忙兜底的独立开发者。
1.2 为什么是 CLI + 浏览器扩展的组合
这里有个设计思路值得拆解。为什么不做成纯 Web 应用，也不做成纯编辑器插件，而是选了 CLI 加浏览器扩展？
CLI 的价值在于可集成。它能塞进 CI/CD 流程，能在 git hook 里跑，能被其他脚本调用。对于 AI coding agents 来说，CLI 是最自然的交互界面——agent 执行命令、拿到结构化输出、再决定下一步。这跟当前 codex cli、zcode cli 这类工具的使用习惯是一致的，开发者已经习惯了在终端里跟 AI 协作。
浏览器扩展的价值在于可视化验证。前端设计好不好，最终得在浏览器里看。扩展能实时抓取页面渲染结果，把设计层面的问题（间距、对比度、层级、响应式断点）直接标注出来。CLI 负责"批处理"和"集成"，扩展负责"实时反馈"和"视觉确认"，两者互补，覆盖了开发流程的不同阶段。
提示：如果你只装 CLI 不装扩展，能用，但会丢掉实时视觉反馈这一块；反过来只装扩展不装 CLI，就没法集成到自动化流程里。建议两个都上。
2. 核心能力拆解：它到底在检查什么
2.1 设计规范层面的静态检查
impeccable 最核心的能力，是对前端代码做设计规范层面的静态分析。注意，它不是 ESLint 那种语法检查，也不是 Prettier 那种格式化，它检查的是"设计意图"层面的东西。
具体来说，它会扫描你的 CSS、Tailwind 类名、组件样式定义，然后对照一套内置的设计规则库做比对。这套规则库覆盖了几个维度：
- 间距系统一致性：你的 margin、padding 是不是遵循了统一的 scale（比如 4px 基准的倍数），有没有出现 13px、17px 这种"随手写"的值。
- 颜色使用规范：有没有硬编码的十六进制颜色散落在各处，对比度是否达到可访问性标准（WCAG AA 至少 4.5:1）。
- 字体层级：字号、字重、行高的组合是否形成了清晰的视觉层级，有没有出现"标题和正文一样大"这种问题。
- 响应式断点：媒体查询的断点值是否统一，有没有在五个不同地方写了五个不同的断点。
这些检查项听起来基础，但实际项目里翻车率极高。我见过太多 AI 生成的前端代码，功能没问题，但间距全是 magic number，颜色东一个西一个，改起来比重写还累。
2.2 与 AI coding agents 的协作机制
这是 impeccable 最有意思的部分。它不是简单地"报错"，而是输出结构化的、AI 可读的诊断报告。
当你用 codex cli 或者类似的 AI 编程助手时，可以让 agent 先跑一遍 impeccable，拿到一份 JSON 格式的问题清单，然后 agent 根据这份清单去修复。整个流程是这样的：
- Agent 生成前端代码
- 执行
impeccable check命令 - 拿到结构化的问题报告（包含文件、行号、问题类型、建议修复值）
- Agent 逐条修复
- 再跑一次验证
这个闭环的价值在于，它把"设计质量"这个原本很主观的东西，变成了 AI 能理解和执行的明确指令。AI 不需要"猜"你想要什么样的间距，impeccable 直接告诉它"这里应该是 16px 不是 13px"。
注意：不同 AI agent 对结构化输出的解析能力不一样。实测下来，codex cli 和 trae cli 对 JSON 格式的诊断报告处理得比较顺，能自动定位到具体行去改。如果你的 agent 解析能力弱，可以先用
--format=text输出人类可读版本，手动喂给它。
2.3 浏览器扩展的实时标注能力
浏览器扩展这块，做的是运行时检查。它注入一个轻量的脚本到页面里，实时计算每个元素的盒模型、颜色对比度、字体渲染结果，然后在页面上叠加标注层。
这个能力在调试响应式布局时特别有用。你可以拖动浏览器窗口改变宽度，扩展会实时告诉你当前断点下哪些元素溢出了、哪些文字对比度不够了、哪些点击区域小于 44x44 的可访问性最小值了。这些问题是静态代码检查抓不到的，必须运行时才能发现。
扩展还支持快照对比。你可以保存一个"设计基准"快照，然后每次改完代码刷新页面，扩展会自动 diff 出视觉差异。这个功能在跟 AI 反复迭代界面时简直是救命稻草——AI 改了一版，你一眼就能看出它是不是把之前调好的间距又改乱了。
3. 实操落地：从安装到集成进工作流
3.1 安装与初始化配置
安装部分，CLI 走的是标准的包管理流程。假设你用 npm 生态：
npm install -g impeccable-cli装完之后，在项目根目录初始化配置：
impeccable init这个命令会生成一个impeccable.config.json文件。这个配置文件是整个工具的核心，它决定了检查规则、忽略路径、输出格式等。一个典型的配置长这样：
{ "designSystem": { "spacingScale": [0, 4, 8, 12, 16, 24, 32, 48, 64], "colorPalette": "./tokens/colors.json", "typographyScale": "./tokens/typography.json", "breakpoints": [640, 768, 1024, 1280, 1536] }, "ignore": ["node_modules/**", "dist/**", "**/*.test.*"], "severity": { "spacing": "error", "color": "error", "contrast": "error", "typography": "warn" }, "output": { "format": "json", "reportPath": "./.impeccable/report.json" } }这里有几个配置项值得展开说。spacingScale定义了你项目允许的间距值集合，任何不在这个集合里的间距都会被标记。colorPalette指向你的设计 token 文件，impeccable 会检查代码里有没有绕过 token 直接用硬编码颜色。severity让你能分级处理——间距和颜色这种硬性问题设成 error，字体层级这种偏主观的设成 warn。
提示：初始化时如果你项目里已经有 Tailwind 配置，impeccable 能自动读取
tailwind.config.js里的 theme 配置，帮你预填 spacingScale 和 colorPalette。省得手动抄一遍。
3.2 跑第一次检查与读懂报告
配置好之后，跑一次全量检查：
impeccable check --path=./src第一次跑，报告大概率会很长。别慌，这是正常的。重点看报告的结构：
{ "summary": { "filesScanned": 47, "issuesFound": 213, "errors": 156, "warnings": 57 }, "issues": [ { "file": "src/components/Button.tsx", "line": 23, "column": 5, "rule": "spacing-scale", "severity": "error", "message": "Padding value 13px is not in the spacing scale", "suggestion": "Use 12px or 16px instead", "context": "padding: 13px 20px;" } ] }读报告有个技巧：先按 rule 分组看，别按文件看。因为同一类问题往往在项目里成片出现，按规则分组能让你一次性理解"我这类问题有多严重"，然后批量修。比如你发现 spacing-scale 报了 80 个错，那说明整个项目的间距系统是失控的，这时候该做的是统一重构，而不是一个个改。
3.3 集成进 AI 协作流程
真正发挥威力，是把它接进 AI coding agent 的工作流。以 codex cli 为例，你可以在项目根目录放一个 agent 指令文件，告诉它每次改完前端代码后自动跑 impeccable：
# 在 agent 的工作流配置里加入 impeccable check --path=./src --format=json --reportPath=./.impeccable/latest.json然后给 agent 的提示词里加上一句："修改完成后，读取 .impeccable/latest.json，修复所有 severity 为 error 的问题，修复后重新运行检查直到 error 数为 0。"
实测下来，这个闭环能把 AI 生成前端代码的"设计返工率"降低一大半。以前 AI 写完你得手动调半天间距颜色，现在它自己就能收敛到一个规范的状态。
注意：别让 agent 无限循环修复。设个上限，比如最多迭代 3 轮。有些问题（比如设计 token 本身定义得有问题）agent 是修不好的，会陷入死循环。这时候需要人工介入调整配置。
3.4 浏览器扩展的安装与使用
浏览器扩展的安装走的是常规流程，从扩展商店装或者开发者模式加载本地包都行。装完之后，在任意页面上点扩展图标，会弹出一个小面板。
面板上有几个核心功能：
- 实时检查开关：打开后页面上会叠加标注层，有问题的元素会被高亮。
- 快照保存：点一下保存当前页面的视觉基准。
- 差异对比：刷新页面后点对比，会显示跟基准快照的视觉差异。
- 导出报告：把当前页面的运行时问题导出成 JSON，可以喂给 CLI 一起分析。
我个人的使用习惯是：开发阶段开着实时检查，边写边看；改完一个模块后保存快照；让 AI 迭代几轮后做一次差异对比，确认没有引入视觉回归。
4. 踩坑记录与问题排查
4.1 常见问题速查表
| 问题现象 | 可能原因 | 排查与解决 |
|---|---|---|
| 检查报告为空 | 路径配置错误或文件被 ignore | 检查--path参数和 config 里的 ignore 规则 |
| 大量误报 | 设计 token 未正确加载 | 确认 colorPalette/typographyScale 路径正确且文件格式合法 |
| 扩展标注不显示 | 页面有 CSP 限制或 iframe 隔离 | 检查控制台是否有 CSP 报错，尝试在非 iframe 页面测试 |
| AI agent 修复后问题依旧 | agent 未读取最新报告 | 确认报告路径一致，且 agent 有文件读取权限 |
| 快照对比差异过大 | 页面有动态内容（时间、随机数） | 在扩展设置里排除动态区域，或改用静态测试数据 |
| CLI 执行超时 | 扫描文件过多 | 用--path缩小范围，或增加--timeout参数 |
4.2 几个我踩过的坑
坑一：spacingScale 设得太严。一开始我把 scale 设成只有 4 的倍数，结果项目里所有 6px、10px 这种"半格"值全报错，报告几千条，根本没法看。后来改成允许 4 的倍数加上常用的半格值（6、10、14），误报率立刻降下来。设计系统不是越严格越好，得贴合实际使用习惯。
坑二：忽略动态内容导致快照对比失效。有次做差异对比，每次都报一大堆差异，查了半天发现是页面上的时间戳和随机推荐位在变。后来在扩展设置里把这些区域标记为"动态排除"，对比才准了。
坑三：让 AI 修 contrast 问题修出花来。对比度不够的问题，AI 有时候会直接把文字改成纯黑或纯白，对比度是够了，但设计上很难看。后来我在配置里加了contrastStrategy: "adjust-lightness"，让它优先调整明度而不是直接换色，效果好很多。
坑四：CI 里跑 impeccable 没设阈值。有段时间 CI 天天红，因为 impeccable 报了一堆 warn 级别的问题。后来在 CI 配置里加了--fail-on=error，只有 error 级别才让流水线失败，warn 只记录不阻断，团队接受度立刻上来了。
4.3 性能优化的小技巧
项目大了之后，全量检查会变慢。几个提速手段：
- 用
--incremental模式，只检查上次检查后变动的文件。 - 把
node_modules、dist、测试文件都加进 ignore。 - 如果只是想在提交前快速过一遍，用
--changed-only只检查 git staged 的文件。 - 浏览器扩展的实时检查可以调低采样频率，默认是每 500ms 扫一次，改成 1000ms 对体验影响不大但省不少 CPU。
5. 进阶玩法与扩展思路
5.1 自定义规则开发
impeccable 支持自定义规则。规则文件是一个导出特定接口的 JS 模块：
module.exports = { name: 'no-inline-style', severity: 'warn', check(node, context) { if (node.type === 'JSXAttribute' && node.name.name === 'style') { return { message: 'Inline style detected, use className instead', suggestion: 'Move styles to CSS module or Tailwind classes' }; } return null; } };把规则文件放进.impeccable/rules/目录，重启检查就会自动加载。这个能力让你能把团队内部的设计约定也变成可自动检查的规则。比如"所有按钮必须有 hover 态"、"所有图片必须有 alt 属性"这类约定，都能写成规则。
5.2 与设计工具的联动
如果你的团队用 Figma 之类的设计工具，可以把设计 token 导出成 JSON，直接喂给 impeccable 的 colorPalette 和 typographyScale。这样设计稿和代码之间的 token 就完全同步了，设计师改了颜色，导出一次，代码检查规则自动更新。
这个联动做起来不难，Figma 有 token 导出插件，导出的 JSON 格式稍微转换一下就能用。关键是建立起"设计 token 单一来源"的机制，避免设计和代码各维护一套。
5.3 在 monorepo 里的用法
monorepo 项目里，可以在根目录放一份共享的 impeccable 配置，各个子包通过 extends 继承：
{ "extends": "../../impeccable.config.json", "designSystem": { "colorPalette": "./tokens/colors.json" } }这样共享规则统一维护，各包只覆盖自己特有的部分。跑检查的时候在根目录跑全量，或者进到具体子包跑增量，都行。
6. 关于工具选型的一点个人看法
市面上做前端代码质量检查的工具不少，ESLint、Stylelint、Prettier 各管一摊。impeccable 的差异化在于它面向 AI 协作场景做了专门优化——结构化输出、可被 agent 解析、支持迭代修复闭环。这是传统 lint 工具没考虑的维度。
但它也不是万能的。它管的是"设计规范"这一层，语法错误、逻辑 bug、性能问题它都不管。所以实际项目里，它是跟 ESLint、Stylelint 配合使用的，各司其职。我的建议是把它当成"设计质检员"，而不是"全能代码检查器"。
另外，工具再好，设计 token 本身得先定义清楚。如果项目连一套统一的间距和颜色规范都没有，impeccable 跑出来的报告只会是一团乱麻。上这个工具之前，先把设计系统的基础打好，收益会大得多。
最后分享一个我自己的使用节奏：新项目初始化时就配好 impeccable，让 AI 从第一行代码就在规范内生成；老项目接入时先跑一次全量，把 error 级别的问题批量修掉，warn 级别的慢慢来；日常开发开着浏览器扩展的实时检查，改完一个模块做一次快照对比。这套节奏跑下来，前端界面的返工率能压到很低，跟 AI 协作的体验也顺畅很多。
