axiom-performance

性能

对于任何性能问题，包括内存泄漏、执行缓慢、电池耗电或性能分析，你都必须使用此技能。

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

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

此处可用：skills/energy-auditor.md、skills/memory-auditor.md、skills/swift-performance-analyzer.md。

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

使用时机

在以下情况下使用此路由：

• 应用运行缓慢或卡顿
• 内存用量随时间持续增长
• 电池耗电过快
• 设备使用时发热
• 电池设置中显示能耗较高
• 使用 Instruments 诊断性能
• 内存泄漏或循环引用
• 应用因内存警告而崩溃

路由逻辑

内存问题

内存泄漏（Swift） → 参阅 skills/memory-debugging.md

• 系统地诊断泄漏
• 5 种常见泄漏模式
• Instruments 工作流
• 未调用 deinit

内存泄漏扫描 → 启动 memory-auditor Agent 或 /axiom:audit memory（5 阶段语义审计：梳理资源所有权、检测 6 种泄漏模式、分析缺失的清理操作、关联复合风险、评估生命周期健康状况）

内存泄漏（Objective-C 块） → 参阅 skills/objc-block-retain-cycles.md

• 块的循环引用
• 弱引用-强引用模式
• 网络回调泄漏

性能分析

性能分析（图形界面） → 参阅 skills/performance-profiling.md

• Time Profiler（CPU），包括用于分析分散开销的 Top Functions 模式（OS27）
• Allocations（内存增长）
• Core Data 性能分析（N+1 查询）
• 工具选择决策树
• Instruments 27 Run Comparisons、Swift executors instrument、Foundation Models instrument；Xcode 27 Organizer（Storage/hitches 指标、Metric Goals、Generate Recommendations）

自动化性能分析（CLI） → 参阅 skills/xctrace-ref.md

• 无界面 xctrace 性能分析
• CI/CD 集成模式
• 命令行跟踪记录
• 以编程方式分析跟踪数据

运行自动化性能分析 → 使用 performance-profiler Agent 或 /axiom:profile

• 通过 xctrace 记录跟踪数据
• 导出并分析数据
• 按严重程度报告发现

比较两条跟踪记录／检测回归 → 参阅 skills/trace-comparison.md 或 /axiom:compare-traces

• 此更改是否拖慢了热点路径？函数级 CPU 占比差异
• 使用 xcprof compare --fail-on-regression 进行 CI 门禁（退出码非零）
• 区分回归与改进、按严重程度排序、理解退出码语义

卡顿／冻结问题

应用卡顿或冻结 → 参阅 skills/hang-diagnostics.md

• UI 无响应超过 1 秒
• 主线程被阻塞（忙碌或等待）
• 决策树：区分忙碌与阻塞
• 选择 Time Profiler 或 System Trace
• 8 种常见卡顿模式及其修复方法
• Watchdog 终止

语料库／聚合卡顿分诊（Sentry、ASC） → axiom-shipping (skills/production-triage.md) + triage-analyzer Agent

• 来自聚合器的多条分组卡顿报告，而非单个 .ips 文件
• 在整个语料库中分类 anr_idle_runloop 与 anr_main_thread_block
• 标记挂起／空闲运行循环的误报（按用户数量统计，排名第一的卡顿问题往往是噪声）
• 聚类根因类型并按影响排序

应用启动

应用启动缓慢 → 参见 skills/app-launch.md

• 首帧缓慢、首屏冻结、Organizer 中的启动回归
• 启动阶段模型（pre-main / main→首帧 / 延长启动）
• 冷启动与温启动、热启动/恢复、通知启动——如何分别复现
• App Launch instrument 工作流、dyld Activity、测量规范
• pre-main 优化：链接策略（静态与动态、可合并，MERGED_BINARY_TYPE/MERGEABLE_LIBRARY）、+load、将任务延后到主线程、优先级反转
• XCTApplicationLaunchMetric 回归测试、MXAppLaunchMetric 字段直方图、自定义“应用可交互”标记
• 推送通知启动路径（点击→首个像素 / 点击→可交互目标）

能耗问题

电池耗电、能耗高 → 参见 skills/energy.md

• Power Profiler 工作流
• 子系统诊断（CPU/GPU/网络/定位/显示）
• 反模式修复
• 后台执行优化

