企业官网建设流程全解析

1. 从“impeccable”说起：一个被低估的前端质量关键词

第一次看到“impeccable”这个词，是在一个前端项目的代码审查清单里。当时团队里有个从设计转前端的同事，每次提交PR之前都会在描述里写一句“impeccable check done”。我一开始以为是什么内部工具的名字，后来才发现，这就是字面意思——无可挑剔的检查。这个词在AI coding agents和frontend design的圈子里，正在变成一个非正式的品质标签，代表的是那种“一眼看过去没有毛病”的前端实现。

为什么这个词值得单独拿出来聊？因为现在AI coding agents的普及速度太快了。你打开任何一个技术社区，都能看到有人在讨论codex cli怎么安装、codex cli有哪些命令、/compact和/model怎么用。CLI工具正在成为前端开发者的日常入口，而browser extension则把这种能力直接嵌进了浏览器。当生成代码的成本趋近于零的时候，真正的瓶颈就变成了：你怎么判断生成出来的东西是不是impeccable的？

这篇文章想做的事情很具体：把“impeccable”这个模糊的品质概念，拆解成一套可操作、可复现的前端质量检查流程。我会聊到CLI工具链的选型思路、AI coding agents在前端场景下的实际表现、browser extension的辅助验证方法，以及我自己在项目里踩过的坑。不管你是刚接触codex cli的新手，还是已经在用openspec cli做规范驱动开发的老手，应该都能从里面找到能直接抄作业的东西。

适合读这篇内容的人：正在用或准备用AI coding agents做前端开发的人、对CLI工作流感兴趣但不知道从哪开始的人、以及那些觉得“代码能跑就行”但隐隐觉得哪里不对的人。我不打算讲太多理论，重点放在实操步骤和判断标准上。

2. 为什么前端质量需要一套“impeccable”标准

2.1 AI生成代码的“差不多”陷阱

用AI coding agents写前端代码，最危险的不是它写不出来，而是它写出来的东西“看起来没问题”。我试过让几个不同的agent生成同一个组件——一个带搜索过滤和分页的表格。结果很有意思：所有agent都能在第一次输出中给出可运行的代码，但只有不到一半的版本在边界情况下表现正常。比如搜索关键词为空字符串时的行为、分页到最后一页时下一页按钮的状态、快速连续点击过滤条件时的竞态处理。这些东西不会在demo里暴露出来，但上线之后就是bug。

这就是“差不多”陷阱：AI生成的代码在视觉上和功能上都能通过快速验收，但缺少那些让代码真正impeccable的细节。这些细节包括但不限于：加载状态的骨架屏、错误边界的兜底、空状态的友好提示、键盘可访问性、以及响应式断点的平滑过渡。

2.2 CLI工具链带来的质量检查自动化

codex cli这类工具的出现，让质量检查有了自动化的可能。你可以在CI流程里加一步，让agent对生成的代码做一次“impeccable review”。具体做法是：把组件的截图、DOM结构、以及关键交互路径喂给agent，让它从可访问性、响应式、状态管理三个维度给出改进建议。这比人工review快得多，而且不会因为疲劳而漏掉问题。

我自己的做法是在package.json里加一个脚本，叫impeccable:check，它做三件事：跑一遍ESLint和Stylelint、用Playwright截取组件在三个断点下的截图、然后把截图和lint结果一起发给agent做分析。这个流程跑下来大概40秒，但能抓住80%以上的常见问题。

2.3 browser extension作为最后一道防线

browser extension在前端质量检查里的角色很特殊。它能看到真实渲染后的页面，包括那些在单元测试里被mock掉的外部资源加载情况。我常用的一个扩展是能高亮显示所有可交互元素的焦点顺序，另一个是能模拟慢速网络下的加载表现。把这些扩展和AI agent结合起来，就能实现“在真实浏览器环境里做impeccable检查”。

注意：不要过度依赖自动化检查。有些问题——比如动画的流畅度、颜色的视觉舒适度——还是需要人眼判断。自动化能帮你排除硬伤，但“无可挑剔”最终是一个主观标准。

3. 搭建你的impeccable检查工作流

3.1 环境准备：从安装codex cli开始

如果你还没装codex cli，这里有一个我实测下来比较稳的安装路径。node安装codex cli很慢是常见问题，主要是因为默认的npm源在国内访问不稳定。我的做法是先配置一个国内镜像源，然后再安装。

# 查看当前npm源 npm config get registry # 切换到国内镜像（如果还没切的话） npm config set registry https://registry.npmmirror.com # 安装codex cli npm install -g @codex/cli # 验证安装 codex --version

安装完成之后，你需要做一次认证。codex cli的认证流程会引导你进入一个网页，输入从认证应用或browser extension获取的验证码。这一步是必须的，因为agent需要访问你的代码仓库和运行环境。

提示：如果你在团队里使用，建议把认证信息放在环境变量里，不要硬编码在配置文件里。codex cli支持从CODEX_API_KEY环境变量读取认证信息。

