axiom-ios-build

iOS 构建与环境路由器

在调试应用代码之前，遇到任何构建、环境或 Xcode 相关问题时，你都必须使用此技能。

适用情形

遇到以下情况时，请使用此路由器：

• 构建失败（BUILD FAILED、编译错误、链接器错误）
• 测试崩溃或卡住
• 模拟器问题（无法启动、设备错误）
• Xcode 行为异常（构建产物过时、僵尸进程）
• 依赖项冲突（CocoaPods、SPM）
• 构建性能问题（编译缓慢）
• 调试代码前遇到的环境问题

路由逻辑

此路由器会根据具体问题调用专用技能：

1. 优先排查环境的问题 → xcode-debugging

触发条件：

• BUILD FAILED，但没有明显的代码原因
• 在干净项目中测试崩溃
• 模拟器卡住或无法启动
• SPM 变更后出现 “No such module”
• 僵尸 xcodebuild 进程
• 构建产物过时（仍在运行旧代码）
• 干净构建与增量构建结果不同

为什么要先用 xcode-debugging：90% 的疑难问题都来自环境，而非代码。调试代码之前，务必先检查这一点。

调用：/skill axiom-xcode-debugging

---

2. 构建缓慢 → build-performance

触发条件：

• 编译耗时过长
• 类型检查成为瓶颈
• 想要优化构建时间
• Build Timeline 显示某些阶段耗时较长

调用：/skill axiom-build-performance

---

3. SPM 依赖项冲突 → spm-conflict-resolver（Agent）

触发条件：

• SPM 解析失败
• 添加程序包后出现 “No such module”
• 重复符号链接器错误
• 程序包之间的版本冲突
• Swift 6 程序包兼容性问题
• Package.swift / Package.resolved 冲突

为什么使用 spm-conflict-resolver：这是一个专用 Agent，可分析 Package.swift 和 Package.resolved，以诊断并解决 Swift Package Manager 冲突。

调用：启动 spm-conflict-resolver Agent

---

4. 安全与隐私审计 → security-privacy-scanner（Agent）

触发条件：

• 准备提交到 App Store
• 隐私清单要求（iOS 17+）
• 代码中硬编码凭据
• 敏感数据存储方面的顾虑
• ATS 违规
• 必需的 Reason API 声明

为什么使用 security-privacy-scanner：这是一个专用 Agent，可扫描安全漏洞和隐私合规问题。

调用：启动 security-privacy-scanner Agent，或使用 /axiom:audit security

---

5. iOS 17→18 现代化改造 → modernization-helper（Agent）

触发条件：

• 将 ObservableObject 迁移到 @Observable
• 将 @StateObject 更新为 @State
• 采用现代 SwiftUI 模式
• 清理已弃用的 API
• 迁移到 iOS 17+

为什么使用 modernization-helper：这是一个专用 Agent，可扫描旧有模式，并提供包含代码示例的迁移方案。

调用：启动 modernization-helper Agent，或使用 /axiom:audit modernization

---

6. 自动修复构建失败 → build-fixer（Agent）

触发条件：

• BUILD FAILED，但没有明确的错误详情
• 构建有时成功，有时失败
• 应用构建成功，但运行的是旧代码
• 出现 “Unable to boot simulator” 错误
• 想要自动执行环境优先诊断

为什么使用 build-fixer：这是一个自主 Agent，会在检查代码之前检查僵尸进程、Derived Data、SPM 缓存和模拟器状态。可为环境问题节省 30 分钟以上。

调用：启动 build-fixer Agent，或使用 /axiom:fix-build

---

7. 优化缓慢的构建 → build-optimizer（Agent）

触发条件：

• 构建耗时过长
• 想要找出缓慢的类型检查
• 构建阶段脚本开销过大
• 构建设置不够理想
• 想要发掘并行化机会

为什么使用 build-optimizer：扫描 Xcode 项目中的构建性能优化点——缓慢的类型检查、开销过大的脚本、不够理想的设置——以将构建时间缩短 30-50%。

调用：启动 build-optimizer Agent，或使用 /axiom:optimize-build

---

8. 常规依赖问题 → build-debugging

触发条件：

