用途：为 Windows 桌面应用编写并运行自动化 UI 测试。winapp ui 基于 Windows UI Automation（UIA），以 AutomationId 为核心的流程适用于任意 Windows 桌面框架，无论是否打包。非 WinUI 框架可忽略 WinUI 专属建议。
主要能力：核心动词包括 list-windows、inspect、search、get-property、get-value、wait-for、invoke、click、set-value、focus、scroll-into-view、send-keys、hover、drag、touch、pen、screenshot、record。各动词的 --help 可查看选择器与选项。
使用方式：建议用一个整体脚本（ui-tests.ps1）而非大量交互式调用。先在 Step 1 选定目标并保留 PID 与之配对；项目构建/发布在主机执行，部署、启动应用与 ui --on sandbox 在来宾机执行。启动用 winapp run . --on sandbox --detach --json，本地运行则省略 --on sandbox。UI 用完后调用 ui yield。脚本失败应 throw 而非 exit；截图定位到已知主窗口 HWND，以便落到确定的主机路径。
适用场景：UI 自动化测试、可访问性审计、文件选择器/浮出菜单/ContentDialog 测试、键盘与指针输入以及截图证据收集。视觉审查需单独查看主机上的 PNG。
限制：需要解锁的主机与已连接且非最小化的 Sandbox 客户端；树可读不代表输入就绪。winapp target snapshot sandbox --json 只是只读就绪查询。持久来宾机为共享，不适合互不信任的工作流；不支持 --unique-identity。来宾 --debug-output 仅支持打包应用。未打包应用的未打包来宾运行需单独定位 PID，且不可使用遏制 PID。新来宾会使旧 PID/HWND 失效。修复并重跑最多两次。系统快捷键需显式权限开关。