argent-react-native-app-workflow

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

1. Starting the React Native App

1. 启动React Native应用

1.1 Explore Configuration (MANDATORY — Do This First)

1.1 查看配置（必须执行——先做这一步）

Before running commands, read the project's build and run configuration from the

argent-environment-inspector

subagent result.

Do NOT default to

npx react-native start

npx react-native run-ios

without first checking for custom scripts and workflows.

Manual fallback (if neither the agent nor the tool is available): read ALL

package.json

scripts — look for custom scripts like

start:local

start:dev

ios

build:ios

, flavors, etc. Custom scripts take priority over default commands. Also check

metro.config.js

for non-default port or watchFolders. For iOS builds, prefer opening

.xcworkspace

over

.xcodeproj

(CocoaPods generates the workspace).

If the project structure is convoluted, ask the user before proceeding.

Remember the workflow: Once you discover the project's build/run workflow, save it to project memory so you don't need to re-discover it each time.

Checklist before start:

```
node_modules
```
present (if not:
```
npm install
```
or
```
yarn
```
)

For iOS:

ios/Podfile

exists; if

ios/Pods

missing or stale, run

cd ios && pod install && cd ..

No conflicting Metro on default port (see 1.2)

在执行命令前，从

argent-environment-inspector

子代理结果中读取项目的构建和运行配置。

不要直接默认使用

npx react-native start

或

npx react-native run-ios

，务必先检查是否存在自定义脚本和工作流。

手动备选方案（若代理或工具均不可用）：阅读所有

package.json

脚本——查找类似

start:local

、

start:dev

、

ios

、

build:ios

、flavors等自定义脚本。自定义脚本优先级高于默认命令。同时检查

metro.config.js

是否有非默认端口或watchFolders配置。对于iOS构建，优先打开

.xcworkspace

而非

.xcodeproj

（CocoaPods会生成workspace）。

若项目结构复杂，在继续操作前请询问用户。

牢记工作流： 一旦确定项目的构建/运行工作流，将其保存到项目记忆中，避免每次重复查找。

启动前检查清单：

已存在
```
node_modules
```
（若不存在：执行
```
npm install
```
或
```
yarn
```
）
针对iOS：
```
ios/Podfile
```
已存在；若
```
ios/Pods
```
缺失或过期，执行
```
cd ios && pod install && cd ..
```
默认端口无冲突的Metro进程（见1.2）

1.2 Start Metro

1.2 启动Metro

Check whether metro is already running on port found in configuration and if it is - do not start another server. Refer to point 2.1.
Use the project's custom start script if one exists (e.g.
```
npm run start:local
```
,
```
yarn start:dev
```
). Fall back to default commands if no custom scripts are defined:
bash
```
npx react-native start
```
Optional:
```
npx react-native start --reset-cache
```
if cache issues are suspected.
Verify Metro is ready: use the
```
debugger-status
```
tool to verify Metro is running and reachable.
Projects with flavors or custom configs: Use project-specific start script if present (e.g.
```
npm run start:local
```
), and start Metro before running the app.

检查配置中指定的端口是否已有Metro在运行，若已运行则无需启动新服务器。参考2.1部分。
若项目存在自定义启动脚本，请优先使用（例如
```
npm run start:local
```
、
```
yarn start:dev
```
）。若无自定义脚本，再使用默认命令：
bash
```
npx react-native start
```
可选：若怀疑存在缓存问题，执行
```
npx react-native start --reset-cache
```
。
验证Metro是否就绪：使用
```
debugger-status
```
工具验证Metro是否正在运行且可访问。
带有flavors或自定义配置的项目：若存在项目专属启动脚本（如
```
npm run start:local
```
），请使用该脚本，并在运行应用之前启动Metro。

1.3 Run the App

1.3 运行应用

In a separate terminal (Metro keeps running in the first):

Use the project's custom build/run script if one exists (e.g.

npm run ios

npm run android

yarn ios:debug

). Only fall back to the defaults below if no custom scripts are defined.

Pass the target device explicitly — derive it from