• CocoaPods 解析失败
• 出现 “Multiple commands produce” 错误
• 框架版本不匹配
• 非 SPM 依赖图冲突

调用：/skill axiom-build-debugging

---

9. TestFlight 崩溃分流 → testflight-triage

触发条件：

• Beta 测试者报告崩溃
• Xcode Organizer 中有崩溃报告
• 崩溃日志未进行符号化
• TestFlight 反馈中包含截图
• App 被终止，但没有崩溃报告

为何使用 testflight-triage：用于调查 TestFlight 崩溃和审查 Beta 反馈的系统化工作流。涵盖符号化、崩溃解读、常见模式和 Claude 辅助分析。

调用：/skill axiom-testflight-triage

---

10. App Store Connect 导航 → app-store-connect-ref

触发条件：

• 如何在 App Store Connect 中查找崩溃
• ASC 指标仪表板导航
• 了解无崩溃用户百分比
• 比较不同版本之间的崩溃率
• 从 ASC 导出崩溃数据
• 用于崩溃数据的 App Store Connect API

为何使用 app-store-connect-ref：用于导航 ASC 崩溃分析、指标仪表板和数据导出工作流的参考资料。

调用：/skill axiom-app-store-connect-ref

---

11. 崩溃日志分析 → crash-analyzer（Agent）

触发条件：

• 用户有待分析的 .ips 或 .crash 文件
• 用户粘贴了崩溃报告文本
• 需要以编程方式解析崩溃日志
• 根据异常类型识别崩溃模式
• 检查符号化状态

为何使用 crash-analyzer：可自主解析崩溃报告、识别模式（空指针、Swift 运行时、看门狗、jetsam），并生成可执行的分析结果。

调用：启动 crash-analyzer Agent，或运行 /axiom:analyze-crash

---

12. MetricKit API 参考 → metrickit-ref

触发条件：

• MetricKit 设置和订阅
• MXMetricPayload 解析（CPU、内存、启动、卡顿）
• MXDiagnosticPayload 解析（崩溃、挂起、磁盘写入）
• MXCallStackTree 解码和符号化
• 现场崩溃／挂起数据收集
• 后台退出指标

为何使用 metrickit-ref：完整的 MetricKit API 参考资料，包含设置模式、负载解析，以及与崩溃报告系统的集成。

调用：/skill axiom-metrickit-ref

---

13. 挂起诊断 → hang-diagnostics

触发条件：

• App 挂起或冻结
• 主线程阻塞超过 1 秒
• UI 无法响应触摸
• Xcode Organizer 显示挂起诊断
• MetricKit 中的 MXHangDiagnostic
• 看门狗终止（App 在启动／后台转换期间被终止）

为何使用 hang-diagnostics：系统化诊断挂起问题，提供用于区分主线程繁忙或阻塞的决策树、工具选择建议（Time Profiler、System Trace），以及 8 种常见挂起模式的修复方法。

调用：/skill axiom-hang-diagnostics

---

14. 实时调试 → axiom-lldb

触发条件：

• 需要交互式重现崩溃
• 想设置断点并检查状态
• 已分析崩溃报告，现在需要进行实时调查
• 需要将调试器附加到正在运行的 App

为何使用 axiom-lldb：崩溃报告会告诉你发生了什么崩溃。LLDB 会告诉你为什么崩溃。

调用：/skill axiom-lldb

---

16. 运行时控制台捕获 → xclog-ref

触发条件：

• 需要查看 App 在运行时记录的内容
• App 崩溃但没有崩溃报告（需要控制台输出）
• 静默故障（网络、数据、身份验证），没有 UI 反馈
• 想从模拟器捕获 print()/os_log() 输出
• 需要结构化日志输出来进行分析
• “App 输出了什么？”

为何使用 xclog-ref：无法从外部访问 Xcode 的调试控制台。xclog 将 simctl stdout/stderr 与 log stream JSON 结合起来，捕获 print()、NSLog()、os_log() 和 Logger 输出的所有内容，并提供用于自动分析的结构化字段（级别、子系统、类别）。

调用：/skill axiom-xclog-ref 或 /axiom:console

---

15. 代码签名问题 → code-signing

触发条件：

