> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# WorkspaceSandbox

**添加于：** `@mastra/core@1.1.0`

`WorkspaceSandbox` 接口定义 Workspace 如何执行命令和管理后台进程。

## 属性

**processes** (`SandboxProcessManager`): 后台进程管理器。如果未实现，则进程管理 Tool 将不可用。请参阅 SandboxProcessManager 参考文档。

## 方法

### `start()`

启动 Sandbox。此方法由 `workspace.init()` 或首次调用 `executeCommand()` 时自动调用。

```typescript
await sandbox.start()
```

此方法为执行命令准备 Sandbox。

### `stop()`

停止 Sandbox。

```typescript
await sandbox.stop?.()
```

### `destroy()`

清理 Sandbox 资源。由 `workspace.destroy()` 调用。

```typescript
await sandbox.destroy()
```

### `executeCommand(command, args?, options?)`

执行 shell 命令。

```typescript
const result = await sandbox.executeCommand('ls', ['-la', '/docs'])
const result = await sandbox.executeCommand('npm', ['install', 'lodash'])
```

**参数：**

**command** (`string`): 要执行的命令

**args** (`string[]`): 命令参数

**options** (`Options`): 配置选项。

**options.timeout** (`number`): 执行超时时间（毫秒）

**options.cwd** (`string`): 命令的工作目录

**options.env** (`Record<string, string>`): 额外的环境变量

**options.onStdout** (`(data: string) => void`): 用于 stdout 流式输出的回调

**options.onStderr** (`(data: string) => void`): 用于 stderr 流式输出的回调

### `getInfo()`

获取 Sandbox 状态和资源信息。

```typescript
const info = await sandbox.getInfo()
// { status: 'running', resources: { memoryMB: 512, cpuPercent: 5 } }
```

### `getInstructions(opts?)`

返回此 Sandbox 工作方式的说明。将 Workspace 分配给 Agent 时，该说明会注入 Agent 的系统消息中。

```typescript
const instructions = sandbox.getInstructions?.()
// 'Local command execution. Working directory: "/workspace".'
```

**参数：**

**opts.requestContext** (`RequestContext`): 如果构造函数中提供了 instructions 函数，则转发给该函数。

**返回值：** `string`

## 相关内容

- [SandboxProcessManager 参考文档](https://mastra.zisheng.pro/reference/workspace/process-manager)
- [Sandbox](https://mastra.zisheng.pro/docs/workspace/sandbox)
- [Workspace 类](https://mastra.zisheng.pro/reference/workspace/workspace-class)
- [Filesystem 接口](https://mastra.zisheng.pro/reference/workspace/filesystem)