argent-react-native-app-workflow

实体 iPhone（kind: "device"）：Metro 调试和性能分析工具不支持它。请使用模拟器。

1. 启动 React Native 应用

1.1 查看配置（必须先执行）

运行命令前，先阅读 argent-environment-inspector 子 Agent 结果中的项目构建和运行配置。

在检查自定义脚本和工作流之前，请勿默认执行 npx react-native start 或 npx react-native run-ios。

手动备用方案（如果 Agent 和工具都不可用）：阅读 package.json 中的所有脚本：查找 start:local、start:dev、ios、build:ios、flavor 等自定义脚本。自定义脚本优先于默认命令。还要检查 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 启动 Metro

1. 检查配置中指定的端口上是否已运行 Metro；如果已运行，则不要再启动另一个服务。参见 2.1。

2. 如果项目有自定义启动脚本，请使用该脚本（例如 npm run start:local、yarn start:dev）。如果未定义自定义脚本，则使用默认命令：

   npx react-native start
   

   可选：如果怀疑存在缓存问题，可以运行 npx react-native start --reset-cache。

3. 确认 Metro 已就绪：使用 debugger-status 工具。该工具会返回 status 结果，而不是报错：status: "connected" 或 reason: "no_app_connected" 的 status: "not_connected" 都表示 Metro 已启动（只是应用尚未连接）；reason: "metro_not_running" 表示无法访问 Metro；请遵循结果中的 guidance。

4. 使用 flavors 或自定义配置的项目：如果存在项目专用启动脚本，请使用该脚本（例如 npm run start:local），并在运行应用之前启动 Metro。

1.3 运行应用

在另一个终端中运行（Metro 会在第一个终端中持续运行）：

如果项目有自定义构建／运行脚本，请使用该脚本（例如 npm run ios、npm run android、yarn ios:debug）。仅当未定义自定义脚本时，才使用以下默认命令。

显式指定目标设备：根据 list-devices 的结果确定设备（参见 <device_selection_rule>）：

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

仅限 Android：安装后，运行 adb -s <serial> reverse tcp:8081 tcp:8081，以便模拟器／设备访问主机上的 Metro。设备重启或 adb 断开后，请重复此操作。

Agent 检查清单：

• Metro 已在运行并显示“ready”
• 命令从项目根目录运行
• 如果设备尚未启动：使用 iOS udid 或 Android avdName 运行 boot-device。参见 argent-ios-simulator-setup／argent-android-emulator-setup 技能。
• Android：已运行 adb -s <serial> reverse tcp:8081 tcp:8081。

---

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

2.1 检查是否已有 Metro

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

lsof -i :PORT

• 无输出 → 端口空闲，可以安全启动 Metro。
• 输出包含 PID → 另一个进程正在使用该端口。

使用 debugger-status 工具检查该端口上的进程是否确实是 Metro 服务：它会返回结构化结果，而不是错误。status: "connected" 或 reason: "no_app_connected" → 该进程是 Metro。若 lsof 显示有监听进程，而结果为 reason: "metro_not_running" → 该端口被非 Metro 进程占用；结果中的 detail 字段会显示该进程的响应内容（Metro at port ... is not running (got: ...)）。此时请询问用户是否允许终止该进程。

要终止 Metro 进程，请使用 stop-metro 工具（需要用户确认）。

2.2 确认连接到正确的服务

• 应用必须指向正在运行的 Metro 所用的同一主机和端口。 默认情况下，使用同一台机器上的 8081 端口。
• iOS Simulator： 默认使用 localhost；连接同一台机器上的 Metro 无需额外配置。

验证 Metro 是否可访问： 使用 debugger-status 工具。reason: "metro_not_running" 表示 Metro 未在该端口响应：请启动它（§2.1）；"no_app_connected" 表示 Metro 已响应，但应用尚未连接（§2.3）。其他任何原因：请遵循结果中的 guidance（这本身并不能证明 Metro 正在运行）。

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

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

方法	操作
重新加载工具	使用 debugger-reload-metro 工具
重启应用	使用 restart-app 工具，或在模拟器中终止应用，然后再次运行 npx react-native run-ios

Agent 检查清单：

• 只运行一个 Metro 进程（端口上没有重复进程）
• Metro 就绪后才启动应用
• 需要重新加载时：参阅 2.3

---

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

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

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

