企业官网建设流程全解析

1. 项目缘起：一个叫 impeccable 的前端设计工具到底在解决什么问题

第一次看到 "impeccable" 这个词，是在几个 AI coding agent 的讨论串里。有人甩出一句"用 impeccable 跑一遍，前端直接能看"，底下跟了一串追问：这玩意儿是 CLI 还是浏览器扩展？跟 codex cli、zcode cli 这些是不是一类东西？要不要单独装 node？我当时的反应跟大多数人一样——名字起得这么"完美主义"，八成又是个包装过度的玩具。

实际用下来才发现，它切中的是一个特别具体的痛点：AI 写出来的前端代码，功能能跑，但视觉上"差一口气"。你让 codex cli 或者别的 agent 生成一个登录页，它给你的是能用的 HTML/CSS，但间距是随手写的、配色是默认的、响应式是碰运气的。impeccable 干的事，就是把这"最后一公里"的打磨环节标准化、可复现化。

所以这篇东西不是产品说明书，是我自己从零装到跑通、踩了一堆坑之后整理出来的实操记录。适合三类人看：一是天天用 AI coding agent 生成前端、但每次都要手动调样式的前端；二是想搞清楚 CLI 工具和浏览器扩展这两种形态各自适合什么场景的工程师；三是单纯被"impeccable 如何使用"这个问题卡住、搜了半天没找到能落地答案的人。下面我会把安装、配置、和 agent 的配合方式、以及那些文档里不会写的坑，一条条拆开讲。

2. 先搞清楚 impeccable 的形态：CLI 还是浏览器扩展

2.1 两种形态的分工逻辑

热词里同时出现了 "CLI" 和 "browser extension"，这不是巧合。impeccable 这类工具通常提供两条入口，但它们服务的是完全不同的工作流，选错了会白白浪费时间。

CLI 形态的核心价值是可编排。它能在终端里被脚本调用，能塞进 CI 流程，能被 codex cli、zcode cli 这类 agent 当成一个"工具"去调用。你写一条命令，它读你的源码目录，输出优化后的样式或者一份诊断报告。适合批量处理、适合自动化、适合"我有一堆文件要过一遍"的场景。

浏览器扩展形态的核心价值是所见即所得。它挂在浏览器里，你打开一个页面，它实时分析 DOM 和计算样式，把问题直接标在你眼前。适合调试单个页面、适合"我就想看看这个按钮为什么歪了"的场景。

我个人的判断标准很简单：要处理的是"一批文件"还是"一个正在看的页面"。前者走 CLI，后者走扩展。两者不是替代关系，是互补关系。很多人卡在"impeccable 如何使用"上，本质是没先想清楚自己要解决哪一类问题。

2.2 为什么 CLI 形态更值得先上手

如果你只打算学一个，我建议先啃 CLI。原因有三个，都是实操里总结出来的。

第一，CLI 的输出是可版本控制的。它改的是你仓库里的文件，改完 git diff 一看，改了什么一目了然，不满意直接回滚。浏览器扩展的调整很多时候停留在运行时，关掉页面就没了，想固化下来还得手动抄。

第二，CLI 能和 agent 形成闭环。现在主流的 AI coding agent 基本都能执行 shell 命令，你把 impeccable 的 CLI 挂上去，agent 生成完代码后自己跑一遍打磨，出来的东西质量直接上一个台阶。这个玩法后面第 4 节会详细讲。

第三，CLI 的参数和配置是显式的。你调了什么、没调什么，全在命令行里写着，团队里别人能复现。扩展的很多行为藏在 UI 开关里，交接的时候容易丢信息。

提示：不要一上来就两个都装。先把 CLI 跑通，理解它的输入输出，再去看扩展，你会发现扩展的很多设计其实是在复刻 CLI 的能力，只是换了个交互壳。

2.3 环境依赖的现实情况

绕不开的一个问题：node 环境。热词里"node 安装 codex cli 很慢"这条，说明很多人是在 node 这一层就卡住了。impeccable 的 CLI 大概率也是 node 生态的产物，所以先把 node 和包管理器理顺。