基于症状的诊断 → 参见 skills/energy-diag.md

• “应用位于电池设置列表顶部”
• “设备发热”
• “后台电池耗电”
• 各路径的时间成本分析

含代码的 API 参考 → 参见 skills/energy-ref.md

• 完整的 WWDC 代码示例
• 定时器、网络、定位效率
• BGContinuedProcessingTask（iOS 26）
• MetricKit 设置

能耗扫描 → 启动 energy-auditor Agent 或 /axiom:audit energy（8 种反模式：滥用定时器、轮询、持续定位、动画泄漏、误用后台模式、网络效率低下、GPU 浪费、磁盘 I/O）

定时器安全

定时器崩溃模式（DispatchSourceTimer） → 参见 axiom-integration（skills/timer-patterns.md）

• 4 种崩溃场景会触发 BUG IN CLIENT OF LIBDISPATCH——arm64 上为 EXC_BREAKPOINT（SIGTRAP），Intel 上为 EXC_BAD_INSTRUCTION
• RunLoop 模式陷阱（滚动时 Timer 会停止）
• SafeDispatchTimer 包装器
• Timer 与 DispatchSourceTimer 的选择

定时器 API 参考 → 参见 axiom-integration（skills/timer-patterns-ref.md）

• Timer、DispatchSourceTimer、Combine、AsyncTimerSequence API
• 生命周期图
• 平台可用性

Swift 性能

Swift 性能优化 → 参见 skills/swift-performance.md

• 值类型与引用类型、写时复制
• ARC 开销、泛型特化
• 集合性能

Swift 性能扫描 → 启动 swift-performance-analyzer Agent 或 /axiom:audit swift-performance（不必要的复制、ARC 开销、未特化的泛型、集合效率低下、Actor 隔离开销、内存布局）

现代 Swift 惯用写法 → 参见 axiom-swift（skills/swift-modern.md）

• 过时的 API 模式（Date()、CGFloat、DateFormatter）
• Foundation 现代化（URL.documentsDirectory、FormatStyle）
• 针对 Claude 的幻觉纠正

MetricKit 集成

MetricKit API 参考 → 参见 skills/metrickit-ref.md

• 新的 Swift 优先 API（OS27）：MetricManager AsyncSequence 流、类型化的 MetricResult 指标（含 Metal 帧率、存储）、包含终止类别的类型化诊断、启动任务跟踪
• 按状态划分的指标（StateReporting framework，OS27）：按标签页、模式或实验划分卡顿/挂起/内存指标
• 崩溃报告扩展（CrashReportExtension framework，OS27）：在崩溃时处理进程崩溃，并在扩展中进行符号化（第 10 部分）
• MXMetricPayload / MXDiagnosticPayload 解析（旧版，iOS 13–26）
• 收集线上性能数据
• 与崩溃报告集成

运行时控制台捕获

捕获模拟器控制台输出 → /axiom:console

• 捕获模拟器中的 print()、os_log()、Logger 输出
• 包含级别、子系统、类别的结构化 JSON
• 使用 --timeout 和 --max-lines 限制收集量
• 按子系统或正则表达式筛选

运行时状态检查

LLDB 交互式调试 → 请参阅 axiom-build (skills/lldb.md)

• 设置断点，在运行时检查变量
• 根据崩溃日志复现崩溃
• 分析线程状态以排查卡顿
• 检查 Swift 值（po 与 v）

LLDB 命令参考 → 请参阅 axiom-build (skills/lldb-ref.md)

• 完整的命令语法
• 断点配置示例
• 表达式求值模式

决策树

1. 内存持续增长且 UI 卡顿／掉帧？→ 首先使用 memory-debugging（内存压力会导致 GC 暂停，从而造成掉帧），如果内存问题已解决但卡顿仍在，再使用 performance-profiling
2. 内存泄漏（Swift）？→ memory-debugging
3. 内存泄漏（Objective-C 闭包）？→ objc-block-retain-cycles
4. 应用卡死／冻结——UI 是否完全无响应（无法点击，也没有反馈）？
   • 是 → hang-diagnostics（诊断忙碌与阻塞）
   • 否，只是缓慢 → performance-profiling（Time Profiler）
   • 仅首次启动时出现？→ 还要在 hang-diagnostics 中检查同步 I/O 或延迟初始化
   • Sentry／ASC 中有多份分组的卡顿报告（语料，而非单个文件）？→ axiom-shipping (skills/production-triage.md) + triage-analyzer
