> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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/zh-TW/reference/workspace/process-manager)
- [Sandbox](https://mastra.zisheng.pro/zh-TW/docs/workspace/sandbox)
- [Workspace 類別](https://mastra.zisheng.pro/zh-TW/reference/workspace/workspace-class)
- [Filesystem 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/filesystem)