axiom-build

构建与环境

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

**Claude Code 中的捆绑工具：**如果 command -v <tool> 未找到任何内容（钩子已关闭或使用了 --bare），请使用 <plugin-root>/tools/<tool> 替代裸名称；<plugin-root> 是此技能的 Base directory for this skill: 路径向上两级的目录。

无法启动 Axiom Agent？ 当此路由器指引你使用某个 Agent 时，请直接按照其流程操作。通过 MCP，axiom_get_agent 会返回该 Agent；其他情况下，请阅读下方的文件，只需使用文件搜索和读取功能即可。

此处可用：skills/modernization-helper.md。 位于另一套件中：axiom-security/skills/security-privacy-scanner.md。

对于其他任何 Agent，通过 MCP 使用 axiom_get_agent 也会返回该 Agent；请使用 axiom_xclog_*、axiom_xcsym_* 和 axiom_xcprof_* 工具执行其 xclog、xcsym 和 xcprof 步骤。其他情况下，请在 Axiom 的技能中搜索 skills/<agent>.md；如果没有该文件，请使用此套件的技能自行完成相关工作，并使用 PATH 中的任何 Axiom 工具。

捕获构建和测试诊断信息

下次需要构建或测试之前，在 Claude Code 中已加载的实际软件包下解析 tools/axbuild（command -v axbuild；若找不到，则在已加载 Axiom 技能的 Base directory for this skill: 路径上两级目录处查找 tools/axbuild），或在 Codex 中解析 <plugin-root>/tools/，也可以在 Pi 中查找 PATH 上的可执行文件。检查可执行权限，并使用其绝对路径运行 --help；将观察到的路径赋给 AXBUILD。切勿根据示例推断安装路径。

Cursor 和 MCP 发行版不包含 axbuild，也不提供 axbuild MCP 包装器。无法使用已验证的 shell 辅助工具时，请使用下方的保存日志回退方案。

每次调用 Xcode 之前，运行 pgrep -lx xcodebuild; echo "pgrep exit=$?"：退出码为 1 表示没有进程运行，0 表示列出了进程，其他退出码表示清点失败。调查已有的构建；进程数量和运行时长都不能证明进程已成僵尸状态。切勿终止无关进程。发生中断或超时时，axbuild 还会停止构建脚本及其他从其构建进程派生、后被 Xcode 移入独立进程组的进程；axbuild 会在开始清理时和每轮清理时通过父子关系查找这些进程。对于无法停止或验证的此类后代进程（属于其他用户、无法读取或正在调试），axbuild 会报告 cleanup-incomplete。已经脱离构建进程树的任务（例如守护进程或由 launchd 启动的工具）既不会被停止，也不会被报告。停止它列出的任何进程之前，先检查其所有权。执行前，先确定实际方案和目标：

"$AXBUILD" xcodebuild -scheme "$SCHEME" -destination "$DESTINATION" build
"$AXBUILD" swift test --package-path "$PACKAGE"

保留调用方标志、工作目录、环境、测试选择、覆盖率设置和显式产物路径。包装器会补充缺失的诊断默认值；它绝不会清理缓存或自动重新构建。不要将构建命令的输出通过管道传给其他命令。

分别检查 command（原生命令结果）和 collection（证据完整性）。原生命令成功时，收集到的内容仍可能不完整。默认 JSON 限制为 8,000 UTF-8 字节；检查 omissions，并相对于绝对路径 artifacts.run 目录读取 artifacts.report，以获取完整记录和已评估的值。启动时的 stderr JSON 会在任务完成前标明运行目录。使用诊断位置和值，而不要通过重新构建来重新显示输出。

保留的日志是主要编译器信息来源；测试结果和经过验证的 Swift Testing 事件可作为补充。失败测试数量为 null 表示结果不确定，而不是 0。保留结果包，以便导出附件、覆盖率、控制台日志并进行更深入的检查。原生信息查询命令会原样传递其输出。

