企业官网建设流程全解析

1. 从"impeccable"说起：一个被低估的前端质量命题

第一次看到"impeccable"这个词，是在给团队做代码评审规范的时候。它的中文意思是"无可挑剔的、完美的"，放在前端开发语境里，这个词其实指向了一个非常具体、也非常难做到的目标——让 AI 编码代理（AI coding agents）产出的前端代码，达到真正无可挑剔的质量水准。

这两年 AI coding agents 的爆发式增长，大家有目共睹。从终端里的 CLI 工具到浏览器扩展，从代码补全到整页生成，工具链已经相当成熟。但真正在一线写过前端的人都知道，AI 生成的代码"能跑"和"能上线"之间，隔着一条巨大的鸿沟。样式能渲染，但响应式一塌糊涂；组件能显示，但无障碍属性全缺；逻辑能走通，但边界条件一个没处理。这就是"impeccable"这个命题要解决的核心问题：不是让 AI 写出代码，而是让 AI 写出经得起推敲的前端代码。

这篇文章适合三类人看：一是正在把 AI coding agents 引入日常前端工作流的工程师，二是负责制定团队代码质量标准的 Tech Lead，三是对 CLI 工具链和浏览器扩展协同工作方式感兴趣的技术爱好者。我会从整体设计思路、核心细节、实操流程、问题排查四个维度，把"如何让 AI 前端产出达到 impeccable 标准"这件事讲透。文中涉及的工具选型、参数配置、检查清单，都是基于常见工程实践做的合理补全，你可以直接拿去改改用。

2. 整体设计思路：为什么"impeccable"要靠工具链协同来实现

2.1 单一工具做不到 impeccable 的根本原因

很多人对 AI coding agents 有个误解，觉得只要模型够强，代码质量自然就上去了。实际用下来完全不是这么回事。我拿同一个组件需求分别测过纯 CLI 生成、纯浏览器扩展生成、以及两者配合的方式，结果差异非常明显。

纯 CLI 工具（比如在终端里跑的 codex cli 这类）的优势是上下文完整、能读写文件、能跑构建命令，但它对"视觉结果"是盲的。它不知道生成的 CSS 在 375px 宽度下会不会溢出，不知道按钮的对比度够不够。纯浏览器扩展的优势是能看到真实渲染结果、能读取 DOM 和计算样式，但它对项目整体结构、构建配置、依赖关系是陌生的，改出来的东西经常和现有代码风格打架。

所以"impeccable"的第一层设计思路就清楚了：让 CLI 负责结构、逻辑、构建层面的正确性，让浏览器扩展负责视觉、交互、无障碍层面的验证，两者通过统一的检查标准串起来。这不是简单的工具叠加，而是要设计一套让它们互相校验的机制。

2.2 三层质量门禁的设计逻辑

我把这套方案拆成三层门禁，每一层拦截不同类别的问题，这样排查起来定位快，也不会让某一层负担过重。

这个分层的关键在于每一层都有明确的通过标准，而不是靠人肉感觉。比如第一层的标准就是 linter 零 error、零 warning；第二层的标准是三个断点（移动端、平板、桌面）截图无异常、axe 无障碍扫描无 critical 问题；第三层的标准是构建产物 gzip 后不超过预设阈值。

提示：三层门禁不要一次性全上，新手建议先把第一层跑通，稳定运行一周后再加第二层。一次性全上会导致问题定位困难，反而拖慢节奏。

2.3 为什么选择 CLI 优先、扩展兜底的顺序

这里有个顺序问题值得展开说。我试过两种流程：一种是先用浏览器扩展生成，再用 CLI 整理；另一种是先用 CLI 生成骨架，再用扩展验证。实测下来CLI 优先的顺序明显更稳。

原因在于，CLI 工具在生成阶段就能把项目上下文吃进去——它能读到你的 tailwind 配置、你的组件库约定、你的路径别名。这样生成出来的代码天然就贴合项目风格，后续扩展验证时改动量小。反过来如果先让扩展生成，它往往吐出一堆内联样式和硬编码值，CLI 再去重构的成本极高，而且容易引入回归。

这个顺序背后其实是一个朴素的工程原则：结构性问题要在源头解决，视觉性问题要在末端验证。把顺序搞反，就等于让装修队先刷墙再改水电，返工是必然的。

3. 核心细节解析：让 AI 产出达到 impeccable 的关键控制点

3.1 上下文注入：决定生成质量的第一变量

