# @hatchet-dev/sandbox 中文文档

规范地址：https://npmcn.com/package/%40hatchet-dev/sandbox/

版本：0\.1\.5
npm 元数据更新时间：2026-11-13T10:46:37.353Z
中文译文更新时间：2026-11-17T11:34:25.993Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：174 kB，16 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：6 个
- peer 依赖：@hatchet-dev/typescript-sdk \>=1\.33\.1
- 首次发布：2026-10-27T13:21:07.424Z
- 最新版本发布：2026-11-13T10:46:36.823Z
- 近 30 天下载量：114899（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 8 个）

## 中文简介

Hatchet 沙盒类型SDK

## 安装

```sh
npm install @hatchet-dev/sandbox
```

也可以使用：`pnpm add @hatchet-dev/sandbox`、`yarn add @hatchet-dev/sandbox`、`bun add @hatchet-dev/sandbox`

## README

# @ hatchet-dev/ sandbox (中文(简体) )

[![npm version](https://img.shields.io/npm/v/%40hatchet-dev%2Fsandbox)](https://www.npmjs.com/package/@hatchet-dev/sandbox) [![License: MIT](https://img.shields.io/badge/License-MIT-purple.svg)](https://opensource.org/licenses/MIT)

运行沙盒从 [标签](https://hatchet.run/) 任务,用于您选择的沙盒供应商.

沙盒是带有外壳的工作空间. 在其中运行命令并读取并撰写其文件. 每次通话都是哈切特任务,与快照相对应. 你可以从任何快照中开始一个新的沙盒,你可以稍后通过它的ID返回到沙盒. 如果你在耐用任务中使用它, 坠机会捡起它留下的地方.

你的密码只跟哈切特说话 沙盒本身运行在一个供应商 你连接你的房客.

## 安装

```bash
pnpm add @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
```

```bash
npm install @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
```

```bash
yarn add @hatchet-dev/sandbox @hatchet-dev/typescript-sdk
```

惠璶 `@hatchet-dev/typescript-sdk` 1.3.3.1或较新.

## 快开始

导入软件包一次 。 它又说 `hatchet.sandbox` 给哈切特客户端.

```ts
import { HatchetClient } from '@hatchet-dev/typescript-sdk/v1';
import '@hatchet-dev/sandbox';

const hatchet = HatchetClient.init();

const session = hatchet.durableTask({
  name: 'agent-session',
  executionTimeout: '1h',
  fn: async (input: { conversationId: string }) => {
    const sandbox = await hatchet.sandbox.create({ id: input.conversationId });
    await sandbox.files.write('haiku.txt', 'an old silent pond');
    const haiku = await sandbox.exec('cat haiku.txt');
    await sandbox.kill();
    return { haiku: haiku.stdout };
  },
});

// later, from anywhere with a Hatchet client
const again = await hatchet.sandbox.connect('conv-42');
await again.exec('cat haiku.txt');
```

设定 `HATCHET_CLIENT_TOKEN` 就像你对哈切特客户一样.

## 供应商

提供商是一个沙盒供应商 与你的哈切特租户相连 曾经配置在仪表板下 `Sandboxes` 带有供应商的 API 密钥和可选配置值.

目前我们支持下列供应商:

-   [代顿a](https://www.daytona.io/)
-   [E2B 软件](https://e2b.dev/)
-   [阿奇尔](https://archil.com/)
-   [自由风格](https://freestyle.sh/)。 。 。 .

```ts
const sandbox = await hatchet.sandbox.create({ provider: 'e2b' });
```

## API 密码

### `hatchet.sandbox`

| 打电话 | 回返 | 它会做什么 |
| --- | --- | --- |
| `create(opts?)` | `Sandbox` | 开一沙盒. |
| `connect(id, { template? })` | `Sandbox` | 从最新的快照中取出一个沙盒. 停止后再开始 如果ID不存在则丢出. |
| `list({ sandboxId?, metadata? })` | `SandboxInfo[]` | 通过ID或元数据查找沙盒. 所有给定的配对必须匹配. |
| `delete({ sandboxId?, metadata? })` | `string[]` | 删除每个匹配的沙盒及其所有快照和文件,并返回其ID。 需要一个过滤器. |

备选方案 `create`数字 :

| 选项 | 它会做什么 |
| --- | --- |
| `provider` | 哪个沙盒供应商可以创建, 名称。 当房客有几分钱的时候需要,叉子总是用它的快照. |
| `id` | 自己选个沙盒身份证 小写字母 数字和连字符 它决不能存在. |
| `template` | 图像或模板,以提供者自己的说法. 默认提供者的默认 . |
| `from` | 从这个快照开始 从同一个快照创建出两个沙盒,你有一个叉子. |
| `metadata` | 您可以搜索的标记 `list`。 。 。 . |
| `inheritParentMetadata` | 与 `from`,复制沙盒的标签 使快照在新的。 给定的标记 `metadata` 优先发言. |
| `idleTimeoutMs` | 这么长时间没打电话就把沙盒停了 供养者设出最上. |
| `resources` | 机器大小为 `{ vcpu, memory, disk }`。 。 。 . `memory` 财务报告和审定财务报表 `disk` 取若干个MIB或数量,单位如下: `'4Gi'`。无法遵守字段的提供者会用自己的信息使创建失败. |

### `Sandbox`

| 打电话 | 回返 | 它会做什么 |
| --- | --- | --- |
| `exec(cmd, { timeoutMs? })` | `{ stdout, stderr, exitCode, snapshotId?, timings? }` | 运行 `sh -c cmd` 在工作区拍个快照 非零退出代码是正常结果,而不是出错. 超时时出站码为124. |
| `kill()` | `void` | 止取沙盒来. 镜头留下,所以 `connect` 还行. |
| `delete()` | `void` | 停止沙盒并删除每个快照和文件. `connect` 之后失败 . |
| `sandboxId` | `string` | 要使用的标识 `connect` 等会. |
| `files` | `Files` | 下面的文件 API . |

每一个结果都有 `timings` 以毫秒计 `claim`, (中文(简体) ), `restore`, (中文(简体) ), `exec`,以及 `checkpoint`,则 `snapshotId` 电话打来的.

### `sandbox.files`

路径与工作空间相对. 指向外面的路径 扔出一个 `FilesystemError` 有代码 `invalid_path`。 。 。 .

| 打电话 | 它会做什么 |
| --- | --- |
| `read(path, { format? })` | 读取文件. `format` 实值 `'text'` (违约), `'bytes'` (单位:千美元) `Uint8Array`,或 `'blob'`。 。 。 . |
| `write(path, data)` 或者说 `write([{ path, data }, ...])` | 写一个或多个文件. `data` 可以是弦, `ArrayBuffer`, (中文(简体) ), `Uint8Array`,或 `Blob`。 。 。 . |
| `list(path?, { depth? })` | 列出有名称、路径、类型、大小、模式、权限和修改时间的条目. |
| `exists(path)`, (中文(简体) ), `getInfo(path)` | 检查路径或获得信息. |
| `makeDir(path)`, (中文(简体) ), `rename(from, to)`, (中文(简体) ), `copy(from, to)`, (中文(简体) ), `remove(path)` | 通常的文件操作. |
| `download(url, path, { timeoutMs? })` | 提供者将 https URL 获取到工作空间 。 私人地址和回路地址被拒绝. |
| `upload(path, url, { timeoutMs? })` | 提供者用 HTTP PUT 向 https URL 发送文件. 指定 URL 运行良好 . |

`read` 财务报告和审定财务报表 `write` 通过Hatchet携带最多2个米B. 提供商拥有一个对象存储台上更大的文件,并且从未通过Hatchet传送过它们;无论用哪种方式,都使用同样的方法.

## 错误

-   `FilesystemError` 有一个 `code`其中: `not_found`, (中文(简体) ), `invalid_path`, (中文(简体) ), `invalid_url`, (中文(简体) ), `invalid_content`, (中文(简体) ), `invalid`, (中文(简体) ), `is_a_directory`, (中文(简体) ), `not_a_directory`, (中文(简体) ), `too_large`, (中文(简体) ), `staging_failed`, (中文(简体) ), `transfer_failed`。 。 。 .
-   失败的命令不会丢出 。 看着 `exitCode`。 。 。 .
-   `connect` 身份不明,身份不明. `create` 带有 `id` 已经存在 扔。 使用 `connect` 给那个 或者选个新的身份证.
-   `hatchet.sandbox.delete` 无 `sandboxId` 或无空 `metadata` 过滤器在触摸任何东西之前抛出. 元数据匹配是一个子集匹配, 和 `list`: 过滤器 `{ a, b }` 匹配贴有标签的沙盒 `{ a, b, c }`。 。 。 .

## 遥测

首先使用SDK打开了Hatchet OpenTeleometry仪器. 如果您已经设置了 OpenTeleometry, 沙盒呼叫会在您的任务跟踪中显示 。 设定 `HATCHET_SANDBOX_OTEL=false` 把它关掉.

## 你需要的东西

-   装有沙盒的Hatchet Cloud租户已启用.
-   至少有一个沙盒供应商与租户连接, 在仪表板的沙盒下配置了您的 Daytona, E2B, Archil, 或 Freestyle API 键.

## 更改日志

见 [变动情况](https://npmcn.com/package/%40hatchet-dev/sandbox/CHANGELOG.md)。 。 。 .

## 许可证

麻省理工学院. 见 [自由主义](https://npmcn.com/package/%40hatchet-dev/sandbox/LICENSE)。 。 。 .

## 常见问题

### @hatchet-dev/sandbox 是什么？

Hatchet 沙盒类型SDK

### 如何安装 @hatchet-dev/sandbox？

在项目目录运行 npm install @hatchet-dev/sandbox，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@hatchet-dev/typescript-sdk（\>=1\.33\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @hatchet-dev/sandbox 支持 TypeScript 吗？

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

### @hatchet-dev/sandbox 支持 ESM 还是 CommonJS？

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

### @hatchet-dev/sandbox 可以商用吗？

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

### @hatchet-dev/sandbox 的下载量有多少？

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

### @hatchet-dev/sandbox 还在维护吗？

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

