flutter-mcp-cli-runtime-validation

Flutter MCP CLI 运行时验证

当你需要通过 flutter-mcp-toolkit 进行 Agent 式运行时验证，并尽量减少操作步骤时，使用此技能。

两步流程

1. 以调试模式启动 Flutter 应用。
2. 运行一条 CLI 命令：

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart --save-images --output-dir .flutter_mcp/runtime_validation validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --timeout-ms 10000 \
  --post-reload-delay-ms 500 \
  --after-reload

也可以在同一条命令中安装技能：

dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart validate-runtime \
  --target ws://127.0.0.1:8181/<token>/ws \
  --install-skill

此流程的权限行为：

• validate-runtime 仅用于视觉捕获，保持只读／写入权限，并默认使用 auto_request_once。
• doctor 保持只读。
• 在 macOS 上，屏幕录制权限属于运行 flutter-mcp-toolkit 的宿主进程。
• 在 Web 上：desktop_window 使用 macOS ScreenCaptureKit，然后使用 Chrome CDP（Page.captureScreenshot）；Linux／Windows 在远程调试可访问时使用 CDP。如果发现失败，请传入 --web-browser-debugging-port。对于 Web 目标，请传入 --flutter-device chrome，避免验证误选 macOS 宿主的 desktop_window。
• 执行器恢复机制会重试一次宿主捕获（截图载荷中为 desktopCaptureRetried）。如果 desktop_window 仍然失败（包括检测到平台视图时），validate-runtime 会使用 flutter_layer 重试一次。请检查 data.summary.captureFallbackUsed。
• 如果只需要一个 URI，可以传入 VM URI 作为全局参数 --vm-service-uri，而不是使用 validate-runtime --target。

validate-runtime 必须验证的内容

• Doctor 预检通过关键检查。
• 存在所需的工具包扩展：
  • ext.mcp.toolkit.app_errors
  • ext.mcp.toolkit.view_details
  • ext.mcp.toolkit.view_screenshots
  • ext.mcp.toolkit.inspect_widget_at_point
• 截图捕获正常。
• 可获取视图详情（布局元数据）。
• 可检索应用错误。
• 如果启用了 --after-reload，重新加载后的截图也能正常捕获。

输出处理

• 使用 data.summary 作为自动化的通过／失败状态。
• 使用 data.summary.capturePlatformViewsDetected 和 captureFocusAttempted 进行平台视图路由。
• 使用 data.summary.captureFallbackUsed 查看 desktop_window 尝试失败后是否运行了 flutter_layer 重试（包括检测到平台视图时）。
• 使用 data.steps 查看每个步骤的证据和重试情况。
• 使用 data.doctor.checks 说明设置方面的阻碍。
• 启用 --save-images 时，使用 data.summary.screenshotFiles 获取已保存的截图路径。
• 启用 --save-images 时，从步骤数据中读取截图文件 URL。
• 对于视觉调试报告，还要运行：
  • exec --name capture_ui_snapshot --args '{"errorsCount":4,"compress":true,"includeViewDetails":true,"includeErrors":true}'
  • exec --name inspect_widget_at_point --args '{"x":<int>,"y":<int>}'

失败规则

• 如果缺少工具包扩展，请停止并报告埋点缺失，并给出确切修复方法：
  • 将 mcp_toolkit 添加到应用依赖项
  • 确保在 runApp 之前运行 MCPToolkitBinding.instance.bootstrapFlutter(...) 或等效的手动初始化
  • 热重启或重新运行应用
• 如果首次显式 URI 连接失败，对于可重试的连接错误会自动重试。
• 如果截图为空白，请确认应用窗口可见，然后重试。
• 如果 macOS 视觉捕获被拒绝，请使用：
  • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions status
  • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions request
  • dart run mcp_server_dart/bin/flutter_mcp_toolkit.dart permissions open-settings
• 如果应用无法埋点，不要声称已成功检查截图／布局／错误。

视觉 QA 与源码映射规则

• 始终比较更改前后的截图证据。
• 对于每个报告的视觉问题，提供坐标和 inspect_widget_at_point 输出。
• 在可用时，使用 get_app_errors 的顶部堆栈帧（file、line、column）将缺陷映射到源码。
• 除非明确要求，否则不要使用 debug_dump_*。

挑战场景（始终明确指出）

• 没有正在运行的调试应用：doctor 在 vm_target_reachable 上发生严重故障；继续前请先启动应用。
• 目标 URI/token 错误：视为连接不匹配，并使用准确的 app.debugPort.wsUri 重试。
• 已添加工具包，但扩展仍缺失：热重载通常不够，必须热重启或完整重新运行。
• 应用无法修改（无法添加工具包）：报告检查不可用，不要猜测。