企业官网建设流程全解析

1. 从"impeccable"这个词说起：一个被低估的前端质量信号

第一次看到"impeccable"作为项目名，我下意识去查了这个词的本义——无可挑剔的、零瑕疵的。放在前端设计和 AI coding agents 的语境里，这个词其实点出了一个很具体的痛点：AI 生成的界面代码，能跑，但经不起看。

我接触过不少用 AI coding agent 辅助做前端的团队，普遍反馈是"效率确实上来了，但返工率也上来了"。一个典型的场景是：你让 agent 生成一个登录页，它给你吐出来一个能用的表单，但间距是随意的、颜色是硬编码的、响应式断点是拍脑袋定的、无障碍属性基本没有。功能上没毛病，视觉和工程规范上全是毛病。这就是"peccable"（有瑕疵的）状态，而"impeccable"要解决的就是这个落差。

这个项目本质上是一个面向 AI coding agents 的前端设计质量约束层。它不是一个 UI 框架，也不是一个组件库，而是一套让 agent 在生成前端代码时"知道什么叫做得好"的规则、检查与反馈机制。关键词里出现的 CLI、browser extension、frontend design、AI coding agents，基本勾勒出了它的形态：命令行工具负责在开发流程里做静态检查和规范注入，浏览器扩展负责在真实渲染环境里做视觉层面的验证，两者共同服务于"让 AI 写出来的前端达到无可挑剔"这个目标。

适合读这篇内容的人有三类：一是正在用 codex cli、trae cli、zcode cli 这类工具做前端开发的工程师，想知道怎么把 AI 产出质量拉上一个台阶；二是团队里负责前端规范的技术负责人，想找一套能约束 AI 生成代码的机制；三是对 AI coding agent 工作流感兴趣、想理解"agent 时代前端工程该怎么做"的开发者。下面我会从它要解决的问题、核心机制、CLI 与浏览器扩展的分工、实操落地、以及踩坑经验几个层面，把这件事讲透。

2. AI 写前端为什么总是"差一口气"

2.1 功能正确和设计正确是两套评价体系

AI coding agent 的训练目标里，"代码能运行"的权重远高于"设计合理"。这不是模型的缺陷，而是任务定义的必然结果。当你给 agent 一个 prompt 说"做一个卡片列表"，它最稳妥的策略是生成一个结构正确、语法无误、能渲染出内容的实现。至于卡片之间的间距是 16px 还是 24px、圆角是 8px 还是 12px、hover 状态有没有过渡、移动端会不会挤成一团，这些在"能跑"的标准下都是可选项。

我在实际项目里做过一个对比：同一个需求分别让 agent 和人类前端各写一遍，功能完成度上 agent 甚至更快，但把两份代码放到设计评审里，agent 那份几乎每一屏都能挑出问题。问题不在于 agent 不会写 CSS，而在于它没有一个稳定的质量参照系。人类前端脑子里有一套隐性的规范——间距用 4 的倍数、颜色走 design token、断点统一、语义化标签优先——agent 没有这套东西，除非你显式地喂给它。

2.2 硬编码是 AI 前端代码的头号顽疾

翻 agent 生成的前端代码，出现频率最高的问题就是魔法数字和硬编码值。margin: 13px、color: #3a7bd5、width: 347px这种值随处可见。单看一处没问题，但一个页面几十处这样的值堆在一起，就变成了无法维护的泥潭。你想改主题色，得全局搜索替换；你想调整整体节奏，根本找不到规律。

这背后的原因是 agent 在生成时是局部最优的——它只考虑当前这个元素长什么样，不考虑整个页面的系统性。而"impeccable"这类工具的核心价值之一，就是在 agent 生成之后、代码合入之前，把这些硬编码值揪出来，强制它走 token 体系。这跟传统前端的 lint 思路一致，但针对的是 AI 生成场景下更高频、更隐蔽的硬编码问题。

2.3 响应式和可访问性是最容易被牺牲的两块

