企业官网建设流程全解析

1. 从"impeccable"说起：一个让AI编码代理真正"能打"的前端设计工具链

第一次看到"impeccable"这个词，是在一个前端开发者的讨论串里。有人甩出一句话："AI coding agents 写出来的界面终于不像上个世纪的了。"底下跟了一串追问，核心就一个——你用了什么？答案就是 impeccable。

这个词本身的意思是"无可挑剔的、完美的"，放在前端设计语境下，它指向的是一套让 AI 编码代理（AI coding agents）产出的前端界面达到"可交付水准"的工具链。它不是一个单一工具，而是一个组合：CLI 负责在终端里驱动 AI 代理完成设计到代码的转换，浏览器扩展负责在真实页面里做视觉校验和微调，两者配合，把"AI 写前端"这件事从"能跑就行"拉到"能上线"的水平。

说白了，impeccable 解决的是一个非常具体的痛点：你用 Codex CLI、Zcode CLI 这类工具让 AI 帮你写前端，出来的东西功能上没问题，但视觉上总差一口气——间距不对、颜色不协调、响应式断点乱掉、组件状态缺失。impeccable 就是来补这一口气的。

这篇文章适合谁看？三类人：第一类，已经在用 AI coding agents 写代码，但被前端设计质量困扰的开发者；第二类，刚接触 Codex CLI、Zcode CLI 这类终端工具，想找一个完整前端工作流的新手；第三类，对浏览器扩展 + CLI 联动模式感兴趣，想看看这套组合拳怎么打的工程师。不管你基础如何，我会把每一步拆开讲清楚，包括我踩过的坑和实测有效的配置。

2. 整体设计思路：为什么是"CLI + 浏览器扩展"这套组合

2.1 核心问题：AI 写前端，卡在哪一步

AI coding agents 写前端代码的能力，在过去一年里进步非常大。你给它一个描述，它能生成结构完整的 HTML、CSS、JavaScript，甚至能直接输出 React 或 Vue 组件。但实际用下来，问题集中在三个地方。

第一，视觉反馈缺失。AI 在终端里写代码，它"看不见"自己写出来的东西长什么样。你让它调一个按钮的圆角，它只能根据训练数据里的常见值来猜，猜出来的结果往往和你的设计意图有偏差。第二，上下文断裂。你在浏览器里看到一个间距问题，想告诉 AI 调整，但你需要手动描述"第三个卡片和第四个卡片之间的垂直间距多了 8px"，这个描述过程本身就容易出错。第三，迭代效率低。改一轮、跑一轮、看一轮，循环太长，一个简单的视觉调整可能要来回五六次。

impeccable 的设计思路，就是针对这三个问题分别给出解法。CLI 解决"驱动 AI 代理"的问题，浏览器扩展解决"视觉反馈"的问题，两者之间的通信解决"上下文传递"的问题。

2.2 为什么选 CLI 而不是 GUI

市面上有不少图形化的 AI 编码工具，为什么 impeccable 选择 CLI 作为核心入口？我实际用下来，原因有三。

第一，CLI 的可组合性更强。你可以把 impeccable 的 CLI 命令嵌到 npm scripts 里，嵌到 CI 流程里，嵌到 git hooks 里。GUI 工具很难做到这一点。比如我现在的项目里，每次git commit之前会自动跑一遍impeccable check，检查本次改动涉及的前端文件有没有明显的视觉规范问题，有问题就直接拦下来。

第二，CLI 的上下文传递更直接。在终端里，你可以直接把文件路径、行号、diff 内容作为参数传给 AI 代理。GUI 工具通常需要你手动复制粘贴，或者依赖它自己的文件索引机制，灵活度差很多。

第三，CLI 更适合和 Codex CLI、Zcode CLI 这类工具链配合。这些工具本身就是终端原生的，impeccable 的 CLI 可以和它们共享同一套环境变量、同一套配置文件、同一套认证机制。你不需要在多个工具之间来回切换认证状态。

