我们遇到的就是这类问题。用户可以在 Sandbox 里安装软件，而实例回收、重新创建以后，安装过的东西没有跟着回来。

上一篇文章讨论了如何把源码留在 NAS，把依赖安装和构建放到本地盘。这次要继续看工作区之外的内容：软件到底装在哪里，怎样让这些安装结果跨实例保存，以及三种持久化方案各自需要解决什么问题。

1. 文件还在，软件为什么没了

1.1. 先分清“重启”做了什么

先用一个简化场景说明。假设基础镜像没有 Graphviz，用户在 Debian 系的 Sandbox 中执行 apt-get install graphviz，随后用它的 dot 命令把项目里的关系图导出为图片。

这时有两份新内容：工作区里生成的图片，以及系统里新增的 Graphviz。两者虽然都能从同一个终端访问，实际可能写在完全不同的存储上。

容器启动时，根据基础镜像准备文件系统。镜像提供初始的系统文件，运行中新增和修改的内容进入这个实例的可写层。与此同时，平台把 NAS 上的项目目录挂进容器，作为工作区。这里把工作区简写为 /workspace。

如果只重启 Agent 进程，文件系统没有换掉，已经安装的文件通常还在。如果停止容器后继续启动原容器，能否保留文件，要看平台是否保留它的可写层。

我们遇到的另一条路径是：旧实例被销毁，再从基础镜像创建新实例。 新实例重新挂载原来的 NAS，所以代码和图片还在；它的系统文件重新来自基础镜像，后来安装的 Graphviz 就没有了。Docker 文档也明确区分了容器可写层和独立 Volume：删除容器会删除可写层，Volume 则有独立的生命周期。Docker Volume

因此，排查时需要看实际发生的是进程重启、原实例恢复，还是销毁后重建。业务层沿用同一个 Sandbox ID，也不能证明底下仍然是同一份文件系统。

1.2. 一次安装会修改哪些地方

apt、apk 是系统包管理器，分别常见于 Debian 系和 Alpine 系发行版。它们安装软件时，不会把所有内容都放进当前工程目录。

下面列的是系统安装可能涉及的位置，不是 Graphviz 某个版本的完整文件清单。

例如，只复制一个可执行文件，可能因为缺共享库而无法运行；只保存包管理器的数据库，则可能出现“记录显示已经安装，文件却不存在”的情况。Debian 的安装流程还会执行包中的维护脚本，处理配置等工作，安装结果不只是一组解压出来的文件。Debian 包安装过程

这里需要保存的是一套相互匹配的文件与元数据。后面提到的根文件系统（RootFS），指的就是 Sandbox 从 / 开始看到的系统文件体系。独立挂载进去的 NAS、临时内存文件系统等，需要按各自的存储规则处理，不能默认算进一份 RootFS 备份里。

我们当时讨论的三条路，也就对应三个不同的保存范围：保留指定目录、保留原来的运行磁盘、把某一时刻的系统环境保存成快照。

2. 方案一：把需要的目录挂到持久卷

2.1. 新实例重新挂载原目录

这是最容易从现有工作区方案继续扩展的一条路。

平台为项目准备一份独立存储，在每个新实例中挂到固定路径。写入这个目录的内容留在存储里，实例删除后，下一个实例再挂载同一份数据。NAS 可以承载这种目录；自建容器平台也可以通过 Volume 或 Kubernetes PVC 声明需要的存储。

但 Volume、PVC 说明的是挂载与管理方式，具体数据存在哪里，仍要看后端。Docker 的本地 Volume 默认在宿主机上；需要换节点恢复时，还必须有相应的共享存储、磁盘迁移或数据恢复能力。Docker Volume 的存储与共享

平台至少需要记录项目对应的卷标识或远端目录、挂载路径、访问身份。创建新实例时，先完成挂载，再启动依赖这些目录的工具。挂错项目目录、改变安装路径，或者恢复后使用不同的用户权限，都可能让文件还在，却无法正常使用。

2.2. 适合能控制安装位置的工具

例如，一个工具允许把自身及依赖安装到 /home/user/tools，我们可以把这个目录持久保存，启动时再配置好 PATH。对于能明确管理目录的用户级工具，这样做简单，也不需要备份整个系统。

语言依赖需要再看一层。保存 Python 虚拟环境的目录，并不保证换一个基础镜像后仍能运行：它可能依赖原来的解释器路径、系统库或本地编译扩展。恢复时应保持兼容的基础环境，或者根据依赖声明重新安装。

上一篇文章中的 node_modules 就采用了后者：保存源码、包声明和锁文件，在新的本地盘上重新准备依赖。这里主动保留的是重建输入，本地依赖目录可以丢弃。这有助于兼顾持久性和小文件访问性能。

2.3. 系统包为什么不能照搬

对于任意 apt install 或 apk add，平台无法事先假定所有修改都落在一个用户目录。多挂一个 /home，仍然覆盖不到 /usr、/etc 和系统包数据库。

把这些系统目录逐个挂出去，还会引出新的问题。挂载到已有目录上的外部文件系统，会遮住那个位置原有的内容；它不会自动把旧系统与新镜像正确合并。基础镜像升级后，外部目录里的旧库、旧配置和新系统之间，也需要处理兼容关系。Docker 挂载覆盖行为

我们的 FC 环境还有平台限制：NAS 挂载文档要求使用适合的数据目录，不能把通用系统目录及其子目录作为挂载点，例如 /bin、/opt、/var、/dev。FC 配置 NAS

所以，这个方案适合保存边界明确的目录。要支持用户自由安装系统软件，就需要把保存范围扩大到整套系统环境。

3. 方案二：停止计算，保留运行磁盘

3.1. 把磁盘的生命周期单独管理

第二种方案直接保留已经安装好的那份文件系统。

对于虚拟机，可以是保留系统盘；对于容器，可以由运行平台保留根文件系统的可写部分，并继续使用匹配的基础镜像。用户安装软件后，文件和包管理器记录都在这份环境里。停止计算时保留它，恢复时继续使用它。

这样，前面的 Graphviz 无须重新安装。恢复时取得原来的磁盘，软件文件、配置和包记录就一起回来了。进程则通常要重新启动，磁盘持久化本身不包含进程内存。

Daytona 的普通 Container Sandbox 提供了这类使用语义：stop/start 保留文件与安装包，停止时清除内存；删除 Sandbox 则是另一种操作。具体选型仍需核对 Sandbox 类型和自动删除配置，不能只看一个“支持持久化”的介绍。Daytona 持久化说明

3.2. 平台需要记录什么

业务层不能只保存“项目正在使用哪个实例”。还需要保存项目的环境磁盘标识、匹配的基础镜像版本，以及当前由哪个实例使用。

正常停止时，平台应让安装和写入结束，再按存储系统的要求完成落盘，最后停止计算、保留磁盘。恢复时找到这份磁盘，确认旧实例已经停止写入，再交给新的运行实例。删除项目时，才根据保留策略删除它。

这里有一个容易忽略的情况：旧实例网络断开，平台认为它失联，于是又启动了一个新实例。旧实例其实还活着，两个实例就可能同时修改包数据库。管理服务中的一把锁还不够，平台需要通过磁盘挂载约束或存储侧的写入控制，阻止已经失去所有权的旧实例继续写。

3.3. 磁盘保留在哪，决定了能恢复到哪里

如果只是让容器停在原机器上，并保留那台机器的本地可写层，原地启动确实方便。但宿主机永久故障以后，能否恢复就取决于有没有其他持久副本。

要允许换节点恢复，需要磁盘本身能脱离原计算节点，例如使用可重新挂载的持久块存储，并满足可用区、文件系统和运行时的约束。异常断电后还可能面对文件系统恢复、包安装中断等状态，保存磁盘不会自动把安装过程变成一个事务。

这条路的主要成本是长期保留每个项目的环境空间，以及磁盘挂载、迁移和故障处理。计算停止后，存储仍然占用资源。它适合经常回来继续工作的开发环境；若有大量长期不活跃的项目，还需要归档和回收机制。

4. 方案三：把环境保存成文件系统快照

