RN Agent Observer

VI · English

RN Agent Observer 2.4.0 是 React Native/Expo 的本地运行时可观测性桥接工具。该工具为 CLI 和 MCP 使用同一个 TypeScript 核心，通过 ADB/UIAutomator 控制 Android，从开发插桩接收遥测数据，通过 Metro 的 Chrome DevTools Protocol 导出 console/exception/heap/JS CPU profile，无需插桩即可按请求捕获网络流量，为 agent 生成包含 state/headline/actions/UI findings 的屏幕理解，提供会话稳定的 ref 快照 + diff + 自动录制回放，录制屏幕视频，用 SQLite 保存会话，并将截图/trace/UI 树作为 artifact 保存在磁盘上。

当前版本在 Windows 上完成了 Android v1：45 个 MCP 工具、对应的 CLI、带有确定性实验室的 Expo 演示、透明的启发式诊断以及像素 + UI 结构对比。

要求

• Node.js 22.12 或更高版本

• pnpm 9.6

• Android Platform Tools（adb）

• 已启用 USB 调试的 Android 模拟器或物理设备

• 如果需要应用特定的遥测数据，则需要 Expo development build

Related MCP server: React Native MCP Server

快速开始

pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:check

将 observer 指向你的 Expo/React Native 应用：

$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Có thể bỏ qua nếu app.json chứa expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'

pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnose

Artifacts 和 SQLite 数据创建在 <projectRoot>/.artifacts/ 下；大型二进制文件永远不会嵌入 MCP 响应中。

确定性演示

pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>

演示包含 PerformanceLab、NetworkLab、RenderLab、AnimationLab、ErrorLab 和 VisualLab。NetworkLab 使用内部 fixture（0/500/2000ms 和 HTTP 503），因此不依赖互联网服务。PerformanceLab 通过插桩精确报告其故意的 100ms 长 JS 任务。

MCP

pnpm mcp:check
pnpm mcp:start

服务器使用 stdio。客户端配置和全部 45 个工具的列表记录在 docs/protocol.md 中。

AI agent 集成

有 3 种方式让 agent（OpenCode/Claude Code/Cursor/Codex...）使用 observer：

1. MCP 服务器（推荐 — 结构化工具）

{
  "mcpServers": {
    "rn-agent-observer": {
      "command": "node",
      "args": [
        "C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
        "RN_OBSERVER_DEVICE_ID": "emulator-5554"
      }
    }
  }
}

2. 作为 skill 安装（通过 CLI 教 agent 调试工作流）

npx skills add GinzaTech/rn-agent-observer

Skill 位于 skills/rn-agent-observer/SKILL.md — 教 agent observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare 循环、如何诚实地读取指标以及常见故障恢复。安装后，只需说"调试应用 X 卡顿"，agent 就会自动知道使用 rn-observe。

3. AGENTS.md（当 agent 直接在此仓库中工作时） — 已存在于仓库根目录，agent 会自动读取。

三种方式可以同时使用：skill/AGENTS.md 教 工作流，MCP 提供 可直接调用的工具。

文档

• 详细使用指南

• 完整项目概览（VI/EN）

• 架构

• CLI 和 MCP 协议

• 指标定义

• 能力矩阵

• 测试和运行时验证

• 测试蓝图

• 故障排除

• 更新日志

当前版本

• Android/Windows 是 Observer 2.4.0 唯一支持的目标。

• ADB 没有可靠的 JS FPS 信号；该字段返回 available: false — 从不猜测数值。

• JS 阻塞、路由、React 渲染和网络元数据需要应用内的开发插桩。

• CDP 功能（devtools-export、devtools-profile、metro-network）需要 Metro 为正确的应用运行且应用已连接到 Metro（adb reverse tcp:8081 tcp:8081）；当另一个 React Native DevTools 会话持有连接时无法附加。

• reload --fast 使用 CDP Page.reload（仅 JS）；当 Metro 不可用时自动回退到 force-stop。

• 没有插桩的应用：使用 metro-network（CDP）、app-state（前台 activity、PID）和 device-network（设备级字节计数器，不归因于应用）作为回退证据。

• record（screenrecord）受 Android 限制为每个片段 180 秒。

• Perfetto 跟踪已支持 Android；深度跟踪分析仍在 Perfetto UI/Android Studio 中进行。

• Observer CDP 命令跨进程排队；外部 React Native DevTools 仍必须关闭，因为它不参与 observer 锁。

• session stop 自动生成回放；会话中的 ref 在重排/滚动后保持稳定；缺失会话产生 EVIDENCE_NOT_RECORDED。

• understand-screen/MCP understand_screen 在可用时返回插桩路由、屏幕状态、标题、文本/操作 ref、UI findings 以及截图/UI 树证据；重复调用可检测不变的加载状态。分类是启发式的，文本字段值始终被脱敏。

• ui-model/MCP runtime_ui_model 使用 TypeScript AST 解析 TSX 以获取组件 + file:line，然后将源码与插桩和原生树关联。结果区分 rendered、visible/offscreen/hidden/unmounted/flattened-or-unobserved、enabled 以及有证据支持的 canPress 状态。

• 仅开发用的 Babel 插件自动注入源自源码的 testID 并包装 onPress；session stop 收集交互 start/success/error，并将带 testID 的点击提升到回放中。从不记录 handler 参数、props 或输入值。

• 网络 body 捕获默认关闭。仅开发用的 opt-in 使用 fail-closed 白名单，但仍应仅限于 fixture。

RN Agent Observer (English)

