Impeccable audit 命令深度解析：五维技术质量审计体系与评分报告机制

2026-09-04 18:41:39作者：冯梦姬Eddie

在 Impeccable 这套"让 AI 更好做设计"的技能体系中，$impeccable audit 是少数以工程测量而非审美判断为核心的命令：它按五个维度对 Web 前端实现做可验证的技术质检，输出 0–20 分的健康度评分表、P0–P3 分级问题清单，以及映射到具体修复命令的优先级行动列表。读完本文，你将完整掌握 audit 的检查维度、评分标准、报告骨架，以及它背后打包的确定性检测器（detector）的源码实现与验证方式，并能在自己的 AI 工作流中规范地消费这份审计报告。

一、定位：代码级审计，而非设计评审

audit 的第一条指令就把边界钉死了：做系统性的技术性质量检查并生成综合报告；只记录问题，不修复问题——修复由其他命令接手。原文明确区分：

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

也就是说，audit 只回答"实现层面可测量、可验证"的问题（对比度、懒加载、固定宽度、token 使用……），而"层级是否清晰、情感共鸣是否到位"这类 UX 设计判断属于兄弟命令 $impeccable critique 的职责。在 SKILL.md 的命令表中，audit [target] 被归入 Evaluate 类别，描述为 "Technical quality checks (a11y, perf, responsive)"，与同属 Evaluate 的 critique（heuristic 评分的 UX 评审）形成互补。

平台路由：Web 专用

原文第 5 行规定了硬性路由：Web only。若项目平台是 ios / android / adaptive，必须立刻切换到 audit.native.md。这一点在路由文档 routing.md 中得到了印证："live and the bundled detect.mjs are web-only"——浏览器 overlay 和 HTML 规则引擎对原生应用代码不适用。从源码结构看，native 版与 Web 版刻意保持"报告骨架镜像"（原文要求 "keep the two in sync when changing it"），区别在于第 4 维从 Implementation Integrity 换成了 Platform Conformance（对照 ios.md / android.md 评分），第 5 维换成 Adaptivity。

二、Diagnostic Scan：五个诊断维度的完整检查清单

audit 要求对 5 个维度各打 0–4 分。以下完整继承原文的每个维度检查项与评分刻度。

1. Accessibility（A11y）

检查项：

Contrast issues：文本对比度 < 4.5:1（AAA 为 7:1）
Motion sensitivity：prefers-reduced-motion 需要保留状态变化与层级感的有意识替代方案；要标记出会摧毁有用反馈的全局 0.01ms 一刀切关闭、超过阈值的闪烁，以及阻塞焦点/阅读/任务完成的动效
Missing ARIA：交互元素缺少正确的 role、label 或状态
Keyboard navigation：焦点指示器缺失、tab 顺序不合逻辑、键盘陷阱
Semantic HTML：标题层级错乱、缺少 landmark、用 div 冒充按钮
Alt text：图片描述缺失或质量差
Form issues：input 无 label、错误提示差、缺少 required 指示

0–4 评分刻度：0 = Inaccessible（不满足 WCAG A）；1 = Major gaps（ARIA 标注极少、无键盘导航）；2 = Partial（有一些 a11y 努力但缺口明显）；3 = Good（WCAG AA 基本达标，小缺口）；4 = Excellent（WCAG AA 完全达标，接近 AAA）。

2. Performance

检查项：

Layout thrashing：循环中读写布局属性
Expensive animations：随手动画布局属性、无界（unbounded）的 blur/filter/shadow 特效、肉眼可见掉帧的效果
Missing optimization：图片未懒加载、资源未优化
will-change overuse：will-change 被大面积施加或静止时仍保留（它是指向已知昂贵动画的定向提示，不是基线要求）
Bundle size：不必要的 import、未使用的依赖
Render performance：不必要的重渲染、缺少 memoization

0–4 评分刻度：0 = Severe issues（layout thrash、全面未优化）；1 = Major problems（无懒加载、昂贵动画）；2 = Partial；3 = Good；4 = Excellent（fast, lean, well-optimized）。

3. Theming

检查项：

