企业官网建设流程全解析

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

第一次看到impeccable这个词，是在几个 AI coding agent 的讨论串里。它本身是个形容词，意思是“无可挑剔的、完美的”，但在这里它是一个工具的名字，一个专门服务于前端设计环节的 CLI 工具，同时配套了浏览器扩展。我花了一段时间把它跑通、用顺，也踩了不少坑，这里把完整的思路和实操过程整理出来。

先说清楚它是什么。impeccable的核心定位，是让 AI coding agent 在生成前端界面时，能够拿到一份“设计规范级别”的约束，而不是让模型自由发挥、生成一堆看起来能用但视觉上很糟糕的代码。它通过 CLI 提供设计规则的注入、校验和导出能力，通过浏览器扩展提供实时的视觉反馈和元素拾取。简单说，它解决的是 AI 写前端“能跑但难看”这个老问题。

适合谁来参考？如果你正在用 codex cli、zcode cli、openspec cli 这类命令行 AI 编程工具做前端开发，或者你在用 minimax cli 之类的工具生成页面，那 impeccable 值得花时间研究。如果你只是偶尔写写 HTML，可能感受不深。但只要你涉及 AI 辅助的前端设计流程，这个东西能省掉大量反复调整样式的时间。

我最初接触它是因为一个实际痛点：用 codex cli 生成一个登录页，出来的东西功能没问题，但间距、字体层级、颜色对比度全都不对，改起来比自己写还慢。impeccable 的思路就是把这个“改”的过程前置，让 agent 在生成之前就拿到明确的设计约束。

2. 核心设计思路拆解：为什么是 CLI 加浏览器扩展的组合

2.1 为什么不做成纯 CLI 或纯插件

很多人第一反应是，设计规范校验为什么不做成一个纯 CLI 工具，跑一遍输出报告就行？或者干脆做成纯浏览器插件，实时看效果？impeccable 选择两者结合，背后有很实际的考量。

纯 CLI 的问题是，设计这件事本质上是视觉的。你在命令行里输出一堆“间距不符合 8px 网格”“对比度低于 4.5:1”的文字报告，开发者要对照着去改，效率很低。而纯浏览器扩展的问题是，它只能做事后检查，没法在 AI agent 生成代码之前就把规则注入进去。AI coding agent 的工作流是“接收指令→生成代码→写入文件”，浏览器扩展插不进这个流程。

所以 impeccable 的分工是：CLI 负责规则的定义、注入和批量校验，浏览器扩展负责可视化的元素拾取和实时预览。CLI 是“规则引擎”，扩展是“眼睛”。这个组合的逻辑，跟很多设计系统工具的思路是一致的，但 impeccable 把它做轻了，没有引入庞大的设计系统依赖。

2.2 设计规则的注入机制

impeccable 的 CLI 在运行时，会读取一份设计配置文件，通常是一个 JSON 或 YAML 文件，里面定义了间距比例、字体阶梯、颜色令牌、圆角规范等。然后它把这些规则转换成 AI agent 能理解的提示词片段，注入到 agent 的上下文里。

这里有个关键设计：它不是简单地把规则文本塞进去，而是做了结构化转换。比如间距规则，它会生成类似“所有 margin 和 padding 必须是 4 的倍数，优先使用 8、16、24、32 这几个值”这样的约束语句，而不是丢一个数组让模型自己理解。这个转换过程是 impeccable 的核心价值之一，因为直接丢规则数组给模型，模型经常会忽略或者理解偏差。

我实测下来，经过 impeccable 注入的规则，codex cli 生成的前端代码在间距一致性上有明显提升。之前生成的卡片组件，内边距有时候 12px 有时候 15px，现在基本稳定在 16px 或 24px。

2.3 与 AI coding agent 的协作模式

impeccable 跟 codex cli、zcode cli 这些工具的协作，不是替代关系，而是增强关系。你还是在 codex cli 里下指令，但 impeccable 会在中间做一层规则注入。

具体流程是这样的：你在项目根目录初始化 impeccable 配置，定义好设计规则。然后当你用 codex cli 生成前端代码时，impeccable 的 CLI 会先运行，把规则转换成提示词前缀，再交给 codex cli 处理。生成完成后，impeccable 还可以跑一次校验，检查生成的代码是否符合规则。

