创建和管理实例
实例是 TaskHandoff 中实际运行项目、应用和 AI 会话的工作环境。
创建实例
在工作台左侧实例列表中选择“新建实例”。创建过程分为工作区和运行环境两部分。
选择工作区
你可以选择：
- “仓库”：从已登记的 Git 项目创建工作区，也可以现场添加仓库；
- “本地文件夹”：直接使用目标节点上的现有目录。
使用 Git 仓库时，按需选择托管凭据。默认凭据只用于首次 clone；只有启用“在此实例中保留该凭据”，实例内的 Agent、终端、应用和仓库操作才能继续访问匹配的远端。
选择节点和运行环境
选择负责运行实例的节点，然后选择运行时：
| 运行时 | 适合场景 | 主要限制 |
|---|---|---|
| Docker Runtime | 多实例、隔离环境、团队服务器 | 节点必须提供可用的 Docker daemon |
| Local Runtime | 直接使用宿主机工具和目录 | 同一宿主用户只能运行一个本地实例 |
Docker Runtime 还需要选择镜像或环境模板。选择镜像后，向导会检查 Docker 状态和镜像可用性；“将拉取”表示创建时需要等待下载。
模型和实例名称
按需为主要支持的 Codex 和 OpenCode 选择模型 Provider。实例名称可留空，由系统根据项目生成，也可以填写便于识别的名称。
确认配置后选择“创建”。实例会依次经过“准备中”“启动中”“注册中”，最终进入“运行中”。镜像首次拉取可能需要较长时间，可展开进度查看详细输出。
日常管理
打开实例控制菜单可以执行：
- 启动、停止和重启；
- 重命名实例；
- 打开实例设置；
- 导入或导出受支持的 Agent 配置；
- 保存为环境模板；
- 关闭全部 AI 会话；
- 删除实例。
实例设置包含常规、AI、模型、应用和 Git 凭据等区域。修改模型或部分运行配置后，可能需要重启实例才会生效。
保存环境模板
“保存为环境模板”会从当前 Docker 容器创建可复用环境，适合复用已经安装的软件、系统包和工具链。
保存期间容器可能短暂停止。模板不会包含工作区、托管数据卷、进程或网络状态，也不能作为项目数据备份。
删除实例
删除时可以选择是否“同时删除实例数据”。
删除数据不可撤销
选中后会永久删除实例的全部受管 volume，包括 /data、/home/agent 以及 Git 工作区。操作前请确认代码已经提交或另行备份。
不删除数据时，界面会返回保留的 Docker volume 名称。请立即记录这些名称；系统不会自动把它们挂载到未来实例。
状态说明
| 状态 | 含义 |
|---|---|
| 已创建 | 实例记录已建立，尚未运行 |
| 准备中 | 正在检查或拉取环境镜像 |
| 启动中 / 注册中 | 运行时已启动，正在连接控制面板 |
| 运行中 | 可以启动应用和 AI 会话 |
| 已停止 | 工作已停止，可以再次启动 |
| 不健康 / 失败 | 检查运行环境、节点连接或错误详情后重试 |
节点离线时，控制面板可能显示缓存的实例状态。先恢复节点连接，再判断实例是否真的停止。