1. 项目缘起与核心定位

第一次看到 "impeccable" 这个词被拿来命名一个开发工具，我的反应是：这名字起得挺狂。"Impeccable" 的意思是"无可挑剔的、完美的"，一个工具敢叫这个名字，要么是过度自信，要么是真的有两把刷子。花了两周时间把它揉进日常开发流程之后，我的判断偏向后者——它确实解决了一个长期被忽视的痛点：AI 编码代理生成的前端代码，质量参差不齐，而人工审查又极其耗时。

这个项目的核心定位很清晰：它是一个面向 AI 编码代理（AI coding agents）的前端设计质量守门员。你可以把它理解成一个"设计审查员"，专门盯着 AI 生成的前端代码，从视觉一致性、布局合理性、响应式适配、可访问性等维度给出评估和改进建议。它同时提供了 CLI 工具和浏览器扩展两种形态，前者适合集成到自动化流程里，后者适合在开发过程中实时查看页面质量。

适合谁来用？三类人最应该关注：一是重度依赖 AI 编码代理做前端开发的独立开发者，二是需要把控团队代码质量的前端负责人，三是正在探索 AI 辅助开发工作流的技术团队。如果你只是偶尔用 AI 写几行 CSS，这个工具可能有点重；但如果你已经把 AI 代理当成日常开发的主力，那它值得你花时间研究。

我最初是在一个用 AI 代理批量生成落地页的项目里接触到它的。当时的情况是：代理生成的页面单看每个都还行，但放到一起就露馅了——间距不统一、颜色体系混乱、移动端断点处理随意。人工一个个改，效率极低。impeccable 的出现，让这个环节从"人工逐页审查"变成了"工具批量扫描 + 重点修复"，时间成本大概降了六成。

2. 核心机制与设计思路拆解

2.1 为什么是"设计质量"而不是"代码质量"

市面上做代码质量检查的工具已经很多了，ESLint、Prettier、Stylelint 各司其职。但 impeccable 切入的角度不一样——它关注的是设计层面的质量，而不是语法层面的规范。这个区别很关键。

举个例子：一段 CSS 代码可能完全符合 Stylelint 的规则，没有重复属性、没有未使用的选择器，但它做出来的页面可能间距混乱、层级不清、在移动端挤成一团。传统 linter 管不了这些，因为它们不理解"设计意图"。impeccable 的做法是引入一套设计评估模型，从视觉层次、空间节奏、色彩协调、响应式行为等维度去判断页面"看起来对不对"。

这个思路背后的逻辑是：AI 编码代理在生成前端代码时，语法错误其实很少，真正的问题集中在设计决策上。代理不知道你的品牌色是什么、不知道你的间距体系是 4px 还是 8px 基准、不知道移动端应该优先展示什么内容。这些"设计上下文"的缺失，才是 AI 生成前端代码质量不稳定的根源。

2.2 CLI 与浏览器扩展的分工逻辑

impeccable 提供两种使用形态，这不是简单的"多端支持"，而是针对不同工作场景的刻意设计。

CLI 工具的定位是批量和自动化。你可以在 CI/CD 流程里跑它，对每次提交的前端代码做设计质量扫描，输出报告。也可以在本地对一整个项目目录做全量检查。它的优势是快、可脚本化、适合集成。我通常会在两个节点用它：一是 AI 代理生成完一批页面之后，跑一次全量扫描；二是代码合并到主分支之前，作为质量门禁。

浏览器扩展的定位是实时和交互。你在浏览器里打开正在开发的页面，扩展会实时分析当前渲染结果，把有问题的区域高亮出来，点击就能看到具体问题和修改建议。这个形态适合调试阶段——你改一行 CSS，立刻能看到设计质量评分的变化。它的优势是直观、反馈快、不需要切换工具。

两种形态共享同一套评估引擎，所以 CLI 扫出来的问题和扩展看到的问题是一致的。这个一致性很重要，否则你会陷入"CLI 说没问题但扩展报一堆错"的混乱。

2.3 评估维度的设计考量

