|
|
@@ -0,0 +1,31 @@
|
|
|
+# 远程桌面主机
|
|
|
+
|
|
|
+一台服务器集中运行 Web（15300）与 Hermes（9119），其他 Mac 安装夭夭 App 后作为"桌面主机"出站连接服务器，向服务器上的 Bot 提供自己的真实桌面（截图、键鼠、独立浏览器）。服务器自己机器上的 App 继续走本机回环通道，等同一台编号为 `local` 的主机。
|
|
|
+
|
|
|
+## 启用流程
|
|
|
+
|
|
|
+1. 管理员在 Web「设置 → Hermes 连接 → 桌面主机」注册主机（填写名称），一次性下载 `desktop-host.json`。凭据只在注册响应中出现，服务端只保存哈希；列表与停用接口不返回令牌。
|
|
|
+2. 在那台 Mac 上打开夭夭 App，菜单「桌面主机 → 导入主机配置…」选择下载的文件。配置经系统钥匙串加密保存在数据目录（`desktop-host.enc`，0600），不进入命令行或环境变量。
|
|
|
+3. 卫星机可在「桌面主机」菜单勾选「仅作为桌面主机运行」：不启动本机 Web 服务与本机回环通道，只维持远程连接。
|
|
|
+4. 管理员在机器人聊天右侧电脑面板选择「本机」或「仅浏览器」后，用「操作的电脑」选择器把机器人绑定到某台主机（`agent.desktopHost`）；未绑定时自动解析：优先本机回环，其次唯一在线的远程主机，多台在线必须显式选择。
|
|
|
+5. 首次授权：管理员点「在桌面端授权」，那台 Mac 弹出原生授权对话框；确认后引导开启屏幕录制与辅助功能。授权按账号哈希（ownerKey）记录在各 Mac 的 `computer-permissions.json`，各机独立；菜单「撤销本机控制授权」同时作用于本机与远程通道。
|
|
|
+
|
|
|
+## 传输与边界
|
|
|
+
|
|
|
+- 机器端点 `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」（配置写入 `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/host-manager.test.mjs`（配置校验、加密导入、交换往返、403 停止、退避重试）、`desktop/preferences.test.mjs`（仅桌面主机偏好持久化）。
|
|
|
+- 浏览器：`tests/e2e/desktop-hosts.spec.ts`（注册/下载/停用；模拟远程主机连接后从电脑面板绑定机器人）。真实多机链路需按上述流程手工验收。
|