4.1. 新实例从保存的环境启动

第三种方案允许原实例彻底退出。退出之前，先把某个时刻的根文件系统保存为一个可恢复版本；下次根据这个版本创建新实例。

快照可以是完整磁盘副本，也可以只记录相对基础镜像的变化。后者能够复用公共镜像，项目只保存自己新增、修改和删除的内容。这里讨论的是文件系统快照；要继续执行原来的进程，还涉及另外的内存与设备状态恢复。

例如，Modal 的文件系统快照记录 RootFS 相对基础镜像的差异，生成的 Image 可以创建新 Sandbox。它的文档也明确说明，挂载的 Volume 不包含在这份快照里；快照还需要配置保留期限。Modal 文件系统快照

恢复 Graphviz 时，平台不再重新执行安装命令，而是从快照取得已经安装好的文件与状态。快照生成以后，即使原实例被删除，只要快照及其依赖仍在，便可以据此准备另一个实例。

保存差异时，删除操作也必须被记录。假设用户删除了基础镜像中的一个配置文件，只备份“当前新增的文件”，恢复后那个旧配置又会出现。以 OverlayFS 为例，它会用 whiteout 等元数据表达对下层文件的删除；这类信息不能在复制过程中丢失。Linux OverlayFS

4.2. 在什么时刻保存

最直接的做法是正常关闭前保存一次。但节点故障、强制回收等情况，不保证有机会执行关闭脚本。要减少丢失，就要在环境修改后建立保存点。

用户安装 Graphviz 后，当前实例里已经有新软件，但持久存储中还是上一次保存的环境。只有新快照生成、上传并确认可恢复之后，才能把它设为项目下次启动时使用的环境。

一种可采用的保存流程是：

1. 暂停同一环境上的其他修改，确认安装进程及其后续配置已经完成。
2. 按快照实现的要求，完成写入刷新，并取得一致的文件系统视图。
3. 生成新快照，保存其数据与元信息，检查它已经能够被恢复。
4. 把新版本标记为可用，再原子地切换项目的当前版本。

单独调用一次 sync 不会阻止其他进程继续写，也不保证跨多个存储的一致性。如果软件还在修改文件，需要先让相关写入停下来，或使用平台提供的协调机制。快照内部完成的原子性范围，也应由具体实现说明。

如果第三步失败，下次启动仍使用上一次保存成功的环境。这样不会把半份快照交给下一次启动，但尚未保存的新安装也不能保证回来。因此，产品需要区分“本次安装可用了”和“环境已保存，可以重建恢复”。如果承诺每次安装成功后都能恢复，就必须把保存完成纳入这次操作的成功条件；允许任意终端命令时，则还需要明确的环境保存点或受控修改入口。

4.3. 快照记录不能只有一个文件地址

管理服务需要在实例之外保存项目与环境版本的关系。可以在数据库中记录当前使用哪一版环境，每个版本关联以下信息。

并发保存时，还需要检查当前版本和写入所有权。保存任务开始时记下项目使用的环境版本，更新时确认它没有被其他任务替换，且自己仍持有有效写入权，再切换到新快照。检查与切换需要原子完成，避免超时后继续执行的旧任务覆盖已经发布的新环境。

NAS 工作区不随 RootFS 快照一起回退。如果还希望把代码与环境一起回到过去，就要额外保存代码提交或工作区版本，并协调两者的对应关系。只记录工作区标识，找到的仍然是同一个目录，并不代表这个目录在历史时刻的内容。

5. 三种方案放在一起看

三种方案都能保存文件，区别在于保存范围和恢复方式。

手机上可左右滑动查看完整对比。

表里的“可以覆盖”有前提：保存的文件范围完整，元数据正确，并使用兼容的恢复环境。外部服务状态、进程内存、单独挂载的数据卷，不会因为保留 RootFS 就全部跟着保存。

性能也需要按用户真正等待的路径来测。目录方案要看挂载后访问文件的成本；保留磁盘要看重新挂载与启动的时间；快照方案则要看生成、传输、恢复，以及恢复后第一次真正使用软件的时间。延迟加载可以把一部分恢复工作推迟到首次读文件，单看“实例启动完成”容易漏掉这部分等待。

这次回顾没有三种方案在同一负载下的耗时和费用实测，因此不能给出谁快多少的排名。更适合先按需求缩小范围：固定工具链与可控目录优先考虑持久卷；需要频繁继续使用同一套环境，可以评估保留磁盘；需要释放原实例、回滚或从同一环境分出多个副本，快照提供的版本能力更直接。

三者也可以组合。例如，活跃项目保留磁盘，长期不活跃时归档为快照；源码继续放 NAS，构建缓存留在可丢弃的本地盘。

6. 放回我们的 FC 架构，怎样接入

6.1. 现有实现保存到了哪一层

现有实现把 NAS 挂到项目工作区；恢复时，根据保存的记录选择镜像和运行配置，再创建实例。部分配置变化还会触发旧实例删除与重新创建。

这条创建、恢复链路没有携带每项目的 RootFS 快照或持久系统盘标识。基础镜像预装的工具会随镜像重新出现，用户在旧实例中临时安装的软件则没有相应的恢复步骤。FC 文档也说明，自定义容器的可写层随容器销毁而删除。FC 自定义容器

目前能从代码中确认的，是公共工具预装、NAS 工作区，以及本地项目依赖的重新准备。项目级环境磁盘、RootFS 快照和下面的派生镜像流程，仍属于这里讨论的设计，不能据此声称已经上线。

6.2. 继续使用 FC，可以先约束可保存的安装

如果暂时继续使用当前的 FC 运行方式，又无法取得和恢复容器的完整可写层，可以把可持久化的安装收敛为声明式配置：记录项目需要哪些系统包、版本和来源，再构建一份项目专用镜像。

例如，用户通过受控入口增加 Graphviz，平台记录基础镜像 digest、发行版与软件源、包名和版本。构建任务在隔离环境中生成派生镜像，验证后推送到镜像仓库，再把项目的环境镜像指针切换过去。下次重建时，创建逻辑使用这个 digest。

软件源也要纳入设计。只记一个包版本，如果上游已经不再提供对应包，仍可能构建失败。长期重建需要可保留的包来源、仓库快照或构建产物。已经构建成功的镜像可以复用，不必在每次启动时重新下载和安装。

这种方式保存的是明确声明并成功构建的环境。用户随手修改 /etc，或者运行一个会改动多个位置的安装脚本，不能仅靠记录命令就完整恢复。允许的包管理入口、额外配置文件和安装脚本范围，需要作为产品能力明确下来。

它是现有平台约束下的一条接入路径，与前面的 RootFS 快照有不同的保存语义。构建失败时也不能先更新项目镜像；应该保留上一版可用环境，并说明这次修改尚未持久保存。

6.3. 完整环境持久化需要运行平台配合

如果产品要让用户自由安装系统软件，并在实例重建后继续使用，就应选择能保存完整环境的运行平台，或者自行提供磁盘与快照能力。这已经涉及 Sandbox 创建和回收的接口，工作区里的脚本无法单独完成。

创建接口需要接受环境版本，保存接口需要返回可恢复的磁盘或快照标识，删除接口则要区分“释放这次计算”和“删除项目环境”。恢复完成后，确认软件真正可用，再让 Agent 继续执行任务。

对应的回收也要分开：本地缓存可以随实例删除；项目当前环境不能被普通实例清理顺手删掉；旧快照只有在不再被项目、恢复任务和派生版本引用时，才能回收。还要设置容量配额，并在写入时返回明确错误，避免用户安装了很大的软件以后，环境迟迟无法保存。

环境快照也不宜包含运行时注入的临时凭证。凭证应放在独立的临时挂载或注入机制中，恢复时重新取得，而不是把一个可能过期的访问令牌随环境版本长期保存。

7. 怎样确认软件确实保住了

验收不能只看“Sandbox 又启动了”。对于开头的例子，应在新实例中执行 dot，实际生成一张图，同时检查包管理器记录、安装配置和工作区文件。

下面是选型时应执行的验证场景，并非本次已经完成的测试结果。