这个模式的好处是，你不需要改变现有的 AI coding 工作流。你还是在用 codex cli 的那些命令，比如/compact、/model、/resume，只是多了一层 impeccable 的规则保障。对于已经习惯了 codex cli 命令体系的开发者来说，迁移成本很低。

3. 环境准备与安装实操：从零把 impeccable 跑起来

3.1 安装前的依赖检查

在安装 impeccable 之前，有几件事必须先确认。首先是 Node.js 环境，impeccable 的 CLI 是基于 Node 的，建议用 Node 18 或以上版本。我试过 Node 16，部分依赖会报错。你可以用node -v检查版本。

其次是包管理器，npm 和 pnpm 都可以，但我个人推荐 pnpm，因为 impeccable 的依赖树比较深，pnpm 的硬链接机制能省不少磁盘空间，安装速度也快一些。如果你还没装 pnpm，可以用npm install -g pnpm装一个。

第三是浏览器扩展的安装环境。impeccable 的浏览器扩展目前主要支持 Chromium 内核的浏览器，安装方式可以是应用商店，也可以是开发者模式加载。如果你用的是其他内核的浏览器，可能需要找对应的版本。

注意：安装 codex cli 很慢是很多人遇到的问题，这通常是因为默认的 npm 源在国内访问不稳定。可以切换镜像源来加速，但具体用哪个源需要根据你的网络环境测试。impeccable 的安装也可能遇到类似情况，建议先把包管理器的源配置好。

3.2 CLI 的安装步骤

安装 impeccable CLI 的命令很直接：

pnpm add -g impeccable-cli

或者用 npm：

npm install -g impeccable-cli

安装完成后，用impeccable --version验证是否成功。如果提示命令找不到，检查一下全局 bin 目录是否在 PATH 里。pnpm 的全局 bin 目录通常是~/.local/share/pnpm，npm 的通常是/usr/local/bin或用户目录下的.npm-global/bin。

安装过程中如果卡住，大概率是网络问题。可以试试先pnpm store prune清理缓存，再重新安装。我遇到过几次安装到一半卡在某个依赖的 postinstall 脚本上，等几分钟就好了，不要急着中断。

3.3 浏览器扩展的加载方式

浏览器扩展的安装，如果你能从应用商店直接装，那是最省事的。如果不行，就用开发者模式加载。具体步骤是：打开浏览器的扩展管理页面，开启“开发者模式”，然后选择“加载已解压的扩展程序”，指向 impeccable 扩展的构建目录。

扩展加载后，你会在浏览器工具栏看到 impeccable 的图标。点击图标，它会尝试连接本地的 impeccable CLI 服务。如果连接不上，检查一下 CLI 是否在运行，以及端口是否被占用。默认端口是 3456，可以在配置里改。

提示：浏览器扩展和 CLI 的版本要匹配。我有一次 CLI 升级了但扩展没更新，导致元素拾取功能失效，排查了半天才发现是版本不一致。建议升级 CLI 后，顺手检查一下扩展是否有更新。

4. 设计规则配置：把“好看”变成可执行的约束

4.1 配置文件的结构与字段说明

impeccable 的配置文件通常叫impeccable.config.json，放在项目根目录。它的结构分为几个主要部分：spacing、typography、color、radius、shadow。每个部分定义了一组规则。

spacing部分定义间距比例。你可以指定基准单位和允许的倍数。比如基准 4px，允许 1、2、3、4、6、8 倍，对应 4、8、12、16、24、32px。这个设置会直接影响 AI 生成代码时的 margin 和 padding 取值。

typography部分定义字体阶梯。你需要指定各级标题和正文的字号、行高、字重。impeccable 会把这些转换成“h1 使用 32px 字号、1.25 行高、700 字重”这样的约束。

color部分定义颜色令牌。你可以定义主色、辅助色、中性色、语义色（成功、警告、错误）。每个颜色给一个名称和一个色值。impeccable 会生成“使用 primary 色而不是硬编码 #3b82f6”这样的规则。

radius和shadow部分相对简单，定义圆角半径和阴影层级的可选值。

4.2 如何根据项目类型调整规则

不同的项目类型，设计规则应该不一样。一个后台管理系统的间距可以紧凑一些，基准 4px，常用 8、12、16。一个营销落地页的间距可以宽松一些，基准 8px，常用 16、24、48。