如果让我排 AI 前端代码的问题优先级，响应式布局和无障碍属性绝对排在前两位。原因很简单：这两块在"快速看到效果"的反馈循环里几乎不可见。你在桌面浏览器里打开 agent 生成的页面，看起来挺好；但一缩到手机宽度，布局就崩了。无障碍更是如此，aria-label、role、焦点管理这些东西，视觉上完全看不出来，agent 自然倾向于省略。

我见过一个真实案例：agent 生成的一个模态框，功能完整，但键盘用户根本没法关闭它——没有焦点陷阱，ESC 键没绑定，关闭按钮是个 div 而不是 button。这种问题在自动化测试里也测不出来，只有真正用键盘操作一遍才会暴露。"impeccable"把浏览器扩展作为一等公民，很大程度上就是为了在真实渲染环境里捕捉这类"看不见的缺陷"。

3. impeccable 的三层质量防线是怎么搭起来的

3.1 第一层：规范注入，让 agent 生成前就知道标准

最有效的质量控制不是事后检查，而是让 agent 在生成时就有约束。impeccable 的第一层机制是在项目里维护一份机器可读的设计规范，通常以配置文件的形式存在，agent 在生成前端代码前会读取这份规范。这跟 openspec cli 那类"先定规格再生成"的思路是一脉相承的，只不过 impeccable 聚焦在前端设计维度。

这份规范里通常包含几类内容：间距刻度（比如只允许 4/8/12/16/24/32 这几个值）、颜色 token 表（语义化命名，如--color-primary、--color-surface）、断点定义（sm/md/lg/xl 的具体像素）、圆角与阴影层级、以及组件命名约定。关键在于这些不是给人看的文档，而是 agent 能直接消费的结构化数据。当 agent 知道"间距只能用这几个值"，它生成margin: 13px的概率就会大幅下降。

这里有个实操细节值得说：规范文件不要写得太全太细。我一开始试图把所有设计决策都塞进去，结果 agent 反而因为约束太多而生成得很僵硬。后来精简到"间距、颜色、断点、圆角"四个核心维度，效果反而更好。约束的目的是消除随意性，不是替代判断，这个度要把握好。

3.2 第二层：CLI 静态检查，在提交前拦截问题

CLI 是 impeccable 最容易被集成进现有工作流的部分。它的定位类似 ESLint 或 Stylelint，但检查规则是针对 AI 生成代码的特点定制的。你可以把它挂在 git pre-commit hook 上，也可以放进 CI 流程，agent 每次生成完代码后自动跑一遍。

它检查的东西和传统 linter 有重叠也有差异。重叠的部分是语法和基础规范，差异的部分在于它专门盯AI 高频问题：硬编码颜色值、非刻度间距、缺失的响应式断点、未使用的 design token、以及可访问性属性的缺失。我实测下来，一个中等复杂度的页面，agent 首次生成后跑一遍检查，平均能报出 15 到 30 个问题，其中硬编码值占一半以上。

CLI 的另一个用途是生成前的规范校验。你可以用它检查项目里的规范配置文件本身是否合法、是否有冲突的 token 定义。这个功能在团队协作里很有用，避免不同人改规范改出矛盾。

3.3 第三层：浏览器扩展，在真实渲染里做视觉验证

静态检查再全，也检查不出"看起来对不对"。浏览器扩展这一层解决的就是渲染后的视觉与交互质量。它注入到页面里，做几件事：测量实际渲染的间距和尺寸是否符合规范、检测对比度是否达标、模拟不同视口宽度看布局是否崩坏、以及用键盘走一遍交互流程看焦点管理是否正常。

这一层和 CLI 的分工很清晰：CLI 管代码层面，扩展管渲染层面。有些问题只有渲染后才会暴露，比如两个元素在代码里间距都是 16px，但因为盒模型或 flex 布局的原因，实际视觉间距不一致。这种问题静态分析看不出来，必须测量真实 DOM。

提示：浏览器扩展这一层不要指望它全自动跑完就万事大吉。视觉质量有很强的主观成分，扩展能帮你抓客观缺陷（对比度、溢出、焦点），但"这个留白是不是舒服"这种判断，还是得人来看。

4. 把 impeccable 接进 codex cli 工作流的完整过程

4.1 环境准备与规范文件初始化

