在 iOS 模拟器里复现和修 Bug

📖 本篇术语速查表

英文 / 缩写	中文	一句话解释
iOS 模拟器	simulator	在 Mac 上模拟 iOS 设备的环境。
复现	reproduce	稳定重现 bug 才能可靠修复。
回归验证	regression check	确认修复没引入新问题。

不想读完？把下面这段提示词丢给 AI 帮你跑完——帮你在 iOS 模拟器里规划复现并修复一个 bug 的任务。

你是 iOS 模拟器 bug 修复规划顾问，帮我把一个 bug 的复现和修复拆成可靠的步骤。

【角色】
你熟悉在 iOS 模拟器里复现和修 bug 的流程，知道先稳定复现再定位、修复后要回归验证。

【输入】
- bug 的现象和触发条件：___
- 涉及的界面 / 模块：___
- 是否能稳定复现：___
- 我的 iOS 开发经验：___

【工作流程】
1. 先在模拟器里稳定复现 bug
2. 让 Codex 据复现路径定位根因
3. 给最小修改方案
4. 修复后做回归验证

【输出规范】
▌一、稳定复现的步骤
▌二、根因定位思路
▌三、最小修复方案
▌四、回归验证方法

【硬约束】
- 先稳定复现再修，不凭猜改
- 最小改动，不顺手重构
- 修复后必须回归验证
- 改动在模拟器实际验证
- 不确定的 API 标注需查官方文档
- 修复方案先在模拟器跑通验证，确认 bug 真的没了再提交，别只凭代码看着对就收工

用 Codex 调 iOS bug，最好让它拥有完整 simulator loop：选择 app target，启动 Simulator，检查当前屏幕，执行复现路径，收集 logs 和 screenshots，需要时看 stack trace，修改代码，再跑同一路径验证修复。

iOS 调试先要证据，再改代码。让 Codex 记录 simulator、scheme、复现步骤、截图、日志或 stack trace，否则修复很难 review。

官方页面：https://developers.openai.com/codex/use-cases/ios-simulator-bug-debugging

适合什么任务

场景	Codex 应该做什么
bug 只在特定 tap、scroll、form entry 后出现	用 Simulator 真实执行复现路径
crash、hang、broken navigation 需要证据	收集 logs、screenshots、view hierarchy、LLDB backtrace
团队希望 Codex 跑完整 reproduce-fix-verify loop	自己复现、定位、修复，再重新验证

使用的能力

能力	用法	链接
`build-ios-apps`	用 iOS debugger agent 通过 XcodeBuildMCP build、launch、inspect、drive Simulator，并收集 logs、screenshots、stack traces	https://github.com/openai/plugins/tree/main/plugins/build-ios-apps

起始提示词

请使用 Build iOS Apps plugin 和 XcodeBuildMCP，直接在 Simulator 中复现这个 bug，诊断 root cause，并实现一个小修复。

Bug report：
[描述 expected behavior、actual bug，以及任何已知 screen 或 account setup。]

约束：
- 先检查 project、scheme 和 simulator 是否已经选定。如果没有，请发现正确的 Xcode project 或 workspace，选择 app scheme，选择 simulator，并在本 session 后续复用这套 setup。
- 在 Simulator 中 build 并 launch app；开始交互前，先用 UI snapshot 或 screenshot 确认正确 screen 可见。
- 自己在 simulator 里通过 tapping、typing、scrolling 和 swiping 执行准确复现路径。优先使用 accessibility labels 或 IDs，不要依赖 raw coordinates；layout 变化后，下一步操作前重新读取 UI hierarchy。
- 调试时捕获证据：visual state 用 screenshots，failure 附近用 simulator logs；如果像 crash 或 hang，再收集 LLDB stack frames 或 variables。
- 如果 simulator 尚未 boot，请 boot 一个，并告诉我选择了哪个 device 和 OS。如果需要 credentials 或特殊 fixture，暂停并只询问这个缺失输入。
- 做能解决 bug 的最小代码改动，然后重新运行 simulator flow，并准确说明你如何验证修复。

交付：
- Codex 执行的 reproduction steps
- 解释 bug 的关键 screenshots、logs 或 stack details
- code fix 以及它为什么有效
- 最终验证使用的 simulator 和 scheme

这个 prompt 要求 Codex 先复现和收集证据，再改代码。不要让它跳过 simulator evidence 直接猜修复。

需要	推荐默认值	原因
Simulator automation	XcodeBuildMCP	覆盖 simulator setup、build/launch、UI snapshots、taps、typing、gestures、screenshots、log capture、debugger attachment
Agent workflow	Build iOS Apps plugin	iOS debugger agent 提供 simulator-first loop，用于复现 bug、收集证据、验证修复
App observability	`Logger`、`OSLog`、LLDB、Simulator screenshots	Codex 可以用 logs 和 debugger state 解释问题，并保存修复前后的 UI evidence

给 Codex 完整 Simulator Loop

这个用例最适合让 Codex 按完整链路工作：

发现 Xcode project 或 workspace。
选择 app scheme。
选择或启动 simulator。
build、install、launch app。
读取 UI accessibility hierarchy。
按复现步骤 tap、type、scroll、swipe。
收集 screenshots、simulator logs、LLDB stack frames。
修改最小代码。
重新运行同一路径验证。

如果 Codex 还没选定 project、scheme 和 simulator，先让它 discover，并在后续 session 复用这个 setup。

XcodeBuildMCP 能做什么

实用 capability groups：

Project and simulator discovery：检查 app target 和 simulator，发现 Xcode project/workspace，枚举 schemes，找到或启动 simulator。
Build and launch control：build active app target，安装并启动 simulator build，需要时 relaunch with log capture，解析 app bundle id。
UI inspection and interaction：读取 accessibility hierarchy，截图，tap controls，type fields，scroll lists，执行 edge swipes 或其他 gestures。
Logs and debugger state：stream simulator logs，attach LLDB，set breakpoints，检查 stack frames 和 local variables，执行 debugger commands。

关键习惯：tap 前先 inspect view tree。优先用 accessibility labels 或 IDs，不要猜 raw screen coordinates。