字体阶梯也是。后台系统正文 14px 就够了，营销页面正文可能要 16px 或 18px。标题的跳跃幅度也不一样，后台系统 h1 可能 24px，营销页面 h1 可能 48px。

我的做法是准备几套预设配置，放在不同的文件里，根据项目类型切换。impeccable 支持通过--config参数指定配置文件路径，所以你可以这样用：

impeccable inject --config ./configs/dashboard.json

这样就不用每次手动改配置了。

4.3 规则注入到 AI agent 的实操

规则注入是 impeccable 最核心的功能。用法是在启动 AI coding agent 之前，先运行 impeccable 的注入命令。以 codex cli 为例，流程是这样的：

impeccable inject --target codex --output .impeccable-prompt.md

这个命令会生成一个提示词文件，里面包含了所有设计规则的文字化描述。然后你在 codex cli 里，用/model确认模型，用/compact清理上下文，再把提示词文件的内容作为系统提示的一部分传进去。

具体怎么传，取决于你用的 agent 工具。codex cli 支持通过--system-prompt参数指定系统提示文件，你可以直接指向 impeccable 生成的文件。zcode cli 和 openspec cli 也有类似的机制，具体参数名可能不同，查一下各自的文档就行。

注意：注入的提示词不要太长。我有一次把整套设计规则都塞进去，结果 agent 的上下文被占用了太多，生成质量反而下降。建议只注入当前任务相关的规则，比如生成卡片组件时，只注入间距、圆角、阴影规则，颜色和字体规则可以精简。

5. 浏览器扩展的实战用法：元素拾取与实时校验

5.1 元素拾取功能的操作流程

浏览器扩展最实用的功能是元素拾取。你在浏览器里打开一个页面，点击 impeccable 扩展图标，进入拾取模式。然后把鼠标移到任意元素上，扩展会高亮显示该元素，并在侧边栏展示它的样式信息：间距、字体、颜色、圆角、阴影。

这个功能在两种场景下特别有用。第一种是你在参考某个现有页面的设计，想提取它的设计令牌。你可以逐个拾取元素，把关键数值记下来，然后写进 impeccable 配置。第二种是你在检查 AI 生成的页面，想快速定位哪些元素的样式不符合规则。扩展会用红色标记违规元素，并给出具体的违规原因。

我实测下来，拾取功能的准确度不错，但对于使用了 CSS-in-JS 或者 Shadow DOM 的页面，偶尔会有样式读取不全的情况。遇到这种情况，可以试试在扩展设置里开启“深度模式”，它会尝试穿透 Shadow DOM 读取样式。

5.2 实时校验与违规提示

实时校验是另一个高频功能。开启后，扩展会持续监控页面上的元素，一旦发现样式不符合 impeccable 配置里的规则，就在元素旁边显示一个小标记。点击标记，会弹出详细的违规说明和修改建议。

这个功能的实现原理是，扩展通过 content script 注入到页面，读取每个元素的 computed style，然后跟配置里的规则做比对。比对逻辑包括：间距值是否在允许的倍数集合里、字号是否在字体阶梯里、颜色是否匹配某个令牌、圆角是否在允许值里。

违规提示的准确度取决于配置的严格程度。如果你把间距规则设得很死，只允许 8、16、24、32，那 12px 就会被标记。但有时候 12px 是合理的，比如图标和文字之间的间距。所以我的建议是，规则不要太死，留一些弹性空间。可以在配置里加一个exceptions字段，列出允许的例外值。

5.3 与 CLI 的联动：从浏览器到代码的闭环

浏览器扩展和 CLI 的联动，体现在一个很实用的功能上：你可以在浏览器里拾取一个元素，然后一键生成对应的 impeccable 规则片段，直接写入配置文件。或者反过来，你在 CLI 里跑一次全量校验，生成一份违规报告，然后在浏览器里逐条查看和修复。

这个闭环的价值在于，它把“看”和“改”连起来了。传统流程是，你在浏览器里看到问题，然后切到编辑器改代码，再切回浏览器刷新看效果。impeccable 把这个流程缩短了，你可以在浏览器里直接看到违规，然后根据提示去改代码，改完刷新，违规标记消失，闭环完成。

