# @computesdk/buddy 中文文档

规范地址：https://npmcn.com/package/%40computesdk/buddy/

版本：1\.0\.22
npm 元数据更新时间：2026-11-07T03:29:56.384Z
中文译文更新时间：2026-11-10T14:48:34.636Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：253 kB，9 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：^20\.19\.0 \|\| \>=22\.12\.0
- 运行依赖：3 个
- 首次发布：2026-09-09T22:40:17.993Z
- 最新版本发布：2026-11-07T03:29:56.198Z
- 近 30 天下载量：8767（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：22（近 12 个月 22 个）

## 中文简介

计算SDK- 用于代理的持久 Ubuntu 沙盒、 以毫秒为单位启动、 有预览 URL 和快照的 buddy 提供者

## 安装

```sh
npm install @computesdk/buddy
```

也可以使用：`pnpm add @computesdk/buddy`、`yarn add @computesdk/buddy`、`bun add @computesdk/buddy`

## README

# @ computesdk/ buddy

计算SDK的Buddy提供者.

每个沙盒都是Buddy沙盒——你Buddy项目中的Ubuntu microVM,服务于前武装的游泳池. 命令在运行时会流出输出,端口通过Buddy隧道发布,快照作为可再用的基础图像双倍.

建造在 [`@buddy-works/sandbox-sdk`](https://www.npmjs.com/package/@buddy-works/sandbox-sdk)Buddy的官方TypeScript SDK(英语:TypeScript SDK).

## 安装

```bash
npm install @computesdk/buddy
```

需要20.19或22.12号节点并更新,匹配Buddy SDK(ESM和CommonJS建筑均被发运出).

## 设置

1.  在其中创建 API 令牌 **巴迪 我的身份证 访问符** 与 `SANDBOX_MANAGE` 范围
2.  为您的沙盒创建( 或选择) Buddy 工程
3.  设置环境变量 :

```bash
export BUDDY_TOKEN=your_api_token_here
export BUDDY_WORKSPACE=your_workspace_domain
export BUDDY_PROJECT=your_project_name
```

## 快速启动

```ts
import { buddy } from '@computesdk/buddy';

const compute = buddy();

const sandbox = await compute.instances.create();

const result = await sandbox.runCommand('echo "hello from buddy"');
console.log(result.stdout);

await sandbox.destroy();
```

全权证书取自环境,因此 `buddy()` 不需要参数。 明确通过它们以覆盖 :

```ts
const compute = buddy({
  token: process.env.BUDDY_TOKEN!,
  workspace: 'acme',
  project: 'sandboxes',
});
```

## 配置

```ts
interface BuddyConfig {
  /** API token with the `SANDBOX_MANAGE` scope. Falls back to `BUDDY_TOKEN`. */
  token?: string;
  /** Workspace domain. Falls back to `BUDDY_WORKSPACE`. */
  workspace?: string;
  /** Project the sandboxes belong to. Falls back to `BUDDY_PROJECT`. */
  project?: string;
  /** Base OS image — `'ubuntu:24.04'` (default) or `'ubuntu:22.04'`. */
  os?: string;
  /** Resource preset, `"{vCPU}x{RAM GB}"` from `1x2` to `12x24`. Buddy's own default applies when omitted. */
  resources?: BuddyResources;
  /** Buddy installation — `'US'` (default) or `'EU'`. */
  region?: BuddyRegion;
  /** Sandbox lifetime in milliseconds, after which Buddy stops it. Defaults to 1 hour. */
  timeout?: number;
  /** Ports to expose on every sandbox this provider creates. */
  ports?: BuddyPortInput[];
  /** API base URL. Overrides `region`, for on-premise installations. */
  apiUrl?: string;
}
```

### 选择安装

Buddy在一个API范围内运行独立设施而不是区域,每个区域都有 自己的主机,账户和信使. `region` 选择 API 主机和位置 隧道终止 :

```ts
const compute = buddy({ region: 'EU' });
```

| `region` | API 主机 |
| --- | --- |
| `US` (默认) | `https://api.buddy.works` |
| `EU` | `https://api.eu.buddy.works` |

一个装置签发的令牌对其他装置无效。 对于一个真实 安装, 设置 `apiUrl` 换句话说.

## 创建选项

除了交叉提供者的选择之外, `create` 接受:

```ts
await compute.instances.create({
  // Expose ports up front, so getUrl needs no extra round trip
  ports: [3000, { port: 443, type: 'TLS', region: 'EU' }],
  // Resources — either a preset, or cpu/memory that map onto one
  resources: '4x8',
  // Commands run once when the sandbox first boots
  firstBootCommands: 'npm ci',
  // Working directory for the sandbox's apps
  appDir: '/buddy/app',
  tags: ['ci'],
});
```

`snapshotId` (或 `templateId`)从快照开始沙盒,而不是从底像开始.

## 显示端口

```ts
const sandbox = await compute.instances.create({ ports: [3000] });
await sandbox.runCommand('npx serve -l 3000', { background: true });

const url = await sandbox.getUrl({ port: 3000 });
```

`getUrl` 如果在创建时没有宣布端口,则按要求打开隧道, 保持任何隧道已经打开。 仅 `HTTP` 财务报告和审定财务报表 `TLS` 隧道获得公共URL; `TCP` 财务报告和审定财务报表 `SSH` 隧道由主机和端口到达,报告于 `getInfo`。 。 。 .

## 文件系统

```ts
await sandbox.filesystem.mkdir('/buddy/app');
await sandbox.filesystem.writeFile('/buddy/app/index.js', 'console.log(1)');
await sandbox.filesystem.readFile('/buddy/app/index.js');
await sandbox.filesystem.readdir('/buddy/app');
await sandbox.filesystem.exists('/buddy/app/index.js');
await sandbox.filesystem.remove('/buddy/app');
```

相对路径解析 `/buddy`,默认值的主目录 `buddy` 用户.

第一个文件系统在沙盒上呼叫等待它的第一个启动设置完成. 哥们 队列 _命令_ 对起步沙盒,但内容终点不: 设置他们要么拒绝请求,要么接受写作,一旦设定就丢弃 完成 。 等待需要几百毫秒 在一个新创造的沙盒和 之后什么都没有.

## 抓图

一个快照是一张从活沙盒取取的磁盘图像,作为可重复使用的底片 图像其他提供者调用模板.

```ts
const snapshot = await compute.snapshot.create(sandbox.instanceId, { name: 'with-deps' });

await compute.snapshot.list();                                 // the whole project
await compute.snapshot.list({ instanceId: sandbox.instanceId });  // one sandbox
await compute.snapshot.delete(snapshot.id);

// Booting from it is a normal create
const prepared = await compute.instances.create({ snapshotId: snapshot.id });
```

Buddy 同步创建快照 它们不会被还原 直到它们转向 `CREATED`这样 `create` 等那个再回来. `metadata` 已接受为 交叉提供者兼容性但不存储: Buddy只保留一个名称.

巴迪没有单独的模板实体 所以 `template.list` 财务报告和审定财务报表 `template.delete` 别名 即时方法和 `template.create` 掷出,指向 `snapshot.create`。 。 。 .

## 倒在巴迪SDK

`getInstance()` 返回提供者工作过的控件,包括活的 SDK 客户端和文件系统,所以Buddy在计算SDK表面外的特性仍然可以达到 不建立第二个客户端 :

```ts
const { client, fs, sandboxId } = sandbox.getInstance();
await client.getSandboxAppLogs({ path: { sandbox_id: sandboxId, app_id: 'web' } });
```

手柄 `fs` 财务报告和审定财务报表 `client` 直接拨打 API, 无需提供者的第一启动等: 在刚刚创建的沙盒上, 制作一个 `sandbox.filesystem` 呼叫( 偶数) `exists`在上传之前.

## 支助业务

| 方法 | 支助 | 页:1 |
| --- | --- | --- |
| `create` | ✅ | 一个请求; 在沙盒仍在启动时返回, 因为命令队列反对它 . |
| `getById` | ✅ | 回返 `null` 当沙盒不复存在时. |
| `list` | ✅ | 在配置的项目中列出沙盒. |
| `destroy` | ✅ | 对服务器错误进行检索; 如果沙盒已经丢失, 则不开放 . |
| `runCommand` | ✅ | 一次往返 `exec` 用于普通调用; 当调用通过时, 流输出 。 真正的退出代码 无论是哪种方式. |
| `getInfo` | ✅ | 报告 巴迪自己的状态和设置状态, 加上每一个隧道,在 `metadata`。 。 。 . |
| `getUrl` | ✅ | 如果端口尚未打开, 则打开一条隧道, 保留已有的隧道 . |
| `filesystem` | ✅ | 通过Buddy的原生端点传输文件内容,没有命令行内容限制. 读取先用本地命令解析并链接;只有在验证其类型后才接受已存在的目录. |
| `snapshot` | ✅ | `create` 编号 : `list` 编号 : `delete`· ; `create` 等待到快照恢复. |
| `template` | ⚠️ | Buddy没有模板实体 —— `list`编号 :`delete` 别名快照, `create` 投出一个提示. |

## 页:1

-   `create` 不等待沙盒到达 `RUNNING`。Buddy队列对起步沙盒提交命令,所以等待只会给第一个命令增加延迟。 有同样的原因 供应商称SDK's `BuddyApiClient` 直接代替 `Sandbox.create()`民意测验准备时间.
-   `runCommand(cmd)` 没有流回调或a `timeout` 运行在巴迪的同步 `exec` 端点: 一个请求, 将 stdout, stderr 和退出代码一起返回 。 这样的命令没有留下 进入沙盒的命令历史。 服务器最多等待60 s; 过去调用返回退出码 124, 服务器的消息输入 `stderr`,该过程会一直运行在沙盒中。 通过 a `timeout` 对于可能运行更长或必须停止的命令.
-   `runCommand(cmd, { onStdout, onStderr })`, (中文(简体) ), `streamCommand`, (中文(简体) ), `background: true` 和任何 `timeout` 使用同步键 `execs` 而不是资源,所以输出会随着它的产生而到来,命令会出现在历史中,一个超时会杀死它. 它的日志没有显示 stdout 从 stderr, 所以所有输出都到 `stdout` 财务报告和审定财务报表 `onStdout`· ; `onStderr` 没有叫。 Buddy最多3个这样的命令,每个成员一次在一个沙盒里,每个工作空间10个, `runCommand` 抛出——90分钟后停止,包括 `background` 这些.
-   `runCommand(cmd, { background: true })` 当Buddy在命令中排入队列时返回,而不读取其输出.
-   `runCommand(cmd, { timeout })` 返回超时结果并终止命令.
-   无法选择安装中的沙盒放置; `region` 选择安装和隧道位置.

## 许可证

麻省理工学院

## 常见问题

### @computesdk/buddy 是什么？

计算SDK- 用于代理的持久 Ubuntu 沙盒、 以毫秒为单位启动、 有预览 URL 和快照的 buddy 提供者

### 如何安装 @computesdk/buddy？

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

### @computesdk/buddy 支持 TypeScript 吗？

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

### @computesdk/buddy 支持 ESM 还是 CommonJS？

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

### @computesdk/buddy 需要什么版本的 Node\.js？

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

### @computesdk/buddy 可以商用吗？

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

### @computesdk/buddy 的下载量有多少？

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

### @computesdk/buddy 还在维护吗？

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