性能测试则应固定基础镜像、软件集合和修改量，分别记录保存耗时、保存大小、冷恢复时间，以及第一个真实命令的完成时间。只有这些数据齐全，才能把方案能力、用户等待和存储费用放在同一张表里比较。

8. 环境留下来了，基础镜像怎样升级

持久化解决了安装结果丢失，也带来了下一个问题：公共基础镜像升级以后，用户保存的旧环境要怎样跟上。

一个项目可能在原基础镜像上安装了很多包。直接换成新版基础镜像，再覆盖旧环境的差异，可能混入两版系统库，甚至把已经修复的旧文件重新盖回去。因此，环境版本需要绑定基础镜像，升级应当是一次可验证的迁移。

声明式环境可以尝试在新镜像上重新构建；保存了任意文件修改的环境，则需要更谨慎地迁移和验证。可以先创建一份新环境，运行项目的真实任务，成功后再切换，并保留旧版本作为回退点。

到了这一步，平台管理的已经不只是一个会启动和销毁的 Sandbox，还包括用户逐渐积累起来的开发环境。它需要明确的保存点、版本和升级过程。这也是持久化方案选定以后，下一步要继续解决的事情。

文中实现状态截至 2026 年 10 月 13 日；项目级环境持久化流程为方案设计。

2026 年 4 月 6 日，测试环境两次新项目准备的平均耗时是 6.66 秒，负责推送的 push_remote 步骤平均用了 2.90 秒，占约 43.6%。沿着这次推送继续看，Gitea 服务端的仓库目录挂在 NAS 上，文件存储由此进入了排查范围。

后面我们又测了不同文件系统上的依赖安装和构建，遇到了“包已经缓存，安装仍然很慢”的问题。这篇文章从 Git push 开始，沿着这些测量与实现，讲到 NAS 选型，以及本地盘上的依赖和编译。

1. 先从一次 Git push 看起

1.1. 新项目为什么先要推送代码

当时的新项目初始化流程，会先把模板解压到 Sandbox，创建本地 Git 仓库并提交初始代码，再推送到 Gitea。Gitea 是保存项目 Git 仓库的服务，后续可以从这里取得已经提交的版本。只有这套准备流程完成，项目才能继续使用。

我们在预热流程，也就是 warmup 中记录了各步骤耗时。下面两条是 2026 年 4 月 6 日测试环境的成功样本，均为新项目的模板初始化路径，时间单位为秒。

占比按未四舍五入的原始时间计算，平均行使用两次推送耗时之和除以两次总耗时之和。这是两个现场样本，不代表长期平均延迟。

init_git 包含建仓、配置提交身份、git add 和 git commit，这两次只花了约 50 毫秒和 47 毫秒。随后的 push_remote 则用了约 2.9 秒，等待主要集中在后一步。

这两个步骤都从沙箱代理服务发起远程执行开始计时，直到脚本返回。push_remote 执行初始代码推送，包含远程执行开销、Git 客户端处理、网络和服务端等待；前一步的本地提交不算在里面。因此，不能把它直接当作纯网络上传时间，也不能拿新项目首次提交的结果代表任意大小仓库的提交与推送。

1.2. 推送在等待什么

Git push 会向远端发送它尚未拥有的对象，并请求更新分支引用。服务端需要接收相关对象，检查这次更新是否允许，再让目标分支指向新的提交。Git push、服务端 receive-pack

因此，客户端在等待推送结果时，等待的内容还包括服务端对仓库的处理。如果仓库保存在网络文件系统上，这条路径就涉及服务端的文件操作。

当时检查 Gitea 部署配置，确认 /data 挂载了 NAS，其中保存 Gitea 的仓库数据。这条线索把存储纳入了排查，但还不能把那 2.90 秒全部归因于 NAS：我们没有在这两个样本中继续测出网络、客户端和服务端 I/O 各占多少。

接下来需要区分两个存储位置：Gitea 保存已经提交的 Git 版本，Sandbox 工作区保存当前正在修改的工程文件。 它们都可以使用 NAS，但访问发生在不同位置，优化其中一处，不会自动改变另一处。

1.3. 工程工作区也需要持久保存

Agent 在 Sandbox 中修改代码、安装依赖，再执行构建。Sandbox 是承载这些操作的隔离执行环境，里面有项目目录、Node.js 和构建工具。用户下一次回来继续修改时，执行任务的容器可能已经换了一个。

源码需要跨实例保存。例如，Agent 给游戏增加了暂停菜单，修改了 src/menu.ts，还增加了一个依赖。容器回收以后，这次修改和对应的依赖版本都需要保留下来。

后来的 NAS 工作区方案，把网络文件存储通过 NFS 协议挂载到 Sandbox 中。挂载以后，程序仍然通过普通目录访问它。新容器挂载同一个项目目录，就可以继续处理原来的工程，包括尚未提交到 Git 的修改。

这个布局很直接：源码、package.json、锁文件、node_modules 和 dist 都在同一个工程目录里，现有工具基本不用调整。持久化的问题解决了，安装和构建也随之使用了网络文件系统。

读取一个依赖文件，可能先要查找目录项、确认权限、读取文件属性，然后才是内容。客户端会缓存一部分信息；缓存未命中或需要向服务端确认时，这些操作就要经过网络。对于包含大量小文件的 node_modules，文件总量不大，也可能有很多次访问。

1.4. 第一个方案：换一种文件系统

既然安装和构建都在 NAS 上，首先可以尝试改善这条存储路径。这样不需要调整工程目录，也不用让包管理器适应新的布局。

阿里云的 NAS 有多种规格。按目前的产品划分，通用型包含容量型、高级型和性能型，极速型又分标准型与高级型。各类产品提供的容量、时延、吞吐和 IOPS 规格不同，选型需要结合项目的实际操作。通用型 NAS、极速型 NAS

CPFS 也进入过我们的测试范围。不过，文件系统的性能只是选型的一部分，还要看 Sandbox 能否接入。当时 Sandbox 使用函数计算 FC，可以配置 NAS 挂载；CPFS 实验则需要先创建协议服务与导出目录，再在 ECS 上安装 CPFS-NFS 客户端并挂载导出的路径。接通 ECS，并不等于可以直接把 FC 的 NAS 地址换成 CPFS。FC 存储选型、CPFS-NFS 挂载说明

接下来需要回答的，就是换存储到底能改善多少。连续读写大文件的吞吐，不能直接换算成安装几万个依赖文件需要的时间，因此我们拿已有的前端模板执行安装和构建。

2. 换了文件系统，构建快了多少

2026 年 6 月 12 日，我们用四种前端模板做了两轮测试，表中分别记为 2D、3D、Empty3D（空的 3D 工程）、Canvas。以下时间均为秒。

这一轮测的是工程目录中的 npm install 和 npm run build，与前面的初始 Git 推送是不同负载。现有记录没有 Git push 在各文件系统上的同口径对照，下面的数据只用于比较安装和构建。命令也保留当时的 npm 口径，不改写成后来的 pnpm 生产流程。

2.1. 第一轮：容量型反而安装得更快

NAS 测试使用新加坡区域的 ecs.c9i.xlarge，4 核 8 GiB，Node.js 22.16.0、npm 10.9.2。每个项目先安装依赖，再连续构建三次。CPFS 随后补跑，也使用 Node.js 22.16.0、npm 10.9.2。

下面是第一轮记录。这轮 NAS 测试共用了 ECS 本地的 npm 缓存，性能型先跑，容量型后跑，安装条件并不完全一致。

2D 的结果最明显：容量型安装用了 16.911 秒，性能型用了 29.924 秒。检查测试过程后，发现 npm 缓存保存在 ECS 的 /root/.npm，后测的一组能够复用前面下载过的内容。

因此，这两行数字不能直接证明容量型更快。缓存是已经确认的干扰因素，但没有单独控制它做实验，也无法判断这约 13 秒的差异有多少由缓存造成。CPFS 的补跑同样没有满足后来要求的完整隔离条件。