impeccable 的评估维度不是拍脑袋定的，而是围绕 AI 生成前端代码的典型缺陷来设计的。根据我的使用观察，它主要覆盖以下几个方向：

视觉层次与信息架构：检查页面是否有清晰的视觉焦点，标题、正文、辅助信息的层级是否分明。AI 代理经常犯的错是把所有元素做成一样的视觉权重，导致页面"平"得没有重点。

空间节奏与间距体系：检查 margin、padding 是否遵循一致的基准单位。AI 代理容易在不同组件里用不同的间距值，4px、6px、8px 混着来，页面看起来就"脏"。

色彩协调与对比度：检查颜色使用是否在合理的色域内，文字与背景的对比度是否达到可访问性标准。这个维度直接关系到页面的专业感和可读性。

响应式行为：检查在不同视口宽度下的布局表现，是否有溢出、重叠、内容截断等问题。AI 代理生成的响应式代码经常只在标准断点测试过，边缘情况处理得很粗糙。

可访问性基础：检查语义化标签、alt 文本、焦点状态、ARIA 属性等。这块是 AI 代理最容易忽略的，因为训练数据里可访问性做得好的样本本身就少。

注意：impeccable 的评估结果不是"对错"判断，而是"质量评分 + 改进建议"。它不会说你的代码有 bug，而是说"这个区域的间距偏离了页面基准值，建议统一为 8px 的倍数"。理解这一点很重要，否则你会把它当成 linter 来用，然后觉得它"报了一堆不是问题的问题"。

3. 实操环境搭建与核心配置

3.1 CLI 工具的安装与初始化

impeccable 的 CLI 安装方式取决于你的运行环境。如果你用的是 Node.js 生态，通过包管理器全局安装是最直接的方式：

npm install -g impeccable-cli

安装完成后，在项目根目录执行初始化命令：

impeccable init

这个命令会做几件事：生成一个impeccable.config.js配置文件，创建.impeccableignore忽略文件，并在package.json里添加相关的脚本命令。初始化过程中，它会问你几个问题：项目使用的前端框架是什么、设计系统的基础间距单位是多少、品牌主色是什么。这些问题不是随便问的，它们直接决定了后续评估的基准线。

我建议在初始化时认真填写这些信息。特别是"基础间距单位"这一项，如果你填了 8px，但实际项目里混用了 4px 和 12px，评估结果就会频繁报"间距不一致"。这时候你有两个选择：要么统一项目间距，要么把基准值调成实际使用最频繁的那个值。我的经验是，新项目直接定 8px 基准，老项目先扫描一遍统计实际间距分布，再决定基准值。

3.2 配置文件的关键参数解析

impeccable.config.js是控制评估行为的核心文件。以下是我在实际使用中认为最需要关注的几个配置项：

