用 `/impeccable audit` 执行代码级技术审计：五维 0–4 评分、P0–P3 严重度分级与可执行修复计划（impeccable 前端设计技能）

用/impeccable audit执行代码级技术审计：五维 0–4 评分、P0–P3 严重度分级与可执行修复计划（impeccable 前端设计技能）

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable

导读

/impeccable audit是 impeccable 前端设计技能中的 "Evaluate" 类命令，专门对 Web 前端实现执行代码层面的系统化技术检查（可访问性、性能、主题化、响应式、实现一致性），并产出一份带健康度评分与 P0–P3 严重度分级的综合报告。与直觉相反，它的职责是"发现问题并写成文档"，而不是"当场修复"——修复动作会留给 audit 报告中建议的其他命令去完成。读完本文，你将掌握 audit 的触发条件与原生平台分流规则、五个审计维度的检查点与 0–4 评分标准、报告骨架（健康度表、评级带、逐条 finding 字段）、严重度分级法则，以及"如何把 finding 映射到最合适的修复命令"的推荐动作规则，并看到它与仓库内检测器、hooks 与测试夹具的协作方式。

audit 是什么：技术审计，不是设计评审

参考文档 .gemini/skills/impeccable/reference/audit.md 开门见山地定义了 audit 的定位：

Run systematictechnicalquality 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.

这决定了 audit 的四个基本纪律：

1. 系统化、技术化：检查的是实现中"可度量、可验证"的东西，而非审美偏好；
2. 只报告、不修复：审计结果由其他命令按优先级去处理；
3. 代码级审计 ≠ 设计批评：它与同属 Evaluate 类的/impeccable critique分工明确——critique 是"带启发式评分的 UX 设计评审"，audit 则是"a11y / perf / responsive 等技术质量检查"，两者在 SKILL.md 的命令总表中分列两行；
4. Web only：如果项目是原生平台（ios/android/adaptive），要改走原生变体 audit.native.md（详见下文"原生平台分流"）。

在技能命令元数据 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."

其参数提示为[area (feature, page, component...)]——即可选定某个功能、页面或组件作为审计对象，而不是必须审计整个项目。用户表达"想做无障碍检查、性能审计、技术质量复查"时，audit 就是应当优先被路由到的命令。

触发方式与前置上下文

audit 属于 impeccable 技能的命令体系。在 SKILL.md 的 Commands 表中，audit [target]被归类为Evaluate，并显式链接到.gemini/skills/impeccable/reference/audit.md（原生平台则链接到audit.native.md）。其上游流程是：

• 每次会话先执行一次 Setup（context.mjs），加载PRODUCT.md、DESIGN.md、匹配的 surface brief 以及适用的原生平台指引；
• 命令路由由 routing.md 决定：用户显式或清晰暗示某个命令时，加载对应参考文档并执行；无参数时展示菜单而不是自动运行；
• Setup 若给出CONTEXT_STALE指令，按该指令处理即可，不必额外跑 doctor。

原生平台分流（Native routing）：audit.md 第 5 行规定——原生平台（ios/android/adaptive）应改走 audit.native.md；如果发现项目是原生的，应立刻切换。原生变体的审计维度与 Web 版一一镜像（Accessibility→VoiceOver/TalkBack、Performance、Appearance & Theming、Platform Conformance、Adaptivity），且明确要求"从源码审计（SwiftUI / UIKit / Compose / React Native / Flutter），不使用浏览器工具或detect.mjs，对照平台参考 ios.md / android.md 打分"。所以请勿把本页的浏览器端检查清单生搬硬套到原生项目上。

Diagnostic Scan：五个维度的检查点与评分标准

audit 的核心产出始于一次覆盖5 个维度的全面诊断扫描，每个维度按 0–4 打分，判断依据是下方给出的客观检查点。下面是 Web 版五个维度的完整检查清单与评分锚点。

1. Accessibility（A11y）

需要检查：

• 对比度问题：文本对比度 < 4.5:1（AAA 级别为 7:1）；
• 动效敏感度：prefers-reduced-motion需要一个"保留状态变化与层级关系的刻意替代方案"——要标记三种情况：全局0.01ms式一刀切 kill（把有用的反馈也毁掉了）、超过闪烁阈值的动画、会阻塞聚焦/阅读/任务完成的动效；
• 缺失 ARIA：交互元素缺少正确的 role、label 或 state；
• 键盘导航：缺少焦点指示、Tab 顺序不合逻辑、键盘陷阱（keyboard trap）；
• 语义化 HTML：标题层级不当、缺少 landmark、用 div 代替 button；
• Alt 文本：图片描述缺失或质量差；
• 表单问题：输入无 label、错误提示差、缺少必填指示。

