argent-react-native-profiler

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

This skill is complementary to

argent-react-native-optimization

, not a replacement for it.

本技能是

argent-react-native-optimization

的补充，而非替代方案。

2. Tool Overview

2. 工具概述

React Profiler (Hermes / React commits)

React Profiler（Hermes / React提交）

Tool	Purpose
`react-profiler-start`	Start CPU sampling + inject React commit-capture hook. Optional: `sample_interval_us` (default 100).
`react-profiler-stop`	Stop recording; stores cpuProfile + commitTree in session.
`react-profiler-status`	Call if you were interrupted in the middle of the flow, never in another scenario (debugger drop, Metro reload, pause, subagent handoff, any doubt). Returns `session_status: "active" \| "taken_over" \| "stopped" \| "no_react_runtime"` . Side-effect free.
`react-profiler-analyze`	Run pipeline -> report with CPU-enriched hot commits, sorted by `totalRenderMs` DESC. Saves raw data to disk.
`react-profiler-component-source`	AST lookup: file, line, memoization status, 50 lines of source for a component.
`react-profiler-renders`	Live fiber walk: render counts + durations per component (no profiling session required).
`react-profiler-fiber-tree`	Live fiber walk: full component hierarchy as JSON.

工具	用途
`react-profiler-start`	启动CPU采样并注入React提交捕获钩子。可选参数： `sample_interval_us` （默认值100）。
`react-profiler-stop`	停止录制；将cpuProfile和commitTree存储到会话中。
`react-profiler-status`	仅在流程中断时调用，其他场景请勿使用（调试器断开、Metro重载、暂停、子智能体交接等不确定情况）。返回 `session_status: "active" \| "taken_over" \| "stopped" \| "no_react_runtime"` 。无副作用。
`react-profiler-analyze`	运行处理流程 -> 生成包含CPU关联热点提交的报告，按 `totalRenderMs` 降序排序。将原始数据保存到磁盘。
`react-profiler-component-source`	AST查找：组件对应的文件、行号、 memoization状态，以及该组件的50行源代码。
`react-profiler-renders`	实时fiber遍历：每个组件的渲染次数和时长（无需性能分析会话）。
`react-profiler-fiber-tree`	实时fiber遍历：完整组件层级结构的JSON格式输出。

Drill-Down Query Tools (call after analyze)

深度查询工具（分析后调用）

Tool	Purpose
`profiler-cpu-query`	Targeted CPU investigation: top functions, time-windowed CPU, call trees, per-component CPU.
`profiler-commit-query`	Targeted commit investigation: by component, time range, commit index, or cascade tree.
`profiler-stack-query`	iOS Instruments drill-down: hang stacks, function callers, thread breakdown, leak details.
`profiler-combined-report`	Cross-correlated report when both React Profiler and native profiler ran in parallel.
`profiler-load`	List and reload previous profiling sessions from disk for re-investigation with query tools.

For native profiling (CPU hotspots, UI hangs, memory leaks), see the

argent-native-profiler

skill.

工具	用途
`profiler-cpu-query`	针对性CPU调查：顶级函数、时间窗口内CPU占用、调用树、组件级CPU占用情况。
`profiler-commit-query`	针对性提交调查：按组件、时间范围、提交索引或级联树查询。
`profiler-stack-query`	iOS Instruments深度分析：卡顿调用栈、函数调用方、线程分解、内存泄漏详情。
`profiler-combined-report`	React Profiler与原生性能分析工具并行运行时的交叉关联报告。
`profiler-load`	列出并重新加载磁盘中过往的性能分析会话，以便使用查询工具重新调查。

如需原生性能分析（CPU热点、UI卡顿、内存泄漏），请查看

argent-native-profiler

技能。

3. Agent Behavior Guidelines

3. 智能体行为准则

Follow these rules throughout the profiling workflow:

Start
```
react-profiler-start
```
and
```
native-profiler-start
```
in parallel (two tool calls in one message). Both need
```
device_id
```
; use the same UDID for both so their data can be correlated later. This gives best coverage.
If the user only wants native profiling, use the
```
argent-native-profiler
```
skill workflow. Only skip
```
native-profiler-start
```
if the user has already explicitly said they don't want native profiling in this session

