本地虚拟机

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

使用流程

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

虚拟机实例移除或重建均保留工作目录和浏览器资料。正常完成任务和主动交还后桌面进入空闲状态；默认空闲 5 分钟后自动停止。应用设置 → 本地虚拟机 → 空闲自动停止 可选择 1、5、10、15、30、60、120 分钟或 永不自动停止。设置保存在执行节点，适用于该节点的所有动态本地虚拟机。再次执行任务或接管时结束空闲计时，交还后重新计时；仅查看画面不会重置计时。

“永不自动停止”仅关闭空闲计时。手动停止、取消、授权撤销、运行中的控制租约过期及执行节点关闭仍会停止旧实例，以隔离迟到操作。基础 Profile 工作目录变化会在空闲时重建运行实例，数据保留。旧版 Runner 需要更新后才能修改此设置；Compose 桌面的启停仍由 Compose 管理。

同一 Bot 使用本机和虚拟机

选择本地虚拟机后，电脑面板提供独立的 执行方式：

虚拟机模式：保留原有独立 Worker。可选的“允许本机环境”继续提供本机文件、命令与复制工具。
本机协作模式：复用云端电脑使用的原生 Profile 会话和工具桥，保留基础 Profile 的本机工具、配置和上下文，同时加入本地虚拟机工具。computer_* 在虚拟机中执行，本机操作使用 Profile 已授权的原生工具；computer_copy_file 显式复制两个环境的文件，computer_export 回传虚拟机产物。此模式本身包含本机环境能力，不再显示重复的权限复选框。

执行方式按 Bot 保存，旧记录默认使用虚拟机模式，不自动迁移。切换执行方式后创建对应的新执行会话，并携带近期聊天记录；虚拟机工作目录、镜像和共享成员不变。任务或人工接管期间不能切换。Bot 创建的成员、临时助手不继承本机协作模式；切换到其他电脑类型或返回虚拟机模式时清除本机协作授权。

本机协作模式需要支持 profile-computer-v1 的配套 Runner，以及当前 Profile 已启用的 yaoyao-bot-bridge。使用与云端模式相同的原生工具桥绑定，不启动隔离模型 Worker。人工接管会请求原生 Profile 停止，确认其空闲且在途虚拟机操作结束后才转交控制权；交还后在原 Profile 会话继续。会话压缩产生的新存储编号在 Runner 中保存，重连继续读取正确的 Profile 历史。

Compose 部署同样可为已选择的桌面启用本机协作模式，仍由 Compose 管理桌面数量和生命周期。所有模式沿用原有虚拟机网络策略，不增加网站发布或端口转发。

兼容旧客户端：取消“允许本机环境”会同时退出本机协作模式，恢复虚拟机模式；不会忽略撤销请求。PUT /api/app/agents/:id/computer-selection 新增可选 vmExecution: worker | profile，未传入时保留原选择。显式同时提交 profile 和 allowHostEnvironment: false 会拒绝冲突配置。

2026-09-14 验证：1119 项服务端及客户端回归通过；新增模式、旧模式本机选项、云端本机选项共 3 项浏览器流程通过（含浅色桌面、深色 390px 页面及刷新恢复）。独立临时 Hermes 配置和真实 Docker 桌面验证了原生终端、虚拟机命令、虚拟机文件读取、Profile 项目上下文与完整回复。模型响应由确定性的本机测试服务提供，不依赖外部模型；测试不使用用户会话。协议测试另覆盖会话编号更新、跨模式会话拒绝、文件复制、团队工具、接管等待与交还继续。

Web／桌面端的 Bot 电脑面板在选择 本地虚拟机的虚拟机模式 或 云端 · Grok Bot 后显示独立的 允许本机环境 复选框。勾选不会改变所选虚拟机类型；切换到自动、本机、仅浏览器或不使用电脑时自动清除该选项，切回虚拟机也不会重新勾选。

本地虚拟机勾选后，host_shell、host_read_file、host_write_file 在 Hermes 执行节点所在主机运行，可操作该主机用户有权访问的文件和程序。默认本机工作目录采用 Profile 的显式目录；.、auto、cwd 使用执行节点用户的主目录。
computer_shell、computer_read_file、computer_write_file、桌面操作等继续在隔离 Linux 环境内执行。虚拟机不会因为启用双环境而挂载本机项目目录。
computer_copy_file 在两个环境之间显式复制文件，支持二进制文件，单文件最多 25 MiB。目标同名文件会被覆盖。
云虚拟机勾选后，本轮规则允许同时使用基础 Profile 已授权的本机文件和终端工具；云端操作继续使用 cloud_computer_*。取消勾选后，本轮规则要求电脑操作使用云端工具；Profile 本身的工具配置不被修改。
勾选后，已连接且已授权的 macOS 桌面可同时提供本机桌面工具。未授权屏幕控制时，本机命令与文件工具仍可用；电脑面板默认显示虚拟机画面。

