第 18 章：SPACE——环境、操作与连接各有一条生命线

为什么 API 返回了还不能开始

SPACE 的全称是 Sandboxed Platform for Agentic Code Execution。它使用 Firecracker microVM 提供执行环境，应用通过 HTTP API 创建环境、执行命令并管理生命周期。[12]

它的架构文档有一个特别适合学习的设计：沙箱、异步操作、命令进程和输出连接分别建模。创建请求返回 operation ID，客户端需要查询完成状态；“请求已被接收”不是“环境已经可以执行”。

用点外卖理解几个 ID

sandbox ID 像厨房编号，operation ID 像开设厨房的工单，process ID 像某一份制作任务，命令会话里的 attachment token 则像这次查看制作过程的通行证。关闭手机上的观看页面，并不代表厨房停止工作，也不代表工单被撤销。

SPACE 的原生流程中，创建 command session 分配进程标识，attach 才启动进程并接收输出。接口里多这一步是有语义的，不要把“拿到会话”误当成“代码已经执行”。断流后应按该版本的接口查询状态或重连规则处理，避免重复提交有副作用的命令。

first-sandbox 文档还明确指出，命令输出是实时流，不是持久日志；用 Last-Event-ID 重连会得到 resync_required，而不是补发丢失输出。应用需要自己保留必要记录，不能默认把断流变成无损续传。

控制面怎样推进现实

架构文档描述 API 把期望状态写入 PostgreSQL，控制器与节点服务再让运行状态收敛到它。在本地 Kind 拓扑中，还包括 Kubernetes sandbox pod、runtime shim、worker 和 microVM；输出则走独立的数据面。

源码 controllers/substrate/direct.rs 同时提供了直接访问 worker 的适配路径。因此“官方入门使用 Kubernetes”不能推导成“整个系统只能在 Kubernetes 上运行”。该文件也列出了 Direct 路径的功能限制；有两个后端不表示功能完全对等。

最值得学的暂停语义

SPACE 原生 pause 保留驻留内存，suspend 才把内存、运行时状态和根文件系统持久化并释放活跃 VM 资源。恢复驻留环境和从快照恢复环境，在成本与故障后能否恢复方面有不同含义。

更容易踩坑的是兼容层：ECW 的 E2B pause 对应原生 suspend，resume 对应 restore。在 crates/libs/api/src/routes/e2b/lifecycle.rs 中，可以直接找到 e2b_native_pause_action 返回 Suspend、e2b_native_resume_action 返回 Restore 的实现。不能只按动词拼写连接两个系统。

小白的阅读顺序

先读 README 流程，再读 docs/architecture.md 的核心概念和生命周期表，最后读 docs/first-sandbox.md。部署前检查官方安装文档中的 Linux、虚拟化和存储要求；Mac 上有 Docker 不代表能直接运行一切依赖 KVM 的平台。

练习：画出“创建环境成功、命令失败、输出连接断开、删除完成”四件事的时间线，为每件事标明用哪个 ID 查询。它比背所有 Rust crate 名字更有价值。