3.2 核心命令：/compact、/model、/resume怎么用

codex cli的命令集不算多，但有几个是每天都会用到的。我整理了一个速查表：

/compact是我用得最多的命令。当你和agent讨论一个复杂组件超过20轮之后，上下文会变得很臃肿，响应质量会下降。这时候执行/compact，agent会把之前的对话压缩成摘要，保留关键决策和代码片段，丢弃那些探索性的中间过程。实测下来，压缩之后响应速度能提升30%左右，而且不会丢失重要信息。

/model命令的选择逻辑是这样的：如果你在做架构设计或者复杂的重构，用能力更强的模型；如果只是做格式调整或者简单的代码补全，用轻量模型就够了。我通常会在/model后面不加参数，直接回车，然后从列表里选。

3.3 删除codex cli指令的正确姿势

有时候你需要清理掉一些不再需要的指令或者会话记录。删除codex cli指令不是简单地把命令从历史里删掉，而是要用codex config unset来移除配置项。比如你之前设置了一个自定义的prompt模板，现在不想用了：

# 查看当前所有配置 codex config list # 删除某个配置项 codex config unset custom_prompt_template # 删除所有会话历史（谨慎操作） codex session clear --all

注意：codex session clear --all会删除所有本地会话记录，包括那些你可能还需要参考的。建议先导出重要会话再执行。

4. 前端设计中的impeccable细节清单

4.1 可访问性：那些看不见但必须有的东西

可访问性是impeccable前端设计的底线。我见过太多AI生成的组件，视觉上很漂亮，但用键盘根本操作不了。检查可访问性不需要复杂的工具，浏览器自带的Accessibility面板就够了。重点看三个东西：焦点顺序是否合理、所有可交互元素是否有可见的焦点样式、图片是否有有意义的alt文本。

一个常见的坑是：AI生成的按钮组件经常忘记处理disabled状态下的焦点行为。正确的做法是，当按钮被禁用时，它不应该出现在Tab键的焦点序列里。实现方式有两种：用disabled属性（浏览器会自动处理），或者用aria-disabled="true"配合tabindex="-1"（当你需要保留点击事件用于提示时）。

<!-- 方式一：原生disabled --> <button disabled>提交</button> <!-- 方式二：aria-disabled + tabindex --> <button aria-disabled="true" tabindex="-1" onclick="showTooltip()">提交</button>

4.2 响应式：断点不是越多越好

AI coding agents在生成响应式代码时，倾向于加很多断点。我见过一个组件用了7个断点，从320px到2560px全覆盖。但实际上，大部分项目只需要3到4个断点。断点太多会导致维护成本指数级上升，而且容易出现某个断点下样式错乱的情况。

我的建议是：先确定你的目标设备范围，然后只在这些范围的边界设置断点。比如一个面向桌面端的管理后台，断点可以简化为：小于768px（移动端）、768px到1024px（平板）、大于1024px（桌面）。每个断点下只调整真正需要变化的属性，不要为了“看起来更精细”而过度设计。

4.3 状态管理：加载、空、错误一个都不能少

一个impeccable的组件必须处理四种状态：加载中、有数据、空数据、出错。AI生成的代码经常只处理“有数据”这一种情况。我的检查方法是：在组件里搜索isLoading、isEmpty、hasError这三个变量，如果缺了任何一个，就说明状态处理不完整。

// 一个完整的状态处理示例 function DataTable({ data, isLoading, error }) { if (isLoading) return <Skeleton rows={5} />; if (error) return <ErrorState message={error.message} onRetry={refetch} />; if (!data || data.length === 0) return <EmptyState onAction={openCreateModal} />; return <Table data={data} />; }

提示：空状态不要只写“暂无数据”。一个好的空状态应该告诉用户为什么是空的，以及下一步可以做什么。比如“还没有添加任何项目，点击下方按钮创建第一个项目”。

5. 用AI coding agents做代码审查的实操流程

5.1 准备审查输入：截图、DOM、交互路径

让agent做代码审查，输入的质量决定了输出的质量。我通常准备三样东西：组件在三个断点下的截图（用Playwright自动截取）、组件的DOM结构（用document.querySelector获取）、以及关键交互路径的描述（比如“点击筛选按钮后，表格应该在300ms内更新”）。

// Playwright截图脚本示例 const { chromium } = require('playwright'); async function captureScreenshots(url, outputDir) { const browser = await chromium.launch(); const page = await browser.newPage(); const viewports = [ { name: 'mobile', width: 375, height: 667 }, { name: 'tablet', width: 768, height: 1024 }, { name: 'desktop', width: 1440, height: 900 } ]; for (const vp of viewports) { await page.setViewportSize({ width: vp.width, height: vp.height }); await page.goto(url); await page.screenshot({ path: `${outputDir}/${vp.name}.png`, fullPage: true }); } await browser.close(); }

5.2 审查提示词的设计技巧

