克隆沙箱

1. 实验冲突与环境污染。当 AI Agent 尝试多种解决方案时，实验性的代码变更可能会干扰开发者的主要工作流程，或者污染当前的运行环境。一旦实验出错，往往只能通过回滚来恢复，无法保留有价值的探索路径。
2. 无法并行探索多个方案。受限于单一环境，AI Agent 只能按顺序测试不同的解决思路。这种串行模式不仅效率低下，更重要的是限制了 AI 的探索广度——无法同时验证多个并行的假设或实现方案。
3. 计算能力扩展受限。当面对需要 “广度并行探索” (Wide-Research) 的任务时（例如同时比较 100 个解决方案、批量生成多个实现版本），单一环境的架构从根本上制约了任务的并行化处理能力。

1. 多时间线探索架构：就像决策树一样，AI Agent 可以从同一个基准状态出发，创建多个独立的沙箱副本，每个副本探索一条不同的解决路径，互不干扰。
2. 真正的并行计算能力：通过将大任务拆分成批量子任务，AI Agent 能够将计算能力扩展数十倍甚至上百倍，同时处理数十个、上百个探索分支。
3. 零风险实验环境：克隆出的沙箱完全隔离，AI 可以在其中自由实验、测试各种可能性，而不会影响原始环境或开发者的主工作流程。
4. 高效的资源利用：虽然可能同时启动多个沙箱实例，但通过动态管理和及时终止不再有价值的分支（沙箱实例），总体计算资源消耗可以保持在合理范围内。

​

名词定义

• 原始沙箱（Origin Sandbox）：被克隆的原始沙箱实例。
• 新沙箱（New Sandbox）：通过克隆操作创建的新沙箱实例。

​

功能概述

• 克隆运行中（Running）状态的沙箱
• 克隆已暂停（Paused）状态的沙箱

​

克隆运行中（Running）状态的沙箱

• 在克隆执行期间，原始沙箱会被短暂挂起；
• 挂起期间该沙箱实例不可用；
• 挂起时长接近一次暂停（pause）操作所需的时间。

• 状态恢复为运行中（running）；
• 原有的暂停记录会被清除，但是随即以当前状态生成一条新的暂停记录；
• 生成一条新的快照模板记录（如果想要删除该快照模板，需要先终止原始沙箱和克隆出来的沙箱）；

• 状态为运行中（running）；
• 可立即使用。

​

克隆已暂停（Paused）状态的沙箱

• 克隆过程不会触发原始沙箱的启动；
• 原始沙箱保持暂停状态。

• 原有的暂停记录不会被清除；
• 生成一条新的快照模板记录（如果想要删除该快照模板，需要先终止原始沙箱和克隆出来的沙箱）；

• 状态为运行中（running）；
• 可立即使用。

​

新沙箱的属性继承规则

​

参数说明

• count：要克隆的沙箱实例数量。最小值为 1，最大值不超过平台限制的并发运行的沙箱实例数（参考：沙箱并发限制）；
• strict：是否严格按照 count 参数中指定的数量进行克隆，默认为 false。
  • true：若成功克隆的实例数量小于 count，则返回克隆失败；已创建成功的沙箱会被自动释放。
  • false：返回实际成功克隆的沙箱实例数量。
• timeout(timeoutMs)：克隆沙箱实例的超时时间。
  • 若未指定：
    • 当原始沙箱为运行中（running）状态时，继承其超时时间配置；
    • 当原始沙箱为已暂停（paused）状态时，使用默认值 5 分钟。

​

返回值说明

​

代码示例

from ppio_sandbox.core import Sandbox

# Create a sandbox
sandbox = Sandbox.create(template="base")
# clone
clones = Sandbox.clone(sandbox.sandbox_id, 2)

print("snapshot:", clones.snapshot_template_id)
for sbx in clones:
    print("clone sandbox:", sbx.sandbox_id)

# ppio-sandbox-cli sandbox clone [sandboxID] -c [count] -s [strict] -t [timeout]
ppio-sandbox-cli sandbox clone 0r0efkbfwzfp9p7qpc1c -c 2