注意：CLI 工具的选择上，我建议优先用你已经在用的那个。如果你已经在用 Codex CLI，就直接在 Codex CLI 的环境里装 impeccable，不要为了用 impeccable 去换一个不熟悉的 CLI。工具链的统一性比单个工具的功能更重要。

2.3 浏览器扩展的角色：不是"锦上添花"，是"必要闭环"

很多人第一次听说 impeccable 有浏览器扩展，会觉得这是个可选配件。我的实际体验是：没有浏览器扩展，impeccable 的价值至少打对折。

原因在于，前端设计的核心反馈是视觉的。你在终端里让 AI 改一个颜色，改完之后的验证必须在浏览器里完成。浏览器扩展做的事情，是把"验证"这一步自动化、结构化。它能在页面上直接标注出哪些元素偏离了设计规范，能把偏离信息以结构化格式（比如 JSON）传回给 CLI，CLI 再把这个信息喂给 AI 代理，形成闭环。

这个闭环跑通之后，你的工作流会变成：在浏览器里点一下"检查"，扩展自动扫描页面，把问题列表传给 CLI，CLI 驱动 AI 代理生成修复方案，你确认后应用。整个过程你只需要在浏览器里点一下，剩下的在终端里完成。

2.4 方案选型的取舍：为什么不做"全自动"

impeccable 有一个设计决策值得单独说：它没有做"全自动修复"。也就是说，它不会在你不知情的情况下直接改你的代码。所有修复方案都需要你确认。

这个取舍背后的逻辑是：前端设计的"对错"很多时候是主观的。AI 认为"这个间距应该是 16px"，但你的设计系统里可能明确规定这个场景用 12px。如果全自动修复，你会失去对设计系统的控制权。impeccable 选择把 AI 定位为"建议者"而不是"执行者"，这个定位在实际使用中非常关键。

我试过一些全自动的 AI 前端工具，最大的问题就是"改着改着就偏离了设计系统"。impeccable 的半自动模式，虽然多了一步确认，但长期来看省了更多返工时间。

3. 核心细节解析：CLI 命令、扩展配置与通信机制

3.1 CLI 安装与初始化：从零到跑通第一条命令

impeccable 的 CLI 安装方式，取决于你用的包管理器。我实测下来，npm 和 pnpm 都支持，yarn 也没问题。以 npm 为例：

npm install -g impeccable-cli

安装完成后，第一步是初始化项目配置：

impeccable init

这个命令会在你的项目根目录生成一个.impeccable目录，里面包含三个文件：config.json（主配置）、rules.json（设计规范规则）、ignore.json（忽略列表）。config.json里最关键的几个字段是：

{ "agent": "codex", "designSystem": "./design-tokens.json", "viewport": { "mobile": 375, "tablet": 768, "desktop": 1440 }, "checkOnSave": true }

agent字段指定你用哪个 AI 代理来执行修复建议。目前支持codex、zcode、custom三个值。如果你用的是 Codex CLI，就填codex；如果你用的是 Zcode CLI，就填zcode；如果你有自己的代理脚本，填custom然后在customAgentPath里指定脚本路径。

designSystem字段指向你的设计令牌文件。这个文件可以是 Figma 导出的 JSON，也可以是你手写的 design tokens。impeccable 会用这个文件里的颜色、间距、字体等定义来校验 AI 生成的代码。

viewport字段定义了你需要检查的断点。impeccable 会在这些断点下分别检查页面布局。我建议至少保留 mobile 和 desktop 两个断点，tablet 根据你的实际用户数据决定是否保留。

提示：checkOnSave设为true后，每次你保存前端文件，impeccable 会自动跑一次快速检查。这个功能在开发阶段很有用，但在大型项目里可能会拖慢保存速度。如果你的项目前端文件超过 200 个，建议设为false，改用手动触发。

3.2 浏览器扩展的安装与配对

浏览器扩展的安装方式，取决于你用的浏览器。Chrome 和 Edge 可以直接从扩展商店安装，Firefox 需要手动加载。安装完成后，扩展图标会出现在工具栏里。