构建数据也需要分开看。两个 NAS 的中位数比较接近，例如 3D 是 1.993 秒和 1.928 秒，Canvas 是 0.982 秒和 0.972 秒。每组只有三次连续执行，还不足以作稳定的性能排名；首次 build 紧接着安装，也不等于清空文件缓存后的冷读测试。

这轮先暴露出来的是测法的问题。要继续比较文件系统，得让每一组从独立环境开始。

2.2. 第二轮：隔离环境后再测

第二轮改成“文件系统类型 × 项目”各用一台新 ECS、一套新文件系统，避免共用 npm 缓存。规格也调整为更接近当时 Sandbox 的 2 核 4 GiB：ecs.c9i.large、Ubuntu 20.04、Node.js 22.22.3、npm 10.9.8，NAS 使用 NFSv3 挂载。

CPU 和软件版本与第一轮不同，所以这一轮内部比较，不能拿两轮数字计算升级收益。

有些组合没有跑完：Empty3D 在两种 NAS 上都遇到 npm install 的 ERESOLVE 依赖解析错误，项目本身声明使用 pnpm，直接以 npm 安装并不完全符合原来的依赖约束；CPFS 独立组合则停在资源与挂载准备阶段。它们没有有效构建时间，也不能用第一轮的 CPFS 数字补上。

极速型 NAS 没有参加这两轮测试。全部阶段记录，包括三次 build 和失败退出码，保留在测试数据 CSV 中。

2.3. 安装仍然占了大头

这六组成功结果，没有显示出换成性能型 NAS 后各个项目都明显变快。更值得继续追的是时间分布：2D 在容量型上的安装占“安装＋首次构建”的约 85%，3D 对应约 88%。

即使只看 2D，把 5.66 秒的编译继续压缩，前面的 31.93 秒安装仍然存在。要缩短用户等待的时间，需要继续拆解依赖准备。

安装依赖会下载包，因此一个直接的方案是预热包缓存，尽量离线安装。我们后来的镜像已经这样做了，但工作区中的 node_modules 仍在 NAS 上。接下来的问题变成了：包内容已经在本地，安装还需要做哪些文件操作？

3. 包已经缓存了，安装还在做什么

3.1. 缓存与依赖树是两个位置

安装大致包含读取包与锁文件、获取包内容、建立项目依赖树，以及执行安装脚本几个过程。缓存能够复用包内容，项目自己的依赖目录仍然需要准备。

以 pnpm 为例，需要区分三个位置：

• 内容存储 store：保存可以复用的包文件；
• 项目的 node_modules/.pnpm：项目使用的依赖文件和目录布局；
• node_modules 中的链接与入口：让程序按照依赖关系找到模块。

pnpm 使用内容存储和链接组织依赖。建立和读取项目依赖树时，仍然要操作项目目录；store 与项目分属不同文件系统时，也不能假定跨文件系统硬链接总能成立。pnpm 依赖目录结构

8 月检查构建链路时，镜像里的预热 store 已经在本地盘，安装器也支持优先离线安装。但 node_modules 和 .pnpm 还在 NAS。包可以不重新下载，目录创建、文件复制、链接与属性检查仍可能经过网络文件系统。

构建阶段也会反复查找模块、读取 package.json、解析源码，再生成临时文件和 dist。依赖留在 NAS 上时，读取依赖的成本会继续影响构建，只调整输出目录还不够。

3.2. 连查看目录也变慢了

2026 年 8 月 8 日的一次排查，进一步把范围指向了文件访问。工作区确认是 NFSv3 挂载，现场记录中，find 用了约 117 秒，git status 约 166 秒，部分目录扫描超过 60 秒。

这些命令不负责把源码编译成产物。它们也变慢，说明需要检查安装和编译之外共同使用的文件系统路径。

约 42 分钟的现场累计统计中，有下面这些 NFS 请求：

这些是多个操作累计的计数，不是一次安装的调用次数。不过，它们解释了为什么不能只看传输带宽：查目录、检查权限、创建文件，每一步都可能有等待。依赖文件多了，即使单个文件很小，这些步骤也要反复执行。

现场同时存在外部包下载慢的问题，手工执行的 pnpm 命令还曾把 store 建在 NAS 上。下载、缓存和项目目录需要分别检查，已有证据不足以把所有等待都算在 NAS 上。但对于已经确认留在 NAS 的依赖树，可以提出一个更具体的改法：把它移到本地。

4. 先把 node_modules 搬到本地

4.1. 哪些文件可以不持久保存

源码、素材和依赖约束需要保留；node_modules 则可以根据 package.json、锁文件和工具版本重新生成。它被频繁读写，却不一定需要和源码使用同一种存储。

因此，可以让 NAS 继续保存工程，把 node_modules 放到 Sandbox 本地盘。工作区里的 node_modules 变成软链接，工具访问这个路径时，实际读取本地目录。

本地盘的选择还取决于部署环境：有独立 SSD 时，可以把依赖目录放在 SSD 对应的挂载点；只有容器本地临时盘时，也可以验证同样的分工。两者的容量、性能和生命周期需要按实际环境确认，目录叫 /tmp 并不能说明底层一定是 SSD。

4.2. 实验结果：安装改善大，构建改善小

我们在 8 月评审过《低权限环境下 node_modules 本地快盘托管方案》，附录保留了一组 2026 年 6 月的实验。它先在本地目录安装依赖，再通过软链接让工作区使用这份 node_modules。

原实验中，/workspace 和 /scratch 是同一个 NFSv3 文件系统，/tmp 是约 9.9 GiB 的容器本地 overlay，没有独立本地 SSD。下面比较的是 NFS 路径与容器本地路径。

在 431 个依赖的记录里，安装从 166 秒降到 31 秒；Vite build 从 6.05 秒降到 4.29 秒。移动依赖目录影响了两部分，安装阶段的变化更大。构建还包含解析、转换、压缩等 CPU 工作，不能用安装的耗时比代表整个发布流程的收益。

这份附录没有保留完整的 CPU 规格、缓存控制和重复轮数，属于方案验证资料，也不是前面几个模板的同口径复测。它提供了继续实现本地依赖目录的依据，生产项目的具体收益还需要重新测量。原记录见方案文档的实机验证附录，revision 7。

4.3. 软链接又被安装器删掉了

有了这组结果，接下来的工作是把目录布局接入现有工具。最先遇到的限制，就在依赖安装本身。

假设目录是这样的：

/workspace/game/node_modules
    → /local/game/project/node_modules

软链接保存目标路径，但包管理器不一定保留它。补充实验中的 npm 11 在安装的 reify 阶段发现 node_modules 是软链接，会移除它，再在原位置创建目录。于是，看起来已经搬到本地的依赖，又写回了 NFS。npm ci 也明确包含先清理既有 node_modules 的行为。npm ci 的行为说明

要保留本地布局，安装命令应当直接在本地工程目录执行，成功以后再由平台建立工作区链接。处理已有依赖目录前，还需要确认它属于可重建数据，并停止正在使用它的进程。

构建工具有另一类限制：部分框架检查工程根目录与依赖的实际路径，外置依赖可能触发“超出文件系统根目录”的错误。只挪 node_modules，源码和依赖仍分处两个工程根，这套结构并不一定适合所有工具。

因此，下一步把源码副本也放进本地，让源码、依赖和构建命令位于同一个工程根。NAS 继续保留原工程，本地副本负责执行这一轮构建。

5. 在本地准备一个完整工程

5.1. 两份目录如何分工

本地工程副本需要源码，但不负责替代 NAS 保存用户修改。每次构建前，从 NAS 同步本轮输入；依赖安装、临时文件和编译都在本地完成；构建成功后，再把产物交回持久层。

同步时排除 NAS 上的旧 node_modules、旧 dist 和无关运行目录，避免把大量可重建文件复制回来。源码中的删除也要同步，否则已经从 NAS 删除的旧文件，可能继续留在本地参与编译。

如果一个 Sandbox 承载多个项目，本地目录还要按项目隔离，防止它们修改同一份依赖。整个本地副本的生命周期跟随当前实例，实例回收后可以重建。

5.2. 一个 npm 项目怎样执行

