impeccable `/impeccable audit` 原生审计指南：用代码级体检让 iOS / Android 应用告别"网页移植感"

/impeccable audit 是 Impeccable 技能体系中负责技术质量审计的命令。当目标项目是原生应用（iOS / Android / adaptive 跨平台应用）时，审计会自动切换到本文所讲解的原生变体 audit.native.md：它不评判美学品位，而是从源码出发（SwiftUI / UIKit / Compose / React Native / Flutter），以可验证的平台规则为标尺，对无障碍、性能、主题、平台一致性、自适应性五个维度打分并产出一份可直接驱动后续修复命令的完整报告。读完本文，你将掌握这套审计的完整流程、五大维度的 0-4 分评分标准、报告骨架的每一节写法，以及"发现即记录、不代修"的闭环机制。

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

原文档开宗明义：native audit 的任务是 "Run systematic technical quality checks … and generate a comprehensive report. Don't fix issues; document them for other commands to address." 也就是说，审计只负责发现问题并写成报告，修复工作交给技能体系中其他命令（如 adapt、polish、optimize）按优先级执行。

它有三个关键限定：

• 从源码审计，而非运行态审计：审计对象是源码本身（SwiftUI / UIKit / Compose / React Native / Flutter），不使用任何浏览器工具，也不运行 detect.mjs 检测器——后者只服务于 Web 场景；
• 以平台参考文档为评分基准：iOS 对照 ios.md，Android 对照 android.md；adaptive（双端跨平台）应用两份都要读。如果 Setup 阶段尚未加载，评分前必须先读；
• 报告骨架与 Web 版保持一致：原生版报告结构与 audit.md 镜像对齐，修改其中一份时必须同步另一份。

路由机制：谁触发 native audit

在 Impeccable 的命令路由中，audit 是一个带平台变体的命令。其核心命令表定义于 SKILL.md：

命令	类别	说明	参考文档
audit [target]	Evaluate	技术质量检查（a11y、性能、响应式）	reference/audit.md · native: reference/audit.native.md

也就是说，Web 项目走 audit.md，而原生平台（ios / android / adaptive）自动路由到 audit.native.md。这一"路由而非共用"的行为已被仓库测试固定：在 tests/skill-behavior/scenarios.test.mjs 的 scenario 15（"native audit routes to the native command variant"）中，测试断言"当平台是 ios 时，agent 应当加载 audit.native.md（而不仅是 audit.md）"，通过 fileLoaded(trace, 'audit.native.md') 验证原生变体确实进入了模型上下文。

值得说明的是，本仓库在多个工具技能目录中维护了同一份参考文档（如 .vibe/skills/impeccable/reference/、skill/reference/、plugin/skills/impeccable/reference/ 等），本文以 .vibe/skills/impeccable/ 下内容为准，其余为面向不同 Agent 运行时的同源副本。

五大维度诊断扫描（Diagnostic Scan）

审计在 5 个维度上执行全面检查，每个维度按 0-4 分打分，评分标准逐维度定义如下。满分合计 20 分。

1. Accessibility（VoiceOver / TalkBack）

围绕屏幕阅读器与系统无障碍能力检查：

• 缺失标签：交互元素没有无障碍标签、traits/roles（特征/角色）或状态播报；
• 阅读与焦点顺序：遍历顺序不合逻辑、控件不可达、导航时丢失焦点；
• 文本缩放：iOS 用固定 point size 破坏 Dynamic Type，Android 用 px 而非 sp；大字号下布局被裁剪或重叠；
• 触控目标：小于 iOS 44 pt / Android 48 dp，或相互挤压无间距；
• 忽略 Reduce Motion：视差与大幅滑动没有交叉淡入替代方案；
• 对比度：在浅色或深色任一外观下文本对比度不达标。

评分锚点：0=屏幕阅读器完全不可用；1=重大缺口（无标签控件、不支持缩放）；2=部分可用（有标签但顺序或缩放出错）；3=良好（少量缺口）；4=优秀（标签齐全、顺序合理、缩放干净、遵循 Reduce Motion）。