提示：浏览器扩展的校验结果可以导出为 JSON 或 CSV，方便在 CI 流程里做自动化检查。我试过把导出结果接到 GitHub Actions 里，每次 PR 都跑一次设计规则校验，不通过就阻止合并。这个做法对于团队协作很有价值，能防止设计规范被随意破坏。

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

6.1 安装与启动阶段的典型问题

问题一：安装 codex cli 很慢，impeccable 安装也慢。这是网络问题，不是工具本身的问题。可以试试切换包管理器的源，或者用--prefer-offline参数利用本地缓存。如果实在慢，可以先用pnpm store add把包下载到本地 store，再安装。

问题二：impeccable 命令找不到。检查全局 bin 目录是否在 PATH 里。pnpm 的话，运行pnpm setup会自动配置。npm 的话，检查npm config get prefix的输出，确保那个目录在 PATH 里。

问题三：浏览器扩展连接不上 CLI。检查 CLI 是否在运行，端口是否被占用。可以用lsof -i :3456查看端口占用情况。如果端口被占，改配置里的端口号，或者杀掉占用进程。

6.2 规则注入不生效的排查思路

规则注入不生效，通常有几个原因。第一，提示词文件没有正确传给 agent。检查一下 agent 的启动参数，确认系统提示文件路径正确。第二，提示词内容太长，被 agent 截断了。可以精简规则，只保留当前任务相关的部分。第三，agent 本身对系统提示的遵循度不高。这个跟模型有关，有些模型对系统提示的遵循度就是差一些，可以试试换模型，或者在用户提示里再强调一遍关键规则。

我遇到过一次，规则注入后 agent 完全忽略，后来发现是提示词文件里有个语法错误，导致整个文件解析失败。所以生成提示词后，最好打开文件看一眼，确认内容完整、格式正确。

6.3 浏览器扩展的兼容性问题

浏览器扩展在不同网站上的表现可能不一样。有些网站用了大量的动态样式和框架，扩展读取样式时可能拿到的是初始值而不是最终值。遇到这种情况，可以试试在扩展设置里调整“样式读取延迟”，让它等页面渲染完成后再读取。

另外，扩展在某些网站上可能被 CSP 策略阻止。如果扩展图标是灰色的，点不动，大概率是 CSP 问题。可以试试在扩展设置里开启“兼容模式”，它会用另一种方式注入脚本。

6.4 常见问题速查表

7. 与主流 AI coding agent 的配合经验

7.1 在 codex cli 里的集成方式

codex cli 是我用得最多的 agent 工具，它的命令体系比较清晰，/compact清理上下文、/model切换模型、/resume恢复会话，这些命令在日常使用中很顺手。impeccable 跟 codex cli 的集成，主要是通过系统提示注入。

具体做法是，在项目根目录放一个.impeccable-prompt.md文件，然后在 codex cli 的配置里指定它为系统提示文件。codex cli 支持在项目级配置里设置系统提示，这样每次启动都会自动加载。如果你不想每次都注入，也可以在需要的时候手动指定。

我实测下来，codex cli 对系统提示的遵循度还不错，尤其是用了较新的模型之后。生成的前端代码在间距和字体层级上，明显比不注入规则时要规范。但颜色方面，模型有时候还是会硬编码色值，而不是用令牌。这个可能需要更明确的提示，比如“禁止使用十六进制色值，必须使用 CSS 变量”。

7.2 与 zcode cli、openspec cli 的配合

zcode cli 和 openspec cli 的集成方式类似，都是通过系统提示或项目配置来注入规则。不同工具的配置格式可能不一样，但核心逻辑是一样的：把 impeccable 生成的提示词文件，作为 agent 的上下文输入。

openspec cli 有一个特点，它支持“规范文件”的概念，你可以把设计规则写成一个规范文件，agent 在生成代码时会参考这个规范。这个机制跟 impeccable 的思路很契合，你可以把 impeccable 的配置转换成 openspec 的规范格式，实现更紧密的集成。

zcode cli 的配置相对灵活，支持通过环境变量指定系统提示文件。你可以在 shell 配置里设置ZCODE_SYSTEM_PROMPT=.impeccable-prompt.md，这样每次启动 zcode cli 都会自动加载。

7.3 多 agent 协作时的规则一致性