在整个性能分析流程中遵循以下规则：

并行启动
```
react-profiler-start
```
和
```
native-profiler-start
```
（一条消息中调用两个工具）。两者都需要
```
device_id
```
；使用相同的UDID，以便后续关联它们的数据。这样能获得最佳覆盖范围。
如果用户仅需要原生性能分析，请使用
```
argent-native-profiler
```
技能流程。仅当用户明确表示本次会话不需要原生性能分析时，才跳过
```
native-profiler-start
```

After analysis: ask about next steps

分析完成后：询问下一步操作

After presenting the analysis report, always ask the user what they want to do next. Present these options:

Investigate further — drill down into specific findings using query tools (CPU call trees, commit cascades, hang stacks, etc.) to identify root causes with confidence before making changes.
Implement fixes — apply changes based on the current findings, then re-profile to measure whether the metric changed (improved, regressed, or stayed flat).
Done for now — accept the report as-is.

Do NOT silently move on after the report. The report is the starting point, not the end — query tools exist specifically to let you dig deeper into anything the report flags.

展示分析报告后，务必询问用户下一步想要做什么。提供以下选项：

进一步调查 — 使用查询工具深入研究具体发现（CPU调用树、提交级联、卡顿调用栈等），在进行更改前确定根本原因。
实施修复 — 根据当前发现应用更改，然后重新进行性能分析以衡量指标是否变化（改善、退化或保持不变）。
暂时结束 — 接受现有报告。

报告展示后请勿静默继续。报告是起点而非终点——查询工具专门用于深入研究报告中标记的任何问题。

During investigation: use query tools proactively

调查过程中：主动使用查询工具

When drilling down, chain query tool calls based on what you find:

A hot commit ->
```
profiler-commit-query
```
mode=
```
by_index
```
to see all components ->
```
profiler-cpu-query
```
mode=
```
component_cpu
```
for the slowest one ->
```
profiler-cpu-query
```
mode=
```
call_tree
```
for the hot function -> read the source file -> propose a fix.
A memory leak ->
```
profiler-stack-query
```
mode=
```
leak_stacks
```
to identify the responsible module -> read the native source if actionable.
A native hang ->
```
profiler-stack-query
```
mode=
```
hang_stacks
```
to get the native call chain -> correlate with React commit timing.

深入调查时，根据发现链式调用查询工具：

发现热点提交 -> 使用
```
profiler-commit-query
```
mode=
```
by_index
```
查看所有组件 -> 对最慢组件使用
```
profiler-cpu-query
```
mode=
```
component_cpu
```
-> 对热点函数使用
```
profiler-cpu-query
```
mode=
```
call_tree
```
-> 读取源代码 -> 提出修复方案。
发现内存泄漏 -> 使用
```
profiler-stack-query
```
mode=
```
leak_stacks
```
确定负责模块 -> 若可行则读取原生源代码。
发现原生卡顿 -> 使用
```
profiler-stack-query
```
mode=
```
hang_stacks
```
获取原生调用链 -> 关联React提交时间。

After fixes: always re-profile

修复后：务必重新分析

When you apply a fix, always re-profile the same scenario afterward. Compare before/after metrics (commit durations, CPU time, render counts) and report honestly: did the target metric improve, stay flat, or regress? Did any other metric get worse? If you need to reference the original data, use

profiler-load

to reload the pre-fix session. If the fix showed no improvement or introduced a regression, say so explicitly and reconsider the approach.

应用修复后，务必针对相同场景重新进行性能分析。对比修复前后的指标（提交时长、CPU时间、渲染次数）并如实报告：目标指标是改善、保持不变还是退化？其他指标是否变差？如果需要参考原始数据，使用

profiler-load

重新加载修复前的会话。如果修复未带来改善或引入退化，请明确说明并重新考虑方案。

Use flows for reproducible profiling

使用流程确保可重复分析

When profiling requires a specific interaction sequence (scroll a list, navigate screens, trigger an animation), record the interaction as a flow using the

argent-create-flow

skill before the first profiling run. Then replay the same flow for every subsequent run. This eliminates interaction variance as a confounder and makes before/after comparisons meaningful. Especially important when:

You are about to re-profile after applying a fix (Step 8).
The user asks you to compare multiple profiling sessions.
The interaction path is more than 2-3 steps long.

当性能分析需要特定交互序列（滚动列表、导航页面、触发动画）时，在首次性能分析运行前，使用
argent-create-flow
技能将交互记录为流程。然后在后续每次运行时重放相同流程。这消除了交互差异的干扰，使修复前后的对比更有意义。以下场景尤为重要：

准备在应用修复后重新分析（步骤8）。
用户要求对比多个性能分析会话。
交互路径超过2-3步。

4. Standard Profiling Workflow

4. 标准性能分析流程

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

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

Step 1: Start profiling

步骤1：启动性能分析

Mind the react-native and ios-native profiler selection mentioned above when starting the session and start the tools. Save
startedAtEpochMs
from the response — you will need it for annotation offsets. Every subsequent profiler/query call in this session must use the same

device_id

. Before beginning, define lightweight success criteria with the user: which metric matters most (e.g.,

totalRenderMs

, specific commit duration, render count for a component) and what threshold would be meaningful. This anchors later evaluation. On success:

if user asked you to perform the profiling, determine how to profile yourself using tools described in
```
argent-device-interact
```
skill.
if the user stated they wish to perform the interaction themselves — suggest what interaction to perform (e.g. "scroll the list", "switch tabs") and wait for their reply. If you received information about existing profiling session being owned by another agent:
if session is marked as "stale", you may overtake it without prompting the user for allowance
if session is NOT "stale" - before taking action and terminating the other session, stop and ask user what you should do, explaining the situation.

启动会话时注意上述提到的React Native和iOS原生性能分析工具选择，并启动工具。保存响应中的
startedAtEpochMs
——后续标注偏移量会用到它。本次会话中所有后续性能分析/查询调用必须使用相同的

device_id

。开始前，与用户定义轻量级成功标准：哪个指标最重要（例如

totalRenderMs

、特定提交时长、组件渲染次数），以及什么阈值有意义。这为后续评估提供依据。成功启动后：

如果用户要求你执行性能分析，使用
```
argent-device-interact
```
技能中描述的工具自行确定分析方式。
如果用户表示希望自行执行交互——建议执行的交互操作（例如“滚动列表”、“切换标签页”）并等待回复。如果收到关于现有性能分析会话被其他智能体占用的信息：
如果会话标记为“stale”，你可以无需用户许可接管会话
如果会话未标记为“stale”——在采取行动终止其他会话前，停止操作并询问用户应如何处理，说明情况。

Annotate every interaction

为每个交互添加标注

After each

gesture-tap

gesture-swipe

call, record an annotation using the returned

timestampMs

. Compute

offsetMs = timestampMs - startedAtEpochMs

. Do this for every interaction — including back-navigation swipes, not just the primary action. Pass all collected annotations to

react-profiler-analyze

in Step 3.

每次调用

gesture-tap

或

gesture-swipe

后，使用返回的

timestampMs

记录标注。计算

offsetMs = timestampMs - startedAtEpochMs

。每个交互都要执行此操作——包括返回导航的滑动，不仅是主要操作。将所有收集到的标注传递给步骤3中的

react-profiler-analyze

。

Step 2: Stop and collect

步骤2：停止并收集数据

Call

react-profiler-stop

and

native-profiler-stop

in parallel. Only skip

native-profiler-stop

if you did not start it in Step 1. Note

duration_ms

and

fiber_renders_captured

. If

fiber_renders_captured: 0

, warn the user — React commit data may be missing.

并行调用

react-profiler-stop

和

native-profiler-stop

。仅当步骤1中未启动

native-profiler-start

时才跳过

native-profiler-stop

。记录

duration_ms

和

fiber_renders_captured

。如果

fiber_renders_captured: 0

，向用户发出警告——React提交数据可能缺失。

Step 3: Analyze

步骤3：分析数据

Call

react-profiler-analyze

with

port

device_id

project_root

platform

, and

rn_version

. The report includes metadata such as

reactCompilerEnabled

strictModeEnabled

, and

buildMode

— check these in the returned markdown report.

If you performed interactions using

gesture-tap

gesture-swipe

, pass

annotations

to mark when each action occurred. Each annotation's

