rn-devtools-hub

rn-devtools-hub

React Native 的 Agent 运行时。你的 Agent 能像 React 一样看到应用，知道每个元素由哪个文件生成，无需坐标即可操作，并验证操作是否成功。零依赖，不收集遥测数据或统计用量，配有本地中枢和 SDK。

文档 · 快速开始 · 集成 · 参与贡献

在 Agent 中使用

两个插件都会安装 MCP 服务，以及一个教会 Agent 如何串联工具的技能：在调试看似不可能的问题前检查项目上下文；用断言而非截图证明结果；等待事件，而非休眠；读取元素的源码，而非在仓库中搜索。

Claude Code

/plugin marketplace add rn-devtools-hub/rn-devtools-hub
/plugin install rn-devtools-hub

Codex

codex plugin marketplace add rn-devtools-hub/rn-devtools-hub
codex plugin add rn-devtools-hub

然后在应用根目录启动中枢，Agent 会与它通信：

npx rn-devtools-hub

也可以手动注册服务。Claude Code：

claude mcp add rn-devtools --transport http http://127.0.0.1:8973/mcp

Codex，在 ~/.codex/config.toml 中：

[mcp_servers.rn-devtools]
url = "http://127.0.0.1:8973/mcp"

Cursor 没有市场，因此需要在自己的项目中创建两个文件。 在 .cursor/mcp.json 中声明服务：

{
  "mcpServers": {
    "rn-devtools": { "type": "http", "url": "http://127.0.0.1:8973/mcp" }
  }
}

然后复制规则，它相当于 Cursor 中的技能：

mkdir -p .cursor/rules
cp node_modules/rn-devtools-hub/templates/cursor-rule.mdc \
   .cursor/rules/rn-devtools-hub.mdc

该规则默认设置为 alwaysApply: false，因此 Cursor 会在任务匹配时加载它，而不是每次请求都加载并产生费用。

对于其他 Agent，可单独从 skills.sh 注册表获取该技能：

npx skills add rn-devtools-hub/rn-devtools-hub

它会写入 .agents/skills/rn-devtools-hub，并链接到它检测到的 Agent，包括 Gemini CLI、Copilot、Windsurf 和 Zed。此操作只会安装技能，因此请按上述说明注册服务并启动中枢，让 Agent 能与之通信。

任何只支持 stdio 的客户端都可以使用 npx rn-devtools-hub mcp，它会桥接到中枢，并按需启动中枢。

测试或调试任务开始时，系统会指示 Agent 宣告项目名称和可点击的仪表板 URL，然后自动继续。中枢会提供实际绑定的端口和当前令牌，即使第二个项目使用了备用端口也不例外。list_devices、get_project_context 和 session_start 的 dashboard 字段中也提供该链接。

截图

概览：一目了然地查看请求数、错误率、JS 线程延迟、连接和设备

网络：方法以颜色区分，高耗时请求高亮显示，JSON 可折叠，可复制为 cURL；机密信息会在离开设备前脱敏

镜像：通过 adb 显示设备实时屏幕，点击可轻触，拖动可滑动，滚轮可滚动，并支持返回、主页、最近任务和开发者菜单

工具：查看 Agent 执行的操作和应用的响应；按已答复／空答复／失败分类统计各工具调用；按消息归类失败；显示附带工具给出的原因的空答复，以及每条答复计入 Agent 费用的上下文

## 为什么

该 SDK 位于应用的 JavaScript 运行时内部。

该 SDK 与应用代码直接并行执行。它通过安装在应用内部的 API 读取 React 的树、调用处理程序、检测请求，并访问已注册的存储。hub 通过自身的本地连接接收这些能力，无需建立调试器协议会话。其他工具可以通过 CDP 等协议访问运行时内部；hub 则以明确的应用内 SDK 及其事件契约为基础。

整个产品正是建立在这一定位之上。其他一切都由此而来：

