Impeccable 原生应用审计指南：audit.native 五维评分体系与 P0-P3 问题报告机制

在 Impeccable 这个面向 AI 编码代理的设计语言项目中，audit 命令承担技术质量审计职责，而 audit.native.md 是其中专门服务于原生平台（ios / android / adaptive）的审计剧本：它不修复问题，而是对原生应用的源码（SwiftUI / UIKit / Compose / React Native / Flutter）执行系统化检查，输出一份可追踪、可分派的评分报告。读完本文，你可以掌握这套 0-4 五维打分体系、P0-P3 严重度分级、报告骨架的完整结构，以及该剧本在 Impeccable 命令路由中如何被加载与使用。

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

audit.native 剧本开篇即明确了三条边界约束：

1. 只记录，不修复。发现问题后为其他命令留好"接口"，由后续命令（如 /impeccable adapt、/impeccable optimize）去处理；
2. 这是代码级审计（code-level audit），不是设计批评。只检查实现中可度量、可验证的内容；
3. 原生平台不走 Web 工具链。浏览器工具与 impeccable detect（基于 HTML/CSS 的确定性检测器）对原生代码均不适用。

评分必须对照平台参考文件执行：iOS 项目对照 ios.md，Android 项目对照 android.md，adaptive（双端自适应）项目则两者都对照；如果 Setup 阶段尚未加载过，打分前必须先读。报告骨架镜像自 Web 版 audit.md，两份文件在修改报告骨架时需要保持同步——仓库开发文档 CLAUDE.md 也专门规定了这一约定："audit.native.md 镜像 audit.md 的报告骨架；骨架改动必须两处一起改"。

从仓库结构看，这种"镜像"是刻意的设计：Web 版 audit.md 第 5 行带有一条 Web-only 守卫——"Native platforms（ios / android / adaptive）路由到 audit.native.md"，即当项目被识别为原生平台时，Web 文件会把读者立即切换到原生版本，反之亦然。

诊断扫描：五个维度的完整检查清单

剧本要求对 5 个维度各打 0-4 分，以下是每个维度的检查项与评分标准（完整继承自原文档）。

维度 1：无障碍（VoiceOver / TalkBack）

检查项：

• 缺失标签：交互元素没有无障碍标签、traits/roles 或状态播报
• 阅读与焦点顺序：遍历顺序不合逻辑、控件不可达、导航后焦点丢失
• 文本缩放：固定点字号击败 Dynamic Type（iOS），或用 px 代替 sp（Android）；大字号下布局被裁切或重叠
• 触控目标：小于 44 pt（iOS）/ 48 dp（Android），或排布拥挤无间距
• 忽视 Reduce Motion：视差与大幅位移动画没有 crossfade 替代方案
• 对比度：文本在浅色或深色任一外观下对比度不达标

评分 0-4：0 = 读屏完全不可用；1 = 重大缺失（无标签控件、无缩放支持）；2 = 部分达标（有标签，但顺序或缩放崩坏）；3 = 良好（轻微缺口）；4 = 优秀（有标签、顺序正确、缩放干净、尊重 Reduce Motion）。

这里的 44 pt / 48 dp 触控目标、Dynamic Type 与 sp 单位并非凭空设定，它们与平台参考文件一一对应：ios.md 明确要求"每个可点控件最小 44×44 pt、使用系统文本样式、11 pt 下限"，android.md 则要求"最小 48×48 dp、目标间距至少 8 dp、用 sp 而非固定 px"。

维度 2：性能

检查项：

• 启动慢：首帧前在启动路径上做重活
• 未虚拟化列表：长内容没有 FlatList / LazyColumn / List 回收机制
• 主线程卡顿：滚动或手势路径中有同步工作，60/120 Hz 掉帧
• 浪费的渲染：React Native 不必要重渲染、Compose 不必要重组；缺少 memoization / keys
• 图片处理：缩略图解码全尺寸图片、无缓存
• 应用体积：臃肿的 JS bundle 或二进制、未使用的依赖

评分 0-4：0 = 处处卡顿；1 = 重大问题（未虚拟化列表、启动慢）；2 = 部分达标；3 = 良好（仍有小改进空间）；4 = 优秀（启动快、滚动流畅、体积精简）。

值得注意的是该维度明确区分了框架语义："wasted rendering" 在 React Native 语境叫 re-render，在 Compose 语境叫 recomposition——审计时要用对应框架的正确术语定位问题。

维度 3：外观与主题

检查项：

• 硬编码颜色：原始 hex 值，而非语义系统色（iOS）/ Material 颜色角色（Android）/ 设计令牌
• 深色外观崩坏：缺深色变体、深色下对比度差、只是草率取色反转
• Dynamic Color（Android 12+）：没有静态回退方案，或在合适场景被忽略
• 平台外的材质：在应使用系统材质或 tonal elevation 的地方手搓视觉效果

