用途：首次设置 qt-ai-dev-tools 以实现 AI 驱动的 Qt/PySide 应用交互，也可用于验证或修复 VM 环境（服务、AT-SPI、显示）以及更新已有安装。不适用于与运行中的 Qt 应用交互（应使用 qt-app-interaction）、在应用中执行代码（qt-runtime-eval）、以及剪贴板、文件对话框、托盘、通知或音频等任务（qt-form-and-input 或 qt-desktop-integration）。
前提条件：Linux 主机、已安装 uv、Vagrant 配合 libvirt provider（vagrant-libvirt 插件与 QEMU/KVM）。
主要步骤：
- 安装工具包。推荐免安装方式：uvx qt-ai-dev-tools workspace init；或本地副本方式：uvx qt-ai-dev-tools install-and-own ./qt-ai-dev-tools --yes-I-will-maintain-it，然后 cd qt-ai-dev-tools 并 uv sync。用 uvx qt-ai-dev-tools --help 或 uv run qt-ai-dev-tools --help 验证。
- 初始化工作区：qt-ai-dev-tools workspace init，生成 .qt-ai-dev-tools/Vagrantfile 与 provision.sh。需检查并可能调整 --static-ip、--memory、--cpus 及 libvirt 网络配置；个人环境可将 .qt-ai-dev-tools/ 加入 .gitignore。
- 启动 VM：uv run qt-ai-dev-tools vm up，首次约 10 分钟，后续约 30 秒，可用 --silent 或 -vv。
- 验证环境：vm status（Xvfb、openbox、AT-SPI 均运行）、apps（AT-SPI 总线正常）、screenshot -o /tmp/test.png（显示 openbox 桌面）。
- 启动目标应用：vm sync 同步文件，vm run "python3 /vagrant/app/main.py &" 启动，wait --app main.py --timeout 15 等待注册。
- 确认交互：tree 查看控件树，screenshot 截图确认。
其他能力：self-update 更新已有安装并保留配置；-v/-vv/--silent/--dry-run 调试；日志写入 ~/.local/state/qt-ai-dev-tools/logs/qt-ai-dev-tools.log；vm sync 与 vm sync-auto 保持文件同步。
限制与排错：DHCP 超时需重建 vagrant-libvirt 网络或使用 --static-ip；AT-SPI 看不到应用需检查应用是否运行、Xvfb、D-Bus 与 DISPLAY=:99；PySide6 缺少 libEGL.so.1 需安装 libegl1 libxkbcommon0；截图为空需确认 Xvfb 与 openbox 运行。具体价格、平台支持范围等资料未提供。