**保存日志回退方案：**将必要的原生命令 stdout/stderr 重定向到唯一文件，等待命令完成，记录其退出状态并检查保存的文件。xcresult 构建摘要不能替代编译器日志。考虑再次构建前，先读取已有日志。如果构建输出以截断标记结束，或未包含 xcodebuild 的结束行 ** BUILD … ** 或 ** TEST … **，请读取保存的日志或报告，而不是重新构建。

何时使用

遇到以下问题时使用此路由器：

• 构建失败（BUILD FAILED、编译错误、链接器错误）
• 测试崩溃或挂起
• 模拟器问题（无法启动、设备错误）
• Xcode 异常（构建状态过期、僵尸进程）
• 依赖冲突（CocoaPods、SPM）
• 构建性能问题（编译缓慢）
• 调试代码前的环境问题

路由逻辑

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

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

触发条件：

• 出现 BUILD FAILED，但没有明显的代码原因
• 在干净项目中测试崩溃
• 模拟器卡住或无法启动
• SPM 变更后出现 “No such module”
• 存在僵尸 xcodebuild 进程
• 构建结果过时（仍在运行旧代码）
• 干净构建与增量构建结果不同
• Xcode 27（OS27）中的 Device Hub / 预测结果与实际构建不一致问题
• 在模拟器（Device Hub）上复现仅在设备上出现的 Bug（OS27）

为什么先用 xcode-debugging：90% 的神秘问题都出在环境，而不是代码。调试代码之前，先检查环境。

调用：skills/xcode-debugging.md

---

2. 构建缓慢 → build-performance

触发条件：

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

调用：skills/build-performance.md

---

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，但没有明确的错误详情
• 构建有时成功，有时失败
• App 构建成功，但运行的是旧代码
• 出现 “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 依赖图冲突

调用：skills/build-debugging.md

---

9. TestFlight 崩溃分诊 → testflight-triage

触发条件：

• Beta 测试人员报告发生崩溃
• Xcode Organizer 中有崩溃报告
• 崩溃日志尚未完成符号化
• TestFlight 反馈中附有屏幕截图
• App 被终止，但没有崩溃报告

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

调用方式：参见 axiom-shipping (skills/testflight-triage.md)

---

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

触发条件：

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

为什么选择 app-store-connect-ref：用于了解 ASC 崩溃分析、指标仪表板和数据导出工作流的参考指南。

调用方式：参见 axiom-shipping (skills/app-store-connect-ref.md)

---

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

触发条件：

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

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

调用方式：启动 crash-analyzer Agent 或 /axiom:analyze-crash

---

12. MetricKit API 参考 → metrickit-ref

触发条件：

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

为什么选择 metrickit-ref：完整的 MetricKit API 参考，涵盖设置模式、负载解析以及与崩溃报告系统的集成。

调用方式：参见 axiom-performance (skills/metrickit-ref.md)

---

13. 卡死诊断 → hang-diagnostics

触发条件：

• App 卡死或冻结
• 主线程阻塞超过 1 秒
• UI 无法响应触控
• Xcode Organizer 显示卡死诊断
• 来自 MetricKit 的 MXHangDiagnostic
• 看门狗终止（App 在启动或后台切换期间被终止）

为什么选择 hang-diagnostics：用于系统化诊断卡死问题，提供判断主线程是忙碌还是阻塞的决策树、工具选择（Time Profiler、System Trace），以及 8 种常见卡死模式的修复方法。

调用方式：参见 axiom-performance (skills/hang-diagnostics.md)

---

14. 实时调试 → lldb

触发条件：

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

为什么选择 lldb：崩溃报告会告诉你崩溃了什么。LLDB 会告诉你为什么崩溃。

调用方式：skills/lldb.md

---

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 的所有输出，并提供结构化字段（级别、子系统、类别）以便自动分析。

调用方式：/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% 的配置问题（证书、配置文件、权限、钥匙串）。使用命令行工具诊断只需 5 分钟，而盲目猜测可能要花数小时。