Hard-coded colors：未走 design token 的颜色
Broken dark mode：缺暗色变体、暗色主题对比度差
Inconsistent tokens：用错 token、混用 token 类型
Theme switching issues：主题切换后不更新取值

0–4 评分刻度：0 = 完全无 theming（全硬编码）；1 = Minimal tokens；2 = Partial（token 存在但不一致）；3 = Good（token 为主，少量硬编码）；4 = Excellent（完整 token 体系，暗色模式完美）。

4. Responsive Design

检查项：

Fixed widths：移动端会崩的硬编码宽度
Touch targets：交互元素小于 44×44px
Horizontal scroll：窄视口下的内容溢出
Text scaling：字号放大后布局崩坏
Missing breakpoints：无移动端/平板变体

0–4 评分刻度：0 = Desktop-only；1 = Major issues；2 = Partial；3 = Good（响应式，少量触控目标/溢出问题）；4 = Excellent（fluid、全视口、触控目标达标）。

5. Implementation Integrity（CRITICAL）

这一维是唯一要求运行工具的维度：运行打包的 detector，并在上下文中验证每一条发现。关注重复的实现捷径、design-system 漂移、误导或纯装饰性内容，以及"与无关产品可互换"的结构。原文强调把确定性发现与视觉判断分开，并点名误报。

0–4 评分刻度：0 = systemic drift；1 = major repeated failures；2 = several verified issues；3 = minor isolated issues；4 = coherent and intentional。

三、源码纵深：detector 如何支撑第 5 维

audit 第 5 维所说的 "the bundled detector" 在仓库中是完整可见的调用链：

入口：技能脚本 detect.mjs 是一个薄包装——按顺序在 detector/detect-antipatterns.mjs 与 cli/engine/detect-antipatterns.mjs 中查找引擎入口，然后调用 detectCli()。它还内嵌了一个护栏：若项目存在未关闭的 comp round / hero gate（由 build-phase.mjs 报告），会向 stderr 打印 COMP_ROUND_OPEN 警告——"detector 通过不等于完工"。这也是为什么 routing.md 建议把 detect.mjs --json 的输出作为推荐命令的"真实、当前"信号（大量 quality/contrast 命中 → 推荐 audit 或 polish；特定 slop 家族 → 对应命令），并且明确要求"detector 报错或树太大就跳过，永远不要阻塞建议"。
门面与规则注册表：detect-antipatterns.mjs 是公共 API 门面，运行时引擎位于 cli/engine/engines/ 下，分为四套：static-html（解析 HTML/CSS 级联）、regex（纯文本/CSS-in-JS 检测，含 extractCSSinJS）、browser（对 URL 做真实浏览器检测）与 visual（截图对比度分析）。规则定义集中在 registry/antipatterns.mjs，共 30+ 条规则，如 low-contrast、gray-on-color、layout-transition、cramped-padding、extreme-negative-tracking、oversized-h1 等。
与 audit 维度的直接对应：
- 第 1 维（A11y）：注册表中 low-contrast 的描述即原文阈值——"Text does not meet WCAG AA contrast requirements (4.5:1 for body, 3:1 for large text)"。实现上，rules/checks.mjs 基于 shared/color.mjs 的 relativeLuminance / contrastRatio 计算，且对渐变背景取所有 stop 的最差比值（worst case across all bg stops），命中后生成形如 low-contrast 的 snippet；对 emoji、半透明 alpha、backdrop 等不可测情形做了显式豁免，从机制上降低误报——这正是 audit 要求"call out false positives"的工具层基础。
- 第 2 维（Performance）：layout-transition 规则直接对应"Expensive animations / Layout thrashing"检查项，描述为"Animating width, height, padding, or margin causes layout thrash... Use transform and opacity instead"。
- 第 5 维（Integrity）：design-system drift 由 design-system.mjs 承接（checkSourceDesignSystem / collectStaticDesignSystemFindings），对照 DESIGN.md 校验源码取值漂移。
advisory 机制：findings.mjs 会为带 advisory: true 的规则打上标记，cli/main.mjs 把 advisory 发现单独分区、置灰输出，且不计入驱动退出码的失败数——这为 audit 报告"把确定性发现与视觉判断分开"提供了工程抓手。
测试佐证：tests/detect-antipatterns-fixtures.test.mjs 使用 tests/fixtures/antipatterns/ 下数十个真实 HTML 夹具（如 visual-contrast.html、pulsing-dot.html、extreme-negative-tracking.html、cramped-padding.html）验证"应标记/应放行"两类期望，是 detector 行为最直接的回归证据。