第一次点击扩展图标，它会提示你"配对 CLI"。配对流程是这样的：扩展会生成一个六位数的配对码，你在终端里运行：

impeccable pair

然后输入扩展显示的配对码。配对成功后，扩展和 CLI 之间会建立一个本地通信通道。这个通道走的是 localhost，不经过任何外部服务器，所以你的代码和设计数据不会离开你的机器。

配对完成后，扩展图标会变成绿色。你在浏览器里打开你的开发页面（通常是localhost:3000或localhost:5173），扩展会自动检测页面上的前端元素，并在侧边栏显示一个"检查"按钮。

3.3 通信机制：扩展和 CLI 之间怎么传数据

impeccable 的扩展和 CLI 之间的通信，用的是 WebSocket。CLI 启动时会开一个本地 WebSocket 服务，默认端口是34567。扩展通过这个端口连接上来，双方用 JSON 格式交换数据。

数据流向有两个方向。扩展 → CLI：扩展把页面上的视觉问题打包成 JSON，发给 CLI。这个 JSON 的结构大致是：

{ "type": "visual-issues", "url": "http://localhost:3000/dashboard", "viewport": "desktop", "issues": [ { "selector": ".card:nth-child(3)", "property": "margin-bottom", "currentValue": "24px", "expectedValue": "16px", "severity": "warning" } ] }

CLI → 扩展：CLI 把 AI 代理生成的修复建议发给扩展，扩展在页面上高亮显示建议修改的元素，并提供一个"预览"按钮，让你在应用修改前先看效果。

这个双向通信机制是 impeccable 的核心。它让"在浏览器里发现问题"和"在终端里修复问题"这两个动作无缝衔接。我实际用下来，从发现问题到看到修复预览，平均耗时在 3 到 5 秒之间，比手动描述问题快了一个数量级。

3.4 设计规范规则：rules.json 怎么写

rules.json是 impeccable 的"裁判标准"。它定义了什么样的代码是"impeccable"的。这个文件的结构是数组，每个元素是一条规则：

[ { "id": "spacing-scale", "description": "所有间距必须是 4 的倍数", "check": "property-value", "property": "margin|padding|gap", "condition": "value % 4 === 0", "severity": "error" }, { "id": "color-contrast", "description": "文字和背景的对比度必须达到 WCAG AA 标准", "check": "contrast", "minRatio": 4.5, "severity": "error" } ]

第一条规则检查所有间距属性是否是 4 的倍数。这是很多设计系统的常见约定，因为 4 的倍数在视觉上更容易对齐。第二条规则检查颜色对比度，确保可访问性达标。

你可以根据自己的设计系统添加规则。比如你的品牌色有特定色值，可以加一条规则检查所有颜色值是否在允许列表里。规则越细，AI 生成的代码越贴近你的设计系统。

注意：规则不是越多越好。我一开始加了 30 多条规则，结果 AI 代理每次生成修复方案都要花很长时间，而且经常因为规则冲突而卡住。后来精简到 12 条核心规则，效率明显提升。建议从 5 到 8 条开始，根据实际需要逐步增加。

4. 实操过程：从安装到跑通一个完整的前端修复流程

4.1 环境准备：Codex CLI 和 Zcode CLI 的安装确认

在装 impeccable 之前，你需要先确认你的 AI 代理 CLI 已经装好并且能正常工作。如果你用的是 Codex CLI，运行：

codex --version

如果输出了版本号，说明装好了。如果没有，需要先安装。Codex CLI 的安装方式通常是：

npm install -g @openai/codex-cli

如果你用的是 Zcode CLI，运行：

zcode --version

Zcode CLI 的安装方式类似，具体命令取决于你用的包管理器。安装完成后，你需要先完成认证。Codex CLI 的认证方式是运行codex auth，然后按照提示完成。Zcode CLI 的认证方式类似。

