1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个词被拿来命名一个开发工具我其实愣了一下。这个词在英文里的意思是无可挑剔的、完美的放在前端开发语境下野心不小。后来我花了两天时间把它的 CLI 和浏览器扩展都跑了一遍才慢慢理解它想做的事情让 AI coding agents 真正看懂你正在开发的页面然后给出接近无可挑剔的前端设计修改建议。说白了过去我们用 AI 辅助写前端最大的痛点是什么是 AI 看不见页面。你给它一段 HTML、一段 CSS它只能靠脑补来理解这个页面长什么样。它不知道你的按钮在 1440px 屏幕上是不是被挤到了第二行不知道你的卡片阴影在深色模式下是不是糊成一团更不知道你的表单在移动端点击区域是不是小得可怜。它只能基于代码文本做推理而前端设计这件事恰恰是所见即所得的。impeccable 的思路就是把这个断层补上。它由两部分组成一个跑在终端里的CLI 工具和一个装在浏览器里的扩展。CLI 负责和 AI coding agents比如 Codex CLI、Zcode CLI 这类命令行智能体对接浏览器扩展负责把当前页面的真实渲染状态、DOM 结构、计算样式、布局信息抓取出来回传给 CLI再交给 AI 去分析。整个链路打通之后AI 就不再是盲人摸象而是能拿到一份相当完整的页面体检报告。这套东西适合谁我梳理了一下大概三类人收益最明显。第一类是独立开发者和小团队没有专职设计师前端界面全靠自己抠AI 能帮忙看出问题就很值。第二类是前端工程师尤其是那种功能写得飞快、样式全靠感觉的类型impeccable 相当于给你配了个随时在线的设计 review 助手。第三类是正在学习前端设计的人它能告诉你为什么这个间距不对为什么这个对比度不够比干看设计规范有用得多。需要提前说明的是impeccable 本身不是一个自动改代码的工具它更像是一个诊断 建议的中间层。最终的修改还是要落到你的代码里或者交给 AI agent 去执行。理解这个定位很重要否则你会对它产生不切实际的期待。2. 整体架构拆解CLI 与浏览器扩展是怎么配合的2.1 为什么必须是CLI 扩展这个组合我一开始也疑惑为什么不做成一个纯浏览器插件或者一个纯命令行工具跑通之后才明白这个组合是被需求逼出来的。纯浏览器扩展的问题在于它拿不到你的项目上下文。它能看到页面但看不到你的组件结构、你的设计 token、你的 Tailwind 配置、你的主题变量。而前端设计的问题很多时候不是这个页面丑而是这个页面和你项目里其他页面的设计语言不一致。要判断一致性就必须让工具能读到项目文件。纯 CLI 的问题则反过来它读得到代码但读不到渲染结果。CSS 的层叠、继承、媒体查询、伪元素、动态计算这些东西光看源码是推不出来的。一个width: 100%在父容器是 flex 布局时和 block 布局时表现完全不同AI 靠读代码根本判断不了。所以 impeccable 选择了两头下注扩展负责看CLI 负责读和算AI agent 负责想。三者通过一个本地通信通道串起来。这个设计我觉得是合理的也是目前这类工具比较务实的做法。2.2 数据是怎么流动的整个数据流我实测下来大致是这样的你在浏览器里打开正在开发的页面通常是 localhost 的某个端口。浏览器扩展被激活它注入一段脚本开始采集页面的结构化信息。采集内容包括DOM 树快照、每个可见元素的计算样式computed style、盒模型尺寸、元素在视口中的位置、颜色值、字体信息、对比度数据等。这些数据被序列化后通过本地回环地址发送给 CLI 进程。CLI 把这些数据和项目里的源码文件做关联比如把某个 DOM 节点映射回对应的组件文件。最后 CLI 把整合后的上下文喂给 AI coding agent由 agent 输出诊断结果和修改建议。这里有个细节值得说采集的是计算样式而不是声明样式。这个区别很关键。声明样式是你 CSS 里写的padding: 16px计算样式是浏览器最终算出来的、单位统一成 px 的实际值。AI 拿到计算样式才能准确判断这个元素实际占了多少空间而不是被rem、em、%这些相对单位绕晕。2.3 和 AI coding agents 的对接方式impeccable 本身不内置 AI 模型它是把 AI coding agent 当作一个可替换的后端。这一点我觉得设计得很聪明因为 AI 模型迭代太快了工具没必要把自己绑死在某个模型上。目前主流的对接方式是命令行智能体比如 Codex CLI、Zcode CLI 这类。它们的共同特点是接受标准输入stdin的文本 prompt输出结构化的文本结果。impeccable 的 CLI 做的就是组装 prompt → 调用 agent → 解析输出这三件事。提示不同 agent 的 prompt 格式和输出格式差异不小impeccable 通常会提供一个适配层。如果你用的是比较冷门的 agent可能需要自己写一个简单的适配脚本把 impeccable 的输出格式转成 agent 能吃的格式。我实测下来用命令行 agent 的好处是可脚本化。你可以把它挂到 CI 里每次提交前跑一遍设计检查也可以写个 watch 脚本文件一改就自动触发分析。这种灵活性是纯 GUI 工具给不了的。3. 环境准备与安装从零把 impeccable 跑起来3.1 前置条件盘点在动手之前先把该装的东西列清楚避免中途卡壳。我按重要性排了个序依赖项作用是否必须备注Node.js 18运行 CLI 和扩展构建必须建议用 LTS 版本包管理器安装依赖必须npm / pnpm / yarn 都行现代浏览器加载扩展必须需支持 Manifest V3AI coding agent提供分析能力必须如 Codex CLI、Zcode CLI本地开发服务器提供可访问页面必须Vite / Next / Webpack 均可Git版本管理建议方便回滚修改Node.js 版本这块我要多嘴一句。我一开始用的是 16.x结果 CLI 启动时报了一堆SyntaxError排查半天才发现是某个依赖用了较新的语法。直接上 18 或 20 的 LTS能省掉很多莫名其妙的报错。3.2 CLI 的安装与初始化安装 CLI 的流程和大多数 Node 工具类似。假设你用的是 npmnpm install -g impeccable-cli装完之后先别急着用跑一下版本检查确认装上了impeccable --version如果提示命令找不到八成是全局 bin 目录没在 PATH 里。这时候可以查一下 npm 的全局路径npm config get prefix把这个路径下的bin目录加到环境变量里就行。Windows 用户遇到这个问题的概率更高因为 npm 全局路径默认不在 PATH 中。接下来是初始化。在你的项目根目录下执行impeccable init这个命令会做几件事生成一个配置文件通常是impeccable.config.js或.impeccablerc探测你的项目类型React / Vue / Svelte 等以及尝试识别你的样式方案CSS Modules / Tailwind / styled-components 等。注意如果你的项目结构比较特殊比如 monorepo 或者自定义了构建配置自动探测可能会失败。这时候别慌手动改配置文件就行把sourceDir、styleType这些字段填对即可。配置文件里我建议重点关注这几个字段sourceDir源码目录AI 分析时要读的文件都在这。devServerUrl本地开发服务器地址扩展采集页面时要用。agent用哪个 AI coding agent以及它的调用命令。ignore忽略的目录比如node_modules、dist。3.3 浏览器扩展的加载扩展的安装分两种场景。如果你是从商店装的直接点安装就行。但开发阶段我更推荐加载未打包的扩展因为这样能看到实时日志出问题好排查。以 Chromium 系浏览器为例步骤是打开扩展管理页面地址栏输入chrome://extensions。打开右上角的开发者模式开关。点击加载已解压的扩展程序。选择 impeccable 扩展的构建产物目录通常是dist/extension或类似路径。加载成功后你会在扩展列表里看到它同时浏览器工具栏上会出现它的图标。点一下图标如果弹出一个小面板显示已连接或类似的绿色状态说明扩展和 CLI 已经握手成功。如果显示未连接先检查 CLI 是不是在跑。CLI 通常需要保持一个常驻进程来接收扩展的数据命令大概是impeccable serve这个命令会启动一个本地服务监听某个端口默认可能是 3717 之类具体看配置。扩展就是往这个端口发数据的。3.4 首次连通性验证环境搭好之后别急着分析复杂页面先做个最小验证。我一般会这么干起一个最简单的 HTML 页面就一个按钮、一段文字。用本地服务器把它跑起来。在浏览器打开这个页面。点扩展图标触发一次采集。回到终端看 CLI 有没有输出。如果终端打印出了页面的 DOM 摘要和样式信息说明链路通了。这一步看着简单但能帮你把 80% 的环境问题挡在门外。我见过太多人一上来就分析复杂项目结果报错信息一大堆根本分不清是环境问题还是页面问题。4. 核心功能实操让 AI 真正看见你的页面4.1 页面采集扩展到底抓了什么扩展采集的数据比我想象的要细。我抓了一次数据包看大致包含这几类第一类是布局信息。每个可见元素的getBoundingClientRect()结果包括 x、y、width、height。有了这些AI 就能判断元素有没有重叠、有没有溢出、间距是否均匀。第二类是计算样式。颜色、字体、字号、行高、边距、圆角、阴影、透明度这些。特别值得一提的是颜色扩展会把颜色转成统一的格式比如rgb()或oklch()方便 AI 做对比度计算。第三类是语义信息。元素的标签名、role 属性、aria 属性、文本内容。这些让 AI 能理解这是个按钮这是个导航这是段正文而不是一堆无语义的 div。第四类是层级关系。DOM 树的父子兄弟关系以及 z-index 的堆叠顺序。这个对判断为什么这个弹窗被遮住了特别有用。提示采集的数据量可能很大尤其是复杂页面。如果发现 CLI 处理很慢可以在配置里开启采样模式只采集视口内的元素或者只采集特定选择器匹配的元素。4.2 触发分析几种不同的用法impeccable 的用法不止一种我按使用场景分了三类场景一单次全页分析。适合你想对某个页面做一次完整体检。命令大概是impeccable analyze --url http://localhost:3000它会触发扩展采集当前页面然后把数据交给 AI输出一份完整报告。场景二针对特定元素分析。有时候你只想问这个卡片设计得怎么样不想分析整页。这时候可以在浏览器里选中元素然后通过扩展的右键菜单触发分析此元素。场景三监听模式。适合开发过程中持续检查。命令大概是impeccable watch --url http://localhost:3000它会监听文件变化每次改动后自动重新采集和分析。这个模式我用得最多因为它能在我改完样式后立刻告诉我这次改动引入了新问题。4.3 解读 AI 的输出怎么区分有效建议和废话AI 输出的报告通常分几块问题列表、严重程度、修改建议、参考代码。但说实话AI 的建议不是每条都靠谱得学会筛选。我的经验是优先看这几类问题对比度不足这是硬性可访问性问题AI 算得比较准因为对比度是有明确公式的。点击区域过小移动端体验杀手AI 能根据元素尺寸判断准确率也高。间距不一致比如同一组卡片里有的间距 16px 有的 20px这种不整齐AI 很敏感。溢出和重叠元素超出容器或者互相遮挡这是布局 bugAI 判断得也准。相对而言这几类建议要打个问号这个颜色不好看审美是主观的AI 的偏好不代表你的用户偏好。建议改用 XX 布局这种大改动的建议往往没考虑你的业务约束。这个动画可以更流畅除非有明确的性能数据支撑否则多半是套话。注意把 AI 当第二双眼睛而不是最终裁判。它指出的问题值得看但改不改、怎么改还是你说了算。4.4 把建议落地手动改还是交给 agentimpeccable 输出的建议落地方式有两种。手动改适合小问题比如调个间距、改个颜色。你自己动手心里有数改完还能顺便 review 一下周边代码。交给 agent 改适合批量问题比如全站对比度不足。这时候可以让 AI coding agent 读取 impeccable 的报告然后自动生成 patch。命令大概是impeccable fix --agent codex --auto-apply但我要泼盆冷水自动改代码有风险。AI 可能改错文件、改坏逻辑、引入新 bug。我的做法是让 agent 生成 patch 但不自动应用我自己 review 一遍再决定。多花几分钟省掉一堆回滚的麻烦。5. 常见问题与排查技巧实录5.1 扩展连不上 CLI这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法扩展显示未连接CLI 没启动检查impeccable serve是否在跑连接后立刻断开端口被占用换端口或杀掉占用进程数据发不出去防火墙拦截检查本地回环是否被拦时连时断版本不匹配升级 CLI 和扩展到同版本我踩过最坑的一次是端口冲突。CLI 默认端口被另一个本地服务占了扩展一直连不上但报错信息很含糊只说连接失败。后来用lsof -i :端口号才查出来。遇到连接问题先查端口能省一半时间。5.2 采集数据不完整有时候扩展采集到的元素比实际少或者样式值是空的。常见原因有几个一是页面还没渲染完就采集了。SPA 应用尤其明显路由切换后 DOM 是异步更新的。解决办法是加个延迟或者等某个标志性元素出现后再采集。二是元素在 iframe 里。扩展默认可能不注入 iframe需要在配置里开启allFrames选项。三是元素被 CSS 隐藏了。display: none的元素不会被采集这是符合预期的。但如果你用的是visibility: hidden或者opacity: 0情况就不一样了得看扩展的具体实现。5.3 AI 输出格式错乱偶尔会遇到 AI 返回的内容不是预期的 JSON而是一堆自然语言。这通常是 prompt 没约束好或者 agent 版本变了。我的应对办法是在 CLI 配置里开启严格模式强制要求 agent 输出符合 schema 的 JSON。如果 agent 不支持就在中间加一层解析脚本用正则把关键信息抠出来。还有个更隐蔽的原因prompt 太长被截断了。复杂页面的上下文可能上万 token超过 agent 的输入限制后后面的内容会被丢掉导致输出不完整。这时候要精简采集数据只保留关键信息。5.4 分析结果前后矛盾同一个页面两次分析结果不一样甚至互相矛盾。这种情况我遇到过几次原因主要有两个一是页面状态变了。比如你第一次分析时弹窗是关的第二次是开的AI 看到的东西当然不同。解决办法是固定页面状态或者明确告诉 AI忽略弹窗。二是AI 的随机性。大模型输出本身有随机性同样的输入可能给出不同的输出。如果对稳定性要求高可以把 temperature 参数调低牺牲一点创造性换取一致性。5.5 性能问题分析大页面时CLI 可能卡住或者内存飙升。我实测下来一个几千个 DOM 节点的页面采集数据能到几 MB。这时候有几个优化方向开启采样只采集视口内元素。排除第三方组件比如地图、富文本编辑器。分区域分析一次只分析一个 section。提高 CLI 的内存上限Node 默认可能不够用。提示如果页面里有大量重复元素比如长列表可以在配置里设置同类元素只采集前 N 个能大幅减少数据量。6. 我踩过的坑和几条实在建议6.1 别指望它一次解决所有问题我刚开始用的时候恨不得把整个项目所有页面都跑一遍然后一次性改完。结果就是报告长得看不完改到一半就烦了。后来我调整了策略一次只分析一个页面一次只改一类问题。比如今天专门解决对比度明天专门解决间距。这样改起来有节奏也不容易漏。6.2 建立自己的问题白名单AI 报的问题里有些是你不关心的。比如你的项目就是故意用低对比度的灰色文字做装饰那这类对比度不足的警告就可以忽略。我的做法是维护一个白名单把已知的、故意为之的问题记下来下次看到直接跳过。这样能大幅减少噪音。6.3 把 impeccable 接进 CI这是我最近做的一件事效果不错。在 CI 里加一个步骤每次 PR 都跑一遍 impeccable把报告作为评论贴到 PR 上。这样设计问题在合并前就能被发现而不是等到上线后用户反馈。当然CI 里跑要注意超时和资源限制别让分析拖慢了整个流水线。6.4 版本锁定很重要impeccable 和它依赖的 AI agent 都在快速迭代版本不匹配很容易出问题。我现在的做法是在项目里锁定版本CLI、扩展、agent 三者的版本都写进文档团队里所有人用同一套。这样能避免我这儿好好的你那儿报错的扯皮。6.5 保留原始报告AI 的分析报告我建议存档。一方面方便对比改之前和改之后的差异另一方面如果哪天想回滚某个改动能查到当初为什么改。我一般会把报告存到项目的docs/design-review/目录下按日期命名。7. 这套工具还能怎么扩展跑通基础流程之后我琢磨了几个扩展方向有些已经在试了。方向一和设计系统打通。如果你的项目有设计 token比如颜色、间距、字号的变量表可以让 impeccable 在分析时对照这些 token判断页面有没有跑偏。比如设计系统规定主色是某个蓝但页面里出现了三个相近但不同的蓝这就是不一致。方向二多页面横向对比。单页分析只能看一个页面但设计一致性问题往往要跨页面才能发现。可以写个脚本批量采集多个页面然后让 AI 做横向对比找出这个页面的按钮圆角和那个页面不一样这类问题。方向三和历史版本对比。把每次分析的快照存下来就能做时间维度的对比。比如这次改动让页面的平均对比度下降了 15%这种量化指标比单次分析更有说服力。方向四接入视觉回归测试。impeccable 采集的是结构化数据但视觉回归测试靠的是截图对比。两者结合既能发现像素级差异又能解释为什么会有差异。方向五自定义规则。如果你的团队有特定的设计规范可以写自定义规则让 impeccable 检查。比如所有按钮必须有 focus 样式所有图片必须有 alt 属性。这类规则用脚本实现比靠 AI 判断更可靠。我个人最看好的是方向一和方向五因为它们把 AI 的模糊判断和规则的精确判断结合起来了。AI 负责发现感觉不对的地方规则负责确认确实违规。两者互补比单靠任何一方都强。最后分享一个小技巧如果你觉得 impeccable 的默认分析太啰嗦可以在配置里调整详细程度。我一般设成中等只报严重和中等问题轻微问题折叠起来。这样报告读起来清爽很多也不会被一堆鸡毛蒜皮的建议淹没。 
长河君 · 2026/10/28 7:00:45 · 阅读 1.2k impeccable 实战：让 AI coding agent 真正看见前端页面
1. 从impeccable这个词说起它到底想解决什么问题第一次看到impeccable这个词被拿来命名一个开发工具我其实愣了一下。这个词在英文里的意思是无可挑剔的、完美的放在前端开发语境下野心不小。后来我花了两天时间把它的 CLI 和浏览器扩展都跑了一遍才慢慢理解它想做的事情让 AI coding agents 真正看懂你正在开发的页面然后给出接近无可挑剔的前端设计修改建议。说白了过去我们用 AI 辅助写前端最大的痛点是什么是 AI 看不见页面。你给它一段 HTML、一段 CSS它只能靠脑补来理解这个页面长什么样。它不知道你的按钮在 1440px 屏幕上是不是被挤到了第二行不知道你的卡片阴影在深色模式下是不是糊成一团更不知道你的表单在移动端点击区域是不是小得可怜。它只能基于代码文本做推理而前端设计这件事恰恰是所见即所得的。impeccable 的思路就是把这个断层补上。它由两部分组成一个跑在终端里的CLI 工具和一个装在浏览器里的扩展。CLI 负责和 AI coding agents比如 Codex CLI、Zcode CLI 这类命令行智能体对接浏览器扩展负责把当前页面的真实渲染状态、DOM 结构、计算样式、布局信息抓取出来回传给 CLI再交给 AI 去分析。整个链路打通之后AI 就不再是盲人摸象而是能拿到一份相当完整的页面体检报告。这套东西适合谁我梳理了一下大概三类人收益最明显。第一类是独立开发者和小团队没有专职设计师前端界面全靠自己抠AI 能帮忙看出问题就很值。第二类是前端工程师尤其是那种功能写得飞快、样式全靠感觉的类型impeccable 相当于给你配了个随时在线的设计 review 助手。第三类是正在学习前端设计的人它能告诉你为什么这个间距不对为什么这个对比度不够比干看设计规范有用得多。需要提前说明的是impeccable 本身不是一个自动改代码的工具它更像是一个诊断 建议的中间层。最终的修改还是要落到你的代码里或者交给 AI agent 去执行。理解这个定位很重要否则你会对它产生不切实际的期待。2. 整体架构拆解CLI 与浏览器扩展是怎么配合的2.1 为什么必须是CLI 扩展这个组合我一开始也疑惑为什么不做成一个纯浏览器插件或者一个纯命令行工具跑通之后才明白这个组合是被需求逼出来的。纯浏览器扩展的问题在于它拿不到你的项目上下文。它能看到页面但看不到你的组件结构、你的设计 token、你的 Tailwind 配置、你的主题变量。而前端设计的问题很多时候不是这个页面丑而是这个页面和你项目里其他页面的设计语言不一致。要判断一致性就必须让工具能读到项目文件。纯 CLI 的问题则反过来它读得到代码但读不到渲染结果。CSS 的层叠、继承、媒体查询、伪元素、动态计算这些东西光看源码是推不出来的。一个width: 100%在父容器是 flex 布局时和 block 布局时表现完全不同AI 靠读代码根本判断不了。所以 impeccable 选择了两头下注扩展负责看CLI 负责读和算AI agent 负责想。三者通过一个本地通信通道串起来。这个设计我觉得是合理的也是目前这类工具比较务实的做法。2.2 数据是怎么流动的整个数据流我实测下来大致是这样的你在浏览器里打开正在开发的页面通常是 localhost 的某个端口。浏览器扩展被激活它注入一段脚本开始采集页面的结构化信息。采集内容包括DOM 树快照、每个可见元素的计算样式computed style、盒模型尺寸、元素在视口中的位置、颜色值、字体信息、对比度数据等。这些数据被序列化后通过本地回环地址发送给 CLI 进程。CLI 把这些数据和项目里的源码文件做关联比如把某个 DOM 节点映射回对应的组件文件。最后 CLI 把整合后的上下文喂给 AI coding agent由 agent 输出诊断结果和修改建议。这里有个细节值得说采集的是计算样式而不是声明样式。这个区别很关键。声明样式是你 CSS 里写的padding: 16px计算样式是浏览器最终算出来的、单位统一成 px 的实际值。AI 拿到计算样式才能准确判断这个元素实际占了多少空间而不是被rem、em、%这些相对单位绕晕。2.3 和 AI coding agents 的对接方式impeccable 本身不内置 AI 模型它是把 AI coding agent 当作一个可替换的后端。这一点我觉得设计得很聪明因为 AI 模型迭代太快了工具没必要把自己绑死在某个模型上。目前主流的对接方式是命令行智能体比如 Codex CLI、Zcode CLI 这类。它们的共同特点是接受标准输入stdin的文本 prompt输出结构化的文本结果。impeccable 的 CLI 做的就是组装 prompt → 调用 agent → 解析输出这三件事。提示不同 agent 的 prompt 格式和输出格式差异不小impeccable 通常会提供一个适配层。如果你用的是比较冷门的 agent可能需要自己写一个简单的适配脚本把 impeccable 的输出格式转成 agent 能吃的格式。我实测下来用命令行 agent 的好处是可脚本化。你可以把它挂到 CI 里每次提交前跑一遍设计检查也可以写个 watch 脚本文件一改就自动触发分析。这种灵活性是纯 GUI 工具给不了的。3. 环境准备与安装从零把 impeccable 跑起来3.1 前置条件盘点在动手之前先把该装的东西列清楚避免中途卡壳。我按重要性排了个序依赖项作用是否必须备注Node.js 18运行 CLI 和扩展构建必须建议用 LTS 版本包管理器安装依赖必须npm / pnpm / yarn 都行现代浏览器加载扩展必须需支持 Manifest V3AI coding agent提供分析能力必须如 Codex CLI、Zcode CLI本地开发服务器提供可访问页面必须Vite / Next / Webpack 均可Git版本管理建议方便回滚修改Node.js 版本这块我要多嘴一句。我一开始用的是 16.x结果 CLI 启动时报了一堆SyntaxError排查半天才发现是某个依赖用了较新的语法。直接上 18 或 20 的 LTS能省掉很多莫名其妙的报错。3.2 CLI 的安装与初始化安装 CLI 的流程和大多数 Node 工具类似。假设你用的是 npmnpm install -g impeccable-cli装完之后先别急着用跑一下版本检查确认装上了impeccable --version如果提示命令找不到八成是全局 bin 目录没在 PATH 里。这时候可以查一下 npm 的全局路径npm config get prefix把这个路径下的bin目录加到环境变量里就行。Windows 用户遇到这个问题的概率更高因为 npm 全局路径默认不在 PATH 中。接下来是初始化。在你的项目根目录下执行impeccable init这个命令会做几件事生成一个配置文件通常是impeccable.config.js或.impeccablerc探测你的项目类型React / Vue / Svelte 等以及尝试识别你的样式方案CSS Modules / Tailwind / styled-components 等。注意如果你的项目结构比较特殊比如 monorepo 或者自定义了构建配置自动探测可能会失败。这时候别慌手动改配置文件就行把sourceDir、styleType这些字段填对即可。配置文件里我建议重点关注这几个字段sourceDir源码目录AI 分析时要读的文件都在这。devServerUrl本地开发服务器地址扩展采集页面时要用。agent用哪个 AI coding agent以及它的调用命令。ignore忽略的目录比如node_modules、dist。3.3 浏览器扩展的加载扩展的安装分两种场景。如果你是从商店装的直接点安装就行。但开发阶段我更推荐加载未打包的扩展因为这样能看到实时日志出问题好排查。以 Chromium 系浏览器为例步骤是打开扩展管理页面地址栏输入chrome://extensions。打开右上角的开发者模式开关。点击加载已解压的扩展程序。选择 impeccable 扩展的构建产物目录通常是dist/extension或类似路径。加载成功后你会在扩展列表里看到它同时浏览器工具栏上会出现它的图标。点一下图标如果弹出一个小面板显示已连接或类似的绿色状态说明扩展和 CLI 已经握手成功。如果显示未连接先检查 CLI 是不是在跑。CLI 通常需要保持一个常驻进程来接收扩展的数据命令大概是impeccable serve这个命令会启动一个本地服务监听某个端口默认可能是 3717 之类具体看配置。扩展就是往这个端口发数据的。3.4 首次连通性验证环境搭好之后别急着分析复杂页面先做个最小验证。我一般会这么干起一个最简单的 HTML 页面就一个按钮、一段文字。用本地服务器把它跑起来。在浏览器打开这个页面。点扩展图标触发一次采集。回到终端看 CLI 有没有输出。如果终端打印出了页面的 DOM 摘要和样式信息说明链路通了。这一步看着简单但能帮你把 80% 的环境问题挡在门外。我见过太多人一上来就分析复杂项目结果报错信息一大堆根本分不清是环境问题还是页面问题。4. 核心功能实操让 AI 真正看见你的页面4.1 页面采集扩展到底抓了什么扩展采集的数据比我想象的要细。我抓了一次数据包看大致包含这几类第一类是布局信息。每个可见元素的getBoundingClientRect()结果包括 x、y、width、height。有了这些AI 就能判断元素有没有重叠、有没有溢出、间距是否均匀。第二类是计算样式。颜色、字体、字号、行高、边距、圆角、阴影、透明度这些。特别值得一提的是颜色扩展会把颜色转成统一的格式比如rgb()或oklch()方便 AI 做对比度计算。第三类是语义信息。元素的标签名、role 属性、aria 属性、文本内容。这些让 AI 能理解这是个按钮这是个导航这是段正文而不是一堆无语义的 div。第四类是层级关系。DOM 树的父子兄弟关系以及 z-index 的堆叠顺序。这个对判断为什么这个弹窗被遮住了特别有用。提示采集的数据量可能很大尤其是复杂页面。如果发现 CLI 处理很慢可以在配置里开启采样模式只采集视口内的元素或者只采集特定选择器匹配的元素。4.2 触发分析几种不同的用法impeccable 的用法不止一种我按使用场景分了三类场景一单次全页分析。适合你想对某个页面做一次完整体检。命令大概是impeccable analyze --url http://localhost:3000它会触发扩展采集当前页面然后把数据交给 AI输出一份完整报告。场景二针对特定元素分析。有时候你只想问这个卡片设计得怎么样不想分析整页。这时候可以在浏览器里选中元素然后通过扩展的右键菜单触发分析此元素。场景三监听模式。适合开发过程中持续检查。命令大概是impeccable watch --url http://localhost:3000它会监听文件变化每次改动后自动重新采集和分析。这个模式我用得最多因为它能在我改完样式后立刻告诉我这次改动引入了新问题。4.3 解读 AI 的输出怎么区分有效建议和废话AI 输出的报告通常分几块问题列表、严重程度、修改建议、参考代码。但说实话AI 的建议不是每条都靠谱得学会筛选。我的经验是优先看这几类问题对比度不足这是硬性可访问性问题AI 算得比较准因为对比度是有明确公式的。点击区域过小移动端体验杀手AI 能根据元素尺寸判断准确率也高。间距不一致比如同一组卡片里有的间距 16px 有的 20px这种不整齐AI 很敏感。溢出和重叠元素超出容器或者互相遮挡这是布局 bugAI 判断得也准。相对而言这几类建议要打个问号这个颜色不好看审美是主观的AI 的偏好不代表你的用户偏好。建议改用 XX 布局这种大改动的建议往往没考虑你的业务约束。这个动画可以更流畅除非有明确的性能数据支撑否则多半是套话。注意把 AI 当第二双眼睛而不是最终裁判。它指出的问题值得看但改不改、怎么改还是你说了算。4.4 把建议落地手动改还是交给 agentimpeccable 输出的建议落地方式有两种。手动改适合小问题比如调个间距、改个颜色。你自己动手心里有数改完还能顺便 review 一下周边代码。交给 agent 改适合批量问题比如全站对比度不足。这时候可以让 AI coding agent 读取 impeccable 的报告然后自动生成 patch。命令大概是impeccable fix --agent codex --auto-apply但我要泼盆冷水自动改代码有风险。AI 可能改错文件、改坏逻辑、引入新 bug。我的做法是让 agent 生成 patch 但不自动应用我自己 review 一遍再决定。多花几分钟省掉一堆回滚的麻烦。5. 常见问题与排查技巧实录5.1 扩展连不上 CLI这是最高频的问题。排查顺序我总结成一张表现象可能原因排查方法扩展显示未连接CLI 没启动检查impeccable serve是否在跑连接后立刻断开端口被占用换端口或杀掉占用进程数据发不出去防火墙拦截检查本地回环是否被拦时连时断版本不匹配升级 CLI 和扩展到同版本我踩过最坑的一次是端口冲突。CLI 默认端口被另一个本地服务占了扩展一直连不上但报错信息很含糊只说连接失败。后来用lsof -i :端口号才查出来。遇到连接问题先查端口能省一半时间。5.2 采集数据不完整有时候扩展采集到的元素比实际少或者样式值是空的。常见原因有几个一是页面还没渲染完就采集了。SPA 应用尤其明显路由切换后 DOM 是异步更新的。解决办法是加个延迟或者等某个标志性元素出现后再采集。二是元素在 iframe 里。扩展默认可能不注入 iframe需要在配置里开启allFrames选项。三是元素被 CSS 隐藏了。display: none的元素不会被采集这是符合预期的。但如果你用的是visibility: hidden或者opacity: 0情况就不一样了得看扩展的具体实现。5.3 AI 输出格式错乱偶尔会遇到 AI 返回的内容不是预期的 JSON而是一堆自然语言。这通常是 prompt 没约束好或者 agent 版本变了。我的应对办法是在 CLI 配置里开启严格模式强制要求 agent 输出符合 schema 的 JSON。如果 agent 不支持就在中间加一层解析脚本用正则把关键信息抠出来。还有个更隐蔽的原因prompt 太长被截断了。复杂页面的上下文可能上万 token超过 agent 的输入限制后后面的内容会被丢掉导致输出不完整。这时候要精简采集数据只保留关键信息。5.4 分析结果前后矛盾同一个页面两次分析结果不一样甚至互相矛盾。这种情况我遇到过几次原因主要有两个一是页面状态变了。比如你第一次分析时弹窗是关的第二次是开的AI 看到的东西当然不同。解决办法是固定页面状态或者明确告诉 AI忽略弹窗。二是AI 的随机性。大模型输出本身有随机性同样的输入可能给出不同的输出。如果对稳定性要求高可以把 temperature 参数调低牺牲一点创造性换取一致性。5.5 性能问题分析大页面时CLI 可能卡住或者内存飙升。我实测下来一个几千个 DOM 节点的页面采集数据能到几 MB。这时候有几个优化方向开启采样只采集视口内元素。排除第三方组件比如地图、富文本编辑器。分区域分析一次只分析一个 section。提高 CLI 的内存上限Node 默认可能不够用。提示如果页面里有大量重复元素比如长列表可以在配置里设置同类元素只采集前 N 个能大幅减少数据量。6. 我踩过的坑和几条实在建议6.1 别指望它一次解决所有问题我刚开始用的时候恨不得把整个项目所有页面都跑一遍然后一次性改完。结果就是报告长得看不完改到一半就烦了。后来我调整了策略一次只分析一个页面一次只改一类问题。比如今天专门解决对比度明天专门解决间距。这样改起来有节奏也不容易漏。6.2 建立自己的问题白名单AI 报的问题里有些是你不关心的。比如你的项目就是故意用低对比度的灰色文字做装饰那这类对比度不足的警告就可以忽略。我的做法是维护一个白名单把已知的、故意为之的问题记下来下次看到直接跳过。这样能大幅减少噪音。6.3 把 impeccable 接进 CI这是我最近做的一件事效果不错。在 CI 里加一个步骤每次 PR 都跑一遍 impeccable把报告作为评论贴到 PR 上。这样设计问题在合并前就能被发现而不是等到上线后用户反馈。当然CI 里跑要注意超时和资源限制别让分析拖慢了整个流水线。6.4 版本锁定很重要impeccable 和它依赖的 AI agent 都在快速迭代版本不匹配很容易出问题。我现在的做法是在项目里锁定版本CLI、扩展、agent 三者的版本都写进文档团队里所有人用同一套。这样能避免我这儿好好的你那儿报错的扯皮。6.5 保留原始报告AI 的分析报告我建议存档。一方面方便对比改之前和改之后的差异另一方面如果哪天想回滚某个改动能查到当初为什么改。我一般会把报告存到项目的docs/design-review/目录下按日期命名。7. 这套工具还能怎么扩展跑通基础流程之后我琢磨了几个扩展方向有些已经在试了。方向一和设计系统打通。如果你的项目有设计 token比如颜色、间距、字号的变量表可以让 impeccable 在分析时对照这些 token判断页面有没有跑偏。比如设计系统规定主色是某个蓝但页面里出现了三个相近但不同的蓝这就是不一致。方向二多页面横向对比。单页分析只能看一个页面但设计一致性问题往往要跨页面才能发现。可以写个脚本批量采集多个页面然后让 AI 做横向对比找出这个页面的按钮圆角和那个页面不一样这类问题。方向三和历史版本对比。把每次分析的快照存下来就能做时间维度的对比。比如这次改动让页面的平均对比度下降了 15%这种量化指标比单次分析更有说服力。方向四接入视觉回归测试。impeccable 采集的是结构化数据但视觉回归测试靠的是截图对比。两者结合既能发现像素级差异又能解释为什么会有差异。方向五自定义规则。如果你的团队有特定的设计规范可以写自定义规则让 impeccable 检查。比如所有按钮必须有 focus 样式所有图片必须有 alt 属性。这类规则用脚本实现比靠 AI 判断更可靠。我个人最看好的是方向一和方向五因为它们把 AI 的模糊判断和规则的精确判断结合起来了。AI 负责发现感觉不对的地方规则负责确认确实违规。两者互补比单靠任何一方都强。最后分享一个小技巧如果你觉得 impeccable 的默认分析太啰嗦可以在配置里调整详细程度。我一般设成中等只报严重和中等问题轻微问题折叠起来。这样报告读起来清爽很多也不会被一堆鸡毛蒜皮的建议淹没。