用途：Qt Pilot 用于对运行中的 PySide6/Qt 应用做无头可视化测试，让 Claude 能启动应用、点击控件、输入文本、按键、截图并核对控件状态。入口命令为 /qt:visual。
架构：Claude 的 MCP 工具调用 Qt Pilot MCP 服务（mcp/qt-pilot/main.py），经 Unix socket 连接运行在 Xvfb 内的 Qt Pilot 测试桩，测试桩再导入并驱动目标应用。
前提条件：需安装 Xvfb（Xvfb 可执行文件在 PATH 中），可运行 scripts/check-prerequisites.sh 检查；控件须用 setObjectName() 设置对象名才能按名称定位；应用须使用 QApplication 或 QGuiApplication。未命名控件只能使用 click_at 坐标交互和 list_all_widgets。
主要能力（共 15 个 MCP 工具）：应用生命周期 launch_app、get_app_status、wait_for_idle、close_app；控件发现 find_widgets、list_all_widgets、get_widget_info、list_actions；按名称交互 click_widget、hover_widget、type_text、press_key、trigger_action；坐标交互 click_at；视觉捕获 capture_screenshot。
使用流程：launch_app(script_path="...") 或 launch_app(module="...", working_dir="...")，确认 success: true；用 find_widgets("*") 发现控件；执行 click_widget、type_text、press_key 等，并在异步处理或动画后调用 wait_for_idle()；用 get_widget_info、capture_screenshot 验证状态；最后 close_app()。
限制与常见问题：应用导入失败或缺少依赖会导致 launch_app 返回 success: false，可查 get_app_status 的 stderr；控件未调用 setObjectName 则按名称查找失败；应用启动后崩溃会显示连接被拒；点击无效通常因事件未处理，需加 wait_for_idle；截图全黑多因 Xvfb 未运行或显示未设置。测试报告由 gui-tester 代理保存到 tests/reports/gui-YYYY-MM-DD-HH-MM.md，完整工具参数与报告模板见对应 references 文件。