1. 清理构建文件夹，然后重试构建命令
2. 清除缓存并重新安装依赖项：重置 Metro 缓存，运行 watchman watch-del-all，删除 node_modules 和锁文件，运行 npm install，然后运行 cd ios && rm -rf build Pods Podfile.lock && pod install --repo-update
3. CocoaPods 问题：先运行 pod deintegrate，再运行 pod install --repo-update
4. 在 Xcode 中打开 ios/*.xcworkspace，通过 Report 导航器查看详细错误

3.2 何时询问用户

构建或运行连续失败 2–3 次后，请停止并询问用户如何处理。 用户可能了解必需的环境变量、Xcode 版本要求、自定义构建配置、monorepo 特定设置或必需的外部服务。

如果项目结构复杂，无法明确正确的构建方式，请尽早询问用户，而不要猜测。

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

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

3.4 何时重新安装，何时刷新

情况	操作
仅 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 设备控制

操作	工具 / 命令
列出设备	list-devices 工具（iOS + Android）
启动 iOS 模拟器	使用带有 udid 的 boot-device 工具
启动 Android 模拟器	使用带有 avdName 的 boot-device 工具
启动应用	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 工具：传入 devices: [...]，将清理范围限定为此会话的设备（不限定范围的调用也会清理其他 Agent 的设备；仅在需要清理整台机器时使用）

有关完整的模拟器设置工作流，请参阅 argent-ios-simulator-setup 技能。

---

4. 应用运行时问题

4.1 查看位置

问题类型	工具 / 查看位置
JavaScript 错误 / 日志	使用 debugger-log-registry 获取摘要和日志文件路径，然后使用 Grep 搜索。如果返回 status: "not_connected"，则不会返回日志文件；请按照其 guidance 先重新连接。
React 组件层级	使用 debugger-component-tree 工具获取文本树，或使用 debugger-inspect-element 检查特定逻辑像素坐标处的元素（不是归一化的 0-1 坐标）。
应用的视觉状态	使用 screenshot 工具截取当前屏幕，但实际导航和目标查找优先使用 describe 或 debugger-component-tree。如果权限提示或系统拥有的模态覆盖层无法可靠地显示出来，则改用 screenshot。
在应用中执行 JS	使用 debugger-evaluate 工具在应用的运行时中执行 JavaScript。
原生崩溃 / 原生堆栈	npx react-native log-ios 或 iOS Simulator：Debug → Open System Log。
构建 / 运行时配置	metro.config.js、babel.config.js、package.json 脚本、ios/Podfile。

有关全面的 Metro 调试工作流（组件检查、控制台日志、JS 执行），请参阅 argent-metro-debugger 技能。

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

日志会写入磁盘上 ~/.argent/tmp/ 下的纯文本日志文件。请使用 日志注册表 → grep 模式，而不要内联读取日志。

完整工作流、纯文本条目格式和 grep 示例，请参阅 argent-metro-debugger 技能 §5。

4.3 默认情况下，不要尝试在 React Native 应用中使用 DevMenu。

请改用 argent 工具。

---

5. 测试应用

查看 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 变更：使用 argent-test-ui-flow 进行手动 QA。有关 screenshot-diff 规则和参数，请遵循 argent-screenshot-diff 技能。稳定的前后截图能够提供有意义的像素可见证据时，请使用它。
• UI 流程测试：对于带自动截图验证的交互式 UI 测试，请参阅 argent-test-ui-flow 技能。

5.2 运行测试（常规）

如果用户的意图不明确（运行现有测试、编写新测试或查找覆盖不足之处），请先确认再继续。

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

5.3 Agent 测试清单

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

---

快速参考：工具和命令

目标	工具 / 命令
检查端口 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 工具
比较可见的 UI 变化	screenshot-diff 工具；根据 argent-screenshot-diff 技能选择基准/当前截图方式
描述屏幕（无障碍树）	对于普通应用屏幕和应用内模态框，使用 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

---

相关技能

技能	使用时机
argent-ios-simulator-setup	初次启动 iOS 模拟器并设置连接
argent-android-emulator-setup	初次启动 Android 模拟器并设置连接
argent-device-interact	在模拟器/仿真器上点击、滑动、输入文字、操作硬件按钮和执行手势
argent-metro-debugger	JS 运行时 CDP 调试（iOS / Android 上的 Metro；这四个移植的工具也可驱动 Chromium/CDP 应用）：检查组件、查看控制台日志、执行 JS
argent-react-native-profiler	分析性能、查找重复渲染问题和 CPU 热点
argent-test-ui-flow	交互式 UI 测试，每次操作后自动验证屏幕截图

运行测试前，请先询问用户：确认要运行哪个测试套件（单元测试、E2E 或两者），是否使用现有 CI 命令，以及希望你运行现有测试、编写新测试，还是自行探索测试用例。