0–4 评分锚点：0=完全不可访问（未过 WCAG A）；1=重大缺口（几乎无 ARIA 标签、无键盘导航）；2=部分达标（有部分 a11y 努力，但存在显著缺口）；3=良好（基本满足 WCAG AA，仅少量缺口）；4=优秀（完全满足 WCAG AA，接近 AAA）。

2. Performance

需要检查：

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

0–4 评分锚点：0=严重问题（布局抖动、一切未优化）；1=重大问题（无懒加载、动画昂贵）；2=部分优化，仍有缺口；3=总体已优化，可小幅改进；4=优秀（快速、精简、优化到位）。

3. Theming

需要检查：

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

0–4 评分锚点：0=完全没有主题化（一切硬编码）；1=几乎全硬编码，token 极少；2=部分达标（token 存在但使用不一致）；3=良好（使用了 token，仅少量硬编码值）；4=优秀（完整 token 体系，暗色模式完美工作）。

4. Responsive Design

需要检查：

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

0–4 评分锚点：0=仅桌面（移动端崩坏）；1=重大问题（有部分断点但大量失败）；2=部分达标（移动端可用但有毛边）；3=良好（响应式良好，仅触控目标或溢出的小问题）；4=优秀（流体布局、覆盖所有视口、触控目标正确）。

5. Implementation Integrity（CRITICAL，关键维度）

这一维度要求运行捆绑的检测器（bundled detector），并在上下文中逐条核实每个 finding，寻找：反复出现的实现捷径（shortcuts）、设计系统漂移、误导性或纯装饰性内容，以及"换个无关产品也能原样使用"的同质化结构。同时要求把确定性（deterministic）的检测结果与主观视觉判断分开，并主动指出误报（false positives）。

0–4 评分锚点：0=系统性漂移；1=反复的重大失败；2=存在若干经核实的问题；3=孤立的轻微问题；4=连贯且意图明确。

关于这里的"捆绑检测器"，参考 hooks.md 可以看到它在项目中的实际形态：检测器规则分两层运行（逐文件编辑的即时层 + 会话结束 Stop 事件的深扫层），支持通过.impeccable/config.json下的detector.ignoreRules/ignoreFiles/ignoreValues/designSystem.enabled过滤，也可用npx impeccable detect手动扫描（--no-config则绕开项目配置做裸扫）；routing.md 亦说明该检测器"作用于本地文件、无网络、无需 npx、只读 HTML/CSS"。检测器所瞄准的实现坏味道在仓库测试夹具 tests/antipatterns 中成对呈现——如should-flag.html/should-pass.html、css-in-prose-should-flag.html/css-in-prose-should-pass.html、jsx-should-flag.jsx/jsx-should-pass.jsx、cream-palette.html与pseudo-stripe.*、buried-raster.html、organic-clip-path.html、radial-spotlight-glow.html等，命名直接表达了"应被检出 vs 应放行"的期望行为，是理解 audit 第 5 维"确定性证据"的最佳实例来源。

关于得分合并的提醒

5 个维度各取 0–4 分，总分满分为20 分。Web 版报告表格中第五行（Implementation Integrity）被标记为 CRITICAL，其 verdict 应在报告中最先陈述（见下节"从这里开始"）。

Generate Report：输出一份可行动的报告

诊断扫描完成后，audit 进入报告生成阶段，报告骨架按固定顺序组织，任何部分都不可省略。

Audit Health Score（健康度汇总表）

（注意：Web 版表格列序为 Accessibility / Performance / Responsive Design / Theming / Implementation Integrity，原文档如此排列，实际填充时以文档为准。）

评级带（Rating bands）：

• 18–20 Excellent：仅需微调（minor polish）；
• 14–17 Good：修复薄弱维度；
• 10–13 Acceptable：需要大量工作（significant work needed）；
• 6–9 Poor：需要重大翻修（major overhaul）；
• 0–5 Critical：存在根本性问题。

Implementation Integrity Verdict（从这里开始）

报告要求"Start here"：先给出第 5 维的 pass/fail 结论——该实现是否表达了一个连贯的、产品专属的系统？必须引用经过核实的证据与检测器发现来支撑结论。把它放在最前，是因为它是区分"整体值得修补"与"需要推倒重来"的第一道闸门。

Executive Summary

执行摘要必须包含：

• Audit Health Score：??/20（对应评级带）；
• 问题总数（按 P0/P1/P2/P3 严重度计数）；
• Top 3–5 关键问题；
• 推荐的下一步。

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：推荐使用的命令（优先从下列命令白名单中挑选）：/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。

注意每个字段都必须给出可落地的具体内容，不能只报问题不解释影响、不能给泛泛的"请优化"式建议。

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

单独识别反复出现的问题——它们暴露的是系统性缺口，而不是偶发失误。文档给出两个典型句式供参考：

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

Positive Findings（正面发现）