RN Agent Observer 2.4.0 is a local runtime observability bridge for React Native/Expo. It uses one shared TypeScript core behind both a CLI and an MCP server, drives Android through ADB/UIAutomator, receives telemetry from development instrumentation, exports console/exceptions/heap/JS CPU profiles through Metro's Chrome DevTools Protocol, captures per-request network traffic without app instrumentation, produces structured screen understanding (state/headline/actions/UI findings) for agents, provides session-stable ref snapshots + diffs + automatically recorded replay scripts, records on-screen video, persists sessions in SQLite, and keeps screenshots/traces/UI trees as on-disk artifacts.

The current release completes Android v1 on Windows: 45 MCP tools, the matching CLI, an Expo demo app with deterministic labs, transparent heuristic diagnosis, and pixel + structural UI comparison.

Requirements

• Node.js 22.12 or newer

• pnpm 9.6

• Android Platform Tools (adb)

• An Android emulator or physical device with USB debugging enabled

• An Expo development build if you need app-specific telemetry

Quick Start

pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:check

Point the observer at your Expo/React Native app:

$env:RN_OBSERVER_PROJECT_ROOT = 'C:\path\to\expo-app'
$env:RN_OBSERVER_DEVICE_ID = 'emulator-5554'
# Optional when app.json contains expo.android.package
$env:RN_OBSERVER_APP_ID = 'com.example.app'

pnpm rn-observe launch
pnpm rn-observe observe
pnpm rn-observe understand-screen
pnpm rn-observe ui-model
pnpm rn-observe tap --test-id buy-button
pnpm rn-observe performance
pnpm rn-observe diagnose

Artifacts and SQLite data are created under <projectRoot>/.artifacts/; large binaries are never embedded in MCP responses.

Deterministic demo

pnpm --filter @rn-agent-observer/demo-expo android -- --device <device-name>

The demo ships PerformanceLab, NetworkLab, RenderLab, AnimationLab, ErrorLab, and VisualLab. NetworkLab uses internal fixtures (0/500/2000ms and HTTP 503) so it never depends on Internet services. PerformanceLab reports its intentional 100ms long JS task precisely through instrumentation.

MCP

pnpm mcp:check
pnpm mcp:start

The server speaks stdio. Client configuration and the full list of 45 tools are documented in docs/protocol.md.

Documentation

• Full project overview (VI/EN)

• Detailed usage guide (Vietnamese)

• Architecture

• CLI and MCP protocol

• Metrics definitions

• Capability matrix

• Testing and runtime verification

• Test blueprint

• Troubleshooting

• Changelog

AI agent integration

Three ways for agents (OpenCode/Claude Code/Cursor/Codex...) to use the observer:

1. MCP server (recommended — structured tools)

{
  "mcpServers": {
    "rn-agent-observer": {
      "command": "node",
      "args": [
        "C:\\abs\\rn-agent-observer\\packages\\mcp-server\\dist\\server.js"
      ],
      "env": {
        "RN_OBSERVER_PROJECT_ROOT": "C:\\path\\to\\expo-app",
        "RN_OBSERVER_DEVICE_ID": "emulator-5554"
      }
    }
  }
}

2. Install as a skill (teaches the agent the debugging workflow via CLI)

npx skills add GinzaTech/rn-agent-observer

The skill lives at skills/rn-agent-observer/SKILL.md — it teaches the observe -> understand-screen -> reproduce -> diagnose -> fix -> understand-screen -> compare loop, how to read metrics honestly, and common failure recovery. After installing, just say "app X feels laggy" and the agent knows to reach for rn-observe.

3. AGENTS.md (when the agent works inside this repo) — already present at the repo root; agents read it automatically.

All three can be combined: the skill/AGENTS.md teach the workflow, MCP provides directly callable tools.

Current boundary

• Android/Windows is the only supported target of Observer 2.4.0.

• ADB has no trustworthy JS FPS signal; the field is returned as available: false — values are never guessed.

• JS blocking, route, React renders, and network metadata require development instrumentation inside the app.

• CDP features (devtools-export, devtools-profile, metro-network) need Metro running for the right app and the app connected to it (adb reverse tcp:8081 tcp:8081); they cannot attach while another React Native DevTools session holds the connection.

• reload --fast uses CDP Page.reload (JS-only) and automatically falls back to force-stop when Metro is unavailable.

• Observer CDP commands queue across processes; external React Native DevTools must still be closed because it does not participate in the observer lock.

• session stop automatically writes a replay, session refs survive reorder/scroll, and missing sessions produce EVIDENCE_NOT_RECORDED.

• understand-screen/MCP understand_screen returns the instrumented route when available, screen state, headline, text/action refs, UI findings, and screenshot/UI-tree evidence; repeated calls detect unchanged loading. Classification is heuristic and text-field values are always redacted.

• ui-model/MCP runtime_ui_model parses TSX with the TypeScript AST for component + file:line, then correlates source with instrumentation and the native tree. It distinguishes rendered, visible/off-screen/hidden/unmounted/flattened-or-unobserved, enabled, and evidence-backed canPress states.

• The development-only Babel plugin injects a source-derived testID and wraps onPress; session stop collects interaction start/success/error and promotes testID taps into replay. Handler arguments, props, and input values are never recorded.

• Network body capture is off by default. Development-only opt-in uses fail-closed allowlists and should still be limited to fixtures.

• Apps without instrumentation: use metro-network (CDP), app-state (foreground activity, PID), and device-network (device-level byte counters, not app-attributed) as fallback evidence.

• record (screenrecord) is limited to 180s per clip by Android.

• Perfetto tracing is supported on Android; deep trace analysis remains in Perfetto UI/Android Studio.