impeccable 实测：用 CLI 与浏览器扩展让 AI 编程代理真正“看见”前端设计

1. 从"impeccable"这个词说起：它到底想解决什么问题

第一次看到"impeccable"作为项目名，我脑子里蹦出来的第一反应是：这词儿选得挺狂。"无可挑剔"——做前端的人都知道，前端设计这件事，从来就没有真正"无可挑剔"的时候。像素对齐了，交互又卡了；交互顺了，响应式又崩了；响应式稳了，无障碍访问又没过。所以当一个项目敢用这个词命名，要么是噱头，要么是真有点东西。

我花了两周时间把这个项目从安装到实际接入工作流完整跑了一遍，结论是：它属于后者，但也没到"无可挑剔"的程度。它真正做的事情，是把AI coding agents和frontend design这两件原本割裂的事，用一个CLI工具加一个browser extension给缝到了一起。说白了，就是让 AI 写代码的时候，能"看见"页面长什么样，而不是闭着眼睛瞎写。

这个定位很关键。现在市面上大部分 AI 编程工具，不管是 codex cli 还是 zcode cli 这类命令行代理，本质上都是"文本进、文本出"。你给它一段需求，它给你一段代码。但前端代码有个特殊性：它的最终产物是视觉的、交互的、在浏览器里跑起来的。AI 看不见这个产物，就只能靠猜。猜字体大小、猜间距、猜颜色对比度，猜出来的东西往往"能跑但难看"。

impeccable 的思路是：给 AI 装一双眼睛。通过 browser extension 把真实渲染的页面状态回传给 CLI 里的 agent，agent 再基于这个真实状态去改代码。这个闭环一旦建立起来，前端设计的迭代效率会有质的变化。适合谁来用？我认为三类人最该关注：一是独立开发者，没人帮你 review 视觉；二是小团队里兼做前端的全栈，时间碎片化；三是对 UI 质量有执念但不想手动调像素的人。

2. 核心设计思路拆解：为什么是 CLI 加浏览器扩展这套组合

2.1 为什么不做成纯 Web 应用或者纯 IDE 插件

这是我在用之前最大的疑问。现在 IDE 插件生态这么成熟，为什么 impeccable 要选 CLI 加 browser extension 这种看起来"复古"的组合？用下来我理解了，这个选择背后有三层考量。

第一层是agent 的运行环境。AI coding agents 这类工具，尤其是 codex cli、zcode cli 这种，它们的强项是在终端里操作文件系统、跑命令、读日志。终端是它们的"主场"，文件读写、git 操作、依赖安装这些事在 CLI 里做最顺。如果硬塞进 IDE 插件，反而要处理一堆 IDE 特有的 API 兼容问题，得不偿失。

第二层是浏览器扩展的不可替代性。要拿到页面真实渲染状态，最靠谱的方式就是直接在浏览器里跑。DOM 结构、计算后的样式（computed style）、布局盒模型、甚至截图，这些东西只有浏览器自己能给。你用无头浏览器也行，但无头浏览器和真实浏览器的渲染差异，做过前端的人都知道有多坑。browser extension 直接挂在真实浏览器上，拿到的就是用户看到的那个状态。

第三层是解耦。CLI 负责"思考和改代码"，extension 负责"观察和反馈"，两者通过一个本地通道通信。这种解耦意味着你可以换掉任何一端——比如你不想用 impeccable 自带的 agent，想接自己的 codex cli，理论上也能通。这种设计哲学在工具链里很常见，但真正做到解耦的不多。

2.2 数据是怎么在两端流动的

理解数据流是理解整个工具的关键。我画不出图（也不让画），但可以用文字把这条链路讲清楚。