报告同样要求记录做得好的地方：值得保持与复制的良好实践。文档明确禁止"跳过正面发现"——celebrate what works。

Recommended Actions：把问题映射到修复命令

推荐动作按优先级排序（P0 优先，再 P1，再 P2），每个动作格式为：

1. [P?]/command-name：一句话描述（务必带上来自审计发现的具体上下文）

硬性规则：

• 只能从上述 19 个命令白名单中推荐，并把 finding 映射到最合适的命令；
• 若推荐了任何修复，最后一步必须以/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 auditafter fixes to see your score improve.

这形成了 impeccable 的审计闭环：audit 只做诊断与排期，修复交给具体命令分批执行，完成后重跑 audit 验证分数提升。这种"检测器给确定性证据、报告给分级、命令白名单给修复路径"的设计，与 polish.md 中"检测器结果是缺陷证据、不是质量的证明；干净扫描不能替代视觉判断"的原则一脉相承。

报告纪律：NEVER 清单

audit.md 以一段 NEVER 清单收尾，约束报告的撰写质量：

• 不要在解释影响之前就报告问题（why does this matter?）；
• 不要给出泛泛的推荐（必须具体、可执行）；
• 不要跳过正面发现；
• 不要忘记优先级排序（不可能每条都是 P0）；
• 不要不经验证就上报误报。

文档最后还强调："Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters."——报告应当详尽但可行动，过多 P3 噪音反而削弱报告价值，要把火力集中在真正影响用户与交付质量的发现上。

与检测器、hooks 及其他命令的分工

把 audit 放回 impeccable 整体来看，能更清楚地理解它的边界：

• audit 与 hooks 的关系：设计检测器 hook（见 hooks.md 与 plugin/hooks/hooks.json）在每次 UI 文件编辑后自动执行"即时层"规则，在会话停止事件执行"深扫层"；而 audit 是一次性的、跨五维度的全面人工-自动混合审查，二者证据同源（同一检测器），但用途不同——hook 拦截编辑，audit 产出健康度报告。对审计第 5 维而言，运行检测器、逐条核对 finding、区分确定性与主观判断，是报告成立的前提。
• audit 与 optimize 的分工：/impeccable optimize只聚焦 UI 性能（加载、渲染、动画、图片、包体积），而 audit 第 2 维只是五个维度之一；若 audit 报告里性能维度大面积失分，Recommended Actions 里自然会映射出/impeccable optimize。
• audit 与 critique 的分工：critique 走"设计评审 + 检测器/浏览器证据"双轨并强制隔离（见 critique.md），产出的是 UX 启发式评分；audit 则明确拒绝设计批评，只对可测量的实现质量负责。
• audit 与 polish 的分工：polish 是发布前的最终质量收尾并"直接修复"，audit 是"只记录、不修复"；因此 Recommended Actions 以/impeccable polish收尾是自然的流水线衔接——audit 排期，polish 兜底。

实战速查：一次完整的 audit 会话流程

把全文浓缩为可执行流程，方便你在真实项目中照做：

1. 确认平台：项目是ios/android/adaptive？是则切换到 audit.native.md，并先读平台参考 ios.md / android.md；
2. 加载上下文：先读PRODUCT.md、DESIGN.md与 surface brief（由 Setup 的 context.mjs 负责加载并给出指令）；
3. 五维扫描：按上文清单逐维检查，每个维度记 0–4 分与最关键 finding；
4. 跑检测器：对 Web 项目运行捆绑检测器（例如按 hooks.md 描述的手动detect扫描），并在上下文中核实每一条命中，分开确定性与视觉判断，标记误报；
5. 填报告骨架：先给 Implementation Integrity Verdict（Start here），再给健康度表（总分 ??/20 + 评级带）→ Executive Summary → 按严重度的详细 findings（每条含 P 级、Location、Category、Impact、WCAG/Standard、Recommendation、Suggested command）→ Patterns & Systemic Issues → Positive Findings；
6. 排期修复：按 P0→P1→P2 推荐白名单命令，若推荐了修复则以/impeccable polish收尾，并把"可逐个运行、一起运行、任意顺序运行；修复后重跑/impeccable audit看分数提升"的提示原样转达用户；
7. 保持克制：解释每条 finding 的影响、给出具体而非泛泛的修复建议、不遗漏正面发现、控制 P3 噪音、误报必须标注。

遵循以上流程，/impeccable audit就能把一次主观的"这界面哪里不行"变成一份带 20 分制健康度、评级带、P0–P3 严重度与白名单修复路径的工程化报告，让修复工作有据可依、可按优先级推进，并通过"修复 → 重跑 audit"的循环持续逼近 Excellent 区间。

【免费下载链接】impeccableThe design language that makes your AI harness better at design.项目地址: https://gitcode.com/GitHub_Trending/im/impeccable