impeccable 技术质量审计指南：用 /impeccable audit 对 Web 界面进行五维评分与 P0-P3 分级整改

/impeccable audit 是 impeccable 技能体系中负责技术质量评估的命令：它不做设计审美评判，而是以代码级、可测量、可验证的方式，对 Web 界面的可访问性、性能、主题化、响应式与实现完整性五个维度逐项打分（每维 0–4 分），产出一份带 P0–P3 严重度分级、整改命令映射与复测路径的完整审计报告。读完本文，你将掌握 audit 命令的完整执行协议（诊断扫描 → 评分 → 报告 → 推荐动作），理解每一条检查项背后的判定标准，并知道如何在审计通过后使用 /impeccable polish 等命令逐级收尾。

本文以 audit.md（其在 skill/reference/、plugin/skills/impeccable/reference/ 等多个技能安装目录下保持同一份内容）为主体，结合仓库中检测器与评分引擎的 Rust 实现展开原理层面的补充。

一、定位与边界：这是代码审计，不是设计评审

/impeccable audit 的执行纲要非常明确：

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

即：系统化地执行技术质量检查并生成综合报告；不修复问题，而是把问题记录下来交给其他命令处理。 这是审计与 polish、adapt 等修复型命令的分工边界——audit 只负责"诊断与举证"。

同时它强调：

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

这是代码层面的审计，不是设计评论。凡是不可测量、无法在实现中验证的"感觉问题"，都不属于 audit 的职责范围；audit 只检查能落到代码事实上的东西。这一原则与仓库中检测器的设计一脉相承：crates/detect 的全部引擎都围绕"可判定、可定位、可复现"的实现事实展开（见下文"五、支撑引擎"）。

Web 平台限定：audit 明确标注 Web only。对于原生平台（ios / android / adaptive），应改走 audit.native.md，其报告骨架与本文档保持一致（The report skeleton mirrors audit.md; keep the two in sync when changing it），但五个维度替换为 VoiceOver/TalkBack 可访问性、性能、外观与主题化、平台符合性（Platform Conformance）、自适应能力，并对照 ios.md 与 android.md 平台参考文档评分。如果项目是原生应用，应立即切换到原生版审计，而不是在 Web 检查项上生搬硬套。

命令在技能体系中的位置：在 SKILL.md 的 Commands 表中，audit [target] 属于 Evaluate（评估） 类别，描述为 "Technical quality checks (a11y, perf, responsive)"，可携带 [target]（feature、page、component 等）参数；command-metadata.json 中的 audit 条目进一步说明：

Run technical quality checks across accessibility, performance, theming, responsive design, and anti-patterns. Generates a scored report with P0-P3 severity ratings and actionable plan. Use when the user wants an accessibility check, performance audit, or technical quality review.

即触发场景是"无障碍检查、性能审计或技术质量评审"，产物是一份带 P0–P3 严重度评级和可执行计划（actionable plan）的评分报告。

二、整体流程：五维诊断扫描 → 报告生成 → 推荐动作

audit 的执行协议由三个阶段构成：

1. Diagnostic Scan（诊断扫描）：跨 5 个维度执行全面检查，每个维度按 0–4 分评分；
2. Generate Report（生成报告）：输出健康评分表、实现完整性裁决、执行摘要、按严重度排列的详细发现、模式化问题与正面发现；
3. Recommended Actions（推荐动作）：按优先级（P0 优先，其次 P1、P2）列出建议执行的 /impeccable 命令，并引导用户复跑审计验证改善。

下面依次展开五个维度的检查项与评分细则。

三、五个诊断维度：检查项与 0–4 评分细则

3.1 维度一：Accessibility（可访问性，A11y）

检查项包括：

• 对比度问题（Contrast）：文本对比度低于 4.5:1（AAA 级为 7:1）；
• 动效敏感性（Motion sensitivity）：prefers-reduced-motion 需要有意识地保留状态变化与层级关系的替代方案。需要标记的动效包括：全局 0.01ms 的"一刀切"动效禁用（会破坏有用反馈）、超过阈值的闪烁（flashing）、以及阻碍焦点、阅读或任务完成的动效；
• ARIA 缺失：交互元素缺少正确的 role、label 或 state；
• 键盘导航：缺少焦点指示器、Tab 顺序不合逻辑、键盘陷阱（keyboard trap）；
• 语义化 HTML：标题层级错误、缺少 landmark、用 div 冒充 button；
• 替代文本：图片缺少 alt 或 alt 质量差；
• 表单问题：输入框无 label、错误提示差、缺少必填标识。

0–4 评分：

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

3.2 维度二：Performance（性能）