offsetMs

must be computed as

tapTimestampMs - startedAtEpochMs

, where

tapTimestampMs

is the

timestampMs

returned by the gesture-tap/gesture-swipe tool and

startedAtEpochMs

was returned by

react-profiler-start

. Do not use

Date.now()

for this calculation — only server-side timestamps from the tool return values.

If dual profiling, also call

native-profiler-analyze

, then you must call

profiler-combined-report

for the cross-correlated view — do not skip this step when both profilers ran; the combined report surfaces correlations that individual reports miss.

The analyze report includes CPU hotspots per commit — showing exactly which JS functions ran during each slow React commit. Raw data is saved to disk automatically for later reload.

调用

react-profiler-analyze

，传入

port

、

device_id

、

project_root

、

platform

和

rn_version

。报告包含

reactCompilerEnabled

、

strictModeEnabled

和

buildMode

等元数据——请检查返回的markdown报告中的这些内容。

如果使用

gesture-tap

gesture-swipe

执行了交互，传入

annotations

标记每个操作的发生时间。每个标注的

offsetMs

必须计算为

tapTimestampMs - startedAtEpochMs

，其中

tapTimestampMs

是

gesture-tap

gesture-swipe

工具返回的

timestampMs

，

startedAtEpochMs

是

react-profiler-start

返回的值。不要使用

Date.now()

进行此计算——仅使用工具返回值中的服务器端时间戳。

如果进行了双重分析，还要调用

native-profiler-analyze

，然后必须调用

profiler-combined-report

获取交叉关联视图——当两个性能分析工具都运行时，请勿跳过此步骤；组合报告能呈现单个报告遗漏的关联信息。

分析报告包含每个提交的CPU热点——显示每个缓慢React提交期间运行的具体JS函数。原始数据会自动保存到磁盘，以便后续重新加载。

Step 4: Assess results

步骤4：评估结果

Analyze whether the results give you a proper image of what is wrong with the application - do not assume improvement always exists, verify results logically with reference to how react-native works. Make sure to give honest feedback and be ready to change the approach if needed.

分析结果是否能准确反映应用存在的问题——不要假设一定存在可优化空间，结合React Native的工作原理逻辑验证结果。确保提供诚实的反馈，并在需要时准备改变方法。

Step 5: Present findings and ask about next steps

步骤5：展示发现并询问下一步操作

Present a concise summary of the key findings - present whether possibilities for improvement exist and how performing further actions could affect performance. Then follow the "After analysis" guideline — ask whether to investigate further, implement fixes (if available), or stop.

简要总结关键发现——说明是否存在优化可能性，以及执行进一步操作对性能的影响。然后遵循“分析完成后”的准则——询问是否要进一步调查、实施修复（如果可行）或停止。

Step 6: Drill-down investigation (iterative)

步骤6：深度调查（迭代）

Based on findings from the report, use query tools to investigate deeper:

Slow component? ->
```
profiler-cpu-query
```
mode=
```
component_cpu
```
component_name=
```
AppNavigator
```
— shows what JS functions ran during that component's commits.
Want to see the call tree? ->
```
profiler-cpu-query
```
mode=
```
call_tree
```
function_name=
```
expensiveFunction
```
— shows callers and callees.
What happened during a time window? ->
```
profiler-commit-query
```
mode=
```
by_time_range
```
— lists all commits in a range.
Full commit detail? ->
```
profiler-commit-query
```
mode=
```
by_index
```
commit_index=38 — all components, props changes, parent cascade.
Who triggered whom? ->
```
profiler-commit-query
```
mode=
```
cascade_tree
```
— visual parent-child cascade.
iOS hang details? ->
```
profiler-stack-query
```
mode=
```
hang_stacks
```
— native call stacks during a hang.

Repeat as needed until you identify the root cause function and file, referring to step 4 for honest evaluation. After each round of investigation, ask the user if they want to continue digging or move to fixing.

根据报告中的发现，使用查询工具深入调查：

