yaoyao/docs/local-vm.md

本地虚拟机

本实现参照 OpenMausBot 的 LocalComputerSection.tsx、ComputerPanel.tsx、LocalVmWorkspace.tsx 及手机 ComputerView.swift / ComputerScreen.kt。

使用流程

1. 进入应用设置 → 本地虚拟机。macOS App 的应用菜单也提供“本地虚拟机设置…”。
2. 检查 Docker/Podman 已安装并启动，点击 准备本地虚拟机。本机执行环境自动连接，不需要手工填写镜像 ID、下载 Runner 配置再导入。准备会复用兼容镜像或构建固定版本，并验证实际桌面后自动使用。
3. 选择 共享虚拟机 或 每个 Agent 独立，最多同时运行 1–4 台，默认 2 台。同一账号、同一基础 Profile 的持久 Agent 共用桌面、工作文件和浏览器资料，新建成员会继承当前共享策略。临时任务助手继续使用任务隔离环境，完成后单独清理，不会删除持久共享工作区。
4. 打开 Agent 聊天，点击右上角 电脑。右侧电脑面板中选择 本地虚拟机，从这里创建或启动该 Agent 的桌面。
5. 右侧显示真实画面及运行状态，可停止或重建虚拟机；点击预览或 打开桌面 后接管交互。
6. 打开双桌面 在主工作区显示两台虚拟机，保留聊天侧栏。进入时仅查看，不会创建/启动机器；切换操作对象时先交还前一台的控制权。

虚拟机实例移除或重建均保留工作目录和浏览器资料。正常完成任务和主动交还后桌面进入空闲状态；空闲 5 分钟后自动停止。取消、授权撤销、异常退出仍停止旧执行实例，以隔离迟到操作。基础 Profile 工作目录变化会在空闲时重建运行实例，数据保留。

切换共享方式不会修改普通 Profile 成员，也不会因其聊天任务而被阻止。已经交还控制权的空闲桌面可保持运行；虚拟机任务仍在执行、人工控制尚未交还或停止状态待核对时，继续保护原执行并拒绝切换。成员任务造成阻挡时，提示会显示具体成员名称。

terminal.cwd 默认的 .（以及 auto、cwd、未设置）指向虚拟机的持久工作区 /home/cua/workspace；相对路径以该工作区为起点，显式绝对路径继续沿用配置。创建、启动和人工接管只读取工作目录，不要求模型可用；停止和移除已有实例也不依赖 Profile 配置。模型仅在运行 Agent 时解析，Profile、目录和模型错误分别提示。

手机端

iOS/Android 没有全局虚拟桌面清单、镜像设置或执行环境选择。入口在 当前 Agent 聊天右上角的电脑图标。单个 Agent 直接打开画面，群聊有多台电脑时选择当前聊天成员的电脑，同一共享环境只显示一次。

黑底全屏、按原比例显示画面，顶部是 Agent 名称、共享标识和状态，底部是接管/交还操作。键盘、文字、滚动及交还说明单独展开。未启用电脑的 Agent 显示桌面端配置提示，不由手机自动创建环境。

范围与接口

• 已删除此前的“电脑与环境”聊天列表入口、独立镜像目录、应用/回退/导入/导出界面及相应管理 HTTP API。
• 旧工作区、旧共享数据、已下载归档和 Docker 镜像不会因删除界面而被删除。无人使用的保留实例可在本地虚拟机设置中停止或移除，工作文件继续保留。
• 托管的本机 Runner 凭据只在服务端加密保存，重启 Web 后自动连接；高级外部 Runner 仍可沿用现有连接配置。
• 本地虚拟机运行在当前连接的服务所在电脑，不跨机器合并容量。
• GET /api/app/admin/local-vm 提供准备状态、隔离策略和实例清单；POST /prepare 准备托管镜像，PUT /policy 更新策略。
• /api/app/agents/:id/local-vm 提供该 Agent 的配置和状态，POST /:action 提供 create/start/stop/recreate/remove。
• 屏幕与输入沿用受控的 /api/app/agents/:id/computer 通道。输入绑定账号、Agent、当前控制令牌、租约版本和截图；旧租约不能继续操作。
• 应用设置只向管理员开放。共享不会跨账号或 Profile；实例操作会拒绝正在由 Agent 或其他人控制的虚拟机。

验收

测试覆盖准备与权限、持久化、实例生命周期、空闲配额、控制权失效、共享范围、聊天右侧面板、双桌面移交及手机聊天入口。另有真实 Docker + Hermes Worker 和从设置自动准备到聊天内操作真实桌面的测试，界面截图来自隔离验收环境。

本轮验收结果：787 项单元/集成测试通过；7 项环境限定测试跳过。7 项浏览器流程、iOS 3 项界面流程、Android 2 项界面流程通过。真实 Hermes Worker + Docker 流程 2 项通过；自动准备本机 Runner、真实桌面键盘输入及快捷键、重启保留文件、双桌面控制切换的完整界面流程通过。

截图：本地虚拟机设置、Agent 聊天右侧电脑面板、交互桌面、双桌面工作区、手机聊天入口。

Docker Web 的固定桌面

Docker Web 使用配套 compose.desktops.yaml 时，桌面由 Compose 预先创建。数量固定为部署清单中的数量，全部作为已有共享桌面供 Agent 选择。页面和 API 都不提供数量修改、镜像准备或桌面增删；每个桌面独立保留工作数据。此模式不会改变 macOS 本机的动态虚拟机流程。部署步骤见 Docker 部署。