环境选择按 Bot 保存，任务执行或人工接管期间不能切换；下一轮采用当前授权，不会把本机工具带入已切回的仅虚拟机模式。Bot 创建的成员和临时助手不会自动获得本机工具。外部 Runner 必须支持 host-computer-tools-v1；“本机”指执行节点主机，可能与打开 Web 的电脑不同。Compose 模式先选择已有桌面，再勾选 允许本机环境，不改变固定桌面数量和生命周期。

空闲策略接口为管理员专用 PUT /api/app/admin/local-vm/idle-policy，参数 requestId 和 idleStopMinutes（0 表示永不，1–10080 表示分钟）。Bot 双环境沿用 PUT /api/app/agents/:id/computer-selection，传入所选 computer: vm | cloud 与独立的 allowHostEnvironment: true | false。其他电脑类型强制清除此布尔值；旧 hybrid 记录在启动时一次性迁移为 computer: vm 和 allowHostEnvironment: true。

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

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

上下文压缩与错误恢复

本地 Worker 保留独立执行架构，但会在每次创建或恢复会话时读取基础 Profile 的 compression 开关、阈值、保留消息规则、重试与超时设置，以及 model.context_length / max_tokens。未设置时采用 Hermes 默认值；明确关闭自动压缩的 Profile 继续保持关闭。人工接管后继续当前轮次沿用原配置快照，下一轮再读取最新配置。

压缩完成、工具执行进度和轮次结束都会保存会话历史。失败返回的压缩历史也会保留，下一轮从保存后的历史继续；已结束或已被替换的 Worker 不能用迟到的检查点覆盖新状态。Hermes 在压缩边界刷新工具时仍使用当前轮次由父进程授权的工具清单，不会丢失虚拟机工具或重新发现本机原生工具。

上下文已满且自动压缩关闭，或自动压缩已耗尽重试／超时，属于会话错误：本轮显示失败原因，持久虚拟机释放控制权进入空闲，按配置的空闲时间停止；选择“永不自动停止”时继续运行。取消、授权失效、工具执行状态不确定、Worker 异常退出及未分类的失败仍会停止旧运行实例。错误类型采用 Hermes 返回的结构化标记，不根据模型回复中的“上下文超限”文字判断。

更新 Web／App 的配套 Runner 后生效，不修改 Grok Bot 云端会话路径。验证覆盖真实 Hermes 自动压缩、压缩后续聊和工具清单、压缩关闭／耗尽时的错误分类，以及真实 Docker 实例和文件保留、之后按空闲策略回收。

镜像与持久状态

标准桌面沿用现有 XFCE 镜像；Cursor Universal 基于 public.ecr.aws/k0i0n2g5/cursorenvironments/universal:sand-box-latest 的固定 amd64 摘要，并添加相同的 CUA 0.20.0 驱动和私有桥接协议。原始镜像不能直接填入现有桌面镜像配置。
Cursor 镜像目前只有 Linux amd64；Apple 芯片上的 Docker/Podman 需要支持 amd64 模拟。macOS arm64 App 安装包不代表有 Linux arm64 桌面镜像。
每台独立桌面拥有自己的工作目录和浏览器资料。同一共享桌面只有一个持久镜像选择，所有成员看到同一个选择。
准备第二个镜像不会替换已有实例的镜像。切换前先停止任务、交还控制权，在电脑面板点击“移除实例”，再选择新镜像并创建。实例移除保留持久数据，后续启动和重启沿用已选镜像。
POST /api/app/admin/local-vm/prepare 接受可选的 imageKey: standard | cursor；PUT /api/app/agents/:id/local-vm/image 保存该桌面的镜像选择。客户端只能选择已准备的配套镜像，不能提交任意镜像 ID。

手机端

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、当前控制令牌、租约版本和截图；旧租约不能继续操作。
应用设置只向管理员开放。共享不会跨账号或执行节点；实例操作会拒绝正在由 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 部署。

local-vm.md 14 KB История Исходник