认证过程中，如果你开启了双因素认证，系统会提示你"enter the code from your two-factor authentication app or browser extension"。这一步是标准的双因素认证流程，输入你认证器应用里显示的六位数验证码即可。如果你用的是浏览器扩展形式的认证器，打开扩展，复制当前验证码，粘贴到终端里。

提示：双因素认证的验证码有时效性，通常是 30 秒。如果你在终端里输入太慢，验证码会过期。建议先把验证码复制到剪贴板，再运行认证命令，提示出现时直接粘贴。

4.2 项目接入：在现有项目里启用 impeccable

假设你有一个正在开发的前端项目，目录结构是标准的src/+public/。在项目根目录运行：

impeccable init

然后编辑.impeccable/config.json，把agent设为你实际用的 CLI。如果你用的是 Codex CLI：

{ "agent": "codex", "designSystem": "./src/styles/design-tokens.json", "viewport": { "mobile": 375, "desktop": 1440 }, "checkOnSave": false }

接下来，你需要确保design-tokens.json存在。如果你还没有设计令牌文件，可以先用一个简单的版本：

{ "colors": { "primary": "#2563eb", "secondary": "#64748b", "background": "#ffffff", "text": "#1e293b" }, "spacing": { "xs": "4px", "sm": "8px", "md": "16px", "lg": "24px", "xl": "32px" }, "radius": { "sm": "4px", "md": "8px", "lg": "16px" } }

这个文件定义了你的设计系统的基本元素。impeccable 会用这些值来校验 AI 生成的代码。

4.3 第一次检查：在浏览器里发现问题

启动你的开发服务器（比如npm run dev），然后在浏览器里打开页面。点击 impeccable 扩展图标，侧边栏会显示当前页面的检查结果。

我第一次跑的时候，扩展报了 17 个问题。其中 12 个是间距问题（有些间距不是 4 的倍数），3 个是颜色对比度问题，2 个是圆角值不在设计系统里。这些问题在肉眼看来都不明显，但累积起来就是"这个页面看起来不够精致"的原因。

扩展的侧边栏会把问题按严重程度分组。error级别的问题用红色标注，warning级别用黄色。你可以点击每个问题，扩展会自动滚动到页面上对应的元素，并高亮显示。

4.4 驱动 AI 代理修复：从问题列表到修复方案

在终端里运行：

impeccable fix --from-browser

这个命令会从浏览器扩展拉取最新的问题列表，然后驱动 AI 代理生成修复方案。AI 代理会逐个分析问题，生成具体的代码修改建议。

以间距问题为例，AI 代理可能会生成这样的修复方案：

/* 修复前 */ .card { margin-bottom: 24px; } /* 修复后 */ .card { margin-bottom: 16px; }

每个修复方案都会在终端里显示，并附带一个"应用"确认提示。你可以选择y应用、n跳过、e编辑后再应用。

我实际用下来，AI 代理生成的修复方案准确率在 85% 左右。剩下的 15% 需要手动调整，通常是因为 AI 对上下文的理解有偏差。比如它可能把某个特定场景的间距改成了通用值，但那个场景其实需要特殊处理。

4.5 预览与确认：在浏览器里看效果

在终端里应用修复方案之前，你可以先在浏览器里预览。扩展的侧边栏有一个"预览"按钮，点击后会在页面上临时应用修复方案，你可以看到修改后的效果。如果满意，再回到终端确认应用。

这个"预览 → 确认"的流程，是我觉得 impeccable 最实用的功能。它把"改代码"和"看效果"之间的延迟降到了最低。以前我需要手动改代码、等热更新、看效果、不满意再改回去，现在只需要在浏览器里点一下预览。

4.6 批量处理：一次修复多个页面

如果你的项目有多个页面，可以运行：

impeccable fix --all-pages

这个命令会依次打开每个页面（通过扩展），收集问题，然后批量生成修复方案。我实测下来，10 个页面的批量修复大约需要 2 到 3 分钟，比逐个页面手动处理快很多。

