react-devtools

agent-react-devtools

通过 React DevTools 协议连接正在运行的 React 或 React Native 应用的 CLI，并以节省 token 的格式展示组件树、props、state、hooks 和性能分析数据。

核心工作流

1. 确保连接 — 检查 agent-react-devtools status。如果守护进程未运行，请使用 agent-react-devtools start 启动。使用 agent-react-devtools wait --connected 阻塞等待 React 应用连接。
2. 检查 — 获取组件树、搜索组件、检查 props/state/hooks。
3. 性能分析 — 开始性能分析，触发交互（或请用户触发），停止性能分析并分析结果。
4. 采取行动 — 使用数据修复错误、优化性能或说明当前情况。

必备命令

守护进程

agent-react-devtools start              # Start daemon (auto-starts on first command)
agent-react-devtools stop               # Stop daemon
agent-react-devtools status             # Check connection, component count, last event
agent-react-devtools wait --connected   # Block until a React app connects
agent-react-devtools wait --component App # Block until a component appears

组件检查

agent-react-devtools get tree           # Full component hierarchy (labels: @c1, @c2, ...)
agent-react-devtools get tree --depth 3 # Limit depth
agent-react-devtools get component @c5  # Props, state, hooks for a specific component
agent-react-devtools find Button        # Search by display name (fuzzy)
agent-react-devtools find Button --exact # Exact match
agent-react-devtools count              # Count by type: fn, cls, host, memo, ...
agent-react-devtools errors             # List components with errors or warnings

性能分析

agent-react-devtools profile start              # Start recording
agent-react-devtools profile stop               # Stop and collect data
agent-react-devtools profile slow               # Slowest components by avg render time
agent-react-devtools profile slow --limit 10    # Top 10
agent-react-devtools profile rerenders          # Most re-rendered components
agent-react-devtools profile report @c5         # Detailed report for one component
agent-react-devtools profile timeline --limit 10                        # First 10 commits (use --limit; uncapped can dump 300+ lines)
agent-react-devtools profile timeline --limit 10 --offset 10           # Next 10 (pagination)
agent-react-devtools profile timeline --sort duration --limit 5        # Top 5 most expensive commits
agent-react-devtools profile timeline --sort timeline --limit 5        # Explicit chronological order (same as default)
agent-react-devtools profile commit 3           # Detail for commit #3
agent-react-devtools profile export profile.json # Export as React DevTools Profiler JSON
agent-react-devtools profile diff before.json after.json  # Compare two exports

了解输出

组件标签

每个组件都会获得一个稳定的标签，例如 @c1、@c2。在后续命令中使用这些标签引用组件：

@c1 [fn] App
├─ @c2 [fn] Header
├─ @c3 [fn] TodoList
│  ├─ @c4 [fn] TodoItem key=1
│  └─ @c5 [fn] TodoItem key=2
└─ @c6 [host] div

类型缩写：fn = 函数，cls = 类，host = DOM 元素，memo = React.memo，fRef = forwardRef，susp = Suspense，ctx = context。

存在错误或警告的组件会显示注释：⚠2 = 2 个警告，✗1 = 1 个错误。使用 agent-react-devtools errors 仅列出受影响的组件。

检查组件

@c3 [fn] TodoList
props:
  items: [{"id":1,"text":"Buy milk"},{"id":2,"text":"Walk dog"}]
  onDelete: ƒ
state:
  filter: "all"
hooks:
  useState: "all"
  useMemo: [...]
  useCallback: ƒ

ƒ = 函数值。超过 60 个字符的值会被截断。

性能分析输出

Slowest (by avg render time):
  @c3 [fn] ExpensiveList  avg:12.3ms  max:18.1ms  renders:47  causes:props-changed  changed: props: items, filter
  @c4 [fn] TodoItem  avg:2.1ms  max:5.0ms  renders:94  causes:parent-rendered, props-changed  changed: props: onToggle

渲染原因：props-changed、state-changed、hooks-changed、parent-rendered、force-update、first-mount。

当有具体的变更键时，changed: 后缀会显示触发渲染的具体 props、state 键或 hooks（例如：changed: props: onClick, className state: count hooks: #0）。

常见模式

重新加载后等待应用连接

agent-react-devtools wait --connected --timeout 10
agent-react-devtools get tree

触发页面重新加载或 HMR 更新后使用此命令，避免查询到空状态。

诊断交互缓慢的问题

agent-react-devtools profile start
# User interacts with the app (or use agent-browser to drive the UI)
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5
agent-react-devtools profile rerenders --limit 5

然后使用 get component @cN 和 profile report @cN 检查性能最差的组件。

分段浏览较长的时间线

agent-react-devtools profile timeline --limit 20               # commits 0–19
agent-react-devtools profile timeline --limit 20 --offset 20   # commits 20–39
agent-react-devtools profile timeline --offset 30 --limit 10   # skip warm-up, show 30–39

发现性能峰值后，使用 profile commit <N> 深入检查特定提交。

查找组件并检查其状态

agent-react-devtools find SearchBar
agent-react-devtools get component @c12

验证修复是否生效

agent-react-devtools profile start
# Repeat the interaction
agent-react-devtools profile stop
agent-react-devtools profile slow --limit 5
# Compare render counts and durations to the previous run

与 agent-browser 搭配使用

使用 agent-browser 驱动应用进行性能分析或调试时，必须使用有头模式（--headed）。无头 Chromium 执行 ES 模块脚本的方式与真实浏览器不同，因此无法正常运行 devtools connect 脚本。

agent-browser --session devtools --headed open http://localhost:5173/
agent-react-devtools status  # Should show 1 connected app

重要规则

• **应用重新加载或组件卸载后重新挂载时，标签会重置。**重新加载后，使用 wait --connected，然后通过 get tree 或 find 重新检查。
• 先运行 status — 如果状态显示已连接的应用数为 0，则 React 应用尚未连接。Web 用户可能需要运行 npx agent-react-devtools init；React Native 用户需要按照 setup.md 完成两个手动步骤。此状态下，树观察命令会以 No React app is attached 退出，代码为 1；应将其视为“尚未观察到任何内容”，而不是干净的结果。
• 其他 DevTools 连接会重新分配 ID — 当 React Native DevTools（或其他 Agent）连接到同一个应用时，React 会使用新 ID 重新刷新组件树，守护进程也会替换其副本。再次运行 get tree 或 find，再使用之前的 @cN 标签。
• 必须使用有头浏览器 — 如果使用 agent-browser，务必启用 --headed 模式。无头 Chromium 无法正确加载 devtools connect 脚本。
• 在交互期间进行性能分析 — 性能分析只会捕获 profile start 和 profile stop 之间发生的渲染。确保相关交互发生在这段时间内。
• 对于大型组件树使用 --depth — 深层组件树可能会产生大量输出。先使用 --depth 3 或 --depth 4，仅在需要检查的子树上进一步增加深度。

参考资料

文件	阅读时机
commands.md	完整的命令参考，包含所有标志和边界情况
profiling-guide.md	逐步了解性能分析工作流和结果解读
setup.md	如何连接不同的框架（Vite、Next.js、Expo、CRA）