SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场agent-react-devtools

agent-react-devtools

编程与开发

查看项目

更新于 10-15 16:28

技能介绍

用途

agent-react-devtools 是一个 React DevTools 的命令行接口，旨在让 AI 智能体能够检查正在运行的 React 应用。它通过一个常驻后台守护进程，提供对组件树、props、state、hooks 以及渲染性能数据的程序化访问。该技能属于 ara.so 的 Devtools Skills 集合。

主要能力

  • 组件检查：获取完整组件树、限制树深度、包含宿主组件、从特定组件获取子树、查看组件详情（props、state、hooks）、按名称搜索组件、按类型统计组件数量、列出有错误或警告的组件。
  • 性能分析：启动/停止分析会话、查找最慢组件、查找重渲染最多的组件、查看提交时间线、检查特定提交、获取特定组件的渲染报告、导出分析数据、比较两次分析导出结果。
  • 等待命令：等待应用连接或等待特定组件出现，适合在脚本中使用，成功退出码为 0，超时为 1。
  • 守护进程管理：启动、查看状态、停止守护进程，支持自定义端口。

使用方式

安装

全局安装：

npm install -g agent-react-devtools

或直接使用 npx：

npx agent-react-devtools start

连接 React 应用

快速设置（推荐）：自动配置项目，检测框架（Vite、Next.js、CRA）并自动修补配置：

npx agent-react-devtools init

撤销：

npx agent-react-devtools uninit

手动设置 - 单行导入：在入口点（如 src/main.tsx）添加，作为第一个导入：

import "agent-react-devtools/connect";

手动设置 - Vite 插件：无需修改应用代码：

// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { reactDevtools } from "agent-react-devtools/vite";

export default defineConfig({
  plugins: [
    reactDevtools(), // Must come before react()
    react()
  ],
});

自定义端口：

reactDevtools({ port: 8097, host: "localhost" })

React Native 设置：自动连接：

agent-react-devtools start
npx react-native start

物理设备需转发端口：

adb reverse tcp:8097 tcp:8097

核心概念

  • 守护进程：常驻后台进程（默认端口 8097），维护连接状态。
  • 组件 ID：组件标记为 @c1、@c2 等，便于引用。
  • 宿主过滤：默认过滤 HTML 元素（<div>、<span>）以保持输出紧凑。
  • LLM 优化：输出 token 高效且结构化，便于 AI 消费。

关键命令

守护进程管理：

agent-react-devtools start
agent-react-devtools start --port 8097
agent-react-devtools status
agent-react-devtools stop

组件检查：

agent-react-devtools get tree
agent-react-devtools get tree --depth 3
agent-react-devtools get tree --all
agent-react-devtools get tree @c5
agent-react-devtools get component @c6
agent-react-devtools find TodoItem
agent-react-devtools find App --exact
agent-react-devtools count
agent-react-devtools errors

组件详情输出示例：

@c6 [fn] TodoItem key=1
props:
  id: 1
  text: "Buy groceries"
  done: false
  onToggle: ƒ
hooks:
  State: false
  Callback: ƒ

等待命令：

agent-react-devtools wait --connected --timeout 30
agent-react-devtools wait --component App --timeout 30

性能分析：

agent-react-devtools profile start
agent-react-devtools profile start "user-interaction-test"
agent-react-devtools profile stop
agent-react-devtools profile slow
agent-react-devtools profile slow --limit 5
agent-react-devtools profile rerenders
agent-react-devtools profile timeline
agent-react-devtools profile commit 3
agent-react-devtools profile commit #3
agent-react-devtools profile report @c5
agent-react-devtools profile export results.json
agent-react-devtools profile diff before.json after.json
agent-react-devtools profile diff before.json after.json --threshold 2.0

常见工作流

调试组件问题：启动守护进程并连接应用，查找问题组件，检查其 state 和 props，查看周围上下文。

性能调查：在交互前启动分析，在应用中执行交互，停止并分析，调查特定组件。

自动化测试/监控：脚本示例（CI 或监控）：

#!/bin/bash
agent-react-devtools start
agent-react-devtools wait --connected --timeout 30 || exit 1

# Check for components with errors
if agent-react-devtools errors | grep -q "@c"; then
  echo "Components have errors!"
  agent-react-devtools errors
  exit 1
fi

# Profile a workflow
agent-react-devtools profile start "ci-test"
# ... trigger app interactions ...
agent-react-devtools profile stop
agent-react-devtools profile export ci-results.json

# Check for slow components
SLOW_COUNT=$(agent-react-devtools profile slow --limit 5 | grep -c "avg:")
if [ "$SLOW_COUNT" -gt 3 ]; then
  echo "Too many slow components detected"
  agent-react-devtools profile slow
  exit 1
fi

与 agent-browser 配合使用：

# IMPORTANT: Must use --headed mode
agent-browser --session devtools --headed open http://localhost:5173/
agent-react-devtools status  # Verify connection
agent-react-devtools profile start
# ... agent-browser interactions ...
agent-react-devtools profile stop
agent-react-devtools profile slow

注意：无头模式不工作——DevTools 连接需要有头浏览器。

配置

环境变量：REACT_DEVTOOLS_PORT - React Native 应用的自定义端口。

默认端口：守护进程默认使用端口 8097。覆盖方式：

agent-react-devtools start --port 9000

然后配置应用连接以匹配。

输出格式说明

  • 组件 ID（@c1、@c2）在守护进程会话内持久。
  • 错误标注：⚠ 表示警告，✗ 表示错误。
  • 函数指示符：ƒ 标记函数 props/回调。
  • 树符号：├─ 表示中间子节点，└─ 表示最后一个子节点。
  • 折叠指示符：输出截断时显示 ... +N more。

与 AI 助手集成

添加到项目的 AGENTS.md 或 .cursorrules：

## React Component Inspection

Use `agent-react-devtools` to inspect the running React app:

1. Start daemon: `agent-react-devtools start`
2. Check connection: `agent-react-devtools status`
3. Browse tree: `agent-react-devtools get tree --depth 3`
4. Inspect component: `agent-react-devtools get component @cN`
5. Profile performance: `agent-react-devtools profile start` → interact → `profile stop` → `profile slow`

Always check `status` before other commands to ensure app is connected.

适用场景

  • AI 智能体调试 React 组件问题。
  • 性能调查与优化。
  • 自动化测试与监控（CI 脚本）。
  • 与 agent-browser 等自动化交互工具配合使用。

限制

  • 连接仅在开发构建中工作，不适用于生产环境。
  • 与 agent-browser 配合时必须使用有头模式，无头模式不工作。
  • 分析数据仅在停止分析会话后收集。
  • 使用 init 后若显示 "No apps connected"，需检查导入顺序（connect 导入必须是入口文件第一个导入）、Vite 插件顺序（reactDevtools() 必须在 react() 之前）、开发服务器是否运行。
  • 组件树为空时，可移除宿主组件过滤（--all）或检查应用是否渲染（count）。
  • 等待连接超时可增加超时时间或检查端口是否被占用（lsof -i :8097）。

许可证

MIT