评分 0-4：0 = 全部硬编码；1 = 极少令牌；2 = 部分（令牌存在但使用不一致）；3 = 良好（少量硬编码值）；4 = 优秀（全语义化，两种外观都是一等公民）。

android.md 进一步解释了为什么角色令牌是硬要求："Role tokens resolve light/dark and contrast variants automatically; raw hex breaks there"——语义角色能自动解析明暗与对比变体，裸 hex 值在切换外观时就会断裂。iOS 侧同理：ios.md 要求使用 label、secondaryLabel、systemBackground 等语义系统色，"它们会随 Dark Mode 与增强对比自动适配，裸 hex 做不到"。

维度 4：平台一致性（CRITICAL）

这是剧本中标注为 CRITICAL 的维度，要求对照已加载的平台参考文件打分，包括其中的 slop test（低质判定测试）。

检查项：

• 系统手势崩坏：边缘滑动手势返回被禁用（iOS）、预测性返回（predictive Back）被劫持（Android）
• 安全区违规：内容压在刘海、Dynamic Island、Home 指示条、状态栏或键盘之下
• 平台外导航：自定义全局导航、过载的 tab bar、iOS 模式出现在 Android 上或反之
• Web 化控件：HTML 风格的按钮、自定义开关、依赖 hover 的交互暗示
• 图标漂移：混用图标集，而非 SF Symbols / Material Symbols
• 系统漂移：反复出现与产品、平台或既定设计系统相冲突的快捷方式或装饰性模式

评分 0-4：0 = Web 移植版（毫无原生感）；1 = 大量违规（3-4 类）；2 = 若干（1-2 类明显）；3 = 基本一致（细微问题）；4 = 完全原生（熟练用户信任每一个屏幕）。

"slop test" 的具体措辞在两份平台参考中有清晰定义：iOS 版问"一个熟练的 iPhone 用户会信任这个 App，还是会被不合规格的控件绊住？典型信号是'从网站移植过来'：重造的导航栏、自定义返回手势、Web 化按钮、依赖 hover 的暗示"；Android 版则把最常见的信号定义为"一个穿了 Android 皮肤的 iOS App"——只出现在底部的导航栏、无视系统返回手势的返回箭头、Cupertino 风格的开关与对话框。这两份 slop test 就是本维度"pass/fail 判定"的验收标准。

维度 5：适应性

检查项：

• 拉伸的手机布局：平板 / iPad 渲染的是放大版手机 UI，而非基于 size classes（iOS）/ window size classes（Android）切换结构
• 横屏崩坏：横屏被裁切、被忽略，或无理由地被锁定
• 键盘 / IME 处理：输入框被键盘挡住、没有 inset 调整
• 多任务：iPad Split View / Android 多窗口撑破布局
• 折叠屏：Android 折叠屏在形态（posture）变化时布局不感知铰链

评分 0-4：0 = 只支持一种屏幕尺寸；1 = 重大崩坏（横屏或平板直接坏掉）；2 = 部分达标；3 = 良好（少量边缘情况）；4 = 优秀（跨尺寸、方向、窗口模式自适应）。

该维度的检查项与原生版 adapt 剧本 adapt.native.md 高度呼应——后者把"在平板上发布被拉伸的手机布局"列为 NEVER 条款，审计发现的这类问题正是交由 /impeccable adapt 处理的依据。

报告生成：从评分表到分派清单

扫描完成后，audit.native 剧本规定了一份结构固定的报告骨架（与 Web 版 audit.md 保持同步）。

审计健康分（Audit Health Score）

报告以一张汇总表开头：

#	维度	分数	关键发现
1	无障碍	?	[最关键的无障碍问题或 "--"]
2	性能	?
3	外观与主题	?
4	平台一致性	?
5	适应性	?
总分		??/20	[评级区间]

评级区间：18-20 优秀（仅需微调）；14-17 良好（处理薄弱维度）；10-13 可接受（需要大量工作）；6-9 差（需重大重构）；0-5 危急（根本性问题）。

平台一致性判定（Platform Conformance Verdict）

剧本要求这部分放在报告最前（"Start here"）：用 pass/fail 判定这个应用读起来像一个原生 App，还是像一个移植的网站，并列出具体违规项，"be brutally honest"。这与维度 4 的 CRITICAL 地位一致——对原生 App 而言，"像不像原生"优先于任何单项技术分数。

执行摘要（Executive Summary）

• 审计健康分：??/20（评级区间）
• 问题总数（按 P0/P1/P2/P3 计数）
• Top 3-5 关键问题
• 建议的下一步

按严重度分组的详细发现

每个问题必须标注 P0-P3 严重度：

• P0 阻断（Blocking）：阻止任务完成，立即修复
• P1 重大（Major）：显著困难或违反平台指南，发布前必须修复
• P2 轻微（Minor）：有 workaround 的不便，下一轮修复
• P3 打磨（Polish）：修了更好，对用户无实质影响，有时间再修