下面用 npm 展示最基本的过程。假设项目已有有效的 package-lock.json，构建期间没有并发修改，输出目录是 dist。本地目录每次新建，暂不考虑缓存复用。

workspace=/workspace/game
local_root=$(mktemp -d /tmp/game-build.XXXXXX)
local_project="$local_root/project"
mkdir -p "$local_project"

# 同步构建输入，跳过可以重新生成的内容。
rsync -a \
  --exclude='/.git' \
  --exclude='/node_modules' \
  --exclude='/dist' \
  --exclude='/.combos' \
  "$workspace/" "$local_project/"

# 安装和构建都从本地工程根开始。
(
  set -e
  cd "$local_project"
  npm ci --cache "$local_root/npm-cache"
  npm run build
)

产物出现在 $local_project/dist。平台检查命令退出状态与产物后，再把它交回持久层。这个示例说明目录关系，没有包含并发锁、缓存复用和发布过程。

已有项目使用 pnpm 时，应保留原来的锁文件与版本。采用本地目录，并不需要改用 npm 重新解析依赖。我们实际的主路径使用 sandbox-pnpm-install，先尝试离线安装，缺包时按策略联网补齐。

monorepo、本地 file: 依赖，以及会访问相邻目录的安装脚本，还要求同步完整的依赖范围。复制工程时需要保持这些相对关系，不能只带走一份 package.json。

5.3. 接入原来的构建入口

实现时，我们把本地 I/O 接入了依赖安装和构建两个统一入口，分别由 sandbox-pnpm-install 和 sandbox-build 负责，已有的持久工作区与后续发布流程继续使用。

依赖准备先检查本地目录是否可用、空间是否足够，再同步输入和安装。成功后，将工作区的 node_modules 链接到本地依赖目录。构建入口核对依赖状态，刷新源码，然后从本地工程根执行原来的 build.sh。

部分旧项目的 build.sh 会再次执行 npm ci 或 pnpm install。统一入口已经准备过依赖，如果脚本再来一遍，就会重复安装。因此，当时为这次构建进程加入命令包装，跳过约定中的重复安装命令；run build 等其他调用继续交给原来的包管理器。这项兼容处理限定在已有构建协议内。

编译成功后，先把本地 dist 复制到 NAS 的暂存目录。复制完成，再将它重命名为本次产物目录，后续上传、Git 提交和版本记录继续走原流程。

这里要分别处理编译失败和回写失败。编译失败，本轮没有可上传的结果；回写失败，即使本地编译已经完成，也还没有把产物交给发布流程。构建入口会清除旧输出，防止上传器在本轮失败后误用上一次的 dist。

暂存目录让消费者不会读到复制了一半的产物，但“编译、上传、版本发布”仍然是多个步骤，并没有组成一个文件系统事务。最终预览还要等后续发布完成。

5.4. 哪些修改需要写回

本地副本带来了一个新的边界：在本地改了文件，不代表用户的持久工程已经变化。

普通构建根据现有锁文件准备依赖。用户要求增加或删除依赖时，package.json 与锁文件的改动需要保存到 NAS，成为下次恢复的输入；只更新本地 node_modules，换一个实例就会丢失这次变化。

因此，修改依赖要作为单独的操作处理，检查并写回对应文件；写回前还应确认原文件没有被其他操作更新。构建脚本如果会生成需要长期保存的源码，也要约定这些文件的写回范围，不能将整个本地副本直接覆盖回 NAS。

到这里，安装和编译已经有了统一的本地执行路径，NAS 上保留的是持久输入与完成后的产物。但还有一个条件需要处理：本地目录只属于当前实例。用户下一次继续工作时，NAS 上的成功记录可能还在，本地文件却已经不在了。

6. 实例换了，依赖怎样恢复

6.1. 成功记录与真实目录

假设原实例已经完成依赖安装，NAS 保存了成功标记。原实例被回收后，新实例挂载同一份 NAS，可以看到旧记录，但没有原实例的本地依赖。

软链接也可能保存在 NAS 上。容器更换后，链接文件仍在，它指向的本地目录却不存在。只检查链接或“安装成功”状态，都会漏掉这个情况。

实际实现判断依赖是否就绪时，会一起核对记录是否属于当前实例、package.json 与锁文件的摘要、本地依赖目录、pnpm 布局标记，以及软链接是否指向当前目录。条件不满足，就重新建立本地副本、安装依赖、修复链接，再更新当前实例的记录。

Node.js 与包管理器版本也需要固定。如果以后把依赖缓存扩展到跨实例共享，还要考虑操作系统、CPU 架构、Node ABI 等兼容条件，尤其是包含原生扩展的包。当前实例内的一份成功记录，不能直接扩展成跨机器复用的依据。

6.2. 恢复过程还会并发执行

异步预热和用户触发的构建可能同时准备依赖。如果只给安装加锁，两个进程仍可能在前面的同步阶段相互干扰：一个正在准备本地布局，另一个同时删除或替换其中的文件。

为此，锁需要覆盖共享目录的准备过程，让源码同步、依赖安装和状态更新按照约定执行。

本地环境不可用时，还需要回到原来的 NAS 工作区。回退不能只切换工作目录：如果 node_modules 仍是指向已消失本地目录的链接，继续安装可能出现 ENOTDIR。因此，回退时还要处理失效链接，让依赖重新安装到可用的工作区目录中。

长时间保留实例时，还要限制缓存占用。检查容量也需要关注可用 inode：剩余字节足够，并不保证还能创建大量文件。

7. 下一步：重新测量完整构建

回看已有数据，可以确认两件事：当时测过的容量型与性能型 NAS 没有给所有模板带来一致的明显改善；补充实验把依赖放到本地后，安装耗时变化远大于构建耗时变化。沿着这个方向，我们把本地执行接入了统一安装、构建与恢复流程。

不过，现有测量还缺少最终生产链路在同一条件下的完整前后对照。前面 166 秒降到 31 秒的数字，不能直接作为这套完整方案的上线收益。

本地副本减少了安装与编译中的网络文件操作，也增加了源码同步和产物回写。因此，下一轮计时需要覆盖：等待执行、同步输入、依赖准备、实际编译、产物回写，以及后续上传和验证。否则，单看本地 build 变快，仍然无法判断用户少等了多久。

测试场景也要分开：新实例首次构建、同一实例重复构建、只修改源码、修改依赖，以及实例丢失后的恢复。每组固定代码、锁文件、工具版本和计算规格，记录缓存条件，核对最终发布的产物。

这样才能继续回答下一个问题：依赖和编译移到本地以后，整条链路中最长的等待又落在了哪里。

本文讨论两种部署方式：由中心服务运行 Agent，通过远程接口操作工程；或者把 Codex 放进 Sandbox，由沙箱内的引擎直接操作工程。下面分别介绍它们的组成、数据存储、执行过程，以及中断后的恢复方法。

1. 总体结构

先说明本文中几个组件的含义：

• Runtime：组织模型调用、工具执行和上下文更新的程序；
• Sandbox：隔离的执行环境，包含工程目录，以及读写文件、运行命令所需的程序；
• 模型 API：接收上下文，返回文本或工具调用请求；
• 平台服务：接收用户需求，管理项目、任务、权限、预算和交付结果。

这几个组件可以有不同的部署关系，如下图所示。

中心服务方案中，Runtime 调用模型，解析模型提出的工具请求，再通过远程接口让 Sandbox 执行。模型拿到工具结果后，继续决定下一步操作。Runtime 可以部署多个实例，分别执行不同任务。

沙箱内 Codex 方案中，平台把任务交给 Codex，由它完成这段循环。文件和命令就在 Codex 所在的环境中，可以直接访问。这里放进沙箱的是执行程序，模型推理仍然可以使用远端 API。

两种方案都需要平台，也都可以扩容。它们主要区别在于：模型调用与工具执行之间的循环，由中心进程维护，还是由沙箱内进程维护。

运行时是否自研，是另一个选择。中心服务可以接入现成引擎，沙箱里也可以运行自研 Agent。本文用我们现有的中心 Runtime 说明第一种方式，用沙箱内 Codex 说明第二种方式；后者按参考架构讨论。