2. Performance

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

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

3. Appearance & Theming

• 硬编码颜色：使用裸 hex 而不是 iOS 语义化系统色 / Android Material 颜色角色 / 设计令牌；
• 深色外观破损：缺少深色变体、深色下对比度差、"快速反相"式的偷懒实现；
• Dynamic Color（Android 12+）：没有静态回退方案，或在该使用处被忽略；
• 离平台的材质：系统材质（system materials）或色调式高度（tonal elevation）本可胜任之处，却手工堆砌视觉材质。

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

4. Platform Conformance（CRITICAL，最高优先级）

这是唯一标注 CRITICAL 的维度，直接对照已加载的平台参考文档（含其中的 slop tests）评分：

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

评分锚点：0=网页移植（毫无原生感）；1=严重违规（3-4 类）；2=有一些（1-2 处可察觉）；3=大体合规（细节瑕疵）；4=完全原生（熟练用户对每个界面都感到自然可信）。

5. Adaptivity

• 手机布局被拉伸：平板/iPad 渲染放大版手机 UI，而非使用 size classes / window size classes；
• 横屏破损：横屏内容被裁剪、被忽略，或无故锁定方向；
• 键盘/IME 处理：输入框被键盘遮挡、未做 inset 调整；
• 多任务：iPad Split View / Android 多窗口破坏布局；
• 折叠屏：Android 姿态变化（posture change）时布局对铰链（hinge）无感知。

评分锚点：0=只支持一种屏幕尺寸；1=重大破损（横屏或平板不可用）；2=部分适配；3=良好（少量边界情况）；4=优秀（跨尺寸、横竖屏与分屏窗口全面适配）。

评分规则书：ios.md 与 android.md 中的可验证细则

native audit 的评分并非空对空的主观判断，Platform Conformance 维度要求**"对照平台参考文档（含其 slop tests）打分"**。两份平台文档中沉淀了大量可落地的硬性阈值与判定准则，是审计时逐条核对的规则书。

iOS 细则（ios.md）

核心判定框架是 "The iOS slop test"：一个熟练 iPhone 用户是否会信任这个 App，还是在遇到不合规控件时犹豫？最具代表性的穿帮是"从网站移植而来"：重新发明的导航栏、自制的返回手势、Web 形态按钮、依赖 hover 的交互。默认使用平台组件，除非有用户会感谢你的理由才偏离。

可验证的硬性准则包括：布局必须落在 safe-area inset 内（不得压到刘海、Dynamic Island、Home 指示条与圆角）；2-5 个顶层栏目标签对应 2-5 个顶层分区（放的是分区而非动作），层级用导航栈、自足任务用 sheet；左缘右滑返回是肌肉记忆，绝不能禁用或遮挡；每个可点击控件最小 44×44 pt 且相邻目标间留出呼吸空间；字体使用系统文本样式（Large Title 到 Caption）走 Dynamic Type，不硬编码 point size（正文 Body 为 17 pt，11 pt 是下限）；颜色使用语义化系统色（label、secondaryLabel、systemBackground、separator、tint），裸 hex 在深色模式与增强对比度下会失效；深色模式是一等外观；交互元素由一个 tint color 统一驱动；图标只用 SF Symbols；转场使用系统 push/sheet 动效；Reduce Motion 时应以交叉淡入替代视差与大幅滑动。

值得注意，ios.md 还给出了真机/模拟器验证方式：截图必须来自 Simulator 而非浏览器——用 xcrun simctl io booted screenshot <path> 捕获（多台设备运行时用 xcrun simctl list devices booted 中的 UDID 替换 booted，因为显示名可能重复而 UDID 不会），且深色模式与动态字体必须纳入验证流程：xcrun simctl ui booted appearance dark 切换外观，再在大字号下检查截断问题。这些正是审计报告对"截图取证"要求的平台侧支撑。

Android 细则（android.md）

