# 远程桌面主机

一台服务器集中运行 Web（15300）与 Hermes（9119），其他 Mac 安装夭夭 App 后作为”桌面主机”出站连接服务器，向服务器上的 Bot 提供自己的真实桌面（截图、键鼠、独立浏览器）。服务器自己机器上的 App 继续走本机回环通道，等同一台编号为 `local` 的主机。

## 并列环境（envs）

每个机器人拥有一组并列的环境开关（`agent.envs`）：**本地虚拟机**、**云端 Grok Bot**、**本机控制**（所有已连接并授权的 Mac）、**仅浏览器**；全部取消即不启用任何环境。勾选的环境同时生效：工具目录是各环境工具的并集，bot 可在同一次任务里查看 A 机屏幕、读 B 机文件、在虚拟机里跑命令。旧机器人的单一 `computer` 选择按”auto→全开、显式选择保留”推导，首次在面板勾选后即迁移为 envs；`/api/app/agents` 仍下发投影后的单值字段，手机端不受影响。

- **多机寻址**：`desktop_*` 工具（查看/操作/文件/命令/浏览器）接受可选 `host` 参数（电脑名称或编号）；未指定时用绑定主机或唯一在线主机。每轮系统规则会列出当前在线的电脑名称。
- **按需执行（Runner 视情况）**：只有勾选”本地虚拟机”且执行节点在线就绪时，会话才走 Runner/VM；节点离线或缺能力时该轮自动改用本机会话（桌面与云端工具照常），绑定与消息执行标记跟随实际执行方式。
- **分后端接管**：`/api/app/agents/:id/computer` 系列接受可选 `backend=desktop|cloud|vm` 查询参数，三段路由按参数透传；缺省保持 desktop→cloud→vm 顺序（手机端契约不变）。Web 面板的云端/虚拟机按钮直达对应查看器。

## 启用流程

1. 在那台 Mac 上启动夭夭 App。**首次启动会询问这台 Mac 的使用方式：「登录远程…」或「进入本地」**。
   - 选「登录远程」：弹出登录窗口，填写**夭夭服务器地址（如 `192.168.1.10:15300`）、用户名和密码**。登录成功后窗口直接使用远程服务器的夭夭界面（本机不运行 Web 服务）；用**管理员账号**登录时，App 会自动把这台 Mac 注册为远程桌面主机（令牌经系统钥匙串加密保存在数据目录 `desktop-host.enc`，0600），无需任何配置文件。非管理员账号只登录界面，并提示需要管理员账号才能注册本机控制。
   - 选「进入本地」：保持原有行为，使用本机 Web 服务。
   - 勾选「记住选择，之后启动不再询问」会把选择写入偏好（`startupChoice`）；也可在菜单「桌面主机 → 启动时询问使用方式」恢复每次询问。
2. 后续启动直接进入远程模式；若登录会话已过期，App 会重新弹出登录窗口（服务器地址已预填）。会话 Cookie 保存在 App 的会话存储中，密码不落盘。使用中可随时通过菜单「桌面主机 → 登录远程服务器… / 进入本地服务」切换；「忘记配置」会移除本机的桌面主机凭据，下次登录时重新注册。
3. 服务器管理侧（可选）：「设置 → Hermes 连接 → 桌面主机」列出各台已注册主机（在线状态、机器名、最后在线）并可停用；停用立即断开那台 Mac。手动注册并下载 `desktop-host.json` 仍可用于不便登录的机器（菜单「桌面主机 → 导入主机配置…」），但常规流程不再需要。
4. 管理员在机器人聊天右侧电脑面板选择「本机」或「仅浏览器」后，用「操作的电脑」选择器把机器人绑定到某台主机（`agent.desktopHost`）；未绑定时自动解析：优先本机回环，其次唯一在线的远程主机，多台在线必须显式选择。
5. 首次授权：管理员点「在桌面端授权」，那台 Mac 弹出原生授权对话框；确认后引导开启屏幕录制与辅助功能。授权按账号哈希（ownerKey）记录在各 Mac 的 `computer-permissions.json`，各机独立；菜单「撤销本机控制授权」同时作用于本机与远程通道。

