# @buddy-works/sandbox-sdk 中文文档

规范地址：https://npmcn.com/package/%40buddy-works/sandbox-sdk/

版本：0\.3\.0
npm 元数据更新时间：2026-10-27T09:11:08.208Z
中文译文更新时间：2026-11-08T18:16:22.053Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40buddy-works/sandbox-sdk
原文对照：https://npmcn.com/package/%40buddy-works/sandbox-sdk/?lang=original
项目主页：https://github.com/buddy/sandbox-sdk#readme
源码仓库：https://github.com/buddy/sandbox-sdk

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：543 kB，7 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：2 个
- 首次发布：2026-01-26T11:53:56.694Z
- 最新版本发布：2026-10-27T09:11:07.402Z
- 近 30 天下载量：6222（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：25（近 12 个月 25 个）

## 中文简介

通过 Buddy API 管理沙盒的脚本 SDK 类型

## 安装

```sh
npm install @buddy-works/sandbox-sdk
```

也可以使用：`pnpm add @buddy-works/sandbox-sdk`、`yarn add @buddy-works/sandbox-sdk`、`bun add @buddy-works/sandbox-sdk`

## README

# 巴迪·沙盒SDK

TypeScript SDK 用于管理 Buddy sandboxs - 用于运行命令的孤立的Ubuntu环境.

## 安装

```bash
npm install @buddy-works/sandbox-sdk
```

## 使用量

```typescript
import { Sandbox } from "@buddy-works/sandbox-sdk";

const identifier = "my-sandbox";

let sandbox: Sandbox;

try {
    sandbox = await Sandbox.getByIdentifier(identifier);
} catch {
    sandbox = await Sandbox.create({
        identifier,
        name: "My Sandbox",
        os: "ubuntu:24.04",
    });
}

await sandbox.start();

await sandbox.runCommand({
    command: "ping -c 5 buddy.works",
});

await sandbox.stop();
```

设定所需的环境变量 :

```bash
export BUDDY_TOKEN="your-api-token"
export BUDDY_WORKSPACE="your-workspace"
export BUDDY_PROJECT="your-project"
export BUDDY_REGION="US"  # Optional: US (default), EU, or AS
```

## 运行命令

`exec()` 运行一个命令,并在它完成后解析,并带有其退出代码和 输出 :

```typescript
const result = await sandbox.exec({ command: "npm test" });

console.log(result.exit_code, result.stdout, result.stderr);
```

一个退出非零的命令仍然解决, 所以检查 `exit_code`。 。 。 .

`runtime` 选择翻译。 默认为 `BASH`,并且还要 `JAVASCRIPT`, (中文(简体) ), `TYPESCRIPT` 或者说 `PYTHON`数字 :

```typescript
await sandbox.exec({ command: "print(1 + 1)", runtime: "PYTHON" });
```

请求在命令运行时保持开放, 60 后 API 失败 秒数。 不管做什么 命令都这样运行 沙盒里没有入口 命令历史,流无日志,无法终止.

使用 `runCommand()` 超过1分钟的输出 它到达,或者在呼叫返回后离开命令运行:

```typescript
// streams to process.stdout as it runs, resolves once it finishes
const command = await sandbox.runCommand({ command: "npm test" });
console.log(command.data.status, command.data.exit_code);

// returns immediately, leaving the command running
const detached = await sandbox.runCommand({
    command: "npm run build",
    detached: true,
    output: null,
});

for await (const line of detached.logs({ follow: true })) {
    console.log(line);
}

const finished = await detached.wait(); // SUCCESSFUL, FAILED or CANCELLED
```

一个分离的命令仍然流到 `process.stdout` 默认时, 保留 将节点进程活到命令结束 - 通过 `output: null` 让它 快离开.

命令的日志中包含 stdout 和 stderr 互出,顺序为 命令写道: `logs()` 减小线条 `output()` 返回为一体 绳子。 使用 `exec()` 当你需要两个分开.

`kill()` 取消运行中的命令,并在命令停止后按 状态 `CANCELLED` 内 `data`,或者30秒后,如果它缓慢停止 - 那么 `data.status` 仍然是 `INPROGRESS`。 。 。 . `listCommands()` 返回 sandbox 的命令历史, 首先是最新的 - API 保留最近的200个.