list-devices

(see

<device_selection_rule>

bash

npx react-native run-ios --simulator="<name>"        # iOS (or --udid <UDID>)
npx react-native run-android --deviceId=<adb-serial> # Android

Android only: after install, run

adb -s <serial> reverse tcp:8081 tcp:8081

so the emulator/device can reach Metro on your host. Repeat if the device restarts or adb drops.

Agent checklist:

Metro is already running and shows "ready"
Command run from project root
If the device isn't booted yet: use
```
boot-device
```
with the iOS
```
udid
```
or Android
```
avdName
```
. Refer to the
```
argent-ios-simulator-setup
```
/
```
argent-android-emulator-setup
```
skill.

Android:

adb -s <serial> reverse tcp:8081 tcp:8081

done.

在单独的终端中执行（Metro保持在第一个终端运行）：

若项目存在自定义构建/运行脚本，请优先使用（例如

npm run ios

、

npm run android

、

yarn ios:debug

）。仅当无自定义脚本时，才使用以下默认命令。

明确指定目标设备——从

list-devices

结果中获取（参考

<device_selection_rule>

）：

bash

npx react-native run-ios --simulator="<name>"        # iOS（或使用--udid <UDID>）
npx react-native run-android --deviceId=<adb-serial> # Android

仅Android： 安装完成后，执行

adb -s <serial> reverse tcp:8081 tcp:8081

，让模拟器/设备可以访问主机上的Metro。若设备重启或adb连接中断，请重复执行该命令。

代理检查清单：

Metro已运行并显示"ready"
命令从项目根目录执行
若设备未启动：使用
```
boot-device
```
工具，传入iOS的
```
udid
```
或Android的
```
avdName
```
。参考
```
argent-ios-simulator-setup
```
/
```
argent-android-emulator-setup
```
技能。

Android：已执行

adb -s <serial> reverse tcp:8081 tcp:8081

。

2. Ensuring / Debugging Metro

2. 确保Metro正常运行/调试Metro

2.1 Check for Existing Metro

2.1 检查是否存在已运行的Metro

Before starting Metro, avoid "port already in use" errors. Default port to check is :8081, infer the port from documentation:

bash

lsof -i :PORT

No output → Port free; safe to start Metro.
Output with PID → Another process is using the port.

Use the

debugger-status

tool to check whether the process on that port is actually a Metro server. If not Metro — ask the user whether you may kill the process.

To kill a Metro process, use the

stop-metro

tool (requires user confirmation).

启动Metro前，避免出现"端口已被占用"错误。默认检查端口为:8081，也可从文档中推断端口：

bash

lsof -i :PORT

无输出 → 端口空闲；可安全启动Metro。
输出包含PID → 该端口已被其他进程占用。

使用

debugger-status

工具检查该端口上的进程是否确实是Metro服务器。若不是Metro——询问用户是否可以终止该进程。

要终止Metro进程，使用

stop-metro

工具（需用户确认）。

2.2 Confirm Correct Server Connection

2.2 确认服务器连接正确

App must point at the same host/port as the running Metro. Default: same machine, port 8081.
iOS Simulator: By default uses localhost; no extra config needed for same-machine Metro.

Verify Metro is reachable: use the

debugger-status

tool.

应用必须指向与运行中的Metro相同的主机/端口。默认：同一机器，端口8081。
iOS模拟器： 默认使用localhost；同一机器上的Metro无需额外配置。

验证Metro是否可访问： 使用

debugger-status

工具。

2.3 Reload the App (Ensure New Bundle)

2.3 重新加载应用（确保加载新Bundle）

After code or config changes, the app must load the new bundle:

Method	How
Reload tool	Use the `debugger-reload-metro` tool
Restart app	Use the `restart-app` tool, or kill the app in simulator and run `npx react-native run-ios` again

Agent checklist:

Only one Metro process (no duplicate on port)
App was started after Metro was ready
When needing to reload: refer to 2.3

代码或配置更改后，应用必须加载新的bundle：

方法	操作方式
重载工具	使用 `debugger-reload-metro` 工具
重启应用	使用 `restart-app` 工具，或在模拟器中关闭应用后重新执行 `npx react-native run-ios`

代理检查清单：

仅存在一个Metro进程（端口无重复进程）
应用在Metro就绪后启动
需要重载时：参考2.3部分

3. Build / Install / Retry (React Native & iOS Native)

3. 构建/安装/重试（React Native & iOS原生）

3.1 When Build Fails (e.g. xcodebuild exit code 65)

3.1 构建失败时（例如xcodebuild退出码65）

Order of operations (simplest first):

Clean build folder, then retry the build command

Clear caches and reinstall dependencies: reset Metro cache,

watchman watch-del-all

, remove

node_modules

+ lockfile,

npm install

, then

cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update

CocoaPods issues:

pod deintegrate

then

pod install --repo-update

Open
```
ios/*.xcworkspace
```
in Xcode for detailed errors in the Report navigator

操作顺序（从最简单的开始）：

清理构建文件夹，然后重试构建命令

清除缓存并重新安装依赖：重置Metro缓存，执行

watchman watch-del-all

，删除

node_modules

+ 锁文件，执行

npm install

，然后执行

cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update

CocoaPods问题：执行

pod deintegrate

，然后执行

pod install --repo-update

在Xcode中打开
```
ios/*.xcworkspace
```
，在Report导航器中查看详细错误信息

3.2 When to Ask the User

3.2 何时询问用户

After 2-3 failed build or run attempts, STOP and ask the user for guidance. The user may know about required env vars, Xcode version requirements, custom build configurations, monorepo-specific setup, or required external services.

If the project structure is convoluted and the correct build approach is not obvious, ask the user early rather than guessing.

经过2-3次构建或运行尝试失败后，请停止操作并向用户寻求指导。 用户可能了解所需的环境变量、Xcode版本要求、自定义构建配置、monorepo专属设置或所需的外部服务。

若项目结构复杂且正确的构建方式不明确，请尽早询问用户，而非猜测。

3.3 Saving Build Workflow for Later

3.3 保存构建工作流供后续使用

Once you discover the correct build/run workflow for a project, save it to project memory. Capture: commands to start Metro, commands to build/run the app, and any required environment setup.

一旦确定项目正确的构建/运行工作流，请将其保存到项目记忆中。记录：启动Metro的命令、构建/运行应用的命令，以及任何所需的环境设置。

3.4 When to Reinstall vs Refresh

3.4 何时重新安装 vs 刷新

Situation	Action
JS/React only changed	Use `debugger-reload-metro` tool. No rebuild.
Native code or `pod install` / project config changed	Rebuild: `npx react-native run-ios` (Metro can stay running).
`node_modules` or `package.json` changed	`npm install` , then if native deps changed run `cd ios && pod install` . Then rebuild.
App needs reinstalling from .app path	Use `reinstall-app` tool with UDID, bundle ID, and .app path.
Persistent native build errors	Full clean + reinstall (step 2 above).

场景	操作
仅JS/React代码变更	使用 `debugger-reload-metro` 工具。无需重新构建。
原生代码或 `pod install` / 项目配置变更	重新构建：执行 `npx react-native run-ios` （Metro可保持运行）。
`node_modules` 或 `package.json` 变更	执行 `npm install` ，若原生依赖变更则执行 `cd ios && pod install` 。然后重新构建。
需要从.app路径重新安装应用	使用 `reinstall-app` 工具，传入UDID、bundle ID和.app路径。
持续出现原生构建错误	完全清理 + 重新安装（上述第2步）。

3.5 Device Control

3.5 设备控制

Action	Tool / Command
List devices	`list-devices` tool (iOS + Android)
Boot an iOS simulator	`boot-device` tool with `udid`
Boot an Android emulator	`boot-device` tool with `avdName`
Launch an app	`launch-app` tool (pass device id + bundle id / package name)
Restart an app	`restart-app` tool (pass device id + bundle id / package name)
Open a URL / deep link	`open-url` tool (pass device id + URL)
Rotate device	`rotate` tool
Stop simulator server	`stop-simulator-server` tool (iOS UDID or Android serial — one device)
Stop all simulator servers	`stop-all-simulator-servers` tool (iOS + Android)

For full simulator setup workflow, refer to the

argent-ios-simulator-setup

skill.

操作	工具 / 命令
列出设备	`list-devices` 工具（iOS + Android）
启动iOS模拟器	`boot-device` 工具，传入 `udid`
启动Android模拟器	`boot-device` 工具，传入 `avdName`
启动应用	`launch-app` 工具（传入设备id + bundle id / 包名）
重启应用	`restart-app` 工具（传入设备id + bundle id / 包名）
打开URL / 深度链接	`open-url` 工具（传入设备id + URL）
旋转设备	`rotate` 工具
停止模拟器服务器	`stop-simulator-server` 工具（iOS UDID或Android序列号——单个设备）
停止所有模拟器服务器	`stop-all-simulator-servers` 工具（iOS + Android）

完整的模拟器设置工作流，请参考

argent-ios-simulator-setup

技能。

4. Runtime Problems in the App

4. 应用运行时问题

4.1 Where to Look

4.1 排查方向

Problem type	Tool / Where to look
JavaScript errors / logs	Use `debugger-log-registry` to get a summary and log file path, then `Grep` / `Read` to search.
React component hierarchy	Use `debugger-component-tree` tool for a text tree, or `debugger-inspect-element` at specific logical pixel coordinates (not normalized 0-1).
Visual state of the app	Use `screenshot` tool to capture the current screen, but prefer `describe` or `debugger-component-tree` for actual navigation and target discovery. If a permission prompt or system-owned modal overlay is not exposed reliably, then fall back to `screenshot` .
Evaluate JS in the app	Use `debugger-evaluate` tool to run JavaScript in the app's runtime.
Native crashes / native stack	`npx react-native log-ios` or iOS Simulator: Debug → Open System Log.
Build/runtime config	`metro.config.js` , `babel.config.js` , `package.json` scripts, `ios/Podfile` .

For comprehensive Metro debugging workflows (component inspection, console logs, JS evaluation), refer to the

argent-metro-debugger

skill.

问题类型	工具 / 排查位置
JavaScript错误 / 日志	使用 `debugger-log-registry` 获取摘要和日志文件路径，然后使用 `Grep` / `Read` 工具搜索。
React组件层级	使用 `debugger-component-tree` 工具获取文本形式的组件树，或在特定逻辑像素坐标（非标准化0-1）处使用 `debugger-inspect-element` 工具。
应用视觉状态	使用 `screenshot` 工具捕获当前屏幕，但优先使用 `describe` 或 `debugger-component-tree` 工具进行实际导航和目标定位。若权限提示或系统模态弹窗无法可靠识别，则使用 `screenshot` 工具作为备选。
在应用中执行JS	使用 `debugger-evaluate` 工具在应用运行时执行JavaScript。
原生崩溃 / 原生调用栈	执行 `npx react-native log-ios` ，或在iOS模拟器中：Debug → Open System Log。
构建/运行时配置	`metro.config.js` 、 `babel.config.js` 、 `package.json` 脚本、 `ios/Podfile` 。

全面的Metro调试工作流（组件检查、控制台日志、JS执行），请参考

argent-metro-debugger

技能。

4.2 JS Console Logs (Log Registry)

4.2 JS控制台日志（日志注册表）

Logs are written to a flat log file on disk under

~/.argent/tmp/

. Use the log-registry → grep pattern instead of reading logs inline.

For the full workflow, flat entry format, and grep examples, see

argent-metro-debugger

skill §5.

日志会写入磁盘上

~/.argent/tmp/

目录下的扁平日志文件中。使用log-registry → grep模式，而非直接读取日志内容。

完整工作流、扁平条目格式和grep示例，请查看

argent-metro-debugger

技能第5节。

4.3 Do not try to use the DevMenu in React Native apps by default.

4.3 默认情况下请勿尝试使用React Native应用的DevMenu。

Use the argent tools instead.

请使用argent工具替代。

5. Testing the App

5. 测试应用

Check the

argent-environment-inspector

result for test commands. For interactive UI testing with automatic screenshot verification, use the

argent-test-ui-flow

skill.

Unit tests: Look for Jest in

package.json

(

"test": "jest"

jest

config). Run:

npm test

yarn test

E2E: Look for Detox (
```
.detoxrc.js
```
or similar), or other E2E config. Dependencies:
```
detox
```
,
```
detox-cli
```
, and for iOS often
```
applesimutils
```
.
UI flow testing: For interactive UI testing with automatic screenshot verification, refer to the
```
argent-test-ui-flow
```
skill.

从

argent-environment-inspector

结果中查看测试命令。如需带自动截图验证的交互式UI测试，请使用

argent-test-ui-flow

技能。

单元测试：在
```
package.json
```
中查找Jest配置（
```
"test": "jest"
```
、
```
jest
```
配置）。运行：
```
npm test
```
或
```
yarn test
```
。
E2E测试：查找Detox配置（
```
.detoxrc.js
```
或类似文件），或其他E2E配置。依赖项：
```
detox
```
、
```
detox-cli
```
，iOS通常还需要
```
applesimutils
```
。
UI流程测试：如需带自动截图验证的交互式UI测试，请参考
```
argent-test-ui-flow
```
技能。

5.2 Running Tests (Typical)

5.2 运行测试（典型流程）

If the user's intent is ambiguous (run existing tests, write new tests, or find missing coverage), clarify before proceeding.

Jest:
```
npm test
```
or
```
npx jest
```
.
Detox (example):
- Build:
```
detox build --configuration ios.sim.release
```
  (or debug).
- Run:
```
detox test --configuration ios.sim.release
```
  .
- Ensure simulator is booted and not used by another process.

若用户意图不明确（运行现有测试、编写新测试或查找测试覆盖率缺口），请先澄清。

Jest：
```
npm test
```
或
```
npx jest
```
。
Detox（示例）:
- 构建：
```
detox build --configuration ios.sim.release
```
  （或debug）。
- 运行：
```
detox test --configuration ios.sim.release
```
  。
- 确保模拟器已启动且未被其他进程占用。

5.3 Agent Testing Checklist

5.3 代理测试检查清单

Read
```
package.json
```
and test config (Jest, Detox, etc.).
If E2E: confirm simulator/device and build config.
If unclear: clarify whether to use existing workflows or write new tests.

已阅读
```
package.json
```
和测试配置（Jest、Detox等）。
若为E2E测试：确认模拟器/设备和构建配置。
若不明确：澄清是使用现有工作流还是编写新测试。

Quick Reference: Tools & Commands

快速参考：工具与命令

Goal	Tool / Command
Check port 8081	`lsof -i :8081`
Kill Metro	`stop-metro` tool
Start Metro	`npx react-native start`
Start Metro (reset cache)	`npx react-native start --reset-cache`
Run iOS app	`npx react-native run-ios`
Run Android app	`npx react-native run-android`
List devices	`list-devices` tool (iOS + Android)
Boot a device	`boot-device` tool (pass `udid` for iOS or `avdName` for Android)
Take screenshot	`screenshot` tool
Describe screen (a11y tree)	`describe` tool for normal app screens and in-app modals; use `screenshot` only when permission/system overlays are not exposed reliably
Read JS console logs	`debugger-log-registry` tool
Reload JS bundle	`debugger-reload-metro` tool
Check Metro status	`debugger-status` tool
Inspect React component tree	`debugger-component-tree` tool
Run JS in app	`debugger-evaluate` tool
iOS native logs	`npx react-native log-ios`
Android native logs	`npx react-native log-android` or `adb -s <serial> logcat`
Clean + reinstall (nuclear)	See §3.1 step 3

目标	工具 / 命令
检查端口8081	`lsof -i :8081`
终止Metro进程	`stop-metro` 工具
启动Metro	`npx react-native start`
启动Metro（重置缓存）	`npx react-native start --reset-cache`
运行iOS应用	`npx react-native run-ios`
运行Android应用	`npx react-native run-android`
列出设备	`list-devices` 工具（iOS + Android）
启动设备	`boot-device` 工具（iOS传入 `udid` ，Android传入 `avdName` ）
截图	`screenshot` 工具
描述屏幕（无障碍树）	`describe` 工具用于普通应用屏幕和应用内弹窗；仅当权限/系统弹窗无法可靠识别时，才使用 `screenshot` 工具
读取JS控制台日志	`debugger-log-registry` 工具
重新加载JS bundle	`debugger-reload-metro` 工具
检查Metro状态	`debugger-status` 工具
检查React组件树	`debugger-component-tree` 工具
在应用中执行JS	`debugger-evaluate` 工具
iOS原生日志	`npx react-native log-ios`
Android原生日志	`npx react-native log-android` 或 `adb -s <serial> logcat`
完全清理 + 重新安装（终极方案）	见第3.1节第3步

Skill	When to use
`argent-ios-simulator-setup`	Initial iOS simulator boot and connection setup
`argent-android-emulator-setup`	Initial Android emulator boot and connection setup
`argent-device-interact`	Tapping, swiping, typing, hardware buttons, gestures on the simulator/emulator
`argent-metro-debugger`	Full Metro CDP debugging: component inspection, console logs, JS evaluation
`argent-react-native-profiler`	Profiling performance, finding re-render issues, CPU hotspots
`argent-test-ui-flow`	Interactive UI testing with automatic screenshot verification after each action

技能	使用场景
`argent-ios-simulator-setup`	iOS模拟器初始启动和连接设置
`argent-android-emulator-setup`	Android模拟器初始启动和连接设置
`argent-device-interact`	在模拟器/设备上执行点击、滑动、输入、硬件按键操作、手势
`argent-metro-debugger`	完整的Metro CDP调试：组件检查、控制台日志、JS执行
`argent-react-native-profiler`	性能分析、查找重渲染问题、CPU热点
`argent-test-ui-flow`	交互式UI测试，每次操作后自动截图验证

argent-react-native-app-workflow

Original

Translation

1. Starting the React Native App

1. 启动React Native应用

1.1 Explore Configuration (MANDATORY — Do This First)

1.1 查看配置（必须执行——先做这一步）

1.2 Start Metro

1.2 启动Metro

1.3 Run the App

1.3 运行应用

2. Ensuring / Debugging Metro

2. 确保Metro正常运行/调试Metro

2.1 Check for Existing Metro

2.1 检查是否存在已运行的Metro

2.2 Confirm Correct Server Connection

2.2 确认服务器连接正确

2.3 Reload the App (Ensure New Bundle)

2.3 重新加载应用（确保加载新Bundle）

3. Build / Install / Retry (React Native & iOS Native)

3. 构建/安装/重试（React Native & iOS原生）

3.1 When Build Fails (e.g. xcodebuild exit code 65)

3.1 构建失败时（例如xcodebuild退出码65）

3.2 When to Ask the User

3.2 何时询问用户

3.3 Saving Build Workflow for Later

3.3 保存构建工作流供后续使用

3.4 When to Reinstall vs Refresh

3.4 何时重新安装 vs 刷新

3.5 Device Control

3.5 设备控制

4. Runtime Problems in the App

4. 应用运行时问题

4.1 Where to Look

4.1 排查方向

4.2 JS Console Logs (Log Registry)

4.2 JS控制台日志（日志注册表）

4.3 Do not try to use the DevMenu in React Native apps by default.

4.3 默认情况下请勿尝试使用React Native应用的DevMenu。

5. Testing the App

5. 测试应用

5.2 Running Tests (Typical)

5.2 运行测试（典型流程）

5.3 Agent Testing Checklist

5.3 代理测试检查清单

Quick Reference: Tools & Commands

快速参考：工具与命令

Related Skills

相关技能