5. 多个异步操作同时完成时出现卡顿？→ 转至 axiom-concurrency（回调竞争，而非性能分析）
6. 应用启动慢／首帧慢／启动性能回退／点击推送后响应慢？→ app-launch
7. 电量消耗快（已知症状）？→ energy-diag
8. 电量消耗快（需要 API 参考）？→ energy-ref
9. 电量消耗快（一般情况）？→ energy
10. MetricKit 设置／解析？→ metrickit-ref 10a. 按应用状态拆分指标（每个标签页的卡顿率、实验分组）或 StateReporting？→ metrickit-ref（第 1 部分） 10b. 分析 Agentic／大模型功能的性能（Foundation Models 埋点、Token 指标）？→ performance-profiling，然后使用 axiom-ai 10c. 构建崩溃报告扩展（在崩溃发生时处理进程崩溃）？→ metrickit-ref（第 10 部分）
11. 使用 GUI（Instruments）进行性能分析？→ performance-profiling
12. 使用命令行（xctrace）进行性能分析？→ xctrace-ref
13. 现在运行自动化性能分析？→ performance-profiler Agent
14. 一般情况下运行缓慢／卡顿？→ performance-profiling 14a. GRDB／SQLite 查询缓慢（EXPLAIN QUERY PLAN、索引设计、游标）？→ 请参阅 axiom-data (skills/grdb-performance.md)
15. 想主动扫描内存泄漏？→ memory-auditor（Agent）
16. 想扫描能耗反模式？→ energy-auditor（Agent）
17. 想审查 Swift 性能（ARC、泛型、集合）？→ swift-performance-analyzer（Agent）
18. 需要在运行时检查变量／线程状态？→ 请参阅 axiom-build (skills/lldb.md)
19. 需要准确的 LLDB 命令语法？→ 请参阅 axiom-build (skills/lldb-ref.md)
20. 滚动时计时器停止？→ timer-patterns（RunLoop 模式）
21. DispatchSourceTimer 导致 EXC_BREAKPOINT (SIGTRAP) 崩溃——BUG IN CLIENT OF LIBDISPATCH？→ timer-patterns（4 种崩溃模式）
22. 在 Timer、DispatchSourceTimer、Combine timer、async timer 之间选择？→ timer-patterns
23. 需要计时器 API 语法／生命周期？→ timer-patterns-ref
24. 审查过时的 Swift 编写模式？→ swift-modern
25. Claude 生成了旧版 API（DateFormatter、CGFloat、DispatchQueue）？→ swift-modern
26. 性能分析前需要查看运行时控制台输出？→ axiom-tools (skills/xclog-ref.md) 或 /axiom:console
27. 有 .ips、MetricKit 或旧版 .crash 文本文件需要符号化／分诊？→ axiom-tools (skills/xcsym-ref.md) 或 /axiom:analyze-crash

反合理化