整个流程是这样的：你在 CLI 里对 agent 说"把这个按钮的对比度调高一点"。agent 首先需要知道"这个按钮"当前长什么样。它会通过本地通道向 browser extension 发一个请求，extension 收到后，在页面上定位到对应元素，抓取它的计算样式、尺寸、位置、颜色值，可能还有一张局部截图，然后回传给 agent。agent 拿到这些真实数据，分析出当前对比度是多少，算出目标对比度需要什么颜色值，然后去改源码。改完之后，extension 再抓一次新状态，agent 对比前后差异，确认改动生效。

这个闭环里最妙的是"确认改动生效"这一步。传统 AI 改代码，改完就完事了，对不对它不知道。impeccable 这套流程里，agent 能自己验证结果，这就把"改代码"升级成了"改到对为止"。这个差别，用过的人才知道有多大。

2.3 和纯截图方案的对比

有人可能会问：直接让 agent 看截图不就行了？现在多模态模型这么强。我实测过纯截图方案，问题在于精度。截图是像素，agent 从像素里反推 CSS 值，误差很大。一个#3b82f6的蓝色，从截图里读出来可能是#3a81f5，差一点点，但前端里差一点点就是差很多。而 extension 直接读 computed style，拿到的是精确值，没有反推误差。这是质的区别，不是量的区别。

3. 安装与首次配置：从零到能跑通的完整记录

3.1 CLI 端的安装与初始化

impeccable 的 CLI 安装本身不复杂，但有几个坑我踩过，得提前说。

安装方式取决于你的包管理器。我用的是 npm 全局安装，命令大概是npm install -g impeccable-cli这种形式（具体包名以官方为准，我这里说的是通用流程）。装完之后第一件事是跑impeccable init，它会在你的项目根目录生成一个配置文件，通常是.impeccablerc或者类似名字。

这个配置文件里最关键的是agent 的接入配置。impeccable 本身不绑定某个特定的 agent，它更像是一个"调度层"。你需要告诉它用哪个 agent 来干活。如果你用的是 codex cli，就要在配置里指定 codex 的可执行路径和调用参数；如果用 zcode cli，同理。这一步配置错了，后面所有命令都会报"agent not found"。

提示：init 之后先别急着改代码，跑一遍impeccable doctor（如果版本里有这个命令）或者类似的健康检查命令，确认 CLI 能正确找到 agent、能找到浏览器扩展、能建立本地通道。三个都绿了再往下走。

我遇到的一个典型问题是 PATH 问题。codex cli 装在某个 nvm 管理的 node 版本下，而 impeccable 用的是系统 node，导致找不到。解决办法是在配置里写绝对路径，别依赖 PATH。

3.2 浏览器扩展的加载与配对

browser extension 的安装，如果你是从商店装的，直接装就行。但 impeccable 这种工具，很多时候需要装开发版或者手动加载。手动加载的流程是：打开浏览器的扩展管理页面，开启"开发者模式"，选择"加载已解压的扩展程序"，指向 impeccable 提供的扩展目录。

装完之后扩展图标会出现在工具栏。点开它，通常会显示一个配对状态。这时候 CLI 那边要跑一个配对命令，两边通过一个本地端口或者 token 建立连接。我第一次配对失败，原因是浏览器扩展和 CLI 版本不匹配——扩展是旧的，CLI 是新的，协议对不上。所以装的时候一定要确保两端版本一致，这是血泪教训。

配对成功后，扩展图标会变成"已连接"状态。这时候你在浏览器里打开你的项目页面，扩展就能开始抓取页面状态了。

3.3 项目侧的准备工作

在让 agent 动手之前，有几个项目侧的准备工作必须做，否则 agent 会"看不见"或者"看错"。

第一，确保你的开发服务器在跑，页面能正常访问。agent 是通过扩展去读当前打开的页面，页面没开或者报错，它就读不到东西。

第二，确保页面上的元素有稳定的选择器。如果 agent 要改"那个按钮"，它得能定位到。如果按钮没有 id、没有稳定的 class、没有 data 属性，agent 定位起来会很痛苦。我的做法是给关键的可交互元素加上>