检查项包括：

• 布局抖动（Layout thrashing）：在循环中交替读写布局属性；
• 昂贵动画：随意对布局属性做动画、无界 blur/filter/shadow 效果，或肉眼可见的掉帧；
• 优化缺失：图片未懒加载、资源未优化；
• will-change 滥用：will-change 被大面积应用或静止状态下仍保留（它应只是针对已知昂贵动画的定向提示，而不是基线要求）；
• 包体积：多余 import、未使用的依赖；
• 渲染性能：不必要的重复渲染、缺少 memoization。

0–4 评分：0=严重问题（布局抖动、一切未优化）；1=主要问题（无懒加载、昂贵动画）；2=部分优化，仍有缺口；3=基本已优化，只有小改进空间；4=优秀（快速、精简、充分优化）。

3.3 维度三：Theming（主题化）

检查项包括：

• 硬编码颜色：颜色未使用设计令牌（design tokens）；
• 暗色模式损坏：缺少暗色变体、暗色主题下对比度差；
• 令牌不一致：用错令牌、混用令牌类型；
• 主题切换问题：主题变化时某些值不随之更新。

0–4 评分：0=无主题化（一切硬编码）；1=令牌极少（基本硬编码）；2=部分（有令牌但使用不一致）；3=良好（使用令牌，仅少量硬编码值）；4=优秀（完整令牌系统、暗色模式完美工作）。

这一维度与仓库的 DESIGN.md 设计系统解析高度对应：crates/detect/src/design_system.rs 负责发现并规范化项目设计系统（resolve_design_md_path 以项目边界向上查找 DESIGN.md / Design.md / design.md，并回退到 .agents/context、docs 目录），从 frontmatter YAML 与 sidecar JSON 中提取 typography（字体、字号）、colors、rounded（圆角）、shadows 等允许值白名单（normalize_design_system）。审计中"颜色是否使用设计令牌""令牌使用是否一致"等判断，正是依据这套允许列表与实现中的实际取值做比对——这也解释了为什么 audit 能做到"可测量、可验证"，而不是凭观感下结论。

3.4 维度四：Responsive Design（响应式）

检查项包括：

• 固定宽度：硬编码宽度在移动端破裂；
• 触摸目标：交互元素小于 44×44px；
• 横向滚动：窄视口下内容溢出；
• 文本缩放：文字尺寸增大后布局崩坏；
• 断点缺失：没有移动端/平板变体。

0–4 评分：0=仅桌面（移动端崩坏）；1=主要问题（有些断点但多处失效）；2=部分（移动端可用但有粗糙边角）；3=良好（响应式，偶有触摸目标或溢出小问题）；4=优秀（流式布局、覆盖所有视口、触摸目标合规）。

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

这是最关键的维度，audit 要求：

• **运行内置检测器（Run the bundled detector）**并在上下文中逐一验证每条 finding；
• 寻找重复的实现捷径（repeated implementation shortcuts）、设计系统漂移（design-system drift）、误导性或装饰性内容（misleading or decorative content）、以及与无关产品可互换的结构（structure that is interchangeable with an unrelated product）；
• 把确定性发现（deterministic findings）与视觉判断分开，并指出误报（call out false positives）。

0–4 评分：0=系统性漂移；1=主要的重复性失败；2=若干已验证的问题；3=少量孤立问题；4=连贯且有意为之。

这里提到的 "bundled detector" 就是仓库中的 impeccable detect：crates/detect/src/lib.rs 中 ROOT_USAGE 描述为 detect [file-or-dir-or-url...] Scan for UI anti-patterns and design quality issues（crates/detect/src/lib.rs）。审计需要"在上下文中验证每个 finding"，意味着拿到 detector 的结论后要回到真实组件代码里确认其成立，并把纯视觉判断排除在确定性发现之外。

四、评分细则与防误报纪律

每个维度单独按 0–4 评分后，汇总为 Audit Health Score。审计协议特别强调几条纪律：

• 不要报告无法解释影响的 issue（why does this matter?）；
• 不要给出泛泛的建议（要具体、可执行）；
• 不要跳过正面发现（好的实践同样值得记录）；
• 不要忘记排优先级（不可能一切都是 P0）；
• 不要在未验证的情况下报告误报。

