1. 当“impeccable”成为前端交付的硬指标第一次看到“impeccable”这个词被拿来形容前端代码是在一个做设计系统的朋友嘴里。他说他们团队现在评审页面不看“能不能跑”而是看“够不够 impeccable”——像素对齐、间距节奏、状态覆盖、暗色模式、键盘可达性任何一项掉链子这个页面就打回去重做。这个词本身的意思是“无可挑剔的、完美的”放在前端语境里它其实指向一个很具体的东西交付质量的下限被抬高了。过去我们做前端验收标准往往是“功能正常、主流浏览器不崩”。但现在不一样了AI coding agents 开始大量参与页面生成CLI 工具能一句话吐出整页组件浏览器扩展能实时审查 DOM 和样式交付的“量”被瞬间拉满可“质”反而成了瓶颈。你让一个 agent 生成十个卡片组件它可能十个的圆角、阴影、hover 状态都不一样。这时候“impeccable”就不再是形容词而是一套可执行的检查清单。这篇内容我想聊的就是围绕 impeccable 这个目标怎么把 AI coding agents、CLI 工具链和浏览器扩展串成一条真正能落地的前端质量流水线。不管你是刚接触 codex cli 安装的新手还是已经在用 zcode cli 做日常开发的老手这里面的思路和踩坑记录应该都能对上你的场景。核心就一件事让“无可挑剔”从口号变成可复现的工程动作。2. 拆解 impeccable 在前端语境下的四层含义2.1 视觉一致性不是好看是“处处一样”很多人把 impeccable 理解成“设计得漂亮”这是个误区。漂亮是主观的impeccable 是客观的。它首先要求的是一致性同一个设计系统里按钮的圆角只有一套值间距只有一套刻度阴影只有一套层级。我见过太多项目主色定义了#3B82F6结果某个页面里手写了个#3b82f6大小写不一致主题切换的时候直接漏掉。这种问题人眼很难逐页发现但浏览器扩展可以。你打开 DevTools用扩展扫一遍所有元素的 computed style把颜色值、圆角值、字号值聚合成频次表那些只出现一两次的“孤儿值”就是嫌疑犯。实测下来一个中等规模的页面孤儿颜色值通常有 5 到 15 个孤儿间距值更多。这些就是 impeccable 的第一层敌人。2.2 状态覆盖默认态只是冰山一角一个组件“看起来没问题”往往只是默认态没问题。真正 impeccable 的组件要覆盖 hover、focus、active、disabled、loading、error、empty 至少七种状态。我做过一个统计团队里被退回的组件80% 的问题出在非默认态focus 没有可见轮廓、disabled 还能点、loading 时布局跳动、error 文案溢出容器。AI coding agents 生成组件时默认态通常写得像模像样但状态覆盖经常偷懒。这时候你需要一个明确的检查协议让 agent 按清单输出而不是靠它“自觉”。后面我会给一份可以直接喂给 agent 的状态清单模板。2.3 可达性键盘和读屏器说了算可达性accessibility是 impeccable 里最容易被忽略、但一旦缺失就最致命的一层。tab 键能不能走通、focus 顺序是否符合视觉顺序、aria 标签是否准确、对比度是否达标这些用鼠标点一遍是发现不了的。浏览器扩展在这里的价值极大比如用 axe 类的审查工具跑一遍能直接列出违规项和对应的 DOM 节点。我个人的经验是可达性问题里最常见的是对比度不足和缺少可见 focus 样式。前者是因为设计师选色时只看视觉效果没算对比度比值后者是因为很多 CSS reset 直接把 outline 干掉了却没给替代方案。这两个问题都能通过扩展自动化检出不需要人工逐个试。2.4 代码可维护性impeccable 的隐藏维度最后一层是代码本身。一个页面视觉上无可挑剔但 class 名全是div1、div2样式全靠!important堆那它离 impeccable 还差得远。可维护性包括命名是否有语义、样式是否复用、是否有魔法数字、组件边界是否清晰。这一层 CLI 工具能帮上忙比如用 lint 规则扫描硬编码颜色、扫描未使用的样式、扫描过深的嵌套选择器。把这四层合起来看impeccable 其实是一个多维度的质量门禁而不是单一的美学标准。理解了这一点后面的工具链搭建才有方向。3. AI coding agents 在 impeccable 流程里该站什么位置3.1 别让 agent 做它不擅长的事很多人对 AI coding agents 的期待是“一句话生成整个页面”然后发现生成的东西离 impeccable 差得远就得出结论说 agent 不好用。问题不在 agent在于任务粒度。让 agent 从零设计一个页面的视觉体系它大概率会给你一堆看起来还行但处处不一致的东西但如果你把任务拆成“按照这份 token 表生成一个按钮组件的七种状态”它的表现会好很多。我的做法是agent 负责生成和补全人负责定义约束和验收。约束包括设计 token、组件 API、状态清单、命名规范验收包括视觉走查、可达性扫描、lint 检查。agent 在这个框架里干活产出质量会稳定得多。3.2 给 agent 的提示词要带“验收标准”普通提示词是“帮我写一个卡片组件”impeccable 提示词应该是“帮我写一个卡片组件要求圆角使用 token--radius-md间距使用--space-4的倍数必须覆盖 hover/focus/disabled 三态focus 必须有 2px 可见轮廓所有颜色引用 token 不得硬编码输出后附上你覆盖了哪些状态的自检清单”。最后那句“附上自检清单”很关键。它逼着 agent 在生成时对照标准而不是生成完就交差。实测下来加了自检要求的产出状态覆盖率能从 40% 左右提升到 85% 以上。剩下的 15% 靠人工和扩展兜底。3.3 agent 产出的“可疑信号”清单用久了你会发现agent 生成的前端代码有一些高频可疑信号看到就要警惕可疑信号背后的问题处理方式硬编码颜色值未使用设计 token全局搜索替换为 tokenoutline: nonefocus 可达性缺失补可见 focus 样式固定 px 间距未使用间距刻度换算为 token 倍数缺少 disabled 样式状态覆盖不全按清单补齐内联 style样式不可复用抽到 class 或 token深层嵌套选择器可维护性差扁平化或改 BEM这份清单可以直接作为 code review 的检查项也可以反过来喂给 agent 作为生成约束。3.4 多 agent 协作时的“风格漂移”问题如果你同时用多个 agent 或者多个会话生成同一个项目的不同页面很容易出现风格漂移A 会话生成的按钮圆角是 6pxB 会话生成的是 8px。原因是每个会话的上下文里没有统一的 token 约束。解决办法是把设计 token 抽成一个独立的、agent 每次都要读取的文件比如design-tokens.json或tokens.css在提示词里明确要求“所有样式必须引用该文件中的变量”。这样即使 agent 换了约束还在。4. CLI 工具链把 impeccable 检查变成一条命令4.1 为什么 CLI 是质量流水线的骨架浏览器扩展适合交互式排查但它的短板是不可自动化。你没法在 CI 里跑一个扩展也没法让它在每次提交时自动执行。CLI 工具正好补上这块它可以在本地、在 pre-commit hook、在 CI 流水线里跑把 impeccable 的检查变成可重复、可阻断的动作。围绕前端质量我常用的 CLI 能力包括样式 lint、可达性扫描headless 方式、构建产物分析、依赖体积检查。这些工具组合起来基本能覆盖前面说的四层含义里的三层视觉一致性、可达性、可维护性状态覆盖那层还是得靠人工和 agent 自检。4.2 codex cli 安装与基础配置的实操记录codex cli 是很多人接触 AI 辅助编码的入口工具。安装本身不复杂但有几个细节容易卡住。以常见的安装方式为例# 通过包管理器安装具体包名以官方文档为准 npm install -g codex-cli-package # 验证安装 codex --version # 首次配置通常需要设置 API 凭据 codex config set api-key your-key安装完之后第一件要做的事不是马上生成代码而是配置项目级的约束文件。我一般会在项目根目录放一个AGENTS.md或类似的约定文件里面写清楚设计 token 在哪、命名规范是什么、状态清单有哪些、禁止硬编码颜色。codex cli 在生成时会读取这个文件产出质量会明显不同。提示安装过程中如果遇到权限报错优先检查全局安装目录的写权限而不是直接加 sudo。用 sudo 装全局包容易导致后续权限混乱。4.3 zcode cli 与 codex cli 的分工思路zcode cli 和 codex cli 这类工具功能上有重叠但使用场景可以分工。我的习惯是codex cli 负责“生成和补全”zcode cli 负责“审查和重构”。比如让 codex 生成一个新组件然后用 zcode 跑一遍样式审查找出硬编码值和状态缺失再让 codex 按审查结果修复。这个“生成—审查—修复”的循环比单次生成的质量高出一大截。这种分工的关键在于审查工具要输出结构化的结果最好是 JSON 或明确的文件行号列表这样修复阶段的 agent 才能精准定位。如果审查结果只是一段自然语言描述agent 修复时容易跑偏。4.4 把检查串成 pre-commit 钩子单次手动跑检查容易忘最好的办法是挂到 git 的 pre-commit 钩子上。一个简化的钩子脚本大概长这样#!/bin/sh # .git/hooks/pre-commit echo 运行样式 lint... npx stylelint src/**/*.css || exit 1 echo 运行可达性扫描... npx a11y-cli-tool --url http://localhost:3000 || exit 1 echo 检查硬编码颜色... grep -rn #[0-9a-fA-F]\{6\} src/ echo 发现硬编码颜色请改用 token exit 1 echo 检查通过这个脚本里硬编码颜色的检查用最简单的 grep 就能做不需要复杂工具。关键是让不合格的提交根本进不了仓库而不是等到 code review 才发现。实测下来挂了钩子之后团队里硬编码颜色的问题减少了 90% 以上。4.5 CLI 检查的常见误报与处理CLI 工具不是万能的误报很常见。比如可达性扫描工具会把一些动态生成的、扫描时还没渲染出来的元素报成违规样式 lint 会把一些刻意的例外报成错误。处理原则是误报要显式豁免而不是关掉整条规则。大多数工具都支持行内注释豁免比如/* stylelint-disable-next-line */ .special-case { color: #ff0000; }但豁免要克制每加一个豁免都应该有理由。如果某个规则被豁免了十几次那说明规则本身或者代码结构有问题该反思的是设计不是继续加豁免。5. 浏览器扩展实时审查与人工走查的放大器5.1 扩展能看到的是 CLI 看不到的“运行时真相”CLI 扫描的是源码和构建产物但页面真正跑起来之后的样子只有浏览器知道。比如某个元素的最终 computed style 是什么、focus 顺序实际怎么走、动态加载的内容有没有可达性问题、暗色模式切换后对比度还够不够。这些都需要浏览器扩展在运行时介入。我常用的扩展类型有三类样式审查类看 computed style、看 token 使用情况、可达性审查类跑 axe 规则、看对比度、布局审查类看间距、看对齐、看溢出。这三类配合起来基本能把视觉一致性和可达性问题在开发阶段就抓出来。5.2 用扩展做“token 使用审计”设计 token 定义了但代码里用没用、用对没用扩展可以帮你审计。思路是在页面上遍历所有元素读取它们的颜色、圆角、间距等属性和 token 表做比对列出所有不在 token 表里的值。这个操作手动做几乎不可能但扩展跑一遍几秒钟就出结果。我做过一次这样的审计一个看起来挺规整的页面扫出来 23 个非 token 颜色值、41 个非 token 间距值。这些值单看都“差不多”但累积起来就是视觉不一致的根源。修完之后页面的“整齐感”提升非常明显虽然用户说不清哪里变了。5.3 键盘走查扩展替代不了的那部分有一点必须说清楚扩展能自动化很多检查但键盘走查替代不了。tab 顺序是否合理、focus 是否可见、模态框打开后焦点是否被正确捕获、关闭后是否回到触发元素这些需要人真的用键盘走一遍。我的习惯是每个页面交付前拔掉鼠标纯键盘操作一遍核心流程。这个过程通常能发现 2 到 3 个扩展没报出来的问题。扩展和人工走查的关系是扩展负责广度覆盖所有元素、所有规则人工负责深度真实操作流程、真实使用场景。两者缺一不可。5.4 扩展配置的团队同步问题浏览器扩展的配置是存在本地的团队里每个人装的扩展、开的规则可能都不一样这就导致“我这边没问题你那边报一堆”。解决办法是把扩展的规则配置导出成文件纳入版本管理。很多审查类扩展支持导入导出配置把配置文件放到项目里新人入职时导入一次检查标准就统一了。这个细节看起来小但对团队协作影响很大。标准不统一讨论就会变成“你的工具是不是有问题”而不是“这个页面到底有没有问题”。6. 一套可复现的 impeccable 交付流程6.1 从 token 定义开始而不是从页面开始很多团队做页面的顺序是先画页面再抽 token。这个顺序是反的也是视觉不一致的根源。impeccable 的流程应该从token 定义开始颜色、间距、字号、圆角、阴影、动效时长全部先定好形成一份tokens文件。之后所有页面、所有组件、所有 agent 生成都引用这份文件。token 的粒度要适中。太粗只有主色和辅色覆盖不了场景太细每个组件一套又失去复用意义。我的经验是颜色分语义层primary、danger、success和中性层背景、边框、文字间距用 4px 或 8px 的倍数刻度字号用有限的几档。这套定下来后面就省心了。6.2 组件开发agent 生成 人工补状态有了 token组件开发就可以半自动化。流程是人写好组件的 API 和状态清单agent 按清单生成初版人再补上 agent 漏掉的状态和边界情况。状态清单我一般这么写默认态正常显示hover 态背景或边框有可见变化focus 态2px 可见轮廓颜色对比度达标active 态按下时有反馈disabled 态降低透明度禁用指针事件loading 态有加载指示布局不跳动error 态有错误提示提示不溢出把这份清单直接贴进提示词agent 的产出会完整很多。剩下的边界情况比如超长文案、空数据、极端窄屏还是得人工补。6.3 页面组装后的三层检查页面组装完跑三层检查CLI 层样式 lint、硬编码检查、可达性 headless 扫描扩展层token 使用审计、对比度检查、布局溢出检查人工层键盘走查、暗色模式走查、极端内容走查这三层跑完基本能覆盖 impeccable 的绝大部分要求。每层检查发现的典型问题我都整理过前面表格里那些就是高频项。6.4 把检查结果反哺给 agent 形成闭环检查发现的问题不要手动一个个改而是把结构化结果喂回给 agent 批量修复。比如扩展导出了一份“非 token 颜色值”列表直接把这个列表和对应的 token 映射喂给 agent让它批量替换。这个闭环跑顺了修复效率比手动高一个数量级。闭环的关键是结果要结构化。自然语言的检查报告 agent 不好用JSON 或 CSV 格式的列表它处理起来很准。所以选工具时优先选那些支持结构化输出的。7. 踩过的坑与实测有效的经验7.1 过度依赖 agent 导致“看起来对但处处不对”早期我试过完全放手让 agent 生成整个页面结果就是前面说的单看每个组件都还行放一起就露馅。圆角不一致、间距不统一、状态覆盖参差。后来改成“token 先行 清单约束 人工验收”质量才稳定下来。agent 是放大器不是替代品这个认知很重要。7.2 扩展装太多反而拖慢浏览器有段时间我装了一堆审查扩展结果浏览器卡得没法用。后来精简到三类各一个够用就行。扩展不是越多越好覆盖核心检查项即可重复功能的扩展只会互相干扰。7.3 对比度检查不能只看工具报不报工具报对比度达标不代表实际可读。比如某些字体在特定字号下即使对比度数值达标实际看起来还是费劲。工具是底线人眼是最终标准。我一般会在工具检查通过后自己再扫一眼尤其是正文和小字。7.4 键盘走查要趁早不要留到最后键盘走查如果留到交付前才做发现问题往往要动结构成本很高。我的做法是组件开发阶段就用键盘走一遍focus 顺序、focus 可见性在组件级别就确认好组装页面时就不会出大问题。7.5 团队标准要写下来不能靠口口相传“我们要求 focus 可见”这种话说一百遍不如写一遍。把 impeccable 的检查清单写成文档纳入 code review 模板新人入职第一周就过一遍。标准写下来之后讨论才有依据质量才可复现。8. 关于 impeccable 这件事我现在的做法说到底impeccable 不是一个能靠某个工具一键达成的状态它是一套约束 生成 检查 修复的循环。约束来自设计 token 和状态清单生成交给 AI coding agents检查靠 CLI 和浏览器扩展修复再把结果喂回 agent。这个循环跑得越顺交付质量越稳。我现在做前端开工第一件事不是写页面而是把 token 文件和检查清单准备好。这两样东西准备好了后面无论是自己写还是 agent 生成都有据可依。工具会更新agent 会换代但这套“先定约束、再谈生成、最后验收”的思路我用了这么久还没找到更好的替代。如果你也在被前端交付质量困扰不妨从整理一份 token 文件开始这一步的投入产出比比换任何工具都高。 
长河君 · 2026/10/28 4:56:04 · 阅读 1.2k impeccable前端交付：AI coding agents与CLI工具链质量流水线
1. 当“impeccable”成为前端交付的硬指标第一次看到“impeccable”这个词被拿来形容前端代码是在一个做设计系统的朋友嘴里。他说他们团队现在评审页面不看“能不能跑”而是看“够不够 impeccable”——像素对齐、间距节奏、状态覆盖、暗色模式、键盘可达性任何一项掉链子这个页面就打回去重做。这个词本身的意思是“无可挑剔的、完美的”放在前端语境里它其实指向一个很具体的东西交付质量的下限被抬高了。过去我们做前端验收标准往往是“功能正常、主流浏览器不崩”。但现在不一样了AI coding agents 开始大量参与页面生成CLI 工具能一句话吐出整页组件浏览器扩展能实时审查 DOM 和样式交付的“量”被瞬间拉满可“质”反而成了瓶颈。你让一个 agent 生成十个卡片组件它可能十个的圆角、阴影、hover 状态都不一样。这时候“impeccable”就不再是形容词而是一套可执行的检查清单。这篇内容我想聊的就是围绕 impeccable 这个目标怎么把 AI coding agents、CLI 工具链和浏览器扩展串成一条真正能落地的前端质量流水线。不管你是刚接触 codex cli 安装的新手还是已经在用 zcode cli 做日常开发的老手这里面的思路和踩坑记录应该都能对上你的场景。核心就一件事让“无可挑剔”从口号变成可复现的工程动作。2. 拆解 impeccable 在前端语境下的四层含义2.1 视觉一致性不是好看是“处处一样”很多人把 impeccable 理解成“设计得漂亮”这是个误区。漂亮是主观的impeccable 是客观的。它首先要求的是一致性同一个设计系统里按钮的圆角只有一套值间距只有一套刻度阴影只有一套层级。我见过太多项目主色定义了#3B82F6结果某个页面里手写了个#3b82f6大小写不一致主题切换的时候直接漏掉。这种问题人眼很难逐页发现但浏览器扩展可以。你打开 DevTools用扩展扫一遍所有元素的 computed style把颜色值、圆角值、字号值聚合成频次表那些只出现一两次的“孤儿值”就是嫌疑犯。实测下来一个中等规模的页面孤儿颜色值通常有 5 到 15 个孤儿间距值更多。这些就是 impeccable 的第一层敌人。2.2 状态覆盖默认态只是冰山一角一个组件“看起来没问题”往往只是默认态没问题。真正 impeccable 的组件要覆盖 hover、focus、active、disabled、loading、error、empty 至少七种状态。我做过一个统计团队里被退回的组件80% 的问题出在非默认态focus 没有可见轮廓、disabled 还能点、loading 时布局跳动、error 文案溢出容器。AI coding agents 生成组件时默认态通常写得像模像样但状态覆盖经常偷懒。这时候你需要一个明确的检查协议让 agent 按清单输出而不是靠它“自觉”。后面我会给一份可以直接喂给 agent 的状态清单模板。2.3 可达性键盘和读屏器说了算可达性accessibility是 impeccable 里最容易被忽略、但一旦缺失就最致命的一层。tab 键能不能走通、focus 顺序是否符合视觉顺序、aria 标签是否准确、对比度是否达标这些用鼠标点一遍是发现不了的。浏览器扩展在这里的价值极大比如用 axe 类的审查工具跑一遍能直接列出违规项和对应的 DOM 节点。我个人的经验是可达性问题里最常见的是对比度不足和缺少可见 focus 样式。前者是因为设计师选色时只看视觉效果没算对比度比值后者是因为很多 CSS reset 直接把 outline 干掉了却没给替代方案。这两个问题都能通过扩展自动化检出不需要人工逐个试。2.4 代码可维护性impeccable 的隐藏维度最后一层是代码本身。一个页面视觉上无可挑剔但 class 名全是div1、div2样式全靠!important堆那它离 impeccable 还差得远。可维护性包括命名是否有语义、样式是否复用、是否有魔法数字、组件边界是否清晰。这一层 CLI 工具能帮上忙比如用 lint 规则扫描硬编码颜色、扫描未使用的样式、扫描过深的嵌套选择器。把这四层合起来看impeccable 其实是一个多维度的质量门禁而不是单一的美学标准。理解了这一点后面的工具链搭建才有方向。3. AI coding agents 在 impeccable 流程里该站什么位置3.1 别让 agent 做它不擅长的事很多人对 AI coding agents 的期待是“一句话生成整个页面”然后发现生成的东西离 impeccable 差得远就得出结论说 agent 不好用。问题不在 agent在于任务粒度。让 agent 从零设计一个页面的视觉体系它大概率会给你一堆看起来还行但处处不一致的东西但如果你把任务拆成“按照这份 token 表生成一个按钮组件的七种状态”它的表现会好很多。我的做法是agent 负责生成和补全人负责定义约束和验收。约束包括设计 token、组件 API、状态清单、命名规范验收包括视觉走查、可达性扫描、lint 检查。agent 在这个框架里干活产出质量会稳定得多。3.2 给 agent 的提示词要带“验收标准”普通提示词是“帮我写一个卡片组件”impeccable 提示词应该是“帮我写一个卡片组件要求圆角使用 token--radius-md间距使用--space-4的倍数必须覆盖 hover/focus/disabled 三态focus 必须有 2px 可见轮廓所有颜色引用 token 不得硬编码输出后附上你覆盖了哪些状态的自检清单”。最后那句“附上自检清单”很关键。它逼着 agent 在生成时对照标准而不是生成完就交差。实测下来加了自检要求的产出状态覆盖率能从 40% 左右提升到 85% 以上。剩下的 15% 靠人工和扩展兜底。3.3 agent 产出的“可疑信号”清单用久了你会发现agent 生成的前端代码有一些高频可疑信号看到就要警惕可疑信号背后的问题处理方式硬编码颜色值未使用设计 token全局搜索替换为 tokenoutline: nonefocus 可达性缺失补可见 focus 样式固定 px 间距未使用间距刻度换算为 token 倍数缺少 disabled 样式状态覆盖不全按清单补齐内联 style样式不可复用抽到 class 或 token深层嵌套选择器可维护性差扁平化或改 BEM这份清单可以直接作为 code review 的检查项也可以反过来喂给 agent 作为生成约束。3.4 多 agent 协作时的“风格漂移”问题如果你同时用多个 agent 或者多个会话生成同一个项目的不同页面很容易出现风格漂移A 会话生成的按钮圆角是 6pxB 会话生成的是 8px。原因是每个会话的上下文里没有统一的 token 约束。解决办法是把设计 token 抽成一个独立的、agent 每次都要读取的文件比如design-tokens.json或tokens.css在提示词里明确要求“所有样式必须引用该文件中的变量”。这样即使 agent 换了约束还在。4. CLI 工具链把 impeccable 检查变成一条命令4.1 为什么 CLI 是质量流水线的骨架浏览器扩展适合交互式排查但它的短板是不可自动化。你没法在 CI 里跑一个扩展也没法让它在每次提交时自动执行。CLI 工具正好补上这块它可以在本地、在 pre-commit hook、在 CI 流水线里跑把 impeccable 的检查变成可重复、可阻断的动作。围绕前端质量我常用的 CLI 能力包括样式 lint、可达性扫描headless 方式、构建产物分析、依赖体积检查。这些工具组合起来基本能覆盖前面说的四层含义里的三层视觉一致性、可达性、可维护性状态覆盖那层还是得靠人工和 agent 自检。4.2 codex cli 安装与基础配置的实操记录codex cli 是很多人接触 AI 辅助编码的入口工具。安装本身不复杂但有几个细节容易卡住。以常见的安装方式为例# 通过包管理器安装具体包名以官方文档为准 npm install -g codex-cli-package # 验证安装 codex --version # 首次配置通常需要设置 API 凭据 codex config set api-key your-key安装完之后第一件要做的事不是马上生成代码而是配置项目级的约束文件。我一般会在项目根目录放一个AGENTS.md或类似的约定文件里面写清楚设计 token 在哪、命名规范是什么、状态清单有哪些、禁止硬编码颜色。codex cli 在生成时会读取这个文件产出质量会明显不同。提示安装过程中如果遇到权限报错优先检查全局安装目录的写权限而不是直接加 sudo。用 sudo 装全局包容易导致后续权限混乱。4.3 zcode cli 与 codex cli 的分工思路zcode cli 和 codex cli 这类工具功能上有重叠但使用场景可以分工。我的习惯是codex cli 负责“生成和补全”zcode cli 负责“审查和重构”。比如让 codex 生成一个新组件然后用 zcode 跑一遍样式审查找出硬编码值和状态缺失再让 codex 按审查结果修复。这个“生成—审查—修复”的循环比单次生成的质量高出一大截。这种分工的关键在于审查工具要输出结构化的结果最好是 JSON 或明确的文件行号列表这样修复阶段的 agent 才能精准定位。如果审查结果只是一段自然语言描述agent 修复时容易跑偏。4.4 把检查串成 pre-commit 钩子单次手动跑检查容易忘最好的办法是挂到 git 的 pre-commit 钩子上。一个简化的钩子脚本大概长这样#!/bin/sh # .git/hooks/pre-commit echo 运行样式 lint... npx stylelint src/**/*.css || exit 1 echo 运行可达性扫描... npx a11y-cli-tool --url http://localhost:3000 || exit 1 echo 检查硬编码颜色... grep -rn #[0-9a-fA-F]\{6\} src/ echo 发现硬编码颜色请改用 token exit 1 echo 检查通过这个脚本里硬编码颜色的检查用最简单的 grep 就能做不需要复杂工具。关键是让不合格的提交根本进不了仓库而不是等到 code review 才发现。实测下来挂了钩子之后团队里硬编码颜色的问题减少了 90% 以上。4.5 CLI 检查的常见误报与处理CLI 工具不是万能的误报很常见。比如可达性扫描工具会把一些动态生成的、扫描时还没渲染出来的元素报成违规样式 lint 会把一些刻意的例外报成错误。处理原则是误报要显式豁免而不是关掉整条规则。大多数工具都支持行内注释豁免比如/* stylelint-disable-next-line */ .special-case { color: #ff0000; }但豁免要克制每加一个豁免都应该有理由。如果某个规则被豁免了十几次那说明规则本身或者代码结构有问题该反思的是设计不是继续加豁免。5. 浏览器扩展实时审查与人工走查的放大器5.1 扩展能看到的是 CLI 看不到的“运行时真相”CLI 扫描的是源码和构建产物但页面真正跑起来之后的样子只有浏览器知道。比如某个元素的最终 computed style 是什么、focus 顺序实际怎么走、动态加载的内容有没有可达性问题、暗色模式切换后对比度还够不够。这些都需要浏览器扩展在运行时介入。我常用的扩展类型有三类样式审查类看 computed style、看 token 使用情况、可达性审查类跑 axe 规则、看对比度、布局审查类看间距、看对齐、看溢出。这三类配合起来基本能把视觉一致性和可达性问题在开发阶段就抓出来。5.2 用扩展做“token 使用审计”设计 token 定义了但代码里用没用、用对没用扩展可以帮你审计。思路是在页面上遍历所有元素读取它们的颜色、圆角、间距等属性和 token 表做比对列出所有不在 token 表里的值。这个操作手动做几乎不可能但扩展跑一遍几秒钟就出结果。我做过一次这样的审计一个看起来挺规整的页面扫出来 23 个非 token 颜色值、41 个非 token 间距值。这些值单看都“差不多”但累积起来就是视觉不一致的根源。修完之后页面的“整齐感”提升非常明显虽然用户说不清哪里变了。5.3 键盘走查扩展替代不了的那部分有一点必须说清楚扩展能自动化很多检查但键盘走查替代不了。tab 顺序是否合理、focus 是否可见、模态框打开后焦点是否被正确捕获、关闭后是否回到触发元素这些需要人真的用键盘走一遍。我的习惯是每个页面交付前拔掉鼠标纯键盘操作一遍核心流程。这个过程通常能发现 2 到 3 个扩展没报出来的问题。扩展和人工走查的关系是扩展负责广度覆盖所有元素、所有规则人工负责深度真实操作流程、真实使用场景。两者缺一不可。5.4 扩展配置的团队同步问题浏览器扩展的配置是存在本地的团队里每个人装的扩展、开的规则可能都不一样这就导致“我这边没问题你那边报一堆”。解决办法是把扩展的规则配置导出成文件纳入版本管理。很多审查类扩展支持导入导出配置把配置文件放到项目里新人入职时导入一次检查标准就统一了。这个细节看起来小但对团队协作影响很大。标准不统一讨论就会变成“你的工具是不是有问题”而不是“这个页面到底有没有问题”。6. 一套可复现的 impeccable 交付流程6.1 从 token 定义开始而不是从页面开始很多团队做页面的顺序是先画页面再抽 token。这个顺序是反的也是视觉不一致的根源。impeccable 的流程应该从token 定义开始颜色、间距、字号、圆角、阴影、动效时长全部先定好形成一份tokens文件。之后所有页面、所有组件、所有 agent 生成都引用这份文件。token 的粒度要适中。太粗只有主色和辅色覆盖不了场景太细每个组件一套又失去复用意义。我的经验是颜色分语义层primary、danger、success和中性层背景、边框、文字间距用 4px 或 8px 的倍数刻度字号用有限的几档。这套定下来后面就省心了。6.2 组件开发agent 生成 人工补状态有了 token组件开发就可以半自动化。流程是人写好组件的 API 和状态清单agent 按清单生成初版人再补上 agent 漏掉的状态和边界情况。状态清单我一般这么写默认态正常显示hover 态背景或边框有可见变化focus 态2px 可见轮廓颜色对比度达标active 态按下时有反馈disabled 态降低透明度禁用指针事件loading 态有加载指示布局不跳动error 态有错误提示提示不溢出把这份清单直接贴进提示词agent 的产出会完整很多。剩下的边界情况比如超长文案、空数据、极端窄屏还是得人工补。6.3 页面组装后的三层检查页面组装完跑三层检查CLI 层样式 lint、硬编码检查、可达性 headless 扫描扩展层token 使用审计、对比度检查、布局溢出检查人工层键盘走查、暗色模式走查、极端内容走查这三层跑完基本能覆盖 impeccable 的绝大部分要求。每层检查发现的典型问题我都整理过前面表格里那些就是高频项。6.4 把检查结果反哺给 agent 形成闭环检查发现的问题不要手动一个个改而是把结构化结果喂回给 agent 批量修复。比如扩展导出了一份“非 token 颜色值”列表直接把这个列表和对应的 token 映射喂给 agent让它批量替换。这个闭环跑顺了修复效率比手动高一个数量级。闭环的关键是结果要结构化。自然语言的检查报告 agent 不好用JSON 或 CSV 格式的列表它处理起来很准。所以选工具时优先选那些支持结构化输出的。7. 踩过的坑与实测有效的经验7.1 过度依赖 agent 导致“看起来对但处处不对”早期我试过完全放手让 agent 生成整个页面结果就是前面说的单看每个组件都还行放一起就露馅。圆角不一致、间距不统一、状态覆盖参差。后来改成“token 先行 清单约束 人工验收”质量才稳定下来。agent 是放大器不是替代品这个认知很重要。7.2 扩展装太多反而拖慢浏览器有段时间我装了一堆审查扩展结果浏览器卡得没法用。后来精简到三类各一个够用就行。扩展不是越多越好覆盖核心检查项即可重复功能的扩展只会互相干扰。7.3 对比度检查不能只看工具报不报工具报对比度达标不代表实际可读。比如某些字体在特定字号下即使对比度数值达标实际看起来还是费劲。工具是底线人眼是最终标准。我一般会在工具检查通过后自己再扫一眼尤其是正文和小字。7.4 键盘走查要趁早不要留到最后键盘走查如果留到交付前才做发现问题往往要动结构成本很高。我的做法是组件开发阶段就用键盘走一遍focus 顺序、focus 可见性在组件级别就确认好组装页面时就不会出大问题。7.5 团队标准要写下来不能靠口口相传“我们要求 focus 可见”这种话说一百遍不如写一遍。把 impeccable 的检查清单写成文档纳入 code review 模板新人入职第一周就过一遍。标准写下来之后讨论才有依据质量才可复现。8. 关于 impeccable 这件事我现在的做法说到底impeccable 不是一个能靠某个工具一键达成的状态它是一套约束 生成 检查 修复的循环。约束来自设计 token 和状态清单生成交给 AI coding agents检查靠 CLI 和浏览器扩展修复再把结果喂回 agent。这个循环跑得越顺交付质量越稳。我现在做前端开工第一件事不是写页面而是把 token 文件和检查清单准备好。这两样东西准备好了后面无论是自己写还是 agent 生成都有据可依。工具会更新agent 会换代但这套“先定约束、再谈生成、最后验收”的思路我用了这么久还没找到更好的替代。如果你也在被前端交付质量困扰不妨从整理一份 token 文件开始这一步的投入产出比比换任何工具都高。