argent-native-profiler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Tools

1. 工具

```
native-profiler-start
```
— start profiling on a booted device. iOS: xctrace recording for CPU, hangs, and leaks.
```
native-profiler-stop
```
— stop the profiler and export trace data to timestamped XML files.
```
native-profiler-analyze
```
— parse exported trace data and return a structured bottleneck payload.
```
profiler-stack-query
```
— drill into parsed data: hang stacks, function callers, thread breakdown, leak details.
```
profiler-load
```
— list and reload previous trace sessions from disk for re-investigation.

```
native-profiler-start
```
— 在已启动的设备上开始性能分析。iOS：通过xctrace记录CPU、卡顿和泄漏情况。
```
native-profiler-stop
```
— 停止性能分析并将追踪数据导出为带时间戳的XML文件。
```
native-profiler-analyze
```
— 解析导出的追踪数据并返回结构化的性能瓶颈结果。
```
profiler-stack-query
```
— 深入解析后的数据：卡顿调用栈、函数调用方、线程细分、泄漏详情。
```
profiler-load
```
— 列出并重新加载磁盘中之前的追踪会话，以便重新分析。

2. Platform Support

2. 平台支持

iOS: Fully supported. Backend: Xcode Instruments via
```
xctrace
```
on a booted simulator or connected device. Requires Xcode command-line tools on PATH.
Android: Not yet implemented. An Android backend (Perfetto or simpleperf via
```
adb
```
) is planned; today
```
native-profiler-start
```
rejects Android serials with a clear "iOS-only for now" error.

iOS：完全支持。后端：通过已启动模拟器或连接设备上的
```
xctrace
```
调用Xcode Instruments。要求PATH中配置Xcode命令行工具。
Android：暂未实现。计划推出基于Android的后端（通过
```
adb
```
使用Perfetto或simpleperf）；目前
```
native-profiler-start
```
会拒绝Android设备序列号，并明确提示“目前仅支持iOS”的错误。

3. Investigation Patterns

3. 分析模式

After

native-profiler-analyze

surfaces findings, use

profiler-stack-query

to drill into root causes:

Hang detected →
```
profiler-stack-query
```
mode=
```
hang_stacks
```
for full native call chains → mode=
```
function_callers
```
for the suspected function → read native source.
CPU hotspot →
```
profiler-stack-query
```
mode=
```
thread_breakdown
```
for per-thread distribution → mode=
```
function_callers
```
for the dominant function.
Memory leak →
```
profiler-stack-query
```
mode=
```
leak_stacks
```
filtered by
```
object_type
```
for responsible frames and libraries.

After presenting findings, ask the user whether to investigate further, implement fixes, or stop. After applying fixes, always re-profile the same scenario and compare with

profiler-load

. Report honestly whether the target metric improved, regressed, or stayed flat. If the fix showed no net benefit or introduced regressions elsewhere, say so and reconsider.

Tip: For reproducible before/after comparisons, record the interaction sequence as a flow using the

argent-create-flow

skill before the first profiling run. Replay with

flow-execute

on subsequent runs to eliminate interaction variance.

Note: The
argent-react-native-profiler
instructs to start native profiling automatically alongside React profiling. This skill's workflow and investigation patterns apply in both cases.

