ExecBro

ExecBro

让你的 AI 助手能够观察并操作正在运行的 React Native 应用。 就像 Chrome DevTools，不过是为 AI Agent 打造的。

无需离开聊天界面，即可端到端地构建、调试和验证功能。

ExecBro 是你的 AI 编码助手与正在运行的 React Native 应用之间的运行时桥梁，可通过 MCP 工具读取日志和网络数据、检查组件状态、截取屏幕截图、点击界面并运行 JS。无需配置，无需 SDK 或修改代码即可开始使用；不过建议安装可选 SDK，以获得最可靠的日志和网络数据采集体验。

开始使用

1. 为你选择的 Agent 设置 ExecBro MCP 服务
2. 设置 UI 自动化辅助工具
3. 在 React Native 应用中安装 SDK——可选，但建议安装，以获得最可靠的日志、网络和状态体验
4. 授权并关联 Web 控制面板——可选，用于查看使用统计和会话历史
5. 启动 React Native 应用（npm start / expo start）
6. 用自然语言向 AI 助手提出请求，例如：“连接到模拟器并调查屏幕上错误的原因”

查看使用情况——execbro.com

登录 execbro.com，即可查看 ExecBro 活动的可视化结果：你最常使用哪些工具、工具的错误率以及会话历史，从而发现不稳定的工具、跟踪使用情况变化，并了解 Agent 在不同会话中如何操作应用。这些数据基于遥测与隐私中所述的相同匿名遥测信息生成，并与你的安装 ID 相关联。

关联账号仅用于控制面板：它会将你的安装关联到账号，以便统计数据归你所有。工具的任何功能都不会因此受到限制。

功能

运行时交互

• 控制台日志捕获 - 捕获 console.log、warn、error、info、debug，并支持筛选和搜索。请注意：冷启动时（首次启动应用），在 MCP 服务连接前输出的日志会丢失；后续重新加载时则会捕获所有日志。安装可选的 SDK，即可从应用启动的第一行开始缓冲日志
• 网络请求跟踪 - 监控 HTTP 请求和响应，包括标头、耗时和正文内容。与日志一样，冷启动时连接建立前发出的早期网络请求可能会丢失。安装可选的 SDK，即可从应用启动时开始完整捕获请求和响应正文
• 响应模拟 - 替换或篡改 HTTP 响应，让应用通过真实代码路径触发错误——包括请求构造器、错误分支和重试逻辑——而不是直接写入状态来伪造错误。可模拟离线、延迟响应、仅让首次尝试失败以测试重试，或修改一个字段后重新发送已捕获的请求。规则在重新加载后仍然有效，且经过修改的流量始终会被标记。请参阅模拟教程
• JavaScript 执行 - 直接在应用中运行代码（REPL 风格）并检查结果
• 全局状态调试 - 查找并检查 Apollo Client、Redux stores、Expo Router 和自定义全局对象。通过可选的 SDK，将 stores 和其他应用内部组件直接接入 Agent，以便直接、可靠地访问状态
• 打包错误检测 - 获取 Metro 打包器错误和编译问题及其文件位置
• 点击定位源码 - 使用 RN 的元素检查器指向任意元素，即可获取渲染该元素的绝对源文件路径和行号；这些信息通过 Metro 符号化从 React fiber 的 _debugStack 中解析得出。在 React 19 中也能正常使用，因为该版本已不再提供 _debugSource。选择结果会在后台缓冲，因此你在手动检查器会话期间进行的点击也会被捕获，无需先询问 Agent

设备控制