2. 中心服务

2.1. 接收任务与分配执行

假设用户提交一个需求：“给游戏增加暂停菜单”。接入服务需要先确定用户、项目和工作区，检查权限与预算，再创建运行记录。

我们将一次用户需求对应的运行称为 Run。Runtime 的工作实例称为 Worker。接入服务把 run_id 交给任务队列，空闲 Worker 领取任务后，从数据库读取运行信息，开始执行。

数据库写入和队列派发之间，存在一个需要处理的间隙：任务已经保存，但进程在发送队列消息前退出，任务就可能一直无人执行。

一种实现方法是在同一事务中保存 Run 和待派发记录，再由后台程序将待派发记录送进队列，这就是 Outbox。发送失败时重新发送；Worker 收到重复通知时，通过数据库条件更新领取任务，避免多个实例同时取得执行权。

用户重复点击提交，也需要单独处理。接入请求可以携带稳定的请求编号，相同请求再次到达时返回原 Run。这个编号表示用户的一次提交，与 Worker 后续重试的编号不同。

2.2. 运行记录

中心服务首先要区分三种对象：

• Thread：会话，关联多轮对话及其工程；
• Run：一次运行，对应本轮用户需求；
• Attempt：一次执行尝试，记录这次由哪个 Worker 执行，以及如何结束。

例如，同一个会话里“增加暂停菜单”和“修改菜单颜色”是两个 Run。第一个 Run 执行到一半，Worker 重启后由另一实例接管，则会产生新的 Attempt，但仍属于原 Run。

我们的中心运行时使用 threads、agent_runs、agent_run_attempts 和 messages 保存相应记录。运行配置和恢复所需变量也随 Run 保存，恢复时使用原任务的输入。

围绕一次运行，持久存储至少需要覆盖以下内容。这里按用途列出逻辑记录，实际实现可以合并或拆分表。

这些记录可以使用关系数据库保存。编号、状态、归属和时间使用固定字段；模型消息、工具参数等可变内容使用 JSON 字段。按会话、Run 和消息顺序建立索引，便于查询和恢复。

工程文件放在独立的工作区，通过持久数据盘或文件快照保存。工作区包含未提交到 Git 的修改，所以仅保存 Git 提交号并不够。图片、截图、完整日志和构建产物一般进入对象存储，数据库保存引用和校验信息。

Worker 内存中仍然会缓存当前上下文和执行状态，但进程重启后，继续任务所需的数据应当能从这些存储中取回。

2.3. 消息与上下文

消息历史和模型上下文有不同的用途。

消息历史记录已经发生的对话和操作，用于展示、排查与恢复；上下文是下一次实际发给模型的输入，除了消息，还包括本轮指令、工程规则和工具定义。

工具定义描述名称、用途和参数格式。例如命令工具需要命令与工作目录，文件工具需要路径。模型根据这些定义提出调用，Runtime 再交给对应的执行代码。

图中的消息包含以下信息：

• message_id：消息编号；
• run_id：所属运行；
• role：用户、模型或工具等消息角色；
• tool_call_id：工具调用与结果的关联编号，普通消息可以没有；
• content：文本或结构化内容。

上下文长度有限，不能无限追加全部历史。任务较长时，可以把较早的历史整理成摘要，保留继续执行所需的原文，再追加新的消息。压缩完成后保存的记录，称为上下文检查点。

图中较早的消息已整理进检查点，后续新消息仍单独保存。恢复时先加载检查点，再按顺序追加它尚未覆盖的消息。因而检查点既要保存整理后的历史，也要保存覆盖位置；只留下摘要，无法确定哪些消息已经包含在内。

工具调用和结果还需要符合所用模型的消息协议。压缩时保留必要的关联，尚未确认完成的操作也要保留真实状态，避免后续把“已提交”理解成“已完成”。

我们的实现中，prompt_checkpoints 保存压缩后的历史及覆盖边界，runtime_context_snapshots 按会话和 Agent 保存最新的模型可见上下文。前者用于接续，后者便于检查当前输入。

两者分开还有存储上的原因。假设每一步都向历史表追加一整份上下文，前面的内容就会反复写入。原始消息顺序追加、压缩时保存检查点、最新快照覆盖更新，可以减少这种重复。

2.4. 工具调用过程

Runtime 收到模型输出后，需要区分普通文本和工具调用。以运行测试为例，一次工具调用的过程如下：

1. 接收完整的工具名称和参数；
2. 检查工具是否可用、参数是否合法，以及任务是否有操作权限；
3. 保存本次工具操作，分配可查询的调用编号；
4. 调用 Sandbox 的执行接口；
5. 保存执行结果，与原工具调用关联；
6. 将结果加入上下文，发起下一次模型请求。

工具参数可能通过流式响应逐段到达。执行层需要等完整参数形成后再调用，不能把半段命令提前交给沙箱。

工具也有两种常见去向。读文件、改代码、运行命令进入 Sandbox；素材生成、扣费、版本发布进入各自的业务服务。后者的操作状态由业务服务保存，Runtime 留下查询它们所需的编号。

2.5. 命令执行会话

读取文件通常很快完成，命令则可能持续很久。测试运行几十秒，开发服务器还可能一直不退出。工具接口等待一段时间后先返回时，需要同时说明命令是否仍在执行。

命令启动后，执行服务返回会话标识，通过它找到对应的沙箱和进程。后续请求使用同一标识，继续读取新增输出、发送输入，或者中断进程。进程结束时再返回退出码。

我们现有的 exec_command 由中心 Runtime 调用 SandboxProxy，再由沙箱中的执行服务启动命令。后续通过 write_stdin 等接口访问原会话。它们采用 Codex 风格的工具接口，这条链路中的 Agent 主循环仍在中心 Runtime。

输出量也需要控制。短输出可以直接进入工具结果；长日志分段返回，并注明是否截断，必要时附上完整日志引用。否则一次构建就可能把后续模型输入占满。

2.6. 中断与恢复

Worker 重启时，Sandbox 中的命令可能还在运行。新 Worker 读取运行、消息和工具记录后，应当先查询原执行会话：

• 进程仍在运行：继续读取输出，等待结果；
• 进程已经结束：取回退出码和剩余输出；
• 会话或沙箱已经丢失：根据操作性质决定是否重新执行；
• 状态暂时无法确认：保留未知状态，继续查询或安排核对。

测试一般可以重跑，发布和付费操作则需要查询原操作、确认幂等条件，不能统一按失败重试。

接管还需要处理旧 Worker 恢复连接的情况。任务可以使用带有效期的租约表示执行权，由 Worker 定期更新心跳。接管时生成新的执行编号，后续数据库写入校验这个编号，拒绝旧执行者的更新。

但数据库的校验不会自动停止旧进程修改工程。同一个工作区需要单独保证写入者唯一，或者为不同执行尝试使用独立副本。交给新执行者之前，要确认旧进程已经停止或失去写入权限。

至此，中心运行时需要维护的主要部分就包括：运行记录、模型上下文、工具协议、远程进程，以及这些状态的恢复。

3. Sandbox 内运行 Codex

3.1. 接入结构

把 Codex 放进 Sandbox 后，平台仍然接收用户需求、创建 Run，并保存项目、权限和预算。执行时由平台分配沙箱，再将任务交给其中的 Codex。

平台与引擎之间通常还需要一段接入程序。这里称为 Runner，主要负责：

• 启动引擎，传入任务与运行配置；
• 继续原会话，传入用户的补充输入；
• 接收引擎事件，回传进度和结果；
• 处理中断，管理引擎及相关命令进程。

Codex 提供 SDK 和命令行入口，可以启动、继续或恢复会话，也可以输出结构化执行事件。具体采用哪种方式，需要与选定版本一起验证。Codex SDK、codex exec。

普通文件读写和命令执行在沙箱内部完成。平台原来围绕模型维护的上下文组织、工具调用循环，转由引擎处理；平台与执行侧的主要接口变为任务、补充输入、事件和控制指令。

3.2. 数据保存

执行程序移入沙箱后，数据也会分布在不同位置。