AI coding agents 的产出质量，七成取决于你喂给它的上下文。我见过太多人直接甩一句"帮我写个登录页"就完事，然后抱怨 AI 写得烂。这不是 AI 的问题，是上下文给得太少。

一个 impeccable 级别的上下文注入，至少要包含四类信息。第一类是项目技术栈声明，明确告诉它用的是 React 还是 Vue、Tailwind 还是 CSS Modules、TypeScript 严格模式开没开。第二类是设计令牌（design tokens），把颜色、间距、圆角、字号的变量表贴进去，这样它就不会自己瞎编数值。第三类是现有组件示例，挑两三个写得规范的组件作为风格参照。第四类是约束条件，比如"不要引入新依赖""必须支持键盘导航""移动端优先"。

在 CLI 工具里，这些信息可以通过项目根目录的配置文件持久化。我习惯建一个.ai-context目录，里面放stack.md、tokens.json、examples/、constraints.md四个文件，每次生成前让 CLI 读取。这样不用每次重复粘贴，也保证了团队内所有人用的是同一套上下文。

3.2 提示词结构：从"描述需求"到"定义验收标准"

普通提示词和 impeccable 级提示词的最大区别，在于是否包含验收标准。普通提示词是"做一个带搜索的表格"，impeccable 级提示词是"做一个带搜索的表格，验收标准：搜索输入 300ms 防抖、空结果有占位提示、键盘上下键可切换行、屏幕阅读器能读出结果数量"。

把验收标准写进提示词，好处是 AI 在生成时就会主动考虑这些边界，而不是等你测出来再返工。我整理了一个提示词模板，实测下来能显著减少返工次数：

## 任务 [一句话描述要做什么] ## 技术约束 - 框架/版本： - 样式方案： - 禁止引入的依赖： ## 验收标准 - [ ] 功能点1（含边界条件） - [ ] 功能点2（含边界条件） - [ ] 无障碍要求 - [ ] 响应式断点要求 ## 参考示例 [贴1-2个现有组件代码]

这个模板的核心是把"做完"和"做对"分开定义。功能点描述做完，验收标准描述做对。AI 拿到这种结构，产出的完整度会高一个档次。

3.3 浏览器扩展的验证维度：不止是"看起来对"

浏览器扩展在 impeccable 流程里的角色，很多人只用到"截图看看"这一层，太浪费了。一个成熟的扩展验证流程，应该覆盖五个维度。

布局维度：在 375px、768px、1440px 三个宽度下截图，检查是否有横向滚动条、元素重叠、文字截断。交互维度：模拟 Tab 键遍历，检查焦点顺序是否合理、焦点样式是否可见。无障碍维度：跑一遍 axe 或类似工具，重点看对比度、ARIA 标签、表单关联。性能维度：看首屏渲染时间、布局偏移（CLS）。一致性维度：和设计稿或现有页面比对，检查间距、颜色、字号是否用了令牌值。

这五个维度里，交互和无障碍是最容易被忽略、也最能体现 impeccable 的。我踩过的坑是：一个看起来完美的下拉菜单，键盘用户根本打不开，因为触发元素是个 div 而不是 button，没有 tabindex。这种问题截图看不出来，只有实际用键盘走一遍才会暴露。

3.4 命名与结构规范：AI 最容易翻车的地方

AI 生成的代码在命名上有个通病：要么过度通用，要么过度冗长。比如handleClick、data、item这种通用名满天飞，或者handleUserProfileSettingsSubmitButtonClick这种长到没法读的。

解决这个问题不能靠事后改，要在上下文里就把命名规范写死。我的做法是提供一份命名对照表，明确告诉 AI 什么场景用什么前缀。比如事件处理函数统一on开头（onSubmit、onToggle），布尔值统一is/has/can开头（isLoading、hasError、canEdit），异步函数统一动词开头（fetchUser、updateProfile）。

结构规范同理。组件文件放哪、样式文件放哪、测试文件放哪、类型定义放哪，这些都要在上下文里约定清楚。否则 AI 会按它自己的"直觉"放，十个组件能给你放出五个不同的目录结构。

4. 实操过程：从零搭一套 impeccable 工作流

4.1 环境准备与 CLI 工具初始化

先把基础环境搭起来。假设你用的是 Node 生态，核心依赖是 CLI 工具本身加上 lint 和格式化工具。安装命令大致如下：

