Impeccable audit 命令深度解析：AI 前端工程化的五维技术质检与报告体系

2026-09-06 14:09:44作者：邵娇湘

/impeccable audit 是 Impeccable（一个面向 AI 编码代理的设计技能包）中专门负责技术质量审计的命令。它不评价"好不好看"，而是用五个 0-4 分的量化维度（无障碍、性能、主题化、响应式、实现完整性）对 Web 前端代码做可度量的技术检查，输出一份带 P0-P3 严重级别、健康分（满分 20）和后续修复命令映射的审计报告。读完本文，你将掌握这套审计方法论的完整执行标准，知道如何用它配合 Impeccable 自带的确定性检测器（61 条规则）为 AI 生成的前端建立可重复、可验证的质量基线。

1. 命令定位：代码级审计，不是设计评审

audit.md 开篇就划定了这条命令的职责边界：

Run systematic technical quality checks and generate a comprehensive report. Don't fix issues; document them for other commands to address.

This is a code-level audit, not a design critique. Check what's measurable and verifiable in the implementation.

三个关键定位：

只查可度量、可验证的东西：审计对象是实现层代码（HTML/CSS/JS），不是视觉观感。"层级乱不乱"、"情感对不对"属于姊妹命令 critique.md（UX 设计评审）的职责，audit 明确不越界。
只记录，不修复：audit 的产物是报告。发现问题后交给其他命令去修（/impeccable adapt、/impeccable optimize 等），这保证了审计与修复两个上下文相互独立，避免"边查边改"导致的报告失真。
仅适用于 Web：文档明确写明 "Web only"，原生平台（ios / android / adaptive）必须切换到 audit.native.md。这个路由逻辑与 CLAUDE.md 中的工程说明一致：detect CLI 和 design hook 都是 Web-only，因为规则引擎读的是 HTML/CSS，对原生代码没有判断力。

在 SKILL.md 的命令表中，audit [target] 被归入 Evaluate 类别（"Technical quality checks (a11y, perf, responsive)"），与同为 Evaluate 类的 critique（UX heuristic scoring）形成"技术面 + 设计面"的双轨评估结构。

2. 诊断扫描：五维模型与 0-4 分制

审计执行 "Diagnostic Scan"，对五个维度做全面检查，每个维度按既定标准打 0-4 分。下面完整继承原文档的每个检查项与评分锚点，并补充其在源码/工具链中的对应实现。

2.1 维度一：无障碍（Accessibility / A11y）

检查项（Check for）：

对比度问题：文本对比度低于 4.5:1（AAA 级则低于 7:1）；
动效敏感度：prefers-reduced-motion 必须有保留状态变化与层级感的"有意替代"。要标记的反模式包括：全局 0.01ms 一刀切禁动（摧毁了有用的反馈）、超过阈值的闪烁、以及阻塞焦点移动/阅读/任务完成的动效；
缺失 ARIA：交互元素缺少正确的 roles、labels 或 states；
键盘导航：缺失焦点指示器、Tab 顺序不合逻辑、存在键盘陷阱（keyboard traps）；
语义化 HTML：标题层级错乱、缺失 landmark 区域、用 div 冒充 button；
替代文本：图片缺失 alt 或 alt 描述质量差；
表单问题：输入框无 label、错误提示不友好、缺少必填指示。

评分锚点（Score 0-4）：

分数	含义
0	不可用（fails WCAG A）
1	重大缺口（几乎没有 ARIA 标签、无键盘导航）
2	部分（有一些 a11y 努力，但缺口显著）
3	良好（基本满足 WCAG AA，少量小缺口）
4	优秀（WCAG AA 完全满足，接近 AAA）

2.2 维度二：性能（Performance）

布局抖动（Layout thrashing）：在循环中交替读写布局属性；
昂贵动画：随手动画 layout 属性、无边界限制的 blur/filter/shadow 效果、或肉眼可见掉帧的效果；
缺失优化：图片未懒加载、资源未压缩；
will-change 滥用：大面积使用或常驻不释放（原文强调它是针对"已知昂贵动画"的定点提示，而不是基线要求）；
Bundle 体积：无用 import、未使用的依赖；
渲染性能：不必要的 re-render、缺失 memoization。