module.exports = { // 评估的严格程度：strict / standard / relaxed strictness: 'standard', // 设计基准参数 design: { baseSpacing: 8, // 基础间距单位（px） colorPalette: ['#1a1a2e', '#16213e', '#0f3460', '#e94560'], fontScale: [12, 14, 16, 20, 24, 32, 48], borderRadius: [0, 4, 8, 16, 9999] }, // 评估维度权重 weights: { visualHierarchy: 0.25, spacing: 0.25, color: 0.2, responsive: 0.2, accessibility: 0.1 }, // 忽略规则 ignore: { selectors: ['.legacy-*', '#third-party-widget'], files: ['**/vendor/**', '**/node_modules/**'] }, // 输出格式 output: { format: 'detailed', // detailed / summary / json showSuggestions: true, maxIssuesPerFile: 20 } }

strictness这个参数值得单独说一下。strict模式下，任何偏离基准值的间距都会被标记；standard模式允许一定范围的浮动，比如 8px 基准下，7-9px 会被视为可接受；relaxed模式只标记严重偏离。我一般在新项目上用strict，在老项目重构时用standard，在快速原型阶段用relaxed。

weights的配置决定了最终评分的计算方式。如果你做的项目对可访问性要求特别高（比如面向公共服务的产品），可以把accessibility的权重调高。如果只是内部工具，可以适当降低。

3.3 浏览器扩展的安装与联动

浏览器扩展的安装方式取决于你使用的浏览器。以 Chrome 为例，可以在扩展商店搜索 "impeccable" 安装，或者从项目的 GitHub Releases 页面下载.crx文件手动加载。

安装完成后，扩展图标会出现在工具栏。点击图标，会弹出一个小面板，显示当前页面的设计质量评分和问题数量。点击"详细报告"，会打开一个侧边栏，列出所有检测到的问题，按严重程度排序。

扩展和 CLI 的联动是通过配置文件实现的。扩展会读取项目根目录的impeccable.config.js，所以你在 CLI 里配置的基准参数，扩展也会遵循。这个设计很贴心，避免了"两套标准"的混乱。

提示：浏览器扩展在分析本地开发服务器（如localhost:3000）的页面时，需要确保扩展有访问本地地址的权限。如果发现扩展不工作，先检查扩展的权限设置里是否允许了本地地址。

3.4 与 AI 编码代理的集成方式

impeccable 最有价值的用法，是把它嵌入到 AI 编码代理的工作流里。具体来说，有两种集成模式：

模式一：生成后扫描。AI 代理生成完代码后，自动触发 impeccable 扫描，把评估报告作为反馈喂回给代理，让代理根据报告做第二轮修改。这个模式适合批量生成场景，比如一次性生成 20 个页面组件。

模式二：生成前约束。把 impeccable 的配置参数作为提示词的一部分，提前告诉 AI 代理设计基准是什么。比如在系统提示里写明"基础间距单位为 8px，主色为 #1a1a2e，圆角只使用 0/4/8/16 四档"。这个模式能显著降低第一轮生成的问题数量。

我实测下来，模式二的效果更好，因为它从源头减少了问题的产生。模式一更像是"事后补救"，虽然也能用，但代理在第二轮修改时可能会引入新的不一致。两种模式结合使用效果最佳：先用模式二约束生成，再用模式一扫描兜底。

4. 完整实操流程与关键环节

4.1 对现有项目做一次全量设计质量扫描

假设你有一个已经用 AI 代理生成了一批页面的项目，现在想全面评估设计质量。以下是完整的操作流程：

第一步，在项目根目录执行扫描命令：

impeccable scan --path ./src --output ./reports

这个命令会递归扫描./src目录下的所有前端文件，把报告输出到./reports目录。扫描过程中，终端会实时显示进度和已发现的问题数量。

第二步，查看汇总报告。扫描完成后，./reports目录下会生成几个文件：summary.md是总体评分和问题分布，details.json是每个问题的详细信息，trend.html是一个可视化页面，用图表展示各维度的得分。

我通常会先看summary.md，了解整体情况。比如下面是一个真实项目的扫描结果片段：

项目设计质量总评：72/100（标准） 维度得分： - 视觉层次：68/100 - 空间节奏：61/100 - 色彩协调：85/100 - 响应式行为：74/100 - 可访问性：70/100 问题分布： - 严重问题：12 个 - 中等问题：34 个 - 轻微问题：67 个 高频问题类型： 1. 间距值偏离基准（43 次） 2. 标题层级跳跃（18 次） 3. 移动端内容溢出（11 次） 4. 对比度不足（9 次）

第三步，根据报告制定修复优先级。我的原则是：先修严重问题，再修高频的中等问题，轻微问题可以批量处理或暂时忽略。严重问题通常集中在响应式溢出和对比度不足上，这两类问题直接影响可用性，必须优先解决。

第四步，针对高频问题做批量修复。比如"间距值偏离基准"出现了 43 次，这时候不要一个个改，而是先统计所有偏离的间距值，找出最接近的基准倍数，然后用查找替换批量处理。impeccable 的details.json里会列出每个问题的具体位置和当前值，你可以据此生成替换脚本。

4.2 用浏览器扩展做实时调试

全量扫描解决的是"存量问题"，浏览器扩展解决的是"增量问题"。在开发过程中，我习惯把扩展面板常驻在侧边栏，每改完一个组件就刷新看一下评分变化。

扩展面板的交互设计很直接：页面上的问题区域会被高亮，颜色越深表示问题越严重。鼠标悬停在高亮区域上，会弹出一个小卡片，显示具体问题和修改建议。点击卡片上的"应用建议"，扩展会生成一段修改代码，你可以直接复制到编辑器里。

这里有一个使用技巧：扩展的评估是基于当前渲染结果的，所以它能看到一些静态分析看不到的问题。比如两个元素在代码层面间距设置没问题，但因为父容器的 padding 叠加，实际渲染出来的间距偏大。这类问题只有扩展能发现。

我通常在两种情况下会打开扩展：一是调完一个复杂组件的样式后，快速验证一下有没有引入新的设计问题；二是在做响应式适配时，拖动浏览器窗口宽度，观察扩展评分的变化，找到断点处理最差的区间。

4.3 把 impeccable 接入 AI 代理工作流

这是我认为 impeccable 最有价值的用法。以下是我实际使用的一套工作流配置：

首先，在 AI 代理的系统提示里加入设计约束：

你是一个前端开发代理。在生成任何前端代码时，必须遵循以下设计基准： - 基础间距单位：8px，所有 margin/padding 必须是 8 的倍数 - 主色：#1a1a2e，辅助色：#16213e、#0f3460，强调色：#e94560 - 字号阶梯：12/14/16/20/24/32/48px - 圆角：只使用 0/4/8/16/9999px 五档 - 响应式断点：640px、768px、1024px、1280px - 所有图片必须有 alt 属性 - 所有交互元素必须有可见的焦点状态

然后，在代理生成代码后，自动触发 impeccable 扫描：

impeccable scan --path ./generated --output ./reports --format json

接着，解析 JSON 报告，提取严重问题，构造反馈提示：

const report = require('./reports/details.json'); const criticalIssues = report.issues.filter(i => i.severity === 'critical'); if (criticalIssues.length > 0) { const feedback = criticalIssues.map(i => `文件 ${i.file} 第 ${i.line} 行：${i.message}。建议：${i.suggestion}` ).join('\n'); // 把 feedback 作为下一轮提示发给代理 }

最后，让代理根据反馈做第二轮修改。这个循环可以跑两到三轮，直到严重问题清零。

我实测下来，这套流程能把 AI 生成前端代码的"可用率"从大概 60% 提升到 85% 以上。剩下的 15% 通常是需要人工判断的设计决策问题，比如"这个页面的视觉重心应该放在哪里"，这类问题工具解决不了，得人来定。

4.4 参数计算与基准值确定

在配置 impeccable 时，最需要动脑子的是确定设计基准值。这不是随便填几个数字就完事的，基准值定得合不合理，直接决定了评估结果有没有参考价值。

以间距基准为例。假设你统计了项目里所有 margin 和 padding 的值，得到以下分布：

从数据看，8px 出现频率最高，16px 和 12px 紧随其后。这三个值都是 4 的倍数，所以基础单位定 4px 是合理的，然后常用档位取 8/12/16/24/32。如果你定 8px 为基础单位，那 12px 和 4px 就会被标记为"偏离"，但实际上它们在这个项目里是合理的存在。

我的建议是：先跑一次impeccable analyze-spacing命令，它会统计项目里所有间距值的分布，并给出推荐的基准单位。这个命令的输出比手动统计准确得多，而且会考虑不同组件类型的差异。

色彩基准的确定类似。impeccable 会提取项目里所有使用的颜色值，做聚类分析，找出实际使用的主色、辅助色和强调色。如果发现颜色数量超过 10 个，它会提示"色彩体系过于分散，建议收敛"。

5. 常见问题与排查技巧实录

5.1 扫描结果全是"误报"怎么办

这是新手最常见的问题。跑完扫描，发现报告里几百个问题，但仔细一看，大部分都是"间距偏离基准"这种看起来无关痛痒的提示。这时候不要急着关掉工具，先做三件事：

第一，检查基准值配置是否合理。如果你项目实际用的是 4px 基准，但配置里写了 8px，那所有 4px 的间距都会被标记。改配置，重新扫描。

第二，调整strictness级别。从strict降到standard，允许一定范围的浮动。很多"偏离"其实是设计上有意为之的微调，不需要一刀切。

第三，配置忽略规则。第三方组件、遗留代码、实验性页面，这些不需要纳入评估范围。在.impeccableignore里把它们排除掉。

做完这三步，问题数量通常会降到可管理的范围。如果还是很多，那说明项目确实存在系统性的设计不一致，这时候应该把扫描报告当成重构的路线图，而不是"误报清单"。

5.2 浏览器扩展不显示评分

扩展不工作通常有几个原因。最常见的是页面没有完全加载完就触发了分析，导致评估结果不完整。解决方法是等页面load事件触发后再手动点击扩展图标刷新。

另一个原因是页面使用了 Shadow DOM 或 iframe，扩展的注入脚本无法穿透。这种情况下，扩展会显示"部分内容无法分析"。如果关键内容在 Shadow DOM 里，可以尝试在扩展设置里开启"深度分析模式"，但这会降低分析速度。

还有一种情况是页面 CSP（内容安全策略）限制了扩展脚本的执行。这个在开发环境下比较少见，但如果你的项目配置了严格的 CSP，需要在 CSP 里为扩展脚本放行。

5.3 与现有 linter 的冲突处理

impeccable 和 Stylelint、ESLint 在功能上有重叠，但关注点不同。冲突通常出现在两个方面：

一是格式化规则。Stylelint 可能要求margin: 0 0 8px 0，而 impeccable 建议margin-bottom: 8px。这类冲突以 Stylelint 为准，因为格式化是它的专长。在 impeccable 配置里把相关的检查项关掉。

二是颜色命名。Stylelint 可能要求使用变量而非硬编码颜色值，而 impeccable 在分析色彩协调时需要读取实际颜色值。这个不冲突，因为 impeccable 可以解析 CSS 变量。确保你的变量定义在 impeccable 能读取到的位置即可。

我的做法是：让 Stylelint 管语法和格式，让 impeccable 管设计质量，两者各司其职。在 CI 流程里，先跑 Stylelint，通过后再跑 impeccable。

5.4 评估报告中的问题优先级判断

impeccable 把问题分为 critical、major、minor 三个级别。但实际修复时，不能只看级别，还要结合出现频率和修复成本。

下面是我总结的一个优先级判断表：

这个表的核心逻辑是：高频低成本的修复优先做，低频高成本的先评估。比如"间距偏离基准"通常是高频低成本，批量替换就能解决。"响应式布局重构"可能是低频高成本，需要评估是否真的影响用户体验。

5.5 如何把评估结果转化为可执行的修复任务

impeccable 的报告是给机器看的，但修复是给人做的。把报告转化为任务清单，需要做一层翻译。

我的做法是写一个简单的脚本，读取details.json，按文件分组，按问题类型聚合，生成一个 Markdown 格式的任务清单：

const report = require('./reports/details.json'); const byFile = {}; report.issues.forEach(issue => { if (!byFile[issue.file]) byFile[issue.file] = []; byFile[issue.file].push(issue); }); let output = '# 设计质量修复任务清单\n\n'; Object.entries(byFile).forEach(([file, issues]) => { output += `## ${file}\n\n`; const byType = {}; issues.forEach(i => { byType[i.type] = byType[i.type] || []; byType[i.type].push(i); }); Object.entries(byType).forEach(([type, items]) => { output += `### ${type}（${items.length}处）\n\n`; items.forEach(i => { output += `- 第 ${i.line} 行：${i.message}\n`; }); output += '\n'; }); }); require('fs').writeFileSync('./fix-tasks.md', output);

这个清单可以直接贴到项目管理工具里，按文件或按问题类型分配任务。我通常会把同一个文件的问题分配给同一个人，减少上下文切换的成本。

6. 进阶用法与扩展思路

6.1 自定义评估规则

impeccable 内置的评估维度覆盖了通用场景，但每个项目都有自己的特殊要求。比如你的项目可能要求"所有卡片组件的阴影必须使用统一的 elevation 变量"，这个规则内置评估里没有，需要自定义。

自定义规则通过配置文件里的customRules字段实现：

customRules: [ { name: 'card-shadow-consistency', description: '卡片阴影必须使用 elevation 变量', selector: '.card', check: (element, styles) => { const shadow = styles.boxShadow; if (shadow && !shadow.includes('var(--elevation')) { return { severity: 'major', message: '卡片阴影未使用 elevation 变量', suggestion: '将 box-shadow 替换为 var(--elevation-1) 或 var(--elevation-2)' }; } return null; } } ]

自定义规则的编写需要一点 JavaScript 基础，但逻辑很直观：给定一个元素和它的计算样式，返回问题描述或 null。我建议先从简单的规则开始，比如检查特定 class 的属性值，熟练后再写复杂的逻辑。

6.2 建立设计质量基线并追踪趋势

单次扫描的结果只能反映当前状态，真正有价值的是趋势。impeccable 支持把每次扫描的结果存档，并生成趋势图。

impeccable scan --path ./src --archive --tag "sprint-12"

--archive会把本次结果保存到.impeccable/history/目录，--tag给这次扫描打个标签。之后可以用impeccable trend命令查看历史趋势：

impeccable trend --from "sprint-10" --to "sprint-12"

这个命令会输出各维度得分的变化曲线。如果某个维度的得分持续下降，说明那个方面的问题在累积，需要重点关注。

我在团队里推行了一个做法：每个 sprint 结束时跑一次全量扫描，把总评分作为团队的一个健康指标。评分低于 70 分时，下一个 sprint 必须分配时间做设计质量修复。这个机制让设计质量从"有空再说"变成了"必须管理"的事情。

6.3 与设计系统的联动

如果你的团队有维护设计系统（Design System），impeccable 可以和它深度联动。具体做法是：从设计系统的 token 文件里读取基准值，自动生成 impeccable 的配置。

比如你的设计系统用 Style Dictionary 管理 token，可以写一个转换脚本：

const tokens = require('./design-tokens.json'); module.exports = { design: { baseSpacing: tokens.spacing.base.value, colorPalette: Object.values(tokens.color).map(c => c.value), fontScale: Object.values(tokens.typography.fontSize).map(f => f.value), borderRadius: Object.values(tokens.borderRadius).map(r => r.value) } };

这样设计系统更新时，impeccable 的评估基准会自动同步，不需要手动维护两套配置。这个联动机制在大型项目里特别有价值，因为它保证了"设计系统定义的规范"和"工具检查的规范"始终一致。

6.4 在 CI/CD 中设置质量门禁

把 impeccable 接入 CI 流程，可以在代码合并前拦截设计质量问题。以下是一个 GitHub Actions 的配置示例：

name: Design Quality Check on: pull_request: paths: - 'src/**/*.vue' - 'src/**/*.jsx' - 'src/**/*.css' jobs: impeccable: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node uses: actions/setup-node@v3 with: node-version: '18' - name: Install dependencies run: npm ci - name: Run impeccable scan run: npx impeccable scan --path ./src --format json --output ./report.json - name: Check quality gate run: | node -e " const report = require('./report.json'); const critical = report.issues.filter(i => i.severity === 'critical').length; const score = report.summary.score; if (critical > 0) { console.error('存在 ' + critical + ' 个严重设计问题，请修复后再提交'); process.exit(1); } if (score < 70) { console.error('设计质量评分 ' + score + ' 低于阈值 70'); process.exit(1); } console.log('设计质量检查通过，评分：' + score); "

这个配置会在 PR 创建时自动运行扫描，如果存在严重问题或评分低于阈值，CI 会失败，阻止合并。阈值可以根据项目阶段调整：新项目可以设高一点（比如 80），老项目重构期可以设低一点（比如 60），逐步提高。

注意：质量门禁的阈值不要一开始就设得太高，否则会导致大量 PR 被阻塞，团队会产生抵触情绪。我的经验是从低阈值开始，比如先设 50 分，让流程跑起来，然后每个 sprint 提高 5 分，给团队适应的时间。

7. 我踩过的坑与实战心得

7.1 不要试图一次修复所有问题

我最初用 impeccable 时，看到报告里几百个问题，第一反应是"全部修完"。结果花了两天时间，修到一半就崩溃了——因为很多问题是相互关联的，改了一个地方，另一个地方又冒出新的不一致。

后来我调整了策略：按维度分批修复，而不是按文件或按问题级别。比如这一周只修"间距"维度的问题，把所有间距统一到基准体系；下一周只修"色彩"维度。这样每次只关注一个维度，修复逻辑一致，不容易引入新问题。

7.2 基准值要"从实践中来，到实践中去"

我见过一些团队，配置 impeccable 时直接抄了某个"最佳实践"的基准值，比如 8px 间距、1.5 倍行高、4.5:1 对比度。这些值本身没错，但如果和项目实际情况脱节，评估结果就没有参考价值。

正确的做法是：先跑impeccable analyze命令，让工具统计项目实际使用的值分布，然后基于统计结果确定基准。基准应该是"项目当前状态的合理收敛"，而不是"理想状态的生硬套用"。比如项目里 70% 的间距是 8px 的倍数，那基准就定 8px，剩下 30% 逐步收敛；如果只有 40% 是 8px 的倍数，那可能需要先定 4px 基准，再慢慢往 8px 迁移。

7.3 浏览器扩展的评分波动是正常的

浏览器扩展的评分是基于当前渲染结果的，所以它会随着页面状态变化而波动。比如页面加载图片前后、字体加载前后、动画进行中，评分都可能不同。这不是 bug，而是实时评估的特性。

我的做法是：等页面完全稳定后再看评分。具体来说，等networkidle事件触发后，再等 500ms 让渲染稳定，然后刷新扩展面板。这样得到的评分才是可比较的。

7.4 把 impeccable 当成"设计教练"而不是"裁判"

这是心态层面的建议。impeccable 的评估结果不是"你的代码不合格"的判决，而是"这里可以更好"的建议。有些建议你可能不认同，那就不采纳，但至少你知道了"工具认为这里有问题"，可以反思一下是不是真的有改进空间。

我在团队里推行 impeccable 时，特别强调这一点：不要把它当成考核工具，而是当成学习工具。新人前端开发者通过看 impeccable 的报告，能快速理解"什么样的设计是好的"，这比看设计规范文档有效得多。

7.5 定期回顾评估报告，发现系统性问题

单次扫描报告看的是"点"，定期回顾看的是"面"。我每个月会把过去四周的扫描报告汇总一次，看看哪些问题类型反复出现。如果某个问题连续四周都在高频问题列表里，那说明它不是偶发问题，而是系统性的流程缺陷。

比如"对比度不足"连续出现，可能意味着设计系统里的颜色定义本身就有问题，需要从源头修正。比如"移动端溢出"反复出现，可能意味着 AI 代理在生成响应式代码时缺少必要的约束，需要在提示词里加强。

这种定期回顾的习惯，让 impeccable 从一个"检查工具"变成了"改进引擎"。它不只是告诉你哪里有问题，还帮你发现"为什么总是这里有问题"。

7.6 关于 CLI 和扩展的选择建议

最后分享一个实用建议：不要试图用 CLI 替代扩展，或者反过来。它们解决的是不同阶段的问题。

CLI 适合"批量"和"自动化"场景：项目初始化时的全量扫描、CI 流程中的质量门禁、定期趋势追踪。它的优势是快、可脚本化、适合集成到其他工具里。

扩展适合"实时"和"交互"场景：开发过程中的即时反馈、调试复杂组件时的可视化分析、向团队成员演示问题时。它的优势是直观、反馈快、不需要切换工具。

我的日常工作流是：开发时开着扩展，随时看评分；提交前跑一次 CLI 扫描，确保没有遗漏；每周跑一次全量扫描，追踪趋势。三者配合，覆盖了从微观到宏观的各个层面。