• “No signing certificate found”
• “Provisioning profile doesn't include signing certificate”
• CI 中出现 errSecInternalComponent
• 上传时出现 ITMS-90035 Invalid Signature
• 身份不明确／存在多个证书
• 权限不匹配或缺少功能
• 设置 CI/CD 代码签名（GitHub Actions、fastlane match）
• 证书已过期或已撤销

为什么使用 code-signing：代码签名错误绝不是代码问题，而是 100% 的配置问题（证书、描述文件、权限、钥匙串）。使用 CLI 工具诊断只需 5 分钟，不必花数小时猜测。

调用：/skill axiom-code-signing（工作流）或 /skill axiom-code-signing-diag（故障排查）

---

决策树

1. 出现神秘／间歇性问题，或干净构建失败？→ xcode-debugging（优先检查环境）
2. SPM 依赖冲突？→ spm-conflict-resolver（Agent）
3. CocoaPods／其他依赖冲突？→ build-debugging
4. 构建速度慢？→ build-performance
5. 安全／隐私／App Store 准备？→ security-privacy-scanner（Agent）
6. 想要自动修复构建（优先诊断环境）？→ build-fixer（Agent）
7. 想要扫描构建时间优化？→ build-optimizer（Agent）
8. 现代化改造／弃用 API？→ modernization-helper（Agent）
9. TestFlight 崩溃／反馈？→ testflight-triage
10. 需要浏览 App Store Connect？→ app-store-connect-ref
11. 有崩溃日志（.ips/.crash）？→ crash-analyzer（Agent）
12. MetricKit 设置／解析？→ metrickit-ref
13. 应用卡顿／冻结／看门狗问题？→ hang-diagnostics
14. 需要交互式复现崩溃／检查运行时状态？→ axiom-lldb
15. 代码签名错误（证书、描述文件、权限、Keychain）？→ code-signing / code-signing-diag
16. 需要查看运行时控制台输出（print/os_log）？→ xclog-ref 或 /axiom:console

避免自我合理化

想法	事实
“我知道如何修复这个链接器错误”	链接器错误至少有 4 种根本原因。xcode-debugging 可在 2 分钟内诊断所有原因。
“我先清理一下构建文件夹”	干净构建会掩盖真正的问题。xcode-debugging 能找到根本原因。
“这只是 SPM 的问题，我会修复 Package.swift”	SPM 冲突会层层扩散。spm-conflict-resolver 会分析完整的依赖关系图。
“模拟器今天只是有点慢”	模拟器问题可能表明环境已损坏。xcode-debugging 会系统地检查。
“我跳过环境检查，代码在本地能编译”	优先检查环境每次都能节省 30 分钟以上。
“我会更仔细地阅读崩溃报告，而不是复现问题”	崩溃报告会显示崩溃了什么，而不是为什么崩溃。在 LLDB 中使用断点复现问题，才能揭示实际状态。axiom-lldb 提供了相应工作流。
“我知道证书没问题，先检查代码吧”	代码签名错误绝不是代码问题，而是 100% 的配置问题。code-signing 可使用 CLI 在 5 分钟内完成诊断。
“没有 Xcode，我看不到应用记录的内容”	xclog 可从模拟器捕获 print() + os_log。它会提供包含级别、子系统和类别的结构化 JSON 输出。使用 /axiom:console 或 /skill axiom-xclog-ref。

不适用情况（冲突处理）

以下情况不要使用 ios-build，应改用正确的路由工具：

错误类型	正确的路由工具	不使用 ios-build 的原因
Swift 6 并发错误	ios-concurrency	这是代码错误，不是环境问题
SwiftData 迁移错误	ios-data	这是架构问题，不是构建环境问题
“Sending 'self' risks data race”	ios-concurrency	这是语言错误，不是 Xcode 问题
类型不匹配／编译错误	修复代码	这些属于代码问题

ios-build 用于排查环境问题，而不是代码错误：

• ✅ 代码正确时出现 “No such module”
• ✅ 模拟器无法启动
• ✅ 干净构建失败，增量构建成功
• ✅ 僵尸 xcodebuild 进程
• ❌ Swift 并发警告／错误
• ❌ 数据库迁移失败
• ❌ 有效代码中的类型检查错误

示例调用

用户：“我的构建因链接器错误而失败” → 调用：/skill axiom-xcode-debugging（优先检查环境的诊断）