在

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
```
过滤查看相关调用帧和库。

展示结果后，询问用户是否需要进一步分析、实施修复或停止操作。应用修复后，务必针对同一场景重新进行性能分析，并通过

profiler-load

与之前的结果对比。如实汇报目标指标是否改善、退化或保持不变。如果修复未带来净收益或在其他方面引入退化，需明确说明并重新考量。

提示：为了可复现的前后对比，在首次性能分析前，使用

argent-create-flow

技能将交互序列记录为流程。后续运行时通过

flow-execute

重放，消除交互差异。

注意：
argent-react-native-profiler
会指示在React性能分析的同时自动启动原生性能分析。本技能的工作流程和分析模式在两种场景下均适用。

4. Workflow

4. 工作流程

Complete all steps in order — do not break mid-flow.

按顺序完成所有步骤——请勿中途中断流程。

Step 0: Ensure the target app is running

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

The

native-profiler-start

tool auto-detects the running app on the device. You do not need to derive

app_process

manually — just make sure the app is launched.

If the app is already running on the device, skip to Step 1 (do not pass
```
app_process
```
).
If the app is not running, use
```
launch-app
```
with the correct bundle ID first.
Only pass
```
app_process
```
explicitly if the tool reports multiple running user apps and you need to disambiguate.

Note: If multiple build flavors are installed (dev, staging, prod), the tool will detect whichever one is currently running. If both are running, it will ask you to specify.

native-profiler-start

工具会自动检测设备上正在运行的应用。无需手动指定

app_process

——只需确保应用已启动。

如果应用已在设备上运行，直接跳至步骤1（无需传入
```
app_process
```
）。
如果应用未运行，先使用
```
launch-app
```
并传入正确的bundle ID启动应用。
仅当工具检测到多个正在运行的用户应用且需要明确指定时，才显式传入
```
app_process
```
。

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

Step 1: Start recording

步骤1：开始记录

Call

native-profiler-start

with

device_id

(iOS UDID; Android not yet supported). The tool auto-detects the running app and saves the trace to

/tmp/argent-profiler-cwd/

with a timestamped filename. Let the user interact with the app or drive interaction via simulator tools (see

argent-device-interact

skill).

调用

native-profiler-start

并传入

device_id

（iOS设备UDID；暂不支持Android）。工具会自动检测正在运行的应用，并将追踪数据保存至

/tmp/argent-profiler-cwd/

目录下，文件名带时间戳。让用户与应用交互，或通过模拟器工具驱动交互（参考

argent-device-interact

技能）。

Step 2: Stop and export

步骤2：停止并导出

Call

native-profiler-stop

with

device_id

. On iOS this sends SIGINT to xctrace, waits for trace packaging, and exports CPU, hangs, and leaks data to XML. Check

exportDiagnostics

in the response for any export warnings.

调用

native-profiler-stop

并传入

device_id

。在iOS上，此操作会向xctrace发送SIGINT信号，等待追踪数据打包，并将CPU、卡顿和泄漏数据导出为XML文件。检查响应中的

exportDiagnostics

字段，查看是否有导出警告。

Step 3: Analyze

步骤3：分析

Call

native-profiler-analyze

with

device_id

. Returns a markdown report with bottlenecks categorized as CPU hotspots, UI hangs, or memory leaks, sorted by severity.

调用

native-profiler-analyze

并传入

device_id

。返回一份Markdown格式的报告，将性能瓶颈分为CPU热点、UI卡顿或内存泄漏三类，并按严重程度排序。

Step 4: Present findings and ask about next steps

步骤4：展示结果并询问下一步操作

Present a concise summary of the key findings. Then follow the "After analysis" guideline — ask whether to investigate further with query tools, implement fixes, or stop.

简要总结关键结果。然后遵循“分析后”指南——询问用户是否需要使用查询工具进一步分析、实施修复或停止操作。

Step 5: Drill-down investigation

步骤5：深入分析

Use

profiler-stack-query

to investigate specific findings. See §3 Investigation Patterns for chaining guidance.

使用

profiler-stack-query

排查具体结果。参考§3分析模式获取链式排查指导。

Step 6: Reload previous sessions

步骤6：重新加载历史会话

To revisit a previous trace:

Call
```
profiler-load
```
mode=
```
list
```
to see available sessions.
Call
```
profiler-load
```
mode=
```
load_native
```
session_id=
```
<timestamp>
```
device_id=
```
<UDID>
```
to re-parse the XML files.
Use
```
profiler-stack-query
```
to investigate the reloaded data.

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

调用
```
profiler-load
```
并设置mode=
```
list
```
查看可用会话。
调用
```
profiler-load
```
并设置mode=
```
load_native
```
、session_id=
```
<时间戳>
```
、device_id=
```
<UDID>
```
重新解析XML文件。
使用
```
profiler-stack-query
```
分析重新加载的数据。

5. Understanding Results

5. 结果解读

Bottlenecks are categorized by severity:

RED: CPU functions taking >15% of total time, all UI hangs, all memory leaks. These require immediate attention.
YELLOW: CPU functions taking 5-15% of total time. Worth investigating but may be acceptable.

Each bottleneck type indicates a different class of problem:

CPU hotspots: Native functions consuming excessive CPU time. Look for tight loops, expensive computations, or redundant work.
UI hangs: Main thread blocked long enough to cause visible jank or unresponsiveness. Often caused by synchronous I/O, heavy layout passes, or lock contention.
Memory leaks: Objects allocated but never freed. Common causes include retain cycles, unclosed resources, or forgotten observers.

性能瓶颈按严重程度分类：

红色：占用总时间>15%的CPU函数、所有UI卡顿、所有内存泄漏。这些问题需要立即处理。
黄色：占用总时间5-15%的CPU函数。值得分析，但可能在可接受范围内。

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

CPU热点：消耗过多CPU时间的原生函数。需检查是否存在死循环、高开销计算或冗余操作。
UI卡顿：主线程被阻塞时间过长，导致可见的界面卡顿或无响应。通常由同步I/O、繁重的布局计算或锁竞争引起。
内存泄漏：已分配但从未释放的对象。常见原因包括引用循环、未关闭的资源或遗忘的观察者。

6. Important Caveats

6. 重要注意事项

Simulator vs device: Simulator profiling reflects host Mac performance, not real device hardware. Use device profiling for accurate CPU timings and memory behavior.
xctrace availability (iOS): Requires Xcode command-line tools installed. Verify with
```
xcrun xctrace version
```
.
Profiler overhead: xctrace instrumentation adds CPU load. If
```
JSLexer
```
,
```
JSONEmitter
```
, or Hermes runtime internals dominate the JS thread in CPU hotspot results, those reflect profiler overhead — not app work. Discount those entries when evaluating findings.
Run-to-run variance: Small fluctuations in CPU percentages between runs are normal. Treat only consistent directional changes (across 2+ runs or >15% delta) as actionable signal.
Live data variability: If the app fetches live API data, different responses between runs change rendering workload independently of code changes. Note when data-dependent screens show variance.

模拟器vs真机：模拟器上的性能分析反映的是宿主Mac的性能，而非真机硬件性能。如需获取准确的CPU计时和内存行为数据，请使用真机进行性能分析。
xctrace可用性（iOS）：需要安装Xcode命令行工具。可通过
```
xcrun xctrace version
```
验证。
性能分析工具开销：xctrace插桩会增加CPU负载。如果CPU热点结果中
```
JSLexer
```
、
```
JSONEmitter
```
或Hermes运行时内部操作在JS线程中占主导，这些反映的是性能分析工具的开销——而非应用本身的工作负载。评估结果时可忽略这些条目。
运行间差异：不同运行之间CPU占比的小幅波动是正常的。只有持续的趋势变化（2次以上运行或>15%的差异）才视为可采取行动的信号。
实时数据差异：如果应用获取实时API数据，不同运行之间的响应差异会独立于代码变更而改变渲染负载。当依赖数据的界面出现差异时需注意记录。