impeccable 原生端技术审计指南：为 iOS / Android / adaptive 应用运行 /impeccable audit 五维代码级质检

在 impeccable 的 19 个命令中，/impeccable audit 是对前端实现做代码级技术体检的评估命令：它不修改任何代码，而是扫描实现的真实缺陷，输出带 P0–P3 严重度分级与可执行修复计划的评分报告，交给其他命令去修。当目标平台是原生应用时，审计执行者并不会照搬 Web 版审计手册，而是切换至本文讲解的 .hermes/skills/impeccable/reference/audit.native.md 原生变体手册。读完本文，你将完整掌握这套针对 SwiftUI / UIKit / Compose / React Native / Flutter 源码的五维诊断方法论、0–4 评分准则、报告生成规范与命令推荐白名单，从而能在原生项目上跑出一份既有客观分数又有可追溯修复路径的审计报告。

一、这是一份什么样的审计：定位与适用边界

/impeccable audit 定位为"systematic technical quality checks"，即系统化的技术质量检查。audit.native.md 在开头就划定了边界：

• 代码级审计，而非设计评审（"This is a code-level audit, not a design critique"）。它检查的是实现中可度量、可验证的东西，而不是审美偏好。
• 只记录问题，不负责修复（"Don't fix issues; document them for other commands to address"）。修复动作由 adapt、colorize、animate、optimize 等其他命令承接，审计的产出是问题清单与修复建议。
• 审计对象是源码：SwiftUI / UIKit / Compose / React Native / Flutter 均在被检之列；不使用任何浏览器工具链，detect.mjs（Web HTML/CSS 检测器）与 live 模式对原生代码完全不适用——这一点在 routing.md 中同样被强调："live and the bundled detect.mjs are web-only."

原生变体的存在缘由在仓库根目录的 CLAUDE.md 中有明确记载：当某个命令的原生指导与 Web 版差异过大、无法共享同一份文件时，就为它建立 native variant（reference/<command>.native.md）。目前拥有原生变体的只有两个命令：audit 与 adapt。audit.native.md 的报告骨架与 Web 版 audit.md 保持镜像同步，改动时必须两份一起改——这是被写进 CLAUDE.md 的硬性约定，也是命令路由的设计约束。

何时触发这份手册

原生变体由 SKILL.md 的 Commands 表登记为 audit 一行的"native:"引用，当 setup.platform 报告平台为 ios、android 或 adaptive（跨平台应用）时，Setup 第 2 步要求读取原生变体替代 Web 版执行。Web 版 audit.md 首行带有一条 "Web only." 的路由守卫：

Web only. Native platforms (ios / android / adaptive) route to audit.native.md instead; if the project is native, switch to it now.

这条"读 audit.md 后经守卫切换到原生变体"的行为被测试固定下来：仓库测试 scenarios.test.mjs 的 Scenario 15（native audit routes to the native command variant） 用一个包含 PRODUCT.md 与 TideDetailView.swift 的 iOS 工作区，以 /impeccable audit the app in this workspace 触发一轮 agent 会话，断言其必须执行 context.mjs 并最终加载 audit.native.md——"永不抵达原生变体即为失败"。

关于 adaptive 平台的评分对象

对于 adaptive（例如同一套 Flutter/React Native 代码同时发往两端的跨平台应用），审计要同时对照两份平台参考：iOS 的 ios.md 与 Android 的 android.md。若 Setup 尚未加载，评分前必须先自行通读它们。iOS 参考规定了 HIG 维度（44×44 pt 触控、Dynamic Type 系统文本样式、语义系统颜色、SF Symbols、Reduce Motion、edge-swipe back 等），Android 参考则规定 Material Design 3 维度（48×48 dp 触控、sp 字号、Material 色彩角色、Dynamic Color / Material You、tonal elevation、预测式返回、edge-to-edge window insets、折叠屏等）。平台一致性维度（第 4 维）的评分必须"Score against the loaded platform reference(s), including their slop tests"——两个平台参考文档各自内置了一道 slop test（"搬运网站"或"iOS 换皮"识别测试），它们共同构成一致性打分的验收标尺。

二、诊断扫描：五个维度与 0–4 评分准则

审计在 5 个维度上运行全面检查，每个维度按以下标准打分 0–4。注意这是对整个项目/目标的连续分值，不是通过/不通过的二分，0–4 分别代表从"彻底崩坏"到"接近卓越"的程度。

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

• 缺失标签：交互元素缺少无障碍标签（accessibility labels）、特征/角色（traits/roles）或状态播报（state announcements）；
• 阅读与焦点顺序：遍历顺序不合逻辑、控件不可达、导航后焦点丢失；
• 文本缩放：iOS 用固定 point size 破坏 Dynamic Type，Android 用 px 而非 sp；大字号下布局裁切或重叠；
• 触控目标：低于 iOS 44 pt / Android 48 dp，或排布拥挤无间距；
• 忽略 Reduce Motion：视差与大位移滑动没有 crossfade 之类的替身方案；
• 对比度：亮/暗任一外观下正文对比度不达标。

