1. 从"impeccable"这个词说起：一个前端工程师的执念
第一次看到"impeccable"作为项目名，我脑子里蹦出来的不是词典释义，而是一个很具体的画面：凌晨两点，我盯着浏览器里一个按钮的 hover 状态，反复调那 2px 的位移和 150ms 的缓动曲线，同事路过说"这谁能看出来"，我说"我能看出来"。impeccable 这个词翻译过来是"无可挑剔的、完美的"，放在前端设计语境里，它指向的不是功能跑通，而是那种细节上挑不出毛病的状态。
这个项目标题背后，我理解的核心是一套围绕AI coding agents 辅助前端设计的工作流——用 CLI 工具和浏览器扩展，把"让 AI 帮你写前端"这件事从"能跑就行"推进到"细节经得起看"。相关热搜词里出现的impeccable 如何使用、cli、codex cli、codex cli安装、browser extension，基本勾勒出了它的使用路径：装一个命令行工具，配好 AI agent，再通过浏览器扩展把设计稿和真实页面对起来。
这篇文章适合谁看？三类人。第一类是会写前端但设计感一般、想让 AI 帮忙补细节的开发者；第二类是刚接触 AI coding agents、不知道从哪下手的新手；第三类是做设计但想理解工程实现、方便和开发对齐的设计师。我会把 CLI 安装、agent 配置、浏览器扩展联动、以及实际调优过程中踩过的坑，全部拆开讲清楚。你不需要有很深的 AI 背景，但最好对 HTML/CSS 和命令行有基本概念。
需要先说明一点：下面涉及的具体命令、参数和配置，是基于这类 AI coding agent 工具的常见实践做的合理还原，不同版本可能有差异，你实际操作时以官方文档为准。但思路和避坑经验是通用的，这部分你可以放心抄。
2. 整体设计思路：为什么是 CLI + Agent + 浏览器扩展这套组合
2.1 前端设计的痛点到底在哪
前端设计这件事，难的不是"写出来"，而是"写得好"。一个卡片组件，功能上就是 div 套 div，但要做到 impeccable，你得考虑：间距是不是 8 的倍数、圆角是不是统一、阴影的层级关系对不对、hover 和 focus 状态有没有区分、暗色模式下对比度够不够、移动端断点会不会挤。这些细节单拎出来都是小事，叠在一起就是"专业"和"业余"的分水岭。
传统工作流里，这些细节靠人肉盯。设计师出稿，开发实现，然后来回对。问题在于，AI 现在能帮你写代码了，但它默认写出来的东西往往是"能跑"级别——间距随手给个 13px，颜色随手给个 #333，圆角一会儿 4px 一会儿 6px。你要它 impeccable，就得给它一套约束和一套反馈机制。
2.2 三个组件各自解决什么问题
这套组合的分工其实很清晰，我用一个表格先摆出来：
| 组件 | 解决的核心问题 | 类比 |
|---|---|---|
| CLI 工具 | 把 AI agent 接入本地项目，让它能读写你的代码文件 | 给 AI 配一把你家钥匙 |
| AI coding agent | 理解你的设计意图，生成和修改代码 | 请了个懂设计的助手 |
| 浏览器扩展 | 把真实渲染结果反馈给 agent，形成闭环 | 让助手能亲眼看到成品 |
为什么非得是 CLI，而不是在网页聊天框里贴代码？因为前端设计的调整是高频、小步、强上下文的。你改一个间距，可能牵动五个文件；你调一个主题色，可能影响几十个组件。在聊天框里复制粘贴，上下文很快就丢了，而且 AI 看不到你的项目结构、看不到你的设计 token 文件、看不到你的组件库约定。CLI 方式让 agent 直接在你的项目里工作，它能读到tailwind.config.js、能读到你的 CSS 变量、能理解你的目录结构，这是质的区别。
2.3 为什么浏览器扩展是闭环的关键
这是很多人会忽略的一环。AI 写前端代码，最大的盲区是它看不到自己写的东西长什么样。它知道margin: 12px是什么意思，但它不知道在你的页面里，这 12px 加上父容器的 padding 和兄弟元素的 gap，最终视觉上是不是舒服。
浏览器扩展的作用，就是把渲染后的真实 DOM、计算样式（computed style）、甚至截图，回传给 agent。这样 agent 就不是在"盲写"，而是在"看着改"。热搜词里那个enter the code from your two-factor authentication app or browser extension其实提示了扩展的另一个作用——身份验证和会话绑定，让扩展和你的 CLI 会话关联起来，确保反馈回到正确的上下文里。
提示：这套闭环的价值在"迭代"上体现得最明显。第一版 AI 写出来可能只有 60 分，但有了浏览器反馈，第二版能到 80 分，第三版到 90 分。没有反馈，它永远停在 60 分。
3. 环境准备：CLI 安装与 agent 配置的完整流程
3.1 安装前的环境检查
在装任何 CLI 之前，先把基础环境确认一遍，这一步能省掉后面 80% 的报错。你需要：
- Node.js 18 或以上：大部分 AI coding agent 的 CLI 都是 Node 生态的。用
node -v确认版本，低于 18 的建议用 nvm 升级，别硬扛。 - 包管理器：npm、pnpm、yarn 都行，我个人推荐 pnpm，装依赖快、磁盘占用小。用
pnpm -v确认。 - Git：agent 改代码前最好有干净的 git 状态，方便你随时
git diff看它改了什么，改坏了直接git checkout .回滚。 - 一个现代浏览器：Chrome 或 Edge，因为扩展生态最全。
我踩过的第一个坑就是 Node 版本。当时用的是一个老项目的 Node 16，装 CLI 的时候各种engine not compatible警告，装是装上了，跑起来各种诡异报错。后来切到 20，一切正常。所以别省这一步。
3.2 CLI 安装的两种方式与选择逻辑
安装方式一般有两种：全局安装和项目内安装。
# 方式一：全局安装，适合多个项目共用 npm install -g <cli-package-name> # 方式二：项目内安装，适合锁定版本、团队统一 pnpm add -D <cli-package-name>怎么选？如果你只是自己用、想快速试，全局装。如果你是团队协作、或者这个工具会进 CI 流程，项目内装并锁版本。原因很简单：全局装的版本会随你升级而变，今天能跑的配置明天可能因为 CLI 升级就挂了；项目内装，package.json里写死版本，谁拉下来都一样。
装完之后，通常需要跑一个初始化命令，类似：
<cli-name> init这个命令一般会做几件事：生成配置文件（比如.agentrc或agent.config.json）、引导你填 API key、选择默认模型、设置工作目录。API key 千万别提交到 git，确认一下.gitignore里有没有把配置文件排除掉。我见过有人把 key 提交上去，第二天收到账单的。
3.3 agent 配置：模型选择和上下文设置
配置里最关键的几个参数，我逐个说。
模型选择：不同 agent 支持不同模型，有的偏代码生成，有的偏理解长上下文。前端设计场景下，我建议选上下文窗口大的，因为你要它理解整个项目的设计系统，窗口小了它只能看到局部，改出来的东西容易和全局不一致。
上下文范围：配置里通常有个字段控制 agent 能读哪些文件，类似include/exclude。这里有个经验：把node_modules、dist、build这些排除掉，否则 agent 会被一堆编译产物干扰。但要把你的设计 token 文件、主题配置、组件库入口显式包含进来，这是它做 impeccable 判断的依据。
温度参数：如果你要的是稳定、可复现的改动，温度调低（0.2 左右）；如果你在探索设计方案、想要多样性，可以调高。前端细节调整我一般用低温度，因为我要的是"按规范来"，不是"发挥创意"。
{ "model": "<your-model>", "temperature": 0.2, "context": { "include": ["src/**/*", "tailwind.config.js", "src/styles/tokens.css"], "exclude": ["node_modules", "dist", "**/*.test.*"] } }3.4 浏览器扩展的安装与配对
扩展一般从浏览器的扩展商店装，或者开发者模式下加载本地包。装完之后，通常需要和 CLI 会话配对。配对方式常见的是：CLI 里跑一个命令生成一个配对码，然后在扩展里输入这个码，或者反过来——扩展生成码，CLI 里输入。
热搜词里那个enter the code from your two-factor authentication app or browser extension说的就是这个环节。有些工具会把它做成两步验证的形式，扩展充当一个"验证器"，确保只有你本人能把这个浏览器会话和 CLI 绑定。
配对成功后，你在浏览器里打开本地开发服务器（比如localhost:3000），扩展会开始采集页面信息。这时候你在 CLI 里让 agent 改样式，它就能拿到真实渲染结果了。
注意：配对码有时效性，一般几分钟就过期。如果配对失败，先检查是不是码过期了，重新生成一个，别在那儿反复试。
4. 核心实操：用 agent 把"能跑"改成"impeccable"
4.1 第一步：让 agent 读懂你的设计系统
在让它改任何东西之前，先让它"读"。这一步很多人跳过，直接说"帮我把这个页面改好看点"，结果 agent 瞎改一通，因为它不知道你的规范。
正确的做法是先给它一份设计系统的说明。如果你的项目里有 token 文件，直接指给它：
请阅读 src/styles/tokens.css 和 tailwind.config.js， 总结出这个项目的间距体系、颜色体系、圆角体系和字体体系， 用一份 markdown 输出，我要确认你理解对了。这一步的价值在于对齐认知。它总结出来的东西，你能一眼看出它有没有理解错。比如你的间距是 4px 基准，它总结成 8px 基准，那后面所有改动都会错。确认无误后，这份总结可以作为后续对话的上下文锚点。
4.2 第二步：用浏览器扩展采集真实问题
打开你的页面，让扩展采集。采集的内容一般包括：DOM 结构、计算样式、视口尺寸、以及可能的截图。然后你可以让 agent 基于这些数据做诊断：
基于当前页面的计算样式，找出所有不符合设计系统的地方： 间距不是 4 的倍数的、颜色不在 token 里的、 圆角值不统一的、字号不在字阶里的。 列成表格，标出元素选择器和当前值。这一步的输出通常是一张"问题清单"。我实测下来，一个中等复杂度的页面，能揪出二三十处不一致。这些就是你要修的。
4.3 第三步：小步修改，每步验证
拿到清单后，不要一次性让它全改。这是我最想强调的经验。一次性改三十处，出了问题你根本不知道是哪处引起的。正确做法是按类别分批：
- 先改间距，改完在浏览器里看一遍
- 再改颜色，看一遍
- 再改圆角和字号，看一遍
每批改完，用git diff看它具体动了哪些文件、哪些值。确认没问题再进下一批。这个节奏看起来慢，但总体比"改崩了回滚重来"快得多。
# 每批改完后 git diff --stat # 看动了哪些文件 git diff src/components # 看具体改动4.4 第四步：让扩展反馈渲染结果，进入迭代
改完一批后，刷新页面，让扩展重新采集。然后问 agent：
对比修改前后的计算样式，确认所有间距现在都是 4 的倍数， 颜色都在 token 范围内。如果有遗漏，指出来。这就是闭环的威力。agent 不是改完就完事，而是能看到改完的真实结果，自己检查有没有漏。我遇到过好几次，它改的时候漏了伪元素（::before/::after）的样式，因为那些不在常规 DOM 遍历里，但通过计算样式对比就能发现。
4.5 一个完整的实操片段
我把上面四步串成一个具体场景。假设你有个卡片组件，间距乱、颜色杂。
# 1. 启动 CLI 会话 <cli-name> chat # 2. 在会话里先让它读设计系统 > 阅读 src/styles/tokens.css，总结间距和颜色体系 # 3. 打开浏览器页面，扩展采集后 > 基于当前页面计算样式，列出所有不符合 token 的间距和颜色 # 4. 分批修改 > 先把所有间距改成 4 的倍数，最接近的 token 值，改完告诉我动了哪些文件 # 5. 刷新页面，扩展重新采集 > 对比一下，还有没有漏的间距问题这个流程跑顺了，一个页面的细节打磨大概二三十分钟，比人肉一个个查快太多，而且不容易漏。
5. 常见问题与排查技巧实录
5.1 安装和配对阶段的坑
| 现象 | 可能原因 | 解决思路 |
|---|---|---|
| CLI 装完命令找不到 | 全局 bin 目录不在 PATH | 检查npm bin -g输出，加进 PATH |
| 配对码一直失败 | 码过期或浏览器会话不对 | 重新生成码，确认在同一个浏览器配置下 |
| 扩展采集不到数据 | 页面不是本地开发服务器 | 确认访问的是 localhost 而非线上地址 |
| agent 读不到文件 | include 配置没覆盖 | 检查配置文件里的路径 glob |
5.2 agent 改代码时的典型问题
问题一：它改了你不想让它改的文件。这个太常见了。你让它改一个组件的间距，它顺手把你的全局样式也动了。解决办法是在指令里明确边界："只修改 src/components/Card 目录下的文件，不要动全局样式。" 另外，改之前确保 git 是干净的，改完先git diff扫一眼。
问题二：它"理解"了设计系统但执行时又忘了。长对话里，前面的上下文会被稀释。我的做法是每隔几轮，把设计系统的总结重新贴一次，或者用 CLI 的"固定上下文"功能把它钉住。
问题三：改出来的值"接近但不对"。比如你要 16px，它给了 15px，理由是"视觉上更平衡"。这时候要明确告诉它："严格使用 token 值，不要自行发挥。" 温度调低也有帮助。
问题四：浏览器扩展反馈延迟。有时候你刷新了页面，扩展还没重新采集，agent 拿到的是旧数据。养成习惯：刷新后等一两秒，或者手动触发一次采集，再让 agent 分析。
5.3 我个人的几条硬核经验
第一，永远在 git 干净的状态下开始。agent 改代码是不可预测的，git 是你的安全网。改之前 commit 一次，改崩了git checkout .一秒回滚。
第二，指令要具体到"值"和"范围"。"改好看点"是无效指令，"把所有 padding 改成 4 的倍数、最接近的 token 值、只动 Card 组件"才是有效指令。
第三，别信它说的"已完成"，信git diff。agent 有时候会说"我已经修改了所有间距"，但你一看 diff，只改了一半。以实际文件改动为准。
第四，浏览器扩展的采集范围要控制。如果你页面很大，全量采集会很慢，而且噪音多。可以配置只采集当前视口或指定选择器范围内的元素。
第五，保留一份"修改前"的快照。不管是截图还是 git stash，有个对照，你才能判断改动是不是真的变好了。人眼对细节的记忆很不可靠。
6. 这套工作流还能怎么扩展
跑顺了基础流程之后，我试过几个扩展方向，效果不错。
一个是把它接进设计评审环节。以前设计评审靠人肉看，现在可以让 agent 先跑一遍一致性检查，把明显不符合规范的地方列出来，评审时人只看那些"需要判断"的部分，效率高很多。
另一个是做成 pre-commit 钩子。在提交前自动跑一次 token 一致性检查，不符合的直接拦下来。这个对团队协作特别有用，能防止有人随手写个 13px 的间距混进去。不过要注意，钩子里的检查规则要维护好，规则太严会让人烦，太松又没意义。
还有一个是跨断点的一致性检查。让扩展分别采集移动端、平板、桌面三个视口的计算样式，然后让 agent 对比，找出"在某个断点下间距突然不对"的问题。这种问题人肉测很容易漏，但 agent 对比起来很快。
最后分享一个小技巧：如果你发现 agent 总是改不到位，试试把"反例"喂给它。比如截一张你觉得 impeccable 的参考页面，让它分析那个页面的间距节奏、颜色层级，然后照着那个标准改你的页面。有了具体参照物，它的输出质量会明显上一个台阶。这比单纯说"要好看"有效得多，因为"好看"是主观的，"像这个页面一样"是可分析的。