我的建议是别用系统自带的 node，用版本管理工具。原因很实际：不同项目依赖的 node 版本不一样，系统级装一个，迟早会遇到版本冲突。装好之后，node -v和包管理器的版本都确认一遍，再往下走。这一步花五分钟，能省掉后面半小时的玄学报错。

3. 安装与首次运行：把 impeccable 跑起来

3.1 安装路径的选择与取舍

安装方式通常有两类：全局安装和项目内安装。这两者的区别不是"方便不方便"，而是"污染范围"。

全局安装的好处是任何目录下都能直接敲命令，适合你把它当成一个通用工具、到处用。坏处是版本锁死在一个全局版本上，A 项目需要新版、B 项目依赖旧版行为的时候，你会很难受。

项目内安装（作为 devDependency）的好处是版本跟着项目走，团队里每个人install完拿到的行为一致，CI 里也能复现。坏处是每个项目都要装一遍，磁盘上会多占点空间。

我的做法是：主力项目内安装，临时试用全局装。先用全局装快速验证这东西值不值得用，确认有价值了，再在正式项目里改成项目内依赖。这样既不会一上来就污染项目配置，也不会因为反复装卸浪费时间。

安装命令的形式一般是包管理器加包名，具体包名以官方为准。装完之后第一件事不是急着跑，而是--help看一眼。这一步很多人跳过，结果后面用错参数、跑出莫名其妙的结果，回头才发现命令本身就敲错了。

3.2 首次运行该拿什么文件试

新手最容易犯的错，是拿一个复杂的大项目当试验田。跑完一堆输出，根本分不清哪些是工具干的、哪些是原本就有的问题，直接懵。

正确的做法是造一个最小可复现的样本。一个 HTML 文件，里面放几个典型元素：一个带内边距的卡片、一个按钮、一段文字、一个简单的两栏布局。就这么点东西，跑一遍 impeccable，看它改了什么、报告了什么。样本越小，你越能看清工具的行为边界。

我自己的最小样本大概长这样：一个容器，里面一个标题、一段正文、一个按钮，容器有固定宽度。跑完之后对比 diff，你会立刻明白这个工具关注的是间距、层级、对比度还是别的什么。这个认知比读十页文档都管用。

3.3 第一次运行的输出怎么读

首次运行的输出通常分几块：检测到的问题、建议的修改、实际应用的改动。这三块要分开看。

检测到的问题里，有些是工具"认为"的问题，不一定是你"在意"的问题。比如它可能觉得某个间距不符合它的栅格体系，但你的设计稿本来就是那个值。这时候不要无脑接受，要有判断。

建议的修改和实际应用的改动之间可能有差异，因为有些建议需要你确认才生效。搞清楚哪些是自动应用的、哪些是需要交互确认的，能避免"我以为它改了其实没改"的尴尬。

注意：第一次运行务必在 git 干净的状态下做。跑完git diff一看，所有改动清清楚楚。如果工作区本来就有未提交的改动，工具改的和你自己改的混在一起，排查起来非常痛苦。

4. 和 AI coding agent 配合：让 impeccable 成为流水线的一环

4.1 agent 生成 + impeccable 打磨的闭环

这是我觉得 impeccable 最有价值的用法，也是热词里 "AI coding agents" 和 "frontend design" 同时出现的原因。

传统流程是：你给 agent 描述需求，agent 生成代码，你手动调样式。问题在于"手动调样式"这一步高度依赖个人审美和经验，而且每次都要重来。

闭环流程是：agent 生成代码，agent 自己调用 impeccable 的 CLI 打磨，然后你再 review。关键在于 agent 要能执行 shell 命令，并且知道什么时候该调用这个工具。现在主流的 agent 基本都支持配置"可用工具"，你把 impeccable 的命令注册进去，它就能在生成完前端代码后自动跑一遍。

这个闭环的收益是质量下限被抬高了。以前 agent 出来的东西可能 60 分，你调到 80 分；现在 agent 自己先打磨到 75 分，你只需要从 75 调到 85。省下来的时间很可观。

4.2 怎么把命令交给 agent

