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 diagnoseArtifacts 和 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 任务。
pnpm mcp:check
pnpm mcp:start服务器使用 stdio。客户端配置和全部 45 个工具的列表记录在 docs/protocol.md 中。
有 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-observerSkill 位于 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 提供 可直接调用的工具。
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 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.
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
pnpm install
pnpm check
adb devices -l
pnpm rn-observe --help
pnpm mcp:checkPoint 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 diagnoseArtifacts and SQLite data are created under <projectRoot>/.artifacts/; large binaries are never embedded in MCP responses.
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.
pnpm mcp:check
pnpm mcp:startThe server speaks stdio. Client configuration and the full list of 45 tools are documented in docs/protocol.md.
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-observerThe 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.
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.
This server cannot be deployed
Remote MCP for Android CLI agent build gate, structured receipts, audit logs, and reviewer-ready evi
Capture, inspect & debug HTTPS traffic across iOS, Android, browsers & backends — 304 MCP tools.
Production runtime data for Android and KMP apps (startup, ANRs, slow screens) for coding agents
Analytics and debugging for your MCP server — explore usage and sessions, then root-cause errors.