# 安装核心 CLI 工具（以常见包管理为例） npm install -g <your-cli-tool> # 项目内安装质量工具 npm install -D eslint prettier stylelint @axe-core/cli # 初始化配置文件 npx eslint --init npx stylelint --init

安装完之后，第一件事是配置 CLI 工具的上下文读取路径。大多数 CLI 工具支持通过配置文件指定上下文目录，你需要把前面提到的.ai-context目录挂上去。这一步的具体配置项因工具而异，但核心逻辑是一样的：让工具在每次启动时自动加载上下文，而不是每次手动喂。

注意：CLI 工具的版本更新比较频繁，命令参数可能变化。建议在项目里锁定版本号，避免团队成员之间因为版本差异导致行为不一致。

环境准备好之后，先跑一个最小验证：让 CLI 生成一个最简单的按钮组件，看它是否读取到了你的设计令牌。如果生成的按钮颜色、圆角、内边距都符合令牌值，说明上下文注入成功；如果它自己编了一套数值，说明配置没生效，回去检查路径。

4.2 浏览器扩展的安装与权限配置

浏览器扩展这块，安装本身没什么难度，关键是权限配置要克制。很多扩展默认申请一堆权限，实际上你只需要它读取当前页面 DOM 和截图的能力。权限给多了，一是安全风险，二是有些扩展会因为权限过宽而在某些页面上被限制。

安装后建议做三件事。第一，配置截图断点，把 375/768/1440 三个宽度预设好，一键切换。第二，配置无障碍扫描规则，把 axe 的规则集调成 WCAG 2.1 AA 级别，太严格会报一堆噪音，太松又漏问题。第三，配置导出格式，让验证结果能导出成 markdown 或 json，方便贴进 PR 描述里。

这里有个实操心得：扩展的验证结果不要只看"通过/不通过"，要看具体条目。有时候一个 critical 问题背后是同一个根因，比如所有对比度问题都源于你用了同一个灰色令牌。看条目能帮你找到根因，一次性修掉。

4.3 完整生成流程：一个真实组件的走查

我拿一个"带筛选的用户列表"组件走一遍完整流程，你能看到每一步在干什么。

第一步，写提示词。按 3.2 的模板，把任务、约束、验收标准、参考示例都填上。验收标准我列了六条：筛选输入防抖、空状态提示、加载骨架屏、键盘可操作、屏幕阅读器可读、三个断点布局正常。

第二步，CLI 生成骨架。把提示词喂给 CLI，让它生成组件文件、样式文件、类型定义。生成后先跑 lint，把语法和类型问题清掉。这一步通常能拦下 60% 的低级问题。

第三步，本地预览。启动 dev server，在浏览器里打开。这时候先别急着看视觉效果，先用键盘走一遍——Tab 能不能进筛选框、能不能切到列表项、Esc 能不能清空。键盘走通了，再上扩展做视觉验证。

第四步，扩展验证。切三个断点截图，跑无障碍扫描，检查对比度和 ARIA。把发现的问题记下来，回到 CLI 让 AI 修。修完再验证，循环到全部通过。

第五步，提交前检查。跑构建，看产物大小；跑完整测试套件；检查命名和目录结构是否符合规范。全过了再提交。

这个流程走下来，一个中等复杂度组件大概需要 20-30 分钟，比纯手写快不了太多，但质量稳定性高很多，尤其是无障碍和响应式这两块，手写很容易漏。

4.4 参数计算：构建产物阈值怎么定

第三层门禁里有个"构建产物大小"的检查，这个阈值不能拍脑袋定，要算。方法是：先统计当前项目所有页面的产物大小，取中位数作为基线，然后给新组件设一个不超过基线 15% 的预算。

举个例子，假设你项目里一个典型页面的 JS 产物 gzip 后是 80KB，那新组件的预算就是 92KB。超过这个数就要检查是不是引入了不必要的依赖，或者有没有把整个图标库打进来。这个 15% 不是随便定的，是根据经验——单个组件的合理增量通常在 5%-15% 之间，超过 15% 基本可以确定有问题。

CSS 产物同理，但阈值可以放宽到 20%，因为样式复用性高，单个组件的增量占比会大一些。

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

5.1 生成结果与项目风格不符怎么办

这是最高频的问题。AI 生成的代码能跑，但一看就不是你项目的风格——缩进不对、引号风格不对、组件写法不对。根因通常是上下文里的示例不够有代表性。

排查思路：先检查你提供的参考示例是不是项目里"最规范"的那几个。很多人随手挑了两个文件，结果那两个本身就是历史遗留的烂代码，AI 照着学当然学歪。正确做法是挑最近重构过、经过评审的组件作为示例。