每个问题需记录以下字段：

• [P?] 问题名称
• 位置：屏幕、文件、行号
• 类别：无障碍 / 性能 / 主题 / 一致性 / 适应性
• 影响：如何影响用户
• 指南依据：违反的 HIG / Material 规则（如适用）
• 修复建议：如何修
• 建议命令：用哪个命令修——从 /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 中选择

注意与 Web 版的差异：Web 版 audit.md 的"指南依据"字段写的是 WCAG 标准，而原生版换成 HIG / Material Design 规则——同一个骨架，平台规则各归其位。

模式与系统性问题

识别反复出现的问题，区分"系统性缺口"与"一次性失误"，例如：

• "硬编码颜色出现在 15+ 个屏幕中，应改用语义颜色"
• "触控目标在 tab bar 和列表行中持续低于 44 pt"

正面发现

明确写出哪些地方做得好——值得保持和复制的实践。剧本把这条写进 NEVER 条款："不要跳过正面发现（celebrate what works）"。

推荐行动与闭环机制

报告末尾给出推荐行动列表，按优先级排序（P0 优先，然后 P1，再 P2）：

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

规则有三条：

• 只能从上述 19 个命令中推荐，把发现映射到最合适的命令；
• 如果推荐了任何修复，最后一步必须是 /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 打分 → 分派命令修复 → 重跑 audit 看分数上涨。

剧本还以"NEVER"条款收尾，定义了审计输出质量的下限：

• 不解释影响（这为什么重要）就不报告问题
• 不给泛泛的建议（必须具体、可执行）
• 不跳过正面发现
• 不忘记优先级（不可能一切都是 P0）
• 不报告未经验证的误报（"too many P3 issues creates noise. Focus on what actually matters."）

从源码看：audit.native 如何被路由与验证

理解了剧本内容本身，还值得看一下它在 Impeccable 命令体系中的加载机制，这解释了为什么它叫 audit.native.md。

路由机制：技能入口 SKILL.src.md 的 Commands 表格中，audit 一行同时列出了 Web 与原生两份参考："audit [target] | Evaluate | Technical quality checks (a11y, perf, responsive) | reference/audit.md · native: reference/audit.native.md"。配套的路由规则（同文件 Routing 小节）规定：当请求的命令显式或隐式匹配时，"load its reference（native variant on native platforms）"——即 setup.platform 为 ios、android 或 adaptive 时，加载的是 .native.md 变体而不是 Web 文件。开发文档 CLAUDE.md 对这一机制有更完整的描述："当某命令的原生指导与 Web 版差异大到无法共用一个文件时，就给它一个 native 变体 reference/<command>.native.md……当 setup.platform 是原生平台时，路由用变体替代 Web 文件。目前的变体：audit.native.md、adapt.native.md"，且"每个变体同时覆盖 ios、android、adaptive 三种平台；各 OS 的细节留在平台参考文件中，Setup 阶段无论如何都会加载"。

也就是说，audit.native 并不内置 iOS 或 Android 的细则，而是依赖 Setup 阶段加载的 ios.md / android.md 作为"评分标尺"——维度 4 的 slop test、触控目标数值、语义色要求都来自这两份平台参考。这也是原文档反复强调"读平台参考再打分"的原因。

行为测试佐证：仓库的行为测试 tests/skill-behavior/README.md 第 15 行用例明确验证了这一路由："同一 iOS fixture，prompt 是 /impeccable audit，断言 agent 加载 reference/audit.native.md（Commands 表格中的原生变体，替代 audit.md 被路由）"。这为"原生项目触发 audit 时确实走原生剧本"提供了自动化验证。

与 Web 检测器的分工：routing.md 中写明 "live and the bundled detect.mjs are web-only. If setup.platform is ios, android, or adaptive, don't lead with either; the browser overlay and the HTML rule engine don't apply to native app code"——这与 audit.native 开头"no browser tooling or impeccable detect applies"的约束互为印证：原生平台的质量检查完全依赖这份人工可执行的检查清单加平台参考，而非 HTML 规则引擎。

小结

audit.native 是 Impeccable 面向原生 App 的技术审计剧本：五维检查（无障碍、性能、外观与主题、平台一致性、适应性）各打 0-4 分，总分 /20 落入五个评级区间；报告以平台一致性 pass/fail 判定开头，用 P0-P3 把每个问题分派到 19 个可执行的 /impeccable 命令之一，并以 /impeccable polish 收尾、重跑 audit 验证分数提升。对维护 AI 辅助原生开发流程的团队而言，这套"只审计不修复、报告即工单"的设计，让审计输出天然可被后续命令消费，而不需要人工转译。

如需继续深入，建议按以下路径阅读仓库：audit.native.md（本文主体）、audit.md（Web 版对照）、ios.md 与 android.md（评分标尺）、adapt.native.md（审计发现后的主要修复入口）、CLAUDE.md（native 变体机制的开发约定）。