0–4 评分：0=读屏完全不可用；1=重大缺口（控件无标签、不支持缩放）；2=部分达标（有标签但顺序或缩放失效）；3=良好（仅个别小缺口）；4=优秀（有标签、有序、缩放平滑、遵守 Reduce Motion）。

维度 2：性能

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

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

维度 3：外观与主题（Appearance & Theming）

• 硬编码颜色：用原始 hex 而不用语义系统色（iOS）/ Material 色彩角色（Android）/ 设计令牌；
• 暗色外观破损：缺少暗色变体、暗色下对比度差、粗暴反色（quick inverts）；
• Dynamic Color（Android 12+）：没有静态兜底 scheme，或在合适场景中忽略了它；
• 非平台材质：在应该使用系统材质或 tonal elevation 的位置手搓视觉材质。

0–4 评分：0=全部硬编码；1=令牌极少；2=部分达标（有令牌但使用不一致）；3=良好（仅个别残留硬编码值）；4=优秀（全程语义化，亮暗两套外观皆为一级公民）。

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

这是五个维度中唯一被标注 CRITICAL 的维度，评分必须**对照已加载的平台参考（含其 slop test）**进行：

• 系统手势被破坏：iOS 被禁用的右边缘返回手势（edge-swipe back）；Android 被劫持的预测式返回（predictive Back）；
• 安全区违规：内容顶到刘海、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=完全原生（熟练用户对每个屏幕都感到自然可信）。

维度 5：自适应（Adaptivity）

• 手机布局被拉伸：平板/iPad 渲染的是等比放大的手机 UI，而未使用 iOS size classes / window size classes；
• 横竖屏破损：横屏裁切、被忽略或无理由锁定方向；
• 键盘/IME 处理：输入框被键盘遮挡、无 insets 调整；
• 多任务：iPad Split View / Android 多窗口下布局破坏；
• 折叠屏：Android 折叠形态/姿势变化时布局不知 hinge（铰链）存在。

0–4 评分：0=只支持一种屏幕尺寸；1=重大破损（横屏或平板不可用）；2=部分达标；3=良好（个别边缘情况）；4=优秀（跨尺寸、方向与多窗口形态都自适应良好）。

三、生成报告：结构骨架与撰写规范

报告骨架与 Web 版 audit.md 镜像同步——两处模板共用同一结构，修改骨架时必须在两份文件里一起改。报告由以下部分组成。

1. Audit Health Score（审计健康分）

五维各打 0–4 分，总分 20 分制，每行还必须给出该维度最关键的发现（Key Finding），没有就用 --：

#	Dimension	Score	Key Finding
1	Accessibility	?	[most critical issue or "--"]
2	Performance	?
3	Appearance & Theming	?
4	Platform Conformance	?
5	Adaptivity	?
Total		??/20	[Rating band]

评级带（Rating bands）：

• 18–20：Excellent（仅需微抛光）；
• 14–17：Good（修薄弱维度）；
• 10–13：Acceptable（需要大量工作）；
• 6–9：Poor（需大改）；
• 0–5：Critical（存在根本性问题）。

2. Platform Conformance Verdict —— 必须从这里开始写

Start here. 平台一致性裁决是报告的开场：给出通过/不通过的结论——这份实现读起来像原生应用，还是像搬过来的网站？逐条列出具体违规。手册要求 "Be brutally honest"，即对违规零粉饰。之所以把它的裁决放在 Exec Summary 之前，是因为"是否原生"是审计结论中最根本的分野：Web 移植痕迹往往同时解释无障碍、外观与自适应各维度的系统性问题。

3. Executive Summary（执行摘要）

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

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

每条发现必须打上 P0–P3 标签，严重度语义如下：

• P0 Blocking：阻断任务完成，立即修复；
• P1 Major：显著使用困难或违反平台指南（native 变体措辞为 platform-guideline violation；对应 Web 版措辞为 WCAG AA 违规），发布前必须修复；
• P2 Minor：令人不快、但有变通方案，下一轮迭代修复；
• P3 Polish：可修可不修、无实际用户影响，有时间再修。

每条发现需逐项记录以下字段：

• [P?] Issue name（问题名称）
• Location：屏幕（Screen）、文件（file）、行号（line）
• Category：Accessibility / Performance / Theming / Conformance / Adaptivity
• Impact：对用户的实际影响
• Guideline：违反的 HIG / Material 规则（如适用）
• Recommendation：修复建议
• Suggested command：建议交由哪个命令处理（从命令白名单中挑选）

5. 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"（tab bar 与列表行中的触控目标持续低于 44 pt）。

一条孤立问题可能是失误，但同一种问题跨屏高频出现，就指向令牌体系、组件基类或设计系统层面的结构性缺口——这才是审计真正要捕获的信号。

6. Positive Findings（正向发现）