平台需要把 run_id、attempt_id、sandbox_id、工作区编号和 Codex 会话编号关联起来。用户继续修改时，据此找到原工程与会话；沙箱替换时，据此确定恢复哪份状态。

Codex 状态目录需要按照固定版本的实际要求保存。聊天文本导出未必包含恢复所需的全部索引和执行状态。不同项目还应使用隔离的状态目录与工作区，避免引擎找到另一项目的文件或会话。

3.3. 任务执行与事件回传

一项任务进入执行阶段时，平台先创建或复用沙箱，挂载工作区与引擎状态，准备依赖和范围受限的访问权限。Runner 接收启动指令后，创建新会话或继续原会话。

这里需要分别处理启动指令和执行事件的重试。

平台发送启动指令后没有收到确认，Runner 可能已经启动了引擎。启动指令因此需要稳定编号，Runner 保存已接受的指令，平台重连后查询原执行。否则一次网络超时就可能启动两个 Codex 进程。

事件回传也可能断线。Runner 可以按 Run 和 Attempt 为事件编号，暂存尚未确认的事件；平台保存后返回确认，重连后从最后确认位置继续传递。平台按照事件编号去重，客户端也可以从已接收位置补读。

这里重传的是执行记录，接收方不会因此再执行一遍工具。沙箱本地暂存只能应对短暂断线；如果连磁盘一起丢失，未同步出去的事件仍然会丢失，关键恢复记录需要及时保存到外部存储。

3.4. 沙箱回收与恢复

沙箱重新创建后，文件、会话和进程需要分别处理。

继续用暂停菜单的例子：Codex 修改了源码并启动测试，随后沙箱丢失。恢复时先准备新环境，取回源码和未提交修改，再加载原会话。原测试进程通常已经不存在，确认可以安全重跑后，重新启动测试。

文件与会话的保存位置不同，保存时间也可能不同。会话已记录“修改完成”，文件快照却来自修改前，后续执行就会基于错误的工程状态。可以在相关工具动作结束后，为工程快照、会话状态和事件确认位置保存关联检查点；无法保证一致时，恢复流程需要检查实际差异。

开发服务器、终端和网络连接属于运行中的进程状态。即使会话与文件都恢复了，也需要重新检查这些进程是否存在，并按需启动。

我们的沙箱代码中，有一套可选的本地文件读写方案：依赖与构建尽量使用本地磁盘，源码保存在持久工作区，最终产物再写回。该方案默认关闭，需要配置启用。这里区分的正是可重建数据与需要保留的任务成果。

沙箱分配方式也影响恢复成本。按项目保留环境，可以复用依赖和预览进程，同时需要处理空闲资源、残留进程和并发写入；按任务新建环境，清理比较直接，但每次要准备依赖并恢复工作区。

引擎与镜像版本同样要固定并记录。升级前验证原会话能否继续、工具行为是否变化。重新分配执行者时，仍需处理旧租约、旧进程及工作区写入权限。

4. 业务工具

4.1. 请求已执行，但响应丢失

两种部署方式都会调用素材、费用和发布等业务服务。这类调用存在一种情况：服务已经接受请求，Agent 却没有收到响应。

例如素材服务创建了背景图任务并登记费用，网络在返回结果时断开。Agent 恢复后若新建一次生成请求，就可能产生第二份任务和费用。

Agent 在第一次调用前保存业务操作标识，素材服务接单时，将这个标识与创建的素材任务关联。这样，即使回复丢失，双方仍然能够找到同一次操作。

同一操作编号和相同参数再次提交时，服务返回原任务，不再执行第二次业务动作，这就是幂等。相同编号携带不同参数则应拒绝或报冲突。编号的去重范围还要结合用户、项目等归属确定。

恢复时按原操作标识查询，可以确认原任务仍在执行、已经结束，还是没有成功提交。不支持查询、也不支持幂等的接口，在断线后可能暂时无法确定结果，应保留未知状态，再按操作性质处理。

4.2. 取消、权限与预算

用户取消任务时，中心 Runtime 或 Runner 可以停止后续模型调用，并中断当前命令。已经交给素材或发布服务的工作，需要另外发送取消请求或确认最终结果。因此，“收到取消指令”和“执行已经停止”需要分别记录。

权限与预算由平台和业务服务校验。平台向执行环境提供有有效期、范围受限的访问权限，下游服务校验项目、操作和额度。恢复任务可以使用原运行配置，但已经撤销的权限仍以当前业务校验为准。

沙箱内程序可访问的文件、网络与凭证，由运行环境限制。长期、跨项目的高权限凭证进入沙箱后，生成的代码也可能读取到。Codex 自身的命令限制和审批策略需要与外层沙箱共同配置。Codex 安全与审批说明。

5. 方案比较

任务以调用业务 API 为主、流程比较明确时，中心服务便于集中组织。任务需要长时间在工程中修改、构建和调试时，沙箱内 Codex 可以复用已有的编码执行能力，减少基础工具适配。

这只是按工作形态做出的判断。比较具体方案时，还需要固定任务、模型和工具条件，检查正常完成率，以及 Worker 重启、沙箱丢失、响应超时和用户取消时的恢复情况。等待时间、重复操作与有效任务成本，应当一起记录。

任务结束时，还需要明确交付了什么。下面是暂停菜单任务的一份简化结果结构。

源码记录说明改了哪些文件；构建记录说明构建是否通过、使用哪份产物；预览记录说明哪个版本正在运行；验证记录说明暂停与继续功能是否符合要求。

我们的一次游戏实验中，部署和健康检查通过以后，多人玩法仍然需要用多个客户端验证。执行器的结束、部署的完成和需求的实现，有各自对应的记录。无论采用哪种部署方式，平台都需要把这些结果关联到原任务。

本文记录我们在实现这条链路时做过的几次调整，依次介绍 Prompt、多 Agent 分工、Skills、工具接口和任务恢复。每一部分说明原来的实现、遇到的问题，以及后续采用的处理方式。原生引擎的接入状态以本文最初整理时为准。

1. 通过 Prompt 组织开发流程

1.1. 初始实现

第一版使用 Python 实现。我们在一份较长的 Prompt 中描述游戏开发过程，包括理解需求、整理策划、准备素材、制作地图、编写玩法、测试和部署。

Prompt 同时提供工程约定：使用什么技术栈，地图采用什么格式，素材怎样加载，最后需要交付什么。模型根据这些信息调用工具，把每一步的结果交给后续步骤。

这套实现的主要作用，是把业务知识和开发步骤放到一个明确的位置，使整条链路能够开始运行。后续增加的规则，则需要区分它究竟在解决哪一类问题。

1.2. 规则对应的问题

例如，模型不知道地图文件的格式，可以补充格式说明；模型启动命令后拿不到剩余输出，需要补充命令会话接口；素材已经生成，恢复任务时却找不到，需要保存素材任务与结果的关联。

这三类问题都可能表现为“游戏没有完成”，但修改位置不同。只有第一类可以直接通过补充知识解决。工具或业务状态没有接好时，增加文字提醒仍然缺少实际的执行依据。

因此，Prompt 中的内容需要能够追溯到具体问题。项目约定和素材能力属于持续需要的业务信息；为了绕开某个模型弱点而加入的固定步骤，则需要在模型更新后重新验证。

2. 多 Agent 分工

2.1. 角色划分

游戏任务变复杂后，我们开始按照能力拆分 Agent：主 Agent 组织任务，开发 Agent 修改代码，配置 Agent 处理地图和音频，素材相关 Agent 生成资源。角色、动画、封面等工作也有各自的入口。

每个 Agent 有自己的 Prompt 和工具集合，能够单独调整。适合独立完成的素材任务，也可以并行执行。

但子 Agent 拥有自己的执行过程，主 Agent 已经知道的信息，需要通过输入显式传过去。任务完成后，结果还要传回主 Agent，才能继续后续工作。

2.2. 上下文交接

以“给角色增加二段跳”为例，开发 Agent 需要读取角色移动代码、跳跃状态、动画和音效的使用方式。如果用户同时要求“保持原来的移动手感”，这条限制也要进入子任务输入。