Agent 可以	因为它位于运行时内部
按角色和可访问名称查找元素，然后对其执行操作	操作通过应用自身的 props 执行，而不是通过像素
获取生成某个元素的文件和行号	位置信息保存在 React 的开发环境记录中
无需截图即可证明某个步骤	截图无法显示悄无声息地失败的请求
区分过时的原生构建与代码问题	只有运行时知道二进制文件的实际情况
冻结时钟和网络	Date 和 fetch 位于运行时中
无需逐屏操作十个页面即可将应用置于精确状态	可以直接访问存储
解释视觉回归，而不只是给出评分	变化区域可以对应到负责它的组件

应用内纯 JavaScript SDK（在生产环境中不执行任何操作）、单进程本地 hub、浏览器中的仪表盘。任何地方都没有依赖，包括 hub。hub 不收集遥测数据。MCP 结果会交付给你的 Agent，并可能发送给其模型提供商。已配置的存储插件会联系其声明的供应商端点。

功能

面板	显示内容
概览	KPI 磁贴、JS 线程延迟、HTTP 状态、耗时分布
崩溃	致命错误、JS 错误、未处理的 Promise 拒绝、调用栈
网络	请求/响应检查器（按方法着色，显示耗时和大小）、复制为 cURL、密钥已脱敏
上传	实时上传队列（如果你的应用会发送这些事件，请参阅协议）
缓存	React Query 快照：键、状态、新鲜度、数据
存储	AsyncStorage 键、大小、值、实时写入时间戳
屏幕	导航轨迹、各屏幕停留时间
日志	console.log/info/warn/error、彩色 JSON、筛选器
SQLite	针对应用数据库的只读 SQL 控制台（SELECT/PRAGMA）
端点	已声明端点、调用次数和延迟的映射
操作	控制应用的按钮：重新加载、清除缓存、自定义操作
测试	易于阅读的 .hubflow 场景、实时回放进度、失败诊断、已批准的视觉证据和安全的目标修复候选项
工具	Agent 如何使用此 Hub：每种工具的调用次数、带错误信息的失败、空答复及原因、返回的上下文字节数（像素单独计数，因为会话如果将大部分上下文用于截图，就是以昂贵的方式进行验证）、使用的选择器，以及根据应用自身事件回放的循环
插件	应用周边的服务：App Store Connect 和 Google Play 的配置、是否允许更改发布版本，以及将联系的所有主机
设计	图标、启动画面、字体、声音、身份信息（从 app.json 和资源中读取）
镜像	实时应用屏幕（应用中需要 react-native-view-shot）、通过 adb 操控完整 Android（点击、滑动、键盘、Wi-Fi）、通过 xcrun 操控 iOS 模拟器

概览面板会先显示项目上下文：项目声明了什么、应用实际运行了什么，以及两者之间的所有不一致之处。原生构建版本过期是最常见的耗时问题，面板会在你开始阅读代码前指出这一点。

此外还支持：合并会话的多设备模式、以 Markdown 导出 Bug 报告（可直接用于 GitHub issue）、实时能力徽章，以及可通过 Claude、Cursor 或任何 MCP 客户端驱动所有功能的本地 MCP 服务。

参阅 Hubflow 场景，了解如何记录探索过程、将其保存为运行时回归测试、在 CI 中回放，并在仪表板中检查选定的成功或失败截图。

Agent 能获取什么