具体做法取决于你用的 agent。有的 agent 支持在配置文件里声明自定义命令，有的支持通过自然语言指令触发。核心思路是一样的：让 agent 知道有这么个工具、知道什么时候用、知道怎么用。

我通常会在项目的 agent 配置里写一段说明，大意是"生成或修改前端样式后，运行 impeccable 的检查命令，根据输出调整"。这样 agent 在完成任务时会主动考虑这一步，而不是等你提醒。

这里有个细节：命令的路径要写对。项目内安装的话，命令在node_modules/.bin下面，直接敲名字可能找不到，得用完整路径或者通过包管理器的执行入口。这个坑我踩过，agent 报"command not found"，排查半天才发现是路径问题。

4.3 和 codex cli 这类工具的协作边界

热词里 codex cli 出现频率很高，还有一堆关于它命令的问题，比如/compact、/model、/resume这些。这说明很多人在用 codex cli 做主力开发工具。

impeccable 和 codex cli 的关系，不是竞争，是上下游。codex cli 负责"从需求到代码"，impeccable 负责"从代码到能看"。你完全可以在 codex cli 的会话里，让它生成完页面后调用 impeccable，形成一条链。

但要注意边界：不要让 agent 无限制地反复调用打磨工具。有的 agent 会陷入"改一点、检查、再改一点"的循环，token 烧得飞快。我的做法是限制调用次数，比如生成后最多跑一轮，剩下的交给人来判断。工具是提效的，不是让它自己跟自己较劲的。

5. 核心参数与配置：把工具调成适合你的样子

5.1 配置文件的位置与优先级

这类 CLI 工具一般支持多级配置：全局配置、项目配置、命令行参数。优先级通常是命令行 > 项目 > 全局。理解这个优先级很重要，因为它决定了你改哪个文件能生效。

全局配置放你的个人偏好，比如默认的输出详细程度、默认的忽略规则。项目配置放团队约定，比如这个项目的设计规范、要忽略的目录。命令行参数放临时覆盖，比如这次我就想看看某个文件的详细报告。

我见过有人改了项目配置发现不生效，最后发现是命令行里带了个参数把它覆盖了。所以调参数之前，先确认当前生效的是哪一层。

5.2 几个值得关注的参数类型

具体参数名以官方为准，但类型上通常有这么几类，理解了类型你就知道该关注什么。

范围类参数：指定处理哪些文件、忽略哪些目录。这个一定要配好，否则它可能去扫node_modules或者构建产物，又慢又没意义。忽略规则写对了，运行速度能差好几倍。

严格度类参数：控制它报多少问题。调太松，该报的不报；调太严，一堆鸡毛蒜皮的警告淹没重点。我的经验是先松后严，先看它在大方向上能发现什么，再逐步收紧，聚焦到你真正在意的问题上。

输出类参数：控制输出格式，是给人看的还是给机器读的。如果要接进 CI 或者给 agent 消费，选结构化输出；如果自己看，选可读性好的。

应用类参数：控制是"只报告"还是"直接改文件"。这个要特别小心，第一次用一定选只报告，确认它的判断符合预期了，再开自动应用。

5.3 配置的版本控制策略

项目配置一定要进版本控制。这是团队协作的基本盘。别人 clone 下来，配置就在，行为一致。

但有个例外：包含个人路径或者本地环境信息的配置不要进。比如你本地某个绝对路径、某个只有你机器上有的工具路径。这类东西放全局配置或者本地覆盖文件里，并且把本地覆盖文件加进.gitignore。

我一般的做法是：项目里放一份xxx.config作为基准，再放一份xxx.config.local.example作为模板，实际的xxx.config.local被忽略。新人来了照着 example 改一份本地的就行，既有个性化空间，又不污染仓库。

6. 实操全流程：从零到跑通一条完整链路

6.1 环境准备与依赖确认

先把地基打牢。确认 node 版本、包管理器版本，然后在一个干净目录里初始化一个最小项目。不要在你现有的复杂项目里折腾，隔离环境能让你排除干扰。

初始化完之后，装 impeccable。装完--help确认命令可用。这一步如果报错，八成是 node 版本或者网络问题，先把这两个排查掉再往下。