这些纪律与 detect 引擎的"确定性优先"设计互为表里：crates/detect/src/engines.rs 定义了两个引擎接缝——静态 HTML 引擎 HtmlEngine（crates/detect/src/engines.rs#L50-L59）与浏览器/URL 引擎 UrlEngine（crates/detect/src/engines.rs#L64-L73），而扫描选项 ScanOptions（crates/detect/src/engines.rs#L16-L30）携带 inline_ignores（是否尊重行内忽略注释）、design_system（DESIGN.md 治理的设计系统）、viewport（浏览器扫描视口）与 rule_pack（可插拔规则包，impeccable 二进制默认内置规则）。规则包实现在 crates/core/src/checks/ 下，按 css_scan.rs、html_patterns.rs、measures.rs、rules.rs、text_rules.rs 等模块组织，并有 crates/detect/tests/rule_pack.rs 与 crates/core/tests/rule_pack.rs 等测试套件守护行为。审计报告中的每一条确定性 finding 都可以回溯到这类可运行、可测试的规则之上。

五、生成审计报告（Generate Report）

5.1 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	修复薄弱维度即可
10–13	Acceptable	需要显著工作
6–9	Poor	需要大改造
0–5	Critical	根本性问题

注意表中第 3、4 行（Responsive Design 与 Theming）与原文档顺序一致；各维度"Key Finding"列应填写该维度最严重的问题，或 "--"。

5.2 Implementation Integrity Verdict（实现完整性裁决）

从这里开始写。Pass/fail 判定：该实现是否表达了一个连贯的、产品专属的系统？必须引用已验证的证据与 detector 的发现来支撑结论。这一节是整个报告的定调部分——先回答"产品是否自洽"，再谈具体缺陷。

5.3 Executive Summary（执行摘要）

• Audit Health Score：??/20（[评级区间]）
• 发现的问题总数（按严重度 P0/P1/P2/P3 计数）
• Top 3–5 个关键问题
• 推荐的下一步

5.4 Detailed Findings by Severity（按严重度的详细发现）

每个 issue 必须标注 P0–P3 严重度：

级别	名称	含义
P0 Blocking	阻塞级	阻止任务完成，立即修复
P1 Major	重大	显著困难或违反 WCAG AA，发布前修复
P2 Minor	次要	烦扰但存在变通方案，下一轮修复
P3 Polish	打磨	可修可不修，无实际用户影响，时间允许时修复

每个 issue 需要记录的字段模板：

• [P?] Issue name（问题名）
• Location：组件、文件、行号
• Category：Accessibility / Performance / Theming / Responsive / Implementation Integrity
• Impact：对用户的影响
• WCAG/Standard：违反的标准（如适用）
• Recommendation：如何修复
• Suggested command：推荐执行的命令（优先从命令白名单中选择，见下文）

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

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

• "Hard-coded colors appear in 15+ components, should use design tokens"（硬编码颜色出现在 15 个以上组件中，应改用设计令牌）
• "Touch targets consistently too small (<44px) throughout mobile experience"（移动端体验中触摸目标持续过小）

5.6 Positive Findings（正面发现）

记录做得好、值得保持与复制的实践。audit 协议明确要求 不要跳过正面发现——"celebrate what works"。

六、推荐动作（Recommended Actions）

按优先级顺序列出建议命令（P0 优先，然后 P1，再 P2）：

1. [P?] /command-name：简要描述（结合审计发现的具体上下文）
2. [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 作为收尾步骤；
• 各命令对应实现细节见 SKILL.md 的 Commands 表，以及各自参考文档：如响应式/跨设备问题映射到 adapt.md，性能问题映射到 optimize.md，动效问题映射到 animate.md，文案问题映射到 clarify.md，最终打磨映射到 polish.md。

展示完摘要后，还需向用户说明：

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 即可看到评分提升——这构成了"审计 → 修复 → 复测"的闭环。

重要提醒：报告要彻底但可执行。过多的 P3 issue 只会制造噪音，请聚焦于真正重要的问题。

七、审计闭环与命令生态

audit 位于 impeccable 技能生态的 Evaluate 环节，与 Refine（polish / bolder / quieter / distill / harden / onboard）、Enhance（animate / colorize / typeset / layout / delight / overdrive）、Fix（clarify / adapt / optimize）等命令共同构成完整工作流：audit 负责找出问题并分级，其余命令按映射关系接手修复，最后以 polish 收尾、复跑 audit 验证。命令元数据（触发场景、参数提示）统一维护在 command-metadata.json（crates/context/src/command-metadata.json 为同步镜像），可据此在 Agent 环境中做路由与提示。

适用前提：audit 的 Web 版检查项与检测器规则均针对浏览器端 UI 实现设计；原生项目应使用 audit.native.md，无浏览器工具链与 impeccable detect 适用。同时，审计报告中的确定性发现依赖 detector 的运行与上下文验证，任何未经验证的怀疑都不应写入正式结论——这既是报告质量的底线，也是"代码级审计"这一立场的直接体现。