## 文件与命令（全面操作）

屏幕授权之外是独立的第二档授权「文件与命令」：电脑面板完成屏幕授权后出现「授权文件与命令」按钮，Mac 端弹窗单独确认。授权后该账号绑定这台机器的机器人获得四个工具：

- `desktop_file_list` / `desktop_file_read` / `desktop_file_write`：在这台 Mac 的**用户主目录**范围内列目录、读文件（≤12MB）和写文件（≤10MB）；`..`、绝对路径越界和符号链接逃逸都会被拒绝，TCC 保护目录仍按系统权限处理。
- `desktop_shell`：在主目录执行一条 zsh 命令（最长 120 秒，stdout/stderr 各截断 512KB，超时终止并如实报告）。

两档授权分别记录（`approved` 与 `approvedFull`），「撤销本机控制授权」同时清除；工具只注入给已获授权的机器人，且每次调用在服务端二次校验。

## 传输与边界

- 机器端点 `POST /api/desktop-host/v1/<hostId>/exchange`：Bearer 令牌（sha256 后 timingSafeEqual）+ `x-desktop-host-protocol: 1`；拒绝任何携带 Origin 的请求，不进入用户会话、CSRF 或 CORS 体系；Host 白名单照常生效。
- 交换协议沿用桌面端 `{host, results} → {commands}` 格式：每轮最多 8 条命令、20 条结果，请求体上限 24MB。App 成功后 400ms 轮询，网络错误指数退避至 5s；令牌失效（401/403）即停止并提示重新导入。
- 每台主机独立持有命令队列、截图缓存、接管凭据与授权状态；宿主 epoch（App 每次启动/撤销时轮换的 host.id）变化即围栏在途命令。人工接管的 generation/epoch/30 秒续期语义与单主机时一致，接管记录以 `desktop:<hostKey>:<resource>` 区分。
- 远程明文 HTTP（服务器地址以 `http://` 登录）时，App 保存的主机配置自动带 `allowInsecureLan: true`，与 Runner 规则一致；公网部署应使用 HTTPS 并把域名加入外网访问地址。登录凭据只走该服务器地址，密码不落盘。
- 停用主机立即断开那台 Mac 并围栏其在途命令；配置丢失时停用并重新注册，旧令牌不能恢复。

## 范围

- 物理机控制仅支持 macOS（屏幕录制、辅助功能与 computer-helper 签名校验均为 macOS 专属）。
- 本功能只提供真实桌面与独立浏览器环境；远程机器上的 Linux 虚拟桌面（无 Hermes 电脑节点）不在本范围。
- 服务器侧 Bot 会话、模型与记忆全部留在服务器的 Hermes；卫星机不安装 Hermes。

## 验证

- 服务端：`tests/server/desktopHosts.test.ts`（注册令牌一次性、准入与协议头、撤销围栏）、`tests/server/desktopEnvironments.test.ts`（多主机隔离、绑定解析、按机围栏、接管按机独立）。
- App：`desktop/remote-login.test.mjs`（地址归一化、账号密码登录的 CSRF/Origin 往返、管理员注册桌面主机、错误路径）、`desktop/host-files.test.mjs`（目录内列/读/写、路径与符号链接逃逸拒绝、命令退出码/超时/工作目录）、`desktop/host-manager.test.mjs`（配置校验、加密导入、交换往返、403 停止、退避重试）、`desktop/preferences.test.mjs`（启动选择与远程地址偏好持久化）。启动选择/登录窗口需按上述流程手工验收（自动化桌面测试通过 fixture 环境固定走本地路径）。
- 浏览器：`tests/e2e/desktop-hosts.spec.ts`（注册/下载/停用；模拟远程主机连接后从电脑面板绑定机器人）。真实多机链路需按上述流程手工验收。