6.2 构造测试样本并首次运行

按 3.2 说的，造一个最小 HTML 样本。然后跑一次只报告模式，把输出完整看一遍。重点看三件事：它检测到了什么、它建议怎么改、它有没有误报。

误报是判断工具成熟度的关键。如果它对一个明显没问题的样式也报一堆警告，说明默认严格度太高，需要调。如果它漏掉了明显的问题，说明覆盖范围不够，可能需要额外配置。

6.3 应用改动并对比 diff

确认报告合理之后，开自动应用模式再跑一次。跑完立刻git diff。对比每一处改动，问自己：这个改动我认不认可？认可的理由是什么？不认可的理由是什么？

不认可的改动，就是你需要通过配置去抑制的。把这类规则记下来，回头写进项目配置。跑几轮之后，你的配置就越来越贴合你的实际需求，工具的噪音也越来越少。

6.4 接入 agent 形成自动化

样本跑通、配置调好之后，再接入 agent。这时候你已经很清楚工具的行为边界了，agent 调用它出问题时，你能快速判断是 agent 用错了还是工具本身的问题。

接入之后，用一个真实的小需求测一遍完整链路：给 agent 描述需求，让它生成，让它调用 impeccable，然后你 review 最终结果。走通一遍，你就有了一个可复用的工作流。

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

7.1 安装阶段的典型问题

安装阶段的问题，九成是环境和网络。我的经验是优先用项目内安装，能绕开大部分全局权限和版本冲突的坑。

7.2 运行阶段的典型问题

跑得特别慢：先看它扫了哪些目录。如果扫进了node_modules或者构建产物，加忽略规则。这个是最常见的性能问题来源。

输出看不懂：换可读性更好的输出格式，或者先在小样本上跑，建立对输出结构的认知。

改了不该改的：立刻回滚，然后去配置里加抑制规则。不要手动去改工具改过的文件，那样下次运行又会覆盖。

和 agent 配合时报错：先手动在终端跑一遍同样的命令，确认命令本身没问题。如果手动能跑、agent 跑不了，那就是 agent 的执行环境或者路径配置问题。

7.3 几个文档里不会写的避坑经验

第一，别在没提交的状态下跑自动应用。这是我用血换来的教训。有一次工作区一堆未提交改动，工具一跑，改得面目全非，想回滚都分不清哪些是它的、哪些是我的。现在我的铁律是：跑之前git status必须干净。

第二，严格度不要一步到位。新手容易一上来就把所有检查开到最严，结果满屏警告，直接劝退。正确的节奏是先用默认值跑，看它默认关注什么，再根据你的实际痛点逐项收紧。

第三，agent 调用要设上限。前面提过，这里再强调一次。让 agent 反复打磨很容易失控，token 消耗和等待时间都会爆炸。给它一个明确的次数限制，比如一轮，剩下的交给人。

第四，配置要跟着项目走，不要跟着人走。你个人的偏好放全局，团队的约定放项目。这样换台机器、换个同事，行为都是一致的。

第五，小样本永远是你的朋友。遇到任何搞不懂的行为，回到最小样本上复现。复杂项目里的问题，往往在最小样本上几秒钟就能定位。

8. 我对这类工具的一点实际体会

用了一段时间 impeccable 之后，我最大的感受是：它不是一个"让前端变好看"的魔法，而是一个"把打磨这件事标准化"的框架。它不会替你做审美决策，但它能保证你不会漏掉那些基础的、机械的、每次都要重复检查的东西——间距、对齐、对比度、响应式断点。

真正省时间的地方，不在于它一次能改多少，而在于它把"检查"这个动作从"靠人记得"变成了"靠流程保证"。以前我 review AI 生成的前端，得逐项去看；现在我先跑一遍工具，把机械问题过滤掉，我的注意力就能集中在真正需要判断的地方。

如果你也在用 AI coding agent 做前端，我建议把它当成流水线上的一个工位，而不是一个独立的工具。它和 agent 配合起来，价值比单独用大得多。至于浏览器扩展那一块，等 CLI 用顺了再去碰，你会发现很多概念是相通的，上手会快很多。