记录做得好的地方：值得保持与复制的良好实践。手册明确将"跳过正向发现"列为禁忌（见文末 NEVER 清单），因为正向发现既是对既有工作的确认，也为后续改动提供了"不要破坏它"的参考基线。

四、Recommended Actions：白名单命令的优先级编排

修复建议按严重度排序输出（先 P0 再 P1 后 P2），每条包含命令与结合审计上下文的简短说明：

1. **[P?] `/command-name`**: Brief description (specific context from audit findings)
2. **[P?] `/command-name`**: Brief description (specific context)

白名单约束（Rules）：只能推荐以下命令，并把每条发现映射到最合适的命令——/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 收尾作为最后一步。修复方向与命令的对应逻辑很清晰：布局/安全区/自适应问题交给 adapt，动效与 Reduce Motion 问题交给 animate，硬编码颜色交给 colorize，排版交给 typeset，性能交给 optimize，交互细节留给 layout 与 shape，文案问题归 clarify，需要把强度调上去或压下来则用 bolder / 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.

这构成了审计的闭环：审计本身不修代码，但给出了一条可执行路径，修复后重新跑 audit 即可看到分数上升。仓库根目录的 CLAUDE.md 与 SKILL.md 的 Commands 表都延续了这套"Evaluate（评估）→ 建议其他 Refine/Fix/Enhance 命令 → polish 收尾"的分工模型，audit 在表内归属 Evaluate 类别，与同类的 critique（UX 设计启发式评审）区分——critique 评体验与美学，audit 查实现与技术债。

五、命令路由与多副本：手册如何在仓库中落地

结合仓库源码可以看清这份手册的运行机制与测试背书：

1. 注册：.hermes/skills/impeccable/SKILL.md 的 Commands 表中 audit 一栏登记为 "audit [target] | Evaluate | Technical quality checks (a11y, perf, responsive) | reference/audit.md · native: reference/audit.native.md"。副本 skill/SKILL.src.md 与 plugin/skills/impeccable/SKILL.md 中的登记保持一致。
2. 路由守卫：Web 版 audit.md 携带 "Web only." 一行守卫，把原生读者重定向到原生变体；CLAUDE.md 指出这是 native variant 的既定设计——"their web files carry a one-line web-only guard that redirects stray native readers"。
3. 行为被测试钉死：tests/skill-behavior/ 目录下的行为测试把"原生平台必须加载 audit.native.md（而非止步于 audit.md）"固化为断言（见 scenarios.test.mjs）；README.md 的矩阵将其列为第 15 号场景 "same iOS fixture; prompt is /impeccable audit; agent loads reference/audit.native.md (the Commands-table native variant, routed instead of audit.md)"。
4. 命令元数据：命令级描述登记在 command-metadata.json："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."，参数提示为 [area (feature, page, component...)]。
5. 多副本差异（模板化占位符）：仓库同时存在三份同名手册——.hermes/skills/impeccable/reference/（运行时工作副本）、skill/reference/（技能源）与 plugin/skills/impeccable/reference/（插件打包副本）。对比可见它们在"推荐命令清单"的书写方式上存在差异：.hermes 与 plugin 副本内联了完整命令列表，而 skill/reference/audit.native.md 保留了 {{available_commands}}、{{command_prefix}} 之类的模板占位符，交由打包环节替换——这解释了为何文中关闭语从 {{command_prefix}}impeccable audit 解析为 /impeccable audit。

六、写报告的纪律：NEVER 清单与实操提醒

手册最后列出写作铁律，也是防幻觉与防噪音的自检清单：

NEVER：

• 只报问题不解释影响（why does this matter?）；
• 给出泛泛而谈的建议（要具体、可执行）；
• 跳过正向发现（做得好的要庆祝/记录）；
• 忘记排优先级（不可能一切都是 P0）；
• 未经核验就报告假阳性。

另外两条收尾提醒同样值得执行者牢记：

• "Be thorough but actionable. Too many P3 issues creates noise. Focus on what actually matters." —— 报告必须详尽但可行动，P3 问题堆积会产生噪音，聚焦真正要紧的事。这与 Web 版 audit.md 的行文逐字一致，再次印证两份骨架必须同步。
• 报告是建议层而非裁决层：每条 Suggested command 只决定"该问题由哪个命令接管修复"，真正动手的仍是用户主动发起的后续命令——审计永不越权直接改码。

最后，回归这份手册的用途边界做一次总结：它是 impeccable 的 audit 命令在原生平台的执行剧本，从"读哪个平台参考、按哪五维打分、用什么评级带收敛分数、按何种字段书写每条 P0–P3 发现、从哪个白名单推荐命令"一路规定到"何时以 polish 收尾、向用户复述哪句闭环话术"。配合仓库中的平台参考（ios.md、android.md）、命令路由文档（SKILL.md、CLAUDE.md）以及行为测试（scenarios.test.mjs），你可以完整复现 impeccable 对原生应用的技术审计闭环，并让修复后重跑的分数成为可量化的改进证据。