组件运行缓慢？ -> 使用
```
profiler-cpu-query
```
mode=
```
component_cpu
```
component_name=
```
AppNavigator
```
——显示该组件提交期间运行的JS函数。
查看调用树？ -> 使用
```
profiler-cpu-query
```
mode=
```
call_tree
```
function_name=
```
expensiveFunction
```
——显示调用方和被调用方。
时间窗口内发生了什么？ -> 使用
```
profiler-commit-query
```
mode=
```
by_time_range
```
——列出指定范围内的所有提交。
完整提交详情？ -> 使用
```
profiler-commit-query
```
mode=
```
by_index
```
commit_index=38 ——所有组件、props变化、父级级联情况。
谁触发了谁？ -> 使用
```
profiler-commit-query
```
mode=
```
cascade_tree
```
——可视化父子级联关系。
iOS卡顿详情？ -> 使用
```
profiler-stack-query
```
mode=
```
hang_stacks
```
——卡顿期间的原生调用栈。

根据需要重复操作，直到确定根本原因函数和文件，参考步骤4进行诚实评估。每轮调查后，询问用户是否继续深入或进入修复阶段。

Step 7: Reload a previous session

步骤7：重新加载过往会话

If you profiled multiple scenarios and need to revisit earlier data:

Call
```
profiler-load
```
mode=
```
list
```
to see all saved sessions with timestamps (the list now also shows Runtime / Device / Metro bundle columns to help identify the right session).
Call
```
profiler-load
```
mode=
```
load_react
```
session_id=
```
<timestamp>
```
device_id=
```
<UDID>
```
to reload React data.
```
device_id
```
scopes the reload into the
```
port:device_id
```
cache slot.
Call
```
profiler-load
```
mode=
```
load_native
```
session_id=
```
<timestamp>
```
device_id=
```
<UDID>
```
to reload native profiler data.
Query tools now operate on the reloaded session data — pass the same
device_id
you loaded with, otherwise they will miss the cache.

This is useful for before/after comparisons: profile, fix, re-profile, then reload the original session to compare metrics side by side.

如果分析了多个场景并需要查看早期数据：

调用
```
profiler-load
```
mode=
```
list
```
查看所有带时间戳的已保存会话（列表现在还显示Runtime/Device/Metro bundle列，帮助识别正确会话）。
调用
```
profiler-load
```
mode=
```
load_react
```
session_id=
```
<timestamp>
```
device_id=
```
<UDID>
```
重新加载React数据。
```
device_id
```
将重新加载范围限定到
```
port:device_id
```
缓存槽。
调用
```
profiler-load
```
mode=
```
load_native
```
session_id=
```
<timestamp>
```
device_id=
```
<UDID>
```
重新加载原生性能分析数据。
查询工具现在将基于重新加载的会话数据运行——传递与加载时相同的
device_id
，否则会错过缓存。

这适用于修复前后对比：分析、修复、重新分析，然后重新加载原始会话以并排对比指标。

Step 8: Apply fix and re-profile

步骤8：应用修复并重新分析

If fix is present, read the source code of the identified bottleneck using

react-profiler-component-source

or the Read tool. Apply the fix, then re-profile (Step 1 -> user interaction -> Step 2 -> Step 3 -> Step 4). Report whether the target metric improved, stayed flat, or regressed. Also check whether the fix introduced regressions in other metrics (e.g., render count dropped but CPU time increased, or a different component now re-renders more). If the fix showed no net benefit or unacceptable tradeoffs, revert and reconsider.

Tip: If the interaction sequence was recorded as a flow (see "Use flows for reproducible profiling" above), replay it with

flow-execute

instead of manually repeating the steps. This guarantees identical interaction conditions for the comparison. If the flow fails during replay (e.g., a UI fix changed the layout), follow

argent-create-flow

skill §10 (Flow Self-Improvement) to diagnose and repair the flow before retrying the profiling cycle.

If the user stated that they do not wish for changes, present the profiling report and skip the fix but suggest it to the user.

React Compiler rule: If the analyze report indicates React Compiler is enabled, do NOT propose

useCallback

useMemo

React.memo

unless you confirmed compiler bail-out (check

react-profiler-fiber-tree

for absent

useMemoCache

on that component).

如果有修复方案，使用

react-profiler-component-source

