yaoyao/docs/computer-management-ui.md

电脑、镜像与屏幕的界面入口

平台边界

• Web/macOS：Bot 模式聊天列表中常驻“电脑与环境”，包含电脑、共享环境、镜像、节点配置。
• iOS/Android：常驻“桌面与屏幕”，只列出虚拟桌面和共享屏幕，支持查看、接管、输入和交还。没有镜像管理、共享成员变更或执行环境切换入口。
• 没有电脑、节点未连接、账号无管理权限或服务端版本较旧时，保留入口并显示原因。手机安装新版客户端不会自动更新它连接的服务端。

Web/macOS 操作

1. 管理员在“节点配置”注册并连接 Runner，勾选隔离电脑 Worker。镜像 ID 可留空，之后在镜像页准备。
2. 在“镜像”选择执行节点，点击“准备兼容镜像”，或选择 .tar 和配套 .tar.json 上传导入。界面显示传输进度及节点上的操作记录。
3. 准备或导入完成后，在镜像列表选择“应用”。界面显示当前镜像及可回退版本。更新和回退保留工作区。
4. “导出”会生成可分别下载的镜像与校验清单；导出副本可以清理，原镜像保留。未完成上传可以取消清理。
5. “电脑”列出所有自己的 Agent 及配置状态，可以启用隔离电脑、进入查看/接管面板。共享环境在独立的“共享环境”页创建、查看成员或解除。

镜像管理仅对服务器管理员开放。镜像任务开始前要求节点的电脑资源空闲，期间新电脑任务等待；未确认测试电脑已停止时保留维护锁，刷新状态可重试清理。后台任务不会因关闭页面自动重复执行，Runner 重启后原未完成任务显示待核对。

接口与数据

• GET /api/app/computers：当前账号的电脑列表、可用性与原因。
• /api/app/computers/shared：沿用已有账号范围的共享授权。
• /api/app/admin/runners/:id/images：镜像目录、当前/上一个镜像、操作记录。
• /images/jobs：准备、校验、应用、回退、导入、导出；请求编号持久去重。
• /images/uploads：512 KiB 分块传输，上限 20 GiB，校验归档 SHA-256 后导入；不接受宿主路径。
• /images/jobs/:id/archive、manifest：下载导出结果；文件在 Runner 侧，控制面流式转发。

Runner 使用 image-management-v1 能力协商，镜像选择与任务记录保存在 Runner 的 SQLite 中。应用的镜像覆盖节点配置中的默认镜像，重新连接后保留；重新导入不同默认镜像配置时清除旧覆盖。管理请求经过管理员身份和授权版本检查，模型工具没有这些管理接口或凭据。

验证

Web 流程覆盖常驻入口、未配置提示、应用/回退、导出下载及旧服务提示，并检查窄屏深色截图。手机 UI 流程确认没有管理按钮，分别显示独立/共享屏幕并完成接管交还。已有 iOS 28 项 Workspace 测试通过，Android 编译与原生 UI 流程通过。

真实 Docker + 打包 Runner + 控制面已完成镜像准备、校验、应用、回退，并导出、分块下载/上传及重新导入约 500 MB 的兼容镜像，核对 SHA-256。镜像完成后继续执行原有 Worker、共享电脑和临时助手验收。

本分支最终单元/集成测试为 775 项通过、6 项按环境跳过；浏览器流程 7 项通过，真实 Worker 流程 2 项通过。下载块只保存命令指纹，每次重试重新鉴权读取，避免在回执数据库中重复存储整个归档；上传块在网络中断或服务器暂时错误时最多重试两次。

手机端源码为 iOS 1.3（189），已签名并安装至 iPhone 13 Pro Max；安装后设备离线，启动核验尚未完成。Android 已通过编译和模拟器界面验证。新版客户端连接旧服务时显示升级提示；本次未替换正式运行中的 Web 服务。

OpenMausBot 展示方式对齐

这轮以 /Users/samien/git/OpenMausBot 当前源码为参考，重点是 Bot 上下文、镜像状态和手机画面的摆放。

参考实现	本分支对应行为
ios/App/ChatView.swift 的右上角电脑入口	iOS/Android 聊天右上角显示电脑图标。一个桌面直接全屏打开，多个桌面先选择；共享成员指向同一环境时只显示一次。
ios/App/ComputerView.swift、Android ComputerScreen.kt	黑色全屏背景，画面保持原比例并居中，顶部显示 Bot 名称、共享环境和预览/控制状态。
手机端主画面底部的桌面操作	底部保留接管/交还主按钮；接管后点“键盘与操作”打开面板，提供文字、按键、左右键、滚动和交还说明。
按查看生命周期订阅屏幕	当前传输沿用已授权的 Runner 帧接口，仅查看时刷新，退出或后台停止轮询；连接失败显示画面已暂停并禁止输入旧帧。
src/components/LocalComputerSection.tsx 的镜像就绪状态	Web/macOS 镜像页突出当前应用状态，展示“准备镜像 → 应用到节点 → 打开 Bot 电脑”的顺序。

聊天列表的“桌面与屏幕”改为顶部图标，不占用聊天内容和输入区。桌面列表使用紧凑的图标行；没有桌面时才展示配置指引。手机依然不管理镜像、共享成员或执行环境。

本轮原生界面使用从兼容镜像中实际截取的 1280×900 XFCE 桌面进行展示验收；交互 API 由隔离测试服务提供。iOS 覆盖聊天右上角入口、独立/共享选择、全屏预览、接管、键盘输入、交还、大字体深色布局。Android 另外验证等比留黑区域不会产生点击，桌面中心正确映射到远端坐标。Web 7 项浏览器流程通过。真实 Runner 的端到端验收记录见上节；本轮未更换屏幕传输协议。

新版手机界面构建号为 iOS 1.3（190）。189 的既有安装记录不代表本轮布局已经覆盖安装，交付时需再次核对设备状态。

本轮截图：聊天右上角入口、iOS 全屏画面、接管后的操作栏、Android 全屏画面、镜像状态。