# VMware 自动化客户端交付说明

这是交付包内 `02_宿主机客户端` 的使用说明。这个客户端安装后会提供本地 API、自动化 GUI、截图调试助手和热更新能力。

## 快速入口

- 安装入口：`..\一键部署_新电脑Server.cmd`
- API 启动：`..\一键打开_API.cmd`
- 自动化 GUI：`..\一键打开_PY自动化.cmd`
- 自动化 GUI 六开：`..\一键打开_PY自动化_六开.cmd`
- 截图调试助手：`..\一键打开_截图调试助手.cmd`
- 完整开发文档：`开发文档.md`
- 源码参考：`..\..\03_PY源码参考`
- VM 内 Agent 分发目录：`..\vm_guest_agent_package`

## 安装说明

1. 先解压整个交付包。
2. 在宿主机双击 `一键部署_新电脑Server.cmd`。
3. 安装脚本会提示确认：
   - 安装目录
   - `VM root path`
   - `vmrun.exe` 路径
   - `vmware.exe` 路径
   - 热更新 `manifest.json` 地址
4. 安装脚本会优先读取旧配置，并尝试从 VMware `inventory.vmls` 自动探测虚拟机目录。
5. 不同电脑的 VMware 虚拟机目录可以不一样，最终以你安装时确认的 `VM root path` 为准。

## 安装后行为

- 客户端会完整复制到安装目录，包含 `scripts` 目录。
- API 会在用户登录后自动后台启动。
- API 每次启动前会先检查热更新。
- 本机的 VMware 路径、虚拟机根目录和热更新地址在更新时会保留，不会被新包覆盖。
- 桌面会生成 `Quark Automation GUI`、`Quark Automation GUI x6`、`VMware Tool GUI` 快捷方式。

## 默认地址

- API 文档： [http://127.0.0.1:18765/docs](http://127.0.0.1:18765/docs)
- OpenAPI： [http://127.0.0.1:18765/openapi.json](http://127.0.0.1:18765/openapi.json)
- 热更新清单： `http://47.109.27.133:8010/manifest.json`

## Guest Agent

新的静默控制架构已经接入，以下接口默认走虚拟机内部 Guest Agent：

- `POST /vm/screenshot`
- `POST /vm/click`
- `POST /vm/type-text`
- `POST /vm/send-keys`
- `POST /vm/ui-nodes`
- `POST /vm/find-ui-node`
- `POST /vm/click-ui-node`

Guest Agent 交付文件在 `..\vm_guest_agent_package`，如果需要单独给基础机安装，也可以直接使用交付包根目录里的 `01_虚拟机内Agent服务`。

## 当前已实现

- 虚拟机列表 / 数量 / 单台状态查询
- 单台复制 / 批量复制 / 开机 / 关机 / 删除
- 屏幕截图
- OCR 文字节点查找 / 查找后点击
- 真实 UIA 节点树抓取 / 查找 / 点击
- 模板图片查找 / 查图点击
- 颜色查找 / 查色点击
- 坐标点击 / 输入文本 / 发送按键
- 手工任务执行器
- 基于 `uc_exchange_ip` 设备接口的自动拉单执行器

## 说明

- `POST /vm/find-node` 目前仍然是 OCR 文字节点，适合查“登录”“确定”“下一步”这类屏幕文字。
- `POST /vm/ui-nodes`、`POST /vm/find-ui-node`、`POST /vm/click-ui-node` 依赖虚拟机内部 Guest Agent 的 UIAutomation 能力。
- 多开任务是支持的，但前台窗口相关 UI 动作会在 API 内部串行执行，避免多个 VMware 窗口互相抢焦点。
- 所有执行器默认按“虚拟机无密码、开机后可直接使用”设计，不包含系统密码输入逻辑。