想法	事实
“我知道这是内存泄漏，让我找出来”	内存泄漏有 6 种模式。memory-debugging 可在 15 min 内诊断出正确的问题，而不是花 2 hours。
“我直接运行 Time Profiler 就行”	选错 Instruments 模板会浪费时间。performance-profiling 会先选择正确的工具。
“电池耗电可能是网络层的问题”	能耗问题涉及 8 个子系统。energy skill 会诊断出实际原因。
“应用感觉很慢，我之后再优化”	性能问题会不断累积。现在进行性能分析，之后能节省更多时间，效果呈指数级增长。
“只是 UI 卡住了，可能是 API 调用太慢”	卡顿可能是忙碌或阻塞导致的。hang-diagnostics 提供了针对这两种情况的决策树。
“内存一直涨，滚动也卡顿——这是两个独立的 bug”	内存压力会导致 GC 暂停并丢帧。先修复泄漏，再重新检查滚动性能。
“只有首次启动时会卡住，肯定是在加载什么”	首次启动卡顿有 3 种模式：同步 I/O、惰性初始化、主线程争用。hang-diagnostics 可以诊断具体是哪一种。
“启动感觉很慢——我精简一些启动代码就行”	启动分为 3 个阶段（pre-main / main→first frame / extended），并受 watchdog 监控。app-launch 会告诉你应该分析哪个阶段，并提供测量规范，确保数据有意义。
“启动没问题，我的手机上很快”	使用最旧的受支持设备，并以 Release 构建进行测量。app-launch 提供完整的测量规范清单——在最新设备上测得的数据会掩盖性能回退。
“从应用切换器恢复也很慢”	恢复不是启动——绝不要把它当作启动来测量。app-launch 会区分冷启动、温启动、热启动和通知启动，并说明如何复现每一种情况。
“框架太多了——我直接把所有东西都静态链接就行”	静态链接会将库复制到每个链接它的二进制文件中（应用 + 每个扩展），造成全局状态重复，并且如果没有 -ObjC，使用 Obj-C 分类时会出错。app-launch 介绍了静态、动态和可合并链接之间的权衡，以及 DYLD_PRINT_STATISTICS 检查，帮助你判断 pre-main 阶段是否真的是问题所在。
“网络请求完成时 UI 会锁住——就是太慢了”	多个回调同时完成 = 主线程争用 = 并发问题。请转到 axiom-concurrency。
“我直接加几条 print 语句调试就行”	每次 print 调试循环（构建 + 运行 + 复现）都要花 3-5 min。LLDB 断点只需 30 seconds。axiom-build（skills/lldb.md）提供了相关命令。
“我看不到应用记录的日志”	xclog 可以从模拟器捕获 print() + os_log，并生成结构化 JSON。/axiom:console。
“我手动解析这个 .ips JSON，看看最上层的栈帧”	xcsym 只需一次调用即可解析、发现 dSYM、符号化并分类——生成包含 pattern_tag 的结构化 JSON。/axiom:analyze-crash。
“我直接用 Timer.scheduledTimer 就行，更简单”	滚动时 Timer 会停止（.default 模式），并且会保留其目标对象（造成泄漏）。timer-patterns 提供了决策树。
“DispatchSourceTimer 崩溃是间歇性的，先发布吧”	DispatchSourceTimer 有 4 种崩溃模式，而且全部是确定性的。timer-patterns 可以诊断具体是哪一种。
“Claude 已经了解现代 Swift”	Claude 默认使用 Swift 5.5 之前的模式（Date()、CGFloat、filter().count）。swift-modern 提供了修正对照表。
“MetricKit 就是那个旧的 MX delegate API”	第 27 个周期重建了它：MetricManager AsyncSequence 流、类型化指标、按状态聚合。metrickit-ref Part 1 介绍了新的接口。
“我的现场指标都混成一个平均值，无法分辨哪个屏幕慢”	StateReporting 会按你定义的应用状态拆分每项指标（按标签页、按实验）。metrickit-ref Part 1。
“没有单个函数占用太多时间，所以性能分析没用”	分散的开销（动态派发、retain/release、存在类型）会隐藏在火焰图中。Top Functions 模式会将其合并。performance-profiling。

关键模式

内存调试（memory-debugging）：

• 6 种泄漏模式：计时器、观察者、闭包、代理、视图回调、PhotoKit
• Instruments 工作流
• 区分泄漏与缓存

性能分析（performance-profiling）：

• 使用 Time Profiler 查找 CPU 瓶颈
• 使用 Allocations 查找内存增长
• 使用 Core Data SQL 日志查找 N+1 查询
• Self Time 与 Total Time

能耗优化（energy）：

• 使用 Power Profiler 诊断子系统
• 8 种反模式：计时器、轮询、定位、动画、后台、网络、GPU、磁盘
• 按子系统划分的审查清单
• 用于抵御截止期限压力的压力场景

示例调用

用户：“我的应用内存占用一直在增长” → 参阅 skills/memory-debugging.md

用户：“我遇到了内存泄漏，但 deinit 没有被调用” → 参阅 skills/memory-debugging.md

用户：“我的应用感觉很慢，该从哪里开始？” → 参阅 skills/performance-profiling.md

用户：“我的 Objective-C 块回调发生了泄漏” → 参阅 skills/objc-block-retain-cycles.md

用户：“我的应用耗电很快” → 参阅 skills/energy.md

用户：“用户反馈使用我的应用时设备会发烫” → 参阅 skills/energy-diag.md

用户：“高效实现定位跟踪的最佳方式是什么？” → 参阅 skills/energy-ref.md