给agent的审查提示词不能太笼统。不要说“帮我看看这个组件有什么问题”，而要说“从可访问性、响应式、状态管理三个维度审查这个组件，每个维度列出最多3个具体问题，并给出修改建议”。这样agent的输出会结构化很多，也更容易直接落地。

我常用的提示词模板是这样的：

你是一个资深前端工程师，正在审查一个React组件。 组件代码：[粘贴代码] 截图：[附上三个断点的截图] 交互路径：[描述关键交互] 请从以下维度审查： 1. 可访问性：焦点管理、ARIA属性、键盘操作 2. 响应式：断点合理性、布局稳定性、内容溢出 3. 状态管理：加载/空/错误状态、竞态条件、乐观更新 每个维度列出最多3个问题，每个问题给出具体的代码修改建议。

5.3 审查结果的落地：从建议到提交

agent给出的建议不能直接照搬。我的做法是：先把所有建议按优先级排序，P0是必须改的（比如可访问性硬伤），P1是应该改的（比如状态处理不完整），P2是可以后续优化的（比如代码风格）。然后针对P0和P1的建议，逐条在本地修改并验证。

验证的方式很简单：改完之后重新跑一遍截图脚本，对比修改前后的截图。如果修改涉及交互逻辑，就用Playwright写一个简单的测试用例来验证。这个过程看起来繁琐，但比上线之后被用户发现问题的成本低得多。

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

6.1 codex cli安装失败怎么办

node安装codex cli很慢或者直接失败，最常见的原因是网络问题。除了切换npm源之外，还可以尝试用--verbose参数查看详细日志，定位卡在哪一步。

npm install -g @codex/cli --verbose

如果卡在fetch阶段，说明是网络问题；如果卡在postinstall阶段，可能是权限问题，试试用sudo或者检查npm的全局目录权限。

6.2 agent生成的代码总是差一点意思

这个问题很普遍。我的经验是：不要指望一次生成就完美。把任务拆小，每次只让agent处理一个具体的点。比如不要让它“生成一个完整的表单”，而是让它“生成表单的验证逻辑”，然后单独让它“生成表单的UI布局”。拆得越细，生成质量越高。

另外，给agent提供参考代码也很重要。如果你项目里已经有一个写得不错的组件，把它作为示例喂给agent，让它按照同样的风格生成新组件。这比任何提示词都管用。

6.3 browser extension和CLI工具冲突

有时候browser extension会拦截CLI工具发出的请求，导致认证失败或者响应超时。排查方法是：先禁用所有扩展，看问题是否消失。如果消失了，再逐个启用，定位是哪个扩展的问题。常见的冲突来源是广告拦截类扩展和隐私保护类扩展，它们可能会把CLI工具的本地请求当成可疑流量。

提示：如果确认是某个扩展的问题，可以在该扩展的设置里把localhost和127.0.0.1加入白名单。

6.4 会话恢复后上下文丢失

/resume命令恢复会话时，有时候会丢失部分上下文，导致agent“忘记”之前讨论过的决策。这种情况通常发生在会话被压缩过之后。我的应对方法是：在恢复会话后，先手动把关键决策重新说一遍，比如“我们之前决定用React Query做数据获取，用Zustand做状态管理，现在继续讨论表格组件的分页逻辑”。这样agent就能快速回到正确的上下文里。

7. 把impeccable变成团队习惯

7.1 在CI里加一道impeccable检查

个人做impeccable检查容易偷懒，但放到CI里就变成了硬性要求。我的做法是在GitHub Actions里加一个job，跑三件事：ESLint + Stylelint、Playwright截图对比、agent审查。只有这三步都通过，PR才能合并。

# .github/workflows/impeccable.yml name: Impeccable Check on: [pull_request] jobs: check: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - run: npm ci - run: npm run lint - run: npm run test:screenshots - run: npm run impeccable:review

7.2 建立团队的impeccable清单

每个团队对“无可挑剔”的定义不一样。我建议团队一起讨论，列出一份自己的impeccable清单。清单不用太长，10到15条就够了。比如：所有图片必须有alt文本、所有表单必须有错误提示、所有异步操作必须有加载状态、所有颜色对比度必须达到WCAG AA标准。这份清单就是代码审查时的检查表。

7.3 定期回顾agent的审查记录

agent的审查记录是一个很好的学习材料。每隔一段时间，把agent给出的高频问题整理一下，看看哪些问题是反复出现的。如果某个问题出现了三次以上，就说明它应该被加入到团队的impeccable清单里，或者应该写一个lint规则来自动检测。

我个人在实际操作中的体会是，impeccable不是一个终点，而是一个持续改进的过程。每次你觉得“这次应该没问题了”，总会有新的边界情况冒出来。但正是这种对细节的坚持，让前端代码从“能跑”变成“值得信赖”。最后分享一个小技巧：把agent的审查提示词保存成一个代码片段，每次用的时候直接粘贴，省去重新组织语言的时间。这个习惯帮我节省了不少精力，也让审查质量更稳定。