flutter-mcp-toolkit-guide

适用场景

当用户想在当前对话中检查或操控正在运行的 Flutter 应用时，请使用此技能。示例：

• “点按应用中的登录按钮”
• “为什么主屏幕是空白的？”
• “截张屏幕截图，告诉我哪里出了问题”
• “通过 MCP 向 Agent 暴露我的购物车／标志／内部状态”

如果用户询问的是与正在运行的应用无关的 Flutter 概念（架构问题、软件包选择），则不适用此技能。

步骤 1：预检

始终先运行 flutter-mcp-toolkit doctor --json。解析输出：

• status: "ok" — 继续执行步骤 2。
• status: "error" 且 error.code: "binary_not_found" — 加载 flutter-mcp-toolkit-setup，并按照其中的安装说明操作。
• status: "error" 且 error.code: "vm_not_connected" — 加载 flutter-mcp-toolkit-setup，并按照其中的故障排查部分操作。
• 其他任何错误 — 加载 flutter-mcp-toolkit-debug，并阅读错误封装说明。

步骤 2：根据用户意图选择合适的技能

用户意图	加载技能
查看状态（“屏幕上有什么？”、“显示错误”、“屏幕截图”）	flutter-mcp-toolkit-inspect
操控 UI（“点按 X”、“在 Y 中输入”、“滚动到 Z”、“热重载”）	flutter-mcp-toolkit-control
诊断问题（“为什么 X 失败了？”、“显示最近的日志”、“求值表达式”）	flutter-mcp-toolkit-debug
注册特定应用的 MCP 工具／资源（AgentCallEntry、addEntries）	flutter-mcp-toolkit-custom-tools
从已移除的旧版调用条目 API 升级	flutter-mcp-toolkit-intentcall-migration
更改工具接口前，审查 CLI／MCP／架构／动态注册表的一致性	flutter-mcp-boundary-audit
维护 showcase/flutter_test_app 的 Web／WebMCP 展示钩子；通过 Chrome DevTools MCP 列出／执行 Agent 工具（list_webmcp_tools／execute_webmcp_tool）	flutter-mcp-toolkit-maintain-web
维护 showcase/flutter_test_app 的 macOS／原生 IntentCall 钩子	flutter-mcp-toolkit-maintain-macos
评估 dogfood 迭代，或路由 dogfood 证据	flutter-mcp-toolkit-dogfood-iterations
将可重复的 E2E 场景编写为 Dart（flutter_mcp_harness：构建／启动／连接／操控／断言、展示应用启动器）	flutter-mcp-e2e-harness
为应用的多个界面（MCP／CLI／harness／oka）、初始循环和 runner 会话配置自动化	flutter-mcp-automation-chain
维护发布、版本或插件技能包	flutter-mcp-toolkit-repo-maintainer

Harness Script 的 lint／运行／Maestro，以及宣传素材／视频录制，归其所属仓库负责。不要在此插件中查找 flutter-mcp-semantic-test、flutter-mcp-capture 或 hyperframes-video。

如果任务涉及多个技能（例如“点按按钮并告诉我有什么变化”），请加载 inspect 和 control。技能可以叠加使用。

步骤 3：执行

每个任务技能都列有工具清单、参数格式和调用示例。请遵循技能开头的前言——其中会说明你需要调用 MCP 工具，还是通过 CLI 执行命令。

工具分类参考

核心工具包中的工具分为以下几类。完整列表及参数结构请参阅任务技能。

• 检查（只读）： discover_debug_apps、get_app_errors、 get_screenshots、get_view_details、get_vm、get_extension_rpcs、 semantic_snapshot、inspect_widget_at_point、capture_ui_snapshot、 connect_debug_app。→ flutter-mcp-toolkit-inspect。
• 交互（会修改状态）： tap_widget、long_press、enter_text、 reveal_search、fill_form、scroll、swipe、drag、hover、 focus_widget、press_key、wait_for、navigate、handle_dialog、 hot_reload_flutter、hot_restart_flutter、hot_reload_and_capture。→ flutter-mcp-toolkit-control。
• 调试： get_recent_logs、evaluate_dart_expression。→ flutter-mcp-toolkit-debug。
• 动态注册表（由应用定义）： 在 Flutter 应用中注册后，MCP 调用使用 fmt_list_client_tools_and_resources，然后使用 fmt_client_tool / fmt_client_resource。通过 CLI 调用 shell 命令时，命令名称只会作为 exec --name <name> 的值出现；不要将裸的 list_client_tools_and_resources、client_tool 或 client_resource 作为 MCP 工具调用。→ flutter-mcp-toolkit-custom-tools。
• 边界／证明维护： 更改目录／架构／注册表相关界面前，使用 flutter-mcp-boundary-audit；维护展示平台钩子时，使用 flutter-mcp-toolkit-maintain-web 或 flutter-mcp-toolkit-maintain-macos；进行发布、版本和生成的 技能包相关工作时，使用 flutter-mcp-toolkit-repo-maintainer。
• 真正的 WebMCP（浏览器）： 使用 Chrome DevTools MCP （--categoryExperimentalWebmcp）导航到 Web 应用后，使用 list_webmcp_tools / execute_webmcp_tool。详情请参阅 flutter-mcp-toolkit-maintain-web。

有疑问时

如果 doctor 状态正常，但工具调用失败，请阅读返回的 error.code 和 error.recovery 字段。完整的代码 → 恢复操作对照表位于 flutter-mcp-toolkit-debug。