假设你已经在用 codex cli 做前端开发，接入 impeccable 的第一步是初始化规范文件。在项目根目录执行初始化命令，它会生成一份默认的规范配置，然后你根据自己项目的设计体系去改。这一步不要偷懒用默认值，因为默认值只是通用起点，跟你的实际设计语言大概率对不上。

初始化之后，规范文件里会有几个区块：spacing、color、breakpoint、radius、shadow。我的建议是先只填 spacing 和 color 两个区块，把这两个跑顺了再补其他的。原因是一上来全填，agent 的生成质量反而会因为约束过载而下降，而且你也不好判断到底是哪个维度的约束起了作用。

规范文件填完之后，用 CLI 的校验命令跑一遍，确认没有语法错误和 token 冲突。这一步很快，但能避免后面 agent 读到一份坏配置而生成出一堆莫名其妙的东西。

4.2 在 agent 生成流程里插入检查节点

接入的核心是在 codex cli 的工作流里插入检查节点。有两种接法：生成后检查和生成前注入。生成后检查是 agent 写完代码，你跑一遍 CLI，看报告再决定改不改；生成前注入是把规范文件的内容作为上下文喂给 agent，让它在生成时就遵守。

我推荐两个都做，但顺序有讲究。先做生成前注入，再做生成后检查。因为如果 agent 生成时就有规范约束，生成后检查报出的问题会少很多，你的返工成本也低。实测下来，只做生成后检查的话，一个页面平均要改两三轮；加上生成前注入，通常一轮就能过。

具体操作上，生成前注入可以通过在 prompt 里引用规范文件，或者用 CLI 提供的注入命令把规范拼进 agent 的上下文。生成后检查就是标准的 CLI 调用，输出一份问题清单。这份清单最好能结构化输出（比如 JSON），方便你后续做统计或者接入其他工具。

4.3 用浏览器扩展做最后一公里的视觉验收

代码层面过了 CLI 检查，不代表视觉上就没问题了。这时候打开浏览器扩展，在真实页面里跑一遍验证。扩展会给你一份渲染层面的报告，包括：实际间距与规范的偏差、颜色对比度、各断点下的布局状态、以及键盘导航的焦点路径。

我一般会重点看三个东西：对比度报告（这个最容易出问题，agent 选的颜色经常在浅色背景上对比度不足）、断点布局（尤其是 320px 和 768px 这两个临界宽度）、焦点顺序（Tab 键走一遍，看是否合理）。这三项过了，基本就能交付了。

注意：浏览器扩展的验证要在真实数据下做，不要用空状态或者假数据。很多布局问题只有在内容长度、数量达到真实水平时才会暴露，比如列表项多了之后换行错位、长文本溢出容器等。

5. 那些只有踩过才知道的坑

5.1 规范太严会让 agent "摆烂"

这是我踩过最深的坑。一开始我把间距刻度定得特别细，从 2px 到 64px 列了十几个值，结果 agent 生成时反而开始乱用——因为它面对太多选择，索性随便挑一个。后来我把刻度砍到 6 个值，生成质量立刻上来了。

这件事的教训是：给 agent 的约束要"少而硬"，不要"多而软"。选项越少，agent 越容易做对；选项越多，它越容易做错。这跟给人做设计规范是一个道理，好的设计系统从来不是选项越多越好，而是把选择收敛到少数几个经过验证的值上。

5.2 硬编码检查会有误报，别一刀切

CLI 的硬编码检查不是万能的。有些值就是需要硬编码，比如某些动画的精确时长、特定图形的尺寸、或者第三方组件的覆盖样式。如果你把检查规则设成"任何硬编码都报错"，那误报会多到你想关掉它。

我的做法是分级处理：颜色和间距的硬编码报 error，其他维度的硬编码报 warning。颜色和间距是最应该走 token 的，其他维度可以容忍例外。另外，允许通过注释显式豁免，比如在那一行加个impeccable-ignore标记，这样既保留了灵活性，又不会让豁免变成常态。

5.3 浏览器扩展和某些框架的 hydration 会打架