四、报告生成：健康度评分表与完整骨架

审计完成后，报告按原文规定的固定骨架产出。以下模板与字段完整继承自原文档。

Audit Health Score

#	Dimension	Score	Key Finding
1	Accessibility	?	[most critical a11y issue or "--"]
2	Performance	?
3	Responsive Design	?
4	Theming	?
5	Implementation Integrity	?
Total		??/20	[Rating band]

Rating bands（分数区间）：18–20 Excellent（minor polish）；14–17 Good（address weak dimensions）；10–13 Acceptable（significant work needed）；6–9 Poor（major overhaul）；0–5 Critical（fundamental issues）。

Implementation Integrity Verdict

原文要求"Start here"：先给出 pass/fail 判断——实现是否表达了一个连贯的、产品特定的系统？必须引用已验证的证据与 detector 发现。这是整个报告的第一读者视角。

Executive Summary

Audit Health Score: ??/20（[rating band]）
Total issues found（按 P0/P1/P2/P3 计数）
Top 3–5 critical issues
Recommended next steps

Detailed Findings by Severity

每个问题必须打 P0–P3 严重度标签：

P0 Blocking：阻止任务完成，立即修复
P1 Major：显著困难或 WCAG AA 违例，发布前修复
P2 Minor：有 workaround 的困扰项，下轮修复
P3 Polish：值得修但无实质用户影响，有空再修

每个问题需记录七个字段：

[P?] Issue name
Location：Component、file、line
Category：Accessibility / Performance / Theming / Responsive / Implementation Integrity
Impact：如何影响用户
WCAG/Standard：违反的规范（如适用）
Recommendation：如何修复
Suggested command：应使用哪个命令（从下文白名单中选择）

Patterns & Systemic Issues 与 Positive Findings

识别反复出现、指示系统性缺口的问题，而非偶发失误，例如：

"Hard-coded colors appear in 15+ components, should use design tokens"
"Touch targets consistently too small (<44px) throughout mobile experience"

同时必须记录 Positive Findings：哪些做得好，是应当保持和复制的实践。

五、Recommended Actions：从审计到执行的命令白名单

报告尾部按优先级（P0 → P1 → P2）列出推荐命令：

1. [P?] `$command-name`: Brief description (specific context from audit findings)
2. [P?] `$command-name`: Brief description (specific context)

规则（原文硬约束）：只允许推荐白名单内的命令——$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。

呈现完毕后，必须原样告知用户：

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 的闭环：只读审计 → 分级报告 → 修复命令 → 复测看分数上涨。

六、质量红线：原文的 IMPORTANT 与 NEVER 清单

audit 文档末尾有两组不可妥协的报告纪律：

IMPORTANT：thorough but actionable——过多 P3 会制造噪音，聚焦真正重要的事。

NEVER：

不解释影响就报告问题（为什么它重要？）
给出泛泛的、不可执行的建议
跳过 Positive Findings（要庆祝做得好的部分）
忘记优先级（不可能全是 P0）
未经验证就报告误报

七、实战调用方式与适用前提

结合仓库 README 与 SKILL 元信息，audit 的常规用法：

/impeccable audit            # 全项目体检
/impeccable audit blog       # 聚焦 blog hub + post 页面
/impeccable audit the header # 聚焦某个区域

前置：Setup 阶段会先运行 context.mjs 加载 PRODUCT.md / DESIGN.md 与 surface brief，audit 的判定依赖这些项目上下文。
快捷方式：/impeccable pin audit 生成独立的 /audit 命令。
复测：修复后重跑 $impeccable audit 验证分数变化，是原文钦定的收尾动作。
适用限制：仅适用于 Web 前端（HTML/CSS/JS 可读实现）；原生平台请走 audit.native.md；audit 不修改代码，其输出是其他命令的 backlog。