impeccable 原生应用代码级审计指南：用 /impeccable audit 对 iOS / Android App 做 5 维技术质检

本文讲解 impeccable 设计语言技能库中面向原生应用（iOS / Android / adaptive）的 audit.native 代码级技术审计指令：它如何在 SwiftUI、UIKit、Jetpack Compose、React Native、Flutter 等源码上运行系统化质量检查、按 5 个维度给出 0–4 分、产出一份带 P0–P3 严重度分级的完整审计报告，并把问题映射回 /impeccable 修复命令闭环。读完你就能亲手复现一次"从诊断扫描到报告生成再到命令推荐"的完整原生审计流程，并理解其与 Web 版 audit 的分工边界。

审计的边界：代码级技术质检，不是设计批评

audit.native.md 开篇就框定了两个核心纪律：

• 只审计、不修复：对原生应用（ios / android / adaptive）运行系统化的技术质量检查并生成综合报告，发现的问题被记录在案，交给其他命令去处理，本指令自身绝不动手改代码。
• 代码级而非设计批评：这是从源码（SwiftUI / UIKit / Jetpack Compose / React Native / Flutter）出发的检查，不适用任何浏览器工具，也不运行 detect.mjs——因为浏览器规则引擎与 HTML/CSS 检测器读不懂原生代码。

这条指令在指令编排中承担"体检/质检"角色，与修复型指令形成"检查→修复→复查"闭环；Web 项目的同类职责由 audit.md 承担。两者刻意保持结构同步——audit.native.md 明确指出"报告骨架镜像 audit.md，改动时要保持二者一致"，从而让同一套报告语言横跨 Web 与原生两条审计路径。

在 routing.md 描述的无参数 /impeccable 上下文菜单中也能看到同样的分界逻辑：当 setup.platform 为 ios、android 或 adaptive 时，live 与内置 detect.mjs 一律不推荐，因为"浏览器覆盖层和 HTML 规则引擎不适用于原生应用代码"——这正是 audit.native 存在的理由。

评分基准：先读平台参考文档再打分

原生审计的独特之处在于有明确的平台规则书作为评分基准：

• 针对 iOS 项目，对照 ios.md（iOS/iPadOS：SwiftUI、UIKit、React Native、Expo、Flutter）评分；
• 针对 Android 项目，对照 android.md（Jetpack Compose、Android Views、React Native、Expo、Flutter）评分；
• 针对 adaptive（跨平台自适应）项目，两份参考文档都要读。

如果 Setup 环节还没有加载这些参考，审计执行前必须先通读它们再打分。这些平台文档不只是泛泛的设计偏好，而是可判定的规则。以两个平台的共同关注点为例：

• "slop 测试"（平台可信度试金石）：iOS 的提问是"熟练的 iPhone 用户会信任这个 App，还是会在不规范的控件前迟疑"，典型败笔是"从网站移植"——重新发明导航栏、自定义返回手势、Web 形状的按钮、依赖 hover 的提示；Android 版最常见的败笔则是"穿着 Android 外衣的 iOS App"：照搬 iPhone 的底部导航、无视系统 Back 手势的返回箭头、Cupertino 形状的开关和对话框。
• 触控目标硬指标：iOS 要求每个可点击控件最小 44×44 pt 且相邻目标留出呼吸空间；Android 要求最小 48×48 dp、间距至少 8 dp。
• 验证工具链：iOS 用 xcrun simctl io booted screenshot 从模拟器截图、xcrun simctl ui booted appearance dark 切换深色外观；Android 用 adb exec-out screencap -p 截图、adb shell cmd uimode night yes 切换深色主题、adb shell settings put system font_scale 1.3（用后还原 1.0）放大字体验证截断。两条路径都强调：截图必须来自模拟器/真机而非浏览器，且"模拟器提供广度，姿态、手势与性能需要真机"，报告要如实说明证据来源。

audit.native 的「Platform Conformance」维度就是在这些规则之上打分，包括其 slop 测试。

Diagnostic Scan：5 个维度的系统化诊断

audit.native 的检查主体是 Diagnostic Scan，对 5 个维度做全面检查，每个维度按 0–4 打分。五个维度与 Web 版 audit.md 的「Accessibility / Performance / Theming / Responsive / Implementation Integrity」形成镜像对应（响应式替换为原生特有的 Adaptivity、Theming 换成 Appearance & Theming、Implementation Integrity 换成 Platform Conformance），这正是两份文档需要保持同步的结构骨架。

