ios-code-audit

iOS 代码审计技能

操作规则

• 只读调查，单一交付物。 不修改代码——输出文件为仓库根目录下的 CODE_AUDIT.md。
• 每项发现都要引用 path/to/file.swift:LINE（或行号范围）。 对于严重或高危问题，“整个代码库中”绝不是可接受的说法。
• 谨慎评定严重性。 严重意味着崩溃、数据丢失、内存损坏或安全暴露。不要夸大。请参阅下方的严重性指南。
• 传播任何严重问题前都要核实。 Agent 有时会夸大严重性。请打开所引用的文件，确认问题确实存在。如果无法通过阅读相关行复现所述问题，请降低严重级别或删除。
• 按根因分组，而非按发生位置分组。 如果缺少一个 @MainActor 注解导致七条警告，应将七处位置列为一项发现，而不是七项发现。
• 排除 Dead/（或任何明确归档的目录）。 启动 Agent 前，检查 CLAUDE.md / 项目 README 中是否列出任何“不要编辑”的目录。

工作流

步骤 1 — 确定代码库范围

快速统计数据，以便向 Agent 介绍项目：

find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" -not -path "*/Pods/*" -not -path "*/.build/*" | xargs wc -l 2>/dev/null | tail -1
find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" 2>/dev/null | wc -l
find . -name "*.metal" 2>/dev/null | wc -l

同时找出热点文件（代码行数最多、核心状态文件）：

find . -name "*.swift" -not -path "./.git/*" -not -path "./Dead/*" -exec wc -l {} \; | sort -rn | head -10

如果存在 CLAUDE.md，请阅读它——其中通常会标出核心状态文件（例如 AppState.swift、CaptureState.swift）、渲染管线以及任何明确排除的目录。

步骤 2 — 获取编译器基准事实

运行构建并提取所有警告。这将作为并发性 / 弃用部分审计的权威依据——你不应该需要猜测是否存在并发警告。

首选（已连接 Xcode MCP 时）：

mcp__xcode__XcodeListNavigatorIssues(tabIdentifier, severity: "warning")

它会返回包含 path、line、message、severity 的结构化列表。请去重（多目标编译会产生重复项），并按根因分类。

备用方案（通过命令行运行 xcodebuild）：

xcodebuild -project <Project>.xcodeproj -scheme "<Dev scheme>" -configuration Debug build 2>&1 \
  | grep -E "warning:" | sort -u

如果构建是增量构建（返回时间不到 2 秒），很可能跳过了大部分文件。请触碰每个目标下的一个 Swift 文件，或运行 clean build，以获取完整的警告集合。

步骤 3 — 并行启动三个 Explore Agent

一条消息，三次工具调用。 每个 Agent 都从 references/agent-prompts.md 获取一个专门的任务说明：

• Agent A — 并发性与 API 现代化。 向它提供步骤 2 中捕获的警告。
• Agent B — 死代码、重复代码、重构候选项。 向它提供热点列表，以及 CLAUDE.md 中提到的任何已知过时文件。
• Agent C — Bug、逻辑错误、安全、性能。 向它提供热点列表，以及用户特别指出的任何子系统（相机管线、IAP、API 客户端等）。

每份任务说明都要求遵循单项发现模板（见下文）。不要让 Agent 返回总结——要求提供具体的文件:行号发现。

步骤 4 — SwiftUI 专家审查（如果项目使用 SwiftUI）

如果项目包含 SwiftUI 视图，请在 Agent 返回结果后，单独调用 swiftui-expert-skill，审查范围限定为 Views/（或 SwiftUI 界面所在目录）以及共享 UI 辅助工具。具体检查：

• @State / @Bindable / @Observable 使用不当
• 修饰符顺序错误
• 应移出视图主体的工作（格式化器、解码器、排序）
• 辅助功能 / 动态字体大小 / 深色模式方面的缺失
• 高频路径上的叶视图缺少 Equatable
• Liquid Glass / iOS 26 采用机会（仅在用户要求时）

你可能需要自行阅读一些视图文件，以确认该技能发现的模式。

步骤 5 — 核实严重问题

撰写报告前，打开每项标记为严重的发现所引用的代码行并确认：

• 代码与 Agent 的描述一致。
• 影响判断属实（例如，如果 Agent 声称存在“内存损坏”，缓冲区是否确实过小？请追踪计算过程。）。
• 建议的修复方案合理。

这一步曾在以往审查中发现过严重性判断的幻觉。对未能证实的问题降低严重级别或删除。绝不要传播未经本人核实的严重问题。

步骤 6 — 综合整理 CODE_AUDIT.md

使用 references/report-template.md 中的骨架。

强制要求：渲染后的报告必须为每个标题添加章节编号。 这并非表面要求——编号是报告的主要接口。用户会提交类似“修复 §5.4”和“§3.1 完成了吗？”的问题；如果标题没有编号，他们就无法这样做。生成无编号报告属于缺陷，而不是风格选择。 无编号的报告将被拒绝。

编号规则：

• 顶级章节编号为 ## 1. 至 ## 12.——必须严格按照下方列出的顺序，即使某个章节没有发现问题也不能省略（此时应在标题下写上“No findings.”）。
• 每项发现都必须是带编号的子章节，格式为 ### N.M <short title>，其中 N 是父章节编号，M 从 1 开始递增。例如：### 5.1 Bundle.main.url 上的强制解包、### 5.2 缺少 .limited Photos 权限处理。绝不能将发现写成不带 N.M 前缀的 ### <short title>。
• 修改时编号必须保持稳定。 如果修订时移除了某项发现，应保留其编号，并在正文中写上 _REMOVED: <reason>_——不要重新编排剩余发现的编号，否则所有外部引用“§5.4”都会失效。
• 执行摘要条目（§1）应为有序列表 1.、2.……并引用对应发现的编号（例如：“[Critical] Bundle.main.url 上的强制解包 — §5.1 — path:line”）。
• 验证条目（§12）应通过子章节编号引用发现，例如：- **§5.1** — 打开 \path`，第 42-47 行。。不要保留模板中的 <N.M>` 占位符——请填写实际编号。

顶级章节及其顺序：

1. 执行摘要 — 影响最大的 5-10 项发现，每项占一行，标注严重级别并回链至 §N.M。
2. 快速修复 — 可在 30 分钟内完成的修复（删除过时文件、移除调试用的 print、修复未使用的 let 警告、添加无障碍标签）。
3. 并发
4. API 现代化 — 弃用 API、iOS 17+ 替代方案
5. 错误 / 逻辑错误
6. 安全性
7. 性能
8. SwiftUI / UI
9. 死代码 / 重复代码 / 重构
10. 跨领域建议 — 值得在整个代码库中采用的模式
11. 未审计内容 — 明确列出审计范围之外的内容
12. 验证 — 对每项 Critical / High 发现，列出能够证明该问题的确切代码行

每项发现的模板（注意前导 N.M）：

### N.M <short title>
- **Location:** `path/to/file.swift:LINE-LINE`
- **What:** <observed problem in one sentence>
- **Why:** <impact / why it matters>
- **Action:** <recommended fix; no code, reference patterns>
- **Severity:** Critical | High | Medium | Low

总长度应详尽但便于浏览——目标为 50-100 项发现。如果某个类别包含许多实例，可将类似实例归为一个标题（列出 5-10 个具体示例，并注明其余实例的数量）。

严重级别指南

• Critical — 可能导致崩溃、数据丢失、内存损坏、安全暴露，或将错误的服务 URL 发布到生产环境。标记为此级别前，请亲自查看所引用的代码行。
• High — 用户可能遇到的实际错误；未来 Swift 模式中会变成错误的编译器警告；正被积极移除的弃用 API；架构层面的并发问题。
• Medium — 性能 / 质量问题；适合重构的候选项；缺少现代化改进，但没有功能性错误。
• Low — 命名、外观、代码风格、单处清理。

质量标准（交付前最终检查）

• 每个顶层章节都必须编号为 ## 1. 到 ## 12.，每条发现都必须是编号小节 ### N.M <title>。 浏览渲染后的报告——如果有任何标题缺少编号，请在交付前修正。没有编号的报告会被判定为不合格。
• 执行摘要条目必须通过 §N.M 引用发现，验证条目也必须如此——不能残留模板中的字面 <N.M> 占位符。
• 每条严重和高优先级发现都必须标明精确的行范围。不要写“遍布整个代码库”。
• 并发问题发现必须交叉引用实际的 Step-2 警告列表。
• 至少 3–5 条严重发现必须通过打开引用文件进行抽查验证。
• 按根本原因对发现分组（一条注释 → 多条警告 = 一条发现）。
• “未审计内容”章节必须明确说明，让用户了解审计缺口。
• 报告不超过约 80 条独立发现——过长的报告会降低可操作性。
• 报告本身不得包含代码——建议应描述模式，而非具体实现。
• 用户应能将任意单条发现单独提取为任务，而无需重新解释上下文。

技能输出

始终将内容写入仓库根目录（用户项目的工作目录）下的 CODE_AUDIT.md。如果文件已存在，则覆盖——此技能生成的是快照，而非追加日志。如果用户需要保留历史记录，可在调用技能前使用 git mv 移动旧版本。

此技能不涵盖的内容

• Metal 内核／特定领域代码的算法正确性。 仅指出明显问题；深入的算法审查不在范围内。
• 构建设置、方案配置、Xcode 项目结构。 不审查共享方案中未显示的内容。
• 第三方依赖内部实现。 将 SPM／CocoaPods 包视为黑盒。
• 测试覆盖率评估。 可以快速扫描测试目标；深入测试审查属于另一项技能。
• 本地化正确性。 审计可以指出未翻译的字符串，但不会评估措辞。
• 性能分析。 此技能会识别潜在热点路径（逐帧分配、广泛状态等），但不会运行 Instruments 跟踪。若要进行性能分析，请另行调用 swiftui-expert-skill 及其跟踪工具。

参考资料

• references/agent-prompts.md — 三份 Explore Agent 简报（可直接复制粘贴，并填入项目上下文）。
• references/report-template.md — CODE_AUDIT.md 的完整模板。