如果你用的是服务端渲染加客户端 hydration 的框架，浏览器扩展在页面 hydration 完成前就去测量 DOM，会拿到不准确的数据。我遇到过扩展报告说某个元素宽度是 0，但实际上渲染完是正常的——就是因为测量时机太早。

解决办法是让扩展等待 hydration 完成的信号，或者延迟一段时间再测量。impeccable 的扩展一般会提供配置项让你设置等待策略。这个坑不踩一次很难想到，但踩过之后就知道，任何在渲染后做测量的工具，都要考虑框架的渲染时序。

5.4 别把 impeccable 当成设计决策的替代品

工具能保证"不出错"，但保证不了"出彩"。impeccable 能让 agent 生成的界面在规范层面无可挑剔，但一个界面好不好看、有没有设计感，还是取决于设计本身。我见过有人指望靠这套工具让 AI 生成"惊艳"的界面，结果发现出来的东西规范是规范了，但很平庸。

正确的预期是：impeccable 负责把下限拉高，上限还是靠人。它消除的是那些低级错误和随意性，让 agent 的产出达到"专业及格线"，至于能不能到优秀，那是设计能力和审美的问题，工具帮不了。

6. 从单点工具到工作流：impeccable 的扩展玩法

6.1 把检查报告变成 agent 的反馈回路

impeccable 的 CLI 报告如果只是给人看，价值就只用了一半。更有意思的玩法是把报告结构化后喂回给 agent，让它根据报告自动修复。这就形成了一个闭环：agent 生成 → CLI 检查 → 报告喂回 → agent 修复 → 再检查。

我试过这个流程，对于硬编码和间距这类机械性问题，agent 的自动修复成功率很高，基本两轮就能清干净。但对于可访问性和响应式这类需要理解上下文的问题，自动修复的成功率就一般，还是得人介入。所以这个闭环适合处理"规则明确"的问题，不适合处理"需要判断"的问题。

6.2 用规范文件做团队的设计对齐

规范文件除了给 agent 用，其实也是团队设计对齐的好载体。以前设计规范写在文档里，没人看；现在它变成了 agent 必须遵守的配置文件，反而倒逼团队把它维护好。我见过一个团队，就是因为引入了这套机制，才第一次把散落在各处的设计决策收敛成了一份统一的规范。

这件事的副产品是：新人和 agent 的产出质量差距缩小了。因为规范是显式的、机器强制的，新人不再需要靠"悟"来理解团队的设计习惯，照着规范做就行。这对团队规模化的价值，可能比单纯提升 AI 生成质量还大。

6.3 和 openspec 类工具的配合

如果你在用 openspec cli 这类"先定规格再生成"的工具，impeccable 可以和它形成很好的配合。openspec 负责定义"做什么"，impeccable 负责约束"做成什么样"。前者管功能规格，后者管设计规格，两者结合，agent 拿到的上下文就完整了。

实操上，我会在 openspec 的规格文件里引用 impeccable 的规范文件，让 agent 一次性拿到功能和质量两方面的约束。这样生成出来的代码，既符合需求，又符合设计规范，返工率能再降一截。

7. 我实际用下来的一些体会

用 impeccable 这套东西大概几个月，最大的感受是：AI 前端开发的质量问题，本质上是"标准缺失"问题，不是"能力不足"问题。agent 完全有能力写出规范的前端代码，它只是不知道你的标准是什么。一旦你把标准显式化、机器化，它的产出质量会有肉眼可见的提升。

另一个体会是，工具的价值在于把人的注意力解放出来。以前我审 agent 生成的前端代码，大量时间花在找硬编码、查间距、看对比度这些机械问题上。现在这些交给 CLI 和扩展，我的注意力可以放在真正需要判断的地方——交互流程顺不顺、信息层级清不清楚、整体气质对不对。这才是人该干的事。

最后分享一个小心得：规范文件要当成活文档来维护，不要一次定死。项目在演进，设计语言也在变，规范文件如果半年不更新，就会和实际脱节，agent 遵守的是一套过时的标准，反而添乱。我现在的习惯是每个迭代回顾一次规范文件，把新出现的模式沉淀进去，把不再用的值删掉。这件事花不了多少时间，但能让整套机制持续有效。