维度一：Accessibility（VoiceOver / TalkBack）

无标签交互元素（缺无障碍标签、traits/roles、状态播报）、不合理的阅读与焦点顺序（遍历顺序不合逻辑、控件不可达、导航后焦点丢失）、文本缩放失效（iOS 用固定 pt 破坏 Dynamic Type，Android 用 px 而非 sp；大字号下布局被裁剪或重叠）、触控目标过小（低于 iOS 44 pt / Android 48 dp，或排列拥挤无间距）、无视 Reduce Motion（视差和大段滑动没有 crossfade 替代）、任意外观（浅色或深色）下文本对比度不达标。

0–4 分：0=读屏完全不可用；1=重大缺口（无标签控件、无缩放）；2=部分达标（有标签，但顺序或缩放有问题）；3=良好（少量小缺口）；4=优秀（有标签、顺序合理、可干净缩放、尊重 Reduce Motion）。

维度二：Performance

启动过慢（首帧前堆积重活）、列表未虚拟化（长内容没有 FlatList / LazyColumn / List 的回收机制）、主线程卡顿（滚动或手势路径上的同步工作、60/120 Hz 下掉帧）、无效渲染（React Native 多余 re-render、Compose 多余 recomposition、缺 memoization/keys）、图片处理不当（缩略图解码全尺寸图、无缓存）、应用体积（臃肿的 JS bundle 或二进制、无用依赖）。

0–4 分：0=处处卡顿；1=重大问题（未虚拟化列表、启动慢）；2=部分达标；3=良好（尚有可优化的点）；4=优秀（启动快、滚动顺滑、体积精简）。

维度三：Appearance & Theming

硬编码颜色（直接写原始 hex，而非 iOS 语义系统色 / Android Material 颜色角色 / design tokens）、深色外观损坏（缺深色变体、深色下对比度差、粗暴快速反色）、Dynamic Color（Android 12+ 的 Material You）缺失（没有静态 fallback 方案，或在合适的场景被忽略）、跨平台材料乱用（在期望系统材料或 tonal elevation 的地方手搓视觉材料）。

0–4 分：0=全部硬编码；1=tokens 极少；2=部分达标（有 tokens 但使用不一致）；3=良好（仅少量硬编码残留）；4=优秀（全程语义化，两种外观都是一等公民）。

维度四：Platform Conformance（CRITICAL，最关键）

对照已加载的平台参考文档（含其 slop 测试）评分。检查点包括：系统手势被破坏（iOS 禁掉边缘右滑返回、Android 劫持 predictive Back）、inset 违规（内容钻到刘海、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=完全原生（熟练用户信任每一个界面）。

维度五：Adaptivity

手机布局被拉伸（平板/iPad 渲染放大版手机 UI，而非使用 size classes / 窗口尺寸类）、横屏损坏（横屏裁剪、被忽略或无故锁定）、键盘/IME 处理不当（输入框被键盘遮挡、无 inset 调整）、多任务（iPad Split View / Android 多窗口破坏布局）、折叠屏（Android 姿态变化时布局不感知铰链）。

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

Generate Report：从打分表到可执行的审计报告

诊断结束后进入报告生成阶段，报告由若干固定部件组成。

Audit Health Score 总表与评级区间

#	Dimension	Score	Key Finding
1	Accessibility	?	[最关键问题或 "--"]
2	Performance	?
3	Appearance & Theming	?
4	Platform Conformance	?
5	Adaptivity	?
Total		??/20	[Rating band]

评级区间：18–20 Excellent（仅需细节打磨）、14–17 Good（针对性补强薄弱维度）、10–13 Acceptable（需要明显投入）、6–9 Poor（需要大改）、0–5 Critical（存在根本性问题）。

Platform Conformance Verdict——从这一节开始写

报告的第一节必须是「平台一致性裁决」，先回答那个非黑即白的问题：这读起来像原生应用，还是一个移植来的网站？ 给出 pass/fail 结论并列出具体违规，且要"残酷地诚实"。之所以放在最前，是因为它决定整份报告的性质——若产品本质是 Web 移植，后面所有维度的修复优先级都要重新排序。

Executive Summary