如果示例没问题但还是不符，那就是约束条件写得太模糊。把"遵循项目风格"改成具体的"使用函数式组件 + hooks、样式用 CSS Modules、导出用命名导出"，AI 就有明确目标了。

5.2 无障碍扫描报一堆问题怎么分级处理

axe 扫描出来的问题分 critical、serious、moderate、minor 四级。新手容易犯的错是想一次性全修，结果改到崩溃。我的建议是分级处理：

critical 和 serious 必须阻塞提交，因为这两级通常影响真实用户使用。moderate 和 minor 可以记录到技术债清单里，按迭代节奏处理。这样既保证了底线，又不至于让团队被无障碍问题拖垮节奏。

5.3 CLI 工具和扩展结果冲突怎么判断

偶尔会遇到 CLI 说没问题、扩展说有问题的情况。比如 CLI 生成的代码 lint 全过，但扩展扫描出对比度不足。这种冲突不是 bug，而是两层门禁关注点不同导致的正常现象。

判断原则很简单：结构问题信 CLI，视觉问题信扩展。对比度、间距、布局这类只有渲染后才能确定的问题，以扩展结果为准；语法、类型、依赖这类静态可分析的问题，以 CLI 结果为准。两者都报的问题，优先修，因为那通常是真问题。

5.4 常见问题速查表

5.5 几个踩过坑才懂的实操心得

第一个心得：别在提示词里写"尽量""最好"这类词。AI 对模糊词的处理是随机的，你说"尽量支持键盘"，它可能支持也可能不支持。要说"必须支持键盘导航，Tab 顺序为……"。

第二个心得：验证结果要存档。每次扩展验证的截图和扫描报告，按组件名和日期存起来。这样当后续改动引入回归时，你能快速对比出是哪次改动导致的。

第三个心得：CLI 的上下文文件要版本控制。.ai-context目录一定要进 git，这样团队所有人的生成行为才一致。我见过有团队把这个目录加到 gitignore 里，结果每个人生成的代码风格都不一样，评审时吵得不可开交。

第四个心得：定期回顾被拦截的问题。每周花十分钟看看这周被三层门禁拦下的问题都是什么类型，如果某一类问题反复出现，说明上下文或规范需要更新，而不是每次都靠门禁拦。

6. 工具链选型与扩展思路

6.1 CLI 工具选型的三个考量维度

市面上的 CLI 工具很多，选型时我主要看三个维度。上下文管理能力是第一位的，能不能持久化上下文、能不能按项目隔离，直接决定了生成质量。可脚本化程度是第二位的，能不能被 CI 调用、能不能输出结构化结果，决定了它能不能融入自动化流程。社区活跃度是第三位的，工具更新快意味着问题修复快，但也意味着 API 可能不稳定，要权衡。

这三个维度里，我个人的优先级是上下文管理 > 可脚本化 > 社区活跃度。因为前两个直接决定日常使用体验，第三个更多是长期风险。

6.2 浏览器扩展的替代方案

如果你不想装扩展，其实有替代方案。可以用 Playwright 或 Puppeteer 写脚本，在无头浏览器里做截图和无障碍扫描。好处是完全可脚本化、能进 CI，坏处是配置成本高、调试不如扩展直观。

我的建议是：日常开发用扩展，快速反馈；CI 里用脚本，保证每次提交都过一遍。两者用同一套检查规则，结果才能对齐。这套组合用下来，基本能覆盖从开发到集成的全流程。

6.3 后续可以扩展的方向

这套工作流跑顺之后，有几个方向可以继续深挖。一是把验证结果接入 PR 流程，让每次 PR 自动跑三层门禁，不通过就阻塞合并。二是建立组件质量档案，记录每个组件的验证历史和问题模式，为后续生成提供更精准的上下文。三是把设计令牌和验证规则打通，让令牌变更时自动触发相关组件的重新验证。

我个人在实际操作中的体会是，impeccable 这个目标本身不是终点，而是一个持续逼近的过程。工具会更新，规范会演进，但"结构在源头保证、视觉在末端验证、问题分级处理"这个核心逻辑是稳定的。把这套逻辑跑通，比追任何一个具体工具都重要。最后再分享一个小技巧：每次引入新工具或新规则时，先在一个小模块上试跑两周，确认稳定了再推广到全项目，这样能把试错成本控制在最小范围。