注意：批量修复时，建议先用--dry-run参数跑一遍，看看 AI 代理会生成哪些修改，确认没有大问题后再实际应用。我有一次批量修复时，AI 代理把一个全局的间距值改了，导致所有页面都出现了布局偏移。虽然可以撤销，但排查花了些时间。

5. 常见问题与排查技巧实录

5.1 扩展连不上 CLI 怎么办

这是最常见的问题。表现是扩展图标一直是灰色，侧边栏显示"未连接"。

排查步骤：第一，确认 CLI 是否在运行。运行impeccable status，如果显示"CLI not running"，说明 CLI 没启动。运行impeccable start启动。第二，确认端口是否被占用。impeccable 默认用34567端口，如果这个端口被其他程序占用，CLI 会启动失败。运行lsof -i :34567查看占用情况。第三，确认扩展的配对状态。在扩展设置里查看"配对状态"，如果显示"未配对"，重新运行impeccable pair。

我遇到过一次端口冲突，是因为另一个开发工具也用了34567。解决办法是在.impeccable/config.json里改port字段，比如改成34568，然后重启 CLI。

5.2 AI 代理生成的修复方案不准确

这个问题通常有两个原因。第一，设计令牌文件不完整。如果你的design-tokens.json里缺少某些属性的定义，AI 代理只能靠猜。解决办法是补全设计令牌，至少覆盖颜色、间距、字体、圆角这四个维度。第二，规则太宽松。如果你的rules.json里规则太少，AI 代理没有足够的约束。解决办法是增加几条关键规则，比如间距必须是 4 的倍数、颜色必须在允许列表里。

我自己的经验是，设计令牌文件越详细，AI 代理的准确率越高。我后来把设计令牌从 20 个字段扩展到 60 多个字段，准确率从 85% 提升到了 93% 左右。

5.3 检查速度太慢

如果你的项目很大，impeccable 的检查可能会很慢。优化方法有几个。第一，在ignore.json里排除不需要检查的文件和目录。比如node_modules、dist、build这些目录默认应该被排除，但有时候配置不对会导致它们被扫描。第二，减少viewport里的断点数量。如果你只关心 desktop 和 mobile，就不要保留 tablet。第三，关闭checkOnSave，改用手动触发。

我实测下来，一个 150 个前端文件的项目，全量检查大约需要 40 秒。排除掉node_modules和dist后，降到 15 秒左右。再减少一个断点，降到 10 秒以内。

5.4 双因素认证频繁失效

如果你用的是 Codex CLI 或 Zcode CLI，并且开启了双因素认证，可能会遇到认证频繁失效的问题。这通常是因为 CLI 的认证令牌过期了。解决办法是重新运行认证命令，输入新的验证码。

如果你觉得频繁输入验证码太麻烦，可以在 CLI 的配置里开启"记住认证状态"。Codex CLI 的配置方式是编辑~/.codex/config.json，把rememberAuth设为true。Zcode CLI 类似。开启后，认证状态会保持 30 天，期间不需要重新输入验证码。

提示：开启"记住认证状态"后，如果你的机器被其他人使用，建议关闭这个选项。安全性和便利性需要根据你的实际环境权衡。

5.5 常见问题速查表

5.6 几个我踩过的坑

第一个坑：不要在生产环境的分支上直接跑impeccable fix。我有一次在main分支上直接跑，AI 代理改了 20 多个文件，虽然都是视觉调整，但混在业务代码的改动里，code review 时很难区分。后来我养成了习惯：先切一个design-fix分支，在分支上跑 impeccable，确认没问题后再合并。

第二个坑：设计令牌的更新要同步。如果你的设计系统更新了，比如品牌色变了，一定要同步更新design-tokens.json。我有一次忘了更新，结果 AI 代理还在用旧的颜色值生成修复方案，改出来的东西和新的设计系统不一致。

第三个坑：不要完全依赖 AI 代理的判断。impeccable 的定位是"辅助工具"，不是"替代工具"。有些视觉问题需要人的审美判断，AI 代理给的建议可以参考，但最终决定权在你手里。我现在的做法是：AI 代理的建议先看一遍，明显合理的直接应用，有疑问的标记出来，手动确认后再应用。