或Read工具查看已识别瓶颈的源代码。应用修复，然后重新进行性能分析（步骤1 -> 用户交互 -> 步骤2 -> 步骤3 -> 步骤4）。报告目标指标是改善、保持不变还是退化。同时检查修复是否导致其他指标退化（例如渲染次数减少但CPU时间增加，或其他组件现在重渲染更频繁）。如果修复未带来净收益或存在不可接受的权衡，回退并重新考虑方案。

提示： 如果交互序列已记录为流程（参见上文“使用流程确保可重复分析”），使用

flow-execute

重放流程，而非手动重复步骤。这确保对比时的交互条件完全一致。如果重放流程时失败（例如UI修复改变了布局），遵循

argent-create-flow

技能第10节（流程自优化）诊断并修复流程后，再重试性能分析周期。

如果用户表示不希望进行更改，展示性能分析报告并跳过修复步骤，但可向用户建议修复方案。

React Compiler规则： 如果分析报告显示React Compiler已启用，除非确认编译器出现退出情况（查看

react-profiler-fiber-tree

中该组件是否缺少

useMemoCache

），否则不要提议使用

useCallback

useMemo

React.memo

。

5. Important Caveats

5. 重要注意事项

Dev mode inflation:
```
buildMode: "dev"
```
renders are ~3x slower than production. Prioritize high
```
normalizedRenderCount
```
— it scales to prod.
Re-run after fixes: Always re-profile after changes. Report honestly whether the metric improved, regressed, or stayed flat — do not assume improvement.
excluded
is informational: Components in
```
animatedSubtrees
```
and
```
recyclerChildren
```
re-render by design.
Strict Mode: Double-invokes renders. The pipeline halves
```
normalizedRenderCount
```
automatically when detected.
Debugger connection: If interrupted, started profiling also closes. Before attempting recovery, call
```
react-profiler-status
```
— it tells you whether the session is
```
active
```
,
```
taken_over
```
,
```
stopped
```
, or
```
no_react_runtime
```
, so you can decide whether to stop, restart, or reconnect first.
Confounders to watch for:
- Live API data may differ between runs (different payload sizes, content counts), which shifts render counts and durations independently of your fix. Note when data-dependent components show variance.
- Profiler overhead inflates CPU measurements. If iOS Instruments shows
```
JSLexer
```
  ,
```
JSONEmitter
```
  , or Hermes internals dominating the JS thread, that reflects profiler instrumentation cost — not app work. Discount those entries.
- Runs are not perfectly reproducible. Small variations (under ~10-15%) in commit duration may be noise; only treat consistent, directional changes as signal.

For standalone diagnostic tools (live render stats, fiber tree, CPU summary), see

references/diagnostic-tools.md

开发模式膨胀：
```
buildMode: "dev"
```
下的渲染速度比生产环境慢约3倍。优先关注高
```
normalizedRenderCount
```
——它已按生产环境标准缩放。
修复后重新分析：更改后务必重新进行性能分析。如实报告指标是改善、退化还是保持不变——不要假设一定有改善。
excluded
仅作参考：
```
animatedSubtrees
```
和
```
recyclerChildren
```
中的组件是设计使然的重渲染。
严格模式：会双重调用渲染。检测到严格模式时，处理流程会自动将
```
normalizedRenderCount
```
减半。
调试器连接：如果连接中断，已启动的性能分析也会关闭。尝试恢复前，调用
```
react-profiler-status
```
——它会告知你会话是
```
active
```
、
```
taken_over
```
、
```
stopped
```
还是
```
no_react_runtime
```
，以便你决定是停止、重启还是先重新连接。
需要注意的干扰因素：
- 实时API数据在不同运行中可能不同（不同 payload大小、内容数量），这会独立于修复改变渲染次数和时长。注意依赖数据的组件出现的差异。
- 性能分析工具的开销会夸大CPU测量结果。如果iOS Instruments显示
```
JSLexer
```
  、
```
JSONEmitter
```
  或Hermes内部组件占用JS线程主导地位，这反映的是性能分析工具的 instrumentation成本——而非应用本身的工作。忽略这些条目。
- 运行并非完全可重复。提交时长的微小差异（约10-15%以内）可能是噪声；只有持续的方向性变化才视为有效信号。

如需独立诊断工具（实时渲染统计、fiber树、CPU摘要），请查看

references/diagnostic-tools.md

。