评分锚点：0=严重问题（布局抖动、处处未优化）→ 1=重大问题（无懒加载、昂贵动画）→ 2=部分（有优化但仍有缺口）→ 3=良好（基本优化，可小幅改进）→ 4=优秀（快、轻、优化到位）。

2.3 维度三：主题化（Theming）

硬编码颜色：没有使用 design tokens 的颜色值；
深色模式损坏：缺失 dark 变体、暗色主题下对比度差；
token 不一致：用错 token、混用不同语义的 token；
主题切换问题：某些值在主题切换后不更新。

评分锚点：0=完全没有主题化（全部硬编码）→ 1=极简 token（大部分硬编码）→ 2=部分（有 token 但使用不一致）→ 3=良好（使用 token，少量硬编码残留）→ 4=优秀（完整 token 体系，深色模式完美工作）。

2.4 维度四：响应式设计（Responsive Design）

固定宽度：硬编码宽度在小屏上破版；
触控目标：交互元素小于 44x44px；
横向滚动：窄视口下内容溢出；
文本缩放：用户调大字号时布局崩坏；
缺失断点：没有移动端/平板变体。

评分锚点：0=只有桌面版（移动直接破）→ 1=重大问题（有些断点但大量失败）→ 2=部分（移动端能看，毛糙）→ 3=良好（响应式，少量触控目标或溢出问题）→ 4=优秀（流式布局、全视口、触控目标规范）。

值得注意的是，"触控目标 < 44x44px" 与 "line length、cramped padding、skipped headings" 等检查项在仓库的确定性检测器中也有对应实现：README.md 明确列出检测器覆盖 "61 deterministic issues across AI slop ... and general design quality (line length, cramped padding, small touch targets, skipped headings, and more)"——也就是说 audit 的部分检查项不是纯靠 LLM 目测，而是有确定性规则兜底的，这提高了打分的可复现性。

2.5 维度五：实现完整性（Implementation Integrity，CRITICAL）

这是 audit 中唯一标记为 CRITICAL 的维度，原文要求：

Run the bundled detector and verify each finding in context. Look for repeated implementation shortcuts, design-system drift, misleading or decorative content, and structure that is interchangeable with an unrelated product. Keep deterministic findings separate from visual judgment and call out false positives.

拆解成四条操作纪律：

必须运行随附的检测器（bundled detector），并把每条发现放回上下文里人工复核；
关注的病灶：重复的实现捷径、设计系统漂移（drift）、误导性或纯装饰内容、以及"换一个不相关产品直接能用"的通用结构；
确定性发现与视觉判断严格分离：检测器输出是机器结论，视觉判断是 LLM 结论，报告里不能混在一起；
主动标记误报（false positives），不许把误报当问题上报。

评分锚点：0=系统性漂移（systemic drift）→ 1=重大重复性失败 → 2=多个已验证问题 → 3=少量孤立的小问题 → 4=连贯且有意为之（coherent and intentional）。

检测器从哪来？ 从源码结构看，技能运行时通过 node "<skill-base-dir>/scripts/detect.mjs" --json [target] 调用该检测器（参见 critique.md 中对同一脚本的调用约定），其底层引擎即 package.json 声明的入口 cli/engine/detect-antipatterns.mjs（"main" 与 exports["."] 均指向它，另有 ./browser 导出供浏览器扩展使用）。CLI 侧，cli/bin/cli.js 把 detect 子命令转发给 detectCli()，并对"路径样参数"做了宽松的 looksLikeDetectTarget 判定，因此 npx impeccable src/ 这种省略 detect 的简写也能工作。运行时环境要求 Node.js >=22.18.0（见 package.json 的 engines 字段）。

独立运行检测器的完整命令面（摘自 README.md）：

npx impeccable detect src/                   # 扫描目录
npx impeccable detect index.html             # 扫描单个 HTML 文件
npx impeccable detect https://example.com    # 扫描 URL（Puppeteer）
npx impeccable detect --json .               # CI 友好的 JSON 输出
npx impeccable detect --no-config src/       # 原始扫描，忽略项目配置
npx impeccable ignores list                  # 查看检测器忽略规则
npx impeccable ignores add-file "src/legacy/**"
npx impeccable ignores add-value overused-font Inter --reason "Brand font"

按 critique.md 的约定，检测器的退出码语义是 0 = clean；2 = findings，可作为 CI 判定的直接信号。