用户：“构建需要 10 分钟” → 调用：/skill axiom-build-performance

用户：“SPM 无法解析依赖项” → 调用：spm-conflict-resolver agent

用户：“两个包要求同一依赖项的不同版本” → 调用：spm-conflict-resolver agent

用户：“重复符号链接器错误” → 调用：spm-conflict-resolver agent

用户：“我需要为 App Store 安全审查做准备” → 调用：security-privacy-scanner agent

用户：“我需要 Privacy Manifest 吗？” → 调用：security-privacy-scanner agent

用户：“我的代码中是否有硬编码的凭据？” → 调用：security-privacy-scanner agent

用户：“如何从 ObservableObject 迁移到 @Observable？” → 调用：modernization-helper agent

用户：“更新我的代码，以使用现代 SwiftUI 模式” → 调用：modernization-helper agent

用户：“我还应该使用 @StateObject 吗？” → 调用：modernization-helper agent

用户：“一位 Beta 测试者说我的应用崩溃了” → 调用：/skill axiom-testflight-triage

用户：“我在 App Store Connect 中看到了崩溃，但不知道如何调查” → 调用：/skill axiom-testflight-triage

用户：“我的崩溃日志尚未符号化” → 调用：/skill axiom-testflight-triage

用户：“我需要查看 TestFlight 反馈” → 调用：/skill axiom-testflight-triage

用户：“如何在 App Store Connect 中查找崩溃？” → 调用：/skill axiom-app-store-connect-ref

用户：“ASC 中的无崩溃用户指标在哪里？” → 调用：/skill axiom-app-store-connect-ref

用户：“如何从 App Store Connect 导出崩溃数据？” → 调用：/skill axiom-app-store-connect-ref

用户：“分析这份崩溃日志”[粘贴 .ips 内容] → 调用：crash-analyzer agent 或 /axiom:analyze-crash

用户：“解析这个 .ips 文件：~/Library/Logs/DiagnosticReports/MyApp.ips” → 调用：crash-analyzer agent 或 /axiom:analyze-crash

用户：“我的应用为什么崩溃了？这是报告……” → 调用：crash-analyzer agent 或 /axiom:analyze-crash

用户：“如何设置 MetricKit 来收集崩溃数据？” → 调用：/skill axiom-metrickit-ref

用户：“如何解析 MXDiagnosticPayload？” → 调用：/skill axiom-metrickit-ref

用户：“MXCallStackTree 中有什么？如何解码？” → 调用：/skill axiom-metrickit-ref

用户：“我的应用有时会卡住” → 调用：/skill axiom-hang-diagnostics

用户：“主线程被阻塞，UI 无响应” → 调用：/skill axiom-hang-diagnostics

用户：“Xcode Organizer 显示我的应用存在卡顿诊断信息” → 调用：/skill axiom-hang-diagnostics

用户：“我的应用在启动期间被 watchdog 终止” → 调用：/skill axiom-hang-diagnostics

用户：“我有一份崩溃报告，需要在调试器中复现” → 调用：/skill axiom-lldb

用户：“如何设置断点来捕获这次崩溃？” → 调用：/skill axiom-lldb

用户：“我的构建失败，显示 BUILD FAILED，但没有错误详情” → 调用：build-fixer agent 或 /axiom:fix-build

用户：“构建有时成功，有时失败” → 调用：build-fixer agent 或 /axiom:fix-build

用户：“如何缩短 Xcode 构建时间？” → 调用：build-optimizer agent 或 /axiom:optimize-build

用户：“尝试构建时找不到签名证书” → 调用：/skill axiom-code-signing-diag

用户：“我的 GitHub Actions CI 中出现 errSecInternalComponent” → 调用：/skill axiom-code-signing-diag

用户：“如何为 GitHub Actions 设置代码签名？” → 调用：/skill axiom-code-signing

用户：“我的应用在控制台中输出了什么？” → 调用：/skill axiom-xclog-ref 或 /axiom:console

用户：“我需要查看模拟器控制台输出” → 调用：/skill axiom-xclog-ref 或 /axiom:console

用户：“应用静默失败，UI 中没有错误” → 调用：/skill axiom-xclog-ref 或 /axiom:console