argent-native-profiler

1. 工具

• native-profiler-start：在已启动的设备上开始性能分析。iOS：使用 xctrace 记录 CPU、卡顿和内存泄漏。
• native-profiler-stop：停止性能分析器，并将跟踪数据导出为带时间戳的 XML 文件。
• native-profiler-analyze：解析导出的跟踪数据，并返回结构化的瓶颈信息。
• profiler-stack-query：深入查询已解析的数据：卡顿调用栈、函数调用者、线程细分和内存泄漏详情。
• profiler-load：列出并重新加载磁盘上之前的跟踪会话，以便重新调查。
• 实体 iPhone：不支持；请使用模拟器。

---

2. 平台支持

• iOS：后端：在已启动的模拟器或已连接的设备上，通过 xctrace 使用 Xcode Instruments。需要将 Xcode 命令行工具添加到 PATH。可查看 CPU 热点、UI 卡顿和内存泄漏（通过 Instruments 的 Leaks 表格）。
• Android：后端：通过 adb shell perfetto 和进程内 WASM 跟踪处理引擎使用 Perfetto。可查看 CPU 热点和 UI 卡顿，包括每次卡顿的卡顿原因代码、主线程状态细分（标注 blocked_function）以及 GC 重叠注释。还会报告 RSS 增长信号，用于提示可能存在内存压力；请将其视为需要手动确认的线索，而非已确认的内存泄漏。目标应用必须可调试，或在其清单中包含 <profileable android:shell="true"/>，才能采集 perf_sample 调用栈。

---

3. 调查模式

native-profiler-analyze 给出发现的问题后，使用 profiler-stack-query 深入调查根因：

• 检测到卡顿 → 使用 profiler-stack-query 的 mode=hang_stacks 获取完整的原生调用链 → 使用 mode=function_callers 查询可疑函数 → 阅读原生代码。
• CPU 热点 → 使用 profiler-stack-query 的 mode=thread_breakdown 查看各线程的分布 → 使用 mode=function_callers 查询占主导地位的函数。
• 内存泄漏 → 使用 profiler-stack-query 的 mode=leak_stacks，按 object_type 筛选出问题的栈帧和库。
  • iOS：如果泄漏结果没有归因信息（责任栈帧为 <Call stack limit reached>），请使用 malloc_stack_logging: true 重新运行 native-profiler-start。这会启用 Malloc Stack Logging 并冷启动应用，使泄漏结果包含真实的分配回溯（责任栈帧和库）。这会重启应用并增加开销，因此仅在需要归因内存泄漏时使用，不要用于 CPU 或卡顿分析。

呈现发现的问题后，询问用户是要继续调查、实施修复，还是停止。应用修复后，务必针对相同场景重新进行性能分析，并使用 profiler-load 对比结果。客观报告目标指标是有所改善、退步，还是保持不变。如果修复没有带来净收益，或在其他方面引入了回归，请如实说明并重新评估。

**提示：**如需进行可复现的前后对比，请在首次性能分析前，使用 argent-create-e2e 技能将交互步骤记录为 e2e 测试。后续运行时使用 e2e-execute 重放，以消除交互差异。

注意：argent-react-native-profiler 会指示同时自动启动原生性能分析和 React 性能分析。无论是哪种情况，都适用本技能的工作流和调查模式。

---

4. 工作流

请按顺序完成所有步骤；不要中途退出。

步骤 0：确保目标应用正在运行

native-profiler-start 工具会自动检测设备上正在运行的应用。 你无需手动推导 app_process；只需确保应用已启动。

1. 如果应用已在设备上运行，请跳至步骤 1（不要传入 app_process）。
2. 如果应用未运行，请先使用 launch-app 和正确的 bundle ID 启动应用。
3. 仅当工具报告有多个正在运行的用户应用且需要区分时，才显式传入 app_process。

注意：如果安装了多个构建变体（dev、staging、prod），工具会检测当前正在运行的变体。如果多个变体同时运行，工具会要求你指定。

步骤 1：开始录制