配置与豁免机制同样服务于"把确定性发现与人工判断分开"这一纪律：detect 默认读取 .impeccable/config.json 与 .impeccable/config.local.json 中的 detector.ignoreRules、detector.ignoreFiles、detector.ignoreValues、detector.designSystem.enabled（hook 与 CLI 共享同一份 detector 配置）；针对单个文件的豁免则用行内注释标记 ，该标记支持任意注释语法、可限定整文件或单行（impeccable-disable-line / impeccable-disable-next-line），并会被 --no-inline-ignores / --no-config 绕过。audit 维度五要求"call out false positives"，这套豁免机制正是把已确认的误报/合理例外沉淀到仓库而不是留在报告噪音里的正规路径。

3. 报告生成：一份可执行的审计报告长什么样

完成五维打分后，audit 按固定骨架生成报告。以下结构完整继承原文档的模板定义。

3.1 Audit Health Score（健康分总表）

#	Dimension	Score	Key Finding
1	Accessibility	?	[最关键的 a11y 问题，无则 "--"]
2	Performance	?
3	Responsive Design	?
4	Theming	?
5	Implementation Integrity	?
Total		??/20	[Rating band]

评级区间（Rating bands）：

总分	评级
18-20	Excellent（只需小修小补）
14-17	Good（处理弱项维度）
10-13	Acceptable（需要较大工作量）
6-9	Poor（需要大改）
0-5	Critical（根本性问题）

每行的 Key Finding 只写该维度最关键的一个发现，保证总表可一眼扫完——这是"报告是给人看的"这一设计取向的体现。

3.2 Implementation Integrity Verdict（完整性裁决）

原文要求把它放在报告最前面："Start here. Pass/fail: does the implementation express a coherent product-specific system? Cite verified evidence and detector findings."

即：整份报告先回答一个通过/不通过的问题——这份实现是否表达了一个连贯的、产品专属的系统？并引用已验证的证据和检测器发现。这与维度五的 CRITICAL 地位呼应：技术小瑕疵可以容忍，"实现整体与产品无关"是不合格的。

3.3 Executive Summary（执行摘要）

Audit Health Score：??/20（+ 评级区间）；
问题总数（按 P0/P1/P2/P3 分别计数）；
Top 3-5 关键问题；
建议的下一步。

3.4 Detailed Findings by Severity（按严重级别列明细）

每条问题必须打上 P0-P3 严重级别，原文给出的四级定义：

P0 Blocking：阻止任务完成。立即修复；
P1 Major：造成显著困难或构成 WCAG AA 违规。发布前修复；
P2 Minor：恼人但存在变通方案。下一轮修复；
P3 Polish：修了更好，无实际用户影响。有时间再修。

每条问题按固定字段记录：

[P?] 问题名
Location：组件、文件、行号；
Category：Accessibility / Performance / Theming / Responsive / Implementation Integrity（五选一，对应打分维度）；
Impact：如何影响用户；
WCAG/Standard：违反了哪条标准（如适用）；
Recommendation：怎么修；
Suggested command：映射到哪个修复命令（见 3.7 的白名单）。

注意"Location 精确到行号 + Category 回指打分维度"这两点：它们使报告可以直接被 CI/代码评审消费，也让每个维度分数与问题清单之间可以互相核对——分数是聚合，明细是可追溯依据。

3.5 Patterns & Systemic Issues（模式与系统性问题）

识别反复出现、说明存在系统性缺口而非一次性失误的问题。原文给出的两个示例：

"硬编码颜色出现在 15+ 个组件中，应该使用 design tokens"；
"移动端全程触控目标小于 44px"。

这类模式类结论直接决定修复策略：散点问题逐个修，模式问题应该建 token 体系或统一改组件，而不是打 15 个补丁。

3.6 Positive Findings（正面发现）

记录做得好的地方：值得保持与复制的好实践。这不是客套章节，后文"报告纪律"里它是硬性要求。

3.7 Recommended Actions（推荐行动）

按优先级列出推荐命令（先 P0，再 P1，再 P2），格式：

[P?] /command-name：简要描述（来自审计发现的具体上下文）
[P?] /command-name：简要描述（具体上下文）

硬规则：只能从固定白名单中推荐命令——