一次交接至少涉及：

• 本次需要完成的修改；
• 必须保留的行为和用户限制；
• 使用哪个工程与工作区；
• 已经完成的相关工作；
• 返回什么结果，后续由谁接着处理。

我们后来还去掉过主 Agent 的 Bash 入口，把编码进一步交给开发 Agent。这样工具权限更加集中，但主 Agent 需要通过子任务才能检查工程或完成一次小修改。

代码、地图配置和素材接入虽然属于不同专业，却经常共同完成同一个需求。拆开以后，各个 Agent 都需要重新理解相关部分，主 Agent 再整合局部结果。交接遗漏约束、结果不足以判断是否完成，都是需要处理的问题。

因此，角色名称只能说明知识分工，还不足以确定执行边界。是否能够并行、是否需要隔离权限、结果是否容易交接，都需要结合实际任务判断。

3. 主 Agent 与 Skills

第二版将编码能力放回主 Agent，同时通过 Skills 按需提供专业方法。

这里的 Skill 是完成某类工作需要的方法、说明和辅助资源。加载 Skill 后，相关知识进入当前工作上下文；启动子 Agent 则会建立一段独立执行。两者有不同的用途。

处理地图时加载地图格式与操作方法，接入素材时加载对应的资源使用说明。仍然由主 Agent 理解需求、读取工程、修改文件，再检查修改结果。

这样，配置修改和代码修改可以在同一上下文里连续完成。用户刚确认的限制也保留在原会话中，减少了重复组织子任务输入的工作。

独立素材生产、封面制作等任务仍然保留自己的执行入口。这类工作有相对明确的输入和输出，外部执行结束后，可以通过任务编号与产物引用交回主流程。

调整后的分工可以归纳为：专业知识通过 Skill 提供，需要独立权限、生命周期或并行执行的工作，再使用独立任务。这一划分仍然要通过任务完成情况验证。

4. 工具接口与模型上下文

4.1. 工具集的适配

模型接入后，需要同时提供它能够使用的工具。工具的名称、参数、执行行为和结果格式，共同组成调用协议。

我们逐步对齐了 Codex 和 Claude Code 两类基础工具，并按所选模型装配相应工具集。

这里仍由自研 Runtime 组织模型循环。采用 Codex 风格的工具接口，并不表示已经由原生 Codex 执行任务。

以命令工具为例，启动测试以后可能出现三种结果：

1. 命令已结束，返回输出与退出码；
2. 命令仍在运行，返回执行会话编号，之后继续读取输出；
3. 执行出错，返回能够定位原因的信息。

后续还需要通过原会话发送输入、中断命令，以及在 Runtime 重启后重新查询。若命令仍在运行，工具却只返回一段文本，模型就无法判断是等待、重试还是继续修改。

文件工具也一样。读取范围、补丁格式和修改失败的反馈，需要与实际工作方式对应。对齐工具名称之后，还需要逐项检查这些行为。

4.2. 上下文组织

每次模型请求包含本轮指令、工具定义、历史消息，以及新的工具结果。运行时间增长后，需要压缩较早的历史，并保留后续执行所需的信息。

模型切换时，还要重新核对推理参数、工具调用与结果的对应关系，以及缓存条件。例如，把已有历史作为稳定前缀继续追加，和每轮重新排列同一批内容，可能有不同的缓存效果；实际命中情况仍以服务端返回的使用信息为准。

这些内容通常归入 Harness，也就是模型外层组织工具、上下文和执行环境的部分。模型能力变化后，Prompt、工具协议和上下文组织需要一起检查，不能只修改模型名称。

5. 验证与修复流程

5.1. 固定检查流程

我们曾增加一套较完整的质量流程，将用户意图、素材、运行证据、检查和发布串起来。对于“玩法保持不变，场景改成雪地”这类需求，流程需要一直保留修改目标与不变条件。

其中还包含固定检查多个视口，以及开始、胜利、失败、重试等场景。检查得到问题后，再触发修复和重新部署。

问题出在检查范围与当前需求不一定一致。用户只要求手机竖屏时，其他方向的检查可能触发额外修改；每次修改又需要重新运行和部署。实际案例中出现过消耗和等待增加，以及围绕检查结果反复修补的情况。这里是个案观察，不据此给出整体效率结论。

5.2. 按任务确定验证范围

调整后，我们把素材使用、工程接入和预算安排提前到部署前处理。验证仍然保留，但检查范围根据当前需求确定，修复也结合问题影响与剩余预算决定。

以手机竖屏游戏为例，本轮优先检查竖屏的核心游玩路径。其他视口的问题可以记录，但是否必须在本轮修复，需要根据交付范围判断。

这样调整之后，需要保留的记录包括：本轮验收条件、执行过的检查、检查结果，以及决定继续修改或结束的依据。减少固定步骤之后，仍然能够说明最终交付经过了哪些验证。

6. 异步任务与恢复

6.1. 几种不同的执行状态

游戏能力接入 Go 后端以后，会话、执行记录和费用由运行时及业务服务管理。一次游戏生成又包含多个异步过程，不能用单一状态概括。

模型结束一轮输出时，素材可能仍在生成。素材完成以后，需要接入工程；游戏发布完成以后，客户端还需要收到版本信息。系统应当保存这些状态及其所属任务，再组合成用户看到的进度。

否则，模型的一次结束可能被误用为整个任务成功，外部任务已经完成也可能因为消息丢失而一直显示等待。

6.2. 恢复记录

恢复一项工作时，需要读取它所对应的持久记录。

上下文检查点保存整理过的历史和覆盖位置，用于继续模型执行。素材任务记录保存外部任务编号与产物引用，用于查询原操作。事件 Outbox 保存待发送事件，用于失败后补发。用户轮次与运行记录关联，使恢复的结果仍然属于原来的请求。

素材是否成功、费用是否发生、版本是否创建，由对应业务记录确认。模型摘要可以帮助继续理解任务，但不能作为这些操作已经发生的唯一依据。

事件补发也不应重新执行一次素材生成或发布。接收方按事件编号去重，业务操作则使用自己的任务编号或幂等编号，两者分别处理。

7. 原生执行引擎的接入

自研 Runtime 要持续维护模型循环、工具协议和上下文组织。另一种选择是复用原生编码引擎，把业务工具接到已有的执行环境中。

Codex 提供程序化接入方式，Claude Agent SDK 也提供相应的执行能力。Codex SDK、Claude Agent SDK 文档。

我们在这一阶段开始尝试把原生 Codex 接入新的 Runtime，通过适配层连接现有业务服务。

引擎负责读取工程、调用基础工具、修改代码和执行验证。平台继续保存项目、会话和运行关系；素材、费用、版本与交付结果仍由业务服务负责。

适配层需要处理事件转换、取消、继续会话，以及产物接入。即使引擎已经在文件系统中生成了一张图片或构建了一份游戏，平台仍需要登记产物、关联项目和版本，才能进入产品的交付流程。

本文最初整理时，原生引擎接入仍在开发验证阶段。部分原生执行和素材任务完成了限定范围的开发环境验收，项目交互、完整交付和恢复仍在推进。这些结果只能说明已验证的范围，不能作为整套迁移完成的依据。

8. 模型与流程的对照验证

上面的调整同时涉及模型、Prompt、工具和编排。若把它们一起修改，只能观察到最终结果变化，很难确定是哪一部分起了作用。

后续可以固定一组游戏需求和验收条件，分步骤比较：

先保存现有模型与流程的结果，再接入兼容的新模型；之后调整工具和上下文；最后每次简化一部分编排。比较旧环境时，应先满足新模型的接口与工具兼容要求。

各组使用相同的记录项：需求完成情况、核心玩法验证、交付版本、总费用、等待时间，以及失败后的恢复结果。把重复素材任务、无效部署和额外修复计入成本，才能判断一次有效交付实际消耗多少资源。

多 Agent、固定检查和独立评估都可以放进这套比较中。某一步删除后，若结果在约定范围内保持稳定，同时费用与等待下降，才有依据继续简化；出现质量下降，则需要检查该步骤在当前任务中承担了什么作用。