Sanity 仓库实战agent-react-devtools CLI 全命令参考与 React 渲染剖析工作流【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity本文以 Sanity 仓库中.agents/skills/react-devtools/references/commands.md这份命令参考文档为主体完整覆盖agent-react-devtoolsCLI 的全部命令、参数与输出约定并结合仓库内 sanity.cli.ts、AGENTS.md 及配套的 SKILL.md、profiling-guide.md、setup.md讲透如何用它对正在运行的 React含 Sanity Studio应用做组件检查与渲染性能剖析。读完后你可以独立搭建 daemon 连接、用标签体系精确定位组件的 props/state/hooks并跑通一套「基线 → 剖析 → 定位瓶颈 → 修复验证」的完整性能诊断流程。一、工具定位为 AI Agent 设计的 React DevTools CLIagent-react-devtools是一个通过 React DevTools 协议连接正在运行的React 或 React Native 应用的 CLI 工具。它的架构由三部分组成依据 commands.md 与 SKILL.mdDaemon守护进程后台常驻监听两类连接——来自 React 应用的WebSocket连接以及来自 CLI 自身的IPC连接。所有组件树、profiling 数据都汇聚在这里Connect 脚本注入到应用中的连接模块负责把react-devtools-core接到 daemon 的 WebSocket 上CLI把组件树、props/state/hooks、profiling 数据以「token 高效」的紧凑格式输出供人或 AI Agent 消费。它的典型使用场景正是 Sanity 仓库dev/test-studio测试用 Studio的渲染剖析AGENTS.md 专门用一节说明了如何用该 daemon 暴露 React 组件树与渲染剖析数据让 Agent 检查 props/state/hooks、排查不必要的重渲染。核心工作流继承自 SKILL.md分四步确保连接status查状态必要时start启动 daemonwait --connected阻塞等待应用接入检查组件get tree、find、get component查看树结构与组件内部状态性能剖析profile start→ 触发交互 →profile stop→ 分析结果行动基于数据修 bug、优化性能或解释现象。二、Daemon 管理命令agent-react-devtools start [--port N]启动后台 daemon。默认端口 8097。daemon 监听来自 React 应用的 WebSocket 连接和来自 CLI 的 IPC 连接。文档特别指出运行任何其他命令时 daemon 会自动启动因此你很少需要显式执行这条命令。--port N可覆盖默认端口当 8097 被其他 DevTools 实例占用时需要。agent-react-devtools stop停止 daemon 进程。所有连接状态都会丢失——应用需要重新握手才能再次被 CLI 查询。agent-react-devtools status显示 daemon 状态字段包括端口、已连接应用、组件数量、profiling 状态、运行时长、最后一次连接事件。输出示例原文档即给出Daemon: running (port 8097) Apps: 1 connected, 42 components Last event: app connected 3s ago Uptime: 120s若剖析正在进行输出中会额外显示Profiling: active。排障要点来自 SKILL.md 与 setup.md 的规则status应作为每次会话的第一步。如果显示Apps: 0 connected说明 React 应用没有连上常见原因有应用没有跑在 dev 模式、控制台有 WebSocket 连接错误、8097 端口被占用、应用尚未配置 connect 脚本用户可能需要在项目里先运行npx agent-react-devtools init。agent-react-devtools wait --connected [--timeout S]阻塞直到至少一个React 应用通过 WebSocket 连上如果已有连接则立即返回。默认超时 30 秒超时时以非零码退出。agent-react-devtools wait --component name [--timeout S]阻塞直到组件树中出现指定display name的组件采用精确名称匹配exact name matching。适合在页面重载后等待 UI 的某一部分渲染完成再继续查询。默认超时 30 秒超时时以非零码退出。典型配合模式重载后避免查询到空状态agent-react-devtools wait --connected --timeout 10 agent-react-devtools get tree三、组件检查命令agent-react-devtools get tree [--depth N]以缩进树的形式打印组件层级。每个节点展示四部分信息标签c1、c2、…——会话内稳定应用重载后重置类型标记fn函数组件、cls类组件、hostDOM 元素、memoReact.memo、fRefforwardRef、suspSuspense、ctxContext显示名称Key如果存在。输出示例c1 [fn] App ├─ c2 [fn] Header ├─ c3 [fn] TodoList │ ├─ c4 [fn] TodoItem key1 │ └─ c5 [fn] TodoItem key2 └─ c6 [host] div--depth N用于限制树的深度。对大型应用强烈建议加这个参数——深度树会产出巨量输出建议从--depth 3或--depth 4起步再对关心的子树逐步加深。agent-react-devtools get component cN | id检查单个组件展示三块内容props—— 所有 prop 的值。函数值显示为ƒ超过 60 字符的长值会被截断state—— 状态值类组件与useStatehooks—— 所有 hook 的当前值及子 hook。参数接受两种形式标签c5或数字形式的 React fiber ID。输出示例c3 [fn] TodoList props: items: [{id:1,text:Buy milk},{id:2,text:Walk dog}] onDelete: ƒ state: filter: all hooks: useState: all useMemo: [...] useCallback: ƒ性能排查时重点看函数型 propsƒ——若父组件没用useCallback包裹很可能是每次渲染都变化的不稳定引用对象/数组型 props——若没被useMemo包裹同样会破坏子组件的memo()bailout。agent-react-devtools find name [--exact]按显示名称搜索组件。默认是大小写不敏感的子串匹配加--exact则做精确匹配。返回一份扁平的匹配组件列表含标签、类型与 key。agent-react-devtools find SearchBar agent-react-devtools get component c12 # 接着用标签深入检查agent-react-devtools count按类型统计组件数量输出形如42 components (fn:25 host:12 memo:3 cls:2)适合在剖析前快速确认「有多少组件挂载了」建立基线。agent-react-devtools errors列出所有 error 或 warning 计数非零的组件。React 按组件维度追踪 console 错误与警告这条命令把它们汇总呈现c5 [fn] Form ⚠2 ✗1 c8 [fn] Input ✗3符号约定⚠N N 条警告✗N N 条错误。全部干净时返回No components with errors or warnings。这些错误/警告注解同样会出现在get tree、get component和find的输出中计数非零时。四、Profiling 命令Profiling 只捕获profile start与profile stop之间发生的渲染务必让被剖析的交互发生在这个窗口内。同一时间只允许一个活跃的剖析会话。agent-react-devtools profile start [name]开始一个剖析会话可选名称用于标识如profile start typing in search。同时只能有一个会话处于活跃状态。agent-react-devtools profile stop停止剖析并向 React 收集数据。输出摘要包含时长、commit 数量、渲染最多的组件。agent-react-devtools profile slow [--limit N]按平均渲染时长从慢到快排序组件。默认 limit 10。输出列标签、类型标记、组件名、平均时长、最大时长、渲染次数、全部渲染原因causes、变化的 keychanged keys。agent-react-devtools profile rerenders [--limit N]按渲染次数从多到少排序组件。默认 limit 10。输出列标签、类型标记、组件名、渲染次数、全部渲染原因、变化的 key。这两个视图互补profiling-guide.md 用两个极端例子说明差异渲染 100 次、每次 0.1ms 总计 10ms重渲染问题看rerenders渲染 2 次、每次 50ms 总计 100ms慢渲染问题看slow。渲染原因causes的取值props-changed、state-changed、hooks-changed、parent-rendered、force-update、first-mount。agent-react-devtools profile report cN | id针对单个组件的详细渲染报告渲染次数、平均/最大/总时长、全部渲染原因、变化的 key。agent-react-devtools profile timeline [--limit N] [--offset N] [--sort duration|timeline]按时间顺序列出剖析会话中的所有 React commit每条含索引、时长、组件数量。默认 limit 20。头部会说明返回了哪些 commitCommit timeline (showing 1–20 of 87):若全部装得下则显示Commit timeline (42 commits):。排序与分页语义原文档的精确约定默认顺序为时间顺序chronological--sort duration在应用--limit之前先按时长降序重排——用于找最昂贵的 commit--sort timeline显式请求时间顺序与默认相同--offset N跳过排序后的前 N 条可与--limit组合分页浏览 commit或跳过已知的预热区warm-up。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 --sort duration --limit 5 # 最贵的 5 个 commitagent-react-devtools profile commit N | #N [--limit N]查看指定索引 commit 的详情每个组件的 self/total 时长、渲染原因、变化的 key。在 timeline 中发现时长尖峰后用它下钻。agent-react-devtools profile export file把剖析数据导出为JSON 文件可直接导入 React DevTools 的 Profiler 标签页做可视化分析也可作为profile diff的输入。要求存在一个活跃或刚停止的剖析会话。agent-react-devtools profile diff before.json after.json [--limit N] [--threshold N]对比两次导出的剖析会话展示退化regressed、改善improved、新增new、移除removed四类组件。默认 threshold 5%——变化幅度低于该百分比的不报告--limit N限制每个类别展示的组件数。该命令不需要 daemon 在运行是离线对比工具。Changed Keys定位重渲染的元凶当 React DevTools 能报告究竟是哪些 props、state key 或 hook 触发了重渲染时profiling 命令会在行尾追加changed:后缀changed: props: onClick, className state: count hooks: #0没有变化的类别会被省略。在聚合报告profile slow、profile rerenders、profile report中变化的 key 会跨 commit 去重。结合 changed keys 的典型修复对照表继承自 profiling-guide.md原因Changed keys 示例含义典型修复parent-rendered(无)父组件重渲染且子组件无法 bail out用React.memo()包裹子组件props-changedprops: onClick, style收到新的 prop 引用在父组件用useMemo/useCallback稳定列出的 propsstate-changedstate: count, filter组件自身状态变化检查列出的 state 更新是否必要hooks-changedhooks: #0, #2某个 hook 的依赖变化按索引复查列出的 hooks 的依赖数组first-mount(无)首次渲染正常现象不是问题五、Setupinit命令与多框架接入agent-react-devtools init [--dry-run]在当前目录自动检测框架并配置 devtools 连接。支持Vite、Next.js、CRA、Expo/React Native。--dry-run可在不写文件的情况下预览将要做的修改。各框架的具体接入方式详见 setup.mdViteinit向配置中添加 Vite 插件插件只在 dev 模式vite dev生效会在应用代码加载前注入 connect 脚本零应用代码改动// vite.config.ts import {reactDevtools} from agent-react-devtools/vite export default defineConfig({ plugins: [reactDevtools(), react()], })Next.jsApp Routerinit创建一个导入 connect 脚本的客户端组件并加入根 layout// app/devtools.tsx use client import agent-react-devtools/connect export default function DevTools() { return null }Create React Appinit把import agent-react-devtools/connect前置写入src/index.tsx。React Native / Expo无需代码改动应用自动连接 8097 端口的 devtools WebSocket真机调试时用adb reverse tcp:8097 tcp:8097反向代理端口。手动接入init覆盖不到的场景把import agent-react-devtools/connect作为入口文件的第一个 import。connect 脚本具备三个特性SSR 安全服务端 no-op、生产安全production build 中被 tree-shake 掉、通过 WebSocket 连接且带 2 秒超时。连接验证agent-react-devtools status应显示Apps: 1 connected, 42 components。若显示 0 connected按「应用是否在 dev 模式 → 控制台 WebSocket 错误 → 8097 端口占用 → 浏览器是否 headed」逐项排查。六、Sanity 仓库中的真实接线方式上述命令在 Sanity 仓库里并非纸上谈兵——dev/test-studio已经完整打通。以下三处仓库证据展示了真实调用链。1. 环境开关与 Vite 插件注入。dev/test-studio/sanity.cli.ts 定义了开关// React DevTools profiling via agent-react-devtools. Usage: pnpm react-devtools:test-studio (see AGENTS.md). const isReactDevtoolsEnabled process.env.ENABLE_REACT_DEVTOOLS true当ENABLE_REACT_DEVTOOLStrue时vite()配置函数懒加载该插件并合入 Vite 配置sanity.cli.tsif (isReactDevtoolsEnabled) { const {reactDevtools} await import(agent-react-devtools/vite) nextConfig mergeConfig(nextConfig, {plugins: [reactDevtools()]}) }这正是 setup.md 所述 Vite 接入路径在 Sanity CLI 配置体系defineCliConfig下的落地形态reactDevtools()插件负责向 dev server 注入 connect 脚本把react-devtools-core接到 daemon 的 WebSocket。2. 一键启动脚本。根目录 package.json 定义了react-devtools:test-studio: ENABLE_REACT_DEVTOOLStrue pnpm dev:test-studio:studio3. 完整剖析流程与注意事项。AGENTS.md 给出的标准操作序列# 1. 启动 daemon端口 8097 pnpm --filter sanity-test-studio exec agent-react-devtools start # 2. 以注入 connect 脚本的方式启动 studio隐含 ENABLE_REACT_DEVTOOLStrue pnpm react-devtools:test-studio # 3. 浏览器打开 http://localhost:3333然后确认应用已注册 pnpm --filter sanity-test-studio exec agent-react-devtools status # 4. 剖析一次交互 pnpm --filter sanity-test-studio exec agent-react-devtools profile start # ... 与 studio 交互 ... pnpm --filter sanity-test-studio exec agent-react-devtools profile stop pnpm --filter sanity-test-studio exec agent-react-devtools profile rerenders --limit 10该节同时列出了几条仓库级的实战 gotchas仅限 dev-server插件按apply: serve工作永远不会出现在sanity build产物里即生产构建不受影响——与 connect 脚本「生产安全」的设计一致浏览器必须是 headed 模式headless Chromium 对 ES module 脚本的执行方式不同注入的 connect 脚本无法正常执行应用永远不会向 daemon 注册。自动化时用agent-browser --session devtools --headed open http://localhost:5173/关闭 StrictMode 再剖析用SANITY_STUDIO_REACT_STRICT_MODEfalse跑避免 dev 双渲染把时长数据放大——生产 Studio 本就不跑 StrictMode。七、端到端剖析工作流从基线到修复验证把命令参考串起来profiling-guide.md 定义了六步闭环流程适合对任意 React 应用包括 Sanity Studio照做第 1 步建立基线。agent-react-devtools status # 确认应用已连接 agent-react-devtools count # 有多少组件挂载 agent-react-devtools get tree --depth 3 # 理解结构第 2 步剖析交互。profile start typing in search起个名字让被报慢的交互输入、点击、导航发生在剖析窗口内然后profile stop。第 3 步定位瓶颈。同时看两个维度profile slow --limit 5谁单次渲染最贵与profile rerenders --limit 5谁渲染次数过多二者互补分别对应「慢渲染」与「重渲染」两类问题。第 4 步下钻可疑组件。profile report c12给出全部渲染原因与 changed keys用 changed keys 精确锁定要稳定化或排查的对象对照上文的修复表。第 5 步检查组件现场。get component c12查看当前 props 与 hooks函数 props 是否缺少useCallback、对象/数组 props 是否缺少useMemo、是否有更新过于频繁的 state。第 6 步修复并验证。用同样的交互重新剖析并对比agent-react-devtools profile start after fix # 同样的交互 agent-react-devtools profile stop agent-react-devtools profile slow --limit 5对比渲染次数与时长确认改善。若需要更正式的回归对比使用导出/对比工作流# 变更前 agent-react-devtools profile start before agent-react-devtools profile stop agent-react-devtools profile export before.json # 变更后同样的交互 agent-react-devtools profile start after agent-react-devtools profile stop agent-react-devtools profile export after.json # 离线对比无需 daemon agent-react-devtools profile diff before.json after.jsondiff 报告输出 regressed / improved / new / removed 四类组件--threshold默认 5%调节灵敏度--limit限制每类条数。profiling-guide.md 还归纳了四类常见性能问题模式便于在读 profiling 数据时对号入座Context / 上提状态引发的级联重渲染——父组件因定时器或 context 变化重渲染子组件无React.memo全部跟着渲染。特征高渲染次数 parent-rendered原因不稳定的 prop 引用——父组件内联传onClick{() ...}或style{{...}}每次渲染产生新引用使memo()失效。子组件显示props-changed而changed:输出直接指认元凶如changed: props: onClick, style未做记忆化的昂贵计算——每次渲染都做过滤/排序/格式化表现为高平均渲染时长修复用useMemoEffect 中的状态更新引发渲染循环——表现为profile timeline中异常高的 commit 数。八、关键规则与边界条件汇总原文档与各参考文件中的硬性约定避免踩坑标签会重置应用重载或组件卸载/重挂载后cN标签全部失效。重载后先wait --connected再用get tree或find重新定位先查status0 connected 即应用未接入回到 init/setup 环节排查headed 浏览器配合agent-browser自动化时务必--headed剖析窗口profiling 只记录start与stop之间的渲染交互必须落在窗口内大树上用--depth从 34 层起步避免一次 dump 数百行输出timeline 要加--limit不加限制时一次可能输出 300 行 commit 记录适用前提整套机制依赖应用跑在dev 模式并注入 connect 脚本生产构建中 connect 脚本会被 tree-shake 掉CLI 无法连接生产部署的应用。结语agent-react-devtools把 React DevTools 协议下最有价值的运行时数据——组件树、props/state/hooks、逐 commit 渲染剖析——压缩成了一套可脚本化、可被 Agent 消费的低 token CLI 命令。Sanity 仓库的.agents/skills/react-devtools/技能文档以 commands.md 为命令权威参考辅以 SKILL.md 的工作流、profiling-guide.md 的剖析方法论与 setup.md 的框架接入说明与dev/test-studio的真实接线sanity.cli.ts、AGENTS.md共同构成了一份可复制的模板任何基于 React 的内容工作室都可以照此接入用wait → get tree → find → profile → diff这条命令链完成从「感觉慢」到「定位到具体 prop 与修复验证」的完整闭环。【免费下载链接】sanitySanity Studio – Rapidly configure content workspaces powered by structured content项目地址: https://gitcode.com/GitHub_Trending/sa/sanity创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考