工具	能回答的问题
get_project_context	项目声明了什么、实际运行的是什么，以及其中的矛盾。遇到任何看似不可能的行为时，先调用它
get_ui_tree、query_ui	可见组件，以及生成每个组件的源文件和行号
ui_act	按元素点击、输入、提交、滚动，绝不按像素操作
assert	验证一个步骤：元素类型会重试；事件类型会捕获静默失败的请求、控制台错误或未处理的拒绝
freeze_time、mock_network	在 JS 层实现确定性，让场景重复运行时结果一致
get_state、set_state	无需逐屏操作，即可将应用置于精确状态
render_component	在运行中的应用内、使用真实的提供器挂载组件
snapshot_baseline、compare_snapshot	视觉差异对比，并指出拥有变更区域的组件
export_session、export_flow	一条关联的时间线，以及与其所致后果配对的操作
save_flow、list_flows、get_flow、run_flow、propose_flow_repair	持久化运行时场景，使用断言和截图重放，并在强标识目标发生移动时创建可供审核的修复候选
audit_accessibility	React 渲染了什么，但无障碍树未公开什么
list_plugins、asc_*、gplay_*	应用周边的发布信息：构建是否已处理完成、版本正在何处审核、生产环境正在提供哪个版本、商店评论怎么说；以及执行发布操作：分发到 TestFlight、提交审核、提升轨道、扩大或暂停分阶段发布
capture_store_screenshots	从运行中的应用重新生成 App Store 和 Play 商店截图：根据清单指定设备、语言区域和屏幕，通过应用自己的开发操作逐个打开，以原生分辨率捕获并上传。像素绝不会进入 Agent 的上下文

在 React 19 中，源位置保存在指向 bundle 的 owner stacks 中；hub 会先通过 Metro 为其解析符号，再将结果提供给 Agent。

对于 AI Agent，hub 还通过 MCP 提供运行时 UI 自动化： get_ui_tree（从 React 运行时读取可见组件的语义树，包括地图等缺少无障碍信息的原生视图）、query_ui（按角色和无障碍名称、testID、占位文本、文本或标签查找元素，可用 within 限定范围，并获取测量出的矩形区域）、ui_act（按元素点击、输入准确文本、提交、滚动，绝不按像素操作；并回读字段以确认文本是否已输入），类型化开发操作（list_actions/run_action：导航、填充数据、登录，无需触碰 UI），以及关联的事件流（wait_for_event、get_events_since），用 screen.ready 等真实信号取代休眠等待。支持 Expo Go、开发版和裸 React Native，也支持在没有模拟器的 CI 中运行：通过 devtools.attachUiAutomation() 启用。

hub 也涵盖原生层，功能超出 idb/simctl 脚本为 Agent 提供的能力：session_start 会在正确的 Metro 服务上启动开发版，不会弹出任何对话框（预先授予权限，并跳过开发菜单引导），还提供 set_permission、launch_app、open_url、screenshot_native、set_location、send_push、set_appearance、set_animations、set_overlay（expo-dev-menu 气泡会遮挡原生控件，而 UI 树无法显示这些控件），以及最后手段 tap_native 和 swipe_native；支持 iOS 模拟器和 Android 设备，并会探测每项能力，在能力不可用时平稳降级。

以上所有功能都止步于机器端。发布流程中不在机器端完成的那一半由插件负责：App Store Connect 和 Google Play 随 hub 一同提供，在你提供凭据之前会保持未启用状态。它们既能读取发布信息，也能执行发布操作，因此，决定扩大分阶段发布范围的 Agent，就是已经掌握崩溃证据的那个 Agent。安装 hub 的插件时，也会一并安装发布技能，无需再添加其他内容。 已配置的插件会在启动时打印它将联系的主机；未配置的插件不会暴露任何工具，而不是浪费 Agent 无法使用的上下文；设置 RN_DEVTOOLS_PLUGIN_WRITES=off 则会移除所有可能更改内容的工具。参见 docs/plugins.md。

快速开始

前置条件：Node 20+。如果存在，则会使用 Bun，但并非必需。可选功能（adb 镜像、iOS 模拟器、Wi-Fi）各有其前置条件：参见集成指南。

# 1. In your React Native / Expo project, as a devDependency:
npm install --save-dev rn-devtools-hub

# 2. Wire it up automatically (detects your libraries, writes the glue,
#    hooks the entry point, adds the `devtools` script):
npx rn-devtools-hub init

# 3. Start the hub (runs on Bun or Node 20+)
npm run devtools
# -> Dashboard: http://localhost:8973/?token=... (URL printed at startup)