/impeccable adapt、/impeccable animate、/impeccable audit、/impeccable bolder、/impeccable clarify、/impeccable colorize、/impeccable critique、/impeccable delight、/impeccable distill、/impeccable document、/impeccable harden、/impeccable layout、/impeccable onboard、/impeccable optimize、/impeccable overdrive、/impeccable polish、/impeccable quieter、/impeccable shape、/impeccable typeset。

发现必须映射到"最合适"的命令，且只要推荐了任何修复，最后一步必须是 /impeccable polish（作为收口工序）。这条"白名单 + 收尾"规则把 audit 的输出直接接入了 Impeccable 的命令生态：audit 是评估端，19 个命令是执行端，报告末尾的动作列表就是两者的接口。

展示完摘要后，须向用户输出固定话术：

You can ask me to run these one at a time, all at once, or in any order you prefer.

Re-run /impeccable audit after fixes to see your score improve.

"修复后重跑 audit 看分数上升"——这就是这套体系作为质量回路的闭环设计：健康分是可重复测量的指标，修复行为的价值通过分数变化来验证。

4. 报告纪律：NEVER 清单

原文末尾用 NEVER 列出了五条禁止项，它们定义了"合格审计报告"的底线：

不解释影响就上报问题（这为什么重要？）；
不给泛泛的建议（要具体、可执行）;
不跳过正面发现（要肯定做得好的部分）；
忘记优先级（不能什么都标 P0）；
把未经核实的误报当真实发现上报。

配合前文的"确定性发现与视觉判断分离"、"call out false positives"，可以推断这套纪律的动机：audit 的读者（人和下游修复命令）依赖报告做资源分配，噪声（P3 泛滥、误报、无影响说明）比漏报的代价更高，所以原文同时要求 "Be thorough but actionable"。

5. 与原生变体及 critique 的边界

理解 audit 的完整定位需要两个横向参照：

Web vs Native：audit.native.md 与 Web 版共享同一套"五维 0-4 分 + 20 分健康分 + P0-P3 明细 + 命令白名单"报告骨架（其第 3 行明确要求两者保持同步），但维度内容整体替换为原生语境：无障碍换成 VoiceOver/TalkBack（44 pt / 48 dp 触控目标）、性能关注启动时间与列表虚拟化、Theming 关注语义系统色与 Material color roles、第 4 维从"实现完整性"换成 Platform Conformance（系统手势、inset 违规、off-platform 控件等），第 5 维是 Adaptivity（平板/横屏/多窗口/折叠屏）。也就是说，audit.md 中的评分与报告机制是跨平台通用的，五个维度的具体检查项才是 Web 特有的部分。
audit vs critique：critique（UX 设计评审）采用"双独立评估 + 综合"的强制流程，其中 Assessment B 同样调用检测器并注入浏览器可视化证据；而 audit 是单轨道的纯技术检查，不设子代理编排要求。两者都消费同一套确定性检测器，但 critique 把检测器发现作为设计判断的"锚点证据"，audit 则把它作为第 5 维的硬性输入。

6. 实操路径小结

在已安装 Impeccable 的项目（npx impeccable install 后）中，使用 audit 的典型流程：

在 AI 编码工具中执行 /impeccable audit <target>，例如 README.md 中的示例 /impeccable audit blog（审计博客列表 + 文章页）；
对 Web 项目，执行流程按 audit.md 逐维打分并运行 bundled detector；原生项目会自动路由到 audit.native.md；
拿到 20 分制健康分报告后，按 Recommended Actions 逐条或批量执行修复命令，最后以 /impeccable polish 收口；
修复完成后重跑 /impeccable audit，用分数变化验证质量提升；
不依赖 AI 代理时，也可用 npx impeccable detect --json . 独立运行 61 条确定性规则（退出码 0/2 可直接接入 CI），其忽略规则通过 .impeccable/config.json 的 detector.* 键或行内 impeccable-disable 标记维护。

需要说明的适用前提：audit.md 的检查项与阈值（4.5:1 对比度、44x44px 触控目标等）是方法论标准而非检测器的完整规则集；检测器自身覆盖 61 条确定性规则，CLI 版本能力以当前仓库 README.md 与 package.json（engines 要求 Node >=22.18.0）声明为准。

核心参考文件：