• Audit Health Score：??/20（附评级区间）
• 问题总数（按 P0/P1/P2/P3 统计）
• Top 3–5 关键问题
• 建议的下一步

Detailed Findings by Severity（P0–P3 严重度体系）

每个问题都必须打上 P0–P3 标签：

• P0 Blocking：阻断任务完成，立即修复
• P1 Major：造成明显困难或违反平台规范，发布前修复
• P2 Minor：烦人但存在绕行方案，下一轮修复
• P3 Polish：锦上添花，对用户无实质影响，有空再修

每条 issue 需要记录 7 项结构化信息：[P?] Issue 名称、Location（屏幕/文件/行）、Category（Accessibility / Performance / Theming / Conformance / Adaptivity 五选一）、Impact（对用户的影响）、Guideline（违反的 HIG / Material 规则，若有）、Recommendation（如何修复）、Suggested command（建议用哪个 /impeccable 命令，仅限白名单内的命令）。

Patterns & Systemic Issues

识别反复出现的问题——它说明是系统性缺口而非一次性失误。文档给的原型句式很有代表性：

• "硬编码颜色出现在 15+ 个界面中，应改用语义色"
• "tab bar 与列表行的触控目标始终低于 44 pt"

一条孤立的问题不值得上这个清单；只有当同一缺陷横跨多个界面时，才说明根因在主题系统、组件库或规范缺失，修复要落在系统层面而非单个控件上。

Positive Findings

别忘了记录做对的地方——值得保持和复制的良好实践。这一点被写进报告的"NEVER"纪律（不许跳过正面发现），因为只有知道什么在正常工作，修复命令才不会顺手破坏它。

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 收尾。

从白名单也能反推各命令的分工：colorize 承接硬编码颜色与主题问题，layout 承接布局/inset/自适应问题，typeset 承接字号与 Dynamic Type 问题，quieter 承接视觉噪音，animate 承接动效与 Reduce Motion，harden 承接健壮性，optimize 承接性能。审计只负责发现与分类，修复由这些专职命令完成——这正是"审计不改代码"纪律的落地方式。

给出清单后，还必须原样告知用户两件事：

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.

后者构成了完整的闭环：审计 → 修复 → 复查审计分数，用分数变化验证修复成效。

执行纪律：审计质量的自检清单

报告的 NEVER 清单是审计质量底线，逐条对照：

• 不许报告问题却不解释影响（为什么它在乎？）——每条 issue 的 Impact 字段是硬性要求；
• 不许给泛泛的建议——Recommendation 必须具体、可执行，能直接落到代码上；
• 不许跳过正面发现——正常工作的部分要记录和庆祝；
• 不许忘记优先级——不可能所有问题都是 P0，分级才有行动价值；
• 不许未经核实就报误报——结论要能对源码验证，宁可少报也不虚构。

此外还有一条总体性提醒："宁可详尽也要可行动，P3 问题过多只会制造噪音，聚焦真正重要的东西。"

将 native audit 接入你的工作流

在 impeccable 的指令体系中，audit.native 的使用方式与其他命令一致（在支持的 Agent 环境中通过 /impeccable audit 触发，由 Setup/上下文信号决定路由到 native 还是 Web 分支）。结合 routing.md 的编排逻辑可以确认几条实操要点：

• 触发场景：项目上下文（setup.platform）为 ios/android/adaptive 时，审计入口路由到本文档描述的 native 流程；git.changedFiles 指向某个原生模块时，可将 audit 范围精确聚焦到这些文件。
• 前置条件：执行前应确认已加载对应平台参考（ios.md / android.md，adaptive 两者都要），否则审计要先自行通读再打分。
• 迭代节奏：把报告里的 Recommended Actions 当作修复 backlog，按 P0→P1→P2 逐个执行、末尾补 /impeccable polish，然后重跑 audit 观察 5 维分数变化——这也是验证修复是否真正解决根因（而非掩盖症状）的客观手段。

需要深入了解某一维度的具体判据时，可直接阅读同目录的完整平台参考与 Web 版审计：.kiro/skills/impeccable/reference/ios.md、.kiro/skills/impeccable/reference/android.md、.kiro/skills/impeccable/reference/audit.md；该技能同样以镜像形式分发在 skill/reference/audit.native.md 与 plugin/skills/impeccable/reference/audit.native.md 等处供各 Agent 环境加载。