SuperAPI AI 工具集

flutter-mcp-cli-runtime-validation

测试与质量

查看项目

更新于 10-15 17:17

技能介绍

用途:在需要以代理式方式执行 Flutter 运行时验证时使用本技能,通过 flutter-mcp-toolkit 以最少的操作步骤完成检查。

两步流程:先以 debug 模式启动 Flutter 应用;随后运行一条 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;Linux/Windows 在可远程调试时使用 CDP,发现失败可传 --web-browser-debugging-port。Web 目标需传 --flutter-device chrome。执行器恢复:宿主捕获失败会重试一次,若 desktop_window 仍失败(含检测到平台视图)则用 flutter_layer 重试一次,可查看 data.summary.captureFallbackUsed。

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 查看是否发生 flutter_layer 重试;用 data.steps 看每步证据与重试;用 data.doctor.checks 解释阻塞原因;--save-images 时用 data.summary.screenshotFiles 获取截图路径。

失败规则:若缺少扩展,停止并报告埋点缺失及修复方式(在应用依赖中加入 mcp_toolkit;确保 MCPToolkitBinding.instance.bootstrapFlutter(...) 或等效初始化在 runApp 前运行;热重启或重跑应用)。首次显式 URI 连接失败会自动重试可重试错误。截图空白需确认窗口可见后重试。macOS 视觉捕获被拒时使用 permissions status、permissions request、permissions open-settings 命令。应用无法埋点则不得声称截图/布局/错误检查成功。

视觉 QA 与源码映射:始终比较变更前后的截图证据;每个视觉问题需给出坐标与 inspect_widget_at_point 输出;可用 get_app_errors 顶层堆栈帧映射到源码;除明确要求外不使用 debug_dump_*。

需明确指出的情况:无运行中的 debug 应用(doctor 关键失败);目标 URI/token 错误(按连接不匹配处理);已加 toolkit 仍缺扩展(需热重启/重跑);不可修改的应用则报告检查不可用而非猜测。