"Android slop test"最典型的穿帮是"披着 Android 外皮的 iOS 应用"：照搬 iPhone 的底部导航、忽略系统返回手势的自绘返回箭头、Cupertino 形状的开关与对话框。Material 3 是规则书，品牌只能经由其主题机制表达。

可验证准则包括：导航随尺寸匹配（紧凑宽度用底部 Navigation bar 3-5 个目的地，展开宽度改用 rail 或 drawer，绝不在平板上原样放大手机底部栏）；系统 Back 永远可用，尊重预测式返回手势与返回键；edge-to-edge 下用 window insets（状态栏、导航栏、display cutout、IME insets）保证内容不被系统栏或键盘遮挡；每个触控目标最小 48×48 dp 且间距至少 8 dp；字号用 sp 而非固定 px，跟随系统字体设置；颜色用 Material 颜色角色（primary、on-primary、surface、surface-variant、secondary-container、outline、error），角色令牌自动解析深浅色与对比度变体；Dynamic Color（Material You）在 Android 12+ 上从壁纸派生 scheme 且需有静态回退；用标准 surface tonal levels 表达高度，不用任意投影；动效遵循 container transform、shared-axis、fade-through 等 Material 动效模式，并在系统开启 Remove animations 时用交叉淡入或瞬间切换。

对应地，android.md 给出的取证方式是 adb exec-out screencap -p > <path>（多设备时 adb -s <serial> 指定），深色主题用 adb shell cmd uimode night yes，字体缩放用 adb shell settings put system font_scale 1.3（用毕恢复 1.0）来暴露固定布局隐藏的文字裁剪。

跨端适配的"翻译表"

当审计对象是 adaptive 应用时，两份参考同时生效，且 adapt.native.md 中提供了一张常用的跨平台习语翻译表，帮助判断"是翻译还是移植"：

iOS	Android
Tab bar	Navigation bar / rail / drawer
Edge-swipe back、back chevron	Predictive Back 手势 / 按钮
Switch、segmented control、系统 pickers	Material switch、chips、Material pickers
Action sheet	Bottom sheet / Material dialog
SF Symbols、SF Pro、Dynamic Type	Material Symbols、Roboto、sp 缩放
语义化系统色、材质	Material 颜色角色、tonal elevation
系统 push/sheet 转场	Container transform、shared-axis、fade-through

产出报告（Generate Report）

诊断完成后，按固定骨架生成报告，该骨架与 audit.md 镜像一致。骨架包含以下小节，逐节说明其实战写法。

Audit Health Score（健康总分表）

用一张表格汇总五维得分与关键发现，并填入总分与评级区间：

#	维度	分数	关键发现
1	Accessibility	?	[最严重问题或 "--"]
2	Performance	?
3	Appearance & Theming	?
4	Platform Conformance	?
5	Adaptivity	?
合计		??/20	[评级区间]

评级区间：18-20 Excellent（只需小幅打磨）；14-17 Good（补齐弱项维度）；10-13 Acceptable（需要明显返工）；6-9 Poor（需要大改）；0-5 Critical（存在根本性问题）。

Platform Conformance Verdict（先写这一节）

原文档明确要求 "Start here"——报告先从平台一致性结论开始：这个应用读起来像原生应用，还是像移植的网站？ 逐条列出具体违规点，并且 "Be brutally honest"（务必坦诚，不粉饰）。

Executive Summary（执行摘要）

固定包含四要素：Audit Health Score ??/20（附评级区间）；按 P0/P1/P2/P3 严重度计数的问题总数；Top 3-5 关键问题；推荐的后续步骤。

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

每条问题都必须打上 P0-P3 严重度标签：

• P0 Blocking（阻塞）：阻止任务完成，立即修复；
• P1 Major（重大）：显著困难或违反平台指南，发布前必须修复；
• P2 Minor（次要）：恼人但存在绕行方案，下一轮修复；
• P3 Polish（打磨）：可修可不修，无真实用户影响。