`wait()`, (中文(简体) ), `logs()` 财务报告和审定财务报表 `output()` 拿着 `AbortSignal` 停止等待, 命令的截止日期 :

```typescript
try {
    await detached.wait({ signal: AbortSignal.timeout(5 * 60_000) });
} catch (error) {
    if (!(error instanceof DOMException && error.name === "TimeoutError")) {
        throw error;
    }
    await detached.kill(); // the signal only stops waiting, not the command
}
```

API在一个沙盒里每个成员一次运行最多3个指令,每个成员10个指令 穿越沙盒和目标的工作空间。 任意限制的指令是 以 HTTP 409 拒绝, 以及 超过 API 节点运行时的 100; `runCommand()` 然后丢出一个 `BuddySDKError` 带代码 `CONCURRENCY_LIMIT`,这样你就可以等待运行 命令完成并再次尝试.

命令最长可达16个KB,90分钟后停止,故跑 服务器和其他长寿进程 [应用程序](https://npmcn.com/package/%40buddy-works/sandbox-sdk/#readme-apps)它的日志封顶于 10米B,过去 `data.truncated` 已经设定.

启动和取消命令需要 `SANDBOX_USE` 符号范围, 其中 `SANDBOX_WRITE` 包含.

## 等待准备

`Sandbox.create()` 直到沙盒设置完毕并到达 `RUNNING`,因此它返回的例可以使用。 一边等着投票 aPI从100ms开始,成长到500ms.

过 `wait: false` 跳过等待,自己开车。 你得到的例子 带回所有创建呼叫 `id`, (中文(简体) ), `identifier`, (中文(简体) ), `url`, (中文(简体) ), `resources` -但是连接细节还没有解决.

```typescript
const sandbox = await Sandbox.create({ identifier: "my-sandbox", wait: false });

// ... do other work while the sandbox boots ...

await sandbox.waitUntilReady();   // setup_status: SUCCESS
await sandbox.waitUntilRunning(); // status: RUNNING
```

服务员接受一个明确的间隔 将投票定在固定值 而不是退后 :

```typescript
await sandbox.waitUntilRunning(500); // check every 500ms
```

## 应用程序

沙盒可以同时运行多个应用程序. 每个应用程序都是由运行命令定义的长期进程,可选 `identifier` (省略时来自命令)和可选 `path` 它在运行( 默认为 `app_dir`) (中文(简体) ).

```typescript
const sandbox = await Sandbox.create({
    identifier: "my-sandbox",
    name: "My Sandbox",
    os: "ubuntu:24.04",
    first_boot_commands: "apt-get update && apt-get install -y curl",
    apps: [
        { identifier: "api", command: "node server.js" },
        { identifier: "worker", command: "python worker.py", path: "/app/jobs" },
    ],
    timeout: 600, // auto-stop after 10 minutes of inactivity
});

// List apps
for (const app of sandbox.data.apps ?? []) {
    console.log(`${app.identifier}: "${app.command}" -> ${app.app_status}`);
}

// Control individual apps - by identifier or by the generated id
await sandbox.stopApp("api");
await sandbox.startApp("api");

const { logs } = await sandbox.getAppLogs("api");
console.log(logs);
```

## 取出仓库和文物

使用 `fetch` 或将文物下载到沙盒中 第一个靴子。 每个条目设置一个 `type` (单位:千美元)`PROJECT_REPO`, (中文(简体) ), `PUBLIC_REPO`,或 `ARTIFACT`\+ 与之相关的字段.

```typescript
await Sandbox.create({
    identifier: "my-sandbox",
    fetch: [
        {
            type: "PUBLIC_REPO",
            repository: "https://github.com/octocat/Hello-World",
            ref: "master",
            path: "/workspace/hello",
            build_command: "echo built",
        },
    ],
});
```

## 更新沙盒

使用 `sandbox.update()` 创建后更改配置 - `timeout`, (中文(简体) ), `apps`, (中文(简体) ), `endpoints`, (中文(简体) ), `variables`, (中文(简体) ), `tags`等 (中文(简体) ). 内部状态随API的回应而更新.

```typescript
const sandbox = await Sandbox.getByIdentifier("my-sandbox");

await sandbox.update({
    timeout: 1200,
    tags: ["staging", "feature-x"],
});
```

## 抓图

取一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一一 每个快照都作为 `Snapshot` 使用自己的方法.

```typescript
const sandbox = await Sandbox.getByIdentifier("my-sandbox");

// Create a snapshot. Returns immediately with status "CREATING".
const snapshot = await sandbox.createSnapshot({ name: "before-deploy" });

// Wait until the snapshot is "CREATED" before using it.
await snapshot.waitUntilReady();

// Create a new sandbox from the snapshot.
const restored = await Sandbox.createFromSnapshot(snapshot.id, {
    name: "restored-sandbox",
});

// List all snapshots for this sandbox.
const snapshots = await sandbox.listSnapshots();

// Delete a snapshot.
await snapshot.delete();
```

如果您已经从别处获得快照ID( 如在自己的存储中坚持), 请直接获取实体 :

```typescript
const snapshot = await Sandbox.getSnapshotById(sandboxId, snapshotId);
```

同等便利方法 `Sandbox` 仅当您有身份证明而不想要获取 `Snapshot` 第一条:

```typescript
await sandbox.waitForSnapshotReady(snapshotId);
await sandbox.deleteSnapshot(snapshotId);
```

## 区域

配置 API 区域 :

```bash
# Via environment variable (recommended)
export BUDDY_REGION="EU"
```

```typescript
// Or via connection config
const sandbox = await Sandbox.create({
    identifier: "my-sandbox",
    name: "My Sandbox",
    os: "ubuntu:24.04",
    connection: {
        region: "EU"  // US, EU, or AS
    }
});
```

## 连接覆盖

覆盖每个呼叫的工作空间/自动 :

```typescript
await Sandbox.create({
    identifier: "my-sandbox",
    name: "My Sandbox",
    os: "ubuntu:24.04",
    connection: {
        workspace: "different-workspace",
        project: "different-project",
        token: "custom-token",
        region: "EU"
    }
});
```

## HTTP/2 导弹

SDK通过HTTP/2发送API请求,使用由所有沙盒共享的每个过程16个连接的集合. 改变池大小或使用 `fetch` (HTTP/1.1)改为:

```bash
export BUDDY_HTTP2_SESSIONS="32"  # 1-64, default 16
export BUDDY_HTTP2="0"            # use fetch instead
```

在第一个请求之前设定 如果设置了代理变量( E)`HTTPS_PROXY`, (中文(简体) ), `HTTP_PROXY`, (中文(简体) ), `ALL_PROXY`), SDK 使用 `fetch`: 节点 `http2` 模块从不通过代理连接,而 `fetch` 当节点运行时 `--use-env-proxy` 或者说 `NODE_USE_ENV_PROXY=1`。 。 。 .

## 常见问题

### @buddy-works/sandbox-sdk 是什么？

通过 Buddy API 管理沙盒的脚本 SDK 类型

### 如何安装 @buddy-works/sandbox-sdk？

在项目目录运行 npm install @buddy-works/sandbox-sdk，或使用 pnpm add / yarn add / bun add。

### @buddy-works/sandbox-sdk 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @buddy-works/sandbox-sdk 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @buddy-works/sandbox-sdk 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^20\.19\.0 \|\| \>=22\.12\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @buddy-works/sandbox-sdk 可以商用吗？

@buddy-works/sandbox-sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @buddy-works/sandbox-sdk 的下载量有多少？

根据 npm 官方下载统计，@buddy-works/sandbox-sdk 在 2026/10/09 – 2026/11/07 这 30 天内被下载 6,222 次，日均约 207 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @buddy-works/sandbox-sdk 还在维护吗？

最新版本 0\.3\.0 发布于 2026/10/27（12 天前）；至今共发布 25 个版本，其中过去 12 个月发布了 25 个；首次发布于 2026/01/26。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。