• iOS Simulator - 截图、应用管理、URL 处理、启动／终止（通过 simctl）
• Android Devices - 截图、应用安装／启动、软件包管理（通过 ADB）
• 统一点击 - 使用单个 tap 工具，并自动按以下链路回退：fiber 树 → 无障碍功能 → OCR → 坐标。自动检测平台，直接接受截图和布局工具提供的坐标，无需转换。默认返回点击后的截图，并验证画面是否发生变化
• 统一滑动 - 使用单个 swipe 工具，根据已连接的设备自动路由到 iOS 或 Android。坐标与布局工具和截图使用相同的屏幕坐标系，无需转换；并返回 verification.meaningful 信号，帮助 Agent 检测列表末尾、不可滚动的界面以及未命中目标的坐标；如果屏幕上没有 React Native 连接，则会说明无法检查，而不会猜测。对于滚动虚拟化列表（FlatList/SectionList）至关重要，因为屏幕外的项目不在 fiber 树中
• 真实多点触控缩放 （仅限 Android 模拟器 — iOS 支持正在开发中） - pinch 工具通过 Android 模拟器的多点触控桥接发送两个真实的内核触控点，因此可缩放地图、图库、WebView 和原生视图——它在应用底层运行，而非通过 React Native。返回与 swipe 相同的 verification.meaningful 信号，并会在目标不受支持时拒绝操作，而不是伪造结果
• UI 自动化 - 在两个平台上支持滑动、长按（使用 duration 的 tap，按 testID／文本／组件解析目标）、按键事件和文本输入。input_text 直接定位字段并通过读回内容验证写入；在 Bridgeless/Fabric 应用中，replace:true 会通过 onChangeText 更新 React 状态，以覆盖预填值，因此受控组件（Formik、react-hook-form、useState）能保持一致。native:true 会向操作系统报告为焦点所在的对象输入文本，无需 RN 连接；dismiss_keyboard 也以相同方式运行
• 无障碍检查 - 查询 UI 层级，以文本、标签或资源 ID 查找元素
• OCR 文本提取 - 通过 Google Cloud Vision 提取可见文本及可直接点击的坐标（适用于任意屏幕内容）

凭据安全

• 机密永远不会进入对话记录 - 每个工具的输出都会经过统一的脱敏关卡，因此无论令牌出现在网络标头、Redux 存储、日志行还是 URL 中，都会被替换为句柄（[secret:auth_api.acme.io]）。凭据标头通过模式匹配，而非固定列表，因此也涵盖带供应商命名空间的标头（x-shopify-access-token、x-goog-api-key、x-hasura-admin-secret）；而 x-request-id 和 x-idempotency-key 则会有意保留。无法按单次调用绕过：EXECBRO_REDACT=off 需由人工设置，并且需要重启
• 无需读取凭据即可使用 - list_secrets 会列出句柄；http_request({auth:{secret:"api.acme.io"}}) 会在主机端替换凭据值，并从你的机器发出请求——默认使用 Authorization: Bearer，也可使用密钥标头或其他方案，因此即使遇到不受支持的格式，也无需粘贴凭据；如果没有捕获到能揭示令牌的请求，vault_capture 会直接从应用读取令牌并存入保险库。每项凭据都与观测到它的源绑定，在其他源上会被拒绝；保险库仅驻留于内存
• 服务器端与客户端隔离运行 - http_request 从主机发出，不使用应用的 TLS 信任设置、代理、Cookie 存储或模拟规则；app_request 则在应用内运行，并使用上述所有设置。比较两者即可判断问题出在后端还是客户端——如果主机收到 401，而应用请求成功，这本身就说明后端强制执行了证明机制
• 将应用数据视为数据 - 服务器会告知每个连接的 Agent：日志、负载、组件树和 eval 结果的内容由应用交互对象决定，绝不能将其视为指令执行

多设备调试

• 连接所有设备 - scan_metro 会自动发现并连接每个 Metro 端口上的所有 Bridgeless 目标
• 设备定向 - 每个工具都接受可选的 device 参数，可按名称定向到特定设备（不区分大小写的子字符串匹配）
• 独立设备缓冲区 - 按设备分别捕获日志和网络请求，方便清晰地进行调试
• 跨平台对比 - 并排调试 iOS 和 Android，对比日志、网络流量和组件树

Electron 和 Chromium（实验性）

• 通过 CDP 调试桌面 React 应用 - Electron 窗口或 Chrome 标签页可作为 chromium 目标与模拟器并列连接，所有工具都使用相同的 device 参数

• 目前可用的功能 - 控制台日志、网络捕获、重放和模拟（network_mock、network_condition）、execute_in_app、调试全局变量、Redux、http_request / app_request、React 组件检查（get_component_tree、find_components、inspect_component），包括 DevTools hook 中没有渲染器的 Vite 应用，以及 screenshot、tap、input_text、swipe（鼠标滚轮滚动，以及使用四个坐标进行真实拖动）和 press_key（Enter、Escape、Tab、方向键、快捷键）。JavaScript 对话框（alert / confirm / prompt / beforeunload）会由打开它们的工具报告，不会超时；对话框打开时，页面工具会拒绝执行；handle_dialog 可接受或关闭对话框。点击操作可通过 data-testid / id、可见文本或 React 组件名称查找元素，并使用真实 CDP 鼠标事件点击。无需截图即可读取屏幕：get_screen_state（可点击的元素、被覆盖层遮挡的内容）、get_screen_layout、inspect_at_point 和 measure