每条发现的记录字段为：[P?] 问题名称；位置（Screen、文件、行）；类别（Accessibility / Performance / Theming / Conformance / Adaptivity）；影响（如何影响用户）；指南（违反的 HIG / Material 规则，如适用）；建议（如何修复）；建议命令（见下方命令白名单）。这与 Web 版审计对照 audit.md 的差异在于：Web 版引用 WCAG 与 Implementation Integrity，而 native 版引用 HIG（iOS 人机界面指南）与 Material 规范。

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

识别反复出现、指向系统性缺口的共性问题，而非一次性失误。原文档给的两个范例句式：

• "Hard-coded colors appear in 15+ screens, should use semantic colors"（15+ 个界面出现硬编码颜色，应改用语义色）；
• "Touch targets consistently below 44 pt throughout the tab bar and list rows"（标签栏与列表行全程低于 44 pt）。

Positive Findings（正面发现）

记录做得好的地方：值得保持并推广的好实践。原文档要求 "celebrate what works"，负面清单里也明确"Skip positive findings"是一条 NEVER 红线。

推荐动作（Recommended Actions）：只推荐白名单内的命令

报告收尾按 P0 → P1 → P2 顺序列出推荐命令，格式为：

1. [P?] /command-name：简要说明（结合审计发现的具体上下文）
2. [P?] /command-name：简要说明（具体上下文）

规则：只能从以下 19 个命令中推荐——/impeccable adapt、animate、audit、bolder、clarify、colorize、critique、delight、distill、document、harden、layout、onboard、optimize、overdrive、polish、quieter、shape、typeset。将每条发现映射到最合适的命令；若推荐了任何修复，必须以 /impeccable polish 收尾作为最后一步。

演示映射逻辑：Platform Conformance 违规（如 iOS 导航隐喻错乱）可交给 adapt（其原生变体 adapt.native.md 专门处理平台/尺寸间的重构）；深色模式与语义色缺失映射到 colorize；触控目标与字号问题可映射到 layout 或 typeset；列表卡顿与渲染浪费交给 optimize；音量过大、需要克制的动效映射到 quieter。

呈现摘要后，必须原样告知用户：

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.

IMPORTANT 提醒：报告要"thorough but actionable"——P3 问题过多只会制造噪音，聚焦真正重要的内容。

NEVER 清单：审计的红线

原文档以一份 NEVER 清单收尾，约束报告质量底线：

• 只报告问题却不解释影响（为什么这很重要？）；
• 给出空泛的通用建议（要具体且可执行）；
• 跳过正面发现（肯定做得好的部分）；
• 忘记排优先级（不可能每条都是 P0）；
• 未经核实就报告误报（no false positives without verification）。

闭环机制与仓库证据

这套 native audit 流程在仓库中并非孤立文档，而是有清晰的上下游闭环：

1. 上下文加载：会话开始时由 Setup 阶段运行 scripts/context.mjs（见 SKILL.md），加载 PRODUCT.md、DESIGN.md、界面简报，并在此场景下附带原生平台指导；原文档中"Read them before scoring if Setup hasn't already"正是对该机制的兜底。
2. 路由验证：如上文所述，tests/skill-behavior/scenarios.test.mjs 中的 scenario 14 验证"原生 iOS 项目上下文会加载 ios.md"，scenario 15 则钉死了"原生 audit 必须路由到 audit.native.md"这一行为，可作为回归守护；
3. 报告 → 修复 → 复评：audit 只记录、不修改，修复交给推荐命令，修复后再跑一次 /impeccable audit 验证分数提升，形成可持续的迭代循环。

对团队而言，最直接的落地方式是：把 audit.native.md 中五大维度清单当作 iOS/Android 发布前的代码评审 checklist，将 P0/P1 发现堵在发布前；把"平台参考文档评分"当作争论裁决器——任何关于"控件像不像原生"的分歧，都回到 ios.md/android.md 的 slop test 与硬性阈值（44 pt、48 dp、sp/Dynamic Type、safe-area/insets）上核对，让设计讨论有据可依。