类class io.agentscope.harness.agent.sandbox 2.x

AbstractBaseSandbox

public abstract class AbstractBaseSandbox implements Sandbox

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:48–288

抽象基类沙箱，承载智能体的部署、调度与服务化运行。位于 io.agentscope.harness.agent.sandbox 包，实现 Sandbox。核心成员包括 start、stop、close、isRunning、getState、exec。

Abstract base implementation of Sandbox with the 4-branch workspace start logic.

4-Branch Start Logic


Branch A: workspaceRootReady=true &amp; workspace dir exists → apply ephemeral-only entries
Branch B: workspaceRootReady=true &amp; workspace dir missing → restore from snapshot + ephemeral entries
Branch C: workspaceRootReady=false &amp; snapshot is restorable → hydrate from snapshot + all entries
Branch D: workspaceRootReady=false &amp; no restorable snapshot → fresh init from full workspace spec

Subclasses implement the backend-specific operations:

#doExec(RuntimeContext, String, int) — execute a shell command in the workspace
#doPersistWorkspace() — create a tar archive of the workspace
#doHydrateWorkspace(InputStream) — extract a tar archive into the workspace
#doSetupWorkspace() — create the workspace root directory
#doDestroyWorkspace() — delete the workspace root directory (on shutdown)
#getWorkspaceRoot() — return the workspace root path string

构造器摘要Constructor Summary

构造器Constructor	说明Description
`protected` `AbstractBaseSandbox(SandboxState state)`	初始化 `AbstractBaseSandbox` 实例。 Creates a new instance.

方法摘要Method Summary

方法Method	说明Description
`public void start() throws Exception`	执行启动相关操作。 Executes the 4-branch workspace start logic.
`public void stop() throws Exception`	执行停止相关操作。 Persists the workspace snapshot and marks the workspace root as ready.
`public void close() throws Exception`	关闭连接并释放相关资源。 {@inheritDoc}
`public boolean isRunning()`	判断是否运行中。 Returns whether the running.
`public` `SandboxState getState()`	获取状态。 Returns the state.
`public` `ExecResult exec(RuntimeContext runtimeContext, String command, Integer timeoutSeconds) throws Exception`	执行 `exec` 方法。 Delegates to `#doExec(RuntimeContext, String, int)` with a fallback timeout.
`public InputStream persistWorkspace() throws Exception`	返回 `persistWorkspace` 结果。 Returns the persist workspace.
`public void hydrateWorkspace(InputStream archive) throws Exception`	设置该参数。 Performs the hydrate workspace operation.
`protected boolean probeWorkspaceRootForPreservedResume()`	返回 `probeWorkspaceRootForPreservedResume` 结果。 Probes whether the workspace root directory still exists, using a backend exec.
`protected int getDefaultExecTimeoutSeconds()`	返回默认命令执行超时 in 秒。 Returns the default command execution timeout in seconds.
`protected abstract` `ExecResult doExec(RuntimeContext runtimeContext, String command, int timeoutSeconds) throws Exception` abstract	执行 `doExec` 回调。 Executes a shell command within the workspace.
`protected abstract InputStream doPersistWorkspace() throws Exception` abstract	执行 `doPersistWorkspace` 回调。 Creates a tar archive of the current workspace contents.
`protected abstract void doHydrateWorkspace(InputStream archive) throws Exception` abstract	执行 `doHydrateWorkspace` 回调。 Extracts a tar archive into the workspace.
`protected abstract void doSetupWorkspace() throws Exception` abstract	创建工作区根目录。 Creates the workspace root directory.
`protected abstract void doDestroyWorkspace() throws Exception` abstract	执行 `doDestroyWorkspace` 回调。 Destroys the workspace root and any backend resources.
`protected abstract String getWorkspaceRoot()` abstract	获取工作区根。 Returns the absolute path of the workspace root directory.

构造器详情Constructor Detail

AbstractBaseSandbox

protected AbstractBaseSandbox(SandboxState state)

初始化 AbstractBaseSandbox 实例。

Creates a new instance.

参数Parameters

名称Name	类型Type	说明Description
`state`	SandboxState	状态对象（类型 `SandboxState`）。The state.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:59–62

方法详情Method Detail

start

public void start() throws Exception

执行启动相关操作。

