Back to Details

axiom-ios-build

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

iOS Build & Environment Router

iOS构建与环境问题路由指南

You MUST use this skill for ANY build, environment, or Xcode-related issue before debugging application code.
在调试应用代码之前，任何构建、环境或Xcode相关问题都必须使用此技能。

When to Use

使用场景

Use this router when you encounter:
  • Build failures (
    BUILD FAILED
    , compilation errors, linker errors)
  • Test crashes or hangs
  • Simulator issues (won't boot, device errors)
  • Xcode misbehavior (stale builds, zombie processes)
  • Dependency conflicts (CocoaPods, SPM)
  • Build performance issues (slow compilation)
  • Environment issues before debugging code
遇到以下情况时使用此路由工具：
  • 构建失败（
    BUILD FAILED
    、编译错误、链接器错误）
  • 测试崩溃或挂起
  • 模拟器问题（无法启动、设备错误）
  • Xcode运行异常（构建缓存残留、僵尸进程）
  • 依赖冲突（CocoaPods、SPM）
  • 构建性能问题（编译耗时过长）
  • 调试代码前出现的环境问题

Routing Logic

路由逻辑

This router invokes specialized skills based on the specific issue:
本工具会根据具体问题调用对应的专业技能：

1. Environment-First Issues → xcode-debugging

1. 优先环境类问题 → xcode-debugging

Triggers:
  • BUILD FAILED
    without obvious code cause
  • Tests crash in clean project
  • Simulator hangs or won't boot
  • "No such module" after SPM changes
  • Zombie 
    xcodebuild
    processes
  • Stale builds (old code still running)
  • Clean build differs from incremental build
Why xcode-debugging first: 90% of mysterious issues are environment, not code. Check this BEFORE debugging code.
Invoke: 
/skill axiom-xcode-debugging
触发条件：
  • 无明显代码原因的
    BUILD FAILED
  • 干净项目中测试崩溃
  • 模拟器挂起或无法启动
  • SPM变更后出现"No such module"错误
  • Xcode构建僵尸进程
  • 构建缓存残留（仍运行旧代码）
  • 干净构建与增量构建结果不同
优先选择xcode-debugging的原因：90%的疑难问题源于环境而非代码，请在调试代码前先检查环境。
调用方式：
/skill axiom-xcode-debugging

2. Slow Builds → build-performance

2. 构建缓慢问题 → build-performance

Triggers:
  • Compilation takes too long
  • Type checking bottlenecks
  • Want to optimize build time
  • Build Timeline shows slow phases
Invoke: 
/skill axiom-build-performance
触发条件：
  • 编译耗时过长
  • 类型检查瓶颈
  • 希望优化构建时间
  • 构建时间线显示阶段耗时过长
调用方式：
/skill axiom-build-performance

3. SPM Dependency Conflicts → spm-conflict-resolver (Agent)

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

Triggers:
  • SPM resolution failures
  • "No such module" after adding package
  • Duplicate symbol linker errors
  • Version conflicts between packages
  • Swift 6 package compatibility issues
  • Package.swift / Package.resolved conflicts
Why spm-conflict-resolver: Specialized agent that analyzes Package.swift and Package.resolved to diagnose and resolve Swift Package Manager conflicts.
Invoke: Launch 
spm-conflict-resolver
agent
触发条件：
  • SPM解析失败
  • 添加包后出现"No such module"错误
  • 重复符号链接器错误
  • 包之间的版本冲突
  • Swift 6包兼容性问题
  • Package.swift / Package.resolved冲突
选择spm-conflict-resolver的原因：这是专门分析Package.swift和Package.resolved以诊断并解决Swift Package Manager冲突的智能代理。
调用方式：启动
spm-conflict-resolver
代理

4. Security & Privacy Audit → security-privacy-scanner (Agent)

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

Triggers:
  • App Store submission prep
  • Privacy Manifest requirements (iOS 17+)
  • Hardcoded credentials in code
  • Sensitive data storage concerns
  • ATS violations
  • Required Reason API declarations
Why security-privacy-scanner: Specialized agent that scans for security vulnerabilities and privacy compliance issues.
Invoke: Launch 
security-privacy-scanner
agent or 
/axiom:audit security
触发条件：
  • App Store提交准备
  • 隐私清单要求（iOS 17+）
  • 代码中存在硬编码凭证
  • 敏感数据存储隐患
  • ATS违规
  • Required Reason API声明
选择security-privacy-scanner的原因：这是专门扫描安全漏洞和隐私合规问题的智能代理。
调用方式：启动
security-privacy-scanner
代理或
/axiom:audit security

5. iOS 17→18 Modernization → modernization-helper (Agent)

5. iOS 17→18版本适配 → modernization-helper（Agent）

Triggers:
  • Migrate ObservableObject to @Observable
  • Update @StateObject to @State
  • Adopt modern SwiftUI patterns
  • Deprecated API cleanup
  • iOS 17+ migration
Why modernization-helper: Specialized agent that scans for legacy patterns and provides migration paths with code examples.
Invoke: Launch 
modernization-helper
agent or 
/axiom:audit modernization
触发条件：
  • 从ObservableObject迁移到@Observable
  • 将@StateObject更新为@State
  • 采用现代SwiftUI模式
  • 清理废弃API
  • iOS 17+版本迁移
选择modernization-helper的原因：这是专门扫描旧有模式并提供含代码示例的迁移方案的智能代理。
调用方式：启动
modernization-helper
代理或
/axiom:audit modernization

6. General Dependency Issues → build-debugging

6. 通用依赖问题 → build-debugging

Triggers:
  • CocoaPods resolution failures
  • "Multiple commands produce" errors
  • Framework version mismatches
  • Non-SPM dependency graph conflicts
Invoke: 
/skill axiom-build-debugging
触发条件：
  • CocoaPods解析失败
  • "Multiple commands produce"错误
  • 框架版本不匹配
  • 非SPM依赖图冲突
调用方式：
/skill axiom-build-debugging

7. TestFlight Crash Triage → testflight-triage

7. TestFlight崩溃分类排查 → testflight-triage

Triggers:
  • Beta tester reported a crash
  • Crash reports in Xcode Organizer
  • Crash logs aren't symbolicated
  • TestFlight feedback with screenshots
  • App was killed but no crash report
Why testflight-triage: Systematic workflow for investigating TestFlight crashes and reviewing beta feedback. Covers symbolication, crash interpretation, common patterns, and Claude-assisted analysis.
Invoke: 
/skill axiom-testflight-triage
触发条件：
  • 测试人员反馈崩溃
  • Xcode Organizer中的崩溃报告
  • 崩溃日志未符号化
  • 带截图的TestFlight反馈
  • 应用被终止但无崩溃报告
选择testflight-triage的原因：提供系统化的TestFlight崩溃调查和Beta反馈审查流程，涵盖符号化、崩溃解读、常见模式及Claude辅助分析。
调用方式：
/skill axiom-testflight-triage

8. App Store Connect Navigation → app-store-connect-ref

8. App Store Connect导航指引 → app-store-connect-ref

Triggers:
  • How to find crashes in App Store Connect
  • ASC metrics dashboard navigation
  • Understanding crash-free users percentage
  • Comparing crash rates between versions
  • Exporting crash data from ASC
  • App Store Connect API for crash data
Why app-store-connect-ref: Reference for navigating ASC crash analysis, metrics dashboards, and data export workflows.
Invoke: 
/skill axiom-app-store-connect-ref
触发条件：
  • 如何在App Store Connect中查找崩溃信息
  • ASC指标仪表板导航
  • 理解无崩溃用户占比
  • 对比版本间的崩溃率
  • 从ASC导出崩溃数据
  • 用于崩溃数据的App Store Connect API
选择app-store-connect-ref的原因：提供ASC崩溃分析、指标仪表板及数据导出流程的导航参考。
调用方式：
/skill axiom-app-store-connect-ref

9. Crash Log Analysis → crash-analyzer (Agent)

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

Triggers:
  • User has .ips or .crash file to analyze
  • User pasted crash report text
  • Need to parse crash log programmatically
  • Identify crash pattern from exception type
  • Check symbolication status
Why crash-analyzer: Autonomous agent that parses crash reports, identifies patterns (null pointer, Swift runtime, watchdog, jetsam), and generates actionable analysis.
Invoke: Launch 
crash-analyzer
agent or 
/axiom:analyze-crash
触发条件：
  • 用户需要分析.ips或.crash文件
  • 用户粘贴了崩溃报告文本
  • 需要以编程方式解析崩溃日志
  • 根据异常类型识别崩溃模式
  • 检查符号化状态
选择crash-analyzer的原因：自主代理，可解析崩溃报告、识别模式（空指针、Swift运行时、看门狗、jetsam）并生成可执行的分析结果。
调用方式：启动
crash-analyzer
代理或
/axiom:analyze-crash

10. MetricKit API Reference → metrickit-ref

10. MetricKit API参考 → metrickit-ref

Triggers:
  • MetricKit setup and subscription
  • MXMetricPayload parsing (CPU, memory, launches, hitches)
  • MXDiagnosticPayload parsing (crashes, hangs, disk writes)
  • MXCallStackTree decoding and symbolication
  • Field crash/hang collection
  • Background exit metrics
Why metrickit-ref: Complete MetricKit API reference with setup patterns, payload parsing, and integration with crash reporting systems.
Invoke: 
/skill axiom-metrickit-ref
触发条件：
  • MetricKit设置与订阅
  • MXMetricPayload解析（CPU、内存、启动次数、卡顿）
  • MXDiagnosticPayload解析（崩溃、挂起、磁盘写入）
  • MXCallStackTree解码与符号化
  • 线上崩溃/挂起收集
  • 后台退出指标
选择metrickit-ref的原因：完整的MetricKit API参考，包含设置模式、负载解析及与崩溃报告系统的集成。
调用方式：
/skill axiom-metrickit-ref

11. Hang Diagnostics → hang-diagnostics

11. 应用挂起诊断 → hang-diagnostics

Triggers:
  • App hangs or freezes
  • Main thread blocked for >1 second
  • UI unresponsive to touches
  • Xcode Organizer shows hang diagnostics
  • MXHangDiagnostic from MetricKit
  • Watchdog terminations (app killed during launch/background transition)
Why hang-diagnostics: Systematic diagnosis of hangs with decision tree for busy vs blocked main thread, tool selection (Time Profiler, System Trace), and 8 common hang patterns with fixes.
Invoke: 
/skill axiom-hang-diagnostics
触发条件：
  • 应用挂起或冻结
  • 主线程阻塞超过1秒
  • UI无法响应触摸
  • Xcode Organizer显示挂起诊断
  • MetricKit的MXHangDiagnostic
  • 看门狗终止（应用在启动/后台切换时被杀死）
选择hang-diagnostics的原因：提供系统化的挂起诊断流程，包含主线程繁忙/阻塞的决策树、工具选择（Time Profiler、System Trace），以及8种常见挂起模式及修复方案。
调用方式：
/skill axiom-hang-diagnostics

Decision Tree

决策树

  1. Mysterious/intermittent/clean build fails? → xcode-debugging (environment-first)
  2. SPM dependency conflict? → spm-conflict-resolver (Agent)
  3. CocoaPods/other dependency conflict? → build-debugging
  4. Slow build time? → build-performance
  5. Security/privacy/App Store prep? → security-privacy-scanner (Agent)
  6. Modernization/deprecated APIs? → modernization-helper (Agent)
  7. TestFlight crash/feedback? → testflight-triage
  8. Navigating App Store Connect? → app-store-connect-ref
  9. Have a crash log (.ips/.crash)? → crash-analyzer (Agent)
  10. MetricKit setup/parsing? → metrickit-ref
  11. App hang/freeze/watchdog? → hang-diagnostics
  1. 出现疑难/间歇性/干净构建失败？→ xcode-debugging（优先环境检查）
  2. SPM依赖冲突？→ spm-conflict-resolver（智能代理）
  3. CocoaPods/其他依赖冲突？→ build-debugging
  4. 构建耗时过长？→ build-performance
  5. 安全/隐私/App Store提交准备？→ security-privacy-scanner（智能代理）
  6. 版本适配/废弃API清理？→ modernization-helper（智能代理）
  7. TestFlight崩溃/反馈？→ testflight-triage
  8. App Store Connect导航？→ app-store-connect-ref
  9. 有崩溃日志（.ips/.crash）？→ crash-analyzer（智能代理）
  10. MetricKit设置/解析？→ metrickit-ref
  11. 应用挂起/冻结/看门狗终止？→ hang-diagnostics

Anti-Rationalization

常见误区纠正

ThoughtReality
"I know how to fix this linker error"Linker errors have 4+ root causes. xcode-debugging diagnoses all in 2 min.
"Let me just clean the build folder"Clean builds mask the real issue. xcode-debugging finds the root cause.
"It's just an SPM issue, I'll fix Package.swift"SPM conflicts cascade. spm-conflict-resolver analyzes the full dependency graph.
"The simulator is just slow today"Simulator issues indicate environment corruption. xcode-debugging checks systematically.
"I'll skip environment checks, it compiles locally"Environment-first saves 30+ min. Every time.
错误想法实际情况
"我知道怎么修复这个链接器错误"链接器错误有4种以上根本原因，xcode-debugging可在2分钟内完成全面诊断。
"我先清理构建文件夹试试"清理构建会掩盖真实问题，xcode-debugging能找到根本原因。
"这只是SPM问题，我修改Package.swift就行"SPM冲突会连锁反应，spm-conflict-resolver会分析完整的依赖图。
"今天模拟器只是变慢了"模拟器问题通常表明环境已损坏，xcode-debugging会进行系统化检查。
"我跳过环境检查，本地能编译就行"优先检查环境每次能节省30分钟以上的时间。

When NOT to Use (Conflict Resolution)

禁用场景（冲突解决）

Do NOT use ios-build for these — use the correct router instead:
Error TypeCorrect RouterWhy NOT ios-build
Swift 6 concurrency errorsios-concurrencyCode error, not environment
SwiftData migration errorsios-dataSchema issue, not build environment
"Sending 'self' risks data race"ios-concurrencyLanguage error, not Xcode issue
Type mismatch / compilation errorsFix the codeThese are code bugs
ios-build is for environment mysteries, not code errors:
  • ✅ "No such module" when code is correct
  • ✅ Simulator won't boot
  • ✅ Clean build fails, incremental works
  • ✅ Zombie xcodebuild processes
  • ❌ Swift concurrency warnings/errors
  • ❌ Database migration failures
  • ❌ Type checking errors in valid code
以下情况请勿使用ios-build，请使用对应的正确路由工具：
错误类型正确路由工具禁用原因
Swift 6并发错误ios-concurrency代码错误，非环境问题
SwiftData迁移错误ios-data架构问题，非构建环境问题
"Sending 'self' risks data race"ios-concurrency语言特性错误，非Xcode问题
类型不匹配/编译错误直接修复代码这些是代码bug
ios-build仅用于环境类疑难问题，而非代码错误：
  • ✅ 代码正确但出现"No such module"错误
  • ✅ 模拟器无法启动
  • ✅ 干净构建失败，增量构建正常
  • ✅ Xcode构建僵尸进程
  • ❌ Swift并发警告/错误
  • ❌ 数据库迁移失败
  • ❌ 有效代码中的类型检查错误

Example Invocations

调用示例

User: "My build failed with a linker error" → Invoke: 
/skill axiom-xcode-debugging
(environment-first diagnostic)
User: "Builds are taking 10 minutes" → Invoke: 
/skill axiom-build-performance
User: "SPM won't resolve dependencies" → Invoke: 
spm-conflict-resolver
agent
User: "Two packages require different versions of the same dependency" → Invoke: 
spm-conflict-resolver
agent
User: "Duplicate symbol linker error" → Invoke: 
spm-conflict-resolver
agent
User: "I need to prepare for App Store security review" → Invoke: 
security-privacy-scanner
agent
User: "Do I need a Privacy Manifest?" → Invoke: 
security-privacy-scanner
agent
User: "Are there hardcoded credentials in my code?" → Invoke: 
security-privacy-scanner
agent
User: "How do I migrate from ObservableObject to @Observable?" → Invoke: 
modernization-helper
agent
User: "Update my code to use modern SwiftUI patterns" → Invoke: 
modernization-helper
agent
User: "Should I still use @StateObject?" → Invoke: 
modernization-helper
agent
User: "A beta tester said my app crashed" → Invoke: 
/skill axiom-testflight-triage
User: "I see crashes in App Store Connect but don't know how to investigate" → Invoke: 
/skill axiom-testflight-triage
User: "My crash logs aren't symbolicated" → Invoke: 
/skill axiom-testflight-triage
User: "I need to review TestFlight feedback" → Invoke: 
/skill axiom-testflight-triage
User: "How do I find crashes in App Store Connect?" → Invoke: 
/skill axiom-app-store-connect-ref
User: "Where's the crash-free users metric in ASC?" → Invoke: 
/skill axiom-app-store-connect-ref
User: "How do I export crash data from App Store Connect?" → Invoke: 
/skill axiom-app-store-connect-ref
User: "Analyze this crash log" [pastes .ips content] → Invoke: 
crash-analyzer
agent or 
/axiom:analyze-crash
User: "Parse this .ips file: ~/Library/Logs/DiagnosticReports/MyApp.ips" → Invoke: 
crash-analyzer
agent or 
/axiom:analyze-crash
User: "Why did my app crash? Here's the report..." → Invoke: 
crash-analyzer
agent or 
/axiom:analyze-crash
User: "How do I set up MetricKit to collect crash data?" → Invoke: 
/skill axiom-metrickit-ref
User: "How do I parse MXDiagnosticPayload?" → Invoke: 
/skill axiom-metrickit-ref
User: "What's in MXCallStackTree and how do I decode it?" → Invoke: 
/skill axiom-metrickit-ref
User: "My app hangs sometimes" → Invoke: 
/skill axiom-hang-diagnostics
User: "The main thread is blocked and UI is unresponsive" → Invoke: 
/skill axiom-hang-diagnostics
User: "Xcode Organizer shows hang diagnostics for my app" → Invoke: 
/skill axiom-hang-diagnostics
User: "My app was killed by watchdog during launch" → Invoke: 
/skill axiom-hang-diagnostics
用户："我的构建因链接器错误失败" → 调用：
/skill axiom-xcode-debugging
（优先环境诊断）
用户："构建需要10分钟" → 调用：
/skill axiom-build-performance
用户："SPM无法解析依赖" → 调用：
spm-conflict-resolver
智能代理
用户："两个包需要同一依赖的不同版本" → 调用：
spm-conflict-resolver
智能代理
用户："出现重复符号链接器错误" → 调用：
spm-conflict-resolver
智能代理
用户："我需要为App Store安全审查做准备" → 调用：
security-privacy-scanner
智能代理
用户："我需要隐私清单吗？" → 调用：
security-privacy-scanner
智能代理
用户："我的代码里有硬编码凭证吗？" → 调用：
security-privacy-scanner
智能代理
用户："如何从ObservableObject迁移到@Observable？" → 调用：
modernization-helper
智能代理
用户："更新我的代码以使用现代SwiftUI模式" → 调用：
modernization-helper
智能代理
用户："我还应该使用@StateObject吗？" → 调用：
modernization-helper
智能代理
用户："测试人员反馈我的应用崩溃了" → 调用：
/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
智能代理或
/axiom:analyze-crash
用户："解析这个.ips文件：~/Library/Logs/DiagnosticReports/MyApp.ips" → 调用：
crash-analyzer
智能代理或
/axiom:analyze-crash
用户："我的应用为什么崩溃？这是报告..." → 调用：
crash-analyzer
智能代理或
/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
用户："我的应用在启动时被看门狗杀死" → 调用：
/skill axiom-hang-diagnostics