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

## 平台边界

- 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、共享电脑和临时助手验收。