• 暂不支持 - pinch、navigate 和其他仅限移动端的工具遇到 chromium 目标时会拒绝执行并说明原因，而不会误操作其他设备。目前尚未处理原生 HTML5 拖放（draggable）和悬停

• 零配置启动 - electron_launch_app({ projectPath: "path/to/app" }) 会从 Electron 项目的源代码文件夹启动应用，打开调试端口并连接其窗口。它运行项目自身的 electron 或 electron-vite，不会运行打包后的构建版本

• 或者手动启用 - 在 Electron 主进程中添加一行仅用于开发的代码，然后运行 scan_metro。系统会列出端口 9222，但不会自动连接，因为连接会向页面注入网络拦截器。使用 connect_metro({ port: 9222, device: "<window title>" }) 附加连接，或者设置 EXECBRO_CHROMIUM_PORTS=9222 以自动连接

  if (!app.isPackaged) app.commandLine.appendSwitch('remote-debugging-port', '9222')
  

  保留 !app.isPackaged 守卫：打包版本上开放调试端口，会允许任何能访问该端口的对象在渲染进程中运行代码

原生 Android（预览版）

• 无需 JavaScript 运行时的 Kotlin 应用 - 原生应用在调试构建版本中包含 execbro-sdk-android 后，即可注册命名状态和命令。scan_metro 会通过 adb 发现该应用，list_debug_globals 和 inspect_global 可读取其状态，run_app_command 可运行其命令，navigate 可驱动 Jetpack Navigation，screenshot 可截取屏幕
• 即将推出 - SDK 尚未发布到 Maven。Execbro 已支持此功能；SDK 发布后将提供安装说明

工作原理

• 自动发现 - 自动扫描 8081-8090 端口上的 Metro，并列出 9222 上的 Chromium/Electron 目标（以及 EXECBRO_CHROMIUM_PORTS 中的任何端口）
• 多设备支持 - 同时连接所有 Bridgeless 目标，并为每台设备分别提供日志和网络缓冲区
• 自动重新连接 - 连接断开时采用指数退避策略（最多尝试 8 次）
• 高效缓冲 - 循环缓冲区：500 条日志、200 个网络请求、100 条检查器选择记录
• 平台支持 - Expo SDK 54+（Bridgeless）和 React Native 0.70+（Hermes）

设置

只需一条命令即可将 ExecBro 添加到 Claude Code——无需安装，npx 会按需获取最新版本：

claude mcp add execbro --scope project -- npx -y execbro@latest

然后彻底重启客户端（退出并重新启动），使其加载新的服务。

项目级配置会写入 .mcp.json，你可以将其提交到代码库，这样整个团队都能在此仓库中使用 ExecBro，而不会影响其他地方。将 project 替换为 user，即可改为全局注册——如果你整天都在开发 React Native，这会很方便；但每次打开会话时都会启动 ExecBro，包括那些没有 Metro 服务可连接的仓库。

使用其他客户端或需要平台设置？ 完整设置指南涵盖 Claude Desktop、Codex CLI、Cursor、VS Code Copilot、Windsurf、Zed 和 Gemini CLI，以及 Android 和 iOS 模拟器 UI 自动化的相关要求。

安装 SDK（推荐）

ExecBro 无需更改应用即可运行，但安装配套的 execbro-sdk 包，是提升调试质量最有效的方法。它可以让你将应用中的关键部分——状态存储和网络层——直接接入 Agent，使 AI 检查真实的 Redux/TanStack Query 状态和完整的请求/响应正文，而不是在外部猜测。

	不使用 SDK	使用 SDK
状态存储（Redux、TanStack Query、……）	通过 execute_in_app 手动操作	已接入——可直接引用
请求/响应正文	不可用	完整（包括 GraphQL）
启动时的网络请求（身份验证、配置）	会遗漏	从首次 fetch 开始捕获
启动时的控制台日志	可能遗漏早期日志	从第一条日志开始捕获
支持 Bridgeless（Expo SDK 52+）	部分支持	完全支持

只需执行一次 npm install，并在应用入口文件中调用一次 init()。安装、初始化及所有配置选项，请参阅 SDK 指南。

要求

• Node.js 20.9+
• 正在运行 Metro bundler 的 React Native 应用
• 推荐：在应用中使用 execbro-sdk——将状态存储和网络层接入 Agent，大幅提升调试效果（可选；不使用也能运行 ExecBro）
• iOS UI 自动化：AXe CLI（brew install cameroncooke/axe/axe，默认）或 Facebook IDB（brew install idb-companion，通过 IOS_DRIVER=idb 启用）——iOS 模拟器上的点按、滑动、文本输入和无障碍功能均需要它
• 离线 OCR 回退的可选要求：Python 3.6+（仅在云端 OCR 不可用时需要，参阅 OCR 指南）

