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