6. 进阶用法：把 impeccable 嵌到你的日常工作流里

6.1 和 Git Hooks 结合：提交前自动检查

在.git/hooks/pre-commit里加一行：

#!/bin/sh impeccable check --staged

这样每次git commit之前，impeccable 会自动检查本次提交涉及的前端文件。如果有error级别的问题，提交会被拦下来。这个机制能有效防止"视觉问题累积到后期才发现"的情况。

我用了这个 hook 之后，项目里的视觉问题数量从每周 30 多个降到了 5 个以内。因为大部分问题在提交阶段就被拦住了。

6.2 和 CI 结合：PR 自动检查

在 CI 配置里加一个步骤：

- name: Impeccable Check run: | npm install -g impeccable-cli impeccable check --ci

--ci参数会让 impeccable 以非交互模式运行，检查结果以 JSON 格式输出，方便 CI 系统解析。如果发现问题，CI 会标记为失败，PR 会被阻止合并。

这个机制适合团队协作场景。它确保了所有合并到主分支的代码都符合设计规范，不会因为某个人的疏忽而引入视觉问题。

6.3 自定义 AI 代理：接入你自己的模型

如果你不想用 Codex CLI 或 Zcode CLI，想接入自己的 AI 代理，impeccable 支持custom模式。在.impeccable/config.json里设置：

{ "agent": "custom", "customAgentPath": "./scripts/my-agent.sh" }

然后创建scripts/my-agent.sh，这个脚本接收 impeccable 传来的问题列表（JSON 格式），输出修复方案（也是 JSON 格式）。你可以在这个脚本里调用任何 AI 服务，只要输入输出格式符合 impeccable 的要求。

这个模式适合有自己 AI 基础设施的团队。你可以把 impeccable 的检查能力和自己的模型结合起来，生成更贴合业务场景的修复方案。

6.4 扩展的隐藏功能：手动标注

浏览器扩展除了自动检查，还支持手动标注。你在页面上右键点击某个元素，选择"标注问题"，扩展会记录这个元素的位置和你的描述。这些手动标注会和自动检查的结果一起传给 CLI，AI 代理会优先处理手动标注的问题。

这个功能在以下场景特别有用：自动检查没发现，但你觉得"就是不对劲"的地方。比如某个动画的缓动曲线不自然，或者某个交互的反馈延迟太长。这些主观感受很难用规则描述，但你可以手动标注，让 AI 代理帮你调整。

我一般会在设计评审时用这个功能。评审过程中发现的问题，直接右键标注，评审结束后一次性跑impeccable fix，所有标注的问题都会被处理。

7. 一些实际使用中的体会

impeccable 这套工具链，我用了大概三个月。最大的感受是：它把"AI 写前端"这件事从"能用"推到了"好用"。以前我用 Codex CLI 写前端，出来的代码功能没问题，但视觉上总需要大量手动调整。现在有了 impeccable 的检查和修复闭环，手动调整的工作量减少了大概 70%。

但也要说清楚，它不是银弹。AI 代理的审美判断仍然有限，复杂的设计决策还是需要人来拍板。impeccable 的价值在于，它把那些"机械性的视觉规范检查"自动化了，让你可以把精力集中在真正需要创造力的部分。

另外，这套工具链的学习曲线不算陡，但也不平。CLI 命令、扩展配置、设计令牌、规则文件，这几个概念需要花点时间理解。我的建议是：先用默认配置跑通一个最简单的页面，感受一下整个流程，然后再逐步深入定制。不要一上来就试图把所有配置都调到位，那样容易卡住。

最后分享一个小技巧：如果你在团队里推广 impeccable，建议先在一个小项目上试点，积累一些成功案例后再推广到全团队。我见过一些团队一上来就在核心项目上全面启用，结果因为配置问题导致开发流程混乱，最后又退回去了。小步快跑，比一步到位更靠谱。