使用 device_id（iOS UDID 或 Android 序列号）调用 native-profiler-start。该工具会自动检测正在运行的应用，并将跟踪数据保存到 /tmp/argent-profiler-cwd/，文件名带有时间戳。 让用户与应用交互，或通过模拟器工具驱动交互（参见 argent-device-interact 技能）。

步骤 2：停止并导出

使用 device_id 调用 native-profiler-stop。iOS 会向 xctrace 发送 SIGINT，等待跟踪数据打包，然后将 CPU、卡顿和泄漏数据导出为 XML；检查 exportDiagnostics 是否包含导出警告。Android 会向设备上的 perfetto 守护进程发送 SIGTERM，轮询 /proc/<pid> 直至进程退出，然后通过 adb pull 将 .pftrace 拉取到主机。

步骤 3：分析

使用 device_id 调用 native-profiler-analyze。该工具会返回一份 Markdown 报告，将瓶颈按 CPU 热点、UI 卡顿或内存泄漏分类，并按严重程度排序。

步骤 4：呈现发现并询问后续步骤

简要总结关键发现。然后遵循“分析后”指南：询问用户是要使用查询工具进一步调查、实施修复，还是停止。

步骤 5：深入调查

使用 profiler-stack-query 调查具体发现。链式调用指南见 §3 调查模式。

步骤 6：重新加载之前的会话

如需重新查看之前的跟踪数据：

1. 调用 profiler-load，设置 mode=list，查看可用会话。
2. 调用 profiler-load，设置 mode=load_native、session_id=<timestamp> 和 device_id=<UDID>，重新解析 XML 文件。
3. 使用 profiler-stack-query 调查重新加载的数据。

---

5. 了解结果

瓶颈按严重程度分类：

• RED：占总耗时 >15% 的 CPU 函数、所有 UI 卡顿，以及已归因的内存泄漏（已解析出责任帧的泄漏）。这些问题需要立即处理。
• YELLOW：占总耗时 3-15% 的 CPU 函数，以及未归因的内存泄漏（<Call stack limit reached>，无库；参见下文的内存泄漏注意事项）。值得调查，但可能可以接受。

不同类型的瓶颈对应不同类别的问题：

• CPU 热点：消耗过多 CPU 时间的原生函数。注意紧密循环、开销大的计算或重复工作。
• UI 卡顿：主线程阻塞时间过长，导致明显卡顿或无响应。通常由同步 I/O、耗时的布局计算或锁争用导致。
• 内存泄漏：已分配但从未释放的对象。常见原因包括强引用循环、未关闭的资源或遗忘移除的观察者。Argent 通过 xctrace --attach 进行记录，该方式没有 malloc 栈历史，因此在模拟器上，大多数泄漏都会显示为未归因（<Call stack limit reached>，无库），且主要来自无害的系统分配；这类数据会作为低置信度的 YELLOW 摘要报告，而不会确认为 RED 泄漏。要获取已归因的调用栈，请在启动时启用 malloc 栈记录后再进行捕获。

---

6. 重要注意事项

• 模拟器与设备：模拟器性能分析反映的是主机 Mac 的性能，而非真实设备硬件。要获得准确的 CPU 耗时和内存行为，请使用设备进行性能分析。
• xctrace 可用性（iOS）：需要安装 Xcode 命令行工具。使用 xcrun xctrace version 验证。
• 性能分析器开销：xctrace 检测会增加 CPU 负载。如果 CPU 热点结果中 JSLexer、JSONEmitter 或 Hermes 运行时内部组件占用了 JS 线程的大量资源，这反映的是性能分析器的开销，而非应用工作负载。评估发现时，请忽略这些条目。
• 不同运行间的波动：不同运行之间 CPU 百分比的小幅波动属于正常现象。只有持续一致的方向性变化（跨 2 次以上运行，或变化幅度 >15%）才应视为可采取行动的信号。
• 实时数据的可变性：如果应用会获取实时 API 数据，不同运行中收到的响应可能会独立于代码变更，改变渲染工作负载。请注意数据相关屏幕出现的波动。