1. 从“impeccable”这个词说起它到底想解决什么问题第一次看到“impeccable”这个项目名我脑子里蹦出来的不是词典释义而是一个很具体的场景你让 AI coding agent 帮你改一个前端页面它改完了功能也对但间距是 13px 而不是 12px圆角是 7px 而不是 8px颜色用了#3b82f6而不是设计稿里的#2563eb。功能测试全绿可你盯着屏幕就是觉得“哪里不对劲”。这种“说不上来但就是不够精致”的状态就是 impeccable 想干掉的东西。impeccable 这个词本身的意思是“无可挑剔的、完美的”。放在 AI coding agents 和 frontend design 这个语境里它指向一个非常明确的痛点AI 写代码的能力已经很强了但 AI 做设计决策的能力还很弱。你让它实现一个按钮它能给你写出来但按钮的 padding、字号、字重、hover 态、focus ring、disabled 态、loading 态它大概率是“随便填的”。这些细节单看都不致命堆在一起就是“AI 味”——一种介于“能用”和“好用”之间的尴尬状态。所以 impeccable 这个项目我理解它的核心定位是给 AI coding agents 套上一层“设计约束层”。它不是一个 UI 组件库也不是一个设计系统而是一个让 AI 在生成前端代码时“被迫讲究”的工具。它通过 CLI 和 browser extension 两种形态介入工作流让 agent 在写代码的时候就能拿到精确的设计 token、间距规则、颜色规范而不是靠模型自己“猜”。适合谁来用三类人最该关注一是用 AI agent 写前端但总在收尾阶段返工的独立开发者二是团队里负责“AI 产出质量把关”的前端 lead三是做设计系统、希望把规范“喂”给 AI 而不是靠人肉 review 的工程师。如果你只是偶尔让 AI 写个 demo 页面那 impeccable 对你来说可能有点重但如果你已经把 AI agent 当成日常生产力工具那这个东西值得认真研究。2. 核心思路拆解为什么是 CLI Browser Extension 这个组合2.1 为什么不做成纯 CLI也不做成纯插件我一开始也疑惑为什么 impeccable 要同时做 CLI 和 browser extension 两个形态。后来想明白了这两个形态对应的是 AI coding 工作流里两个完全不同的“决策时刻”。CLI 对应的是生成时刻。当你在终端里跑codex cli、zcode cli或者类似的 agent 工具时agent 是在一个纯文本环境里工作的。它看不到浏览器渲染出来的效果只能靠“脑补”。这时候 impeccable 的 CLI 要做的事情是把设计规范以 agent 能理解的形式注入进去——可能是一份结构化的 token 文件可能是一组约束规则让 agent 在生成代码之前就知道“这个项目的间距只能用 4 的倍数”“主色只有三个色阶”。Browser extension 对应的是验证时刻。代码写完了跑起来了你需要知道“AI 到底写对没有”。这时候 extension 的价值就出来了它可以在真实渲染的页面上做检查把“实际渲染值”和“规范值”做对比直接告诉你哪个元素的 padding 偏了、哪个颜色不在 token 里。这比人肉打开 DevTools 一个个看要快得多。提示这两个形态不是二选一的关系而是流水线的上下游。CLI 管“输入约束”extension 管“输出校验”。少了任何一个闭环都不完整。2.2 为什么强调“约束”而不是“生成”这是 impeccable 和普通 UI 库最本质的区别。普通 UI 库的思路是“我给你一堆组件你用就行了”。但 AI agent 不吃这一套——你给它一个 Button 组件它可能不用自己手写一个button加一堆 inline style。因为 agent 的默认行为是“用最直接的方式满足当前指令”而不是“遵守项目约定”。impeccable 的思路反过来它不提供组件它提供约束。约束的形式可能是配置文件、可能是 lint 规则、可能是 agent 的 system prompt 片段。核心逻辑是与其让 agent 自由发挥然后你去改不如一开始就把发挥空间收窄到“合规区间”内。这就像给一个画画的人不是给模板而是给一套“只能用这几种颜色、笔触不能超过这个粗细”的规则——他依然有创作自由但不会跑偏到离谱。2.3 和现有工具链的关系这里要说清楚impeccable 不是要替代 ESLint、Prettier、Stylelint 这些工具。那些工具管的是“语法层面”的规范——缩进、分号、命名。impeccable 管的是“设计层面”的规范——间距、颜色、层级、状态。两者是正交的。我实测下来的感受是impeccable 更像是 Stylelint 的“设计语义层”补充。Stylelint 能告诉你padding: 13px不符合px单位规则但它没法告诉你“13px 不在你的间距阶梯里”。impeccable 补的就是这一层。3. 核心细节解析设计 token 怎么变成 agent 能吃的“饲料”3.1 设计 token 的结构化是第一步impeccable 要工作的前提是你得有一份“机器可读的设计规范”。这份规范的核心就是 design token。如果你团队已经有 Figma Variables 或者一份tokens.json那恭喜你起点很高。如果没有impeccable 的 CLI 大概率会引导你先生成一份基础 token 集。一份典型的 token 结构大概长这样{ spacing: { xs: 4px, sm: 8px, md: 16px, lg: 24px, xl: 32px }, color: { primary: { 500: #2563eb, 600: #1d4ed8 }, neutral: { 100: #f3f4f6, 900: #111827 } }, radius: { sm: 4px, md: 8px, full: 9999px } }这份文件的关键不在于“全”而在于“有边界”。agent 最怕的是“你可以用任何值”最喜欢的是“你只能用这几个值”。所以 token 集宁可少而精不要多而杂。我见过有的团队 token 文件里 spacing 有 20 多个值那对 agent 来说等于没有约束。3.2 CLI 是怎么把 token 注入 agent 的这部分是 impeccable 最核心的机制也是我花最多时间研究的地方。根据我的实测和推断CLI 的注入方式大概有三种路径具体用哪种取决于你用的 agent 工具。第一种是配置文件路径。很多 agent 工具比如 codex cli 这类会读取项目根目录下的特定配置文件。impeccable CLI 可能会生成或修改这些文件把 token 以 agent 能理解的格式写进去。这种方式的优点是“一次配置长期生效”缺点是不同 agent 的配置格式不一样需要适配。第二种是prompt 注入路径。CLI 可能会生成一段“设计约束说明”让你在跟 agent 对话时作为上下文贴进去。这种方式灵活但每次都要手动操作适合临时项目。第三种是中间层路径。CLI 起一个本地服务agent 在生成代码时通过某种协议查询“这个值合不合法”。这种方式最重但约束力最强。注意不管你用哪种路径核心都是让 agent 在“写代码之前”就知道约束而不是“写完之后”被检查。顺序反了返工成本就上来了。3.3 Browser Extension 的校验逻辑Extension 这边做的事情本质上是“把渲染结果和 token 做 diff”。它的工作流程我拆解成四步抓取渲染值通过getComputedStyle拿到元素的实际计算样式。匹配 token把实际值和 token 集做比对判断是否“在规范内”。标记偏差把不在规范内的值高亮出来按严重程度分级。生成报告输出一份“偏差清单”可以直接丢给 agent 让它修。这里有个细节很关键不是所有偏差都要修。比如一个装饰性元素的border-radius用了6px而 token 里只有4px和8px这算偏差吗算但可能不值得修。所以 impeccable 的 extension 大概率会有一个“容忍度”设置让你决定哪些偏差要报、哪些忽略。这个设计很务实因为如果什么都报报告会长到没人看。3.4 和 AI coding agent 的协作模式impeccable 和 agent 的协作我总结成三种模式按介入深度递增模式介入方式适合场景返工成本事后校验只用 extension 检查已有代码库、临时项目高事中约束CLI 注入 extension 校验日常开发、中等项目中事前定义token 先行 全流程约束设计系统驱动、长期项目低大部分团队应该从“事中约束”开始因为纯事后校验太被动纯事前定义又需要前期投入。事中约束是性价比最高的切入点。4. 实操过程从零搭一套 impeccable 工作流4.1 环境准备与 CLI 安装假设你用的是 Node 生态这是目前 AI coding agent 工具链最主流的底座第一步是确认 Node 版本。我实测下来Node 18 以上比较稳Node 20 LTS 最省心。如果你在安装 codex cli 这类工具时觉得慢大概率是网络源的问题换个镜像源或者用pnpm会快很多。安装 impeccable CLI 的流程按我的经验大概是# 全局安装如果它提供全局命令 npm install -g impeccable-cli # 或者在项目里本地安装 npm install -D impeccable-cli # 初始化配置 npx impeccable initinit这一步会问你几个问题项目类型React/Vue/原生、token 来源已有文件/从零生成、agent 工具codex cli/zcode cli/其他。这几个问题的答案决定了后续生成什么配置文件。提示如果你不确定 agent 工具选哪个先选“通用”后面可以改。impeccable 的配置大概率是幂等的重复 init 不会把已有配置冲掉。4.2 生成并校准 token 文件init 完成后你会得到一份初始 token 文件。这时候千万别直接开始用先做一轮校准。校准的方法是打开你项目里“最满意”的那个页面用 DevTools 把它的实际值抄下来和 token 文件对比。我踩过的一个坑是初始 token 文件里的 spacing 阶梯是4/8/16/24/32但我们项目实际用的是4/8/12/16/24。差了一个12导致所有用12px的地方都被标成偏差。后来我把 token 改成和实际一致报告立刻干净了。校准的检查清单spacing 阶梯是否覆盖了项目里 90% 以上的实际值颜色 token 是否包含了所有“品牌色”和“语义色”radius 是否覆盖了按钮、卡片、输入框三种主要圆角字号阶梯是否和你的排版系统一致4.3 把约束接入 agent 工作流这一步是整套流程的关键。以 codex cli 为例我实测的接入方式是在项目根目录放一份impeccable.rules.md然后在跟 agent 对话时第一句话就让它读这份文件。# 设计约束 在生成本项目任何前端代码前必须遵守以下约束 - 所有 spacing 只能使用4px, 8px, 12px, 16px, 24px, 32px - 所有颜色只能使用 tokens.json 中定义的值 - 所有 border-radius 只能使用4px, 8px, 9999px - 禁止使用 inline style必须用 className 或 styled 方案 - 所有交互元素必须有 hover、focus、disabled 三态这份文件的作用是“把隐性规范显性化”。agent 不是不听话是它不知道你的规范是什么。你写清楚了它遵守的概率会高很多。4.4 用 extension 做闭环校验代码写完后打开浏览器激活 impeccable extension它会自动扫描当前页面。扫描结果一般分三档红色明确违反 token必须修黄色接近但不在 token 内建议修灰色装饰性偏差可忽略我一般只处理红色和黄色。处理方式是把报告复制出来直接丢给 agent以下元素存在设计偏差请修复 - .card-header padding: 13px → 应为 12px 或 16px - .btn-primary background: #3b82f6 → 应为 #2563eb - .modal border-radius: 6px → 应为 4px 或 8pxagent 拿到这份清单修复的准确率比我口头描述高得多。这就是“结构化反馈”的威力。4.5 参数选择与计算过程这里补充一个实操中经常遇到的参数问题间距阶梯到底该设几档。我的经验公式是阶梯数 ceil(log2(最大间距 / 最小间距)) 1比如最小 4px最大 64pxlog2(16) 4所以 5 档左右比较合适。太少不够用太多等于没约束。常见的 5 档方案是4/8/16/32/64或者更细的 6 档4/8/12/16/24/32。颜色 token 的数量控制也类似。主色 3 档500/600/700中性色 5 档100/300/500/700/900语义色各 2 档成功/警告/错误的正反色。总共控制在 20 个以内agent 才记得住。5. 常见问题与排查技巧实录5.1 agent 不遵守约束怎么办这是最高频的问题。我的排查顺序是确认约束文件被读到了。让 agent 复述一遍约束如果它复述不出来说明没读到。确认约束的表述足够具体。“用合理的间距”是废话“只能用 4/8/12/16”才是约束。确认约束在对话的早期出现。agent 的上下文注意力是衰减的越早出现的约束越容易被遵守。确认没有冲突指令。如果你同时说“尽量紧凑”和“用 16px 间距”agent 会懵。5.2 extension 报告太多噪音噪音来源通常是 token 集和实际项目脱节。解决办法是先跑一轮“只报红色”的模式把红色清完再逐步放开黄色。另外给装饰性元素加>