argent-metro-debugger
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinese1. Prerequisites
1. 前提条件
The debugger requires Metro dev server running (default ) and a React Native app connected to Metro (at least one CDP target). Verify via .
localhost:8081debugger-status调试器要求Metro开发服务器处于运行状态（默认地址为），且React Native应用已连接到Metro（至少存在一个CDP目标）。可通过命令验证连接状态。
localhost:8081debugger-statusAndroid: reverse port for Metro
Android：为Metro反向端口映射
Android emulators and physical devices do not resolve the host's by default. Before the RN app can reach Metro, forward port 8081 (or whichever port Metro is on) from the device back to the host:
localhostbash
adb -s <serial> reverse tcp:8081 tcp:8081<serial>seriallist-devicesdebugger-*network-*react-profiler-*adb reverseAndroid模拟器和物理设备默认无法解析主机的地址。在RN应用能够连接Metro之前，需将设备的8081端口（或Metro使用的其他端口）反向映射到主机：
localhostbash
adb -s <serial> reverse tcp:8081 tcp:8081<serial>list-devicesdebugger-*network-*react-profiler-*adb reverse2. Tool Overview
2. 工具概述
All tools accept (default 8081) AND (the iOS Simulator UDID or Android serial, a.k.a. — the CDP-reported id that matches the device). Always make sure you target the correct app on the correct device.
portdevice_idlogicalDeviceIdOne Metro port can serve multiple connected devices (e.g. two simulators on , or an iOS simulator alongside an Android emulator with set up). pins every debugger/network/profiler call to a specific device so sessions do not collide.
localhost:8081adb reversedevice_id所有工具均支持（默认8081）和参数（iOS模拟器UDID或Android序列号，即CDP报告的，与设备匹配的标识）。请始终确保目标为正确设备上的正确应用。
portdevice_idlogicalDeviceId单个Metro端口可服务多个已连接设备（例如，两个模拟器连接到，或iOS模拟器与已配置的Android模拟器同时连接）。可将所有调试器/网络/性能分析器的调用绑定到特定设备，避免会话冲突。
localhost:8081adb reversedevice_idConnect & diagnostics
连接与诊断
| Tool | Purpose |
|---|---|
| Connect to Metro CDP. Returns port, projectRoot, deviceName, appName, |
| Like connect + loadedScripts, enabledDomains, sourceMapReady. Use to diagnose. |
| 工具 | 用途 |
|---|---|
| 连接到Metro CDP。返回端口、项目根目录、设备名称、应用名称、 |
| 功能类似connect，额外返回已加载脚本、启用的域、源映射就绪状态。用于诊断问题。 |
Reload & recovery
重载与恢复
| Tool | Purpose |
|---|---|
| Reload all connected apps (like pressing "r" in Metro terminal). Needs a CDP target. |
| Terminate and relaunch the app by device id and bundleId. Use when app lost Metro connection. |
| 工具 | 用途 |
|---|---|
| 重载所有已连接的应用（类似在Metro终端中按"r"键）。需要存在CDP目标。 |
| 根据设备ID和bundleId终止并重新启动应用。适用于应用丢失Metro连接的场景。 |
Inspection & console
检查与控制台
| Tool | Purpose |
|---|---|
| Full React fiber tree (names, depth, bounding rects, tap coordinates). |
| Inspect at (x, y) using logical pixel coordinates (not normalized 0-1): component hierarchy with source file:line and code fragment. See |
| Get log summary (counts, clusters, file path). Then use |
| Run a JS expression in the app runtime. |
| 工具 | 用途 |
|---|---|
| 获取完整的React Fiber树（包含组件名称、层级、边界矩形、点击坐标）。 |
| 使用逻辑像素坐标（非归一化0-1范围）在(x, y)位置检查元素：返回组件层级结构及对应的源文件:行号和代码片段。详情请参考 |
| 获取日志摘要（数量、聚类、文件路径）。随后可对扁平化日志文件使用 |
| 在应用运行时执行JS表达式。 |
3. Component Inspection
3. 组件检查
debugger-component-tree
vs debugger-inspect-element
debugger-component-treedebugger-inspect-elementdebugger-component-tree
vs debugger-inspect-element
debugger-component-treedebugger-inspect-element | | |
|---|---|---|
| Best for | Layout overview; finding tap targets; user-defined component hierarchy | Identifying a visible element and tracing it to its source file |
| Use when | "What's on screen and where?" | "What component is this and where is it defined?" |
Both can point to source files, but is purpose-built for source tracing. is for orientation and tap-target discovery.
inspect-elementcomponent-tree | | |
|---|---|---|
| 适用场景 | 布局概览、查找点击目标、用户自定义组件层级分析 | 识别可见元素并追踪到其源文件 |
| 使用时机 | 需了解“屏幕上有什么，位置在哪里？”时 | 需了解“这是什么组件，定义在哪里？”时 |
两者均可指向源文件，但专为源文件追踪设计。则用于定位方向和发现点击目标。
inspect-elementcomponent-treeincludeSkipped
guidance
includeSkippedincludeSkipped
参数指南
includeSkippedApplies to both and . Set to only when debugging filter behavior — e.g., an expected component is missing from output, or you need to inspect a very specific branch of the tree (not just an overview).
debugger-component-treedebugger-inspect-elementtrueWarning: Output can be very large. Always combine with(component-tree) ormaxNodes(inspect-element) and increase it incrementally (e.g., start at 50, then grow). Do not usemaxItemswithout a limit on large apps.includeSkipped
该参数适用于和。仅在调试过滤行为时设置为——例如，预期的组件未出现在输出中，或需要检查树的某个特定分支（而非仅概览）。
debugger-component-treedebugger-inspect-elementtrue警告： 输出内容可能非常庞大。请始终结合（component-tree）或maxNodes（inspect-element）参数使用，并逐步增加数值（例如，从50开始，再逐步增大）。在大型应用中，请勿在未设置限制的情况下使用maxItems。includeSkipped
4. Golden Rules
4. 黄金准则
- first when something fails — it runs discovery, connection, and returns diagnostics.
debugger-status - "No CDP targets" → get the app to connect to Metro — use on the device, then retry
restart-app.debugger-status - Never assume one failure is permanent — follow recovery steps before asking the user. For starting Metro and full failure recovery, see and
argent-react-native-app-workflow.references/failure-scenarios.md
- 出现问题时首先使用—— 该命令会执行发现、连接操作并返回诊断信息。
debugger-status - 提示“无CDP目标” → 让应用连接到Metro —— 在设备上使用命令，然后重试
restart-app。debugger-status - 永远不要假设一次失败是永久性的 —— 在询问用户之前先执行恢复步骤。关于启动Metro和完整故障恢复的内容，请参考和
argent-react-native-app-workflow。references/failure-scenarios.md
5. Reading Console Logs (Log Registry)
5. 读取控制台日志（日志注册表）
Logs are written to a flat log file on disk. Use the log-registry → grep pattern instead of reading logs inline.
日志会写入磁盘上的扁平化日志文件。请使用日志注册表 → grep的模式，而非直接读取日志内容。
Workflow
工作流程
- Call — returns:
debugger-log-registry(log path),file,totalEntries,byLevel(top message groups with counts and source file info)clusters - Search the file using or
Grepwith patterns from the response.Read
Large log files: Ifexceeds 10 000, delegate the grep exploration to antotalEntriessubagent — pass it the file path, the entry format, and the patterns you need.Explore
- 调用—— 返回：
debugger-log-registry（日志路径）、file（总条目数）、totalEntries（按级别统计）、byLevel（顶级消息分组，包含数量和源文件信息）clusters - 搜索文件 —— 使用或
Grep命令，结合返回结果中的模式进行搜索。Read
大型日志文件： 若超过10000条，可将grep探索任务委托给totalEntries子代理——传递文件路径、条目格式和所需的搜索模式。Explore
Flat log format
扁平化日志格式
One entry per line — fields (whitespace-separated, delimiter before message)
|| Field | Example | Notes |
|---|---|---|
| | Unique grep anchor |
| | ISO 8601 |
| | Uppercase, padded to 5 chars |
| | Relative path from source map; |
| | Full message; embedded newlines replaced with space |
Source attribution (file + line) is also available in returned by .
clustersdebugger-log-registryLog files and messages can be large - Always scope your search, treat the file like a database, not a document.
When reading from the log file:
- Never the log file directly. Use
Reador shell commands with limits using the above file format tips.grep - Default to unless you need more.
-m 50 - Use recent entries.
tail -N - gives you the exact text which you may look for
clusters[].message
If the file is too large Delegate to ansubagent with the file path, the format spec above, and the specific patterns you need.Explore
每行一条日志条目——字段（空格分隔，消息前使用作为分隔符）
|| 字段 | 示例 | 说明 |
|---|---|---|
| | 唯一的grep锚点 |
| | ISO 8601格式 |
| | 大写，填充至5个字符 |
| | 源映射中的相对路径；若不可用则显示 |
| | 完整消息；嵌入的换行符将替换为空格 |
源文件归属（文件+行号）也可在返回的中查看。
debugger-log-registryclusters日志文件和消息可能很大——请始终限定搜索范围，将文件视为数据库而非文档。
读取日志文件时：
- 不要直接日志文件。使用grep或带限制的shell命令，并结合上述文件格式提示。
Read - 默认使用参数，除非需要更多结果。
-m 50 - 使用查看最近的N条条目。
tail -N - 提供了可用于搜索的精确文本
clusters[].message
若文件过大 将任务委托给子代理，传递文件路径、上述格式规范和特定的搜索模式。Explore
Quick Reference
快速参考
| Action | Tool |
|---|---|
| Diagnose / check connection | |
| Connect to Metro CDP | |
| Reload JS (already connected) | |
| Relaunch app on device | |
| Inspect component at point | |
| Full component tree | |
| Console log overview | |
| Evaluate JS | |
| 操作 | 工具 |
|---|---|
| 诊断/检查连接状态 | |
| 连接到Metro CDP | |
| 重载JS（已连接状态下） | |
| 在设备上重新启动应用 | |
| 检查指定位置的组件 | |
| 获取完整组件树 | |
| 控制台日志概览 | |
| 执行JS代码 | |