Executes the 4-branch workspace start logic.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:69–124

stop

public void stop() throws Exception

执行停止相关操作。

Persists the workspace snapshot and marks the workspace root as ready.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:131–141

close

public void close() throws Exception

关闭连接并释放相关资源。

{@inheritDoc} Calls #stop() then #shutdown().

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:149–157

isRunning

public boolean isRunning()

判断是否运行中。

Returns whether the running.

返回Returns boolean

返回布尔值，表示判断结果。Returns a boolean result.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:159–162

getState

public SandboxState getState()

获取状态。

Returns the state.

返回Returns SandboxState

返回SandboxState。Returns sandbox state.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:164–167

exec

public ExecResult exec(RuntimeContext runtimeContext, String command, Integer timeoutSeconds) throws Exception

执行 exec 方法。

Delegates to #doExec(RuntimeContext, String, int) with a fallback timeout.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。The runtime context.
`command`	String	命令（类型 `String`）。The command.
`timeoutSeconds`	Integer	超时秒（类型 `Integer`）。The timeout seconds.

返回Returns ExecResult

返回ExecResult。Returns exec result.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:172–177

persistWorkspace

public InputStream persistWorkspace() throws Exception

返回 persistWorkspace 结果。

Returns the persist workspace.

返回Returns InputStream

返回InputStream。Returns input stream.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:179–182

hydrateWorkspace

public void hydrateWorkspace(InputStream archive) throws Exception

设置该参数。

Performs the hydrate workspace operation.

参数Parameters

名称Name	类型Type	说明Description
`archive`	InputStream	归档（类型 `InputStream`）。The archive.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:184–187

probeWorkspaceRootForPreservedResume

protected boolean probeWorkspaceRootForPreservedResume()

返回 probeWorkspaceRootForPreservedResume 结果。

Probes whether the workspace root directory still exists, using a backend exec.

返回Returns boolean

返回布尔值，表示判断结果。true if the workspace root exists

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:197–207

getDefaultExecTimeoutSeconds

protected int getDefaultExecTimeoutSeconds()

返回默认命令执行超时 in 秒。

Returns the default command execution timeout in seconds.

返回Returns int

返回数值结果。default timeout (120 seconds)

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:214–216

doExec

protected abstract ExecResult doExec(RuntimeContext runtimeContext, String command, int timeoutSeconds) throws Exception

abstract

执行 doExec 回调。

Executes a shell command within the workspace.

参数Parameters

名称Name	类型Type	说明Description
`runtimeContext`	RuntimeContext	运行时上下文（类型 `RuntimeContext`）。per-call context; may be `null` for internal probes
`command`	String	命令（类型 `String`）。shell command string
`timeoutSeconds`	int	超时秒（类型 `int`）。maximum execution time

返回Returns ExecResult

返回ExecResult。execution result

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:227–228

doPersistWorkspace

protected abstract InputStream doPersistWorkspace() throws Exception

abstract

执行 doPersistWorkspace 回调。

Creates a tar archive of the current workspace contents.

返回Returns InputStream

返回InputStream。an `InputStream` over the tar stream; caller must close

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:236

doHydrateWorkspace

protected abstract void doHydrateWorkspace(InputStream archive) throws Exception

abstract

执行 doHydrateWorkspace 回调。

Extracts a tar archive into the workspace.

参数Parameters

名称Name	类型Type	说明Description
`archive`	InputStream	归档（类型 `InputStream`）。the tar archive stream to extract

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:244

doSetupWorkspace

protected abstract void doSetupWorkspace() throws Exception

abstract

创建工作区根目录。

Creates the workspace root directory.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:251

doDestroyWorkspace

protected abstract void doDestroyWorkspace() throws Exception

abstract

执行 doDestroyWorkspace 回调。

Destroys the workspace root and any backend resources.

抛出Throws

Exception 可能抛出 `Exception`。Thrown when the operation cannot be completed.

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:258

getWorkspaceRoot

protected abstract String getWorkspaceRoot()

abstract

获取工作区根。

Returns the absolute path of the workspace root directory.

返回Returns String

返回字符串结果。workspace root path string

源码Source io/agentscope/harness/agent/sandbox/AbstractBaseSandbox.java:265

继承成员Inherited Members

继承自Methods inherited from Sandbox

shutdown