调用方式：请参阅 axiom-security (skills/code-signing.md)（工作流），或参阅 axiom-security (skills/code-signing-diag.md)（故障排查）

---

决策树

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. 需要交互式复现崩溃／检查运行时状态？→ 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 中用断点复现问题，才能揭示实际状态。skills/lldb.md 中介绍了相关工作流。
“我知道证书没问题，我来检查代码”	代码签名错误绝不是代码错误，而是 100% 的配置问题。code-signing 可在 5 分钟内使用命令行完成诊断。
“没有 Xcode，我看不到应用记录了什么”	xclog 可从模拟器捕获 print() 和 os_log。输出结构化 JSON，其中包含级别、子系统和类别。/axiom:console。

不适用场景（冲突解决）

以下情况不要使用 axiom-build——请改用正确的路由工具：

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

axiom-build 用于排查环境疑难问题，而非代码错误：

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

调用示例

User：“我的构建因链接器错误而失败” → 调用：skills/xcode-debugging.md（优先从环境入手诊断）

User：“构建要花 10 分钟” → 调用：skills/build-performance.md

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

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

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

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

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

User：“我的代码中是否硬编码了凭据？” → 调用：security-privacy-scanner Agent

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

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

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

User：“一位 Beta 测试人员说我的应用崩溃了” → 调用：参见 axiom-shipping（skills/testflight-triage.md）

User：“我在 App Store Connect 中看到了崩溃，但不知道如何调查” → 调用：参见 axiom-shipping（skills/testflight-triage.md）

User：“我的崩溃日志没有符号化” → 调用：参见 axiom-shipping（skills/testflight-triage.md）

User：“我需要查看 TestFlight 反馈” → 调用：参见 axiom-shipping（skills/testflight-triage.md）

User：“如何在 App Store Connect 中查找崩溃？” → 调用：参见 axiom-shipping（skills/app-store-connect-ref.md）

User：“ASC 中的无崩溃用户指标在哪里？” → 调用：参见 axiom-shipping（skills/app-store-connect-ref.md）

User：“如何从 App Store Connect 导出崩溃数据？” → 调用：参见 axiom-shipping（skills/app-store-connect-ref.md）

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

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

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

User：“如何设置 MetricKit 来收集崩溃数据？” → 调用：参见 axiom-performance（skills/metrickit-ref.md）

User：“如何解析 MXDiagnosticPayload？” → 调用：参见 axiom-performance（skills/metrickit-ref.md）

User：“MXCallStackTree 中有什么内容？如何解码？” → 调用：参见 axiom-performance（skills/metrickit-ref.md）

User：“我的应用有时会卡住” → 调用：参见 axiom-performance（skills/hang-diagnostics.md）

User：“主线程被阻塞，UI 没有响应” → 调用：参见 axiom-performance（skills/hang-diagnostics.md）

User：“Xcode Organizer 显示我的应用存在卡顿诊断信息” → 调用：参见 axiom-performance（skills/hang-diagnostics.md）

User：“我的应用在启动期间被 watchdog 终止” → 调用：参见 axiom-performance（skills/hang-diagnostics.md）

User：“我有一份崩溃报告，需要在调试器中复现” → 调用：skills/lldb.md

User：“如何设置断点来捕获这次崩溃？” → 调用：skills/lldb.md

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

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

User：“如何加快 Xcode 构建速度？” → 调用：build-optimizer Agent 或 /axiom:optimize-build

User：“尝试构建时找不到签名证书” → 调用：参见 axiom-security（skills/code-signing-diag.md）

User：“我的 GitHub Actions CI 中出现 errSecInternalComponent” → 调用：参见 axiom-security（skills/code-signing-diag.md）

User：“如何为 GitHub Actions 设置代码签名？” → 调用：参见 axiom-security（skills/code-signing.md）

User：“我的应用向控制台输出了什么？” → 调用：/axiom:console

User：“我需要查看模拟器控制台输出” → 调用：/axiom:console 用户：“应用静默失败，界面中没有错误提示” → 调用：/axiom:console