init 会检查你的项目，并且只生成实际能够运行的代码：如果你使用 axios，就生成 axios 拦截；如果你有 AsyncStorage，就生成 Storage 面板；如果你有 expo-device，就生成设备信息，依此类推。它绝不会覆盖现有的胶合代码文件（使用 --force），而 --dry-run 会显示它将进行哪些更改。

就是这样：日志、崩溃和性能数据已可流入。每项额外集成（网络、缓存、存储、SQLite、镜像……）都只需几行配置：参见集成指南。

集成指南

SDK 不依赖特定库：它提供通用基础功能，由你接入自己的库。所有配置示例都在 docs/integration.md 中，尤其包括：

• devtools.attachAxios(instance, "api")：适用于任何 axios 实例
• devtools.wrapFetch(fetch, "uploads")：适用于任何基于 fetch 的客户端
• devtools.emit(type, payload)：向任意面板提供数据
• devtools.onCommand(name, handler)：响应仪表板请求（例如 SQLite）
• devtools.registerAction({name, label, danger, requiresNative}, handler)
• devtools.attachUiAutomation()：为 AI Agent 提供 UI 感知和操作能力
• devtools.markScreenReady("Login")：Agent 等待的“屏幕就绪”信号
• 完整的事件和命令协议： docs/protocol.md。这是契约：任何工具（或任何 大模型）都可以通过实现该协议来集成面板。

宿主项目依赖

SDK 不施加任何要求。根据你需要的功能，在自己的项目中添加：

功能	在项目中安装	类型
软件包本身	rn-devtools-hub	devDependencies
应用镜像（屏幕流）	react-native-view-shot	dependencies（已包含在 Expo Go 中）
Storage 面板	@react-native-async-storage/async-storage	大多数应用中已存在
SQLite 控制台	expo-sqlite（或你的驱动程序 + 一个 sqlite.query 处理程序）	取决于你的应用
增强型设备信息	expo-device、expo-application、expo-network	dependencies
完整 Android 镜像	开发机器上的 adb（不在应用中）	系统工具
iOS 模拟器镜像	Xcode 命令行工具（开发机器）	系统工具

安全

• SDK 在 __DEV__ 之外处于非活动状态（双重防护：你的防护和 SDK 的防护）
• 仪表板需要令牌（启动时打印；使用 RN_DEVTOOLS_TOKEN 固定令牌）
• 敏感请求头（Authorization、cookies、x-api-key）会在离开设备前被脱敏
• SQLite 控制台仅接受 SELECT 和 PRAGMA
• MCP 服务仅监听 localhost，并验证 Origin
• Design 面板资源仅限于项目根目录，且扩展名必须在白名单中
• 插件是唯一的出站通道；没有凭据时处于非活动状态。每个插件都会声明其联系的主机，工具绝不会返回凭据，也不会将凭据写入日志
• 每个会更改内容的插件工具都会明确声明，并附带标注，以便 MCP 客户端确认；还可以通过 RN_DEVTOOLS_PLUGIN_WRITES=off 将其完全移除
• RN_DEVTOOLS_SCREENSHOTS=off（或设为一个数字）会移除像素捕获功能，或限制其数量，适用于不希望 Agent 通过截图进行验证的团队

贡献

欢迎贡献。完整指南请参阅 CONTRIBUTING.md。简而言之：

git clone https://github.com/rn-devtools-hub/rn-devtools-hub
cd rn-devtools-hub
npm install          # also installs the husky hooks
npm test             # vitest
npm run typecheck
npm run hub          # starts the local hub to test the dashboard

• 提交遵循 Conventional Commits （feat:、fix:、docs: 等）：变更日志和版本会据此自动生成（release-it），commitlint 会在提交时检查提交信息
• 提交前钩子会运行类型检查和测试
• 发布：npm run release（维护者）

AI Agent 请阅读 AGENTS.md 和 llms.txt。

许可证

MIT