Claude Code 技能

针对常见调试工作流预先构建的技能——会话设置、日志检查、网络调试等。完整列表和安装说明请参阅技能指南。

可用工具

如需查看所有工具及其说明，请参阅完整工具参考。主要工具：

Tool	Description
scan_metro	从这里开始 — 扫描 Metro 服务并自动连接
get_logs / search_logs	捕获并搜索控制台日志，支持筛选和摘要
get_network_requests	监控 HTTP 请求，支持按方法和状态筛选
get_screen_state	方向快照 — 当前路由、覆盖层，以及每个可点击元素的 (x, y) 坐标
get_screen_layout	可见组件的屏幕示意图，包含位置、尺寸和文本内容
tap	统一点击 — 自动检测平台，并依次尝试 fiber → accessibility → OCR → 坐标
pinch	真实双指缩放 — 仅适用于 Android 模拟器（iOS 支持正在开发中）
input_text	输入文本 — 自动定位并聚焦字段，或使用 native:true 输入到当前焦点所在位置。replace:true 会先清除内容（Fabric）
dismiss_keyboard	取消当前输入框的焦点并关闭屏幕键盘
execute_in_app	在应用运行时中执行 JS 表达式（REPL 风格）
screenshot	在任意平台截取屏幕：iOS 模拟器、Android、Electron 或 Chrome，以及通过 USB 连接的实体 iPhone/iPad（仅支持捕获）

使用方法

1. 启动 React Native 应用：

   npm start
   # or
   expo start
   

2. 只需用自然语言描述你的需求 — Agent 会选择合适的工具。你无需了解工具名称，也不必指定使用哪个工具。例如：

   Connect to the simulator and investigate what caused the error on the screen
   

   Check the network logs and investigate why this error is happening
   

   Why is the current screen empty? Take a look and figure it out
   

   Tap the "Sign in" button and tell me what happens
   

   The list won't scroll — scroll it down and check what's going on
   

   Why does this button look wrong — what component renders it and where?
   

   Agent 会连接到 Metro，读取日志和网络信息，检查屏幕，并根据需要操作界面来回答问题。

详细指南

指南	描述
设置	各客户端的 MCP 配置（Claude、Codex、Cursor、VS Code 等）、Android 和 iOS 设置
SDK 设置	安装应用内 SDK 并调用 init()，将存储和网络层接入 Agent
控制台日志	get_logs 参数、过滤、摘要模式、令牌优化
网络跟踪	完整捕获的 SDK 设置、过滤、请求详情、统计数据
网络模拟	教程：强制返回 500、移除字段、测试重试、切换到离线状态、重放请求
应用检查	调试全局对象（Apollo、Redux、Expo Router）、execute_in_app、限制
布局和组件检查	get_screen_layout、组件树、inspect_at_point、find_components
设备交互	统一的 tap、平台专属手势、文本输入、按键事件
OCR 文本提取	tap 中的 Cloud Vision OCR、离线回退、语言配置
Claude Code 技能	用于会话设置、调试和自动化的预构建技能
完整工具参考	全部 62 个工具的完整列表及说明

工作原理

1. 从 Metro 的 /json 端点获取设备列表
2. 通过 CDP（Chrome DevTools Protocol）WebSocket 连接到主 JS 运行时
3. 启用 Runtime.enable，接收 Runtime.consoleAPICalled 事件
4. 通过两种路径捕获网络数据：
   • 使用 SDK：通过 Runtime.evaluate 从 SDK 的应用内缓冲区读取数据，可捕获启动以来的所有请求及完整的请求头和请求体，包括 CDP 可能遗漏的冷启动事件
   • 不使用 SDK：在支持的目标上启用 CDP Network.enable，或注入 JS fetch 拦截器作为回退方案。冷启动时，CDP 连接建立前发出的事件会丢失；之后重新加载则可捕获所有内容
5. 响应模拟在同一个注入的拦截器中运行：请求到达网络前会匹配规则，并将规则重新推送到每个新的 JS 上下文中，确保重新加载后规则仍然生效
6. 将日志和网络请求存储在循环缓冲区中，以供检索

连接管理

