ios-debugger-agent

iOS 调试 Agent

概述

使用 XcodeBuildMCP 在已启动的 iOS 模拟器上构建并运行当前项目方案，与 UI 交互并捕获日志。模拟器控制、日志和视图检查优先使用 MCP 工具。

核心工作流

除非用户要求执行范围更小的操作，否则请按以下顺序操作。

1) 查找已启动的模拟器

• 调用 mcp__XcodeBuildMCP__list_sims，选择状态为 Booted 的模拟器。
• 如果没有模拟器处于启动状态，请让用户启动一个（除非用户要求，否则不要自动启动）。

2) 设置会话默认值

• 调用 mcp__XcodeBuildMCP__session-set-defaults，并设置：
  • projectPath 或 workspacePath（根据仓库实际使用的类型选择）
  • 当前应用的 scheme
  • 已启动设备的 simulatorId
  • 可选：configuration: "Debug"、useLatestOS: true

3) 构建并运行（用户有此要求时）

• 调用 mcp__XcodeBuildMCP__build_run_sim。
• 如果构建失败，检查错误输出并重试（可选择使用 preferXcodebuild: true），或在尝试任何 UI 交互前向用户说明情况。
• 构建成功后，调用 mcp__XcodeBuildMCP__describe_ui 或 mcp__XcodeBuildMCP__screenshot，确认应用已启动，再进行 UI 交互。
• 如果应用已经构建完成且用户只要求启动，请使用 mcp__XcodeBuildMCP__launch_app_sim。
• 如果未知 bundle id：
  1. mcp__XcodeBuildMCP__get_sim_app_path
  2. mcp__XcodeBuildMCP__get_app_bundle_id

UI 交互与调试

用户要求检查或与运行中的应用交互时，使用以下工具。

• 描述 UI：点击或滑动前调用 mcp__XcodeBuildMCP__describe_ui。
• 点击：调用 mcp__XcodeBuildMCP__tap（优先使用 id 或 label；仅在需要时使用坐标）。
• 输入：聚焦字段后调用 mcp__XcodeBuildMCP__type_text。
• 手势：使用 mcp__XcodeBuildMCP__gesture 执行常见滚动和边缘滑动。
• 屏幕截图：调用 mcp__XcodeBuildMCP__screenshot 进行视觉确认。

日志与控制台输出

• 启动日志：提供应用 bundle id，调用 mcp__XcodeBuildMCP__start_sim_log_cap。
• 停止日志：调用 mcp__XcodeBuildMCP__stop_sim_log_cap，并总结重要内容。
• 要捕获控制台输出，请设置 captureConsole: true；如有需要，重新启动应用。

故障排查

• 如果构建失败，请询问是否使用 preferXcodebuild: true 重试。
• 如果启动了错误的应用，请确认 scheme 和 bundle id。
• 如果 UI 元素无法点击，请在布局变化后重新调用 describe_ui。