如果你同时用多个 agent 工具，比如 codex cli 写业务逻辑，minimax cli 生成页面，那规则一致性就很重要。我的做法是，把 impeccable 配置作为单一事实来源，所有 agent 都从这个配置生成各自的提示词文件。

具体来说，写一个脚本，读取 impeccable 配置，然后分别生成 codex 格式、zcode 格式、openspec 格式的提示词文件。每次配置更新，跑一遍脚本，所有 agent 的规则就同步了。这个做法虽然多了一步，但能避免不同 agent 生成风格不一致的代码。

提示：如果你在用 codex cli 的/resume功能恢复会话，注意恢复后的会话可能不会重新加载系统提示。这时候需要手动重新注入规则，或者在恢复后跑一次 impeccable 的校验，看看生成的代码是否符合规则。

8. 从设计规范到代码质量的完整闭环

8.1 校验流程的自动化

impeccable 的校验功能可以集成到 CI 流程里。具体做法是，在 CI 配置里加一步，运行impeccable check，它会扫描项目里的前端代码，检查是否符合设计规则。不符合就返回非零退出码，CI 就会失败。

这个做法的好处是，设计规范不再是一纸空文，而是有强制力的约束。任何 PR 如果破坏了设计规范，CI 会直接拦住。我试过在一个小团队里推行这个做法，效果不错，前端代码的视觉一致性明显提升。

校验的严格程度可以配置。初期可以设成“警告”模式，只提示不阻断。等团队适应了，再改成“错误”模式，强制阻断。这样有个过渡期，不会一下子引起太大反弹。

8.2 设计令牌的导出与复用

impeccable 支持把配置导出为多种格式的设计令牌，比如 CSS 变量、SCSS 变量、JavaScript 对象、JSON。这个功能很实用，因为你可以把同一套设计规则，同时用于 AI 生成代码和手写代码。

导出命令大概是这样的：

impeccable export --format css --output ./src/styles/tokens.css

导出的 CSS 变量文件，可以直接在项目里引用。这样 AI 生成的代码和手写的代码，用的都是同一套令牌，视觉上自然就一致了。

我通常会把导出的令牌文件提交到代码仓库，这样团队成员拉取代码后，直接就能用。如果设计规则更新了，重新导出一次，提交，大家拉取后自动生效。

8.3 团队协作中的规范落地经验

在团队里推行设计规范，最大的阻力往往不是工具，而是习惯。开发者习惯了随手写margin: 13px，你让他改成margin: 12px或margin: 16px，他会觉得麻烦。所以工具要尽量无感，不能增加太多操作负担。

impeccable 在这方面做得不错，它的校验是自动的，提示是实时的，开发者不需要额外做什么，就能看到违规。而且违规提示会给出具体的修改建议，比如“将 13px 改为 12px 或 16px”，降低了修改的心理门槛。

我的经验是，先在小范围试点，找一两个愿意尝试的开发者，把流程跑通，收集反馈。等流程顺了，再推广到整个团队。推广的时候，重点讲“这个工具能帮你省时间”，而不是“这个工具能约束你”。角度不一样，接受度差很多。

9. 一些踩坑之后的个人体会

用 impeccable 这段时间，最大的感受是，设计规范这件事，工具只能解决一半问题，另一半是人的意识。工具能告诉你哪里不符合规范，但改不改、怎么改，还是取决于开发者。所以选工具的时候，易用性和提示的友好度，比功能的多少更重要。

另一个体会是，规则不要太细。我一开始把间距规则设得很死，只允许 4 的倍数，结果生成代码时，agent 为了符合规则，把一些本来合理的 6px、10px 也强行改成 4 或 8，反而破坏了视觉节奏。后来我放宽了规则，允许一些例外值，生成质量反而更好了。

还有一点，浏览器扩展的实时校验，在开发阶段很有用，但在生产环境不要开。它会增加页面负担，而且用户也不需要看到这些标记。impeccable 的扩展支持按环境开关，记得在构建生产版本时关掉。

最后分享一个小技巧：如果你在用 codex cli 生成组件，可以在提示词里加上“参考项目里已有的组件样式”，然后让 impeccable 把现有组件的样式令牌提取出来，一并注入。这样生成的组件，跟项目里已有的组件风格会更一致。这个做法我试了几次，效果比单纯注入规则要好。