• 每个会话运行一个服务 — 每个 Agent 会话（每个终端或 IDE 窗口）都会运行自己的 ExecBro MCP 服务实例。
• 按需连接，而非启动时连接 — 服务不会自动连接。只有在你发出请求（例如 scan_metro）时，它才会连接到正在运行的 React Native 应用，因此在你确实需要设备之前，它不会妨碍你。
• 每台设备由一个驱动程序控制 — 如果同一项目中的两个或更多会话连接到同一个 Metro/设备，它们就会争夺控制权，就像一辆车有两个方向盘。每台设备只在一个会话中进行交互。
• 想要并行运行多个会话？为每个会话分配独立的设备和端口 — 在 git worktree 中运行独立的工作，并在不同端口启动各自的 Metro 实例，再连接另一台设备（模拟器/仿真器）。例如，让 main 使用默认端口 8081，然后在工作树中用端口 8082 启动 Metro（npx react-native start --port 8082，或 npx expo start --port 8082），再启动该工作树中指向 8082 的应用。随后，每个 Agent 会话都可以运行 scan_metro 并控制自己的设备，彼此不会争夺连接。

故障排查

未找到设备

• 确认应用正在模拟器/设备上运行
• 检查 Metro bundler 是否正在运行（npm start）

未显示日志

• 确认应用正在实际运行（而不只是 Metro）
• 尝试运行 clear_logs，然后在应用中触发一些操作
• 检查 get_apps，确认连接状态
• 冷启动时（首次启动）： CDP 连接是在应用的早期初始化代码运行之后才建立的，因此会错过启动日志和网络请求。连接建立后，运行 reload_app——由于连接已就绪，后续重新加载会从一开始就捕获所有内容。若要在每次启动时捕获启动事件，请安装可选的 SDK

遥测与隐私

绝不会发送源代码、文件路径或应用内容。 你的应用和代码仓库都会留在你的设备上。

ExecBro 会发送两项简要信号：

• 产品分析（可选）——工具名称、成功/失败情况和耗时。这些数据用于生成你的用量仪表板，并帮助我了解哪些工具不稳定、值得修复。你可以随时在 MCP 服务配置中通过 EXECBRO_TELEMETRY=false 关闭此功能。
• 使用次数——持续累计你调用工具的次数。这只是一个数字，不包含内容，也是关闭分析后仍会持续运行的唯一信号。

请参阅遥测与数据收集指南，了解完整的逐字段说明；完整隐私政策请参阅 PRIVACY.md。

支持的 React Native 版本

版本	架构	引擎	状态
Expo SDK 54+	无桥接（新架构）	Hermes	✓ 完全支持
RN 0.76+	无桥接（新架构）	Hermes	✓ 完全支持
RN 0.73 - 0.75	Bridge（旧架构）	Hermes	✓ 完全支持（通过 CDP 捕获网络的效果最佳）
RN 0.70 - 0.72	Bridge（旧架构）	Hermes / JSC	✓ 支持
RN < 0.70	Bridge	JSC	未测试

定价

ExecBro 免费。所有工具均可使用，没有调用上限，也无需账号。关联账号是可选的，只用于查看用量仪表板。

反馈与功能请求

请在会话结束时运行此操作，帮助我改进这些工具。 ExecBro 专为 AI Agent 打造，因此最有价值的反馈来自 Agent 本身——将此提示词粘贴给你的 Agent：

撰写一份报告，介绍你使用 ExecBro 工具的体验——遇到的困难以及可以改进的地方。将报告保存为 Markdown 文件，然后使用 send_feedback 工具（类型为 "feedback"）提交，这样它就会成为一个 GitHub issue。

只需 30 秒：你的 Agent 运行 send_feedback，为你提供一个预填好的 GitHub issue URL（已附加环境信息），你点击提交即可——无需设置 GitHub，也无需复制粘贴。真实会话中的实际问题记录将帮助确定路线图，并优先修复这些问题，所以请发送一份反馈。🙏 如果你只是有个简单的想法或问题，可以加入 GitHub 讨论区，分享反馈、请求新功能，并为接下来要开发的内容投票。

包名与保持更新

以 npm 包 execbro 的形式发布。该包此前以 react-native-ai-devtools 发布，更早之前的名称是 react-native-ai-debugger——这两个旧名称通过镜像发布继续接收完全相同的构建版本，因此现有安装和 MCP 配置无需更改即可继续使用。新安装请使用 execbro。

重要

已经在使用 ExecBro？ npx 会无限期缓存包，因此你可能在不知情的情况下仍在使用旧版本。请将 MCP 配置更新为 npx -y execbro@latest（参见设置），这样每次会话都会获取包含新工具和错误修复的最新版本。完成此更改后，新安装也会自动更新。

许可证

MIT