用户：“分析我的应用的 CPU 使用情况” → 使用：performance-profiler agent（或 /axiom:profile）

用户：“如何从命令行运行 xctrace？” → 参阅 skills/xctrace-ref.md

用户：“我需要为 CI/CD 执行无头性能分析” → 参阅 skills/xctrace-ref.md

用户：“我的应用有时会卡住” → 参阅 skills/hang-diagnostics.md

用户：“UI 冻结且无响应” → 参阅 skills/hang-diagnostics.md

用户：“主线程被阻塞了，该如何诊断？” → 参阅 skills/hang-diagnostics.md

用户：“对我的 Sentry 卡顿问题进行分类” / “哪些 ANR 报告是真正的阻塞？” → 参阅 axiom-shipping (skills/production-triage.md) + triage-analyzer agent（或 /axiom:triage sentry）

用户：“我的应用需要 3 秒才能启动” → 参阅 skills/app-launch.md

用户：“Xcode Organizer 提示我的启动时间变差了” → 参阅 skills/app-launch.md

用户：“如何缩短 pre-main / dyld 耗时？” → 参阅 skills/app-launch.md

用户：“我应该使用可合并库 / 静态链接我的框架吗？” → 参阅 skills/app-launch.md

用户：“点击推送通知后，应用启动很慢” → 参阅 skills/app-launch.md

用户：“如何编写启动性能测试？” → 参阅 skills/app-launch.md

用户：“如何设置 MetricKit？” → 参阅 skills/metrickit-ref.md

用户：“如何解析 MXMetricPayload？” → 参阅 skills/metrickit-ref.md

用户：“如何使用新的 MetricManager / 从 MXMetricManager 迁移？” → 参阅 skills/metrickit-ref.md (Part 1)

用户：“能否按标签页或实验获取卡顿指标？” → 参阅 skills/metrickit-ref.md (Part 1, StateReporting)

用户：“如何分析我的 Foundation Models / Agent 功能？” → 参阅 skills/performance-profiling.md (Foundation Models instrument)，然后参阅 axiom-ai

用户：“如何比较两次 Instruments 运行以验证修复效果？” → 参阅 skills/performance-profiling.md (Run Comparisons) 或 skills/trace-comparison.md (CLI/CI)

用户：“扫描我的代码，查找内存泄漏” → 调用：memory-auditor agent

用户：“检查我的应用是否存在耗电问题” → 调用：energy-auditor agent

用户：“审查我的 Swift 代码，查找性能反模式” → 调用：swift-performance-analyzer agent

用户：“如何在调试器中检查这个变量？” → 调用：参阅 axiom-build (skills/lldb.md)

用户：“条件断点的 LLDB 命令是什么？” → 调用：参阅 axiom-build (skills/lldb-ref.md)

用户：“我需要在调试器中复现这个崩溃” → 调用：参阅 axiom-build (skills/lldb.md)

用户：“我的列表滚动很慢，而且内存一直在增长” → 先参阅 skills/memory-debugging.md；如果仍然卡顿，再参阅 skills/performance-profiling.md

用户：“应用首次启动时会冻结几秒，之后就正常了” → 参阅 skills/hang-diagnostics.md 用户：“多个 API 调用同时返回时，UI 会卡住” → 跨路由：/skill axiom-concurrency（回调争用）

用户：“用户滚动时，我的计时器会停止” → 阅读：axiom-integration（skills/timer-patterns.md）

用户：“我的计时器代码发生 EXC_BREAKPOINT (SIGTRAP) 崩溃 — BUG IN CLIENT OF LIBDISPATCH” → 阅读：axiom-integration（skills/timer-patterns.md）

用户：“我应该使用 Timer 还是 DispatchSourceTimer？” → 阅读：axiom-integration（skills/timer-patterns.md）

用户：“如何创建 AsyncTimerSequence？” → 阅读：axiom-integration（skills/timer-patterns-ref.md）

用户：“检查我的 Swift 代码中是否有过时模式” → 调用：参见 axiom-swift（skills/swift-modern.md）

用户：“有没有更现代的实现方式？” → 调用：参见 axiom-swift（skills/swift-modern.md）

用户：“应用记录了什么日志？我需要查看控制台输出” → 调用：/axiom:console

用户：“在我重现这个错误时，捕获模拟器日志” → 调用：/axiom:console