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

# SandboxProcessManager

**新增于：** `@mastra/core@1.7.0`

用于管理 Sandbox 中后台进程的抽象基类。提供生成进程、列出进程、按 PID 获取 handle 以及终止进程的方法。

[`BlaxelSandbox`](https://mastra.zisheng.pro/reference/workspace/blaxel-sandbox)、[`DaytonaSandbox`](https://mastra.zisheng.pro/reference/workspace/daytona-sandbox)、[`E2BSandbox`](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)、[`ModalSandbox`](https://mastra.zisheng.pro/reference/workspace/modal-sandbox) 和 [`LocalSandbox`](https://mastra.zisheng.pro/reference/workspace/local-sandbox) 都内置了进程管理器。除非要构建自定义 Sandbox Provider，否则无需直接实例化此类。

## 用法示例

通过 Sandbox 的 `processes` 属性访问进程管理器：

```typescript
import { LocalSandbox } from '@mastra/core/workspace'

const sandbox = new LocalSandbox({ workingDirectory: './workspace' })
await sandbox.start()

// Spawn a background process
const handle = await sandbox.processes.spawn('node server.js', {
  env: { PORT: '3000' },
  onStdout: data => console.log(data),
})

// List all tracked processes
const procs = await sandbox.processes.list()

// Get a handle by PID
const proc = await sandbox.processes.get(handle.pid)

// Kill a process
await sandbox.processes.kill(handle.pid)
```

## 方法

### `spawn(command, options?)`

生成后台进程。立即返回 `ProcessHandle`，无需等待进程结束。

```typescript
const handle = await sandbox.processes.spawn('npm run dev', {
  cwd: '/app',
  env: { NODE_ENV: 'development' },
  onStdout: data => console.log(data),
})
```

**参数：**

**command** (`string`): 要运行的命令。由 shell 解释。

**options** (`SpawnProcessOptions`): 所生成进程的可选设置。

**options.timeout** (`number`): 以毫秒为单位的超时时间。超过后终止进程。

**options.env** (`NodeJS.ProcessEnv`): 进程的环境变量。

**options.cwd** (`string`): 进程的工作目录。

**options.onStdout** (`(data: string) => void`): stdout 数据块的回调。数据到达时调用。

**options.onStderr** (`(data: string) => void`): stderr 数据块的回调。数据到达时调用。

**options.abortSignal** (`AbortSignal`): 用于中止进程的 signal。中止时会终止进程。

**返回：** `Promise<ProcessHandle>`

### `list()`

列出所有被跟踪的进程。返回每个进程的信息，包括 PID、运行状态和退出代码。

```typescript
const procs = await sandbox.processes.list()
for (const proc of procs) {
  console.log(proc.pid, proc.running, proc.exitCode)
}
```

**返回：** `Promise<ProcessInfo[]>`

### `get(pid)`

按 PID 获取进程 handle。如果未找到进程或进程已被移除，则返回 `undefined`。

```typescript
const handle = await sandbox.processes.get(1234)
if (handle) {
  console.log(handle.stdout)
  await handle.kill()
}
```

**返回：** `Promise<ProcessHandle | undefined>`

### `kill(pid)`

按 PID 终止进程。返回前会等待进程终止。成功终止进程时返回 `true`，未找到进程时返回 `false`。

```typescript
const killed = await sandbox.processes.kill(handle.pid)
```

**返回：** `Promise<boolean>`

## `ProcessInfo`

由 `list()` 返回的被跟踪进程信息。

**pid** (`number`): 进程 ID。

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

**running** (`boolean`): 进程是否仍在运行。

**exitCode** (`number`): 进程已结束时的退出代码。

***

## `ProcessHandle`

已生成后台进程的 handle。提供读取输出、发送 stdin、等待进程完成和终止进程的方法。

你无需直接创建 `ProcessHandle` 实例。它们由 `spawn()` 和 `get()` 返回。

### 用法示例

```typescript
const handle = await sandbox.processes.spawn('npm run dev', {
  onStdout: data => console.log(data),
})

// Read accumulated output
console.log(handle.pid)
console.log(handle.stdout)
console.log(handle.stderr)
console.log(handle.exitCode) // undefined while running

// Wait for completion
const result = await handle.wait()

// Send stdin
await handle.sendStdin('input data\n')

// Kill the process
await handle.kill()
```

### 属性

**pid** (`number`): 进程 ID。

**stdout** (`string`): 到目前为止累积的 stdout 输出。

**stderr** (`string`): 到目前为止累积的 stderr 输出。

**exitCode** (`number | undefined`): 退出代码。进程仍在运行时为 undefined。

**command** (`string | undefined`): 生成进程时使用的命令。由进程管理器自动设置。

**reader** (`Readable`): stdout 的可读 stream。适用于通过 stdio 通信的 LSP 或 JSON-RPC 等协议。

**writer** (`Writable`): 指向 stdin 的可写 stream。适用于通过 stdio 通信的 LSP 或 JSON-RPC 等协议。

### 方法

#### `wait(options?)`

等待进程退出并返回结果。可选择传入 `onStdout`/`onStderr` 回调，以便在等待期间以 streaming 方式获取输出。`wait()` resolve 时会自动移除这些回调。

```typescript
// Simple wait
const result = await handle.wait()
console.log(result.success, result.exitCode, result.stdout)

// Wait with streaming
const result = await handle.wait({
  onStdout: data => process.stdout.write(data),
  onStderr: data => process.stderr.write(data),
})
```

**参数：**

**options** (`WaitOptions`): 等待时使用的可选设置。

**options.onStdout** (`(data: string) => void`): 等待期间 stdout 数据块的回调。

**options.onStderr** (`(data: string) => void`): 等待期间 stderr 数据块的回调。

**返回：** `Promise<CommandResult>`

`CommandResult` 对象包含：

**success** (`boolean`): 退出代码为 0 时为 true。

**exitCode** (`number`): 数字形式的退出代码。

**stdout** (`string`): 完整的 stdout 输出。

**stderr** (`string`): 完整的 stderr 输出。

**executionTimeMs** (`number`): 以毫秒为单位的执行时间。

**timedOut** (`boolean`): 进程因超时被终止时为 true。

**killed** (`boolean`): 进程被 signal 终止时为 true。

#### `kill()`

终止进程。成功终止进程时返回 `true`；进程已退出时返回 `false`。

```typescript
const killed = await handle.kill()
```

**返回：** `Promise<boolean>`

#### `sendStdin(data)`

向进程的 stdin 发送数据。如果进程已退出或 stdin 不可用，则抛出错误。

```typescript
await handle.sendStdin('console.log("hello")\n')
```

**返回：** `Promise<void>`

## Stream 互操作

`ProcessHandle` 公开 `reader` 和 `writer` 属性，可与 LSP 或 JSON-RPC 等基于 Node.js stream 的协议集成：

```typescript
import {
  createMessageConnection,
  StreamMessageReader,
  StreamMessageWriter,
} from 'vscode-jsonrpc/node'

const handle = await sandbox.processes.spawn('typescript-language-server --stdio')

const connection = createMessageConnection(
  new StreamMessageReader(handle.reader),
  new StreamMessageWriter(handle.writer),
)
connection.listen()
```

## 构建自定义进程管理器

要为自定义 Sandbox Provider 构建进程管理器，请扩展 `SandboxProcessManager` 并实现 `spawn()` 和 `list()`。基类会自动使用 `ensureRunning()` 封装你的方法，以确保在执行任何进程操作前启动 Sandbox。

```typescript
import { SandboxProcessManager, ProcessHandle } from '@mastra/core/workspace'
import type { ProcessInfo, SpawnProcessOptions } from '@mastra/core/workspace'

class MyProcessManager extends SandboxProcessManager<MySandbox> {
  async spawn(command: string, options: SpawnProcessOptions = {}): Promise<ProcessHandle> {
    // Your spawn implementation
    const handle = new MyProcessHandle(/* ... */)
    this._tracked.set(handle.pid, handle)
    return handle
  }

  async list(): Promise<ProcessInfo[]> {
    return Array.from(this._tracked.values()).map(handle => ({
      pid: handle.pid,
      running: handle.exitCode === undefined,
      exitCode: handle.exitCode,
    }))
  }
}
```

通过 `MastraSandbox` 中的 `processes` 选项将进程管理器传给 Sandbox：

```typescript
class MySandbox extends MastraSandbox {
  constructor() {
    super({
      name: 'MySandbox',
      processes: new MyProcessManager(),
    })
  }
}
```

提供进程管理器后，`MastraSandbox` 会自动创建默认的 `executeCommand` 实现，该实现使用 `spawn()` + `wait()`，因此无需同时实现两者。

## 相关内容

- [Sandbox](https://mastra.zisheng.pro/docs/workspace/sandbox)
- [WorkspaceSandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)
- [LocalSandbox 参考](https://mastra.zisheng.pro/reference/workspace/local-sandbox)
- [E2BSandbox 参考](https://mastra.zisheng.pro/reference/workspace/e2b-sandbox)
- [DaytonaSandbox 参考](https://mastra.zisheng.pro/reference/workspace/daytona-sandbox)