performance-profiling

性能分析

使用此技能系统地诊断 Apple 应用的性能问题，选择合适的分析工作流，实施有针对性的修复，并通过实际测量验证更改。

适用场景

• Apple 平台应用出现卡顿、掉帧或 CPU 使用率过高，需要使用 Time Profiler 进行分析
• 内存泄漏、内存持续增长或 OOM 崩溃，需要使用 Leaks、Allocations 或 Memory Graph 调试器
• 冷启动／热启动缓慢或首帧耗时过长，需要分析 App Launch instrument
• 电池耗电、热降频或后台／网络能耗过高，需要使用 Energy Log 进行分析
• 发布前性能审计，需要完整检查 Xcode Diagnostics + MetricKit，或添加 os_signpost 测量钩子
• 不适用于一般的（非 Apple）网页／服务性能调优，例如包体积、API 延迟或数据库查询计划——请使用 performance-optimization；也不适用于 Unity／Unreal 引擎帧捕获分析——请使用 game-performance-profiler

决策树

修改代码前，先选择对应的参考文件：

What performance problem are you investigating?

+ App hangs, stutters, dropped frames, slow UI, high CPU
  -> Read references/time-profiler.md

+ High memory, leaks, OOM crashes, growing footprint
  -> Read references/memory-profiling.md

+ Slow cold launch, warm launch, resume, or time to first frame
  -> Read references/launch-optimization.md

+ Battery drain, thermal throttling, background energy, network waste
  -> Read references/energy-diagnostics.md

+ General "app feels slow"
  -> Start with references/time-profiler.md, then references/memory-profiling.md

+ Pre-release performance audit
  -> Read all reference files and use the review checklist below

快速参考

问题	工具／仪器	关键指标	参考
UI 卡顿超过 250 ms	Time Profiler + Hangs	卡顿时长、主线程调用栈	references/time-profiler.md
CPU 使用率过高	Time Profiler	各函数的 CPU 占比、调用树权重	references/time-profiler.md
内存泄漏	Leaks + Memory Graph	泄漏字节数、保留循环路径	references/memory-profiling.md
内存增长	Allocations	存活字节数、代际分析	references/memory-profiling.md
启动缓慢	App Launch	首帧耗时、主程序前阶段、主程序后阶段	references/launch-optimization.md
电池耗电	Energy Log	能耗影响、CPU／GPU／网络活动	references/energy-diagnostics.md
热问题	Activity Monitor、Instruments	热状态变化	references/energy-diagnostics.md
网络浪费	网络分析器	多余的请求、负载大小	references/energy-diagnostics.md

工作流

1. 根据用户报告、跟踪记录、日志或代码路径，确定性能问题类别。
2. 除非问题涉及范围较广或不明确，否则只阅读匹配的参考文件。
3. 优先使用 Release 构建，在真实设备上通过有代表性的数据进行分析。
4. 在提出修复建议前，检查分析结果指出的代码路径。
5. 采用最小范围的针对性修复，解决测得的瓶颈。
6. 重新分析或添加可重复的测量，以确认改进效果。

分析基本原则

• 尽可能在设备上分析；Simulator 使用的是宿主机的 CPU 和内存。
• 使用 Release 配置，因为优化可能会改变热点路径。
• 使用有代表性的数据复现问题，而非空数据库或简单示例资源。
• 关闭无关应用，减少分析过程中的干扰。
• 保留修复前后的测量结果，以便明确验证效果。
• 当工作流需要持续监测耗时情况时，添加 os_signpost 标记。

Xcode 诊断

怀疑的问题与以下 Scheme > Run > Diagnostics 设置相符时，建议启用对应设置：

设置	用途
Main Thread Checker	检查在主线程之外执行的 UI 工作
Thread Sanitizer	检查数据竞争和不安全的共享状态
Address Sanitizer	检查缓冲区溢出和释放后使用问题
Malloc Stack Logging	记录分配调用栈
Zombie Objects	检查对已释放对象发送的消息

MetricKit 钩子

建议使用 MetricKit 监控生产环境中的启动、响应能力、内存和诊断信息：

import MetricKit

final class PerformanceReporter: NSObject, MXMetricManagerSubscriber {
    func startCollecting() {
        MXMetricManager.shared.add(self)
    }

    func didReceive(_ payloads: [MXMetricPayload]) {
        for payload in payloads {
            if let launch = payload.applicationLaunchMetrics {
                log("Resume time: \(launch.histogrammedResumeTime)")
            }
            if let responsiveness = payload.applicationResponsivenessMetrics {
                log("Hang time: \(responsiveness.histogrammedApplicationHangTime)")
            }
            if let memory = payload.memoryMetrics {
                log("Peak memory: \(memory.peakMemoryUsage)")
            }
        }
    }

    func didReceive(_ payloads: [MXDiagnosticPayload]) {
        for payload in payloads {
            if let hangs = payload.hangDiagnostics {
                for hang in hangs {
                    log("Hang: \(hang.callStackTree)")
                }
            }
        }
    }
}

审查清单

响应性：

• 主线程上没有耗时超过 100 ms 的同步操作。
• 主线程上没有文件 I/O 或网络调用。
• 大型 Core Data 或 SwiftData 查询使用后台上下文。
• 图像在主线程之外解码。
• @MainActor 仅用于确实需要访问 UI 的代码。

内存：

• 委托、闭包、观察者或异步任务中没有循环引用。
• 不再可见时释放大型资源。
• 集合和缓存的大小有上限。
• 在会创建 Objective-C 对象的紧密循环中使用 autoreleasepool。

启动：

• @main App 结构体的 init() 中没有繁重操作。
• 延后非必要的初始化。
• 在可行的情况下，尽量减少动态框架。
• 启动期间不执行同步网络调用。

能耗：

• 后台任务使用适当的 BGTaskScheduler 请求类型。
• 定位精度符合产品需求。
• 计时器设置容差，以便系统合并唤醒事件。
• 尽可能批量处理并缓存网络请求。

参考资料

• 上游源代码：MengTo/Skills — performance-profiling
• references/time-profiler.md：CPU 性能分析、卡顿检测、signpost API。
• references/memory-profiling.md：Allocations、Leaks、Memory Graph 调试器。
• references/launch-optimization.md：启动阶段以及冷启动／热启动优化。
• references/energy-diagnostics.md：电池、热状态和网络效率。
• agents/openai.yaml：OpenAI Agent 接口元数据（显示名称、简短描述、默认提示词）。